Metadata-Version: 2.4
Name: papis
Version: 0.15.0
Summary: Powerful and highly extensible command-line based document and bibliography manager
Project-URL: Documentation, https://papis.readthedocs.io
Project-URL: Repository, https://github.com/papis/papis
Author-email: Alejandro Gallo <aamsgallo@gmail.com>
Maintainer-email: Alejandro Gallo <aamsgallo@gmail.com>
License: GPL-3.0-or-later
License-File: AUTHORS
License-File: LICENSE
Keywords: biblatex,bibtex,biliography,books,cli,command-line,crossref,datasheets,document,elsevier,ieee,latex,libgen,mathematics,mendeley,papers,physics,pubmed,reference manager,research,science,scihub,tui,zotero
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: arxiv>=1.0.0
Requires-Dist: beautifulsoup4>=4.4.1
Requires-Dist: bibtexparser<2,>=0.6.2
Requires-Dist: click>=7
Requires-Dist: colorama>=0.2
Requires-Dist: dominate>=2.8
Requires-Dist: filetype>=1.0.1
Requires-Dist: habanero>=0.6
Requires-Dist: isbnlib>=3.9.1
Requires-Dist: lxml>=4.3.5
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: prompt-toolkit>=3.0.5
Requires-Dist: pygments>=2.2
Requires-Dist: pyparsing>=3.0
Requires-Dist: python-doi>=0.1.1
Requires-Dist: python-slugify>=1.2.6
Requires-Dist: pyyaml>=3.12
Requires-Dist: requests>=2.11.1
Requires-Dist: setuptools
Provides-Extra: develop
Requires-Dist: mypy>=1.0; extra == 'develop'
Requires-Dist: pytest; extra == 'develop'
Requires-Dist: pytest-cov; extra == 'develop'
Requires-Dist: ruff; extra == 'develop'
Requires-Dist: sphinx-lint; extra == 'develop'
Requires-Dist: types-beautifulsoup4; extra == 'develop'
Requires-Dist: types-docutils; extra == 'develop'
Requires-Dist: types-pygments; extra == 'develop'
Requires-Dist: types-pyyaml; extra == 'develop'
Requires-Dist: types-requests; extra == 'develop'
Provides-Extra: docs
Requires-Dist: pytest; extra == 'docs'
Requires-Dist: sphinx-click; extra == 'docs'
Requires-Dist: sphinx-design; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=1; extra == 'docs'
Requires-Dist: sphinx>=4; extra == 'docs'
Provides-Extra: lint
Requires-Dist: ruff; extra == 'lint'
Requires-Dist: sphinx-lint; extra == 'lint'
Provides-Extra: optional
Requires-Dist: chardet>=3.0.2; extra == 'optional'
Requires-Dist: citeproc-py>=0.6; extra == 'optional'
Requires-Dist: jinja2>=3.0.0; extra == 'optional'
Requires-Dist: markdownify>=1.0.0; extra == 'optional'
Requires-Dist: whoosh>=2.7.4; extra == 'optional'
Provides-Extra: papis-sphinx-ext
Requires-Dist: docutils; extra == 'papis-sphinx-ext'
Requires-Dist: sphinx; extra == 'papis-sphinx-ext'
Requires-Dist: sphinx-click; extra == 'papis-sphinx-ext'
Provides-Extra: papis-testing
Requires-Dist: pytest; extra == 'papis-testing'
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Provides-Extra: typing
Requires-Dist: mypy>=1.0; extra == 'typing'
Requires-Dist: types-beautifulsoup4; extra == 'typing'
Requires-Dist: types-docutils; extra == 'typing'
Requires-Dist: types-pygments; extra == 'typing'
Requires-Dist: types-pyyaml; extra == 'typing'
Requires-Dist: types-requests; extra == 'typing'
Provides-Extra: windows
Requires-Dist: pyinstaller; extra == 'windows'
Description-Content-Type: text/x-rst

Papis
=====

|ghbadge| |RTD| |CodeQL| |Pypi| |zenodo_badge|

Papis is a powerful and highly extensible CLI document and bibliography manager.

|first_glance|

With Papis, you can search your library for books and papers, add documents and
notes, import and export to and from other formats, and much much more. Papis
uses a human-readable and easily hackable ``.yaml`` file to store each entry's
bibliographical data. It strives to be easy to use while providing a wide range
of features. And for those who still want more, Papis makes it easy to write
scripts that extend its features even further.

Features
--------

- **Add documents** and automatically fetch their metadata.
- **Search** by author, title, tags, and so on.
- **Synchronize** your library with whatever software you're already using.
- **Share** your documents with colleagues without having to force some proprietary
  service onto them.
- **Import** your data from other bibliography managers.
- **Export** to BibTeX and other formats.
- **Integrate with your editor** with plugins for (Neo)vim and Emacs.
- **TUIs** make it easy to get a quick overview of your library.
- **Use the web app** when the CLI doesn't quite cut it (for example on your tablet).
- **Hacking** Papis is easy! Use the API to easily create your own custom Python
  scripts.

Quick tour
----------

Install Papis with pip (or `one of the alternatives
<https://papis.readthedocs.io/en/latest/install.html>`__):

.. code:: bash

    pip install papis

Let's download a couple of documents:

.. code:: bash

    wget https://www.gnu.org/s/libc/manual/pdf/libc.pdf
    wget https://www.ams.org/notices/201304/rnoti-p434.pdf

We can now add these to the (default) library. This will automatically query for
the metadata associated with the ``doi``.

.. code:: bash

    papis add --from doi 10.1090/noti963 rnoti-p434.pdf

|add|

You can also use ``--set`` to add information:

.. code:: bash

    papis add libc.pdf --set author "Sandra Loosemore" \
                       --set title "GNU C reference manual" \
                       --set year 2018 \
                       --set tags programming \
                       --confirm

Now open an attached file or edit an entry:

.. code:: bash

    papis open
    papis edit


|edit|

The Papis picker (set using the ``picktool`` configuration option) has
helpful shortcuts to call other functionality as well (press ``F1`` for
a complete list). It can be used to open (``Ctrl-o``), browse (``Ctrl-b``)
or edit (``Ctrl-e``) selected documents (marked with ``Ctrl-t``).

Import your bibliography into Papis from BibTeX:

.. code:: bash

    papis bibtex read mylib.bib import --all

Or export it to BibTeX:

.. code:: bash

    papis export --all --format bibtex > mylib.bib

|bibtex_export|

Papis also includes a web app that you can start with:

.. code:: bash

    papis serve

You can then open the indicated address (``http://localhost:8888``) in your
browser.

|web_app|

All ``papis`` commands come with help messages:

.. code:: bash

    papis -h      # General help
    papis add -h  # Help with a specific command

Installation & setup
--------------------

Information about installation and setup can be found in the
`docs <https://papis.readthedocs.io/en/latest/>`__, for example in the these sections:

- `Installation <https://papis.readthedocs.io/en/latest/install.html>`__
- `Configuration <https://papis.readthedocs.io/en/latest/configuration.html>`__
- `Import <https://papis.readthedocs.io/en/latest/importing.html>`__
- `Editor integration <https://papis.readthedocs.io/en/latest/editors.html>`__

Questions?
----------

The `docs <https://papis.readthedocs.io/en/latest/>`__ cover Papis' features and
discuss possible work flows. If you still have questions, head to our
`GitHub discussions <https://github.com/papis/papis/discussions>`__ — we're
more than happy to help. If you've found a bug, please
`open an issue <https://github.com/papis/papis/issues>`__ and help make Papis
even better!

If you're not finding a command or configuration value that shows up in the
documentation in your local installation, you may just be looking at the wrong
docs. You can find the documentation for the latest *released* version
`here <https://papis.readthedocs.io/en/stable/>`__ and the documentation for
the *in-development* version `here <https://papis.readthedocs.io/en/latest/>`__.

Reviews and blog posts
----------------------

- `Blog post
  <https://alejandrogallo.github.io/blog/posts/getting-paper-references-with-papis/>`__
  about getting a paper's references with ``papis explore``.
- `Blog post
  <https://web.archive.org/web/20250428103318/https://nicolasshu.com/zotero_and_papis.html>`__
  about using Papis with Zotero and Syncthing.
- GNU/Linux Switzerland `wrote about Papis
  <https://gnulinux.ch/papis-dokumentenverwaltung-fuer-die-kommandozeile>`__
  *(in German)*.
- The folks at OSTechNix wrote a review of `Papis
  <https://www.ostechnix.com/papis-command-line-based-document-bibliography-manager>`__.
- A `review of Papis <https://ubunlog.com/papis-administrador-documentos/>`__
  by Ubunlog *(in Spanish)*.

Contributing
------------

Contributions are very welcome! Take a look at
`CONTRIBUTING.md <https://github.com/papis/papis/blob/main/CONTRIBUTING.md>`__ for
general rules and `HACKING.md <https://github.com/papis/papis/blob/main/HACKING.md>`__
for additional code-related information. We encourage you to also check out,
contribute to, or even help maintain the other projects in the Papis ecosystem
mentioned below 😉.

The Papis ecosystem
-------------------

Papis has grown over the years and there are now a number of projects that
extend Papis' features or integrate it with other software.

.. list-table::
   :widths: 33 67
   :header-rows: 1

   * - Project
     - Maintained by

   * - `papis (core) <https://github.com/papis/papis-rofi/>`__
     - `Alejandro Gallo <https://alejandrogallo.github.io/>`__,
       `Julian Hauser <https://github.com/jghauser>`__,
       `Alex Fikl <https://github.com/alexfikl>`__

   * - `papis-rofi <https://github.com/papis/papis-rofi/>`__
     - `Etn40ff <https://github.com/Etn40ff>`__

   * - `papis-dmenu <https://github.com/papis/papis-dmenu>`__
     - you?

   * - `papis-vim <https://github.com/papis/papis-vim>`__
     - you?

   * - `papis.nvim <https://github.com/jghauser/papis.nvim>`__
     - `Julian Hauser <https://github.com/jghauser>`__

   * - `papis-emacs <https://github.com/papis/papis.el>`__
     - `Alejandro Gallo <https://alejandrogallo.github.io/>`__,
       `Jean-Alexandre Barszcz <https://jabarsz.cz/en/home>`__

   * - `papis-zotero <https://github.com/papis/papis-zotero>`__
     - `Alex Fikl <https://github.com/alexfikl>`__

   * - `papis-libgen <https://github.com/papis/papis-zotero>`__
     - you?

   * - `papis-firefox <https://github.com/papis/papis-firefox>`__
     - `wavefrontshaping <https://github.com/wavefrontshaping>`__
   * - `papis-ask <https://github.com/jghauser/papis-ask>`__ (AI for Papis)
     - `Julian Hauser <https://github.com/jghauser>`__

Related software
----------------

Papis isn't the only fish in the pond. You might also be interested in:

- `bibman <https://codeberg.org/KMIJPH/bibman>`__ (open source)
- `bibiman <https://codeberg.org/lukeflo/bibiman>`__ (open source)
- `cobib <https://github.com/mrossinek/cobib>`__ (open source)
- `jabref <https://www.jabref.org/>`__ (open source)
- `Mendeley <https://www.mendeley.com/>`__ (proprietary)
- `pubs <https://github.com/pubs/pubs/>`__ (open source)
- `Xapers <https://finestructure.net/xapers/>`__ (open source)
- `Zotero <https://www.zotero.org/>`__ (open source)


Thanks
------

We thank `Irteza Rehman <https://www.irtezarehman.com/>`__ for generously creating
our beautiful logo.

.. |ghbadge| image:: https://github.com/papis/papis/workflows/CI/badge.svg
   :target: https://github.com/papis/papis/actions?query=branch%3Amain+workflow%3ACI
.. |RTD| image:: https://readthedocs.org/projects/papis/badge/?version=latest
   :target: http://papis.readthedocs.io/en/latest/?badge=latest
.. |CodeQL| image:: https://github.com/papis/papis/workflows/CodeQL/badge.svg
   :target: https://github.com/papis/papis/actions?query=branch%3Amain+workflow%3ACodeQL
.. |Pypi| image:: https://badge.fury.io/py/papis.svg
   :target: https://pypi.org/project/papis/
.. |zenodo_badge| image:: https://zenodo.org/badge/82691622.svg
   :target: https://zenodo.org/badge/latestdoi/82691622

.. |first_glance| image:: https://papis.github.io/images/first_glance.gif
.. |edit| image:: https://papis.github.io/images/edit.gif
.. |bibtex_export| image:: https://papis.github.io/images/bibtex_export.gif
.. |add| image:: https://papis.github.io/images/add.gif
.. |web_app| image:: https://papis.github.io/images/web_app.jpg
