papers-cli 2.17.4__tar.gz → 2.17.5__tar.gz

{papers_cli-2.17.4 → papers_cli-2.17.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: papers-cli
-Version: 2.17.4
+Version: 2.17.5
 Summary: utilities to keep your PDF library organized
 Author-email: Mahé Perrette <mahe.perrette@gmail.com>
 License: MIT
@@ -91,6 +91,12 @@ papers add esd-4-11-2013.pdf --rename --copy --bibtex papers.bib --filesdir file
 papers list perrette scaling approach sea level
 ```
 
+Without `--rename` (`-r`) the PDF is linked where it is: the entry points to
+its current location and nothing is copied into the files directory. `--rename`
+moves it into `--filesdir` under a name made from the name template, and
+`--copy` (`-c`) makes a copy instead of moving (it has no effect without
+`--rename`).
+
 See the [quickstart](https://perrette.github.io/papers/quickstart/) for a full
 walkthrough.
 

{papers_cli-2.17.4 → papers_cli-2.17.5}/README.md

@@ -63,6 +63,12 @@ papers add esd-4-11-2013.pdf --rename --copy --bibtex papers.bib --filesdir file
 papers list perrette scaling approach sea level
 ```
 
+Without `--rename` (`-r`) the PDF is linked where it is: the entry points to
+its current location and nothing is copied into the files directory. `--rename`
+moves it into `--filesdir` under a name made from the name template, and
+`--copy` (`-c`) makes a copy instead of moving (it has no effect without
+`--rename`).
+
 See the [quickstart](https://perrette.github.io/papers/quickstart/) for a full
 walkthrough.
 

papers_cli-2.17.5/docs/adding-entries.md

@@ -0,0 +1,93 @@
+# Adding entries
+
+The `papers add` command adds entries to your library, with or without a PDF
+attachment.
+
+## Add a PDF (extract metadata automatically)
+
+```
+$> 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
+```
+
+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
+```
+
+Without `--rename` (`-r`) the PDF is linked where it is: the `file` field
+points to its current location and nothing is moved or copied into the files
+directory. `--rename` moves the file into `--filesdir` under a name made from
+the name template, and `--copy` (`-c`) makes a copy there instead of moving
+the original (it has no effect without `--rename`). The same applies to the
+files linked from the entries of a bibtex file added with `papers add
+other.bib`: their paths are read relative to that bibtex and stored so that
+they remain valid from your own bibtex (absolute, or relative to it, according
+to `--absolute-paths`/`--relative-paths` or the installed setting); with
+`--rename` they are moved (or copied with `--copy`) into the files directory.
+
+See [Renaming files and keys](renaming.md) for how to specify file naming
+patterns.
+
+## Add a whole directory of PDFs
+
+It is possible to do this on a full directory of files, recursively:
+
+```
+papers add --rename --recursive /home/perette/playground/papers/papers_test
+```
+
+where, above, the `papers_test` directory contains a few PDF files. For each
+PDF, `papers` will attempt to extract the metadata and add the relevant file to
+the bibliography, and rename files into the files directory.
+
+## Add an 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
+```
+
+## Add an entry without DOI from bibtex + PDF
+
+Some old files don't have a DOI. The best approach is to add the entry from its
+bibtex:
+
+```
+papers add entry.bib --attachment esd-4-11-2013.pdf
+```
+
+## Duplicates and keys
+
+Before inserting an entry, `papers add` looks for a duplicate in the library
+(same DOI, or same authors and title). The `-m/--mode` option says what to do
+when one is found: `i` (interactive, the default), `u` (update the existing
+entry with the new entry's missing fields, existing values win), `U` (update
+the existing entry with the new entry's values, new values win), `o`
+(overwrite), `s` (skip the new entry), `a` (append it anyway), `r` (raise an
+error).
+
+Entries added from a bibtex file keep their own key, unless `-u/--update-key`
+is passed, in which case the key is regenerated from the key template (see
+[Renaming files and keys](renaming.md)). Entries extracted from a PDF or
+fetched from a DOI always get a generated key.
+
+With `-u/--update-key`, a duplicate is always merged under the key of the entry
+already in the library, in every mode (`u`, `U`, `o`; with `a` the existing
+entry keeps its key and the appended entry gets a fresh one). Without `-u`,
+modes `u` and `s` keep the existing entry's key, while `U` and `o` take over
+the new entry's key.

{papers_cli-2.17.4 → papers_cli-2.17.5}/docs/quickstart.md

@@ -43,6 +43,9 @@ INFO:papers:renamed file(s): 1
 (the `--info` argument asks for the above output information to be printed out
 to the terminal)
 
+Without `--rename` the PDF is linked where it is, and nothing is copied into
+the files directory; `--copy` only applies together with `--rename`.
+
 See [Adding entries](adding-entries.md) for the full range of ways to add
 entries, and [Renaming files and keys](renaming.md) for how to specify file
 naming patterns.

{papers_cli-2.17.4 → papers_cli-2.17.5}/papers/__main__.py

@@ -69,10 +69,14 @@ def savebib(biblio, config):
     logger.info(f'Saving {config.bibtex}')
     if biblio is not None:
         biblio.save(config.bibtex)
-    if config.file and config.git:
-        silent_backup_bib(biblio, config)
+    if config.git:
+        # the backup comes last: a failure must not undo the work done above
+        try:
+            silent_backup_bib(biblio, config)
+        except Exception as error:
+            logger.error(f'the bibliography was saved, but its git backup failed: {error}')
     else:
-        logger.debug(f'do not backup bib: {config.file}, {config.git}')
+        logger.debug(f'do not backup bib: git is off')
     # if config.git:
         # config.gitcommit()
 
@@ -177,11 +181,43 @@ def uninstallcmd(parser, o, config):
         if os.path.exists(configfile):
             uninstallcmd(parser, o, Config.load(configfile))
 
+def config_for_bibtex(bibtex, config):
+    """The configuration to use when --bibtex is passed on the command line.
+
+    If it is another library than the configured one, the local configuration
+    of that library (searched from the bibtex's directory upwards, as for the
+    current directory) applies: its files directory, git backup and formats.
+    Without one, the current configuration applies to the bibtex, except that
+    it is never written back to disk and the backup goes to a directory of
+    the bibtex's own.
+    """
+    if config.bibtex and os.path.realpath(bibtex) == os.path.realpath(config.bibtex):
+        return config
+
+    configfile = search_config([CONFIG_FILE_LOCAL, os.path.join(".papers", "config.json")],
+                               start_dir=os.path.dirname(os.path.abspath(bibtex)), default=None)
+    if configfile is not None:
+        other = Config.load(check_legacy_config(configfile))
+        if other.bibtex and os.path.realpath(other.bibtex) == os.path.realpath(bibtex):
+            logger.info(f'configuration of {bibtex}: {configfile}')
+            return other
+
+    logger.debug(f'{bibtex} has no configuration of its own: use {config.file} without saving it')
+    config = copy.copy(config)
+    config.file = None
+    if config.git:
+        from papers.backup import resolve_gitdir
+        config.gitdir = resolve_gitdir(bibtex)
+    return config
+
+
 def check_install(parser, o, config, bibtex_must_exist=True):
     """
     Given an option and config, checks to see if the install is done correctly on this filesystem.
+    Returns the configuration to use (see config_for_bibtex).
     """
     if getattr(o, "bibtex", None) is not None:
+        config = config_for_bibtex(o.bibtex, config)
         config.bibtex = o.bibtex
     if getattr(o, "filesdir", None) is not None:
         config.filesdir = o.filesdir
@@ -201,7 +237,7 @@ def check_install(parser, o, config, bibtex_must_exist=True):
         raise PapersExit()
     logger.info(f'bibtex: {config.bibtex!r}')
     logger.info(f'filesdir: {config.filesdir!r}')
-    return True
+    return config
 
 
 def _print_biblio_diff(biblio_init, biblio, touched_entries, show_existing=False):
@@ -781,9 +817,9 @@ def get_parser(config=None):
 
     cfg = argparse.ArgumentParser(add_help=False, parents=[loggingp])
     grp = cfg.add_argument_group('config')
-    grp.add_argument('--filesdir', default=None,
+    grp.add_argument('--filesdir', default=None, type=file_uri_to_path,
         help=f'files directory (default: {config.filesdir}')
-    grp.add_argument('--bibtex', default=None,
+    grp.add_argument('--bibtex', default=None, type=file_uri_to_path,
         help=f'bibtex database (default: {config.bibtex}')
     grp.add_argument('--dry-run', action='store_true',
         help='no PDF renaming/copying, no bibtex writing on disk (for testing)')
@@ -878,7 +914,7 @@ def get_parser(config=None):
     # ===
     addp = subparsers.add_parser('add', description='add PDF(s) or bibtex(s) to library',
         parents=[cfg, namefmt, keyfmt])
-    addp.add_argument('file', nargs='*', default=[])
+    addp.add_argument('file', nargs='*', default=[], type=file_uri_to_path)
     # addp.add_argument('-f','--force', action='store_true', help='disable interactive')
 
     grp = addp.add_argument_group('duplicate check')
@@ -918,12 +954,17 @@ def get_parser(config=None):
     grp.add_argument('--no-query-fulltext', action='store_true', help='do not attempt to query fulltext in case doi query fails')
     grp.add_argument('--scholar', action='store_true', help='use google scholar instead of crossref')
 
-    grp = addp.add_argument_group('attached files')
-    grp.add_argument('-a','--attachment', nargs='+') #'supplementary material')
+    grp = addp.add_argument_group('attached files',
+        description='''Without -r/--rename, the PDF (and the files of a bibtex entry) are linked
+        where they are: the file field points to their current location and nothing is
+        moved or copied into the files directory. -r moves them into the files directory
+        (--filesdir) under a name made from the name template; with -c the original is
+        kept and a copy is made instead (-c has no effect without -r).''')
+    grp.add_argument('-a','--attachment', nargs='+', type=file_uri_to_path, help='attach these files to the entry (supplementary material)')
     grp.add_argument('-r','--rename', action='store_true',
-        help='rename PDFs according to key')
+        help='move the files into the files directory, renamed according to the name template')
     grp.add_argument('-c','--copy', action='store_true',
-        help='copy file instead of moving them')
+        help='with -r, copy the files instead of moving them')
 
     grp = addp.add_argument_group('actions')
     grp.add_argument('-e', '--edit', action='store_true', help='edit entry')
@@ -1048,7 +1089,7 @@ def get_parser(config=None):
     grp.add_argument('-e', '--edit', action='store_true', help='interactive edit text file with entries, and re-insert them')
     grp.add_argument('--fetch', action='store_true', help='fetch and fix metadata')
     grp.add_argument('--add-keywords', '--add-tag', nargs='+', help='add keywords to the selected entries')
-    grp.add_argument('--add-files', nargs='+', help='add files to the selected entries (only one entry must be listed)')
+    grp.add_argument('--add-files', nargs='+', type=file_uri_to_path, help='add files to the selected entries (only one entry must be listed)')
     grp.add_argument('--rename', action='store_true', help='rename file(s) of the listed entries into the files folder (also applies to files added via --add-files)')
     grp.add_argument('--copy', action='store_true', help='in combination with --rename, keep a copy of the file(s) in their original location')
     grp.add_argument('-o', '--open', action='store_true', help='open attachments (if any)')
@@ -1059,12 +1100,12 @@ def get_parser(config=None):
     # 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')
+    openp.add_argument('key', nargs='+', type=file_uri_to_path, help='entry key(s) (case-insensitive), or existing file path(s) to open directly')
 
     # doi
     # ===
     doip = subparsers.add_parser('doi', description='parse DOI from PDF', parents=[loggingp])
-    doip.add_argument('pdf')
+    doip.add_argument('pdf', type=file_uri_to_path)
     doip.add_argument('--image', action='store_true', help='convert to image and use tesseract instead of pdftotext')
 
     # fetch
@@ -1076,7 +1117,7 @@ def get_parser(config=None):
     # extract
     # ========
     extractp = subparsers.add_parser('extract', description='extract pdf metadata', parents=[loggingp])
-    extractp.add_argument('pdf', nargs='+', help='one or several PDF files')
+    extractp.add_argument('pdf', nargs='+', type=file_uri_to_path, help='one or several PDF files')
     extractp.add_argument('--recursive', action='store_true', help='accept directories and scan them for PDF files')
     extractp.add_argument('-n', '--word-count', type=int, default=200)
     extractp.add_argument('--fulltext', action='store_true', help='fulltext only (otherwise DOI-based)')
@@ -1212,23 +1253,23 @@ def main(args=None):
         uninstallcmd(subp, o, config)
         print(config.status(verbose=True))
     elif o.cmd == 'add':
-        check_install(subp, o, config) and addcmd(subp, o, config)
+        addcmd(subp, o, check_install(subp, o, config))
     elif o.cmd == 'check':
-        check_install(subp, o, config) and checkcmd(subp, o, config)
+        checkcmd(subp, o, check_install(subp, o, config))
     elif o.cmd == 'filecheck':
-        check_install(subp, o, config) and filecheckcmd(subp, o, config)
+        filecheckcmd(subp, o, check_install(subp, o, config))
     elif o.cmd == 'list':
-        check_install(subp, o, config) and listcmd(subp, o, config)
+        listcmd(subp, o, check_install(subp, o, config))
     elif o.cmd == 'open':
         # 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)
+        undocmd(subp, o, check_install(subp, o, config))
     elif o.cmd == 'redo':
-        check_install(subp, o, config) and redocmd(subp, o, config)
+        redocmd(subp, o, check_install(subp, o, config))
     elif o.cmd == 'restore-backup':
-        check_install(subp, o, config, bibtex_must_exist=False) and restorecmd(subp, o, config)
+        restorecmd(subp, o, check_install(subp, o, config, bibtex_must_exist=False))
     elif o.cmd == 'git':
         if not installed:
             subp.error('papers must be installed to use git command')

{papers_cli-2.17.4 → papers_cli-2.17.5}/papers/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.17.4'
-__version_tuple__ = version_tuple = (2, 17, 4)
+__version__ = version = '2.17.5'
+__version_tuple__ = version_tuple = (2, 17, 5)
 
-__commit_id__ = commit_id = 'gc3df29014'
+__commit_id__ = commit_id = 'g6f089411a'

{papers_cli-2.17.4 → papers_cli-2.17.5}/papers/backup.py

@@ -244,13 +244,21 @@ def backup_bib(biblio, config, message=None):
 
     if not config.git:
         raise PapersExit('cannot backup without --git enabled')
+    if not config.gitdir:
+        config.gitdir = resolve_gitdir(config.bibtex)
     backupdir = Path(config.gitdir)
-    backupdir.mkdir(exist_ok=True)
+    backupdir.mkdir(parents=True, exist_ok=True)
 
     # never mix the histories of two libraries in one backup directory
     check_gitdir_ownership(config)
     backupdir = Path(config.gitdir)  # may have been re-allocated
 
+    # a backup directory that was never initialized (or removed since the install)
+    if not (backupdir / ".git").exists():
+        logger.info(f"initialize backup repository: {backupdir}")
+        run_git(config.gitdir, ["init"])
+        write_manifest(config.gitdir, config.bibtex)
+
     # a snapshot made while undone must append to the full history
     adopt_legacy_undone_state(config.gitdir)
 

{papers_cli-2.17.4 → papers_cli-2.17.5}/papers/bib.py

@@ -463,7 +463,13 @@ class Biblio:
                 candidate.key = candidate_key_after
             entries = []
             for e in resolved:
-                entries.extend( self.insert_entry(e, update_key, rename=rename, copy=copy) )
+                # the existing entry keeps its key (and so does the single
+                # resolved entry that carries it, e.g. an overwrite with
+                # --update-key): only entries new to the library get a key
+                # regenerated from the template
+                keeps_key = e is candidate or (
+                    len(resolved) == 1 and get_entry_val(e, 'ID', '') == candidate_key_before)
+                entries.extend( self.insert_entry(e, update_key and not keeps_key, rename=rename, copy=copy) )
             return entries
 
 
@@ -480,13 +486,17 @@ class Biblio:
 
 
     def set_files(self, entry, files, relative_to=None):
-        entry['file'] = format_file(list(sorted(set(files), key=lambda f: files.index(f))), relative_to=relative_to or self.relative_to)
+        if relative_to is None:
+            relative_to = self.relative_to
+        entry['file'] = format_file(list(sorted(set(files), key=lambda f: files.index(f))), relative_to=relative_to)
         # delete field if empty
         if not entry['file'].strip():
             del entry['file']
 
     def get_files(self, entry, relative_to=None):
-        return parse_file(get_entry_val(entry, 'file', ''), relative_to=relative_to or self.relative_to)
+        if relative_to is None:
+            relative_to = self.relative_to
+        return parse_file(get_entry_val(entry, 'file', ''), relative_to=relative_to)
 
     def add_bibtex(self, bibtex, relative_to=None, attachments=None, convert_to_unicode=False, **kw):
         bib = parse_string(bibtex)
@@ -522,7 +532,9 @@ class Biblio:
 
     def add_bibtex_file(self, file, **kw):
         bibtex = open(file).read()
-        return self.add_bibtex(bibtex, relative_to=os.path.dirname(file), **kw)
+        # file links in the added bibtex are relative to its own directory
+        # (the absolute path matters: dirname('papers.bib') is '')
+        return self.add_bibtex(bibtex, relative_to=os.path.dirname(os.path.abspath(file)), **kw)
 
 
     def fetch_doi(self, doi, **kw):