API

This module describes which functions are intended to be used by users to create Papis scripts.

class papis.api.T
papis.api.get_lib_name() str[source]

Get current library.

It either retrieves the library from the environment PAPIS_LIB variable, the command-line arguments passed in by the user or the configuration files.

Returns:

the name of the library.

>>> get_lib_name() is not None
True
papis.api.set_lib_from_name(library: str) None[source]

Set current library.

It either sets the library from the environment PAPIS_LIB variable, the command-line args passed by the user or the configuration files.

Parameters:

library – name of a library (as defined in the configuration files) or a path to an existing library.

papis.api.get_libraries() List[str][source]

Get all the libraries declared in the configuration files.

A library in the configuration files is a section that has the dir or dirs keys defined.

Returns:

a list of library names.

>>> len(get_libraries()) >= 1
True
papis.api.pick_doc(documents: Sequence[Document]) Sequence[Document][source]

Pick a subset of documents from the given documents.

Parameters:

documents – a sequence of documents.

Returns:

a subset of documents corresponding to the user selected ones.

papis.api.pick(items: Sequence[T], default_index: int = 0, header_filter: Callable[[T], str] | None = None, match_filter: Callable[[T], str] | None = None) Sequence[T][source]

Pick a subset of items from the given items.

Parameters:
  • items – a sequence of items.

  • default_index – index used when no explicit item is picked.

  • header_filter – a callable to stringify the given item for display.

  • match_filter – a callable to stringify the given item for display.

papis.api.open_file(file_path: str, wait: bool = True) None[source]

Open the given file using the configured opentool.

Parameters:
  • file_path – a path to a file.

  • wait – if True, wait for the completion of the opener program before continuing execution (blocking behavior).

papis.api.open_dir(dir_path: str, wait: bool = True) None[source]

Open the given directory using the configured file-browser.

Parameters:
  • dir_path – a path to a folder.

  • wait – if True, wait for the completion of the opener program before continuing execution (blocking behavior).

papis.api.edit_file(file_path: str, wait: bool = True) None[source]

Edit the given file using the configured editor.

Parameters:
  • file_path – a path to a file.

  • wait – if True, wait for the completion of the editor before continuing execution (blocking behavior).

papis.api.get_all_documents_in_lib(library: str | None = None) List[Document][source]

Get all documents in the given library.

Parameters:

library – a library name.

Returns:

a list of all known documents in the library.

>>> import tempfile
>>> folder = tempfile.mkdtemp()
>>> set_lib_from_name(folder)
>>> docs = get_all_documents_in_lib(folder)
>>> len(docs)
0
papis.api.get_documents_in_dir(directory: str, search: str = '') List[Document][source]

Get documents contained in the given folder.

Parameters:
  • directory – a path to a folder containing documents.

  • search – a search string used to filter the documents.

Returns:

a list of filtered documents from directory.

>>> import tempfile
>>> docs = get_documents_in_dir(tempfile.mkdtemp())
>>> len(docs)
0
papis.api.get_documents_in_lib(library: str | None = None, search: Dict[str, Any] | str = '') List[Document][source]

Get documents contained in the given library.

Parameters:
  • library – a library name.

  • search – a search parameter used to filter the documents.

Returns:

a list of filtered documents from library.

papis.api.clear_lib_cache(lib: str | None = None) None[source]

Clear the cache associated with a library.

If no library is given, then the current library is used.

Parameters:

lib – a library name.

>>> clear_lib_cache()
papis.api.doi_to_data(doi: str) Dict[str, Any][source]

Get metadata for the given doi by querying Crossref.

Parameters:

doi – a valid DOI (Document Object Identifier).

Returns:

metadata for the given identifier.

papis.api.save_doc(doc: Document) None[source]

Save the document to disk.

This commits the new document to the database and saves it to disk by updating its info.yaml file.

Parameters:

doc – an existing document.