### Navigation

- index
- modules |
- modules |
- home|
- search|

# 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.

### Navigation

- index
- modules |
- modules |
- home|
- search|