garfield Package

The garfield package is sort of a catch-all collection for all the core and generic functionality you need, but which are not included in other libraries.

class garfield.__init__.AbstractUserHostPasswordPrompt(username=None, host=None, use_keyring=True, appname=None)

Bases: object

clear_password()
is_password_stored()
password_is_correct()
request_password()
show_password_prompt()

Displays a password prompt to the user and returns the entered password. Return None in case the user aborted the password entry.

username
garfield.__init__.DIFFICULT_ASCII_LETTERS = 'lI10OoB8'

List of ASCII characters that are difficult to tell apart, especially when used without context (like in passwords and keys).

class garfield.__init__.EntryPointLoader(entry_point_name)

Bases: object

This class provides a load() generator that iterates over all entry points registered under the entry_point_name that this instance was initialised with.

load()
class garfield.__init__.MultipleEntryPointLoaders(*loaders)

Bases: object

This class allows entry points from several entry point loaders to be loaded.

load()
class garfield.__init__.TextUserHostPasswordPrompt(username=None, host=None, use_keyring=True, appname=None)

Bases: garfield.__init__.AbstractUserHostPasswordPrompt

show_password_prompt()
class garfield.__init__.WrapLoadedEntryPoints(loader, wrapper)

Bases: object

This class wraps entry point elements, typically returned by EntryPointLoader.load() with the specified wrapper before passing them on.

load()
garfield.__init__.decimal_float_equal(double_val, decimal_val, places=2)
garfield.__init__.float_to_decimal(double_val, places=2)
garfield.__init__.generate_random_key(key_len=12, valid_chars='abcdefghijklmnopqrstuvwxyz0123456789', invalid_chars='')

Returns a random string of length key_len with characters chosen from valid_chars. (Any characters mentioned in invalid_chars are filtered out of valid_chars.

garfield.__init__.group_string(in_str, group_len=3, group_delimiter='-')

Returns in_str with inserted group_delimiter every group_len characters.

garfield.__init__.monetary_to_str(val, places=2, grouping=True, currency_symbol=u'\u20ac')

Same functionality as locale.currency(), but allows the number of places and the currency symbol to be specified.

Needs proper locale to be active and does not work correctly with C locale.

garfield.__init__.print_files(files, printer=None, num_copies=1, title=None, options=None, priority=None)
garfield.__init__.send_mail(message)
garfield.__init__.str_to_dict(s, d=None)

Parse a string s of the form key=value, otherkey=othervalue, ... into a dictionary. If d is an existing dictionary, the parsed items are inserted into d. Returns the resulting dictionary. Note that surrounding whitespaces are lost and the special characters , and = cannot occur as payload.

garfield.accounting Module

garfield.accounting.create_subtotals(sess, location, environment_sess, details_config, mon=<garfield.progress.NullProgressMonitor object>)

garfield.basic Module

class garfield.basic.BankAccount

Bases: object

@DynamicAttrs

class garfield.basic.BankAccountLog

Bases: object

@DynamicAttrs

class garfield.basic.CBFAny

Bases: object

apply(query)
description = u'Alles'
prio = 90
class garfield.basic.CBFDepositWithdrawal

Bases: object

apply(query)
description = u'Snackkontoeinzahlungen / -auszahlungen'
prio = 80
class garfield.basic.CashBox

Bases: object

@DynamicAttrs

create_subtotal(subtotal)
class garfield.basic.CashBoxLog

Bases: garfield.basic.DescriptionProvidersMixin

@DynamicAttrs

description

Returns the details of the cash box log transaction.

class garfield.basic.CashBoxLogCancel

Bases: object

@DynamicAttrs

class garfield.basic.CashBoxUserLog

Bases: object

@DynamicAttrs

class garfield.basic.Configuration

Bases: object

@DynamicAttrs

static get_value(sess, key)
class garfield.basic.ConfigurationType

Bases: object

@DynamicAttrs

convert_value(value)
class garfield.basic.DescriptionProvidersMixin

Bases: object

class garfield.basic.Location

Bases: object

@DynamicAttrs

classmethod get_by_name(sess, location_name)

Convenience method to retrieve the location matching a location name.

class garfield.basic.MiscChangeUserLog

Bases: object

@DynamicAttrs

static add_income(sess, account, amount, description)
static add_spending(sess, account, amount, description)
exception garfield.basic.NoTypeConversionKnown

Bases: exceptions.Exception

class garfield.basic.RangeOfNumbers

Bases: object

@DynamicAttrs

class garfield.basic.SnackAccountBalance

Bases: object

@DynamicAttrs

class garfield.basic.Subtotal

Bases: object

@DynamicAttrs

static create(sess, location)
class garfield.basic.Tax

Bases: object

@DynamicAttrs

static get_all_dict(sess)
class garfield.basic.TaxGroup

Bases: object

@DynamicAttrs

static create(sess, description)
create_mapping(tax, start_date, end_date)
current_percentage

Useful for visualisation of the tax group’s current tax percentage. Should not be used for actual calculations. Returns the tax percentage for the tax that is mapped for this tax group for the time of the request.

delete()
find_tax(searched_date=datetime.date(2017, 7, 25))

Returns the Tax that is mapped for this tax group for the specified searched_date, or today if searched_date is None.

mappings_no_overlap_with(start_date, end_date)
class garfield.basic.TaxMapping

Bases: object

@DynamicAttrs

static create(sess, tax_group, tax, start_date, end_date)
class garfield.basic.Type

Bases: garfield.database.TypeDescriptionPluginMixin

@DynamicAttrs

type_name

Returns the description for the current instance of the base class. Overrides TypeDescriptionMixin._get_type_description() and lazy loads the descriptions first.

class garfield.basic.User

Bases: object

@DynamicAttrs | user_id | user_name | user_full_name

close()
close_account()
static create(sess, user_name, user_full_name=None, opening_value=Decimal('0'))
deposit(cash_box, amount)
classmethod get_all_usernames(sess)
classmethod get_by_name(sess, user_name)

Convenience method to retrieve the user matching a certain user name.

has_account
open_account(opening_value)
transaction_list
transfer_to(target, amount, description=None)
user_display_name

Returns the user name in a form that is best suited for human consumption, i.e. preferrably the full name. If the full name isn’t set, then the user name is returned.

static user_display_name_sql()

Returns the SQL expression which is equivalent to the value programmatically generated by user_display_name().

withdraw(cash_box, amount)
class garfield.basic.UserToUserTransLog

Bases: object

@DynamicAttrs

class garfield.basic.UserTransaction

Bases: garfield.basic.DescriptionProvidersMixin

@DynamicAttrs

description

Returns the detail of the transaction.

Possibly contains details provided by plugins based on other tables.

static lock_exclusive_mode(sess)
class garfield.basic.UserTransactionCancel

Bases: object

@DynamicAttrs

garfield.basic.add_basic_cash_box_filters(cb_filters, **_)
garfield.basic.create_user_trans_log_basic_subtotals(sess, subtotal)

Creates subtotals of all user accounts that are currently open or were open earlier and haven’t been subtotaled yet.

garfield.basic.enhance_cash_box_log_description(cash_box_log_row)

Returns an enhanced description for the cash box log row or None in case no donation type is involved.

garfield.basic.enhance_user_trans_log_description(user_trans)

Returns an enhanced description for the user transaction or None in case no basic type is involved.

garfield.basic.setup_tables(sess, meta)

garfield.configparser Module

Provides a config parser with programmable defaults.

class garfield.configparser.DefaultConfigParserMixin

Bases: object

The DefaultConfigParserMixin class is intended as a thin wrapper around SafeConfigParser. It provides a new variant for each of the get methods, where a default value can be specified in case the option does not exist.

getbooleandef(section, option, default=None, **kwargs)
getdef(section, option, default=None, **kwargs)
getintdef(section, option, default=None, **kwargs)
class garfield.configparser.DictConfigParserMixin

Bases: object

The DictConfigParserMixin class adds support for configuration options that list multiple key-value pairs.

getdict(section, option, default=None)

Parse the option from section as key-values pairs of the form key=value, otherkey=othervalue, .... In case the option doesn’t exist, default is returned.

class garfield.configparser.InclusionConfigParserMixin

Bases: object

InclusionConfigParserMixin is intended as a wrapper around one of the ConfigParser classes. It replaces :meth:read with a variant that additionally recursively loads all configuration files specified in the [include] section of the configuration file. Example of such a section:

[include] somename = /etc/another_file.conf another_name = /etc/yet_another_file.conf

The file inclusion is ordered in case the underlying dictionary type supports ordering. So, assuming a dictionary with ordering support, for the above example, first /etc/another_file.conf and then /etc/yet_another_file.conf would be included.

Note: Does not protect against include cycles.

INCLUDE_BASE_CLASS

alias of SafeConfigParser

INCLUDE_SEC_NAME = 'include'
read(conf_fn, *conf_fns)
class garfield.configparser.InclusionDefaultConfigParser(defaults=None, dict_type=<class 'garfield.ordereddict.OrderedDict'>)

Bases: garfield.configparser.InclusionConfigParserMixin, garfield.configparser.DefaultConfigParserMixin, garfield.configparser.DictConfigParserMixin, ConfigParser.SafeConfigParser

Provides a config parser class that overlays ConfigParser.SafeConfigParser with the additional features provided by InclusionConfigParserMixin, DefaultConfigParserMixin and DictConfigParserMixin.

garfield.configparser.copy_conf_to_conf(src_conf, dst_conf)

Copies all sections and all entries from the config object src_conf to the config object dst_conf.

garfield.country Module

This modules provides a wrapper around the :mod:pycountry module and provides country lists and country naming information with localised strings.

class garfield.country.LocalisedCountries

Bases: object

Allows retrieval and querying of countries from ISO 3166-1 with localised strings.

find_partial(name=None, alpha2=None)

Find a partial match for country name or country with alpha2-code in the database. Returns the set of matches.

get_country(alpha2)

Loads and returns a specific country from the database, based on the alpha2 code. Does not depend on :meth:load_all_countries for pre-loading.

load_all_countries()

Eager-loads all countries from the database.

class garfield.country.LocalisedCountryProxy(country, translation)

Bases: object

Wraps around a :class:pycountry.Country object and provides the same names as localised strings.

garfield.cups Module

exception garfield.cups.PageLogParseError

Bases: exceptions.Exception

Gets raised in case the page log is formatted in an unexpected way.

garfield.cups.parse_page_log(fn)
garfield.cups.parse_page_log_stream(fp)

Parse the page log stream fp and return one dict per print log entry.

garfield.filescleaner Module

The filescleaner module provides the class FilesCleaner.

class garfield.filescleaner.FilesCleaner

Bases: object

Simple helper to keep track of a bunch of files and clean easily delete them all at some point.

add(fn)

Adds fn to the list of files.

clean()

Deletes all files previously added by add(). Ignores files that no longer exist.

garfield.filestorage Module

The filestorage module implements the on-disk storage of files.

class garfield.filestorage.FileStorage(base_directory, module, mode=None, unix_group=None)

Bases: object

Storage layer for files. Uses unique and opaque identifiers to refer to the content stored therein. An item can be added by calling add_object(). A file type is required, which can later be queried by applications accessing the storage. All files stored by this class are compressed using gzip. Hence direct file access through get_object_filename() needs to cope with this fact. Accesses through get_fileobj() are completely transparent.

The caller should check using :property:`writeable` if the storage area is writeable for the current user before trying to add object. Similarly before fetching objects object_accessible() should be called to fail early if the files are unavailable.

The class can ensure proper privileges when saving files. You can pass a file mode that should be set for new files, and a Unix group name that will be common for all stored files.

add_object(f_in, f_type)
get_fileobj(identifier)
get_object_encoding(identifier)
get_object_filename(identifier)
get_object_type(identifier)
object_readable(identifier)
writeable

garfield.filestorage_test Module

class garfield.filestorage_test.TestFileStorage

Bases: object

setUp()
tearDown()
test_add_file_object()
test_writeable()

garfield.io Module

The garfield.io package contains a few I/O related helper classes and functions.

class garfield.io.FileErrorSuppressor(filep)

Bases: object

This class wraps around the file-like object filep and suppresses all exceptions caused by EPIPE and EINVAL errors.

An example where this behaviour might be useful: Logging output to sys.stdout or ``sys.stderr`’ on a best-effort basis, without having to wrap each print statement with a try-catch block.

SUPPRESSED_ERRORS = [32, 22]

List of errors that are suppressed by this class.

garfield.keyring Module

A module that provides a common interface to desktop keyrings, similar to python-keyring but focusing on good support for Gnome Keyring and KDE4’s KWallet. Another key feature is lazy loading of all dependencies, delaying the need for an X11 connection or a password prompt for keyring decryption until absolutely necessary.

class garfield.keyring.DefaultKeyring

Bases: object

Queries a number of default keyrings to determine the one suited best for the current user and situation.

KEYRING_CLASSES = [<class 'garfield.keyring.KWallet'>, <class 'garfield.keyring.GnomeKeyring'>]
get_support_level()
read_password(appname, username, host=None)
write_password(appname, username, password, host=None)
class garfield.keyring.GnomeKeyring

Bases: object

Wraps around the Gnome Keyring interface to provide a common interface.

get_support_level()
read_password(_appname, username, host=None)
write_password(appname, username, password, host=None)
class garfield.keyring.KWallet

Bases: object

Wraps around KDE4’s KWallet interface to provide a common interface.

get_support_level()
read_password(appname, username, host=None)
write_password(appname, username, password, host=None)
exception garfield.keyring.KeyringOpenFailed

Bases: exceptions.Exception

Raised when the keyring cannot not be opened, most likely because the user denied the request.

exception garfield.keyring.MismatchingApplicationNameError

Bases: exceptions.Exception

Raised when the requested application name could not be set.

exception garfield.keyring.PasswordStoreError

Bases: exceptions.Exception

Raised when the password cannot be stored.

exception garfield.keyring.UnsupportedKeyringError

Bases: exceptions.Exception

Raised when the keyring cannot be loaded for some reason.

garfield.network Module

This module contains useful network support classes.

class garfield.network.LineBuffer

Bases: object

Helps parse a buffer into lines.

The buffer receives chunks of data and internally splits the data into complete lines. Lines can then be requested by calling :method:~`get_lines`.

append(new_buf)

Splits new_buf into full lines and stores them.

If new_buf is None, the stream is assumed to have ended, which causes LineBuffer to store the remaining data (which misses a terminating new-line character) as a last line.

get_lines()

Returns all complete lines.

class garfield.network.LineSocket(socket, line_buffer=None)

Bases: object

Wraps around a raw socket and allows for easy line-based communication.

Reads data from a socket and allows full lines to be retrieved by calling :method:~`get_lines`.

close()
fileno()
get_lines()

Returns all complete lines.

getsockopt(level, optname)
process()

Reads any data available for the socket. Should be called as soon as the socket has data available for reading. Might block, depending on whether the socket was configured as blocking or non-blocking.

send_line(data)

garfield.network_test Module

Tests the garfield.network module.

garfield.network_test.test_empty()

.

garfield.network_test.test_no_newline()

.

garfield.network_test.test_partial_lines()

.

garfield.network_test.test_partial_lines_multiple_missing_newlines()

.

garfield.network_test.test_partial_lines_one_step()

.

garfield.network_test.test_single_line()

.

garfield.notification Module

garfield.notification.notify(app_name, title, body, icon='', array=None, hint=None, show_time=-1)

garfield.ordereddict Module

class garfield.ordereddict.OrderedDict(*args, **kwds)

Bases: dict, UserDict.DictMixin

clear()
copy()
classmethod fromkeys(iterable, value=None)
items()
iteritems()
iterkeys()
itervalues()
keys()
pop(key, *args)
popitem(last=True)
setdefault(key, default=None)
update(other=None, **kwargs)
values()

garfield.pdflatex Module

The pdflatex module provides functionality for easily rendering a LaTeX document into a PDF file.

garfield.pdflatex.latex_archive_to_pdf(archive_fn, latex_fn, enhance_latex_func=None)

Renders the LaTeX document latex_fn as a PDF file. The LaTeX document is contained in the tar file archive_fn, which may contain supplementary files (such as graphics).

If the archive extracts into a sub-directory, the latex_fn should provide a relative path to the LaTeX document within that sub-directory.

Optionally, a callable enhance_latex_func can be provided which will be called as soon as the archive is extracted. The callable gets passed-in the latex_dir and the latex_fn. It can modify the LaTeX file and add further files to the directory that will influence the LaTeX build process.

Returns the absolute path of the PDF file. The callee is responsible for cleaning up the file after use.

garfield.pdflatex.latex_auto_to_pdf(latex_fn, enhance_latex_func=None)

Redirects to :meth’latex_archive_to_pdf, latex_dir_to_pdf() or latex_file_to_pdf() depending on latex_fn.

If latex_fn isn’t of the form <archive name>:<tex filename> it is assumed to be a single file and the call is redirected to latex_file_to_pdf. If the ``<archive name>`() is found to be a directory, latex_dir_to_pdf() is called.

garfield.pdflatex.latex_dir_to_pdf(dir_fn, latex_fn, enhance_latex_func=None)

Renders the LaTeX document latex_fn as a PDF file. The LaTeX document is contained in the directory dir_fn, which may contain supplementary files (such as graphics). The directory dir_fn and its contents will be recursively copied to a temporary build directory.

The latex_fn should provide a relative path to the LaTeX document from within dir_fn.

Optionally, a callable enhance_latex_func can be provided which will be called as soon as the archive is extracted. The callable gets passed-in the latex_dir and the latex_fn. It can modify the LaTeX file and add further files to the directory that will influence the LaTeX build process.

Returns the absolute path of the PDF file. The callee is responsible for cleaning up the file after use.

garfield.pdflatex.latex_file_to_pdf(latex_fn, enhance_latex_func=None)

Renders the LaTeX document latex_fn as a PDF file.

Optionally, a callable enhance_latex_func can be provided which will be called as soon as the build directory has been prepared and the LaTeX file was copied there. The callable gets passed-in the latex_dir and the latex_fn. It can modify the LaTeX file and add further files to the directory that will influence the LaTeX build process.

Returns the absolute path of the PDF file. The callee is responsible for cleaning up the file after use.

garfield.pdflatex.replace_latex_functions(input_latex_fn, output_latex_fn, templates)

Replaces LaTeX functions within the LaTeX file input_latex_fn and writes the changed file to output_latex_fn.

Each item in the templates dictionary replaces one LaTeX function - the key is the function name and the value is used as the function’s replacement.

input_latex_fn and output_latex_fn may be identical.

The function does not care whether anything actually gets replaced.

garfield.pdflatex.replace_latex_functions_in_all(latex_fns, templates)

Calls replace_latex_functions() on each of the latex_fns.

garfield.pkgconf Module

Holds configuration data that is setup at build time. (During development, the configuration data contains special values that allow Garfield to work without the build step.)

garfield.progress Module

This package provides progress monitoring classes.

class garfield.progress.AbstractProgressMonitor(work_part, depth=1)

Bases: garfield.progress.IProgressMonitor

DELTA = 1e-05
begin_task(task_name, total_work=100)
done()
is_done()
worked(work=1)
class garfield.progress.IProgressMonitor

Bases: object

Progress monitor interface, loosely modelled after Eclipse’s interface with the same name.

begin_task(_task_name, _total_work)
done()
is_done()
set_sub_task_name(_sub_task_name)
set_task_name(_task_name)
worked(_work=1)
class garfield.progress.NullProgressMonitor

Bases: garfield.progress.IProgressMonitor

Pretend to be a ProgressMonitor, but simply do nothing. Use this class if someone expects to receive a progress monitor but you have none to give them.

begin_task(_task_name, _total_work)
done()
is_done()
set_sub_task_name(_sub_task_name)
set_task_name(_task_name)
worked(_work=1)
class garfield.progress.SetDoneAfterwards(monitor, task_name=None, total_work=None)

Bases: object

Use this class in with statements and pass in the progress monitor monitor. The class will make sure that the monitor is closed by calling IProgressMonitor.done() as soon as the with context is exited.

If task_name and optionally total_work are given, IProgressMonitor.begin_task() is called to immediately start the work.

class garfield.progress.SubProgressMonitor(parent_monitor, work_part)

Bases: garfield.progress.AbstractProgressMonitor

This class takes a parent_monitor and provides the same interface IProgressMonitor but runs all work as a sub-task of the parent monitor. Use this class when passing a monitor to another class or method.

set_sub_task_name(sub_task_name)
set_task_name(task_name)

garfield.script_runtime Module

class garfield.script_runtime.ScriptRuntime(**hooks)

Bases: object

garfield_config

A ConfigParser instance containing the parsed Garfield configuration files, i.e. the system default config, possibly overwritten by user configuration.

garfield_database

The FSMI Garfield database object, connected to the server as specified in the configuration files, i.e. ready for use.

garfield.version Module

Holds version information for Garfield package. Will use information from git during development.

garfield.weakmethod Module

class garfield.weakmethod.WeakBoundMethod(bound_method, ignore_emptiness=False)

Bases: object

Used to create a proxy method of a bound method, which weakly references the method’s binding instance.

Assuming the following simple class:

>>> class Example(object):
...     def print_num(self, a_number):
...         print "%d" % a_number

We can create an example instance and create a weak reference to the bound print_num method:

>>> e = Example()
>>> wmeth = WeakBoundMethod(e.print_num)

The proxy method works as expected:

>>> wmeth(5)
5

It holds no strong reference to e, so deleting e will invalidate the proxy method:

>>> del e
>>> wmeth(5)
Traceback (most recent call last):
    ...
ReferenceError

The exception can be suppressed by setting ignore_emptiness to True:

>>> e = Example()
>>> wmeth = WeakBoundMethod(e.print_num, ignore_emptiness=True)
>>> wmeth(5)
5
>>> del e
>>> wmeth(5)

Subpackages