This repository contains implementation of a Python API, otherwise known as "FABlib", for intereacting with FABRIC testbed.
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.
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.
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.
- CHANGELOG.md will be checked for updates.
- Packages will be built.
- Unit tests will be run.
You can run tests in your environment, like so, using pytest:
$ pip install -e .[test]
$ pytest
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
When it is time to release a new version of FABlib, remember to: (1)
update the package version in top-level __init__.py
, (2) build the
source and wheel packages, and (3) upload packages to PyPI:
$ 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.