Contributing

Licensing

Autoprotocol-Python is BSD licensed (see LICENSE).

Features and Bugs

The easiest way to contribute is to fork this repository and submit a pull request. You can also submit an issue or write an email to us at support@strateos.com if you want to discuss ideas or bugs.

Dev Env Setup

Installation:

Minimum Python version supported for development is v3.7.

Python Virtual Environment (Optional):

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

Dependencies:

We recommend first activating your desired virtualenv, then installing the dependencies using the snippet below.

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

We use tox as a runner for managing test environments and running our entire suite of tests, including linting and documentation, for all supported Python versions.

However, you may choose to execute tests piecemeal while iterating on code development. For that, we use pytest as our test framework for python tests.

tox  # Execute the full suite of tests, usually not required
python setup.py test  # Executing just python tests
Linting and Formatting:

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 by using the snippet below.

pre-commit run
Documentation:

We use sphinx for generating documentation.

cd docs  # Assuming you're in the root cloned directory
sphinx-build -W -b html -d tmp/doctrees . tmp/html
Adding New Packages:

Because of how the tox setup is configured, if you’re attempting to add a new package into the directory structure of autoprotocol, you’ll need to add the package name into the root setup.py file’s setup package list. Without adding the new package to this list you’ll get failures when attempting to run the doc generator or linting steps.

Package Structure

Protocol

  • Primary user interface for Autoprotocol Python

  • Represent high level abstractions around instructions, refs, and constraints

  • Have more situational checks than those in Builders or Instruction

  • Have simple arguments that are as flat as possible, ideally with no nesting

  • Don’t necessarily have a 1:1 mapping to an Instruction

    • a single call may generate multiple Instruction instances

    • a complicated, modal Instruction may have multiple corresponding Protocol methods

    • significantly complex instructions (e.g. LiquidHandle) may require parametrization with user-configurable class instances to avoid overloading the Protocol method with too many arguments

Builders

  • Constructors for nested Instruction parameters

  • Assigned to the builders attribute of their corresponding Instruction

  • Only contain checks that are valid for all instances of their corresponding Instruction

  • Check the relationship between parameters

    • a modal Instruction generally has mode_params that depend on the specified mode (e.g. LiquidHandle and Spectrophotometry.groups)

    • parameters like shape are very interdependent, and only certain combinations of rows, columns, and format are physically possible

Instruction

  • Code analogue of an Autoprotocol Instruction; constructs Instruction JSON

  • __init___ parameters mirror structure of Autoprotocol Instruction

  • Only validate the type, structure, and extent of their inputs