
 
**biblib** is a (pure) python library that provides several useful classes, methods and functions to work with
BibTeX bibliographic data within your python scripts.

The idea is to enabling you to prepare *your own tools*, which are specifically tailored
to *your own literature investigation scheme*, comfortably.


Usage example
=============

The following code will read the file into a db, fetch an entry by its DOI and save the db to a new file:

.. code-block:: py

    import biblib

    # open file as filedb in read only mode
    fileDb = biblib.FileBibDB('bibtex.bib', mode='r')

    # open file as db read/write mode,
    # no LaTeX encoding of unicode character
    newFileDb = biblib.FileBibDB('new.bib', encode=False)

    # add fileDb entries to newFileDb
    newFileDb.merge_bibdb(fileDb)

    # access an entry object refered by its cite-key
    entry = newFileDb['JCP-127-234509']
    entry.get_tag('year')
    > 2007

    # init doi db
    doiDb = biblib.DoiBibDB()

    # retrieve bibliographic meta data by DOI
    entry = doiDb['10.1088/0959-5309/43/5/301']

    # add new entries to database
    newFileDb.add_entry(entry)
    # or this way to set a specific cite-key
    # newFileDb['MY_CITE_KEY'] = entry1


If you don't use biblib in a bigger context (i.e. from the command line) you can use the helper functions for the fast and easy way:

.. code-block:: py

    from biblib import db_from_file, entry_from_doi, db_to_file

    db = db_from_file('bibtex.bib')
    entry = entry_from_doi('10.1088/0959-5309/43/5/301')
    db.add_entry(entry)
    db_to_file(db, 'new.bib', encode=False)


Requirements
============

* Python 2.7, 3.3+
* `pybtex`_ for BibTeX parsing
* `isbnlib`_ for retrieving citation entries via ISBN number
* `python-magic`_ for detecting character encoding
* `unidecode`_ for robust generation of citation-keys


Installation
============

You can install the latest version from the `Python package index`_.
From the command line, enter (in some cases you have to precede the command with **sudo**):


.. code-block:: bash

	$ pip install biblib



More information about the usage and how to get and install ``pip`` you find in the `PIP documentation`_.

To install it manual, `download`_ the archive, unpack it, and type
(in some cases you have to precede the command with **sudo**):


.. code-block:: bash

	$ python setup.py install



Documentation
=============

Documentation including installation procedure, tutorial and API:
http://wgserve.de/biblib/


Thanks
======

Thanks to `Jackalope`_ for his support while planing and designing *biblib*,
and for his contribution of the *Storage* concept.


.. _Python package index: https://pypi.python.org/pypi
.. _download: https://pypi.python.org/pypi/biblib
.. _isbnlib: https://pypi.python.org/pypi/isbnlib
.. _python-magic: https://pypi.python.org/pypi/python-magic
.. _Jackalope: http://www.jackalope.eu
.. _pybtex: https://pypi.python.org/pypi/pybtex
.. _unidecode: https://pypi.python.org/pypi/Unidecode
.. _PIP documentation: https://pip.pypa.io/en/stable/#

