The Librarian Client¶
The librarian client really refers to two individual components:
The python API defined in
hera_librarian/client.py, which is two well-documented objectsLibrarianClientandAdminClientthat provide wrappers over the REST API.The
librariancommand-line tool that passes through to this client.
Of course, should you wish to access the librarian server from
outside of python or the command line, you could always make the
REST calls yourself using any appropriate tool. The benefit of using
the python interface is that all data is transformed on the
client-side using the same pydantic models (hera_librarian/models)
that are used on the server side, providing significant client-side
validation and error checking that may be useful to you.
Python client¶
The librarian python client is easy to use, and is well-documented
through its docstrings. The LibrarianClient object contains
all the methods that can be used without administration privliages
on the server, and the AdminClient contains methods that wrap
all endpoints. Using the client is simple:
The python interface is considered stable (appendable), and is the preferred way for programatically interacting with the librarian server.
Command-line client¶
The command-line client wraps almost all of the python functions
through the use of the argparse library. The command-line
library can be somewhat clunky due to the large number of parameters
that are needed for most functions on the librarian, and as such
its use is generally discouraged for anything other than simple
interactions.
To use the command-line client, you will need to provide information for the server you are connecting to through a JSON parameter file.
This file is generally stored at ~/.hl_client.cfg (we recommend using 400
permissions for this file!), but its location can be configured through
the use of the HL_CLIENT_CONFIG environment variable.
A list of available commands is availble through the librarian --help command.
Command-line interactions generally take the following form:
librarian {command} {connection-name} {parameters}
For instance, to search for files that have been uploaded in the past week on the local server, you would use the following command:
librarian search-files local --create-time-start=$(date -uv -1d) --create-time-end=$(date -u)
Individual parameter information is available through
librarian {command} --help.