bibstuff.bibstyles package

Submodules

bibstuff.bibstyles.default module

bibstuff.bibstyles.default: default citation and reference style

Produces a list of citations that to be included in a reStructuredText document. (In very simple documents, can also provide citation reference formatting by substituting in the document text for the citation references.)

A style includes:

• citation template
• CitationManager class
• sortkey for make_text_output (often based on a field list)

note:you will often want to override these note:shared.py holds defintions common to most styles note:see the examples (e.g., example_numbered.py) of different styles copyright:2006 Alan G Isaac, see AUTHORS license:MIT (see LICENSE)

bibstuff.bibstyles.default.CITEREF_TEMPLATE = {'citeref_sep': ', ', 'max_cite_names': 2}

Every style must have a CITATION_TEMPLATE, a CitationManager, and a ref_list_sort_key. Crucial formatting decisions are made int the CITATION_TEMPLATE. The CITATION_TEMPLATE provides default reference formatting (may also be used by BibStyle)

TODO:

• provide graceful handling of missing fields
• allow different formatting of first and other names
• allow different initial line and subsequent line indenting

class bibstuff.bibstyles.default.CitationManager(biblist, citekeys=None, citation_template=None, sortkey=None)

Bases: bibstuff.bibstyles.shared.CitationManager

format_inline_cite(cite_key_list)

Usually you will need to write a ‘format_inline_cite’ function that the CiteRefProcessor will use to substitute inline for citation references.

get_citation_label(entry, citation_template=None)

sortkey(bibentry)

bibstuff.bibstyles.default.format_inline_cite(entry_list, citation_manager)

Return string, formatted in-text citation (allows multiple citations).

entry_list : list

entries to be formatted

citation_manager : CitationManager instance

handles name formatting

Note:need the entry formatter bc its determines the field of the names for the cite Note:much of the following functionality was in the old Bibstyle’s formatCitation() method TODO:rewrite TODO:? entries shd be more featureful ? (conflicts with core goal of BibEntry class)

bibstuff.bibstyles.default_templates module

bibstuff.bibstyles.default_templates

Provides default templates for style writers. Used by the default style (default.py).

CITATION TEMPLATE

book = ‘%(year)s. %(title)s.’, article = ‘%(year)s. %(title)s. %(journal)s %(volume)s, %(pages)s.’, misc = ‘%(year)s. %(title)s.’,

default_type : str

provide template for string interpolation (use fields as keys) e.g., ‘ %(year)s. %(title)s.’

name_first : str

name template for primary name in citation (see NameFormatter documentation)

name_other : str

name template for remaining names in citation (see NameFormatter documentation)

name_name_sep : 2-tuple of str

first element separates each name from the next, second element separates penultimate name from ultimate

etal : str

replacement for name when max_citation_names exceeded (e.g., ‘, et al.’)

initials : str

first letter of first (f), von (v), last (l), jr (j) (e.g., ‘f’)

max_citation_names : int

maximum number of names to format for a citation definition

indent_left : int

left indent for citation definitions

citation_sep : str

separator between citations (e.g., “\n\n”)

names_details_sep : str

separator between the names and the details in a citation definition (e.g., ‘. ‘)

copyright:2006 by Alan G Isaac license:MIT since:2006-08-19

bibstuff.bibstyles.default_templates.default_post_processor(citations_as_string)

bibstuff.bibstyles.example_numbered module

bibstuff.bibstyles.example_numbered

Provides an examle of how to easily modify an existing style: Just import everything from that style, and then override what you wish to change. In this case, we import from default.py, the default style.

This style changes to numbered citation references and citations. Citation references are numbered like this: (1,2). Citations are numbered like this:

1. First Citation Definition
2. Second Citation Definition

The numbers reflect the order cited (the ‘citation_rank’).

copyright:2006 Alan G Isaac, see AUTHORS license:MIT (see LICENSE)

class bibstuff.bibstyles.example_numbered.CitationManager(biblist, citekeys=None, citation_template=None, sortkey=None)

Bases: bibstuff.bibstyles.shared.CitationManager

default_citation_template = {'name_first': 'f{. }. |v |l|, j', 'misc': '%(year)s. %(title)s.', 'default_type': ' %(year)s. %(title)s.', 'max_citation_names': 3, 'article': '%(year)s. %(title)s. *%(journal)s* %(volume)s, %(pages)s.', 'indent_left': 0, 'citation_sep': '\n\n', 'post_processor': <function default_post_processor at 0x2b04960b9320>, 'inproceedings': '(%(year)s) "%(title)s". In %(editor)s (Eds.) *%(booktitle)s*, %(address)s: %(publisher)s.', 'name_other': 'f{. }. |v |l|, j', 'incollection': '(%(year)s) "%(title)s". In %(editor)s (Eds.) *%(booktitle)s*, %(address)s: %(publisher)s.', 'techreport': '(%(year)s) "%(title)s". %(institution)s %(type)s %(number)s. %(url)s', 'book': '(%(year)s) *%(title)s*. %(address)s: %(publisher)s.', 'etal': ', et al.', 'name_name_sep': (', ', ' and '), 'initials': 'f', 'names_details_sep': '. '}

format_inline_cite(cite_key_list)

get_citation_label(entry, template=None)

sortkey(bibentry)

bibstuff.bibstyles.example_numbered.format_inline_cite(entries, keys, all_keys)

bibstuff.bibstyles.jasss_style module

bibstuff.bibstyles.JASSS_style

Style for the Journal of Artificial Societies and Social Simulation The JASSS page for authors claims they use the Oxford style, but these are clearly different.

Examples (from the journal website) inconsistent in use of commas, quotes, ...

HASTIE, R (1986) “Experimental evidence on group accuracy”. In Jablin F M, Putnam L L, Roberts K H and Porter L W (Eds.) Handbook of Organizational Communication: An Interdisciplinary Perspective, Beverly Hills, CA: Sage.

KALAKOTA R and Whinston A B (1996) Frontiers of Electronic Commerce. Reading, MA: Addison-Wesley Publishing Company, Inc..

KARPINSKI R (1997) Extranets emerge as next challenge for marketers. Netmarketing, April 1997. pp. 1-4.

LEE H L and Billington C (1992) Managing Supply Chain Inventory: Pitfalls and Opportunities. Sloan Management Review, Spring 1992. pp. 65-73.

RICHIARDI, M, Leombruni, R, Sonnessa, M and Saam, N (2006). ‘A Common Protocol for Agent-Based Social Simulation’. Journal of Artificial Societies and Social Simulation 9(1) http://jasss.soc.surrey.ac.uk/9/1/15.html.

copyright:2006 Alan G Isaac, see AUTHORS license:MIT (see LICENSE)

class bibstuff.bibstyles.jasss_style.CitationManager(biblist, citekeys=None, citation_template=None, sortkey=None)

Bases: bibstuff.bibstyles.shared.CitationManager

default_citation_manager = {'name_first': 'V |L |f', 'misc': '%(year)s. %(title)s.', 'default_type': ' %(year)s. %(title)s.', 'max_citation_names': 5, 'article': '(%(year)s) "%(title)s". *%(journal)s* %(volume)s, %(month)s %(year)s. pp. %(pages)s. %(url)s', 'indent_left': 3, 'citation_sep': '\n\n', 'post_processor': <function default_post_processor at 0x2b04960b9320>, 'inproceedings': '(%(year)s) "%(title)s". In %(editor)s (Eds.) *%(booktitle)s*, %(address)s: %(publishers)s', 'name_other': 'v |l |f', 'incollection': '(%(year)s) "%(title)s". In %(editor)s (Eds.) *%(booktitle)s*, %(address)s: %(publishers)s', 'techreport': '(%(year)s) "%(title)s". %(institution)s %(type)s %(number)s. %(url)s', 'book': '(%(year)s) *%(title)s*. %(address)s: %(publisher)s.', 'etal': ', et al.', 'name_name_sep': (', ', ' and '), 'initials': 'f', 'names_details_sep': ' '}

format_inline_cite(cite_key_list)

get_citation_label(entry, citation_template=None)

sortkey(bibentry)

bibstuff.bibstyles.shared module

bibstuff.bibstyles.shared: Utilities and formatting classes

Utilities and formatting classes for BibStuff, especially for bib4txt.py.

copyright:2008 Alan G Isaac, see AUTHORS license:MIT (see LICENSE)

class bibstuff.bibstyles.shared.CitationManager(biblist, citekeys=None, citation_template=None, sortkey=None)

Bases: object

TODO:possibly useful for bibsearch.py

citekeys

citekeys property

default_citation_template = {'name_first': 'v |l,| j,| f', 'misc': '%(year)s. %(title)s.', 'default_type': ' %(year)s. %(title)s.', 'max_citation_names': 3, 'article': '%(year)s. %(title)s. *%(journal)s* %(volume)s, %(pages)s.', 'indent_left': 3, 'citation_sep': '\n\n', 'post_processor': <function default_post_processor at 0x2b04960b9320>, 'inproceedings': '(%(year)s) "%(title)s". In %(editor)s (Eds.) *%(booktitle)s*, %(address)s: %(publisher)s.', 'name_other': 'f |v |l|, j', 'incollection': '(%(year)s) "%(title)s". In %(editor)s (Eds.) *%(booktitle)s*, %(address)s: %(publisher)s.', 'techreport': '(%(year)s) "%(title)s". %(institution)s %(type)s %(number)s. %(url)s', 'book': '(%(year)s) *%(title)s*. %(address)s: %(publisher)s.', 'etal': ', et al.', 'name_name_sep': (', ', ', and '), 'names_details_sep': '. ', 'initials': ''}

find_entries(citekeys=None, discard=True)

return all entries if citekeys==None else matching entries discard=True -> discard keys that do not have a bib entry

format_citation(entry)

format_inline_cite(cite_key_list)

Returns a formatted inline citation reference. Usually used by a CiteRefProcessor object during processing. Usually styles need to override this method.

get_citation_label(entry, citation_template=None)

get_citation_rank(entry, citekeys=None)

get_citekeys()

get_entries(citekeys=None)

make_citations(entries=None, citation_template=None)

return formatted citations based on list of entries

Note:called by ../bib4txt.py in make_text_output Note:citation order based on order of entries (so must sort ahead of time) Note:related functionality was in the old CitationFormatter’s FormatReferences() method

make_sort_key(bibentry, field_list)

create a string for sorting. Function returns tuple: (sort_string, bibentry key)

Note:this is essentially what was Bibstyle’s makeSortKey method

set_citekeys(citekeys)

set self._citekeys to keys and make associated entries

set_citeref_processor(processor)

sort(sortkey=None)

sortkey(entry)

Note:the sort key is a style consideration and so must be provided by the style; therefore, you must usually OVERRIDE this default sort key

class bibstuff.bibstyles.shared.CiteRefProcessor(citation_manager)

Bases: simpleparse.dispatchprocessor.DispatchProcessor

Formats inline citations and substitutes them into text. Stores all cite keys in all_citekeys (a list, to record citation order). Can store result as original text with substituted citation references.

Note:based on the defunct ‘addrefs.py’ CitationFormatter class

cite((tag, start, stop, subtags), buffer)

Return everything.

Alternative default def: self.result.append( buffer[start:stop])

fn((tag, start, stop, subtags), buffer)

Return everything.

inline_literal((tag, start, stop, subtags), buffer)

Return everything.

log_msg(msg)

plain((tag, start, stop, subtags), buffer)

Return everything.

class bibstuff.bibstyles.shared.EntryFormatter(citation_template)

Bases: object

format_citation_details(entry, citation_template=None)

Return string.

format_citation_names(entry, citation_template=None)

format_entry(entry, citation_template=None)

Return string. Format an entry (e.g., as a citation, i.e., a single bibliography reference). Note that a BibEntry object acts like a dict for Bib fields except no KeyError (returns None instead). citation_template holds templates for entry types

Note:something related to this method was formerly Bibstyle’s formatRef method Note:called by make_citations (and currently nothing else)

pick_raw_names(entry, fields=None)

Return BibName-object if possible else string (from “raw” names).

Note:2006-08-02 altered to return BibName instance and not set _names Note:self returns None if field missing (-> no KeyError) TODO:return BibName instance for each available name field??

class bibstuff.bibstyles.shared.NameFormatter(template, initials='')

Bases: object

Create a NameFormatter object based on a template string.

NAME FORMATTING TEMPLATES

The name template takes some explanation.

Name parts are referred to by part-designator, which is just the part’s first letter: (v)on, (l)last, (j)r or (f)irst. The designator may be capitalized for force upper-casing the entire part.

Each name part may have one associated section in a name formatting template. Sections are separated by ‘|’ and must include a part-designator (one of ‘FVLJfvlj’). The presumption is that part-designators will be the only alphabetic characters in a name template.

A section will generate output iff the name part for that section exists. Each section may have a partsep (in curly braces, immediately following the part-designator) and other characters (which may not be any of ‘fvljFVLJ’). The partsep indicates what should separate multiple tokens of the same part (e.g., two part last names, or ‘van der’ for the (v)on part). A part separator will replace the default space to separate multiple tokens in a part. Any other characters are included as is.

For example:

"v{~}~|l,| j,| f{. }." with initials='f' produces:
"McFeely, J. W." or "van~der~Stadt, Jr, C. M."

Note:has a property -> must be new style class, inherit carefully Note:20080331 allow capital part-designators (FVLJ) to force capitalization

default_partsep = None

note: not planning to parameterize this default (e.g., in the citation template)

format_name(name_data)

Return one name (stored in name_data) as a formatted string.

Formats name_data according to the NameFormatter template.

Parameters:name_data (list or string) – list of name_parts or name as string

get_template()

name_dict2formatted(name_dict)

Returns one fully formatted name, based on a name_dict. the name_dict should have the keys: first , von, last, jr

set_template(template)

Return None.

sets the name formatting template and sets the associated partdict used for actual formatting

template

template property

template2dict(template)

parse the name formatting template into a partdict to be used for the actual formatting

Note:parsing a name template into a partdict is trivial, so just do it here Note:allow capital part id (to force capitalization)

class bibstuff.bibstyles.shared.NamesFormatter(citation_template=None, template_list=None, initials='')

Bases: object

Provides a formatter for BibName instances. Instances are initialized with formatting information. Use the format_names method to produce a formatted string representing a BibName instance.

Sample usage:

#create an author entry
n = bibname.BibName('One, Test and Test Two','author') 
#create a formatter
nf = bibstyles.shared.NamesFormatter(template_list=['f| v| l| j']*2,initials=False)
#print the formatted names
print nf.format_names(n)

See:documentation for the NameFormatter class Note:2006-08-03 add initials keyword to __init__

format_names(names)

Return string, which represents the BibName instance names formatted as determined by the NamesFormatter attributes.

NAME FORMATTING TEMPLATES are explained in some detail in the doc string for the NameFormatter class. Briefly:

Template sections are separated by |. Name parts are referred to by first letter: (v)on, (l)last, (j)r or (f)irst. These letters may be followed by token separator enclosed in curly braces. Any other characters are included as is.

Note:2006-07-25 radically refactored from bibname.py’s FormatName() function

bibstuff.bibstyles.shared.append_sep(s, sep)

return s+sep after removing duplicate punctuation at the join

Parameters:

• s: string
• sep: string

TODO:

restrict characters removed?

bibstuff.bibstyles.shared.reformat_para(para='', left=0, right=72, just='LEFT')

Simple paragraph reformatter. Allows specification of left and right margins, and of justification style (using constants defined in module). :note: Adopted by Schwilk from David Mertz’s example in TPiP :see: Mertz, David, Text Processing in Python (TPiP)

Module contents

The bibstyles package provides classes and styles for formatted text output.

This is the __init__.py for bibstyles package

bibstuff.bibstyles.from_name(name)