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.