Database module

BibDB

The BibDB class provides methods to store and manage BibTeX entry objects, like Article, Book, etc..

Like the entry object, it is designed to behave similar to s python dictionary. The citation-key and the respective entry object are the key-value pair. To manipulate database entries, one can either use the class methods (BibDB.get_entry(), BibDB.add_entry() and BibDB.del_entry()) or the standard operators, like:

>>> entryObject = dbObject['citation-key']
>>> dbObject['citation-key'] = entryObject
>>> del dbObject['citation-key']

Note

The method BibDB.add_entry() offers more flexibility regarding the citation-key than the set-operator!

Like a dictionary it supports the methods keys(), values(), and items(). Furthermore it is iterable, like:

>>> for citation_key, entryObject in dbObject.items():
>>>     ...

It also supports the built-in function hash() and comparison operator: ==, !=.

Note

Because the hash value represents the contents, an database object should not been used as a key in hashable collections!

To check if a citation-key is defined, one can simply:

>>> if citation_key in dbObject:
>>>     ...

The built-in function len() returns the number of entries stored in the database.

class biblib.BibDB(ListOfEntryObj=None, method=None)[source]

This is the BibTeX database main class.

Optional a database can be initially populate by a list of Entry objects.

Parameters:
  • ListOfEntryObj (BibDB.data) – list of BibTeX Entry object (Article | Book | …)
  • method (str) – keyword for merging method (see add_entry())
Returns:

BibTeX database object
Return type:

BibDB
Raises:
  • TypeError – if an EntryObj is not of a valid object type
  • KeyError – if there is trouble with a citation-key of an EntryObj
ckey_tpl = None

Template for a citation-key, based on the tag names within an Entry. By default: {family}{year}, here family refers to the first author family name.

ckey_tpl_wc = None

Template for a citation-key with a counter. By default: {family}{year}{cnt}, here cnt will be replaced with the choosen counter (ckey_tpl_cnt).

ckey_tpl_cnt = None

Counter style for the citation-key template: alpha (default a,b,..,z), Alpha (A,B,..,Z) or num (1,2,3,…).

keys()[source]

Returns a list of citation-keys defined in the database.

Returns:list of citation-keys
Return type:list
values()[source]

Returns a list of entry objects stored in the database.

Returns:list of entry objects
Return type:list
items()[source]

Returns a list of sets containing citation-key/entry object.

Returns:list of sets citation-key/entry object
Return type:list
get_entry(ckey)[source]

Returns the Entry object with the given citation-key in the database.

Parameters:ckey (str) – citation-key
Returns:BibTeX Entry object
Return type:Article | Book | …
Raises:KeyError – if citation-key did not exist in database
add_entry(entryObj, ckey=None, method=None)[source]

Adds an Entry object to the database using ckey or Entry.ckey of entryObj as citation-key. The method argument will overwrite an existing object attribute. There are different methods available how to handle the citation-key. If method is:

  • None: (default) an invalid or conflicting citation-key will raise a KeyError.
  • 'lazy': Try to use Entry.ckey of entryObj or ckey as citation-key. If the it is already in use or invalid, generate a new using proposeCKey().
  • 'auto': Always use proposeCKey() to generate a proper citation-key.
  • 'force': Use Entry.ckey of entryObj or ckey as citation-key. If the it is already in used, the old Entry object will be replaced. If it is invalid, generate a new using proposeCKey().
Parameters:
  • entryObj (Article | Book | …) – BibTeX Entry object
  • ckey (str) – citation-key
  • method (str) – keyword for adding method (see above)
Returns:

citation-key as used for the database
Return type:

str
Raises:
  • TypeError – if entryObj is not of a valid object type
  • KeyError – if there is trouble with a citation-key
  • NameError – if argument for method is invalid
del_entry(ckey)[source]

Deletes the Entry object with a given BibTeX citation-key.

Parameters:ckey (str) – citation-key
Raises:KeyError – if citation-key did not exist in database
mod_entry_type(ckey, newtype)[source]

Modifies the BibTeX Entry type for a given citation-key.

Parameters:
  • ckey (str) – citation-key
  • newtype (str) – new Entry type
Raises:
  • KeyError – if there is trouble with a citation-key
  • NameError – if newtype is invalid
update_ckey(old, new)[source]

Updates the BibTeX citation-key of an Entry object in the database.

Note

The citation-key stored in the respective Entry object (Entry.ckey) will left unchanged!

Parameters:
  • old (str) – old citation-key
  • new (str) – new citation-key
Raises:

KeyError – if one of the citation-keys are invalid
proposeCKey(entryObj)[source]

Proposes a BibTeX citation-key for a given Entry object.

Based on the tag names and their contents within the Entry object and with the template strings (ckey_tpl, ckey_tpl_wc), the method will return a citation-key which suits the database.

Parameters:

entryObj (Article | Book | …) – BibTeX Entry object
Returns:

proposed citation-key
Return type:

str
Raises:
  • TypeError – if entryObj is not of a valid object type
  • KeyError – if a tag is used in ckey_tpl or ckey_tpl_wc which is not defined
  • ValueError – if ckey_tpl or ckey_tpl_wc string is erroneous.
  • IndexError – if the counter runs out of elements.
merge_bibdb(dbObj, method=None)[source]

Merges the Entry objects of another database object. There are different methods available how to handle the citation-key. It returns a dictionary where the keys refer to the original citation-key of an Entry object and the value to the new one used in the database.

Parameters:
  • dbObj (BibDB) – BibTeX database object
  • method (str) – keyword for merging method (see add_entry())
Returns:

dictionary mapping old to new citation-key
Return type:

dict
Raises:
  • TypeError – if dbObj is not a valid BibTeX database object
  • KeyError – if there is trouble with a citation-key
  • NameError – if argument for method is invalid
bibtex()[source]

Returns the BibTeX formatted string of data base.

Deprecated since version 0.1.dev1-r67: Use function db_to_string() instead.

Returns:BibTeX formatted string
Return type:str
has_ckey(ckey)[source]

Test if a citation-key is defined within the database.

Deprecated since version 0.1.dev4: Use ckey in dbOject instead.

Parameters:ckey (str) – citation-key
Returns:True | False
Return type:bool
has_doi(doi)[source]

Test if a DOI is defined within the database.

Parameters:doi (str) – digital object identifier
Returns:True | False
Return type:bool
datadict

A dictionary containing the citation-keys as keys and the BibTeX Entry objects (Article | Book | …) as values.

data

A list containing the BibTeX objects (Article | Book | …) of the database.

Deprecated since version 0.1.dev4: Use BibDB.values() instead.

ckeys

A list of the BibTeX citation-keys of the database.

Deprecated since version 0.1.dev4: Use BibDB.keys() instead.

dois

Returns a dictionary with doi as key and citation-key as value.

StorageDB

class biblib.StorageBibDB(storage, method=None)[source]

Bases: biblib._bibdb.BibDB

StorageBibDB is a BibDB utilizing a storage as defined in storage.

Parameters:storage (biblib.storage.ReadStorage) – storage object used as backend 
>>> from biblib.storage import FileStorage
>>> storage = FileStorage('/path/to/some/file')
>>> db = FileStorage(storage)
>>> # changes to db will persited within the storage
>>> db['MyCiteKey'] = someEntry
>>> # do bulk changes
>>> with db:
>>>     # do some changes to db
>>>
storage = None

storage given on object creation

save()[source]

Persist database entries in storage backend

class biblib.StringBibDB(string='', method=None, mode='w', encoding='ascii')[source]

Bases: biblib._bibdb.StorageBibDB

StorageBibDB that will store the database in a BibTex string.

>>> from biblib.storage import StringStorage
>>> # get db data as bibtex string
>>> db.string()
>>> # or
>>> str(db)
Parameters:
  • string (str) – string from which the db will be initialized
  • method (str) – method to determin cite key in db
  • mode (str) – open db in read/write (‘w’) or read onyl (‘r’) mode
  • encoding (str) – string encoding
string

return storage data as string

class biblib.FileBibDB(filename, method=None, mode='w', encoding='ascii')[source]

Bases: biblib._bibdb.StorageBibDB

StorageBibDB that will store the database in a BibTeX file.

Parameters:
  • file (str) – path to BibTeX file
  • method (str) – method to determin cite key in db
  • mode (str) – open db in read/write (‘w’) or read onyl (‘r’) mode
  • encoding (str) – file encoding
class biblib.SqliteBibDB(filename, method=None)[source]

Bases: biblib._bibdb.StorageBibDB

StorageBibDB that will store the database in a SQLite3 database.

Parameters:
  • file (str) – path to SQLite database file
  • method (str) – method to determin cite key in db
class biblib.DoiBibDB(method=None)[source]

Bases: biblib._bibdb.StorageBibDB

StorageBibDB that will read entries from doi.org

Parameters:method (str) – method to determin cite key in db
class biblib.IsbnBibDB(method=None)[source]

Bases: biblib._bibdb.StorageBibDB

StorageBibDB that will read entries for given ISBN numbers

Parameters:method (str) – method to determin cite key in db

BibDBCollection

class biblib.BibDBCollection(dbORentries=None, method=None)[source]

Bases: biblib._bibdb.BibDB

datadict

A dictionary containing the citation-keys as keys and the BibTeX Entry objects (Article | Book | …) as values.

addDB(db)[source]
class biblib._bibdb.DBAccessor(dbs=None)[source]

Bases: object

next()[source]
keys()[source]
values()[source]
items()[source]
pop(key)[source]
addDB(db)[source]