FABRIC Python Client Library and CLI Extensions
Project description
fabrictestbed-extensions
This repository contains implementation of a Python API, otherwise known as "FABlib", for intereacting with FABRIC testbed.
Installing FABlib
You can install released versions of FABlib from PyPI:
$ pip install fabrictestbed-extensions
If you need the current development version of FABlib, install it from the git repository:
$ pip install git+https://github.com/fabric-testbed/fabrictestbed-extensions@main
Note that installing FABlib using either methods will also install a number of dependencies, so you might want to install FABlib in a virtual environment. Your favorite tool for managing virtual environments (venv, virtualenv, or virtualenvwrapper) should work. FABRIC team tends to favor virtualenvwrapper.
Using FABlib
Once installed, you can use FABlib in your Python projects:
from fabrictestbed_extensions.fablib.fablib import FablibManager as fablib_manager
try:
fablib = fablib_manager()
fablib.show_config()
except Exception as e:
print(f"Exception: {e}")
Your first encounter with FABlib however might be through FABRIC project's JupyterHub instance. You will be presented with many examples on FABlib usage when you log in there. The notebook sources can be found on GitHub as well.
Since FABlib 1.4, API docs can be found here. Older API docs are here.
If you want to interact with FABRIC from Jupyter installed on your computer, see: Install the FABRIC Python API.
Contributing to FABlib
Contributions to FABlib are made with GitHub Pull Requests. When you submit a pull request, some tests will run against it:
- Code formatting will be checked using black and isort. Be sure that your code is formatted with these tools.
- Unit tests will be run.
- Packages will be built.
- CHANGELOG.md will be checked for updates.
Testing FABlib
FABlib currently has a modest set of unit and integration tests, under
the top-level tests directory. Unit tests can be run like so, using
tox:
$ pip install -e .[test]
$ tox
Integration tests can be run like so:
$ tox -e integration
Tox attempts to run tests in an isolated virtual environment. If you want to run some tests directly using pytest, that is possible too:
$ pytest -s tests/integration/test_hello_fabric.py
Documenting FABlib
FABlib uses Sphinx to generate API documentation from Python docstrings. Publishing them at Read the Docs is a mostly automated process.
When working on API documentation on your local setup, in order to preview the generated HTML, run:
$ tox -e docs
Resulting files can be found in docs/build/html/.
Packaging FABlib
FABlib uses flit as the build backend. To build source and wheel packages, do this:
$ pip install flit
$ flit build
While using flit as the build backend, continuing to use build as the build frontend should work too:
$ pip install build
$ python -m build
Releasing FABlib
The "publish" workflow automates building packages and publishing them on PyPI. In order to publish a new FABlib version on PyPI, follow these steps:
-
Bump up version in top-level
__init__.py. -
Update changelog.
-
Start a PR with these changes, and get it merged.
-
Tag the release, and push the tag to GitHub:
$ git tag --sign --message="Great set of features" relX.Y.Z <ref> $ git push <origin> --tags relX.Y.Z
This should trigger the publish workflow that will: (1) run unit tests, (2) build FABlib sdist and wheel packages, and then (3) publish the packages on PyPI.
Manual steps
In order to "manually" upload FABlib packages (such as in the case of release candidate versions), bump up the version string in the appropriate place, and then do:
$ flit publish
Continuing to use twine to publish packages is an option too:
$ twine upload dist/*
For details about publishing to PyPI, see flit documentation about package uploads.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file fabrictestbed_extensions-1.5.6rc3.tar.gz.
File metadata
- Download URL: fabrictestbed_extensions-1.5.6rc3.tar.gz
- Upload date:
- Size: 391.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/4.0.2 CPython/3.11.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | c148131efe92f412e69b7d9d1ec6e8efdbb579e495cedb79ecc8fc07a4ad1c33 |
|
| MD5 | 82f1cadc881b5dff7bc83a73d6bcb359 |
|
| BLAKE2b-256 | f90e80d88f9563db98facd8d7f6d0086957a336236e00ccdce0b30b3b8c5efbe |
File details
Details for the file fabrictestbed_extensions-1.5.6rc3-py3-none-any.whl.
File metadata
- Download URL: fabrictestbed_extensions-1.5.6rc3-py3-none-any.whl
- Upload date:
- Size: 369.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/4.0.2 CPython/3.11.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | a73f24d6302de6635b1e3544936b92270c650400f30ec1874ac3bb0d7d63ab49 |
|
| MD5 | 8e50633823de31bd86ca08385f87d361 |
|
| BLAKE2b-256 | 36b127234b67f48fca4d9c5b40906adabda2c10ba4ca6fa45d0ba8dc75a0fa34 |
