You're reading the documentation for a development version. For the latest released version, please have a look at v0.2.

bibrecord.record module

Facilities for representing bibliographic records.

Bibliographic records form the basis of bibliographies and proper citations of other people’s work, particularly in humanities and science.

Types of bibliographic records

The different types of bibliographic records follow closely the standard set by the BibTeX system.

Note

While currently, not all bibliographic record types BibTeX supports and knows are implemented, and for those implemented not all fields are supported, the idea is to eventually support at least all record types.

The following types of bibliographic records are currently supported:

Article

Probably the primary way of publishing nowadays in science is to write an article and to submit this article to a journal for publication.
Book

Books are probably the most important type of literature in general, and in science the second important type besides articles appearing in journals.
Dataset

Datasets are increasingly seen as independent research output that should be citable. A typical use case of this record type would be a package containing some published data where for each record, the relevant dataset should be referenced.

For details, have a look at the documentation of the respective classes.

Base classes

Key to the module is a series of base classes that make implementing classes for concrete types of bibliographic records straight-forward and simple:

Record

Base class for each bibliographic record.
Person

Representation of a person’s name.

Names consist, according to BibTeX, of four parts: first (given names), last (family name), particle (e.g., von), suffix (e.g., Jr., III). To properly handle these four parts and to allow for switching between “FIRST LAST” and “LAST, FIRST” mode of display is the duty of this class.

Implementing additional types

All types of bibliographic records inherit from Record. Usually, there is not much left to do to implement an additional class, besides setting the properties (aka fields of the bibliographic record) in the constructor. However, a few things are crucial and deserve explicit mentioning:

Attributes should be settable using the constructor.

This greatly facilitates using the classes in their original intended setting, namely storing bibliographic records within a class implementing an algorithm in a somewhat structured and natural way.
Each type needs to implement a non-public attribute _type that is set to __class__.__name__.
The constructor needs to call the constructor of the super class, by using super().__init__(key=key). Note that here, the key is passed. Hence, add the key property explicitly to your class constructor as well.
Provide a default format in the property self.format.

Taken together, the constructor of a class may look as follows (this is a stripped-down example of the Book class):

def __init__(self, key='', author=None, title='', publisher='', year=''):
    super().__init__(key=key)
    self.author = author or []
    self.title = title
    self.publisher = publisher
    self.year = year
    self.format = 'author: title. publisher, year.'
    self._type = __class__.__name__

Please note that author (and editor) fields are always lists. Hence, the default is not the empty list (as this is mutable), but None. Therefore the property is set to either the value of the constructor keyword or to the empty list.

Module documentation

class bibrecord.record.Record(key='')

Bases: object

Base class for each bibliographic record.

Actual bibliographic records are represented by classes inheriting from this class. The types of bibliographic records follow those known from BibTeX.

format

Format string used to create string representation of record

For details, see to_string()

Type:: str

key

BibTeX key used to refer to the record

Type:: str

reverse

Whether to reverse last and first name in output

Default: False

Type:: bool

Examples

For examples of how to use this class, have a look at the examples of the classes that inherit from this one and implement actual types of bibliographic records.

to_string()

Return string representation of a bibliographic record.

The format of the resulting string is controlled by the property format. There, you can use all the public properties of the class that form part of the bibliographic record, such as “author”, “title”, and alike.

The properties “author” and “editor” are treated specially, to ensure the names to be appropriately formatted.

Similarly, the property “doi” is treated specially, prefixing the string “doi:” to make it easier to recognise.

Note

The aim of this method is currently in no way to allow for advanced formatting including conditionals, as possible with BibTeX styles. It only provides a rudimentary way of converting a bibliographic record into a string representation.

Returns:: output – String representation of a bibliography record
Return type:: str

to_bib()

Return BibTeX representation of a bibliography record as string.

The BibTeX representation generally looks as follows:

@Record(<key>,
    <property1> = {<value1>},
    ...
    <propertyN> = {<valueN>}
}

As you can see from this example, the output is quite opinionated, although BibTeX as such would allow for some slightly different formatting as well. To highlight the most important aspects:

Values are surrounded by curly brackets, not quotation marks.
The type of record is capitalised.
Indentation is done using tabulators.

The record type is identical to the actual class used. The properties “author” and “editor” are treated specially, to ensure the names to be appropriately formatted.

Returns:: record – BibTeX representation of a bibliography record
Return type:: str

from_bib(bibtex_record=None)

Read BibTeX entry from string and parse the contents.

Currently, the format of the BibTeX records is quite restricted. For details see bibrecord.bibtex.Entry.from_bib().

Parameters:: bibtex_record (str) – Multiline string containing a BibTeX record
Raises:: ValueError – Raised if no bibtex_record is provided

New in version 0.2.

class bibrecord.record.Person(first='', last='', particle='', suffix='')

Bases: object

Representation of a person’s name.

Names consist, according to BibTeX, of four parts: first (given names), last (family name), particle (e.g., von), suffix (e.g., Jr., III).

first

First or given name of a person

Type:: str

last

Last or family name of a person

Type:: str

particle

Particle such as “von”, usually prefixing the last name

Type:: str

suffix

Suffix of a person’s last name, such as “Jr.” or “III”

Type:: str

reverse

Whether to reverse last and first name in output

Default: False

Type:: bool

Examples

There are different usage scenarios for this class. The first is to populate the properties of an object from a (BibTeX) string:

person = Person()
person.from_bib('John Doe')

This will result in the object person having set “John” as its property “first” and “Doe” as its property “last”. Note that a person’s name consists (according to BibTeX) of four parts. See from_bib() for details.

The other way round, you may want to have a string representation of a person’s name, either in plain text representation or for use within a BibTeX record:

string = person.to_string()
bib_string = person.to_bib()

The difference of these two methods is quite subtle, and only present if at least one of “particle” or “suffix” is present. In the latter case, to_bib() will return a string that can be understood by BibTeX, i.e. with reversed order of names, meaning the first name output last and separated by a comma.

from_bib(string)

Set properties of a person’s name from a BibTeX record.

There are quote some different ways one can format a person’s name in a BibTeX record, and not all are (currently) supported. See below for a list of variants that are currently supported:

FIRST LAST
LAST, FIRST
PARTICLE LAST, FIRST
LAST, SUFFIX, FIRST
PARTICLE LAST, SUFFIX, FIRST

For the meaning of FIRST, LAST, PARTICLE, and SUFFIX see the class documentation.

Parameters:: string (str) – String containing person’s name

to_string()

Return the string representation of a person’s name.

Depending on the property reverse, the name is returned with first name first or last. Some examples:

FIRST LAST
FIRST PARTICLE LAST
FIRST LAST, SUFFIX
FIRST PARTICLE LAST, SUFFIX

Returns:: string – String representation of a person’s name
Return type:: str

to_bib()

Return the BibTeX-compatible string representation of a person’s name.

The output is basically the same as for to_string(), as long as neither particle nor suffix are set. If either of these is present, reverse is temporarily set to True.

Returns:: string – BibTeX-compatible string representation of a person’s name
Return type:: str

class bibrecord.record.Article(key='', author=None, title='', journal='', year='', volume='', pages='', doi='')

Bases: Record

Bibliographic record for an article published in a journal.

Probably the primary way of publishing nowadays in science is to write an article and to submit this article to a journal for publication.

The four essential properties of a bibliographic record of an article, according to BibTeX, are: author, title, journal, and year.

Of course, to make sense of such a record, usually you would like to have at least volume and pages in addition to those properties.

A purely optional, though sometimes very helpful property is the doi, i.e. the unique digital object identifier allowing you to retrieve the electronic version of this article if you happen to have access to the internet (and your institution subscribes to the publisher’s content).

author

List of author names (as strings)

Type:: list

title

Title of the article

Type:: str

journal

Name of the journal the article appeared in

Type:: str

year

Year the article was published

Type:: str

volume

Volume of the journal the article appeared in

Type:: str

pages

Range of pages (or article id)

Type:: str

doi

Digital object identifier referring to the article

Type:: str

Examples

One use case (and the original reason for writing this package) is to specify a bibliographic record within another class, for example in case you’ve implemented an algorithm and want to give credit to the original authors in a somewhat portable way. As you can directly give the properties on object instantiation, this looks quite natural:

reference = Article(
    author=['J. Timmer', 'M. König'],
    title="On generating power law noise",
    journal="Astronomy and Astrophysics",
    volume="300",
    pages="707--710",
    year="1995"
)

If you would want to output the above reference as a string, simply use the to_string() method:

reference.to_string()

With the default format, this would result in the following text:

J. Timmer, M. König: On generating power law noise. Astronomy and
Astrophysics 300:707--710, 1995.

Note that the line break is a matter of display here and not contained in the original string output. Of course, if you would like to revert the names, i.e. having the first name printed last, this can be done as well:

reference.reverse = True
reference.to_string()

With the default format, this would result in the following text:

Timmer, J., König, M.: On generating power law noise. Astronomy and
Astrophysics 300:707--710, 1995.

If you would want to create a BibTeX record from this, make sure to first add a key:

reference.key = 'timm-aaa-300-707'
reference.to_bib()

The output of print(reference.to_bib()) would look as follows:

@Article{timm-aaa-300-707,
    author = {J. Timmer AND M. König},
    title = {On generating power law noise},
    journal = {Astronomy and Astrophysics},
    year = {1995},
    volume = {300},
    pages = {707--710}
}

Thus, you can easily create a BibTeX bibliography from your bibliography records that should work well with BibTeX.

class bibrecord.record.Book(key='', author=None, editor=None, title='', publisher='', year='', address='', edition='')

Bases: Record

Bibliographic record for a book.

Books are probably the most important type of literature in general, and in science the second important type besides articles appearing in journals.

The four essential properties of a bibliographic record of a book, according to BibTeX, are: author or editor, title, publisher, and year.

Of course, to make sense of such a record, usually you would like to have at least address in addition to those properties.

Optionally, you would like to give details of the edition of the book as well.

author

List of author names (as strings)

Note: You should only provide either authors or editors.

Type:: list

editor

List of editor names (as strings)

Note: You should only provide either authors or editors.

Type:: list

title

Title of the book

Type:: str

publisher

Name of the publisher of the book

Type:: str

year

Year the book was published

Type:: str

address

Address of the publisher of the book (usually the name of the place)

Type:: str

edition

Information on the edition of the book (if not first edition)

Type:: str

Examples

One use case (and the original reason for writing this package) is to specify a bibliographic record within another class, for example in case you’ve implemented an algorithm and want to give credit to the original authors in a somewhat portable way. As you can directly give the properties on object instantiation, this looks quite natural:

reference = Book(
    author=['A. Abragam'],
    title="Principles of Nuclear Magnetism",
    publisher="Oxford University Press",
    year="1961",
    address="Oxford, UK"
)

If you would want to output the above reference as a string, simply use the to_string() method:

reference.to_string()

With the default format, this would result in the following text:

A. Abragam: Principles of Nuclear Magnetism. Oxford University
Press, Oxford, UK 1961.

Note that the line break is a matter of display here and not contained in the original string output. Of course, if you would like to revert the names, i.e. having the first name printed last, this can be done as well:

reference.reverse = True
reference.to_string()

With the default format, this would result in the following text:

Abragam, A.: Principles of Nuclear Magnetism. Oxford University
Press, Oxford, UK 1961.

If you would want to create a BibTeX record from this, make sure to first add a key:

reference.key = 'abragam-a-1961'
reference.to_bib()

The output of print(reference.to_bib()) would look as follows:

@Book{abragam-a-1961,
    author = {A. Abragam},
    title = {Principles of Nuclear Magnetism},
    publisher = {Oxford University Press},
    year = {1961},
    address = {Oxford, UK}
}

Thus, you can easily create a BibTeX bibliography from your bibliography records that should work well with BibTeX.

Similarly, if you have a book that has an editor (or a list of editors) rather than an author/authors, you would define your bibliographic record like so:

reference = Book(
    editor=['Arnold J. Hoff'],
    title="Advanced EPR. Applications in Biology and Biochemistry",
    publisher="Elsevier",
    year="1989",
    address="Amsterdam"
)

If you would want to output the above reference as a string, simply use the to_string() method, as before:

reference.to_string()

With the default format, this would result in the following text:

Arnold J. Hoff (Ed.): Advanced EPR. Applications in Biology and
Biochemistry. Elsevier, Amsterdam 1989.

Note that the line break is a matter of display here and not contained in the original string output.

to_string()

Return string representation of a bibliographic record.

The format of the resulting string is controlled by the property format. There, you can use all the public properties of the class that form part of the bibliographic record, such as “author”, “title”, and alike.

The properties “author” and “editor” are treated specially, to ensure the names to be appropriately formatted. Furthermore, in case of the editor property not being empty, the editors’ rather than the authors’ names are listed, and “(Ed.)” added to the end.

For further details of this method, see Record.to_string().

Returns:: output – String representation of a bibliography record
Return type:: str

class bibrecord.record.Dataset(key='', author=None, editor=None, title='', publisher='', year='', version='', doi='', url='')

Bases: Record

Bibliographic record for a dataset.

Datasets are (fortunately) increasingly seen as independent research output that should be citable. While published datasets are only as good (and useful) as they are annotated, in general publishing data is an excellent idea.

The class currently closely follows the fields available from Zenodo. Furthermore, the dataset record type is not part of the original BibTeX record types (as the idea of publishing datasets is much younger than BibTeX), but is included in biblatex starting with version 3.13.

author

List of author names (as strings)

Note: You should only provide either authors or editors.

Type:: list

editor

List of editor names (as strings)

Note: You should only provide either authors or editors.

Type:: list

title

Title of the dataset

Type:: str

publisher

Name of the publisher of the dataset (e.g., “Zenodo”)

Type:: str

year

Year the dataset was published

Type:: str

version

Version of the dataset cited

Note that datasets often have version numbers or strings

Type:: str

doi

Digital object identifier referring to the dataset

Type:: str

url

Uniform Resource Location (URL) referring to the dataset

Type:: str

Examples

One use case (and the original reason for writing this package) is to specify a bibliographic record within another class, for example in case you’ve implemented an algorithm and want to give credit to the original authors in a somewhat portable way. As you can directly give the properties on object instantiation, this looks quite natural:

reference = Dataset(
    author=['John Doe'],
    title="Lorem ipsum",
    publisher="Zenodo",
    year="2024",
    version="2024-01-29",
    doi="10.5281/zenodo.00000000",
)

If you would want to output the above reference as a string, simply use the to_string() method:

reference.to_string()

With the default format, this would result in the following text:

John Doe: Lorem ipsum (2024-01-29).
Zenodo, DOI:10.5281/zenodo.00000000, 2024.

Note that the line break is a matter of display here and not contained in the original string output. Of course, if you would like to revert the names, i.e. having the first name printed last, this can be done as well:

reference.reverse = True
reference.to_string()

With the default format, this would result in the following text:

Doe, John: Lorem ipsum (2024-01-29).
Zenodo, DOI:10.5281/zenodo.00000000, 2024.

If you would want to create a BibTeX record from this, make sure to first add a key:

reference.key = 'timm-aaa-300-707'
reference.to_bib()

The output of print(reference.to_bib()) would look as follows:

@Dataset{,
    author = {John Doe},
    title = {Lorem ipsum},
    publisher = {Zenodo},
    year = {2024},
    version = {2024-01-29},
    doi = {10.5281/zenodo.00000000}
}

Thus, you can easily create a BibTeX bibliography from your bibliography records that should work well with BibTeX/biblatex.

New in version 0.2.

to_string()

Return string representation of a bibliographic record.

The format of the resulting string is controlled by the property format. There, you can use all the public properties of the class that form part of the bibliographic record, such as “author”, “title”, and alike.

The properties “author” and “editor” are treated specially, to ensure the names to be appropriately formatted. Furthermore, in case of the editor property not being empty, the editors’ rather than the authors’ names are listed, and “(Ed.)” added to the end.

For further details of this method, see Record.to_string().

Returns:: output – String representation of a bibliography record
Return type:: str