papers-cli 2.16.2__tar.gz → 2.17.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. papers_cli-2.17.1/.github/workflows/docs.yml +34 -0
  2. {papers_cli-2.16.2 → papers_cli-2.17.1}/.github/workflows/pypi.yml +8 -4
  3. {papers_cli-2.16.2 → papers_cli-2.17.1}/.github/workflows/release.yml +1 -1
  4. {papers_cli-2.16.2 → papers_cli-2.17.1}/.github/workflows/tests.yml +2 -2
  5. {papers_cli-2.16.2 → papers_cli-2.17.1}/.gitignore +5 -2
  6. papers_cli-2.17.1/PKG-INFO +112 -0
  7. papers_cli-2.17.1/README.md +84 -0
  8. papers_cli-2.17.1/docs/adding-entries.md +61 -0
  9. papers_cli-2.17.1/docs/comparison.md +25 -0
  10. papers_cli-2.17.1/docs/configuration.md +101 -0
  11. papers_cli-2.17.1/docs/features.md +50 -0
  12. papers_cli-2.17.1/docs/git.md +49 -0
  13. papers_cli-2.17.1/docs/index.md +55 -0
  14. papers_cli-2.17.1/docs/installation.md +38 -0
  15. papers_cli-2.17.1/docs/library-management.md +76 -0
  16. papers_cli-2.17.1/docs/listing.md +52 -0
  17. papers_cli-2.17.1/docs/quickstart.md +74 -0
  18. papers_cli-2.17.1/docs/renaming.md +58 -0
  19. papers_cli-2.17.1/docs/undo-redo.md +22 -0
  20. papers_cli-2.17.1/mkdocs.yml +79 -0
  21. {papers_cli-2.16.2 → papers_cli-2.17.1}/papers/__main__.py +266 -457
  22. papers_cli-2.17.1/papers/_version.py +24 -0
  23. papers_cli-2.17.1/papers/backup.py +505 -0
  24. {papers_cli-2.16.2 → papers_cli-2.17.1}/papers/bib.py +108 -16
  25. {papers_cli-2.16.2 → papers_cli-2.17.1}/papers/config.py +92 -40
  26. {papers_cli-2.16.2 → papers_cli-2.17.1}/papers/duplicate.py +114 -77
  27. {papers_cli-2.16.2 → papers_cli-2.17.1}/papers/encoding.py +24 -17
  28. {papers_cli-2.16.2 → papers_cli-2.17.1}/papers/extract.py +10 -1
  29. {papers_cli-2.16.2 → papers_cli-2.17.1}/papers/filename.py +3 -1
  30. papers_cli-2.17.1/papers/install.py +293 -0
  31. {papers_cli-2.16.2 → papers_cli-2.17.1}/papers/utils.py +5 -1
  32. papers_cli-2.17.1/papers_cli.egg-info/PKG-INFO +112 -0
  33. {papers_cli-2.16.2 → papers_cli-2.17.1}/papers_cli.egg-info/SOURCES.txt +21 -2
  34. {papers_cli-2.16.2 → papers_cli-2.17.1}/papers_cli.egg-info/entry_points.txt +1 -0
  35. papers_cli-2.17.1/papers_cli.egg-info/requires.txt +14 -0
  36. {papers_cli-2.16.2 → papers_cli-2.17.1}/pyproject.toml +17 -0
  37. {papers_cli-2.16.2 → papers_cli-2.17.1}/requirements.txt +1 -0
  38. {papers_cli-2.16.2 → papers_cli-2.17.1}/tests/common.py +3 -3
  39. papers_cli-2.17.1/tests/downloadedpapers/.gitignore +6 -0
  40. papers_cli-2.17.1/tests/downloadedpapers/bg-8-515-2011.pdf +0 -0
  41. papers_cli-2.17.1/tests/downloadedpapers/esd-4-11-2013-supplement.pdf +0 -0
  42. papers_cli-2.17.1/tests/downloadedpapers/esd-4-11-2013.pdf +0 -0
  43. {papers_cli-2.16.2 → papers_cli-2.17.1}/tests/test_add.py +19 -1
  44. papers_cli-2.17.1/tests/test_backup_dirs.py +137 -0
  45. papers_cli-2.17.1/tests/test_bib_unit.py +258 -0
  46. papers_cli-2.17.1/tests/test_config_unit.py +207 -0
  47. {papers_cli-2.16.2 → papers_cli-2.17.1}/tests/test_duplicates.py +147 -2
  48. {papers_cli-2.16.2 → papers_cli-2.17.1}/tests/test_encoding.py +11 -4
  49. {papers_cli-2.16.2 → papers_cli-2.17.1}/tests/test_extract_unit.py +59 -0
  50. {papers_cli-2.16.2 → papers_cli-2.17.1}/tests/test_filename_unit.py +11 -0
  51. {papers_cli-2.16.2 → papers_cli-2.17.1}/tests/test_install.py +124 -21
  52. {papers_cli-2.16.2 → papers_cli-2.17.1}/tests/test_list.py +27 -2
  53. {papers_cli-2.16.2 → papers_cli-2.17.1}/tests/test_undo.py +33 -7
  54. {papers_cli-2.16.2 → papers_cli-2.17.1}/tests/test_utils.py +11 -0
  55. papers_cli-2.16.2/PKG-INFO +0 -421
  56. papers_cli-2.16.2/README.md +0 -399
  57. papers_cli-2.16.2/papers/_version.py +0 -34
  58. papers_cli-2.16.2/papers_cli.egg-info/PKG-INFO +0 -421
  59. papers_cli-2.16.2/papers_cli.egg-info/requires.txt +0 -8
  60. papers_cli-2.16.2/tests/downloadedpapers/.gitignore +0 -1
  61. papers_cli-2.16.2/tests/test_bib_unit.py +0 -135
  62. papers_cli-2.16.2/tests/test_config_unit.py +0 -86
  63. papers_cli-2.16.2/tests/test_misc.py +0 -0
  64. {papers_cli-2.16.2 → papers_cli-2.17.1}/.gitattributes +0 -0
  65. {papers_cli-2.16.2 → papers_cli-2.17.1}/.github/FUNDING.yml +0 -0
  66. {papers_cli-2.16.2 → papers_cli-2.17.1}/LICENSE +0 -0
  67. {papers_cli-2.16.2 → papers_cli-2.17.1}/papers/__init__.py +0 -0
  68. {papers_cli-2.16.2 → papers_cli-2.17.1}/papers/entries.py +0 -0
  69. {papers_cli-2.16.2 → papers_cli-2.17.1}/papers/latexenc.py +0 -0
  70. {papers_cli-2.16.2 → papers_cli-2.17.1}/papers_cli.egg-info/dependency_links.txt +0 -0
  71. {papers_cli-2.16.2 → papers_cli-2.17.1}/papers_cli.egg-info/top_level.txt +0 -0
  72. {papers_cli-2.16.2 → papers_cli-2.17.1}/scripts/README.md +0 -0
  73. {papers_cli-2.16.2 → papers_cli-2.17.1}/scripts/benchmark_bibtexparser_load.py +0 -0
  74. {papers_cli-2.16.2 → papers_cli-2.17.1}/scripts/generate_dummy_bib.py +0 -0
  75. {papers_cli-2.16.2 → papers_cli-2.17.1}/setup.cfg +0 -0
  76. {papers_cli-2.16.2 → papers_cli-2.17.1}/setup.py +0 -0
  77. {papers_cli-2.16.2 → papers_cli-2.17.1}/tests/__init__.py +0 -0
  78. {papers_cli-2.16.2 → papers_cli-2.17.1}/tests/config.py +0 -0
  79. {papers_cli-2.16.2 → papers_cli-2.17.1}/tests/download.py +0 -0
  80. {papers_cli-2.16.2 → papers_cli-2.17.1}/tests/downloadedpapers/bg-8-515-2011.txt +0 -0
  81. {papers_cli-2.16.2 → papers_cli-2.17.1}/tests/test_biblio.py +0 -0
  82. {papers_cli-2.16.2 → papers_cli-2.17.1}/tests/test_check.py +0 -0
  83. {papers_cli-2.16.2 → papers_cli-2.17.1}/tests/test_extract.py +0 -0
  84. {papers_cli-2.16.2 → papers_cli-2.17.1}/tests/test_filecheck.py +0 -0
  85. {papers_cli-2.16.2 → papers_cli-2.17.1}/tests/test_latexenc.py +0 -0
@@ -0,0 +1,34 @@
1
+ name: docs
2
+
3
+ on:
4
+ push:
5
+ branches: [master]
6
+ paths:
7
+ - "docs/**"
8
+ - "mkdocs.yml"
9
+ - "README.md"
10
+ - ".github/workflows/docs.yml"
11
+ workflow_dispatch:
12
+
13
+ permissions:
14
+ contents: write
15
+
16
+ jobs:
17
+ deploy:
18
+ runs-on: ubuntu-latest
19
+ steps:
20
+ - uses: actions/checkout@v6
21
+ with:
22
+ fetch-depth: 0
23
+ - uses: actions/setup-python@v6
24
+ with:
25
+ python-version: "3.x"
26
+ - name: Cache mkdocs-material assets
27
+ uses: actions/cache@v4
28
+ with:
29
+ key: mkdocs-material-${{ github.sha }}
30
+ path: .cache
31
+ restore-keys: |
32
+ mkdocs-material-
33
+ - run: pip install .[docs]
34
+ - run: mkdocs gh-deploy --force
@@ -20,21 +20,25 @@ jobs:
20
20
 
21
21
  steps:
22
22
  - name: Checkout code
23
- uses: actions/checkout@v5
23
+ uses: actions/checkout@v6
24
24
 
25
25
  - name: Set up Python
26
- uses: actions/setup-python@v5
26
+ uses: actions/setup-python@v6
27
27
  with:
28
28
  python-version: '3.x'
29
29
 
30
30
  - name: Install dependencies
31
31
  run: |
32
32
  python -m pip install --upgrade pip
33
- pip install setuptools wheel twine
33
+ pip install build
34
34
 
35
35
  - name: Build distribution
36
+ # PEP 517 build: resolves build-system.requires from pyproject.toml in an
37
+ # isolated environment (the legacy `setup.py sdist` path fetched the newest
38
+ # setuptools_scm without its dependencies and broke when it split out
39
+ # vcs-versioning)
36
40
  run: |
37
- python setup.py sdist bdist_wheel
41
+ python -m build
38
42
 
39
43
  - name: Publish to PyPI
40
44
  uses: pypa/gh-action-pypi-publish@release/v1
@@ -13,7 +13,7 @@ jobs:
13
13
 
14
14
  steps:
15
15
  - name: Checkout code
16
- uses: actions/checkout@v4
16
+ uses: actions/checkout@v6
17
17
  with:
18
18
  fetch-depth: 0 # Fetch all history for changelog generation
19
19
 
@@ -13,9 +13,9 @@ jobs:
13
13
  python-version: [ "3.9", "3.10", "3.11", "3.12", "3.13", "3.14", "3.14t" ]
14
14
 
15
15
  steps:
16
- - uses: actions/checkout@v5
16
+ - uses: actions/checkout@v6
17
17
  - name: Set up Python ${{ matrix.python-version }}
18
- uses: actions/setup-python@v5
18
+ uses: actions/setup-python@v6
19
19
  with:
20
20
  python-version: ${{ matrix.python-version }}
21
21
  - name: Install dependencies
@@ -9,7 +9,10 @@ papers/_version.py
9
9
  dist/
10
10
  .coverage
11
11
  htmlcov/
12
- .venv
12
+ .venv*
13
13
  .pytest_cache
14
14
  papers.sublime-project
15
- papers.sublime-workspace
15
+ papers.sublime-workspace
16
+ site/
17
+ notes/
18
+ dummy_library.bib
@@ -0,0 +1,112 @@
1
+ Metadata-Version: 2.4
2
+ Name: papers-cli
3
+ Version: 2.17.1
4
+ Summary: utilities to keep your PDF library organized
5
+ Author-email: Mahé Perrette <mahe.perrette@gmail.com>
6
+ License: MIT
7
+ Project-URL: homepage, https://github.com/perrette/papers
8
+ Project-URL: Documentation, https://perrette.github.io/papers/
9
+ Keywords: bibtex,references,bibliography
10
+ Classifier: Programming Language :: Python :: 3
11
+ Requires-Python: >=3.9
12
+ Description-Content-Type: text/markdown
13
+ License-File: LICENSE
14
+ Requires-Dist: PyMuPDF
15
+ Requires-Dist: unidecode
16
+ Requires-Dist: crossrefapi
17
+ Requires-Dist: bibtexparser>=2.0.0b2
18
+ Requires-Dist: scholarly
19
+ Requires-Dist: rapidfuzz
20
+ Requires-Dist: python-slugify
21
+ Requires-Dist: bs4
22
+ Requires-Dist: platformdirs
23
+ Provides-Extra: docs
24
+ Requires-Dist: mkdocs<2,>=1.5; extra == "docs"
25
+ Requires-Dist: mkdocs-material>=9.5; extra == "docs"
26
+ Requires-Dist: mkdocs-include-markdown-plugin>=6.0; extra == "docs"
27
+ Dynamic: license-file
28
+
29
+ # papers
30
+
31
+ [![pypi](https://img.shields.io/pypi/v/papers-cli)](https://pypi.org/project/papers-cli)
32
+ [![python](https://img.shields.io/badge/python-3.9-blue.svg)]()
33
+ [![python](https://img.shields.io/badge/python-3.14t-blue.svg)]()
34
+ [![test](https://github.com/perrette/papers/workflows/CI/badge.svg?query=branch%3Amaster)](https://github.com/perrette/papers/actions)
35
+ [![docs](https://img.shields.io/badge/docs-perrette.github.io%2Fpapers-blue)](https://perrette.github.io/papers/)
36
+
37
+ Command-line tool to manage your bibliography (PDFs + BibTeX).
38
+
39
+ Disclaimer: This tool requires further development and testing, and might never
40
+ be fully production-ready (contributors welcome). \
41
+ That said, it is becoming useful :)
42
+
43
+ <!-- intro-start -->
44
+ A light-weight, command-line bibliography management tool built like `git`,
45
+ with a main command `papers` and a range of subcommands. It lets you:
46
+
47
+ - **Maintain a PDF library** with appropriate, customisable file naming.
48
+ - **Maintain one or several BibTeX collections**, linked to their PDFs.
49
+ - **Fetch metadata from the internet** — enough PDF-parsing capability to pull
50
+ metadata from [crossref](https://github.com/CrossRef/rest-api-doc) (by DOI or
51
+ fulltext search) or google scholar.
52
+ - **Search and act on your library** with a `find`/`grep`-inspired
53
+ `papers list` (tag, edit, delete, rename, fetch, deduplicate).
54
+ - **Stay in control** — plain BibTeX files, optional git tracking, and
55
+ undo/redo for every change.
56
+ <!-- intro-end -->
57
+
58
+ ## 📖 Documentation
59
+
60
+ Full documentation lives at **<https://perrette.github.io/papers/>**:
61
+
62
+ - [Installation](https://perrette.github.io/papers/installation/) (incl. external dependencies)
63
+ - [Quickstart](https://perrette.github.io/papers/quickstart/)
64
+ - [Adding entries](https://perrette.github.io/papers/adding-entries/)
65
+ - [Listing and searching](https://perrette.github.io/papers/listing/)
66
+ - [Renaming files and keys](https://perrette.github.io/papers/renaming/)
67
+ - [Configuration and install](https://perrette.github.io/papers/configuration/)
68
+ - Also: [managing your library](https://perrette.github.io/papers/library-management/),
69
+ [git integration](https://perrette.github.io/papers/git/),
70
+ [undo/redo](https://perrette.github.io/papers/undo-redo/),
71
+ [features](https://perrette.github.io/papers/features/)
72
+
73
+ ## Install
74
+
75
+ ```bash
76
+ pip install papers-cli
77
+ ```
78
+
79
+ Note there is another project registered on PyPI as `papers`, hence
80
+ `papers-cli` for command-line-interface. See the
81
+ [installation page](https://perrette.github.io/papers/installation/) for
82
+ external dependencies.
83
+
84
+ ## Quickstart
85
+
86
+ ```bash
87
+ # extract metadata from a PDF and add it to your library
88
+ papers add esd-4-11-2013.pdf --rename --copy --bibtex papers.bib --filesdir files
89
+
90
+ # list and search your library
91
+ papers list perrette scaling approach sea level
92
+ ```
93
+
94
+ See the [quickstart](https://perrette.github.io/papers/quickstart/) for a full
95
+ walkthrough.
96
+
97
+ Consult inline help (`papers --help`, `papers <command> --help`) for more
98
+ detailed documentation.
99
+
100
+ ## From the same author
101
+
102
+ A few other open-source tools I maintain.
103
+
104
+ **Scientific writing & data**
105
+
106
+ - [**texmark**](https://perrette.github.io/texmark/) — write scientific articles in Markdown and convert them to journal-ready LaTeX/PDF.
107
+ - [**datamanifest**](https://perrette.github.io/datamanifest/) — declarative, reproducible dataset management. *(See also the [datamanifest.toml](https://perrette.github.io/datamanifest.toml/) format spec and the [DataManifest.jl](https://awi-esc.github.io/DataManifest.jl/) Julia port.)*
108
+
109
+ **Speech to Text (dictate) and Text to Speech (read-aloud) tools**
110
+
111
+ - [**scribe**](https://perrette.github.io/scribe/) — speech-to-text dictation.
112
+ - [**bard**](https://perrette.github.io/bard/) — text-to-speech reader.
@@ -0,0 +1,84 @@
1
+ # papers
2
+
3
+ [![pypi](https://img.shields.io/pypi/v/papers-cli)](https://pypi.org/project/papers-cli)
4
+ [![python](https://img.shields.io/badge/python-3.9-blue.svg)]()
5
+ [![python](https://img.shields.io/badge/python-3.14t-blue.svg)]()
6
+ [![test](https://github.com/perrette/papers/workflows/CI/badge.svg?query=branch%3Amaster)](https://github.com/perrette/papers/actions)
7
+ [![docs](https://img.shields.io/badge/docs-perrette.github.io%2Fpapers-blue)](https://perrette.github.io/papers/)
8
+
9
+ Command-line tool to manage your bibliography (PDFs + BibTeX).
10
+
11
+ Disclaimer: This tool requires further development and testing, and might never
12
+ be fully production-ready (contributors welcome). \
13
+ That said, it is becoming useful :)
14
+
15
+ <!-- intro-start -->
16
+ A light-weight, command-line bibliography management tool built like `git`,
17
+ with a main command `papers` and a range of subcommands. It lets you:
18
+
19
+ - **Maintain a PDF library** with appropriate, customisable file naming.
20
+ - **Maintain one or several BibTeX collections**, linked to their PDFs.
21
+ - **Fetch metadata from the internet** — enough PDF-parsing capability to pull
22
+ metadata from [crossref](https://github.com/CrossRef/rest-api-doc) (by DOI or
23
+ fulltext search) or google scholar.
24
+ - **Search and act on your library** with a `find`/`grep`-inspired
25
+ `papers list` (tag, edit, delete, rename, fetch, deduplicate).
26
+ - **Stay in control** — plain BibTeX files, optional git tracking, and
27
+ undo/redo for every change.
28
+ <!-- intro-end -->
29
+
30
+ ## 📖 Documentation
31
+
32
+ Full documentation lives at **<https://perrette.github.io/papers/>**:
33
+
34
+ - [Installation](https://perrette.github.io/papers/installation/) (incl. external dependencies)
35
+ - [Quickstart](https://perrette.github.io/papers/quickstart/)
36
+ - [Adding entries](https://perrette.github.io/papers/adding-entries/)
37
+ - [Listing and searching](https://perrette.github.io/papers/listing/)
38
+ - [Renaming files and keys](https://perrette.github.io/papers/renaming/)
39
+ - [Configuration and install](https://perrette.github.io/papers/configuration/)
40
+ - Also: [managing your library](https://perrette.github.io/papers/library-management/),
41
+ [git integration](https://perrette.github.io/papers/git/),
42
+ [undo/redo](https://perrette.github.io/papers/undo-redo/),
43
+ [features](https://perrette.github.io/papers/features/)
44
+
45
+ ## Install
46
+
47
+ ```bash
48
+ pip install papers-cli
49
+ ```
50
+
51
+ Note there is another project registered on PyPI as `papers`, hence
52
+ `papers-cli` for command-line-interface. See the
53
+ [installation page](https://perrette.github.io/papers/installation/) for
54
+ external dependencies.
55
+
56
+ ## Quickstart
57
+
58
+ ```bash
59
+ # extract metadata from a PDF and add it to your library
60
+ papers add esd-4-11-2013.pdf --rename --copy --bibtex papers.bib --filesdir files
61
+
62
+ # list and search your library
63
+ papers list perrette scaling approach sea level
64
+ ```
65
+
66
+ See the [quickstart](https://perrette.github.io/papers/quickstart/) for a full
67
+ walkthrough.
68
+
69
+ Consult inline help (`papers --help`, `papers <command> --help`) for more
70
+ detailed documentation.
71
+
72
+ ## From the same author
73
+
74
+ A few other open-source tools I maintain.
75
+
76
+ **Scientific writing & data**
77
+
78
+ - [**texmark**](https://perrette.github.io/texmark/) — write scientific articles in Markdown and convert them to journal-ready LaTeX/PDF.
79
+ - [**datamanifest**](https://perrette.github.io/datamanifest/) — declarative, reproducible dataset management. *(See also the [datamanifest.toml](https://perrette.github.io/datamanifest.toml/) format spec and the [DataManifest.jl](https://awi-esc.github.io/DataManifest.jl/) Julia port.)*
80
+
81
+ **Speech to Text (dictate) and Text to Speech (read-aloud) tools**
82
+
83
+ - [**scribe**](https://perrette.github.io/scribe/) — speech-to-text dictation.
84
+ - [**bard**](https://perrette.github.io/bard/) — text-to-speech reader.
@@ -0,0 +1,61 @@
1
+ # Adding entries
2
+
3
+ The `papers add` command adds entries to your library, with or without a PDF
4
+ attachment.
5
+
6
+ ## Add a PDF (extract metadata automatically)
7
+
8
+ ```
9
+ $> papers add esd-4-11-2013.pdf --rename --copy --bibtex papers.bib --filesdir files --info
10
+ INFO:papers:found doi:10.5194/esd-4-11-2013
11
+ INFO:papers:new entry: perrette_landerer2013
12
+ 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
13
+ INFO:papers:renamed file(s): 1
14
+ ```
15
+
16
+ That is equivalent to doing:
17
+
18
+ ```
19
+ papers extract esd-4-11-2013.pdf > entry.bib
20
+ papers add entry.bib --bibtex papers.bib --attachment esd-4-11-2013.pdf --rename --copy
21
+ ```
22
+
23
+ See [Renaming files and keys](renaming.md) for how to specify file naming
24
+ patterns.
25
+
26
+ ## Add a whole directory of PDFs
27
+
28
+ It is possible to do this on a full directory of files, recursively:
29
+
30
+ ```
31
+ papers add --rename --recursive /home/perette/playground/papers/papers_test
32
+ ```
33
+
34
+ where, above, the `papers_test` directory contains a few PDF files. For each
35
+ PDF, `papers` will attempt to extract the metadata and add the relevant file to
36
+ the bibliography, and rename files into the files directory.
37
+
38
+ ## Add an entry from its DOI
39
+
40
+ If you already know the DOI of a PDF, and don't want to gamble the fulltext
41
+ search and match, you can indicate it via `--doi`:
42
+
43
+ ```
44
+ papers add esd-4-11-2013.pdf --doi 10.5194/esd-4-11-2013 --bibtex papers.bib
45
+ ```
46
+
47
+ The `add` command above also works without any PDF (create a bibtex entry
48
+ without file attachment):
49
+
50
+ ```
51
+ papers add --doi 10.5194/esd-4-11-2013 --bibtex papers.bib
52
+ ```
53
+
54
+ ## Add an entry without DOI from bibtex + PDF
55
+
56
+ Some old files don't have a DOI. The best approach is to add the entry from its
57
+ bibtex:
58
+
59
+ ```
60
+ papers add entry.bib --attachment esd-4-11-2013.pdf
61
+ ```
@@ -0,0 +1,25 @@
1
+ # Comparison with other tools
2
+
3
+ ## Why not JabRef, Zotero or Mendeley (or...) ?
4
+
5
+ - JabRef (2.10) is nice, light-weight, but is not so good at managing PDFs.
6
+ - Zotero (5.0) features excellent PDF import capability, but it needs to be done
7
+ manually one by one and is a little slow. Not very flexible.
8
+ - Mendeley (1.17) is perfect at automatically extracting metadata from
9
+ downloaded PDFs and managing your PDF library, but it is not open source, and
10
+ many issues remain (own experience, Ubuntu 14.04, Desktop Version 1.17):
11
+ - very unstable
12
+ - PDF automatic naming is too verbose, and sometimes the behaviour is
13
+ unexpected (some PDFs remain in an obscure Downloaded folder, instead of
14
+ in the main collection)
15
+ - somewhat heavy (it offers functions of online syncing, etc)
16
+ - poor search capability (related to the point above)
17
+
18
+ Above-mentioned issues will with no doubt be improved in future releases, but
19
+ they are a starting point for this project. Anyway, a command-line tool is per
20
+ se a good idea for faster development, as noted
21
+ [here](https://forums.zotero.org/discussion/43386/zotero-cli-version), but so
22
+ far I could only find zotero clients for their online API (like
23
+ [pyzotero](https://github.com/urschrei/pyzotero) or
24
+ [zotero-cli](https://github.com/jbaiter/zotero-cli)). Please contact me if you
25
+ know another interesting project.
@@ -0,0 +1,101 @@
1
+ # Configuration and install
2
+
3
+ ## install: make bibtex and files directory persistent
4
+
5
+ ```
6
+ $> papers install --global --bibtex papers.bib --filesdir files
7
+ papers configuration
8
+ * configuration file: /home/perrette/.config/papersconfig.json
9
+ * cache directory: /home/perrette/.cache/papers
10
+ * absolute paths: True
11
+ * files directory: files (1 files, 5.8 MB)
12
+ * bibtex: papers.bib (1 entries)
13
+ ```
14
+
15
+ With `--global`, the configuration applies to the whole user account: any
16
+ `papers` command, from any directory, will know about these settings. A
17
+ fresh `papers install` without scope option is *local* to the current
18
+ directory (see below); re-running `papers install` on an existing install
19
+ keeps its scope, so `--local`/`--global` are only needed to be explicit.
20
+
21
+ Running `papers install` again *updates* the existing configuration: options
22
+ you pass change, everything else is kept. Pass `--reset` to discard the
23
+ existing configuration and start over from defaults. Use `--no-prompt` to
24
+ accept all defaults non-interactively (at the prompts, `Enter` accepts the
25
+ proposed default, typing a value sets it, and `unset` clears it).
26
+
27
+ Type `papers status -v` to check your configuration.
28
+
29
+ You also notice a cache directory. All internet requests such as crossref
30
+ requests are saved in the cache directory. This happens regardless of whether
31
+ `papers` is installed or not.
32
+
33
+ ## Local install
34
+
35
+ A local install keeps separate configurations per project — one bibliography
36
+ per folder. It is the default for a fresh install (`--local` makes it
37
+ explicit):
38
+
39
+ ```
40
+ $> papers install
41
+ Bibtex file name [default to existing: papers.bib] [Enter/path/'unset']:
42
+ Files folder [default to new: papers] [Enter/path/'unset']: pdfs
43
+ papers configuration
44
+ * configuration file: papersconfig.json
45
+ * cache directory: /home/perrette/.cache/papers
46
+ * absolute paths: True
47
+ * git-tracked: False
48
+ * files directory: pdfs (90 files, 337.4 MB)
49
+ * bibtex: papers.bib (82 entries)
50
+ ```
51
+
52
+ Creates a local configuration file (`.papersconfig.json`) in the current
53
+ directory. By default, it expects existing or creates new `papers.bib`
54
+ bibliography and `files` folder in the local directory, though `papers` will
55
+ ask first unless explicitly provided. Note that every call from a subfolder
56
+ will also detect that configuration file (it has priority over global
57
+ install).
58
+
59
+ By default, the local install is meant to be portable with bibtex and files, so
60
+ the file paths are encoded relatively to the bibtex file. If instead absolute
61
+ paths make more sense (example use case: local bibtex file but central PDF
62
+ folder), then simply specify `--absolute-paths`:
63
+
64
+ ```
65
+ papers install --local --absolute-paths --filesdir /path/to/central/pdfs
66
+ ```
67
+
68
+ ## Uninstall
69
+
70
+ Getting confused with papers config files scattered in subfolders? Check the
71
+ config with:
72
+
73
+ ```
74
+ papers status -v
75
+ ```
76
+
77
+ and remove the configuration file by hand (`rm ...`). Or use the `papers
78
+ uninstall` command:
79
+
80
+ ```
81
+ papers uninstall
82
+ ```
83
+
84
+ It removes the configuration file and reports what it leaves behind (the
85
+ bibtex file, the files directory, and the backup directory if any). Pass
86
+ `--remove-backup` to also remove the backup directory.
87
+
88
+ You may repeat `papers status -v` and cleaning until a satisfying state is
89
+ reached, or remove all config files recursively up to (and including) global
90
+ install:
91
+
92
+ ```
93
+ papers uninstall --recursive
94
+ ```
95
+
96
+ ## Relative versus absolute paths
97
+
98
+ By default, the file paths in the bibtex are stored as absolute paths (starting
99
+ with `/`), except for local installs. It is possible to change this behaviour
100
+ explicitly during install or in a case-by-case basis with `--relative-paths` or
101
+ `--absolute-paths`, with or without install.
@@ -0,0 +1,50 @@
1
+ # Features
2
+
3
+ ## Current features
4
+
5
+ - parse PDF to extract DOI
6
+ - fetch bibtex entry from DOI (using crossref API)
7
+ - fetch bibtex entry by fulltext search (using crossref API or google scholar)
8
+ - create and maintain bibtex file
9
+ - add entry as PDF (`papers add ...`)
10
+ - add entry as bibtex (`papers add ...`)
11
+ - scan directory for PDFs (`papers add ...`)
12
+ - rename PDFs according to bibtex key and year (`papers filecheck --rename [--copy]`)
13
+ - some support for attachment
14
+ - merging (`papers check --duplicates ...`)
15
+ - fix entries (`papers check --format-name --encoding unicode --fix-doi --fix-key ...`)
16
+ - configuration file with default bibtex and files directory (`papers install --bibtex BIB --filesdir DIR ...`)
17
+ - integration with git
18
+ - undo/redo command (`papers undo / redo`)
19
+ - display / search / list entries: format as bibtex or key or whatever (`papers list ... [--key-only, -l]`)
20
+ - list + edit or remove entry by key or else (`papers list ... [--edit, --delete]`)
21
+ - fix broken PDF links (`papers filecheck ...`):
22
+ - remove duplicate file names (always) or file copies (`--hash-check`)
23
+ - remove missing link (`--delete-missing`)
24
+ - fix files name after a Mendeley export (`--fix-mendeley`):
25
+ - leading `/` missing is added
26
+ - latex characters, e.g. `{\_}` or `{\'{e}}` replaced with unicode
27
+
28
+ ## Tests
29
+
30
+ Test coverage is improving (now 80%).
31
+
32
+ Currently covers:
33
+
34
+ - `papers extract` (test on a handful of PDFs)
35
+ - parse pdf DOI
36
+ - fetch bibtex on crossref based on DOI
37
+ - fetch bibtex on crossref based on fulltext search
38
+ - fetch bibtex on google-scholar based on fulltext search
39
+ - `papers add`
40
+ - add entry and manage conflict
41
+ - add pdf file, bibtex, directory
42
+ - add one pdf file with attachment (beta, API will change)
43
+ - conflict resolution
44
+ - `papers install`
45
+ - internals:
46
+ - duplicate test with levels `EXACT`, `GOOD`, `FAIR` (the default), `PARTIAL`
47
+ - `papers list`
48
+ - `papers undo / redo` (partial)
49
+ - `papers filecheck --rename` (superficial)
50
+ - `papers check --duplicate` (fix DOI etc.) (superficial)
@@ -0,0 +1,49 @@
1
+ # Git integration
2
+
3
+ ## Git-tracked library
4
+
5
+ By default (when a git binary is available), a fresh `papers install`
6
+ git-tracks any change to the bibtex file. Pass `--no-git` to opt out, and
7
+ `--git-lfs` to also back up the attached files (see below):
8
+
9
+ ```
10
+ $> papers install --bibtex papers.bib --filesdir files [ --no-git | --git-lfs ]
11
+ ```
12
+
13
+ Installs made by older papers versions keep their saved setting; re-run
14
+ `papers install` (or `papers install --edit --git`) to enable git-tracking
15
+ on an existing install.
16
+
17
+ From now on, every change to the library will result in an automatic git
18
+ commit. And the `papers git ...` command will work just as `git ...` executed
19
+ from the backup directory. E.g. `papers git remote add origin *REMOTE URL*`;
20
+ `papers git lfs track files`; `papers git add files`; `papers git push`.
21
+
22
+ Under the hood, every save commits a copy of the bibtex file to the backup
23
+ repository. If `--git-lfs` is passed, the attached files are backed up along
24
+ with the bibtex: they are hard-linked into the backup directory and tracked
25
+ with git-lfs, together with a copy of the bibtex whose file paths point into
26
+ the backup (so the backup is self-contained). Background in
27
+ [issue 51](https://github.com/perrette/papers/issues/51).
28
+
29
+ Backup occurs in a subfolder of `~/.local/share/papers/backups` regardless of
30
+ the type of installation. Type `papers status -v` to find out, or
31
+ `papers backup list` to see every backup directory papers knows of and which
32
+ library each belongs to. Orphaned directories (e.g. whose library was
33
+ deleted) can be cleaned up with `papers backup remove NAME` (glob patterns
34
+ allowed; asks before deleting unless `--force` is passed).
35
+
36
+ Backup directories are named after the bibtex file and its parent folder,
37
+ plus a hash of the full path (e.g. `myproject-references-3f9a1c2b`), so two
38
+ libraries can never share a directory and same-named libraries remain
39
+ recognizable.
40
+ Each directory also contains a `manifest.json` recording the bibtex file it
41
+ backs up; if a backup operation finds a directory that belongs to another
42
+ library (which could happen with directories created by papers versions that
43
+ used the bibtex name alone), it moves the current library to a fresh
44
+ directory instead of mixing the two histories. Directories created by older
45
+ versions keep their name and are adopted as-is.
46
+
47
+ For local installs that are already git-tracked, the feature remains useful as
48
+ it is the basis for `papers undo` and `papers redo` (see
49
+ [Undo and redo](undo-redo.md)).
@@ -0,0 +1,55 @@
1
+ <!--
2
+ Home page. The feature bullets are pulled straight from README.md (single
3
+ source of truth) via the include-markdown plugin; everything else links into
4
+ the guide.
5
+ -->
6
+ # papers
7
+
8
+ Command-line tool to manage your bibliography (PDFs + BibTeX).
9
+
10
+ {%
11
+ include-markdown "../README.md"
12
+ start="<!-- intro-start -->"
13
+ end="<!-- intro-end -->"
14
+ %}
15
+
16
+ ## Get started
17
+
18
+ ```bash
19
+ pip install papers-cli
20
+ papers add mypaper.pdf --rename --copy --bibtex papers.bib --filesdir files
21
+ ```
22
+
23
+ - **[Installation](installation.md)** — pip install and external dependencies.
24
+ - **[Quickstart](quickstart.md)** — extract metadata, add a PDF, list entries.
25
+ - **[Adding entries](adding-entries.md)** — from PDFs, DOIs, bibtex, or whole directories.
26
+ - **[Configuration and install](configuration.md)** — make your bibtex and files directory persistent.
27
+
28
+ ## Guides
29
+
30
+ - [Adding entries](adding-entries.md)
31
+ - [Listing and searching](listing.md)
32
+ - [Renaming files and keys](renaming.md)
33
+ - [Configuration and install](configuration.md)
34
+ - [Managing your library](library-management.md)
35
+ - [Git integration](git.md)
36
+ - [Undo and redo](undo-redo.md)
37
+
38
+ ## About
39
+
40
+ - [Features](features.md)
41
+ - [Comparison with other tools](comparison.md)
42
+
43
+ ## From the same author
44
+
45
+ A few other open-source tools I maintain.
46
+
47
+ **Scientific writing & data**
48
+
49
+ - [**texmark**](https://perrette.github.io/texmark/) — write scientific articles in Markdown and convert them to journal-ready LaTeX/PDF.
50
+ - [**datamanifest**](https://perrette.github.io/datamanifest/) — declarative, reproducible dataset management. *(See also the [datamanifest.toml](https://perrette.github.io/datamanifest.toml/) format spec and the [DataManifest.jl](https://awi-esc.github.io/DataManifest.jl/) Julia port.)*
51
+
52
+ **Speech to Text (dictate) and Text to Speech (read-aloud) tools**
53
+
54
+ - [**scribe**](https://perrette.github.io/scribe/) — speech-to-text dictation.
55
+ - [**bard**](https://perrette.github.io/bard/) — text-to-speech reader.