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

{papers_cli-2.17.1 → papers_cli-2.17.3}/PKG-INFO

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

{papers_cli-2.17.1 → papers_cli-2.17.3}/docs/installation.md

@@ -14,10 +14,23 @@ Note there is another project registered on PyPI as `papers`, hence
 
 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. The
-package therefore 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.
+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, a call whose arguments are all
+  existing files (paths or `file://` URIs, as passed by file managers through
+  the viewer's desktop entry) is handed over unchanged to the next `papers`
+  executable in `$PATH` that is not this tool, i.e. GNOME Papers itself.
+  Double-clicking a PDF and `papers somefile.pdf` therefore keep opening the
+  viewer. If no other `papers` is found, the files are opened with the
+  system's default viewer (`xdg-open`) instead; should that lead back to
+  this command, it stops with an error rather than looping. Subcommand names
+  always take precedence (`papers ./list` opens a file named `list`;
+  `papers list` lists your library), and any flag disables the hand-over —
+  call the viewer's binary directly for viewer-specific flags.
 
 ## Dependencies
 

{papers_cli-2.17.1 → papers_cli-2.17.3}/papers/__main__.py

@@ -24,7 +24,7 @@ from papers.bib import (Biblio, FUZZY_RATIO, DEFAULT_SIMILARITY, entry_filecheck
                         backupfile as backupfile_func, isvalidkey, DuplicateKeyError, clean_filesdir,
                         are_duplicates, download_url, get_biblio)
 from papers.install import resolve_install, apply_install, InputAsker, DefaultAsker
-from papers.utils import view_pdf, open_folder, PapersExit
+from papers.utils import view_pdf, open_folder, PapersExit, file_uri_to_path, find_masked_viewer
 from papers.backup import (silent_backup_bib, restore_from_backupdir,
                            git_undo, git_redo, git_restore_state, list_backup_dirs)
 from papers import __version__
@@ -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}')
@@ -782,7 +794,10 @@ def get_parser(config=None):
     keyfmt = argparse.ArgumentParser(add_help=False)
     grp = keyfmt.add_argument_group('bibtex key format')
     grp.add_argument('--key-template', default=config.keyformat.template,
-        help='python template for generating keys (default:%(default)s)')
+        help='''python template for generating keys (default:%(default)s).
+        The template applies to entries generated from a PDF or a DOI;
+        entries added from a bibtex file keep their original key unless
+        -u/--update-key is passed.''')
     grp.add_argument('--key-author-num', type=int, default=config.keyformat.author_num,
         help='number of authors to include in key (default:%(default)s)')
     grp.add_argument('--key-author-sep', default=config.keyformat.author_sep,
@@ -872,7 +887,10 @@ def get_parser(config=None):
     grp.add_argument('--no-merge-files', action='store_true',
         help='distinct "file" field considered a conflict, all other things being equal')
     grp.add_argument('-u', '--update-key', action='store_true',
-        help='update added key according to any existing duplicate (otherwise an error might be raised on identical insert key)')
+        help='''regenerate the key of added entries from the key template
+        (see "bibtex key format" options); if a duplicate is found, use the
+        existing entry's key instead (otherwise an error might be raised on
+        identical insert key)''')
     # grp.add_argument('-f', '--force', action='store_true', help='no interactive')
     grp.add_argument('-m', '--mode', default='i', choices=['u', 'U', 'o', 's', 'r', 'i', 'a'],
         help='''if duplicates are found, the default is to start an (i)nteractive dialogue,
@@ -1040,8 +1058,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
     # ===
@@ -1107,6 +1125,10 @@ def handle_logging(o):
     logger.debug("LOGGER LEVEL: "+logging.getLevelName(logger.getEffectiveLevel()))
 
 
+# set while handing files to the system viewer, to detect a passthrough loop (#107)
+VIEWER_PASSTHROUGH_ENV = 'PAPERS_CLI_VIEWER_PASSTHROUGH'
+
+
 def main(args=None):
     papers.config.DRYRUN = False  # reset in case main() if called directly
     if args is not None:
@@ -1125,6 +1147,37 @@ def main(args=None):
 
     parser, subparsers = get_parser(config)
 
+    # viewer passthrough (#107): this command often masks the GNOME Papers
+    # document viewer in $PATH. Its desktop entry runs `papers %U`, so file
+    # managers and xdg-open land here with file paths or file:// URIs. When
+    # every argument is an existing file, the call is handed over unchanged
+    # to the masked viewer (the next `papers` on $PATH that is not this tool).
+    # xdg-open is only a fallback when there is no such viewer: it resolves
+    # the desktop entry, which may lead back to this command, hence the
+    # environment guard against a loop. 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(file_uri_to_path(a)) for a in argv):
+        viewer = find_masked_viewer()
+        if viewer:
+            print(f"papers-cli: passing {' '.join(map(repr, argv))} to {viewer} "
+                  f"(see `papers --help` for the bibliography tool)", file=sys.stderr)
+            os.execv(viewer, [viewer] + argv)
+            return  # only reached when os.execv is mocked
+        if os.environ.get(VIEWER_PASSTHROUGH_ENV):
+            raise PapersExit("the system viewer for these files leads back to this "
+                             "command, and no other `papers` viewer is in $PATH")
+        os.environ[VIEWER_PASSTHROUGH_ENV] = '1'  # inherited by the viewer
+        for a in argv:
+            f = file_uri_to_path(a)
+            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 +1220,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.1 → papers_cli-2.17.3}/papers/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.17.1'
-__version_tuple__ = version_tuple = (2, 17, 1)
+__version__ = version = '2.17.3'
+__version_tuple__ = version_tuple = (2, 17, 3)
 
-__commit_id__ = commit_id = 'g6a373feeb'
+__commit_id__ = commit_id = 'g7999cf082'

{papers_cli-2.17.1 → papers_cli-2.17.3}/papers/utils.py

@@ -203,6 +203,42 @@ def view_pdf(filepath):
         subprocess.call(('xdg-open', filepath))
 
 
+def file_uri_to_path(arg):
+    """Return the local path of a file:// URI, or `arg` unchanged otherwise
+
+    Desktop entries launch viewers with `%U`, i.e. with file:// URIs.
+    """
+    if arg.startswith('file://'):
+        from urllib.parse import urlparse, unquote
+        return unquote(urlparse(arg).path)
+    return arg
+
+
+def _is_papers_cli_script(path):
+    """True if `path` is a console script of this package (`papers` or `papers-cli`)"""
+    try:
+        with open(path, 'rb') as f:
+            head = f.read(1024)
+    except OSError:
+        return False
+    return b'papers.__main__' in head
+
+
+def find_masked_viewer(name='papers'):
+    """Return the first `name` executable on $PATH that is not this tool, or None
+
+    This tool's `papers` command often masks the GNOME Papers document viewer
+    in $PATH (issue #107). Console scripts of this package are recognized by
+    their content, so other installs of it (pipx, venvs) are skipped too.
+    """
+    for d in os.environ.get('PATH', '').split(os.pathsep):
+        candidate = os.path.join(d or '.', name)
+        if os.path.isfile(candidate) and os.access(candidate, os.X_OK) \
+                and not _is_papers_cli_script(candidate):
+            return candidate
+    return None
+
+
 def open_folder(path):
     system_platform = platform.system()
 

{papers_cli-2.17.1 → papers_cli-2.17.3}/papers_cli.egg-info/PKG-INFO

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

{papers_cli-2.17.1 → papers_cli-2.17.3}/papers_cli.egg-info/SOURCES.txt

@@ -42,6 +42,8 @@ papers_cli.egg-info/SOURCES.txt
 papers_cli.egg-info/dependency_links.txt
 papers_cli.egg-info/entry_points.txt
 papers_cli.egg-info/requires.txt
+papers_cli.egg-info/scm_file_list.json
+papers_cli.egg-info/scm_version.json
 papers_cli.egg-info/top_level.txt
 scripts/README.md
 scripts/benchmark_bibtexparser_load.py

papers_cli-2.17.3/papers_cli.egg-info/scm_file_list.json

@@ -0,0 +1,71 @@
+{
+  "files": [
+    ".gitattributes",
+    ".github/FUNDING.yml",
+    ".github/workflows/docs.yml",
+    ".github/workflows/pypi.yml",
+    ".github/workflows/release.yml",
+    ".github/workflows/tests.yml",
+    ".gitignore",
+    "LICENSE",
+    "README.md",
+    "docs/adding-entries.md",
+    "docs/comparison.md",
+    "docs/configuration.md",
+    "docs/features.md",
+    "docs/git.md",
+    "docs/index.md",
+    "docs/installation.md",
+    "docs/library-management.md",
+    "docs/listing.md",
+    "docs/quickstart.md",
+    "docs/renaming.md",
+    "docs/undo-redo.md",
+    "mkdocs.yml",
+    "papers/__init__.py",
+    "papers/__main__.py",
+    "papers/backup.py",
+    "papers/bib.py",
+    "papers/config.py",
+    "papers/duplicate.py",
+    "papers/encoding.py",
+    "papers/entries.py",
+    "papers/extract.py",
+    "papers/filename.py",
+    "papers/install.py",
+    "papers/latexenc.py",
+    "papers/utils.py",
+    "pyproject.toml",
+    "requirements.txt",
+    "scripts/README.md",
+    "scripts/benchmark_bibtexparser_load.py",
+    "scripts/generate_dummy_bib.py",
+    "setup.py",
+    "tests/__init__.py",
+    "tests/common.py",
+    "tests/config.py",
+    "tests/download.py",
+    "tests/downloadedpapers/.gitignore",
+    "tests/downloadedpapers/bg-8-515-2011.pdf",
+    "tests/downloadedpapers/bg-8-515-2011.txt",
+    "tests/downloadedpapers/esd-4-11-2013-supplement.pdf",
+    "tests/downloadedpapers/esd-4-11-2013.pdf",
+    "tests/test_add.py",
+    "tests/test_backup_dirs.py",
+    "tests/test_bib_unit.py",
+    "tests/test_biblio.py",
+    "tests/test_check.py",
+    "tests/test_config_unit.py",
+    "tests/test_duplicates.py",
+    "tests/test_encoding.py",
+    "tests/test_extract.py",
+    "tests/test_extract_unit.py",
+    "tests/test_filecheck.py",
+    "tests/test_filename_unit.py",
+    "tests/test_install.py",
+    "tests/test_latexenc.py",
+    "tests/test_list.py",
+    "tests/test_undo.py",
+    "tests/test_utils.py"
+  ]
+}

papers_cli-2.17.3/papers_cli.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "2.17.3",
+  "distance": 0,
+  "node": "g7999cf08232dd30a1acd83196023e069aaa3dd48",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-01"
+}

{papers_cli-2.17.1 → papers_cli-2.17.3}/tests/test_add.py

@@ -196,6 +196,22 @@ class TestAddBib(BibTest):
         self.assertEqual(bib.db.entries[0]['ID'], self.key1)
         self.assertTrue(self.key2 not in [e['ID'] for e in self.my.db.entries])
 
+    def test_addbib_cmd_update_key(self):
+        # --update-key regenerates the key of entries added from a bibtex file
+        # according to the key template (issue #108)
+        paperscmd(f'add {self.somebib} --bibtex {self.mybib} --update-key')
+        bib = Biblio.load(self.mybib, '')
+        self.assertEqual(len(bib.db.entries), 2)
+        self.assertEqual(bib.db.entries[0]['ID'], self.key1)  # pre-existing entry untouched
+        self.assertEqual(bib.db.entries[1]['ID'], self.newkey2)  # default template {author}{year}
+
+    def test_addbib_cmd_update_key_custom_template(self):
+        paperscmd(f'add {self.somebib} --bibtex {self.mybib} -u --key-template "{{year}}"')
+        bib = Biblio.load(self.mybib, '')
+        self.assertEqual(len(bib.db.entries), 2)
+        self.assertEqual(bib.db.entries[0]['ID'], self.key1)
+        self.assertEqual(bib.db.entries[1]['ID'], self.year)
+
     def test_attachment_fails_with_multiple_entries(self):
         func = lambda: paperscmd(f'add {self.pdf} {self.pdf} --bibtex {self.mybib} --filesdir {self.filesdir} --attachment {self.pdf}')
         self.assertRaises(Exception, func)

{papers_cli-2.17.1 → papers_cli-2.17.3}/tests/test_list.py

@@ -1,5 +1,11 @@
 import bibtexparser
-from tests.common import LocalInstallTest, Biblio, tempfile
+import os
+import unittest
+from unittest.mock import patch
+from urllib.parse import quote
+from tests.common import LocalInstallTest, BaseTest, Biblio, tempfile
+from papers.__main__ import VIEWER_PASSTHROUGH_ENV
+from papers.utils import PapersExit, find_masked_viewer, file_uri_to_path
 from papers.utils import strip_all
 
 bibtex = """@article{Perrette_2011,
@@ -246,3 +252,110 @@ 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: without another `papers` in $PATH, the file is opened with
+        # the system viewer (issue #107)
+        f = self._path('direct.pdf')
+        open(f, 'w').write('x')
+        with patch.dict(os.environ), \
+                patch('papers.__main__.find_masked_viewer', return_value=None), \
+                patch('papers.__main__.view_pdf') as viewer:
+            os.environ.pop(VIEWER_PASSTHROUGH_ENV, None)
+            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
+        open(self._path('status'), 'w').write('x')
+        with patch('papers.__main__.find_masked_viewer') as finder, \
+                patch('papers.__main__.view_pdf') as viewer:
+            self.papers('status')
+            finder.assert_not_called()
+            viewer.assert_not_called()
+
+
+class ViewerPassthroughNoInstallTest(BaseTest):
+    anotherbib_content = None
+
+    def setUp(self):
+        super().setUp()
+        self.pdf = self._path('doc.pdf')
+        open(self.pdf, 'w').write('x')
+        env = patch.dict(os.environ)
+        env.start()
+        self.addCleanup(env.stop)
+        os.environ.pop(VIEWER_PASSTHROUGH_ENV, None)
+
+    def test_bare_file_argument_without_install(self):
+        # the viewer passthrough must work without any papers install
+        with patch('papers.__main__.find_masked_viewer', return_value=None), \
+                patch('papers.__main__.view_pdf') as viewer:
+            self.papers(f'{self.pdf}')
+            viewer.assert_called_once_with(self.pdf)
+
+    def test_file_uri_argument(self):
+        # desktop entries launch the viewer as `papers %U`, i.e. with file:// URIs
+        uri = 'file://' + quote(self.pdf)
+        with patch('papers.__main__.find_masked_viewer', return_value=None), \
+                patch('papers.__main__.view_pdf') as viewer:
+            self.papers(f"'{uri}'")
+            viewer.assert_called_once_with(self.pdf)
+
+    def test_masked_viewer_receives_arguments_unchanged(self):
+        # the masked viewer is exec'd with the original arguments, instead of
+        # xdg-open, which may resolve back to this command
+        uri = 'file://' + quote(self.pdf)
+        with patch('papers.__main__.find_masked_viewer', return_value='/usr/bin/papers'), \
+                patch('papers.__main__.os.execv') as execv, \
+                patch('papers.__main__.view_pdf') as viewer:
+            self.papers(f"'{uri}' {self.pdf}")
+            execv.assert_called_once_with('/usr/bin/papers', ['/usr/bin/papers', uri, self.pdf])
+            viewer.assert_not_called()
+
+    def test_loop_guard(self):
+        # handed to the system viewer once already: stop instead of looping
+        os.environ[VIEWER_PASSTHROUGH_ENV] = '1'
+        with patch('papers.__main__.find_masked_viewer', return_value=None), \
+                patch('papers.__main__.view_pdf') as viewer:
+            with self.assertRaises(PapersExit):
+                self.papers(f'{self.pdf}')
+            viewer.assert_not_called()
+
+
+class FindMaskedViewerTest(unittest.TestCase):
+
+    def _executable(self, path, content):
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        open(path, 'w').write(content)
+        os.chmod(path, 0o755)
+
+    def test_skips_papers_cli_scripts(self):
+        with tempfile.TemporaryDirectory() as d:
+            script = '#!/usr/bin/python3\nfrom papers.__main__ import main_clean_exit\n'
+            self._executable(os.path.join(d, 'venv', 'papers'), script)
+            self._executable(os.path.join(d, 'pipx', 'papers'), script)
+            self._executable(os.path.join(d, 'usr', 'papers'), '#!/bin/sh\n')
+            path = os.pathsep.join(os.path.join(d, x) for x in ['venv', 'empty', 'pipx', 'usr'])
+            with patch.dict(os.environ, {'PATH': path}):
+                self.assertEqual(find_masked_viewer(), os.path.join(d, 'usr', 'papers'))
+
+    def test_none_without_other_viewer(self):
+        with tempfile.TemporaryDirectory() as d:
+            self._executable(os.path.join(d, 'papers'), 'from papers.__main__ import main\n')
+            with patch.dict(os.environ, {'PATH': d}):
+                self.assertIsNone(find_masked_viewer())
+
+    def test_file_uri_to_path(self):
+        self.assertEqual(file_uri_to_path('file:///tmp/a%20b,%203.pdf'), '/tmp/a b, 3.pdf')
+        self.assertEqual(file_uri_to_path('/tmp/a b.pdf'), '/tmp/a b.pdf')