Quetzal Python client¶
Python client for the Quetzal API.
If you are not familiar with the Quetzal API, read its documentation first. This Python package provides a command-line and helper functions to interact with the Quetzal API.
Note that this package depends on an auto-generated package quetzal.openapi_client, which is also a client to this API. You can use the latter as a pure Python client, but quetzal.client provides some helpers and small fixes.
Installation¶
You can install quetzal-client, with pip
:
pip install quetzal-client
Alternatively, add this line to your requirements.txt
:
quetzal-client
and then do pip install -r requirements.txt
.
If you are using conda, add the following structure to your environment.yaml
:
...
dependencies:
- pip
- pip:
- quetzal-client
and create or update your environment with
conda env create -f environment.yaml
or
conda env update -f environment.yaml
, respectively.
Getting started¶
In order to use quetzal.client, you need to know the URL of the API server, your username and password. You can set these on the command-line interface, through a configuration object, or using environment variables:
Variable | Description | Default if not set |
---|---|---|
QUETZAL_URL |
Complete URL of the Quetzal server + API version. | 'https://api.quetz.al/api/v1' |
QUETZAL_USER |
Quetzal username. | '' |
QUETZAL_PASSWORD |
Quetzal password. | '' |
QUETZAL_API_KEY |
Quetzal API key. | '' |
Basic usage¶
There are two ways this package helps you: with a command-line interface or by providing some helper modules that you can use in Python.
Command-line interface¶
The command-line interface is available through the quetzal-client
command.
Use the --help
or --help-all
options to get a detailed description of
each command.
$ quetzal-client --help
Usage: quetzal-client [GLOBAL OPTIONS] COMMAND [ARGS]...
Command-line utility for the Quetzal API client.
Options:
--url TEXT Quetzal URL. If not set, uses environment variable
QUETZAL_URL if this variable is defined. [default:
https://api.quetz.al/api/v1]
--username TEXT Quetzal username. If not set, uses environment variable
QUETZAL_USER. Option is mutually exclusive with token,
api_key.
--password TEXT Quetzal password. If not set, uses environment variable
QUETZAL_PASSWORD. Option is mutually exclusive with token,
api_key.
--token TEXT Quetzal bearer token. If not set, uses environment variable
QUETZAL_TOKEN. Option is mutually exclusive with username,
password, api_key.
--api-key TEXT Quetzal API key. If not set, uses environment variable
QUETZAL_API_KEY Option is mutually exclusive with username,
password, token.
--insecure Do not verify HTTPS certificates.
-v, --verbose Verbosity level. Use -v for verbose, -vv for even more
verbosity
--help-all Show a detailed help message with all options and exit.
--help Show help message for this command and exit.
--version Show the version and exit.
Commands:
auth Authentication operations.
file File operations.
query Query metadata.
workspace Workspace operations.
Python¶
To start using quetzal.client on Python code, use the following template:
from quetzal.client import Client, Configuration, QuetzalAPIException
from quetzal.client import helpers
config = Configuration()
# ... change config as needed or fallback to the environment variables ...
# config.verify_ssl = False # Use this for servers without certificates (dev servers)
client = Client(config)
# A simple test using the helpers to verify that we can login to Quetzal
try:
helpers.auth.login(client)
print('Logged in successfully!')
except QuetzalAPIException as ex:
print(f'Operation failed. {ex.title} - {ex.detail}')
Documentation¶
There are more details on quetzal.client on its official documentation at readthedocs.
Contribute¶
- Issue Tracker: https://github.com/quetz-al/quetzal-client/issues
- Source Code: https://github.com/quetz-al/quetzal-client
Note to package maintainer¶
To build and send this package to PyPI:
# Clean previous builds!
rm -rf dist/
# Build
python setup.py sdist bdist_wheel
# Install helper module for uploading to PyPI
pip install twine
# First, send to test PyPI
twine upload --repository-url https://test.pypi.org/legacy/ dist/*
# If that works ok, then send to PyPI
python -m twine upload dist/*
License¶
The project is under the BSD 3-clause license.
Changelog¶
This document list all important changes to quetzal-client.
Quetzal-client version numbers follow semantic versioning.
0.5.3 (2020-06-05)¶
- Fix incorrect pathlib handling on file download.
- Fix incorrect exception handling that impacted retry logic.
0.5.2 (2020-03-13)¶
This is just a re-release of 0.5.1 code due to problem when uploading to PyPI.
0.5.1 (2020-03-13)¶
- Add data_url to workspace details on the CLI
- Fix permission error when using query history on the CLI
- Update backoff requirement to avoid problems when used by dask
0.5.1-rc3 (2020-03-04)¶
- Fix incorrect management of auto retry backoff for 503 errors and a recursive auto-login that was also incorrect
0.5.1-rc2 (2020-02-28)¶
- Fix incorrect management of output and output_dir in download helper.
0.5.1-rc1 (2020-02-27)¶
- Fix problem with API key authentication when requesting file details.
- Fix API key management on configuration object.
- Fix lack of default format on CLI for file metadata.
- Add file delete CLI.
0.5.0 (2019-10-17)¶
- Update to API version 0.5.0.
- Add API key authentication.
0.3.0 (2019-07-02)¶
- Update to API version 0.3.0.
- Add more helper functions (query and client).
- Fix incorrect call to derived configuration object.
- Fix unpickeable exception types.
- Fix bugs on file download checksum verification and file upload parameters.
0.2.0 (2019-03-21)¶
- Update dependency quetzal-openapi-client to match Quetzal API version 0.2.0.
- Fix
dependency_links
to correctly link to quetzal-openapi-client.
0.1.1 (2019-03-08)¶
quetzal.client.api
has been renamed toquetzal.client.helpers
.- File download, with verification of known files, added to helpers.
- File download falls back to user data directory if output not set.
- Config default to environment variable values when created.
- Initial structure of Sphinx documentation.
0.1.0 (2019-03-05)¶
- First iteration of the Quetzal Python client.
- Delegates the automatic code to quetzal-openapi-client.
- Command-line interface implemented with Click for most operations available on the Quetzal API.
- Incomplete implementation of a helper module quetzal.client.api that encapsulates the usage of the auto-generated client.