Welcome to tammy’s documentation!

tammy is a python module to manage your bibliography in a sane, minimalistic, scriptable, hacker-ish way.

>>> import tammy
>>> lib = tammy.library()
>>> lib.new(tammy.from_crossref_doi('10.7717/peerj.426'))
>>> lib.keys()
['leh14']
>>> lib.records['leh14'].generate_key(tammy.keygen.AuthorYear)
>>> lib.keys()
['Lehiy2014']
>>> lib.new(tammy.from_peerj('403', 'preprint'))
>>> lib.write()

User guide

Introduction

Why tammy?

tammy is a python (2.7) module that allows managing your bibliography in a simple way. I was dissatisfied by all the tools I used, so I decided to build my own. I was looking for a reference manager that...

Can be used programmatically

Being able to manage my references in a programmatic way is important to me, because it means that I can automate a lot of things. Importing, exporting, etc etc. And because tammy is essentially an API to manage bibliographic records, along with a few helper functions, automation is easy.

Works well with unicode

Us Europeans tend to have accents in our names. BibTeX is bad at that, and unicode conversion is in my experience the first source of screw-ups when opening a bib file in different programs. I wanted something that would play nicely with unicode.

Is not based on a database

There were two things I absolutely wanted to avoid: relying on a database, and relying on a single, massive file. I wanted something light, that I can easily manipulate using grep and other nice things if I feel like it. And because there is no reason that a single corrupted record should render your whole database useless, I decided to assign each record to its own file, and build export functions instead.

Integrates in my pandoc-based workflow

I use pandoc and markdown to write papers. pandoc can read bibliogrphy files in citeproc-JSON, so using bibtex as a storage format makes very little sense (see also, unicode).

First steps

This page will show you the very first steps of installing and configuring tammy to your liking.

Installing tammy

Configuration file

At the moment, there is only one configuration option. The configuration file must be stored at $HOME/.tammy.yaml. The bib_dir variable will give the root of your library. By default, this is $HOME/.bib. You can change it with

bib_dir = $HOME/.references

When tammy will read the content of your library, it will go look for configuration options here.

Creating a first library

Whether or not you already have records on the disk, creating a bibliography is as simple as

>>> import tammy
>>> my_lib = tammy.new()

Note that the term creating is misleading: your library won’t be re-created every time; the python objects that allow you to interact with it, on the other hand, will be.

API guide

Classes

Library

class tammy.library
read(force=False)

Read the yaml files from the references folder

This method is called when the library class is instanciated, and it ensures that all records are loaded. Because it calls the new method of the record class, if for some weird reason a file has no id field (e.g. you added it yourself), the key will be generated at this point.

Args:
force: a boolean to force the method to read all files, or only ...
update()

Update the keys in the library dict

This function will loop through all the references, and if the record id do not match with the key in the records dict, it will fix things up. Additionally, this function will rename the file in the references folder.

Record

class tammy.record(library, content)
generate_key(keymaker=<function autYr at 0x7f0f3800d9b0>)

Generates a citation key from the record information

At the moment, citations keys are created as FirstauthorYEAR plus one letter if this is required to make the citation key unique. Note that the citation key is also the filename of the record, so that a record whose key is Doe2004 will be written at Doe2004.yaml.

key()

Outputs the unique citation key for the record

Returns:
a unicode string with the citation key
write()

Writes the content of a record to disk

This will write the content of the record in the records folder of the bib_dir folder. The filename is the unique record key and the .yaml extension.

This method is usually called by library.write(), but it can be used to update the content of any file.

Key generators

Indices and tables