You're reading an old version of this documentation. For up-to-date information, please have a look at v0.2.

Use cases

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.

Based on this idea, you may want to output the information contained in the bibliographic record in different ways, be it as some kind of string representation or as full-fledged BibTeX record for using it, e.g., with the TeX/LaTeX typesetting system.

Bibliographic record within code 

The primary use case and original reason for writing this package is to specify a bibliographic record within another class. Suppose you’ve implemented an algorithm for power law noise and want to give credit to the original authors within your code. As you can directly give the properties on object instantiation, this looks quite natural:

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

In a more complete setting, showing a bit more code surrounding your class, this may look like:

import bibrecord


class PowerLawNoise():

    def __init__(self):
        # ... your other properties go here
        self.reference = bibrecord.Article(
            author=['J. Timmer', 'M. König'],
            title="On generating power law noise",
            journal="Astronomy and Astrophysics",
            volume="300",
            pages="707--710",
            year="1995"
        )

So what’s the advantage of this way of defining the relevant reference(s)? First of all, you define the reference in a structured fashion, making it quite easy to use the information contained in different ways (more of this below). Second, if you’re somewhat familiar with BibTeX and its way of storing bibliographic records, this way of specifying the reference will feel quite familiar.

Why would you want to use this information of the bibliographic record? Suppose you have implemented some kind of report generation mechanism (perhaps even using a template engine) that summarises what has been done in a user-friendly and well-formatted way. Here, you probably want to include the relevant literature for specific algorithms as well. This can be done quite easily, as you don’t need to parse your bibliographic record that you’ve buried somewhere as a string.

Output as string 

As it has been mentioned above already, you may have ample of use cases where you want to output a reference as a string, e.g. in context of generating a report. To create a string representation of a bibliographic record, simply use its 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.

Of course, there are nearly as many different citation styles as there are journals (and people). Therefore, the bibrecord package provides you with a simple yet quite powerful mechanism of formatting the string representation of your bibliographic records. Each record type has a format property. (For details, see bibrecord.record.Record.format). Here, you can define how you would want your string representation to look like.

Note

At least for now, no complicated conditionals (as used in BibTeX styles) can be used when defining the format, as this would require using a template engine and contradict the approach of the bibrecord package to be as light-weight and simple to use as possible.

Create a BibTeX record 

The classes used for the different types of bibliographic records, such as article and book, clearly resemble the record types of BibTeX. Hence, you may want to create a BibTeX record from a record. This is pretty simple. Just 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 (for the reference defined above):

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

Note

As you can see, the bibrecord package is quite opinionated with respect to how a BibTeX record should look like. It uses curly brackets as delimiters for the fields of each key, not quotation marks, and capitalises the record type. Furthermore, unicode characters are directly output, hence it is your sole responsibility to use a BibTeX backend capable of dealing with unicode.

Use cases

Bibliographic record within code

Output as string

Create a BibTeX record

Bibliographic record within code 

Output as string 

Create a BibTeX record 