Python API: Core Bibolamazi Module

core Package

Core bibolamazi module.

See core.bibfilter, core.bibolamazifile, core.bibusercache for the main core modules.

Subpackages

• bibfilter Package
  • bibfilter Package
  • argtypes Module
  • factory Module
• bibusercache Package
  • bibusercache Package
  • tokencheckers Module
• pylatexenc Package
  • pylatexenc Module
  • latex2text Module
  • latexencode Module
  • latexwalker Module

argparseactions Module

This module defines callbacks and actions for parsing the command-line arguments for bibolamazi. You’re most probably not interested in this API. (Not mentioning that it might change if I feel the need for it.)

core.argparseactions.help_list_filters()

core.argparseactions.helptext_prolog()

class core.argparseactions.opt_action_help(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

Bases: argparse.Action

class core.argparseactions.opt_action_version(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

Bases: argparse.Action

class core.argparseactions.opt_init_empty_template(nargs=1, **kwargs)

Bases: argparse.Action

class core.argparseactions.opt_list_filters(nargs=0, **kwargs)

Bases: argparse.Action

core.argparseactions.run_pager(text)

Call pydoc.pager() in a unicode-safe way.

class core.argparseactions.store_key_bool(option_strings, dest, nargs=1, const=True, exception=<type 'exceptions.ValueError'>, **kwargs)

Bases: argparse.Action

class core.argparseactions.store_key_const(option_strings, dest, nargs=1, const=True, **kwargs)

Bases: argparse.Action

class core.argparseactions.store_key_val(option_strings, dest, nargs=1, exception=<type 'exceptions.ValueError'>, **kwargs)

Bases: argparse.Action

class core.argparseactions.store_or_count(option_strings, dest, nargs='?', **kwargs)

Bases: argparse.Action

bibolamazifile Module

The Main bibolamazifile module: this contains the BibolamaziFile class definition.

class core.bibolamazifile.BibolamaziFile(fname=None, create=False, load_to_state=3, use_cache=True, default_cache_invalidation_time=None)

Bases: object

Represents a Bibolamazi file.

This class provides an API to read and parse bibolamazi files, as well as load data defined in its configuration section and interact with its filters.

Filter instances are automatically created upon loading, etc.

.......... TODO: MORE DOC ............

.......... TODO: DOCUMENT MEMBERS ...........

bibliographyData()

bibliographydata()

cacheAccessor(klass)

Returns the cache accessor instance corresponding to the given class.

cacheFileName()

The file name where the cache will be stored. You don’t need to access this directly, the cache will be loaded and saved automatically. You should normally only access the cache through cache accessors. See cacheAccessor().

configData()

configLineNo(filelineno)

Returns the line number in the config data corresponding to line filelineno in the file. Opposite of fileLineNo().

fdir()

fileLineNo(configlineno)

Returns the line number in the file of the config line configlineno. The latter refers to the line number INSIDE the config section, where line number 1 is right after the begin config tag CONFIG_BEGIN_TAG.

filters()

fname()

getLoadState()

load(fname=[], to_state=3)

Loads the given file.

If fname is None, then resets the object to an empty state. If fname is not given or an empty list, then uses any previously loaded fname and its state.

If to_state is given, will only attempt to load the file up to that state. This can be useful, e.g., in a config editor which needs to parse the sections of the file but does not need to worry about syntax errors. The state should be one of BIBOLAMAZIFILE_INIT, BIBOLAMAZIFILE_READ, BIBOLAMAZIFILE_PARSED or BIBOLAMAZIFILE_LOADED.

rawConfig()

rawHeader()

rawStartConfigDataLineNo()

Returns the line number on which the begin config tag CONFIG_BEGIN_TAG is located. Line numbers start at 1 at the top of the file like in any reasonable editor.

rawcmds()

rawrest()

reset()

resolveSourcePath(path)

Resolves a path (for example corresponding to a source file) to an absolute file location.

This function expands ‘~/foo/bar’ to e.g. ‘/home/someone/foo/bar’, it expands shell variables, e.g. ‘$HOME/foo/bar’ or ‘${MYBIBDIR}/foo/bar.bib’.

If the path is relative, it is made absolute by interpreting it as relative to the location of this bibolamazi file (see fdir()).

Note: path should not be an URL.

saveToFile()

setBibliographyData(bibliographydata)

Set the bibliographydata database object directly.

The object bibliographydata should be of instance pybtex.database.BibliographyData.

Warning

Filters should NOT set a different bibliographydata object: caches might have kept a pointer to this object (see, for example EntryFieldsTokenChecker). Please use setEntries() instead.

setConfigData(configdata)

setDefaultCacheInvalidationTime(time_delta)

A timedelta object giving the amount of time for which data in cache is consdered valid (by default).

Note that this function should be called BEFORE the data is loaded. If you just call, for example the default constructor, this might be too late already. If you use the load() function, set the default cache invalidation time before you load up to the state BIBOLAMAZIFILE_LOADED.

Note that you may also use the option in the constructor default_cache_invalidation_time, which has the same effect as this funtion called at the appropriate time.

setEntries(bibentries)

Replace all the entries in the current bibliographydata object by the given entries.

Arguments:

• bibentries: the new entries to set. bibentries should be an iterable of (key, entry) (or, more precisely, any valid argument for pybtex.database.BibliographyData.add_entries()).

Warning

This will remove any existing entries in the database.

This function alters the current bibliographyData() object, and does not replace it by a new object. (I.e., if you kept a reference to the bibliographyData() object, the reference is still valid after calling this function.)

setRawConfig(configblock)

sourceLists()

sources()

class core.bibolamazifile.BibolamaziFileCmd(cmd=None, text='', lineno=-1, linenoend=-1, info={})

exception core.bibolamazifile.BibolamaziFileParseError(msg, fname=None, lineno=None)

Bases: core.butils.BibolamaziError

exception core.bibolamazifile.NotBibolamaziFileError(msg, fname=None, lineno=None)

Bases: core.bibolamazifile.BibolamaziFileParseError

This error is raised to signify that the file specified is not a bibolamazi file—most probably, it does not contain a valid configuration section.

blogger Module

Set up a logging framework for logging debug, information, warning and error messages.

Modules should get their logger using Python’s standard logging mechanism:

import logging
logger = logging.getLogger(__name__)

This allows for the user to be rather specific about which type of messages she/he would like to see.

class core.blogger.BibolamaziConsoleFormatter(ttycolors=False, show_pos_info_level=None, **kwargs)

Bases: logging.Formatter

Format log messages for console output. Customized for bibolamazi.

class core.blogger.BibolamaziLogger(name, level=0)

Bases: logging.Logger

A Logger used in Bibolamazi.

This logger class knows about an additional log level, LONGDEBUG.

longdebug(msg, *args, **kwargs)

Produce a log message at level LONGDEBUG.

class core.blogger.ConditionalFormatter(defaultfmt=None, datefmt=None, **kwargs)

Bases: logging.Formatter

A formatter class.

Very much like logging.Formatter, except that different formats can be specified for different log levels.

Specify the different formats to the constructor with keyword arguments. E.g.:

ConditionalFormatter('%(message)s',
                     DEBUG='DEBUG: %(message)s',
                     INFO='just some info... %(message)s')

This will use ‘%(message)s’ as format for all messages except with level other thand DEBUG or INFO, for which their respective formats are used.

core.blogger.logger = <core.blogger.BibolamaziLogger object>

(OBSOLETE) The main logger object. This is a logging.Logger object.

Deprecated since version 2.1: This object is still here to keep old code functioning. New code should use the following idiom somewhere at the top of their module:

import logging
logger = logging.getLogger(__name__)

(Just make sure the logging mechanism has been set up correctly already, see doc for blogger module.)

This object has an additional method longdebug() (which behaves similarly to debug()), for logging long debug output such as dumping the database during intermediate steps, etc. This corresponds to bibolamazi command-line verbosity level 3.

core.blogger.setup_simple_console_logging(logger=<logging.RootLogger object>)

Sets up the given logger object for simple console output.

The main program module may for example invoke this function on the root logger to provide a basic logging mechanism.

butils Module

Various utilities for use within all of the Bibolamazi Project.

exception core.butils.BibolamaziError(msg, where=None)

Bases: exceptions.Exception

Root bibolamazi error exception.

See also BibFilterError and BibUserCacheError.

core.butils.call_with_args(fn, *args, **kwargs)

Utility to call a function fn with *args and **kwargs.

fn(*args) must be an acceptable function call; beyond that, additional keyword arguments which the function accepts will be provided from **kwargs.

This function is meant to be essentially fn(*args, **kwargs), but without raising an error if there are arguments in kwargs which the function doesn’t accept (in which case, those arguments are ignored).

core.butils.get_version()

Return the version string version_str, unchanged.

core.butils.get_version_split()

Return a 4-tuple (maj, min, rel, suffix) resulting from parsing the version obtained via version.version_str.

............ TODO: FIXME: CURRENTLY, the elements are strings! why not integers? If not there, they will/should be empty or None?

core.butils.getbool(x)

Utility to parse a string representing a boolean value.

If x is already of integer or boolean type (actually, anything castable to an integer), then the corresponding boolean convertion is returned. If it is a string-like type, then it is matched against something that looks like ‘t(rue)?’, ‘1’, ‘y(es)?’ or ‘on’ (ignoring case), or against something that looks like ‘f(alse)?’, ‘0’, ‘n(o)?’ or ‘off’ (also ignoring case). Leading or trailing whitespace is ignored. If the string cannot be parsed, a ValueError is raised.

core.butils.guess_encoding_decode(dat, encoding=None)

core.butils.parse_timedelta(in_s)

Note: only positive timedelta accepted.

core.butils.quotearg(x)

core.butils.resolve_type(typename, in_module=None)

Returns a type object corresponding to the given type name typename, given as a string.

..... TODO: MORE DOC .........

core.butils.warn_deprecated(classname, oldname, newname, modulename=None, explanation=None)

main Module

This module contains the code that implements Bibolamazi’s command-line interface.

class core.main.AddFilterPackageAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

Bases: argparse.Action

class core.main.ArgsStruct(bibolamazifile, verbosity, use_cache, cache_timeout, fine_log_levels)

Bases: tuple

bibolamazifile

Alias for field number 0

cache_timeout

Alias for field number 3

fine_log_levels

Alias for field number 4

use_cache

Alias for field number 2

verbosity

Alias for field number 1

exception core.main.BibolamaziNoSourceEntriesError

Bases: core.butils.BibolamaziError

core.main.get_args_parser()

core.main.main(argv=['-T', '-b', 'readthedocsdirhtml', '-D', 'language=en', '.', '_build/html'])

core.main.run_bibolamazi(bibolamazifile, **kwargs)

core.main.run_bibolamazi_args(args)

core.main.setup_filterpackage_from_argstr(argstr)

Add a filter package definition and path to filterfactory.filterpath from a string that is a e.g. a command-line argument to –filterpath or a part of the environment variable BIBOLAMAZI_FILTER_PATH.

core.main.setup_filterpackages_from_env()

core.main.verbosity_logger_level(verbosity)

Simple mapping of ‘verbosity level’ (used, for example for command line options) to correspondig logging level (logging.DEBUG, logging.ERROR, etc.).

version Module

core.version.version_str = '2.3'

The version string. This is increased upon each release.