| Name | papers-cli JSON |
| Version |
2.4
JSON |
| download |
| home_page | |
| Summary | utilities to keep your PDF library organized |
| upload_time | 2023-04-28 01:50:51 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.7 |
| license | MIT |
| keywords |
bibtex
references
bibliography
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://github.com/perrette/papers/actions)
[]()
[]()
[]()
[]()
# papers
Command-line tool to manage bibliography (pdfs + bibtex)
Disclaimer: This tool requires further development and testing, and might never be fully production-ready (contributors welcome). \
That said, it is becoming useful :)
## Motivation
This project is an attempt to create a light-weight,
command-line bibliography managenent tool. Aims:
- maintain a PDF library (with appropriate naming)
- maintain one or several bibtex-compatible collections, linked to PDFs
- enough PDF-parsing capability to fetch metadata from the internet (i.e. [crossref](https://github.com/CrossRef/rest-api-doc) or google-scholar)
## Dependencies
- python 3.8+
- [poppler-utils](https://en.wikipedia.org/wiki/Poppler_(software)) (only:`pdftotext`): convert PDF to text for parsing
- [bibtexparser](https://bibtexparser.readthedocs.io) : parse bibtex files
- [crossrefapi](https://github.com/fabiobatalha/crossrefapi) : make polite requests to crossref API
- [scholarly](https://github.com/OrganicIrradiation/scholarly) : interface for google scholar
- [rapidfuzz](https://github.com/rhasspy/rapidfuzz) : calculate score to sort crossref requests
- [unidecode](https://github.com/avian2/unidecode) : replace unicode with ascii equivalent
## Install
- `pip install papers-cli`
- install third-party dependencies (Ubuntu: `sudo apt install poppler-utils`)
Note there is another project registered on pypi as papers, hence `papers-cli` for command-line-interface.
## Getting started
This tool's interface is built like `git`, with main command `papers` and a range of subcommands.
### Extract PDF metadata and add to library
Start with PDF of your choice (modern enough to have a DOI, e.g. anything from the Copernicus publications).
For the sake of the example, one of my owns: https://www.earth-syst-dynam.net/4/11/2013/esd-4-11-2013.pdf
- extract pdf metadata (doi-based if available, otherwise crossref, or google scholar if so specified)
$> papers extract esd-4-11-2013.pdf
@article{Perrette_2013,
doi = {10.5194/esd-4-11-2013},
url = {https://doi.org/10.5194%2Fesd-4-11-2013},
year = 2013,
month = {jan},
publisher = {Copernicus {GmbH}},
volume = {4},
number = {1},
pages = {11--29},
author = {M. Perrette and F. Landerer and R. Riva and K. Frieler and M. Meinshausen},
title = {A scaling approach to project regional sea level rise and its uncertainties},
journal = {Earth System Dynamics}
}
- add pdf to `papers.bib` library, and rename a copy of it in a files directory `files`.
$> papers add esd-4-11-2013.pdf --rename --copy --bibtex papers.bib --filesdir files --info
INFO:papers:found doi:10.5194/esd-4-11-2013
INFO:papers:new entry: perrette_landerer2013
INFO:papers:mv /home/perrette/playground/papers/esd-4-11-2013.pdf files/perrette_et_al_2013_a-scaling-approach-to-project-regional-sea-level-rise-and-its-uncertainties.pdf
INFO:papers:renamed file(s): 1
(the `--info` argument asks for the above output information to be printed out to the terminal)
That is equivalent to doing:
papers extract esd-4-11-2013.pdf > entry.bib
papers add entry.bib --bibtex papers.bib --attachment esd-4-11-2013.pdf --rename --copy
See [Control fields when renaming file](#control-fields-when-renaming-file) for how to specify file naming patterns.
### Add library entry from its DOI
If you already know the DOI of a PDF, and don't want to gamble the fulltext search and match, you can indicate it via `--doi`:
papers add esd-4-11-2013.pdf --doi 10.5194/esd-4-11-2013 --bibtex papers.bib
The `add` command above also works without any PDF (create a bibtex entry without file attachment).
papers add --doi 10.5194/esd-4-11-2013 --bibtex papers.bib
### List entries (and edit etc...)
Pretty listing (-1 or -l for one-liner listing, otherwise plain bibtex):
$> papers list -1
Perrette2013: A scaling approach to project regional sea level rise and it... (doi:10.5194/esd-4-11-2013, file:1)
Search with any number of keywords:
$> papers list perrette scaling approach sea level -1
... (short list)
$> papers list perrette scaling approach sea level --any -1
... (long list)
$> papers list --key perrette2013 --author perrette --year 2013 --title scaling approach sea level -1
... (precise list)
Add tags to view papers by topic:
$> papers list perrette2013 --add-tag sea-level projections -1
...
$> papers list --tag sea-level projections -1
Perrette2013: A scaling approach to project regional sea level rise and it... (doi:10.5194/esd-4-11-2013, file:1, sea-level | projections )
`papers list` is a powerful command, inspired from unix's `find` and `grep`.
It lets you search in your bibtex in a typical manner (including a number of special flags such as `--duplicates`, `--review-required`, `--broken-file`...),
then output the result in a number of formats (one-liner, raw bibtex, keys-only, selected fields) or let you perform actions on it (currently `--edit`, `--delete`, `--add-tag`, `--fetch`).
For instance, it is possible to manually merge the duplicates with:
$> papers list --duplicates --edit
### Control fields when renaming file
$> papers add --rename --info --name-template "{AuthorX}{year}-{Title}" --name-title-sep '' --name-author-sep '' esd-4-11-2013
INFO:papers:found doi:10.5194/esd-4-11-2013
INFO:papers:new entry: perrette2013scaling
INFO:papers:create directory: files/2013
INFO:papers:mv /home/perrette/playground/papers/esd-4-11-2013.pdf files/PerretteEtAl2013-AScalingApproachToProjectRegionalSeaLevelRiseAndItsUncertainties.pdf
INFO:papers:renamed file(s): 1
where '--name-template' is a python template (will be formated via .format() method) with valid fields being any field available in the bibtex. Fields not in the bibtex will remain untouched.
To rename `esd-4-11-2013.pdf` as `perrette_2013.pdf`, the template should be `--name-template {author}_{year} --name-author-num 1`
If that happens to be the entry ID, `ID` also works.
To `rename esd-4-11-2013.pdf` as `2013/Perrette2013-AScalingApproachToProjectRegionalSeaLevelRiseAndItsUncertainties.pdf`,
name-template should be `--name-template {year}/{Author}{year}-{Title} --name-title-sep ''` (note the case).
Entries are case-sensitive, and a few more fields are added, so that:
- 'author' generates 'perrette'
- 'Author' generates 'Perrette'
- 'AUTHOR' generates 'PERRETTE'
- 'authorX' generates 'perrette', 'perrette_and_landerer' or 'perrette_et_al' dependening on the number of authors
- 'AuthorX' same as authorX but capitalized
The modifiers are:
- `--name-title-sep` : separator for title words
- `--name-title-length` : max title length
- `--name-title-word-size` : min size to be considered a word
- `--name-title-word-num` : max number of title words
and similarly:
- `--name-author-sep` : separator for authors
- `--name-author-num` : number of authors to (not relevant for `{authorX}`)
The same template and modifiers system applies to the bibtex key generation by replacing the prefix `--name-` with `--key-`, e.g. `--key-template`
In the common case where the bibtex (`--bibtex`), files directory (`--filesdir`), and name and key formats (e.g. `--name-template`) do not change, it is convenient to
(install)[#install-make-bibtex-and-files-directory-persistent] `papers`.
### install: make bibtex and files directory persistent
$> papers install --bibtex papers.bib --filesdir files
papers configuration
* configuration file: /home/perrette/.config/papersconfig.json
* cache directory: /home/perrette/.cache/papers
* absolute paths: True
* files directory: files (1 files, 5.8 MB)
* bibtex: papers.bib (1 entries)
The configuration file is global (unless `--local` is specified), so from now on, any `papers`
command will know about these settings: no need to specify bibtex file or files directory.
Type `papers status -v` to check your configuration.
You also notice a cache directory. All internet requests such as crossref requests are saved in the cache directory.
This happens regardless of whether `papers` is installed or not.
#### local install
Sometimes it is desirable to have separate configurations. In that case a local install is the way to go:
$> papers install --local
Bibtex file name [default to existing: papers.bib] [Enter/Yes/No]:
Files folder [default to new: papers] [Enter/Yes/No]: pdfs
papers configuration
* configuration file: .papers/config.json
* cache directory: /home/perrette/.cache/papers
* absolute paths: True
* git-tracked: False
* files directory: pdfs (90 files, 337.4 MB)
* bibtex: papers.bib (82 entries)
Creates a local configuration file in a hidden `.papers` folder.
By default, it expects existing or creates new `papers.bib` bibliography and `papers` files folder in the local directory, though `papers` will ask first unless explicitly provided.
Note that every call from a subfolder will also detect that configuration file (it has priority over global install).
By default, the local install is meant to be portable with bibtex and files, so the file paths are encoded relatively to the bibtex file.
If instead absolute paths make more sense (example use case: local bibtex file but central PDF folder), then simply specify `--absolute-paths` options:
`papers install --local --absolute-paths --filesdir /path/to/central/pdfs`
#### uninstall
Getting confused with papers config files scattered in subfolders ? Check the config with
papers status -v
and remove the configuration file by hand (`rm ...`). Or use `papers uninstall` command:
papers uninstall
You may repeat `papers status -v` and cleaning until a satistfying state is reached, or remove all config files recursively up to (and including) global install:
papers uninstall --recursive
### Relative versus Absolute path
By default, the file paths in the bibtex are stored as absolute paths (starting with `/`), except for local installs.
It is possible to change this behavious explicitly during install or in a case by case basis with `--relative-paths` or `--absolute-paths` options.
With or without install.
### Move library to a new location
Moving a library can be tricky.
Simple cases are:
- files are stored in a central repository, and the bibtex contains absolute paths. Then moving the bibtex by hand is fine.
- files are stored alongside the bibtex, and the bibtex contains relative paths. Just move around the folder containing bibtex and files
In any other cases, you risk breaking the file links.
Papers tries to be as little opinionated as possible about how files are organized, and so it relies on your own judgement and use case.
When loading a bibtex, it always inteprete relative file links as being relative to the bibtex file.
When saving a bibtex, it will save file links accordingly to the default setting path (usually absolute, unless local install or unless you specify otherwise).
In any case, the following set of commands will always work provided the initial file links are valid (optional parameters in brackets):
touch new.bib
papers add /path/to/old.bib --bib new.bib [ --rename ] [ --relative-paths ] [ --filesdir newfilesdir ]
rm -f /path/to/old.bib
### check
It's easy to end up with duplicates in your bibtex. After adding PDFs, or every once in a while, do:
papers check --duplicates
### filecheck
Check for broken links, rename files etc. Example:
papers filecheck --rename
The command can be used to move around the file directory:
papers filecheck --rename --filesdir newfilesdir
That command is also convenient to check on what's actually tracked and what is not. Example workflow
papers filecheck --rename --filesdir tmp
# check what's left over in your initial files directory, e.g.
# papers extract files/leftover1.pdf
# papers add files/leftover1.pdf
# ...
papers filecheck --rename --filesdir files
### Setup git-tracked library (optional)
Install comes with the option to git-track any change to the bibtex file (`--git`) options.
$> papers install --bibtex papers.bib --filesdir files --git [ --git-lfs ]
From now on, every change to the library will result in an automatic git commit.
And `papers git ...` command will work just as `git ...` executed from the bibtex directory.
E.g. `papers git add origin *REMOTE URL*`; `papers git lfs track files`; `papers git add files`; `papers git push`
If `--git-lfs` is passed, the files will be backed-up along with the bibtex.
Under the hood, bibtex and files (if applicable) are copied (hard-linked) to a back-up directory.
Details are described in [issue 51](https://github.com/perrette/papers/issues/51).
In local installs, backup occurs in `.papers/`. In global installs, defaults to `~/.local/.share/papers`.
Type `papers status -v` to find out.
For local install that are already git-tracked, the feature remains useful as it is the basis for `papers undo` and `papers redo`.
You might want to add `.papers` to your .gitignore to avoid messing up with your larger project.
This feature is experimental.
### undo / redo
Did a `papers add` and are unhappy with the result?
papers undo
will revert to the previous version. If repeated, it will jump back and forth between latest and before-latest.
Unless papers is installed with --git option, in which case `papers undo` and `papers redo` will have essentially infinite memory
(doing undos and making a new commit risk loosing history, unless you keep track of the commit).
Consult inline help for more detailed documentation!
Current features
----------------
- parse PDF to extract DOI
- fetch bibtex entry from DOI (using crossref API)
- fetch bibtex entry by fulltext search (using crossref API or google scholar)
- create and maintain bibtex file
- add entry as PDF (`papers add ...`)
- add entry as bibtex (`papers add ...`)
- scan directory for PDFs (`papers add ...`)
- rename PDFs according to bibtex key and year (`papers filecheck --rename [--copy]`)
- some support for attachment
- merging (`papers check --duplicates ...`)
- fix entries (`papers check --format-name --encoding unicode --fix-doi --fix-key ...`)
- configuration file with default bibtex and files directory (`papers install --bibtex BIB --filesdir DIR ...`)
- integration with git
- undo/redo command (`papers undo / redo`)
- display / search / list entries : format as bibtex or key or whatever (`papers list ... [--key-only, -l]`)
- list + edit or remove entry by key or else (`papers list ... [--edit, --delete]`)
- fix broken PDF links (`papers filecheck ...`):
- remove duplicate file names (always) or file copies (`--hash-check`)
- remove missing link (`--delete-missing`)
- fix files name after a Mendeley export (`--fix-mendeley`):
- leading '/' missing is added
- latex characters, e.g. `{\_}` or `{\'{e}}` replaced with unicode
Tests
-----
Test coverage is improving (now 80%)
Currently covers:
- `papers extract` (test on a handful of PDFs)
- parse pdf DOI
- fetch bibtex on crossref based on DOI
- fetch bibtex on crossref based fulltext search
- fetch bibtex on google-scholar based fulltext search
- `papers add`
- add entry and manage conflict
- add pdf file, bibtex, directory
- add one pdf file with attachment (beta, API will change)
- conflict resolution
- `papers install`
- internals:
- duplicate test with levels `EXACT`, `GOOD`, `FAIR` (the default), `PARTIAL`
- `papers list`
- `papers undo / redo` (partial)
- `papers filecheck --rename` (superficial)
- `papers check --duplicate` (fix DOI etc.) (superficial)
Why not JabRef, Zotero or Mendeley (or...) ?
--------------------------------------------
- JabRef (2.10) is nice, light-weight, but is not so good at managing PDFs.
- Zotero (5.0) features excellent PDF import capability, but it needs to be manually one by one and is a little slow. Not very flexible.
- Mendeley (1.17) is perfect at automatically extracting metadata from downloaded PDF and managing your PDF library,
but it is not open source, and many issues remain (own experience, Ubuntu 14.04, Desktop Version 1.17):
- very unstable
- PDF automatic naming is too verbose, and sometimes the behaviour is unexpected (some PDFs remain in on obscure Downloaded folder, instead of in the main collection)
- somewhat heavy (it offers functions of online syncing, etc)
- poor seach capability (related to the point above)
Above-mentioned issues will with no doubt be improved in future releases, but they are a starting point for this project.
Anyway, a command-line tool is per se a good idea for faster development,
as noted [here](https://forums.zotero.org/discussion/43386/zotero-cli-version),
but so far I could only find zotero clients for their online API
(like [pyzotero](https://github.com/urschrei/pyzotero) or [zotero-cli](https://github.com/jbaiter/zotero-cli)).
Please contact me if you know another interesting project.
Raw data
{
"_id": null,
"home_page": "",
"name": "papers-cli",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "bibtex,references,bibliography",
"author": "",
"author_email": "Mah\u00e9 Perrette <mahe.perrette@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/28/00/099e6d5d36dfcdd5030af9d056890ce7d920aafdd69b283e9cabd2a1a1e0/papers-cli-2.4.tar.gz",
"platform": null,
"description": "[](https://github.com/perrette/papers/actions)\n[]()\n[]()\n[]()\n[]()\n\n# papers\n\nCommand-line tool to manage bibliography (pdfs + bibtex)\n\nDisclaimer: This tool requires further development and testing, and might never be fully production-ready (contributors welcome). \\\nThat said, it is becoming useful :)\n\n## Motivation\n\nThis project is an attempt to create a light-weight,\ncommand-line bibliography managenent tool. Aims:\n\n- maintain a PDF library (with appropriate naming)\n- maintain one or several bibtex-compatible collections, linked to PDFs\n- enough PDF-parsing capability to fetch metadata from the internet (i.e. [crossref](https://github.com/CrossRef/rest-api-doc) or google-scholar)\n\n\n## Dependencies\n\n- python 3.8+\n- [poppler-utils](https://en.wikipedia.org/wiki/Poppler_(software)) (only:`pdftotext`): convert PDF to text for parsing\n- [bibtexparser](https://bibtexparser.readthedocs.io) : parse bibtex files\n- [crossrefapi](https://github.com/fabiobatalha/crossrefapi) : make polite requests to crossref API\n- [scholarly](https://github.com/OrganicIrradiation/scholarly) : interface for google scholar\n- [rapidfuzz](https://github.com/rhasspy/rapidfuzz) : calculate score to sort crossref requests\n- [unidecode](https://github.com/avian2/unidecode) : replace unicode with ascii equivalent\n\n## Install\n\n- `pip install papers-cli`\n- install third-party dependencies (Ubuntu: `sudo apt install poppler-utils`)\n\nNote there is another project registered on pypi as papers, hence `papers-cli` for command-line-interface.\n\n## Getting started\n\nThis tool's interface is built like `git`, with main command `papers` and a range of subcommands.\n\n### Extract PDF metadata and add to library\n\nStart with PDF of your choice (modern enough to have a DOI, e.g. anything from the Copernicus publications).\nFor the sake of the example, one of my owns: https://www.earth-syst-dynam.net/4/11/2013/esd-4-11-2013.pdf\n\n- extract pdf metadata (doi-based if available, otherwise crossref, or google scholar if so specified)\n\n\t\t$> papers extract esd-4-11-2013.pdf\n\t\t@article{Perrette_2013,\n\t\tdoi = {10.5194/esd-4-11-2013},\n\t\turl = {https://doi.org/10.5194%2Fesd-4-11-2013},\n\t\tyear = 2013,\n\t\tmonth = {jan},\n\t\tpublisher = {Copernicus {GmbH}},\n\t\tvolume = {4},\n\t\tnumber = {1},\n\t\tpages = {11--29},\n\t\tauthor = {M. Perrette and F. Landerer and R. Riva and K. Frieler and M. Meinshausen},\n\t\ttitle = {A scaling approach to project regional sea level rise and its uncertainties},\n\t\tjournal = {Earth System Dynamics}\n\t\t}\n\n- add pdf to `papers.bib` library, and rename a copy of it in a files directory `files`.\n\n\t\t$> papers add esd-4-11-2013.pdf --rename --copy --bibtex papers.bib --filesdir files --info\n\t\tINFO:papers:found doi:10.5194/esd-4-11-2013\n\t\tINFO:papers:new entry: perrette_landerer2013\n\t\tINFO:papers:mv /home/perrette/playground/papers/esd-4-11-2013.pdf files/perrette_et_al_2013_a-scaling-approach-to-project-regional-sea-level-rise-and-its-uncertainties.pdf\n\t\tINFO:papers:renamed file(s): 1\n\n(the `--info` argument asks for the above output information to be printed out to the terminal)\n\nThat is equivalent to doing:\n\n papers extract esd-4-11-2013.pdf > entry.bib\n papers add entry.bib --bibtex papers.bib --attachment esd-4-11-2013.pdf --rename --copy\n\nSee [Control fields when renaming file](#control-fields-when-renaming-file) for how to specify file naming patterns.\n\n### Add library entry from its DOI\n\nIf you already know the DOI of a PDF, and don't want to gamble the fulltext search and match, you can indicate it via `--doi`:\n\n papers add esd-4-11-2013.pdf --doi 10.5194/esd-4-11-2013 --bibtex papers.bib\n\nThe `add` command above also works without any PDF (create a bibtex entry without file attachment).\n\n papers add --doi 10.5194/esd-4-11-2013 --bibtex papers.bib\n \n### List entries (and edit etc...)\n\nPretty listing (-1 or -l for one-liner listing, otherwise plain bibtex):\n\n $> papers list -1\n Perrette2013: A scaling approach to project regional sea level rise and it... (doi:10.5194/esd-4-11-2013, file:1)\n\nSearch with any number of keywords:\n\n $> papers list perrette scaling approach sea level -1\n ... (short list)\n $> papers list perrette scaling approach sea level --any -1\n ... (long list)\n $> papers list --key perrette2013 --author perrette --year 2013 --title scaling approach sea level -1\n ... (precise list)\n\nAdd tags to view papers by topic:\n\n $> papers list perrette2013 --add-tag sea-level projections -1\n ...\n $> papers list --tag sea-level projections -1\n Perrette2013: A scaling approach to project regional sea level rise and it... (doi:10.5194/esd-4-11-2013, file:1, sea-level | projections )\n\n`papers list` is a powerful command, inspired from unix's `find` and `grep`.\n\nIt lets you search in your bibtex in a typical manner (including a number of special flags such as `--duplicates`, `--review-required`, `--broken-file`...),\nthen output the result in a number of formats (one-liner, raw bibtex, keys-only, selected fields) or let you perform actions on it (currently `--edit`, `--delete`, `--add-tag`, `--fetch`).\nFor instance, it is possible to manually merge the duplicates with:\n\n $> papers list --duplicates --edit\n\n\n### Control fields when renaming file\n\n $> papers add --rename --info --name-template \"{AuthorX}{year}-{Title}\" --name-title-sep '' --name-author-sep '' esd-4-11-2013\n INFO:papers:found doi:10.5194/esd-4-11-2013\n INFO:papers:new entry: perrette2013scaling\n INFO:papers:create directory: files/2013\n INFO:papers:mv /home/perrette/playground/papers/esd-4-11-2013.pdf files/PerretteEtAl2013-AScalingApproachToProjectRegionalSeaLevelRiseAndItsUncertainties.pdf\n INFO:papers:renamed file(s): 1\n\nwhere '--name-template' is a python template (will be formated via .format() method) with valid fields being any field available in the bibtex. Fields not in the bibtex will remain untouched.\n\nTo rename `esd-4-11-2013.pdf` as `perrette_2013.pdf`, the template should be `--name-template {author}_{year} --name-author-num 1`\nIf that happens to be the entry ID, `ID` also works.\n\nTo `rename esd-4-11-2013.pdf` as `2013/Perrette2013-AScalingApproachToProjectRegionalSeaLevelRiseAndItsUncertainties.pdf`,\nname-template should be `--name-template {year}/{Author}{year}-{Title} --name-title-sep ''` (note the case).\n\nEntries are case-sensitive, and a few more fields are added, so that:\n- 'author' generates 'perrette'\n- 'Author' generates 'Perrette'\n- 'AUTHOR' generates 'PERRETTE'\n- 'authorX' generates 'perrette', 'perrette_and_landerer' or 'perrette_et_al' dependening on the number of authors\n- 'AuthorX' same as authorX but capitalized\n\nThe modifiers are:\n\n- `--name-title-sep` : separator for title words\n- `--name-title-length` : max title length\n- `--name-title-word-size` : min size to be considered a word\n- `--name-title-word-num` : max number of title words\n\nand similarly:\n\n- `--name-author-sep` : separator for authors\n- `--name-author-num` : number of authors to (not relevant for `{authorX}`)\n\nThe same template and modifiers system applies to the bibtex key generation by replacing the prefix `--name-` with `--key-`, e.g. `--key-template`\n\n\nIn the common case where the bibtex (`--bibtex`), files directory (`--filesdir`), and name and key formats (e.g. `--name-template`) do not change, it is convenient to\n(install)[#install-make-bibtex-and-files-directory-persistent] `papers`.\n\n\n### install: make bibtex and files directory persistent\n\n $> papers install --bibtex papers.bib --filesdir files\n papers configuration\n * configuration file: /home/perrette/.config/papersconfig.json\n * cache directory: /home/perrette/.cache/papers\n * absolute paths: True\n * files directory: files (1 files, 5.8 MB)\n * bibtex: papers.bib (1 entries)\n\nThe configuration file is global (unless `--local` is specified), so from now on, any `papers`\ncommand will know about these settings: no need to specify bibtex file or files directory.\n\nType `papers status -v` to check your configuration.\n\nYou also notice a cache directory. All internet requests such as crossref requests are saved in the cache directory.\nThis happens regardless of whether `papers` is installed or not.\n\n\n#### local install\n\nSometimes it is desirable to have separate configurations. In that case a local install is the way to go:\n\n $> papers install --local\n Bibtex file name [default to existing: papers.bib] [Enter/Yes/No]:\n Files folder [default to new: papers] [Enter/Yes/No]: pdfs\n papers configuration\n * configuration file: .papers/config.json\n * cache directory: /home/perrette/.cache/papers\n * absolute paths: True\n * git-tracked: False\n * files directory: pdfs (90 files, 337.4 MB)\n * bibtex: papers.bib (82 entries)\n\n\nCreates a local configuration file in a hidden `.papers` folder.\nBy default, it expects existing or creates new `papers.bib` bibliography and `papers` files folder in the local directory, though `papers` will ask first unless explicitly provided.\nNote that every call from a subfolder will also detect that configuration file (it has priority over global install).\n\nBy default, the local install is meant to be portable with bibtex and files, so the file paths are encoded relatively to the bibtex file.\nIf instead absolute paths make more sense (example use case: local bibtex file but central PDF folder), then simply specify `--absolute-paths` options:\n\n `papers install --local --absolute-paths --filesdir /path/to/central/pdfs`\n\n\n#### uninstall\n\nGetting confused with papers config files scattered in subfolders ? Check the config with\n\n papers status -v\n\nand remove the configuration file by hand (`rm ...`). Or use `papers uninstall` command:\n\n papers uninstall\n\nYou may repeat `papers status -v` and cleaning until a satistfying state is reached, or remove all config files recursively up to (and including) global install:\n\n papers uninstall --recursive\n\n\n### Relative versus Absolute path\n\nBy default, the file paths in the bibtex are stored as absolute paths (starting with `/`), except for local installs.\nIt is possible to change this behavious explicitly during install or in a case by case basis with `--relative-paths` or `--absolute-paths` options.\nWith or without install.\n\n\n### Move library to a new location\n\nMoving a library can be tricky.\nSimple cases are:\n- files are stored in a central repository, and the bibtex contains absolute paths. Then moving the bibtex by hand is fine.\n- files are stored alongside the bibtex, and the bibtex contains relative paths. Just move around the folder containing bibtex and files\nIn any other cases, you risk breaking the file links.\n\nPapers tries to be as little opinionated as possible about how files are organized, and so it relies on your own judgement and use case.\nWhen loading a bibtex, it always inteprete relative file links as being relative to the bibtex file.\nWhen saving a bibtex, it will save file links accordingly to the default setting path (usually absolute, unless local install or unless you specify otherwise).\n\nIn any case, the following set of commands will always work provided the initial file links are valid (optional parameters in brackets):\n\n touch new.bib\n papers add /path/to/old.bib --bib new.bib [ --rename ] [ --relative-paths ] [ --filesdir newfilesdir ]\n rm -f /path/to/old.bib\n\n\n### check\n\nIt's easy to end up with duplicates in your bibtex. After adding PDFs, or every once in a while, do:\n\n papers check --duplicates\n\n\n### filecheck\n\nCheck for broken links, rename files etc. Example:\n\n papers filecheck --rename\n\nThe command can be used to move around the file directory:\n\n papers filecheck --rename --filesdir newfilesdir\n\nThat command is also convenient to check on what's actually tracked and what is not. Example workflow\n\n papers filecheck --rename --filesdir tmp\n # check what's left over in your initial files directory, e.g.\n # papers extract files/leftover1.pdf\n # papers add files/leftover1.pdf\n # ...\n papers filecheck --rename --filesdir files\n\n\n### Setup git-tracked library (optional)\n\n Install comes with the option to git-track any change to the bibtex file (`--git`) options.\n\n $> papers install --bibtex papers.bib --filesdir files --git [ --git-lfs ]\n\nFrom now on, every change to the library will result in an automatic git commit.\nAnd `papers git ...` command will work just as `git ...` executed from the bibtex directory.\nE.g. `papers git add origin *REMOTE URL*`; `papers git lfs track files`; `papers git add files`; `papers git push`\n\nIf `--git-lfs` is passed, the files will be backed-up along with the bibtex.\nUnder the hood, bibtex and files (if applicable) are copied (hard-linked) to a back-up directory.\nDetails are described in [issue 51](https://github.com/perrette/papers/issues/51).\n\nIn local installs, backup occurs in `.papers/`. In global installs, defaults to `~/.local/.share/papers`.\nType `papers status -v` to find out.\n\nFor local install that are already git-tracked, the feature remains useful as it is the basis for `papers undo` and `papers redo`.\nYou might want to add `.papers` to your .gitignore to avoid messing up with your larger project.\n\nThis feature is experimental.\n\n\n### undo / redo\n\nDid a `papers add` and are unhappy with the result?\n\n papers undo\n\nwill revert to the previous version. If repeated, it will jump back and forth between latest and before-latest.\nUnless papers is installed with --git option, in which case `papers undo` and `papers redo` will have essentially infinite memory\n(doing undos and making a new commit risk loosing history, unless you keep track of the commit).\n\n\nConsult inline help for more detailed documentation!\n\n\nCurrent features\n----------------\n- parse PDF to extract DOI\n- fetch bibtex entry from DOI (using crossref API)\n- fetch bibtex entry by fulltext search (using crossref API or google scholar)\n- create and maintain bibtex file\n- add entry as PDF (`papers add ...`)\n- add entry as bibtex (`papers add ...`)\n- scan directory for PDFs (`papers add ...`)\n- rename PDFs according to bibtex key and year (`papers filecheck --rename [--copy]`)\n- some support for attachment\n- merging (`papers check --duplicates ...`)\n- fix entries (`papers check --format-name --encoding unicode --fix-doi --fix-key ...`)\n- configuration file with default bibtex and files directory (`papers install --bibtex BIB --filesdir DIR ...`)\n- integration with git\n- undo/redo command (`papers undo / redo`)\n- display / search / list entries : format as bibtex or key or whatever (`papers list ... [--key-only, -l]`)\n- list + edit or remove entry by key or else (`papers list ... [--edit, --delete]`)\n- fix broken PDF links (`papers filecheck ...`):\n - remove duplicate file names (always) or file copies (`--hash-check`)\n - remove missing link (`--delete-missing`)\n - fix files name after a Mendeley export (`--fix-mendeley`):\n - leading '/' missing is added\n - latex characters, e.g. `{\\_}` or `{\\'{e}}` replaced with unicode\n\n\nTests\n-----\nTest coverage is improving (now 80%)\n\nCurrently covers:\n- `papers extract` (test on a handful of PDFs)\n - parse pdf DOI\n - fetch bibtex on crossref based on DOI\n - fetch bibtex on crossref based fulltext search\n - fetch bibtex on google-scholar based fulltext search\n- `papers add`\n - add entry and manage conflict\n - add pdf file, bibtex, directory\n - add one pdf file with attachment (beta, API will change)\n - conflict resolution\n- `papers install`\n- internals:\n - duplicate test with levels `EXACT`, `GOOD`, `FAIR` (the default), `PARTIAL`\n- `papers list`\n- `papers undo / redo` (partial)\n- `papers filecheck --rename` (superficial)\n- `papers check --duplicate` (fix DOI etc.) (superficial)\n\n\nWhy not JabRef, Zotero or Mendeley (or...) ?\n--------------------------------------------\n- JabRef (2.10) is nice, light-weight, but is not so good at managing PDFs.\n- Zotero (5.0) features excellent PDF import capability, but it needs to be manually one by one and is a little slow. Not very flexible.\n- Mendeley (1.17) is perfect at automatically extracting metadata from downloaded PDF and managing your PDF library,\nbut it is not open source, and many issues remain (own experience, Ubuntu 14.04, Desktop Version 1.17):\n - very unstable\n - PDF automatic naming is too verbose, and sometimes the behaviour is unexpected (some PDFs remain in on obscure Downloaded folder, instead of in the main collection)\n - somewhat heavy (it offers functions of online syncing, etc)\n - poor seach capability (related to the point above)\n\nAbove-mentioned issues will with no doubt be improved in future releases, but they are a starting point for this project.\nAnyway, a command-line tool is per se a good idea for faster development,\nas noted [here](https://forums.zotero.org/discussion/43386/zotero-cli-version),\nbut so far I could only find zotero clients for their online API\n(like [pyzotero](https://github.com/urschrei/pyzotero) or [zotero-cli](https://github.com/jbaiter/zotero-cli)).\nPlease contact me if you know another interesting project.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "utilities to keep your PDF library organized",
"version": "2.4",
"split_keywords": [
"bibtex",
"references",
"bibliography"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7abfc7a688f78b46cfb3cc4b27bab1f1152295dd8a591a06bfa96c5e39386679",
"md5": "a350337fc1c7a105e5a1fdb26d5715f5",
"sha256": "2105c8e1ebc8af0c29ca709a7c262f1861119fd68e1ac0811ad8c9574fce95ea"
},
"downloads": -1,
"filename": "papers_cli-2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a350337fc1c7a105e5a1fdb26d5715f5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 63519,
"upload_time": "2023-04-28T01:50:48",
"upload_time_iso_8601": "2023-04-28T01:50:48.794033Z",
"url": "https://files.pythonhosted.org/packages/7a/bf/c7a688f78b46cfb3cc4b27bab1f1152295dd8a591a06bfa96c5e39386679/papers_cli-2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2800099e6d5d36dfcdd5030af9d056890ce7d920aafdd69b283e9cabd2a1a1e0",
"md5": "2e882da69970fd88c791a82d31110b23",
"sha256": "e4643e8ca60c78a9b3e29793647b8f3a80eed392f54d3b408b5f5525f2eb476b"
},
"downloads": -1,
"filename": "papers-cli-2.4.tar.gz",
"has_sig": false,
"md5_digest": "2e882da69970fd88c791a82d31110b23",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 80620,
"upload_time": "2023-04-28T01:50:51",
"upload_time_iso_8601": "2023-04-28T01:50:51.760661Z",
"url": "https://files.pythonhosted.org/packages/28/00/099e6d5d36dfcdd5030af9d056890ce7d920aafdd69b283e9cabd2a1a1e0/papers-cli-2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-28 01:50:51",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "papers-cli"
}
