PAPIS(1)

NAME
papis - Papis Documentation

Papis is a command-line based document and bibliography manager. Its command-line interface (CLI) is heavily tailored after Git.

QUICK START

This is a tutorial that should be enough to get you started using papis. Papis tries to be as simple and lightweight as possible, therefore its database structure is ridiculously simple.

But before taking a look at its database structure let us see how is the daily usage of papis for a regular user. This tutorial is command-line based, so you should be familiar with opening a terminal window in your system.

  Creating a new library

We will illustrate the process by creating a first library with a couple of `pdf` documents in it. Papis can be highly configured using configuration files. Many programs use configuration files without you maybe being aware of it. Papis’ configuration files are stored together inside the folder

~/.papis

Bear in mind that ~ means “Home Directory”. Inside this directory a configuration file is found,

~/.papis/config

Right now we will open this file to edit and we will create a library. In papis everything should be human-readabale and human-editable. So adding a library is as easy as adding two lines to this configuration file.

Say that you want to create a “papers” library, where you can finally order all those pdf’s hanging around in your computer. We can create this library by putting inside the config file the two lines:

[papers]
dir = ~/Documents/mypapers

In the above lines we have created a library with the name papers which is located in the directory ~/Documents/mypapers. So all the documents that we will be adding to the library will be located inside ~/Documents/mypapers, and nowhere else. Everything that papis needs to take care of your papers library is inside the ~/Documents/mypapers directory, self-contained.

So now add the two lines to the ~/.papis/config file and save it, and we will proceed to add some documents.

  Adding the first document

If you don’t have any special pdf lying around let me choose one for you: link. You can download this document and we are going to add it into the papers library.

Supposing that you have the document in the current directory and you have renamed the document to document.pdf, you can do the following to add this into your library:

papis add document.pdf --author "Newton" --title "Principia Mathematica"

And it’s done! We have added our first book to the library.

Let us see how this works exactly. Papis consists of many commands, and one of these commands is add. Add itself has many flags, which are options for the given command. In the example above we have used the flags author and title to tell papis to use Newton as the author’s name and Principia Mathematica as the document’s title. You can see all the posible flags for the command add if you use the help flag, i.e., if you issue the following command

papis add --help

Now you are asking yourself, what happened to the pdf file? Where it is stored? Is it stored in an obscure database somewhere in my computer? No, papis just copied the document.pdf file into a folder inside the library folder ~/Documents/papers/. If you go now there, you will see that a folder with a weird name has been created. Inside of the folder there is the document.pdf file and another file, info.yaml.

If you open the info.yaml file you will see the following contents:

author: Newton
title: Principia Mathematica
files:
- document.pdf

This file is all that papis uses to store the information of your newly added document. It is stored in a nicely readable yaml format.

Now you already have your first document, and.. you can open it! Just do

papis open

and the document should just open in your default pdf viewer. You can change the default pdf viewer in your configuration file (see section on configuration-file).

Now you can try to repeat the same process with another pdf file lying around. When you hit papis open again, it will ask you which one you want. If you input parts of the title or the author’s name it will try to match what you typed with the paper you are looking for, so that you can get the paper that you are looking for very easily.

Nice Reading!!

INSTALLATION

  Using pip

The easiest way of installing papis is using the PyPi repositories and the package manager pip3, just open a terminal and type in

pip3 install papis

If you are on GNU/Linux like systems you might need to type sudo

sudo pip3 install papis

of if you prefer installing it locally then simply type

pip3 install --user papis

  From source

First of all you have to get the code, open a terminal and hit

git clone https://github.com/alejandrogallo/papis.git

or download the zip file.

Go inside of the papis source folder and you can either use the Makefile or install it with python3.

  Using the Makefile

If you want to install it globally, just hit

sudo make install

If you want to install it locally:

make install-local

If you want to install it locally and have the development version:

make install-dev-local

And to see the available targets hit:

make help

  Using python3

The general command that you have to hit is by using the setup.py script:

python3 setup.py install

Again, if you want to install it locally because you don’t have administrative rights in your computer you can just simply type

python3 setup.py install --user

If you want to develop on the code, you can also alternatively hit

python3 setup.py develop --user

WARNING: If you install the package locally, the program papis will be installed by default into your ~/.local/bin direcrtory, so that you will have to set your PATH accordingly.

One way of doing this in bash shells (Linux and the like, also Ubuntu on Windows or cygwin) is by adding the following line to your ~/.bashrc file

export PATH=$PATH:$HOME/.local/bin

  Requirements

Papis needs the following packages that are sometimes not installed with the system python3 distribution

python3-ncurses
python3-setuptools

However if you have a general enough python distribution they should be installed.

CONFIGURATION FILE

Papis uses a configuration file in INI format. You can then have several libraries which work independently from each other.

For example, maybe you want to have one library for papers and the other for some miscellaneous documents. An example for that is given below

[papers]
dir = ~/Documents/papers
[settings]
editor = vim
default-library = papers
[books]
dir = ~/Documents/books

A more complete example of a configuration file is the following

[settings]
# Open file with rifle, a nice python program
opentool = rifle
# Use gvim as a graphical editor
xeditor = gvim
# Use ranger as a file browser, too a  nice python package
file-browser = ranger
# Ask for confirmation when doing papis add ...
add-confirm = True
# Edit the info.yaml file before adding a doc into the library
# papis add --edit
add-edit = True
# Open the files before adding a document into the library
# papis add --open
add-open = True
# Define custom default match and header formats
match-format = {doc[tags]}{doc.subfolder}{doc[title]}{doc[author]}{doc[year]}
header-format = > {doc[title]:<70.70}|{doc[author]:<20.20} ({doc[year]:-<4})
# Commands that will be run when one does papis run ...
# e.g., papis run gagp will run the command below in the library folder
gagp = git commit -a && git push origin master
gs = git status
gm = git commit
gp = git push
gu = git pull
gma = git commit -a
# Define a lib
[papers]
dir = ~/Documents/papers
# Define a lib for books
[books]
dir = ~/Documents/books
# Define a lib for Videos
[videos]
dir = ~/Videos/courses
# Define a lib for contacts, why not?
# To make it work you just have to define some default settings
[contacts]
dir = ~/contacts/general
mode = contact
header-format = {doc[first_name]} {doc[last_name]}
match-format = {doc[org]} {doc[first_name]} {doc[last_name]}
browse-query-format = {doc[first_name]} {doc[last_name]}
add-open = False
rofi-gui-gui-eh = 2
rofi-gui-header-format = %(header-format)s
                     {doc[tel][cell]}
tk-gui-header-format = %(rofi-gui-header-format)s
vim-gui-header-format = Title: %(header-format)s
                        Tel  : {doc[tel]}
                        Mail : {doc[email]}
                     {doc[empty]}

  Default settings

  settings

add-confirm
    Default: False

add-edit
    Default: False

add-interactive
    Default: False

add-open
    Default: False

browse-query-format
    Default: {doc[title]} {doc[author]}

browser
    Default: xdg-open

cache-dir
    Default: /home/gallo/.cache/papis

check-keys
    Default: files

default-gui
    Default: vim

default-library
    Default: papers

    Library to be open if no library has not been explicitly selected.

doc-url-key-name
    Default: doc_url

editor
    Default: vim

export-text-format
    Default: {doc[author]}. {doc[title]}. {doc[journal]} {doc[pages]} {doc[month]} {doc[year]}

file-browser
    Default: xdg-open

format-doc-name
    Default: doc

header-format
    Default: {doc[title]:<70.70}|{doc[author]:<20.20} ({doc[year]:-<4})

info-name
    Default: info.yaml

match-format
    Default: {doc[tags]}{doc.subfolder}{doc[title]}{doc[author]}{doc[year]}

mode
    Default: document

mvtool
    Default: mv

notes-name
    Default: notes.tex

opentool
    Default: xdg-open

picktool
    Default: papis.pick

scripts-short-help-regex
    Default: .*papis-short-help: *(.*)

search-engine
    Default: https://duckduckgo.com

sync-command
    Default: git -C $dir pull origin master

use-cache
    Default: True

use-git
    Default: False

user-agent
    Default: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/35.0.1916.47 Safari/537.36

xeditor
    Default: xdg-open

  tk-gui

activebackground
    Default: #394249

activeforeground
    Default: gray99

borderwidth
    Default: -1

clear
    Default: q

cursor
    Default: xterm

edit
    Default: e

entry-bg-odd
    Default: #273238

entry-bg-pair
    Default: #273238

entry-bg-size
    Default: 14

entry-fg
    Default: grey77

entry-font-name
    Default: Times

entry-font-size
    Default: 14

entry-font-style
    Default: normal

entry-lines
    Default: 3

exit
    Default: <Control-q>

focus_prompt
    Default: :

half_down
    Default: <Control-d>

half_up
    Default: <Control-u>

header-format

Default:

    {doc[title]}
    {doc[empty]}   {doc[author]}
    ({doc[year]:->4})

height
    Default: 1

help
    Default: h

insertbackground
    Default: red

labels-per-page
    Default: 6

match-format
    Default: {doc[tags]}{doc.subfolder}{doc[title]}{doc[author]}{doc[year]}

move_bottom
    Default: <Shift-G>

move_down
    Default: j

move_top
    Default: g

move_up
    Default: k

open
    Default: o

print_info
    Default: i

prompt-bg
    Default: black

prompt-fg
    Default: lightgreen

prompt-font-size
    Default: 14

scroll_down
    Default: <Control-e>

scroll_up
    Default: <Control-y>

window-bg
    Default: #273238

window-height
    Default: 700

window-width
    Default: 1200

  rofi-gui

case_sensitive
    Default: False

eh  Default: 3

fixed_lines
    Default: 20

fullscreen
    Default: False

header-format

Default:

    <b>{doc[title]}</b>
    {doc[empty]}  <i>{doc[author]}</i>
    {doc[empty]}  <span foreground="red">({doc[year]:->4})</span><span foreground="green">{doc[tags]}</span>

key-browse
    Default: Alt+u

key-delete
    Default: Alt+d

key-edit
    Default: Alt+e

key-help
    Default: Alt+h

key-normal-window
    Default: Alt+w

key-open
    Default: Enter

key-open-stay
    Default: Alt+o

key-quit
    Default: Alt+q

lines
    Default: 10

markup_rows
    Default: True

multi_select
    Default: True

normal_window
    Default: False

sep Default: |

width
    Default: 80

  vim-gui

delete-key
    Default: dd

edit-key
    Default: e

header-format

Default:

    Title : {doc[title]}
    Author: {doc[author]}
    Year  : {doc[year]}
    -------

help-key
    Default: h

next-search-key
    Default: n

open-dir-key
    Default: <S-o>

open-key
    Default: o

prev-search-key
    Default: N

search-key
    Default: /

THE INFO.YAML FILE

At the heart of papis there is the information file. The info file contains all information about the documents.

THE DATABASE

One of the things that makes papis interesting is the fact that its database is no database.

A papis library is linked to a directory, where all the documents are (and possibly sublibraries). What papis does is simply to go to the library folder and look for all subfolders that contain a information file, which by default is a info.yaml file.

Every subfolder that has an info.yaml file in it is a valid papis document. As an example let us consider the following library

/home/fulano/Documents/papers/
├── folder1
│   └── paper.pdf
├── folder2
│   ├── folder3
│   │   ├── info.yaml
│   │   └── blahblahblah.pdf
│   └── folder4
│       ├── info.yaml
│       └── output.pdf
├── classics
│   └── folder5
│       ├── info.yaml
│       └── output.pdf
├── physics
│   └── newton
│       └── principia
│           ├── document.pdf
│           ├── supplements.pdf
│           └── info.yaml
└─── rpa
    └── bohm
        ├── info.yaml
        ├── notes.tex
        └── output.pdf

The first thing that you might notice is that there are really many folders of course. Just to check that you undeerstand exactly what is a document, just please think about which of these pdfs is not a valid papis document… That’s right!, folder1/paper.pdf is not a valid document since the folder1 does not contain any info.yaml file. You see also that it does not matter how deep the folder structure is, you can have in your library a physics folder, where you have a newton folder, where also you have a folder containing the actual book document.pdf plus some supplementary information supplements.pdf. In this case inside the info.yaml you would have the following file section

files:
- document.pdf
- supplements.pdf

so that you are telling papis that in this folder there are two relevant files.

  Cache system

The fact that there is no database means that papis should crawl through the library folder and see which folders have an info.yaml file, which is for slow computers quite bad.

Papis implements a very rudimentary caching system. A cache is created for every library. Inside the cache only the paths to the different valid papis documents is stored. These cache files are stored in

~/.papis/cache

Some papis commands clear the cache automatically, for example the add and rm command clear the cache when something is changed.

  Disabling the cache

You can disable the cache using the configuration setting use-cache and set it to False, e.g.

[settings]
use-cache = False
[books]
# Use cache for books but don't use for the rest of libraries
use-cache = True

COMMANDS

  Add

usage: papis add [-h] [-d DIR] [-i] [--name NAME] [--title TITLE]
                 [--author AUTHOR] [--from-bibtex FROM_BIBTEX]
                 [--from-yaml FROM_YAML] [--from-url FROM_URL]
                 [--from-doi FROM_DOI] [--from-vcf FROM_VCF] [--to [TO]]
                 [--confirm] [--open] [--edit] [--commit] [--no-document]
                 [document [document ...]]

  Positional Arguments

Document file name

    Default: []

  Named Arguments

Subfolder in the library

    Default: “”

Do some of the actions interactively

    Default: False

Name for the main folder

    Default: “”

Title for document

    Default: “”

Author(s) for document

    Default: “”

Parse information from a bibtex file

    Default: “”

Parse information from a yaml file

    Default: “”

Get document and information from agiven url, a parser must be implemented

    Default: “”

Doi to try to get information from

Get contact information from a vcard (.vcf) file

When –to is specified, the document will be added to theselected already existing document entry.

Ask to confirm before adding to the collection

    Default: True

Open file before adding document

    Default: True

Edit info file before adding document

    Default: True

Commit document if library is a git repository

    Default: False

Add entry without a document related to it

    Default: False

  Open

usage: papis open [-h] [--tool TOOL] [-d] [search]

  Positional Arguments

Search query string

    Default: “.”

  Named Arguments

Tool for opening the file (opentool)

    Default: “”

Open directory

    Default: False

  Edit

usage: papis edit [-h] [-n] [search]

  Positional Arguments

Search query string

    Default: “.”

  Named Arguments

Open notes document

    Default: False

  Export

usage: papis export [-h] [--yaml] [--bibtex] [--folder] [--no-bibtex] [-o OUT]
                    [-t] [-a] [--vcf]
                    [search]

  Positional Arguments

Search query string

    Default: “.”

  Named Arguments

Export into bibtex

    Default: False

Export into bibtex

    Default: False

Export document folder to share

    Default: False

When exporting to a folder, do not include the bibtex

    Default: False

Outfile or outdir

    Default: “”

Text formated reference

    Default: False

Export all without picking

    Default: False

Export contact to vcf format

    Default: False

  Explore

usage: papis explore [-h] [--arxiv] [--max MAX] [search [search ...]]

  Positional Arguments

Search string

    Default: []

  Named Arguments

Search on the arxiv

    Default: False

Maximum number of items

    Default: 30

  Remove

usage: papis rm [-h] [-f] [search]

  Positional Arguments

Search query string

    Default: “.”

  Named Arguments

Do not confirm removal

    Default: False

  Gui

usage: papis gui [-h] [--tk] [--rofi] [--vim]

  Named Arguments

Tk based UI

    Default: False

Rofi based UI

    Default: False

Vim based UI

    Default: False

  List

This command is to list contents of a library.

  Examples

•   List all document files associated will all entries:

    papis list --file

•   List all document year and title with custom formatting:

    papis list --format '{doc[year]} {doc[title]}'

•   List all documents according to the bibitem formatting (stored in a template file bibitem.template):

    papis list --template bibitem.template

    usage: papis list [-h] [-i] [-f] [-d] [--format FORMAT] [--template TEMPLATE]
                      [-p] [--downloaders]
                      [search]

  Positional Arguments

Search query string

    Default: “.”

  Named Arguments

Show the info file name associated with the document

    Default: False

Show the file name associated with the document

    Default: False

Show the folder name associated with the document

    Default: False

List entries using a custom papis format, e.g. ‘{doc[year] {doc[title]}

Template file containing a papis format to list entries

Pick the document instead of listing everything

    Default: False

List available downloaders

    Default: False

  Browse

This command will try its best to find a source in the internet for the document at hand.

Of course if the document has an url key in its info file, it will use this url to open it in a browser. Also if it has a doc_url key, or a doi, it will try to compose urls out of these to open it.

If none of the above work, then it will try to use a search engine with the document’s information (using the browse-query-format). You can select wich search engine you want to use using the search-engine setting.

usage: papis browse [-h] [search]

  Positional Arguments

Search query string

    Default: “.”

  Git

usage: papis git [-h] commands [commands ...]

  Positional Arguments

Commands

    Default: “”

CUSTOM SCRIPTS

As in git, you can write custom scripts to include them in the command spectrum of papis.

  Example: Mail script

Imagine you want to write a script to send papers to someone via the email client mutt (you can try to do it with another mail client), you could write the following script called papis-mail:

#! /usr/bin/env bash
# papis-short-help: Email a paper to my friend
folder_name=$1
zip_name="${folder_name}.zip"
papis -l ${PAPIS_LIB} export --folder --out ${folder_name}
zip -r ${zip_name} ${folder_name}
mutt -a ${zip_name}

Papis defines environment variables such as PAPIS_LIB so that external scripts can make use of the user input.

To use the script you can put it somewhere in your PATH or alternatively inside the ~/.papis/scripts folder. If this is the case then you can run

papis -h

and you will see that there is another command besides the default called mail. You will see in fact

positional arguments:
  command               For further information for every command, type in 'papis <command> -h'
    add                 Add a document into a given library
    .............       ..........................
    mail                Email a paper to my friend
optional arguments:
  -h, --help            show this help message and exit
  ... .........         .... ... ...... ....... ........... .. ..... ......

where the description Email a paper to my friend is there because we have defined the comment # papis-short-help: Email a paper to my friend in the header of the script.

Then if you type

papis -l mylib mail this_paper

this will create a folder called this_paper with a selection of a document, zip it, and send it to whoever you choose to.

API

This module describes which functions are intended to be used by users to create papis scripts.

papis.api.clear_lib_cache(lib=None)
    Clear cache associated with a library. If no library is given then the current library is used.

Parameters
    lib (str) – Library name.

papis.api.edit_file(file_path)
    Edit file using the editor key value as a program to handle file_path.

Parameters
    file_path (str) – File path to be handled.

papis.api.get_documents_in_dir(directory, search='')
    Get documents contained in the given folder with possibly a search string.

Parameters

•   directory (str) – Folder path.

•   search (str) – Search string

Returns
    List of filtered documents.

Return type
    list

    >>> docs = get_documents_in_dir('non/existent/path')
    >>> len(docs)
    0

papis.api.get_documents_in_lib(library=None, search='')
    Get documents contained in the given library with possibly a search string.

Parameters

•   library (str) – Library name.

•   search (str) – Search string

Returns
    List of filtered documents.

Return type
    list

papis.api.get_lib()
    Get current library, it either retrieves the library from the environment PAPIS_LIB variable or from the command line args passed by the user.

Returns
    Library name

Return type
    str

    >>> get_lib() == papis.config.get_default_settings(key='default-library')
    True
    >>> set_lib('books')
    >>> get_lib()
    'books'

papis.api.get_libraries()
    Get all libraries declared in the configuration. A library is discovered if the dir key defined in the library section.

Returns
    List of library names

Return type
    list

papis.api.open_dir(dir_path)
    Open dir using the file-browser key value as a program to open dir_path.

Parameters
    dir_path (str) – Folder path to be handled.

papis.api.open_file(file_path)
    Open file using the opentool key value as a program to handle file_path.

Parameters
    file_path (str) – File path to be handled.

papis.api.pick(options, pick_config={})
    This is a wrapper for the various pickers that are supported. Depending on the configuration different selectors or ‘pickers’ are used.

Parameters

•   options (list) – List of different objects. The type of the objects within the list must be supported by the pickers. This is the reason why this function is difficult to generalize for external picker programs.

•   pick_config (dict) – Dictionary with additional configuration for the used picker. This depends on the picker.

Returns
    Returns elements of options.

Return type
    Element(s) of options

    >>> papis.config.set('picktool', 'papis.pick')
    >>> pick(['something'])
    'something'

papis.api.set_lib(library)
    Set current library, it either sets the library in the environment PAPIS_LIB variable or in the command line args passed by the user.

Parameters
    library (str) – Name of library or path to a given library

•   genindex

•   modindex

•   search

AUTHOR
Alejandro Gallo

COPYRIGHT
2017, Alejandro Gallo