Architecture

Each software has some kind of architecture, and this is the place to describe it in broad terms, to make it easier for developers to get around the code.

Core domain

The idea of the bibrecord package is to handle bibliographic records within source code in a way that the information contained in this records can be operated upon. The prototypical use case scenario: you implement an algorithm described in a publication, and you would like to cite this publication in the code – in a way that users of your implementation can have the reference printed in a report or else.

Hence, the core abstraction of the bibrecord package is the bibliographic record, in its abstract form implemented in the bibrecord.record.Record class. The bibliographic record is modelled following closely the overall scheme defined by the BibTeX file format and bibliography tool. Therefore, a bibliographic record defined by bibrecord.record.Record or one of its subclasses – you will never use bibrecord.record.Record directly, but always a concrete subclass, such as bibrecord.record.Article – can be output directly as BibTeX record or as formatted textual reference. Nevertheless, the primary focus of the bibrecord.record.Record class is on containing the relevant information (metadata) of the bibliographic record, and not any connection to the BibTeX world.

Extension: collections of records

Individual bibliographic records are handled by the bibrecord.record.Record class and its descendants, as described above. However, sometimes there is the need to deal with collections of bibliographic records. A prototypical use case would be a package containing data from different sources (i.e., with different references) where for each individual dataset the appropriate reference should be provided. Furthermore, datasets and bibliographic records may have an n to m relationship. Hence, it seems unreasonable to manually add the same reference(s) over and over in the code.

The solution is obvious: a collection of records, i.e. a bibliographic database, where we can access individual records based on a unique key. This is what the class bibrecord.database.Database provides us with. How we get the information contained in the individual bibliographic records into the database in the first place is a different matter and an unimportant detail for now.

Periphery: reading BibTeX files

Some connection to the BibTeX world comes to no surprise after all. Particularly in light of collections of datasets, there is a need for a code-independent storage of the actual information contained in the individual bibliographic records, and the BibTeX format is well-established and quite robust.

The bibrecord.bibtex module contains two abstractions for dealing with BibTeX files and records: Individual BibTeX entries are represented as bibrecord.bibtex.Entry, and entire BibTeX bibliographies as read from a file as bibrecord.bibtex.Bibliography. Normal users will not care about the bibrecord.bibtex.Entry class, as this is merely a proxy between the bibrecord.bibtex.Bibliography and the individual machine-actionable bibliographic records of bibrecord.record.Record contained in a bibrecord.database.Database.