Contributing

Structure

The Transcriptic Python Library (TxPy) is separated into two main portions: the command line interface (CLI) and the Jupyter notebook interface.

Both the CLI and the notebook interface uses the base Connection object for making relevant application programming interface (API) calls to Transcriptic. The Connection object itself uses the routes module to figure out the relevant routes and passes that onto the api module for making these calls.

The base functionality of the CLI is handled by the cli module which is the front-facing interface for users. The english module provides autoprotocol parsing functionalities, and the util module provides additional generic helper functions.

The base functionality of the notebook interface is exposed through the objects module. Additional analysis of these objects is provided through the analysis module. In general, html representations should be provided as much as possible.

For analysis purposes, we prefer using Pandas DataFrames and NumPy arrays for representing and slicing data. For plotting, matplotlib and plotly is preferred.

Version Compatibility

TxPy is written with Python 3.6+ compatibility in mind. Python 2 is no longer officially supported.

General Setup

Use of virtual environment to isolate the development environment is highly recommended. There are several tools available such as conda and pyenv.

After activating your desired virtualenv, install the dependencies using the snippet below

pip install -e '.[test, docs]'
pre-commit install

Styling and Documentation

All code written should follow the PEP8 standard

For documentation purposes, we follow NumPy style doc strings

We use pre-commit as our linting and auto-formatting framework. Lint is checked with pylint and auto-formatting is done with black. This is automatically executed as part of the git commit and git push workflows. You may also execute it manually using the snippet below.

pre-commit run

Testing

For testing purposes, we write tests in the test folder in the pytest format. We also use tox for automating tests.

The tox command is run by CI and is currently configured to run the main module tests, generate a coverage report and build documentation.

Generally, please ensure that all tests pass when you execute tox in the root folder.

cd $TXPY_ROOT_DIR
tox

If you’re using pyenv to manage python versions, ensure you have all the tested environments in your .python-version file. i.e.pyenv local 3.6.12 3.7.9 3.8.7

Running Specific Tests

Specific tests are controlled by the tox.ini configuration file.

To run just the main module tests, execute python setup.py test in the root folder. This is specified by the main [testenv] flag in tox.ini.

To run a specific test, execute python setup.py test -a path/to/test.py. Using tox, tox -e py36 -- -a path/to/test.py.

To build the docs locally, execute sphinx-build -W -b html -d tmp/doctrees . -d tmp/html in the docs directory. This is specified by the [testenv:docs] flag in tox.ini.

Pull Requests

To contribute, please submit a pull-request to the Github repository.

Before submitting the request, please ensure that all tests pass by running tox in the main directory.