Contributing to Tapis CLI¶
We welcome contributions to Tapis CLI, since our users are often best qualified to propose and improve its functionality.
Hacking¶
Install CLI in editable mode:
pip install -e .
Run all the tests:
python -m pytest
Run multi-environment tests with tox:
# Note tox is not included in requirements.txt
pip install tox
tox
Docker image¶
A local build of the Tapis CLI container image can be created and launched
using make image
followed by make interactive
. This is helpful when
customizing or extending the project Dockerfile.
Code structure¶
API commands are implemented as subclasses of TaccApisCommandBase
, which
handles Oauth client setup, and either TaccApisFormatOne
or
TaccApisFormatMany
, which are in turn subclassed from cliff’s Lister
and FormatMany
classes. This design reflects two kinds of responses: a
list of records or a single record (or response to a CRUD action).
Each command is implemented as a TitleCased class in a snake_cased module,
which in turn are organized by platform, version, and service under the
commands
subpackage. Consider the tapis apps list
command. It is one
of the Tapis APIs, the command being implemented is specific to the v2
version of TACC APIs, and is a command pertaining to the apps service.
Thus, the command is defined in class AppsList
in
tapis_cli.commands.taccapis.v2.apps.apps_list
.
This code structure reflects two requirements. The first is that the cliff package uses setuptools entrypoints to establish command line functions. The second is that the Tapis CLI will integrate multiple platforms and versions of TACC-hosted services. There is space marked out in the CLI design for v3 of Tapis, management functions for hosted Gitlab and Container registry, and eventual public release of the TACC SSH Keys service.
Returning to the setuptools topic: Each command is defined in setup.cfg
by defining a command and pointing to the implementing class. The apps list
command is defined as shown below.
Example setuptools entrypoint:
[entry_points]
console_scripts =
tapis = tapis_cli.main:main
tapis.cli =
apps_list = tapis_cli.commands.taccapis.v2.apps:AppsList
Limited (at present) unit tests are implemented in the tests directory. Automated code linting (to PEP8) and code coverage analysis are included in all PyTest runs to encourage sustainable development practices.
Documentation¶
The project uses Sphinx and the Napoleon extension, which is configured to support Google-style documentation strings.
Regenerate the documentation:
make docs
Code Style¶
The project code style is vanilla PEP8, as configured by the
[flake8]
section of setup.cfg
.
Use of yapf
autoformatter is supported and encouraged to
maintain the codebase, and is available via the make format
Makefile target.
Issue Tracker¶
Major functional objectives are bundled into Milestones with due dates in the future. This provides a way to organize the work and have a public road map for functionality.
All work should proceed via reported Issues.