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