utils (0.1.3)
Installation
pip install --index-url /api/packages/madrigal/pypi/simple/ --no-deps utilsAbout this package
A comprehensive collection of the robust utilities at the core of the RIA Project, including common data ADTs, SDR interfaces, and essential signal processing tools and transforms
Utils
Utils is a comprehensive collection of robust utilities at the core of the RIA Project, including common interfaces (class blueprints), APIs to communicate with software-defined radios, file managers, signal generators, and essential signal processing tools and transforms.
🚀 Getting started
The Utils codebase is hosted on RIA Hub: qoherent / utils. Pre-built binaries are available both on RIA Hub, as well as Qoherent's private devpi server. Therefore, there are several ways to install utils:
Installation from devpi (recommended)
At the time of writing, the recommended way to install Utils is from devpi.
Utils is listed on Qoherent's private devpi server: Thor devpi Server. To access this server, you need to be connected to Qoherent's private network, either directly or through a VPN.
This server hosts multiple indexes. Locate the project listing that you would like use, and then install with pip.
By default, pip installs the utils listed on PyPI, which is a separate project. To use one of our listings, you need
to specify the --index-url option. For example, the following command will install a suitable version of Utils
listed on the michael/dev index:
pip install --index-url http://thor:8080/michael/dev/+simple/ --trusted-host thor utils
Please note that pip requires secure HTTPS by default. Therefore, the --trusted-host option is required to install
over plain HTTP.
Installation from RIA Hub
Utils binaries are also available on RIA Hub: utils / packages. To access RIA Hub at this URL, you need to be connected to Qoherent's private network, either directly or through a VPN.
In the future, installation from RIA Hub will become the recommended installation method. However, at the time of writing, RIA Hub is missing support for two key features:
-
RIA Hub does not support a proxy or cache for PyPI. Therefore, when installing packages, you need to use the
--no-depsoption with pip to skip automatic dependency installation, and then manually install each dependency afterward. -
RIA Hub currently does not provide support for hosting Sphinx docs.
The following installation command will install a suitable version of Utils:
pip install --index-url https://riahub.qoherent.internal:3000/api/packages/qoherent/pypi/simple/ --no-deps utils
Note: This is the same command listed at the top of the release: Utils package listing on RIA Hub.
Installation from source
If release binaries are not available, you will need to install utils from source.
- Clone the repository. For example:
git clone https://riahub.qoherent.internal:3000/qoherent/utils.git
- Navigate into the project directory:
cd utils
- Install the package:
pip install .
Or, if you plan to modify the Utils code and want changes to reflect immediately without reinstalling, use an editable installation:
pip install -e .
Basic Usage
Once the project is installed, you can import its modules, functions, and classes, just as you would with any other
Python library. For example, you can use the following import statement to access the Recording object:
from utils.data import Recording
You can also access select utilities via the Utils command-line interface (CLI), which is automatically installed
alongside Utils. Execute utils --help from the command line for CLI usage information.
Additional installation and usage information and examples are provided in the project documentation. The project
documentation is also hosted on Qoherent's devpi server and can be viewed in the browser. Please be careful to ensure
you are viewing the documentation for the installed version, which can be determined using the following command:
pip show utils. For convenience, the documentation for the latest stable version is linked here:
Utils Project Documentation.
🐛 Issues
Kindly report any issues to the GitHub Issues board here.
🔗 Adding Utils as a project dependency
Include Utils as a project dependency by adding the following line to your project's pyproject.toml file:
[tool.poetry.dependencies]
utils = { git = "git@riahub.qoherent.internal:qoherent/utils.git" }
Note: We've listed the SSH URL as it tends to be more convenient in our workflows. However, the HTTPS URL can be used as well.
For non-Python projects or projects where dependencies are not managed by Poetry, consider incorporating Utils as a submodule.
🤝 Contribution
Contributions are always welcome! Whether it's an enhancement, bug fix, or new usage example, your input is valuable. If you'd like to contribute to the project, please reach out to the project maintainers.
💻 Project Guidelines
This project adheres to Qoherent's Coding Guidelines. We kindly ask you to review them before getting started.
Utils is designed to be backend-independent and relatively lightweight, so please avoid adding large dependencies like PyTorch.
Utils is designed to be built and installed as a standalone package, so please avoid adding other Qoherent projects as dependencies.
Poetry
To ensure a consistent development environment, this project employs Poetry for dependency management.
You can initialize a new Poetry environment by running install from anywhere within the project:
poetry install
Running install when a poetry.lock file is present resolves and installs all dependencies listed in
pyproject.toml, but Poetry uses the exact versions listed in poetry.lock to ensure that the package versions
are consistent for everyone working on your project. Please note that the project itself will be installed in
editable mode when running poetry install.
Tests can be run with the following command:
poetry run pytest
Source and wheels archives can be built with the following command:
poetry build
For more information on basic Poetry usage, start here.
Sphinx
Project documentation is crucial because it serves as the primary source of usage information. Documentation is auto-generated from project docstrings using Sphinx. Therefore, all importable components require comprehensive docstrings, complete with doctests demonstrating usage.
It's recommended to use sphinx-autobuild, which eliminates the need to manually rebuild the docs after making
changes:
sphinx-autobuild docs/source docs/build/html
When using sphinx-autobuild, the docs will automatically be served at http://127.0.0.1:8000.
To build the project documentation manually, navigate to the docs directory and run the following commands:
make clean
make html
Once the documentation is built, you can view it by opening docs/build/html/index.html in a web browser. Please note
that this strategy requires you to manually rebuild in order to see the changes.
For more information on basic Sphinx usage, start here.
tox
This project uses tox to streamline the testing and release. tox runs linting and formatting checks and tests
the package across multiple version of Python.
To run the tests, simply execute:
tox
For more information on basic tox usage, start here.