bibolamazi.core.bibfilter package

bibolamazi.core.bibfilter.argtypes module

class bibolamazi.core.bibfilter.argtypes.CommaStrList(iterable=[])

Bases: list

A list of values, specified as a comma-separated string.

class bibolamazi.core.bibfilter.argtypes.CommaStrListArgType

class bibolamazi.core.bibfilter.argtypes.EnumArgType(listofvalues)

bibolamazi.core.bibfilter.argtypes.enum_class(class_name, values, default_value=0, value_attr_name='value')

class_name is the class name.

values should be a list of tuples (string_key, numeric_value) of all the expected string names and of their corresponding numeric values.

default_value should be the value that would be taken by default, e.g. by using the default constructor.

value_attr_name the name of the attribute in the class that should store the value. For example, the arxiv module defines the enum class Mode this way with the attribute mode, so that the numerical mode can be obtained with enumobject.mode.

bibolamazi.core.bibfilter.factory module

class bibolamazi.core.bibfilter.factory.DefaultFilterOptions(filtername, fclass=None)

filterDeclOptions()

This gives a list of _ArgDoc named tuples.

filterOptions()

This gives a list of _ArgDoc named tuples.

filterVarOptions()

This gives a list of _ArgDoc named tuples.

filtername()

format_filter_help()

getArgNameFromSOpt(x)

getSOptNameFromArg(x)

optionSpec(argname)

parse_optionstring(optionstring)

Parse the given option string (one raw string, which may contain quotes, escapes etc.) into arguments which can be directly provided to the filter constructor.

parse_optionstring_to_optspec(optionstring)

Parses the optionstring, and returns a description of which options where specified, which which values.

This doesn’t go as far as parse_optionstring(), which returns pretty much exactly how to call the filter constructor. This function is meant for example for the GUI, who needs to parse what the user specified, and not necessarily how to construct the filter itself.

Return a dictionary:

{
  "_args": <additional *pargs positional arguments>
  "kwargs": <keyword arguments>
}

The value of _args is either None, or a list of additional positional arguments if the filter accepts *args (and hence the option parser too). These will only be passed to *args and NOT be distributed to the declared arguments of the filter constructor.

The value of kwargs is a dictionary of all options specified by keywords, either with the --keyword=value syntax or with the syntax -sKey=Value. The corresponding value is converted to the type the filter expects, in each case whenever possible (i.e. documented by the filter).

parser()

use_auto_case()

class bibolamazi.core.bibfilter.factory.FilterArgumentParser(filtername, **kwargs)

Bases: argparse.ArgumentParser

error(message)

exit(status=0, message=None)

exception bibolamazi.core.bibfilter.factory.FilterCreateArgumentError(errorstr, name=None)

Bases: bibolamazi.core.bibfilter.factory.FilterError

Although the filter arguments may have been successfully parsed, they may still not translate to a valid python filter call (i.e. in terms of function arguments, for example when using both positional and keyword arguments). This error is raised when the composed filter call is not valid.

fmt(name)

exception bibolamazi.core.bibfilter.factory.FilterCreateError(errorstr, name=None)

Bases: bibolamazi.core.bibfilter.factory.FilterError

There was an error instantiating the filter. This could be due because the filter constructor raised an exception.

fmt(name)

exception bibolamazi.core.bibfilter.factory.FilterError(errorstr, name=None)

Bases: exceptions.Exception

Signifies that there was some error in creating or instanciating the filter, or that the filter has a problem. (It could be, for example, that a function defined by the filter does not behave as expected. Or, that the option string passed to the filter could not be parsed.)

This is meant to signify a problem occuring in this factory, and not in the filter. The filter classes themselves should raise bibfilter.BibFilterError in the event of an error inside the filter.

fmt(name)

setName(name)

exception bibolamazi.core.bibfilter.factory.FilterOptionsParseError(errorstr, name=None)

Bases: bibolamazi.core.bibfilter.factory.FilterError

Raised when there was an error parsing the option string provided by the user.

fmt(name)

exception bibolamazi.core.bibfilter.factory.FilterOptionsParseErrorHintSInstead(errorstr, name=None)

Bases: bibolamazi.core.bibfilter.factory.FilterOptionsParseError

As FilterOptionsParseError, but hinting that maybe -sOption=Value was meant instead of -dOption=Value.

fmt(name)

exception bibolamazi.core.bibfilter.factory.NoSuchFilter(fname, errorstr=None)

Bases: exceptions.Exception

Signifies that the requested filter was not found. See also get_module().

exception bibolamazi.core.bibfilter.factory.NoSuchFilterPackage(fpname, errorstr='No such filter package', fpdir=None)

Bases: exceptions.Exception

Signifies that the requested filter package was not found. See also get_module().

class bibolamazi.core.bibfilter.factory.PrependOrderedDict(*args, **kwargs)

Bases: collections.OrderedDict

An ordered dict that stores the items in the order where the first item is the one that was added/modified last.

item_at(idx)

set_at(idx, key, value)

set_items(items)

bibolamazi.core.bibfilter.factory.detect_filter_package_listings()

bibolamazi.core.bibfilter.factory.detect_filters(force_redetect=False)

bibolamazi.core.bibfilter.factory.filter_arg_parser(name)

If the filter name uses the default-based argument parser, then returns a DefaultFilterOptions object that is initialized with the options available for the given filter name.

If the filter has its own option parsing mechanism, this returns None.

bibolamazi.core.bibfilter.factory.filter_uses_default_arg_parser(name)

bibolamazi.core.bibfilter.factory.format_filter_help(filtname)

bibolamazi.core.bibfilter.factory.get_filter_class(name, filterpackage=None)

bibolamazi.core.bibfilter.factory.get_module(name, raise_nosuchfilter=True, filterpackage=None)

bibolamazi.core.bibfilter.factory.load_precompiled_filters(filterpackage, precompiled_modules)

filterpackage: name of the filter package under which to scope the given precompiled

filter modules.

precompiled_modules: a dictionary of ‘filter_name’: filter_module of precompiled

filter modules, along with their name.

bibolamazi.core.bibfilter.factory.make_filter(name, optionstring)

bibolamazi.core.bibfilter.factory.reset_filters_cache()

bibolamazi.core.bibfilter.factory.validate_filter_package(fpname, fpdir, raise_exception=True)

Module contents

class bibolamazi.core.bibfilter.BibFilter(*pargs, **kwargs)

Bases: object

Base class for a bibolamazi filter.

To write new filters, you should subclass BibFilter and reimplement the relevant methods. See documentation of the different methods below to understand which to reimplement.

Constructor. No particular arguments are expected; any received are passed further to superclasses.

BIB_FILTER_BIBOLAMAZIFILE = 3

A constant that indicates that the filter should act upon the whole bibliography at once. See documentation for the action() method for more details.

BIB_FILTER_SINGLE_ENTRY = 1

A constant that indicates that the filter should act upon individual entries only. See documentation for the action() method for more details.

action()

Return one of BIB_FILTER_SINGLE_ENTRY or BIB_FILTER_BIBOLAMAZIFILE, which tells how this filter should function. Depending on the return value of this function, either filter_bibentry() or filter_bibolamazifile() will be called.

If the filter wishes to act on individual entries (like the built-in arxiv or url filters), then the subclass should return BibFilter.BIB_FILTER_SINGLE_ENTRY. At the time of filtering the data, the function filter_bibentry() will be called repeatedly for each entry of the database.

If the filter wishes to act on the full database at once (like the built-in duplicates filter), then the subclass should return BIB_FILTER_BIBOLAMAZIFILE. At the time of filtering the data, the function filter_bibolamazifile() will be called once with the full BibolamaziFile object as parameter. Note this is the only way to add or remove entries to or from the database, or to change their order.

Note that when the filter is instantiated by a BibolamaziFile (as is most of the time in practice), then the function bibolamaziFile() will always return a valid object, independently of the filter’s way of acting.

bibolamaziFile()

Get the BibolamaziFile object that we are acting on. (The one previously set by setBibolamaziFile().)

There’s no use overriding this.

cacheAccessor(klass)

A shorthand for calling the cacheAccessor() method of the bibolamazi file returned by bibolamaziFile().

filter_bibentry(x)

The main filter function for filters that filter the data entry by entry.

If the subclass’ action() function returns BibFilter.BIB_FILTER_SINGLE_ENTRY, then the subclass must reimplement this function. Otherwise, this function is never called.

The object x is a pybtex.database.Entry object instance, which should be updated according to the filter’s action and purpose.

The return value of this function is ignored. Subclasses should report warnings and logging through Python’s logging mechanism (see doc of core.blogger) and should raise errors as BibFilterError (preferrably, a subclass). Other raised exceptions will be interpreted as internal errors and will open a debugger.

filter_bibolamazifile(x)

The main filter function for filters that filter the data entry by entry.

If the subclass’ action() function returns BibFilter.BIB_FILTER_SINGLE_ENTRY, then the subclass must reimplement this function. Otherwise, this function is never called.

The object x is a BibolamaziFile object instance, which should be updated according to the filter’s action and purpose.

The return value of this function is ignored. Subclasses should report warnings and logging through Python’s logging mechanism (see doc of core.blogger) and should raise errors as BibFilterError (preferrably, a subclass). Other raised exceptions will be interpreted as internal errors and will open a debugger.

classmethod getHelpAuthor()

Convenience function that returns helpauthor, with whitespace stripped. Use this when getting the contents of the helpauthor text.

There’s no need to (translate: you should not) reimplement this function in your subclass.

classmethod getHelpDescription()

Convenience function that returns helpdescription, with whitespace stripped. Use this when getting the contents of the helpdescription text.

There’s no need to (translate: you should not) reimplement this function in your subclass.

classmethod getHelpText()

Convenience function that returns helptext, with whitespace stripped. Use this when getting the contents of the helptext text.

There’s no need to (translate: you should not) reimplement this function in your subclass.

getRunningMessage()

Return a nice message to display when invoking the fitler. The default implementation returns name(). Define this to whatever you want in your subclass to describe what you’re doing. The core bibolamazi program displays this information to the user as it runs the filter.

helpauthor = ''

Your subclass should provide a helpauthor attribute, containing a one-line notice with the name of the author that wrote the filter code. You may also add a copyright notice. The exact format is not specified. This text is typically displayed at the top of the page generated by bibolamazi --help <filter>.

You should also avoid accessing this class attribute, you should use getHelpAuthor() instead, which will ensure that whitespace is properly stripped.

helpdescription = 'Some filter that filters some entries'

Your subclass should provide a helpdescription attribute, containing a one-line description of what your filter does. This is typically displayed when invoking bibolamazi --list-filters, along with the filter name.

You should also avoid accessing this class attribute, you should use getHelpDescription() instead, which will ensure that whitespace is properly stripped.

helptext = ''

Your subclass should provide a helptext attribute, containing a possibly long, as detailed as possible description of how to use your filter. You don’t need to provide the basic ‘usage’ and option list, which are automatically generated; but you should include all the text that would appear after the option list. This is typically displayed when invoking bibolamazi --help <filter>.

You should also avoid accessing this class attribute, you should use getHelpText() instead, which will ensure that whitespace is properly stripped.

name()

Returns the name of the filter as it was invoked in the bibolamazifile. This might be with, or without, the filterpackage. This information should be only used for reporting purposes and might slightly vary.

If the filter was instantiated manually, and setInvokationName() was not called, then this function returns the class name.

The subclass should not reimplement this function unless it really really really really feels it needs to.

prerun(bibolamazifile)

This function gets called immediately before the filter is run, after any preceeding filters have been executed.

It is not very useful if the action() is BibFilter.BIB_FILTER_BIBOLAMAZIFILE, but it can prove useful for filters with action BibFilter.BIB_FILTER_SINGLE_ENTRY, if any sort of pre-processing task should be done just before the actual filtering of the data.

The default implementation does nothing.

requested_cache_accessors()

This function should return a list of bibusercache.BibUserCacheAccessor class names of cache objects it would like to use. The relevant caches are then collected from the various filters and automatically instantiated and initialized.

The default implementation of this function returns an empty list. Subclasses should override if they want to access the bibolamazi cache.

setBibolamaziFile(bibolamazifile)

Remembers bibolamazifile as the BibolamaziFile object that we will be acting on.

There’s no use overriding this. When writing filters, there’s also no need calling this explicitly, it’s done in BibolamaziFile.

setInvokationName(filtername)

Called internally by bibolamazifile, so that name() returns the name by which this filter was invoked.

This function sets exactly what name() will return. Subclasses should not reimplement, the default implementation should suffice.

exception bibolamazi.core.bibfilter.BibFilterError(filtername, message)

Bases: bibolamazi.core.butils.BibolamaziError

Exception a filter should raise if it encounters an error.