papers-cli 2.17__tar.gz → 2.17.2__tar.gz

{papers_cli-2.17 → papers_cli-2.17.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: papers-cli
-Version: 2.17
+Version: 2.17.2
 Summary: utilities to keep your PDF library organized
 Author-email: Mahé Perrette <mahe.perrette@gmail.com>
 License: MIT

papers_cli-2.17.2/docs/installation.md

@@ -0,0 +1,47 @@
+# Installation
+
+## Install papers
+
+```bash
+pip install papers-cli
+```
+
+Note there is another project registered on PyPI as `papers`, hence
+`papers-cli` for command-line-interface. The installed command is still
+`papers`.
+
+## Name clash with GNOME Papers
+
+The [GNOME Papers](https://gitlab.gnome.org/GNOME/papers) document viewer
+(the default viewer on recent GNOME desktops) also installs a `papers`
+command; with both installed, whichever comes first in `$PATH` wins. Two
+mitigations are built in:
+
+- The package also installs the command under the unambiguous name
+  `papers-cli` — call that, or set a shell alias (e.g.
+  `alias papers=papers-cli`), on systems where the names collide.
+- Because this command may mask GNOME Papers, `papers somefile.pdf` (a plain
+  existing file instead of a subcommand) opens the file with the system's
+  default viewer rather than erroring — which on a GNOME desktop typically
+  launches GNOME Papers itself, so the viewer keeps working for the common
+  case. Subcommand names always take precedence (`papers ./list` opens a
+  file named `list`; `papers list` lists your library), and viewer-specific
+  flags are not forwarded — call the viewer's binary directly for those.
+
+## Dependencies
+
+- python 3.9+
+- [PyMuPDF](https://github.com/pymupdf/PyMuPDF) (preferred) or
+  [poppler-utils](https://en.wikipedia.org/wiki/Poppler_(software))
+  (only `pdftotext`; deprecated): convert PDF to text for parsing
+- [bibtexparser](https://bibtexparser.readthedocs.io): parse bibtex files
+- [crossrefapi](https://github.com/fabiobatalha/crossrefapi): make polite
+  requests to the 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
+
+The Python dependencies are installed automatically with `pip`.

{papers_cli-2.17 → papers_cli-2.17.2}/papers/__main__.py

@@ -731,9 +731,21 @@ def listcmd(parser, o, config):
 
 
 def opencmd(parser, o, config):
-    biblio = get_biblio(config)
-    entries_by_key = {biblio.key(e): e for e in biblio.entries}
+    biblio = None
+    entries_by_key = {}
     for key in o.key:
+        # an existing file is opened directly with the system viewer; anything
+        # else is looked up as an entry key in the bibliography
+        if os.path.isfile(key):
+            logger.info(f"opening {key} ...")
+            view_pdf(key)
+            continue
+        if biblio is None:
+            try:
+                biblio = get_biblio(config)
+            except ValueError:
+                raise PapersExit(f"'{key}' is not an existing file, and no bibliography is configured to look it up as a key")
+            entries_by_key = {biblio.key(e): e for e in biblio.entries}
         e = entries_by_key.get(key.lower())
         if e is None:
             logger.error(f'no entry found with key: {key}')
@@ -1040,8 +1052,8 @@ def get_parser(config=None):
 
     # open
     # ====
-    openp = subparsers.add_parser('open', description='open the file(s) attached to entries', parents=[cfg])
-    openp.add_argument('key', nargs='+', help='entry key(s), case-insensitive (shortcut for `papers list --key KEY --open`)')
+    openp = subparsers.add_parser('open', description='open entry attachments or files with the system viewer', parents=[cfg])
+    openp.add_argument('key', nargs='+', help='entry key(s) (case-insensitive), or existing file path(s) to open directly')
 
     # doi
     # ===
@@ -1125,6 +1137,22 @@ def main(args=None):
 
     parser, subparsers = get_parser(config)
 
+    # viewer passthrough (#107): this command often masks the GNOME Papers
+    # document viewer in $PATH, so `papers somefile.pdf` opens the file(s)
+    # with the system viewer instead of erroring. xdg-open resolves the
+    # handler via desktop entries, not $PATH, so this typically launches the
+    # masked viewer itself. Subcommand names always take precedence, and any
+    # flag disables the passthrough (it cannot be meant for this tool).
+    argv = sys.argv[1:]
+    if argv and all(not a.startswith('-') for a in argv) \
+            and argv[0] not in subparsers.choices \
+            and all(os.path.isfile(a) for a in argv):
+        for f in argv:
+            print(f"papers-cli: opening {f!r} with the system viewer "
+                  f"(see `papers --help` for the bibliography tool)", file=sys.stderr)
+            view_pdf(f)
+        return
+
     o, args = parser.parse_known_args(args)
 
     if o.version:
@@ -1167,7 +1195,9 @@ def main(args=None):
     elif o.cmd == 'list':
         check_install(subp, o, config) and listcmd(subp, o, config)
     elif o.cmd == 'open':
-        check_install(subp, o, config) and opencmd(subp, o, config)
+        # no install required when opening plain files; opencmd reports the
+        # missing bibliography itself when an argument must be looked up as a key
+        opencmd(subp, o, config)
     elif o.cmd == 'undo':
         check_install(subp, o, config) and undocmd(subp, o, config)
     elif o.cmd == 'redo':

{papers_cli-2.17 → papers_cli-2.17.2}/papers/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.17'
-__version_tuple__ = version_tuple = (2, 17)
+__version__ = version = '2.17.2'
+__version_tuple__ = version_tuple = (2, 17, 2)
 
-__commit_id__ = commit_id = 'gaa9613af4'
+__commit_id__ = commit_id = 'g7e17d470e'

{papers_cli-2.17 → papers_cli-2.17.2}/papers_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: papers-cli
-Version: 2.17
+Version: 2.17.2
 Summary: utilities to keep your PDF library organized
 Author-email: Mahé Perrette <mahe.perrette@gmail.com>
 License: MIT

{papers_cli-2.17 → papers_cli-2.17.2}/papers_cli.egg-info/entry_points.txt

@@ -1,2 +1,3 @@
 [console_scripts]
 papers = papers.__main__:main_clean_exit
+papers-cli = papers.__main__:main_clean_exit

{papers_cli-2.17 → papers_cli-2.17.2}/pyproject.toml

@@ -43,11 +43,18 @@ docs = [
 homepage = "https://github.com/perrette/papers"
 Documentation = "https://perrette.github.io/papers/"
 
+[tool.setuptools]
+# explicit: auto-discovery fails on stray top-level dirs (site/, notes/...)
+packages = ["papers"]
+
 [tool.setuptools_scm]
 write_to = "papers/_version.py"
 
 [project.scripts]
 papers = "papers.__main__:main_clean_exit"
+# unambiguous alternative for systems where `papers` clashes with the
+# GNOME Papers document viewer (issue #107)
+papers-cli = "papers.__main__:main_clean_exit"
 
 [tool.tox]
 # Tox (https://tox.readthedocs.io/) is a tool for running tests

{papers_cli-2.17 → papers_cli-2.17.2}/tests/test_list.py

@@ -1,5 +1,5 @@
 import bibtexparser
-from tests.common import LocalInstallTest, Biblio, tempfile
+from tests.common import LocalInstallTest, BaseTest, Biblio, tempfile
 from papers.utils import strip_all
 
 bibtex = """@article{Perrette_2011,
@@ -246,3 +246,43 @@ class OpenCmdTest(LocalInstallTest):
 
     def test_open_unknown_key(self):
         self.papers('open NoSuchKey')  # logs an error, does not crash
+
+    def test_open_file_path(self):
+        # `papers open` also accepts existing file paths directly
+        from unittest.mock import patch
+        f = self._path('direct.pdf')
+        open(f, 'w').write('x')
+        with patch('papers.__main__.view_pdf') as viewer:
+            self.papers(f'open {f}')
+            viewer.assert_called_once_with(f)
+
+    def test_bare_file_argument_opens_viewer(self):
+        # `papers somefile.pdf` behaves like the (possibly masked) document
+        # viewer: the file is opened with the system viewer (issue #107)
+        from unittest.mock import patch
+        f = self._path('direct.pdf')
+        open(f, 'w').write('x')
+        with patch('papers.__main__.view_pdf') as viewer:
+            self.papers(f'{f}')
+            viewer.assert_called_once_with(f)
+
+    def test_subcommand_wins_over_file(self):
+        # a file named like a subcommand does not hijack the CLI
+        from unittest.mock import patch
+        open(self._path('status'), 'w').write('x')
+        with patch('papers.__main__.view_pdf') as viewer:
+            self.papers('status')
+            viewer.assert_not_called()
+
+
+class ViewerPassthroughNoInstallTest(BaseTest):
+    anotherbib_content = None
+
+    def test_bare_file_argument_without_install(self):
+        # the viewer passthrough must work without any papers install
+        from unittest.mock import patch
+        f = self._path('doc.pdf')
+        open(f, 'w').write('x')
+        with patch('papers.__main__.view_pdf') as viewer:
+            self.papers(f'{f}')
+            viewer.assert_called_once_with(f)

papers_cli-2.17/docs/installation.md

@@ -1,29 +0,0 @@
-# Installation
-
-## Install papers
-
-```bash
-pip install papers-cli
-```
-
-Note there is another project registered on PyPI as `papers`, hence
-`papers-cli` for command-line-interface. The installed command is still
-`papers`.
-
-## Dependencies
-
-- python 3.9+
-- [PyMuPDF](https://github.com/pymupdf/PyMuPDF) (preferred) or
-  [poppler-utils](https://en.wikipedia.org/wiki/Poppler_(software))
-  (only `pdftotext`; deprecated): convert PDF to text for parsing
-- [bibtexparser](https://bibtexparser.readthedocs.io): parse bibtex files
-- [crossrefapi](https://github.com/fabiobatalha/crossrefapi): make polite
-  requests to the 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
-
-The Python dependencies are installed automatically with `pip`.