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¶
quetzal-client and its dependency, quetzal-openapi-client, are not on
PyPI yet. In the meantime, in order to install this package, create a virtual
environment and install with pip
:
pip install git+https://github.com/quetz-al/quetzal-client.git@v0.2.0\#egg=quetzal-client
Alternatively, add this line to your requirements.txt
:
and then do pip install -r requirements.txt
.
If you are using conda, add the following structure to your environment.yaml
:
...
dependencies:
- pip:
- git+https://github.com/quetz-al/quetzal-client.git@v0.2.0#egg=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. | '' |
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://staging.quetz.al/api/v1]
--insecure Do not verify HTTPS certificates.
--username TEXT Quetzal username. If not set, uses environment variable
QUETZAL_USER. Option is mutually exclusive with token.
--password TEXT Quetzal password. If not set, uses environment variable
QUETZAL_PASSWORD. Option is mutually exclusive with token.
--token TEXT Quetzal access token. If not set, uses environment variable
QUETZAL_TOKEN. Option is mutually exclusive with username,
password.
-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
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.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.