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-clientAlternatively, 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-clientand 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.
