Bibulous Module

Bibulous is a drop-in replacement for BibTeX, with the primary advantage that the bibliography template format is compact and very easy to modify.

The basic program flow upon object initialization is as follows:

1. Read the .aux file and get the names of the bibliography databases (.bib files), the style templates (.bst files) to use, and the entire set of citations.
2. Read in the Bibulous style template .bst file as a dictionary (bstdict). This also allows us to set options for how to parse the database file(s).
3. Look for the -extract.bib “extracted” database file. If it exists, then read it in. Compare the entrykeys in the the extracted database to the citation keys in the .aux file. If any of the latter are not within the extracted database, then re-extract the database from the main database file. Otherwise, continue with the extracted database.
4. If the extracted database doesn’t exist, or need to be replaced, then read in all of the bibliography database files into one long dictionary (bibdata), replacing any abbreviations with their full form. Cross-referenced data is not yet inserted at this point. That is delayed until the time of writing the BBL file in order to speed up parsing.
5. Now that all the information is collected, go through each citation key, find the corresponding entry key in bibdata. From the entry type, select a template from bstdict and begin inserting the variables one-by-one into the template. If any data is missing, check for cross-references and use crossref data to fill in missing values.

bibulous.sentence_case(s)

Reduce the case of the string to lower case, except for the first character in the string, and except if any given character is at nonzero brace level.

Parameters:

s : str

The string to be modified.

Returns:

t : str

The resulting modified string.

bibulous.stringsplit(s, sep=u' |(?<!\\\\)~')

Split a string into tokens, taking care not to allow the separator to act unless at brace level zero.

Parameters:

s : str

The string to split.

Returns:

tokens : list of str

The list of tokens.

bibulous.namefield_to_namelist(namefield, key=None, sep=u'and', disable=None)

Parse a name field (“author” or “editor”) of a BibTeX entry into a list of dicts, one for each person.

Parameters:

namefield : str

Either the “author” field of a database entry or the “editor” field.

key : str, optional

The bibliography data entry key.

sep : str, optional

The string defining the string to be used as a name separator.

disable : list of int, optional

The list of warning message numbers to ignore.

Returns:

namelist : list

A list of dictionaries, with one dictionary for each name. Each dict has keys “first”, “middle”, “prefix”, “last”, and “suffix”. The “last” key is the only one that is required.

bibulous.namestr_to_namedict(namestr, disable=None)

Take a BibTeX string representing a single person’s name and parse it into its first, middle, last, etc pieces.

BibTeX allows three different styles of author formats.

1. A space-separated list, [firstname middlenames suffix lastname]
2. A two-element comma-separated list, [prefix lastname, firstname middlenames]
3. a three-element comma-separated list, [prefix lastname, suffix, firstname middlenames].

So, we can separate these three categories by counting the number of commas that appear.

Parameters:

namestr : str

The string containing a single person’s name, in BibTeX format

disable : list of int, optional

The list of warning message numbers to ignore.

Returns:

namedict : dict

A dictionary with keys “first”, “middle”, “prefix”, “last”, and “suffix”.

bibulous.initialize_name(name, options=None, debug=False)

From an input name element (first, middle, prefix, last, or suffix) , convert it to its initials.

Parameters:

name : str

The name element to be converted.

options : dict of bools, optional

‘french_intials’: whether to initialize digraphs with two letters instead of the default of one. For example, if use_french_initials==True, then “Christian” -> “Ch.”, not “C.”. ‘period_after_initial’: whether to include a ‘.’ after the author initial.

Returns:

new_name : str

The name element converted to its initials form.

bibulous.get_delim_levels(s, delims=(u'{', u'}'), operator=None)

Generate a list of level numbers for each character in a string.

Parameters:

s : str

The string to characterize.

delims : tuple of two strings

The (left-hand-side delimiter, right-hand-side delimiter).

operator : str

The “operator” string that appears to the left of the delimiter. For example, operator=r’ extbf’ allows the code to look for nested structures like {...} and simultaneously for structures like ` extbf{...}`, and be able to keep track of which is which.

Returns:

levels : list of ints

A list giving the operator delimiter level (or “brace level” if no operator is given) of each character in the string.

bibulous.show_levels_debug(s, levels)

A debugging tool for showing delimiter levels and the input string next to one another.

Parameters:

s : str

The string used to determine the delimiter levels.

levels : list of ints

The list of delimiter levels at each character position in the string.

bibulous.get_quote_levels(s, disable=None, debug=False)

Return a list which gives the “quotation level” of each character in the string.

Parameters:

s : str

The string to analyze.

disable : list of ints, optional

The list of warning message numbers to ignore.

Returns:

alevels : list of ints

The double-quote-level for (``,’‘) pairs in the string.

blevels : list of ints

The single-quote-level for (`,’) pairs in the string.

clevels : list of ints

The neutral-quote-level for (”,”) pairs in the string.

Notes

When using double-quotes, it is easy to break the parser, so they should be used only sparingly.

bibulous.splitat(s, ilist)

Split a string at locations given by a list of indices.

This can be used more flexibly than Python’s native string split() function, when the character you are splitting on is not always a valid splitting location.

Parameters:

s : str

The string to split.

ilist : list

The list of string index locations at which to split the string.

Returns:

slist : list of str

The list of split substrings.

bibulous.multisplit(s, seps)

Split a string using more than one separator.

Copied from http://stackoverflow.com/questions/1059559/python-strings-split-with-multiple-separators.

Parameters:

s : str

The string to split.

sep : list of str

The list of separators.

Returns:

res : list

The list of split substrings.

bibulous.enwrap_nested_string(s, delims=(u'{', u'}'), odd_operator=u'\\textbf', even_operator=u'\\textrm', disable=None)

This function will return the input string if it finds there are no nested operators inside (i.e. when the number of delimiters found is < 2).

Parameters:

s : str

The string whose nested operators are to be modified.

delims : tuple of two strings

The left and right delimiters for all matches.

odd_operator : str

The nested operator (applied to the left of the delimiter) currently used within string “s”.

even_operator : str

The operator used to replace the currently used one for all even nesting levels.

disable : list of int, optional

The list of warning message numbers to ignore.

Returns:

s : str

The modified string.

bibulous.enwrap_nested_quotes(s, disable=None, debug=False)

Find nested quotes within strings and, if necessary, replace them with the proper nesting (i.e. outer quotes use ``...'' while inner quotes use `...').

Parameters:

s : str

The string to modify.

disable : list of int, optional

The list of warning message numbers to ignore.

Returns:

s : str

The new string in which nested quotes have been properly reformatted.

bibulous.purify_string(s)

Remove the LaTeX-based formatting elements from a string so that a sorting function can use alphanumerical sorting on the string.

Parameters:

s : str

The string to “purify”.

Returns:

p : str

The “purified” string.

bibulous.latex_to_utf8(s)

Translate LaTeX-markup special characters to their Unicode equivalents.

Parameters:

s : str

The string to translate.

Returns:

s : str

The translated version of the input.

bibulous.search_middlename_for_prefixes(namedict)

From the middle name of a single person, check if any of the names should be placed into the “prefix” and move them there.

Parameters:

namedict : dict

The dictionary containing the key “middle”, containing the string with the person’s middle names/initials.

Returns:

namedict : dict

The dictionary augmented with the key “prefix” if a prefix is indeed found.

bibulous.get_edition_ordinal(edition_field, disable=None)

Given a bibliography entry’s edition number, format it as an ordinal (i.e. “1st”, “2nd” instead of “1”, “2”) in the way that it will appear on the formatted page.

Parameters:

edition_field : str

The string representing the “edition” field in the database entry.

disable : list of int, optional

The list of warning message numbers to ignore.

Returns:

edition_ordinal_str : str

The formatted form of the edition, with ordinal attached.

bibulous.export_bibfile(bibdata, filename, abbrevs=None)

Write a bibliography database dictionary into a .bib file.

Parameters:

filename : str

The filename of the file to write.

bibdata : dict

The bibliography dictionary to write out.

abbrevs : dict, optional

The dictionary of abbreviations to write to the BIB file.

bibulous.parse_pagerange(pages_str, citekey=None, disable=None)

Given a string containing the “pages” field of a bibliographic entry, figure out the start and end pages.

Parameters:

pages_str : str

The string to parse.

citekey : str, optional

The citation key (useful for debugging messages).

disable : list of int, optional

The list of warning message numbers to ignore.

Returns:

startpage : str

The starting page.

endpage : str

The ending page. If endpage==startpage, then endpage is set to None.

bibulous.parse_nameabbrev(abbrevstr)

Given a string containing either a single “name” > “abbreviation” pair or a list of such pairs, parse the string into a dictionary of names and abbreviations.

Parameters:

abbrevstr : str

The string containing the abbreviation definitions.

Returns:

nameabbrev_dict : dict

A dictionary with names for keys and abbreviations for values.

bibulous.filter_script(line)

Remove elements from a Python script which are provide the most egregious security flaws; also replace some identifiers with their correct namespace representation.

Parameters:

line : str

The line of source code to filter.

Returns:

filtered : str

The filtered line of source code.

bibulous.str_is_integer(s)

Check is an input string represents an integer value. Although a trivial function, it will be useful for user scripts.

Parameters:

s : str

The input string to test.

Returns:

is_integer : bool

Whether the string represents an integer value.

bibulous.bib_warning(msg, disable=None)

Print a warning message, with the option to disable any given message.

Parameters:

msg : str

The warning message to print.

disable : list of int, optional

The list of warning message numbers that the user wishes to disable (i.e. ignore).

bibulous.create_citation_alpha(entry, options)

Create an “alpha” style citation key (typically the first three letters of the author’s last name, followed by the last two numbers of the year).

Parameters:

entry : dict

The bibliography entry.

options : dict

The dictionary of keyword options (the only key used is “name_separator”).

Returns:

alpha : str

The alpha-style citation key.

bibulous.toplevel_split(s, splitchar, levels)

Split a string, but only if the splitting character is at level 0 or 1 and not higher.

Parameters:

s : str

The string to split.

splitchar : str

The character to split with.

levels : list of ints

The operator levels of the characters in the string.

Returns:

split_list : list of str

The list of split sections of the string.

bibulous.get_variable_name_elements(variable)

Split the variable name into “name” (left-hand-side part), “iterator” (middle part), and “remainder” (the right- hand-side part).

With these three elements, we will know how to build a template variable inside the implicit loop.

Parameters:

variable : str

The variable name to be parsed.

Returns:

var_dict : dict

The dictionary containing elements of the variable name, with keys ‘varname’, ‘prefix’, ‘index’, and ‘suffix’. The input variable can be reconstructed with name + ‘.’ + prefix + index + suffix.

bibulous.get_names(entry, templatestr)

Get the list of names associated with a given entry, giving priority to the first namelist present in the “namelists” list.

Parameters:

entry : dict

The bibliography data entry.

templatestr : str

The template string – to tell whether to use authors or editors.

Returns:

namelist : list of dicts

The list of names found.

bibulous.format_namelist(namelist, nametype=u'author', options=None)

Format a list of dictionaries (one dict for each person) into a long string, with the format according to the directives in the bibliography style template.

Parameters:

namelist : str

The list of dictionaries containing all of the names to be formatted.

nametype : str, {‘author’, ‘editor’}, optional

Whether the names are for authors or editors.

options : dict, optional

The dictionary of keyword-based options.

Returns:

namestr : str

The formatted form of the “name string”. This is generally a list of authors or list of editors.

bibulous.namedict_to_formatted_namestr(namedict, options=None)

Convert a name dictionary into a formatted name string.

Parameters:

namedict : dict

The name dictionary (contains a required key “last” and optional keys “first”, “middle”, “prefix”, and “suffix”.

options : dict, optional

Dictionary of formatting options.

Returns:

namestr : str

The formatted string of the name.

bibulous.argsort(seq, reverse=False)

Return the indices for producing a sorted list.

Parameters:

seq : iterable

The iterable object to sort.

reverse : bool

Whether to return a reversed list.

Returns:

idx : list of ints

The indices needed for a sorted list.

bibulous.create_alphanum_citelabels(entrykey, bibdata, citelist)

Create an alphanumeric style citation key (the first letter of the author’s last name, followed by a number giving the sort order).

Warning: do not run this function on a large database of citations — it is not optimized for that use and will take quite a while to complete.

Parameters:

entry : dict

The bibliography entry.

bibdata : dict

The entire bibliography database.

citelist : list of str

The sorted list of citation keys.

Returns:

citelabels : str

The dictionary of citation labels.

bibulous.get_implicit_loop_data(templatestr)

From a template containing an implicit loop (‘...’ notation), build a full-size template without an ellipsis.

Right now, the code only allows one implicit loop in any given template.

Parameters:

templatestr : str

The input template string (containing the implicit loop ellipsis notation).

Returns:

loop_data : dict

A dictionary containing all of the information needed to build a loop for a template.

class bibulous.Bibdata(filename, disable=None, culldata=True, uselocale=None, silent=False, debug=False)

Bibdata is a class to hold all data related to a bibliography database, a citation list, and a style template.

To initialize the class, either call it with the filename of the .aux file containing the relevant file locations (for the .bib database files and the .bst template files) or simply call it with a list of all filenames to be used (i.e. database_name.bib, style_template_name.bst and main_filename.aux). The output file (the LaTeX- formatted bibliography) is assumed to have the same filename root as the .aux file, but with .bbl as its extension.

Attributes

abbrevs	dict	The list of abbreviations given in the bibliography database file(s). The dictionary keys are the abbreviations, and the values are their full forms.
bibdata	dict	The database of bibliography entries and fields derived from parsing the bibliography database file(s).
bstdict	dict	The style template for formatting the bibliography. The dictionary keys are the entrytypes, with the dictionary values their string template.
citedict	dict	The dictionary of citation keys, and their corresponding numerical order of citation.
debug	bool	Whether to turn on debugging features.
filedict	dict	The ditionary of filenames associated with the bibliographic data. The dictionary consists of keys bib, bst, aux, tex, and bbl. The first two are lists of filenames, while the others contain only a single filename.
filename	str	(For error messages and debugging) The name of the file currently being parsed.
i	int	(For error messages and debugging) The line of the file currently being parsed.
options	dict	The dictionary containing the various option settings from the style template (BST) files.
specials	dict	The dictionary containing the special templates from the BST file(s).
abbrevkey_pattern	compiled regular expression object	The regex used to search for abbreviation keys.
anybrace_pattern	compiled regular expression object	The regex used to search for curly braces { or }.
anybraceorquote_pattern	compiled regular expression object	The regex used to search for curly braces or for double-quotes, i.e. {, }, or “.
endbrace_pattern	compiled regular expression object	The regex used to search for an ending curly brace, i.e. ‘}’.
quote_pattern	compiled regular expression object	The regex used to search for a double-quote, i.e. “.
startbrace_pattern	compiled regular expression object	The regex used to search for a starting curly brace, {.
culldata	bool	Whether to cull the database so that only cited entries are parsed. Setting this to False means that the entire BIB file database will be parsed. When True, the BIB file parser will only parse those entries corresponding to keys in the citedict. Setting this to True provides significant speedups for large databases.
parse_only_entrykeys	bool	When comparing a database file against a citation list, all we are initially interested in are the entrykeys and not the data. So, in our first pass through the database, we can use this flag to skip the data and get only the keys themselves.

Methods

parse_bibfile(filename)	Parse a ”.bib” file to generate a dictionary representing a bibliography database.
parse_bibentry(entrystr, entrytype)	Given a string representing the entire contents of the BibTeX-format bibliography entry, parse the contents and place them into the bibliography preamble string, the set of abbreviations, and the bibliography database dictionary.
parse_bibfield(entrystr[, entrykey])	For a given string representing the raw contents of a BibTeX-format bibliography entry, parse the contents into a dictionary of key:value pairs corresponding to the field names and field values.
parse_auxfile(filename[, recursive_call, debug])	Read in an .aux file and convert the citation{} entries found there into a dictionary of citekeys and citation order number.
parse_bstfile(filename)	Convert a Bibulous-type bibliography style template into a dictionary.
write_bblfile([filename, write_preamble, ...])	Given a bibliography database bibdata, a dictionary containing the citations called out citedict, and a bibliography style template bstdict write the LaTeX-format file for the formatted bibliography.
create_citation_list()	Create the list of citation keys, sorted into the proper order.
format_bibitem(citekey[, debug])	Create the “ibitem{...}” string to insert into the ”.bbl” file.
insert_crossref_data(entrykey[, fieldname])	Insert crossref info into a bibliography database dictionary.
write_citeextract(outputfile[, write_abbrevs])	Extract a sub-database from a large bibliography database, with the former containing only those entries cited in the .aux file (and any relevant cross-references).
write_authorextract(searchname[, ...])	Extract a sub-database from a large bibliography database, with the former containing only those entries citing the given author/editor.
replace_abbrevs_with_full(fieldstr, resultstr)	Given an input str, locate the abbreviation key within it and replace the abbreviation with its full form.
get_bibfilenames(filename)	If the input is a filename ending in .aux, then read through the .aux file and locate the lines ibdata{...} and ibstyle{...} to get the filename(s) for the bibliography database and style template.
check_citekeys_in_datakeys()	Check to see if all of the citation keys (from the AUX file) exist within the current set of database entrykeys.
add_crossrefs_to_searchkeys()	Add any cross-referenced entrykeys into the searchkeys, the list which is used to cull the database so that only necessary entries are parsed.
insert_specials(entrykey)	Insert “special” fields into a database entry.
validate_templatestr(templatestr, key)	Validate the template string so that it contains no formatting errors.
fillout_implicit_indices(templatestr, entrykey)	From a template containing an implicit loop (‘...’ notation), build a full-size template without an ellipsis.
template_substitution(templatestr, entrykey)	Substitute database entry variables into template string.
insert_title_into_template(title_var, ...)	Insert the title field into a template string.
remove_nested_template_options_brackets(...)	Given a template string, go through each options sequence [...] and search for undefined variables.
remove_template_options_brackets(...)	Given a template string, go through each options sequence [...] and search for undefined variables.
simplify_template_bracket(templatestr, ...)	From an “options train” [...|...|...], find the first fully defined block in the sequence.
get_variable(bibentry, variable[, options])	Get the variable (i.e.
get_indexed_variable(field, indexer[, ...])	Get the result of dot-indexing into a field.
get_indexed_vars_in_template(templatestr)	Get a list of the indexed variables within a template.

add_crossrefs_to_searchkeys()

Add any cross-referenced entrykeys into the searchkeys, the list which is used to cull the database so that only necessary entries are parsed.

check_citekeys_in_datakeys()

Check to see if all of the citation keys (from the AUX file) exist within the current set of database entrykeys.

Returns:

is_complete : bool

True if all citations exist in the database, False otherwise.

create_citation_list()

Create the list of citation keys, sorted into the proper order.

fillout_implicit_indices(templatestr, entrykey, templatekey=None)

From a template containing an implicit loop (‘...’ notation), build a full-size template without an ellipsis.

Right now, the code only allows one implicit loop in any given template.

Parameters:

templatestr : str

The input template string (containing the implicit loop ellipsis notation).

entrykey : str

The key of the bibliography entry to query.

templatekey : str

If this template is for a special variable rather than an entrytype, then this key will tell which special variable is being operated on.

Returns:

new_templatestr : str

The new template with the ellipsis replaced with the loop-generated template variables and “glue”.

format_bibitem(citekey, debug=False)

Create the “ibitem{...}” string to insert into the ”.bbl” file.

This is the workhorse function of Bibulous. For a given citation key, find the resulting entry in the bibliography database. From the entry’s entrytype, lookup the relevant template in bstdict and start replacing template variables with formatted elements of the database entry. Once you’ve replaced all template variables, you’re done formatting that entry. Write the result to the BBL file.

Parameters:

citekey : str

The citation key.

Returns:

itemstr : str

The string containing the ibitem{} citation key and LaTeX-formatted string for the formatted bibliography. (That is, this string is designed to be inserted directly into the LaTeX document.)

get_bibfilenames(filename)

If the input is a filename ending in .aux, then read through the .aux file and locate the lines ibdata{...} and ibstyle{...} to get the filename(s) for the bibliography database and style template.

Also determine whether to set the culldata flag. If the input is a single AUX filename, then the default is to set culldata=True. If the input is a list of filenames, then assume that this is the complete list of files to use (i.e. ignore the contents of the AUX file except for generating the citedict), and set culldata=False.

Parameters:

filename : str

The “auxiliary” file, containing citation info, TOC info, etc.

Returns:

filedict : dict

A dictionary with keys aux, bbl, bib, bst, extract, and tex, each entry of which contains a list of filenames.

get_indexed_variable(field, indexer, entrykey=u'', options={})

Get the result of dot-indexing into a field. This can be accessing an element of a list or dictionary, or the result of operating on a string with a function.

Parameters:

field : str

The field to operate on.

indexer : str

The dot-delimited indexing operator.

entrykey : str

The entrykey of the bibliography entry being evaluated (useful for error messages).

options : dict

An optional dictionary giving extra info (such as whether to insert dots after initials).

Returns:

result : str

The string resulting from the dot-indexing operation on the field. If a valid operation cannot be performed, then return “None”.

get_indexed_vars_in_template(templatestr)

Get a list of the indexed variables within a template.

Parameters:

templatestr : str

The template to analyze.

Returns:

indexed_vars : list of str

The list of variable names that are indexed variables.

get_variable(bibentry, variable, options={})

Get the variable (i.e. entry field) from within the current bibliography entry.

Parameters:

bibentry : dict

The bibliography entry to search.

variable : str

The dot-indexed template variable to evaluate.

options : dict

An optional dictionary giving extra info (such as whether to insert dots after initials).

Returns:

result : str

The field value (if it exists). If no corresponding field is found, return None.

insert_crossref_data(entrykey, fieldname=None)

Insert crossref info into a bibliography database dictionary.

Loop through a bibliography database dictionary and, for each entry which has a “crossref” field, locate the crossref entry and insert any missing bibliographic information into the main entry’s fields.

Parameters:

entrykey : str

The key of the bibliography entry to query.

fieldname : str, optional

The name of the field to check. If fieldname==None, then check all fields.

Returns:

foundit : bool

Whether the function found a crossref for the queried field. If multiple fieldnames were input, then foundit will be True if a crossref is located for any one of them.

insert_specials(entrykey)

Insert “special” fields into a database entry.

Parameters:

entrykey : str

The key of the entry to which we want to add special fields.

insert_title_into_template(title_var, templatestr, bibentry)

Insert the title field into a template string.

This requires more work than simply performing a string replacement, because there can be punctuation conflicts when the title itself ends with punctuation, while the template itself has punctuation immediately following the title.

Parameters:

title_var : str

The title variable (which may simply be “<title>”, or may have operators attached to the variable name.

templatestr : str

The template to insert the title into.

bibentry : dict

The bibliography entry to get the title from.

Returns:

templatestr : str

The template with the variable replaced with the “title” field, with possible operators applied.

parse_auxfile(filename, recursive_call=False, debug=False)

Read in an .aux file and convert the citation{} entries found there into a dictionary of citekeys and citation order number.

Parameters:

filename : str

The filename of the .aux file to parse.

recursive_call : bool

Whether this function was called recursively (recursive_call=True), or if it is the top-level call (recursive_call=False). Only in the latter case do we take the keylist and make self.citedict with it.

parse_bibentry(entrystr, entrytype)

Given a string representing the entire contents of the BibTeX-format bibliography entry, parse the contents and place them into the bibliography preamble string, the set of abbreviations, and the bibliography database dictionary.

Parameters:

entrystr : str

The string containing the entire contents of the bibliography entry.

entrytype : str

The type of entry (article, preamble, etc.).

parse_bibfield(entrystr, entrykey=u'')

For a given string representing the raw contents of a BibTeX-format bibliography entry, parse the contents into a dictionary of key:value pairs corresponding to the field names and field values.

Parameters:

entrystr : str

The string containing the entire contents of the bibliography entry.

entrykey : str

The key of the bibliography entry being parsed (useful for error messages).

Returns:

fd : dict

The dictionary of “field name” and “field value” pairs.

parse_bibfile(filename)

Parse a ”.bib” file to generate a dictionary representing a bibliography database.

Parameters:

filename : str

The filename of the .bib file to parse.

parse_bstfile(filename)

Convert a Bibulous-type bibliography style template into a dictionary.

The resulting dictionary consists of keys which are the various entrytypes, and values which are the template strings. In addition, any formatting options are stored in the “options” key as a dictionary of option_name:option_value pairs.

Parameters:

filename : str

The filename of the Bibulous style template to use.

remove_nested_template_options_brackets(templatestr, entry, variables)

Given a template string, go through each options sequence [...] and search for undefined variables. In each sequence, return only the block of each sequence in which all variables are defined (i.e. with outer braces removed).

Parameters:

templatestr : str

The string defining the template to analyze.

entry : dict

The bibliography database entry inside which to look for variables.

variables : list of str

The variables to look for.

remove_template_options_brackets(templatestr, entry, variables)

Given a template string, go through each options sequence [...] and search for undefined variables. In each sequence, return only the block of each sequence in which all variables are defined.

Parameters:

templatestr : str

The string defining the template to analyze.

entry : dict

The bibliography database entry inside which to look for variables.

variables : list of str

The variables to look for.

replace_abbrevs_with_full(fieldstr, resultstr)

Given an input str, locate the abbreviation key within it and replace the abbreviation with its full form.

Once the abbreviation key is found, remove it from the “fieldstr” and add the full form to the “resultstr”.

Parameters:

fieldstr : str

The string to search for the abbrevation key.

resultstr : str

The thing to hold the abbreviation’s full form. (Note that it might not be empty on input.)

Returns:

fieldstr : str

The string to search for the abbrevation key.

resultstr : str

The thing to hold the abbreviation’s full form.

end_of_field : bool

Whether the abbreviation key was at the end of the current field.

simplify_template_bracket(templatestr, bibentry, variables)

From an “options train” [...|...|...], find the first fully defined block in the sequence.

A style template string contains grammatical features of the form [...|...|...], which we can call options sequences. Each “block” in the sequence (divided from the others by a | symbol), contains fields which, if defined, replace the entire options sequence in the returned string.

When the options sequence ends with “|]” (i.e. at least one of the blocks is required to be defined) but we find that none of the blocks have all their variables defined, then we replace the entire block with the “undefstr”.

Parameters:

templatestr : str

The string containing a complete entrytype bibliography style template.

variables : list of str

The list of variables defined within the template string.

bibentry : dict

An entry from the bibliography database.

Returns:

arg : str

The string giving the entrytype block to replace an options sequence.

template_substitution(templatestr, entrykey, templatekey=None)

Substitute database entry variables into template string.

Parameters:

templatestr : str

The template string itself.

entrykey : dict

The key of the database entry from which to get fields to substitute into the template.

templatekey : str

If this template is for a special variable rather than an entrytype, then this key will tell which special variable is being operated on.

Returns:

templatestr : str

The template string with all variables replaced.

validate_templatestr(templatestr, key)

Validate the template string so that it contains no formatting errors.

Parameters:

templatestr : str

The template string to be validated.

key : str

The name of the variable that uses this template.

Returns:

okay : bool

Whether or not the template is properly formatted.

write_authorextract(searchname, outputfile=None, write_abbrevs=False)

Extract a sub-database from a large bibliography database, with the former containing only those entries citing the given author/editor.

Parameters:

searchname : str or dict

The string or dictionary for the author’s name. This can be, for example, “Bugs E. Bunny” or {‘first’:’Bugs’, ‘last’:’Bunny’, ‘middle’:’E’}.

outputfile : str, optional

The filename of the extracted BIB file to write.

write_abbrevs : bool

Whether or not to write the abbreviations to the BIB file. Since the abbreviations are already inserted into the database entries, they are no longer needed, but may be useful for future editing and adding of entries to the database file.

write_auxfile(filename=None)

Given the input database file(s) and style file(s), write out an AUX file containing citations to all unique database entries.

This function is only provided as a utility, and is not actually used except during troubleshooting.

Parameters:

filename : str

The filename of the auxfile to write.

write_bblfile(filename=None, write_preamble=True, write_postamble=True, bibsize=None, debug=False)

Given a bibliography database bibdata, a dictionary containing the citations called out citedict, and a bibliography style template bstdict write the LaTeX-format file for the formatted bibliography.

Start with the preamble and then loop over the citations one by one, formatting each entry one at a time, and put end{thebibliography} at the end when done.

Parameters:

filename : str, optional

The filename of the ”.bbl” file to write. (Default is to take the AUX file and change its extension to ”.bbl”.)

write_preamble : bool, optional

Whether to write the preamble. (Setting this to False can be useful when writing the bibliography in separate steps, as in the testing suite.)

write_postamble : bool, optional

Whether to write the postamble. (Setting this to False can be useful when writing the bibliography in separate steps, as in the testing suite.)

bibsize : str, optional

A string the length of which is used to determine the label margin for the bibliography.

write_citeextract(outputfile, write_abbrevs=False)

Extract a sub-database from a large bibliography database, with the former containing only those entries cited in the .aux file (and any relevant cross-references).

Parameters:

filedict : str

The dictionary filenames must have keys “aux”, “bst”, and “bib”.

outputfile : str, optional

The filename to use for writing the extracted BIB file.

write_abbrevs : bool

Whether or not to write the abbreviations to the BIB file. Since the abbreviations are already inserted into the database entries, they are no longer needed, but may be useful for future editing and adding of entries to the database file.