Pybtex / Docs / Python API / Reading and writing bibliography data

# Reading and writing bibliography data

- Reading bibliography data
- Writing bibliography data
- Bibliography data classes

## Reading bibliography data

One of the most common things to do with Pybtex API is parsing BibTeX files. There are several high level functions in the `pybtex.database` module for reading bibliography databases.

`pybtex.database.``parse_string`(value, bib_format, **kwargs)

  Parse a Unicode string containing bibliography data and return a `BibliographyData` object.

  Parameters:

  - value – Unicode string.
  - bib_format – Data format (“bibtex”, “yaml”, etc.).

  New in version 0.19.

`pybtex.database.``parse_bytes`(value, bib_format, **kwargs)

  Parse a byte string containing bibliography data and return a `BibliographyData` object.

  Parameters:

  - value – Byte string.
  - bib_format – Data format (for example, “bibtexml”).

  New in version 0.19.

`pybtex.database.``parse_file`(file, bib_format=None, **kwargs)

  Read bibliography data from file and return a `BibliographyData` object.

  Parameters:

  - file – A file name or a file-like object.
  - bib_format – Data format (“bibtex”, “yaml”, etc.). If not specified, Pybtex will try to guess by the file name.

  New in version 0.19.

Each of these functions does basically the same thing. It reads the bibliography data from a string or a file and returns a `BibliographyData` object containing all the bibliography data.

Here is a quick example: .. doctest:

    >>> from pybtex.database import parse_file
    >>> bib_data = parse_file('../examples/tugboat/tugboat.bib')
    >>> print bib_data.entries['Knuth:TB8-1-14'].fields['title']
    Mixing right-to-left texts with left-to-right texts
    >>> for author in bib_data.entries['Knuth:TB8-1-14'].persons['author']:
    ...     print(unicode(author))
    Knuth, Donald
    MacKay, Pierre

## Writing bibliography data

The `BibliographyData` class has several methods that are symmetrical to the functions described above:

- `BibliographyData.to_string()` formats the bibliograhy data into a string,
- `BibliographyData.to_bytes()` formats the bibliograhy data into a byte string,
- `BibliographyData.to_file()` writes the bibliograhy data to a file.

    >>> from pybtex.database import BibliographyData, Entry
    >>> bib_data = BibliographyData({
    ...     'article-minimal': Entry('article', [
    ...         ('author', 'L[eslie] B. Lamport'),
    ...         ('title', 'The Gnats and Gnus Document Preparation System'),
    ...         ('journal', "G-Animal's Journal"),
    ...         ('year', '1986'),
    ...     ]),
    ... })
    >>> print bib_data.to_string('bibtex')
    @article{article-minimal,
        author = "L[eslie] B. Lamport",
        title = "The Gnats and Gnus Document Preparation System",
        journal = "G-Animal's Journal",
        year = "1986"
    }

## Bibliography data classes

Pybtex uses several classes to represent bibligraphy databases:

- `BibliographyData` is a collection of individual bibliography entries and some additional metadata.

- `Entry` is a single bibliography entry (a book, an article, etc.).

  An entry has a key (like `"knuth74"`), a type (`"book"`, `"article"`, etc.), and a number of key-value fields (`"author"`, `"title"`, etc.).

- `Person` is a person related to a bibliography entry (usually as an author or an editor).

class `pybtex.database.``BibliographyData`(entries=None, preamble=None, wanted_entries=None, min_crossrefs=2)
  `entries` = None

    A dictionary of bibliography entries referenced by their keys.

    The dictionary is case insensitive:

        >>> bib_data = parse_string("""
        ...     @ARTICLE{gnats,
        ...         author = {L[eslie] A. Aamport},
        ...         title = {The Gnats and Gnus Document Preparation System},
        ...     }
        ... """, 'bibtex')
        >>> bib_data.entries['gnats'] == bib_data.entries['GNATS']
        True

  `preamble`

    LaTeX preamble.

        >>> bib_data = parse_string(r"""
        ...     @PREAMBLE{"\newcommand{\noopsort}[1]{}"}
        ... """, 'bibtex')
        >>> print bib_data.preamble
        \newcommand{\noopsort}[1]{}

    New in version 0.19: Earlier versions used `get_preamble()`, which is now deprecated.

  `get_preamble`(*args, **kwargs)

    Deprecated since version 0.19: Use `preamble` instead.

  `to_string`(bib_format, **kwargs)

    Return the data as a unicode string in the given format.

    Parameters: | bib_format – Data format (“bibtex”, “yaml”, etc.).

    New in version 0.19.

  `to_bytes`(bib_format, **kwargs)

    Return the data as a byte string in the given format.

    Parameters: | bib_format – Data format (“bibtex”, “yaml”, etc.).

    New in version 0.19.

  `to_file`(file, bib_format=None, **kwargs)

    Save the data to a file.

    Parameters:

    - file – A file name or a file-like object.
    - bib_format – Data format (“bibtex”, “yaml”, etc.). If not specified, Pybtex will try to guess by the file name.

    New in version 0.19.

  `lower`()

    Return another `BibliographyData` with all identifiers converted to lowercase.

        >>> data = parse_string("""
        ...     @BOOK{Obrazy,
        ...         title = "Obrazy z Rus",
        ...         author = "Karel Havlíček Borovský",
        ...     }
        ...     @BOOK{Elegie,
        ...         title = "Tirolské elegie",
        ...         author = "Karel Havlíček Borovský",
        ...     }
        ... """, 'bibtex')
        >>> data_lower = data.lower()
        >>> data_lower.entries.keys()
        ['obrazy', 'elegie']
        >>> for entry in data_lower.entries.values():
        ...     entry.key
        ...     entry.persons.keys()
        ...     entry.fields.keys()
        'obrazy'
        ['author']
        ['title']
        'elegie'
        ['author']
        ['title']

class `pybtex.database.``Entry`(type_, fields=None, persons=None, collection=None)

  A bibliography entry.

  `key` = None

    Entry key (for example, `'fukushima1980neocognitron'`).

  `type` = None

    Entry type (`'book'`, `'article'`, etc.).

  `fields` = None

    A dictionary of entry fields. The dictionary is ordered and case-insensitive.

  `rich_fields` = None

    A dictionary of entry fields, converted to rich text.

  `persons` = None

    A dictionary of entry persons, by their roles.

    The most often used roles are `'author'` and `'editor'`.

  `collection` = None

    A reference to the containing `BibliographyData` object. Used to resolve crossrefs.

class `pybtex.database.``Person`(string='', first='', middle='', prelast='', last='', lineage='')

  A person or some other person-like entity.

      >>> knuth = Person('Donald E. Knuth')
      >>> knuth.first_names
      ['Donald']
      >>> knuth.middle_names
      ['E.']
      >>> knuth.last_names
      ['Knuth']

  `first_names` = None

    A list of first names.

    New in version 0.19: Earlier versions used `first()`, which is now deprecated.

  `middle_names` = None

    A list of middle names.

    New in version 0.19: Earlier versions used `middle()`, which is now deprecated.

  `prelast_names` = None

    A list of pre-last (aka von) name parts.

    New in version 0.19: Earlier versions used `middle()`, which is now deprecated.

  `last_names` = None

    A list of last names.

    New in version 0.19: Earlier versions used `last()`, which is now deprecated.

  `lineage_names` = None

    A list of linage (aka Jr) name parts.

    New in version 0.19: Earlier versions used `lineage()`, which is now deprecated.

  `bibtex_first_names`

    A list of first and middle names together. (BibTeX treats all middle names as first.)

    New in version 0.19: Earlier versions used `Person.bibtex_first()`, which is now deprecated.

        >>> knuth = Person('Donald E. Knuth')
        >>> knuth.bibtex_first_names
        ['Donald', 'E.']

  `get_part`(type, abbr=False)

    Get a list of name parts by type.

        >>> knuth = Person('Donald E. Knuth')
        >>> knuth.get_part('first')
        ['Donald']
        >>> knuth.get_part('last')
        ['Knuth']

  `rich_first_names`

    A list of first names converted to rich text.

    New in version 0.20.

  `rich_middle_names`

    A list of middle names converted to rich text.

    New in version 0.20.

  `rich_prelast_names`

    A list of pre-last (aka von) name parts converted to rich text.

    New in version 0.20.

  `rich_last_names`

    A list of last names converted to rich text.

    New in version 0.20.

  `rich_lineage_names`

    A list of lineage (aka Jr) name parts converted to rich text.

    New in version 0.20.

  `first`(*args, **kwargs)

    Deprecated since version 0.19: Use `first_names` instead.

  `middle`(*args, **kwargs)

    Deprecated since version 0.19: Use `middle_names` instead.

  `prelast`(*args, **kwargs)

    Deprecated since version 0.19: Use `prelast_names` instead.

  `last`(*args, **kwargs)

    Deprecated since version 0.19: Use `last_names` instead.

  `lineage`(*args, **kwargs)

    Deprecated since version 0.19: Use `lineage_names` instead.

  `bibtex_first`(*args, **kwargs)

    Deprecated since version 0.19: Use `bibtex_first_names` instead.

← Python API
Table of contents
Formatting bibliographies →