build: pre-commit infrastructure and update travis (#243)

Add pre-commit infrastructure to help with basic lint tasks. This is in
preparation of adding an autoformatter for the repo.

As part of this, the travis file is reorganized to help with clearer
delineation of jobs. The underlying dist is also bumped to `bionic`
since there aren't any explicit dependencies on `xenial` and `bionic`
is stable.

Documention is also updated, with the Contributing section updated with
more explicit testing steps and the new environment and lint setup.

This includes all the fixes from the pre-commit hooks added.

.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v3.1.0
+    hooks:
+    -   id: check-yaml
+    -   id: end-of-file-fixer
+    -   id: trailing-whitespace
+-   repo: https://github.com/pycqa/pylint
+    rev: pylint-2.5.2
+    hooks:
+    -   id: pylint
+        args:
+        - --disable=R,C
+        - --rcfile=.pylintrc
+        name: Pylint
+        language: system
+        types: [python]

.travis.yml

@@ -1,16 +1,30 @@
+dist: bionic
 env:
   global:
   - secure: 'DvgFv3NTqwnFpR4tzvvwEIc43VPyp9eDlMjtEsqUffMF9oLyRLTiUtMZEzIpGgNg4UY8cyNWv6iWHJBsmmVncow6ziDp2+cpC43zWtilZeo+ohri4ejVw16MNKaIfP2bAVU4u0QpC6xQHHDGsUyRdM6OINjQxPUqFTjjOBRggkk='
   - secure: 'PHjo7CS3U+uGxmAf9/ClQbNWUt0zfZMRuZRSwdzMc6jNy0Mp21Bl/kq/K5022yXGxaEoTF8SWzvN3pOVmUnPve71Fz85AUclzGNdLnLtOGcsE/lzXxjW+uNprLHZ9rakj9MzAlUexX6j8A5NOaxdOKOihwlNjY7xMKA5Xy+pjWA='
   - secure: 'CicwL3ulhGLS+J8yvSQt18Ta1VUOBKv9Rd60ZMzlkCoEXAoO7IvpYUwnUXE7ZurLRt1Yuif+wd3D7P4BNDFIOVw7gEYllX9S4URE+9j3I/oFze+dFpqncb15CWkCK6EIyerXs/HjZe/J1o0IwPmDTqn6KXBnP6wCNLBf4UoJBnw='
 sudo: false
 language: python
-python:
-- '3.6'
-- '3.7'
-- '3.8'
-install: pip install tox-travis
-script: tox
+jobs:
+  include:
+  - python: '3.6'
+    env: TOXENV=docs
+  - python: '3.6'
+    env: TOXENV=lint
+  - python: '3.6'
+    env: TOXENV=clean,py36,stats
+  - python: '3.7'
+    env: TOXENV=py37
+  - python: '3.8'
+    env: TOXENV=py38
+install:
+- pip install tox
+script:
+- tox -v
+after_failure:
+- more .tox/log/* | cat
+- more .tox/*/log/* | cat
 before_deploy:
 - python setup.py sdist
 - python setup.py bdist_wheel

CONTRIBUTING.rst

@@ -11,6 +11,58 @@ 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 :code:`v3.6`.
+
+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.
+
+.. code-block:: sh
+
+   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.
+
+.. code-block:: sh
+
+    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.
+    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.
+
+.. code-block:: sh
+
+   pre-commit run
+
+Documentation:
+    We use sphinx_ for generating documentation.
+
+.. code-block:: bash
+
+   cd docs  # Assuming you're in the root cloned directory
+   sphinx-build -W -b html -d tmp/doctrees . tmp/html
+
 Package Structure
 -----------------
 
@@ -48,4 +100,9 @@ Instruction_
 .. _Protocol: http://autoprotocol-python.readthedocs.io/en/latest/protocol.html
 .. _Builders: http://autoprotocol-python.readthedocs.io/en/latest/builders.html
 .. _Instruction: http://autoprotocol-python.readthedocs.io/en/latest/instruction.html
-
+.. _pyenv: https://github.com/pyenv/pyenv#installation
+.. _conda: https://docs.conda.io/projects/conda/en/latest/user-guide/install/
+.. _tox: https://tox.readthedocs.io/en/latest/
+.. _pytest: https://docs.pytest.org/en/latest/
+.. _pre-commit: https://pre-commit.com/
+.. _sphinx: https://www.sphinx-doc.org/en/master/

LICENSE.rst

@@ -22,4 +22,3 @@ PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
 OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-

README.rst

@@ -37,17 +37,6 @@ Alternatively to get more up-to-date features:
 
 check the changelog_ for information about features included on `master` but not yet released.
 
-Dev Env Setup
--------------
-
-Installation:
-    Minimum Python version supported for development is :code:`v3.6`.
-
-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_.
-
 Building a Protocol
 -------------------
 
@@ -135,6 +124,3 @@ For more information, see CONTRIBUTING_.
 .. _changelog: http://autoprotocol-python.readthedocs.io/en/latest/changelog.html
 .. _CONTRIBUTING: http://autoprotocol-python.readthedocs.io/en/latest/CONTRIBUTING.html
 .. _documentation: http://autoprotocol-python.readthedocs.org/en/latest/
-.. _python: https://www.python.org/downloads/release/python-356/
-.. _pyenv: https://github.com/pyenv/pyenv#installation
-.. _conda: https://docs.conda.io/projects/conda/en/latest/user-guide/install/

autoprotocol-python SublimeText Snippets/WellGroup.sublime-snippet

@@ -5,4 +5,4 @@ WellGroup(wells=${1:Well wells})
     <tabTrigger>WellGroup</tabTrigger>
     <scope>source.python</scope>
     <description>Returns a well object</description>
-</snippet>
+</snippet>

autoprotocol-python SublimeText Snippets/WellGroup_append.sublime-snippet

@@ -2,5 +2,5 @@
 	<content><![CDATA[append(${1:Well well})]]></content>
 	<tabTrigger>append</tabTrigger>
 	<scope>source.python</scope>
-	<description>Appends Well to WellGroup</description> 
-</snippet>
+	<description>Appends Well to WellGroup</description>
+</snippet>

autoprotocol-python SublimeText Snippets/Well_Container.sublime-snippet

@@ -5,4 +5,4 @@ Well(${1:Container container}, ${2:Int index})
     <tabTrigger>Well</tabTrigger>
     <scope>source.python</scope>
     <description>Returns a well object</description>
-</snippet>
+</snippet>

autoprotocol-python SublimeText Snippets/absorbance.sublime-snippet

@@ -5,4 +5,4 @@ absorbance(ref=${1:Container ref}, wells=${2:WellGroup wells}, wavelength="${3:S
     <tabTrigger>absorbance</tabTrigger>
     <scope>source.python</scope>
     <description>Read well absorbance</description>
-</snippet>
+</snippet>

autoprotocol-python SublimeText Snippets/acoustic_transfer.sublime-snippet

@@ -4,4 +4,4 @@ acoustic_transfer(source=${1:WellGroup source}, dest=${2:WellGroup destination},
 	<tabTrigger>acoustic_transfer</tabTrigger>
 	<scope>source.python</scope>
 	<description>Transfer liquid via acoustics</description>
-</snippet>
+</snippet>

autoprotocol-python SublimeText Snippets/add_properties.sublime-snippet

@@ -5,4 +5,4 @@ add_properties(properties=${1:Dict properties})
     <tabTrigger>add_properties</tabTrigger>
     <scope>source.python</scope>
     <description>Add well property</description>
-</snippet>
+</snippet>

autoprotocol-python SublimeText Snippets/aliquot.sublime-snippet

@@ -12,5 +12,3 @@
 	<scope>source.json</scope>
 	<description>Implements aliquot </description>
 </snippet>
-
-

autoprotocol-python SublimeText Snippets/aliquot_plus.sublime-snippet

@@ -12,5 +12,3 @@
 	<scope>source.json</scope>
 	<description>'extendable group of aliquot selector'</description>
 </snippet>
-
-

autoprotocol-python SublimeText Snippets/aliquot_plus_plus.sublime-snippet

@@ -12,5 +12,3 @@
 	<scope>source.json</scope>
 	<description>'extendable group of aliquot selectors'</description>
 </snippet>
-
-

autoprotocol-python SublimeText Snippets/all_wells.sublime-snippet

@@ -5,4 +5,4 @@ all_wells()
     <tabTrigger>all_wells</tabTrigger>
     <scope>source.python</scope>
     <description>Returns a WellGroup</description>
-</snippet>
+</snippet>

autoprotocol-python SublimeText Snippets/another_choice.sublime-snippet

@@ -7,5 +7,3 @@
 	<!-- Optional: Set a scope to limit where the snippet will trigger -->
 	<scope>source.json</scope>
 </snippet>
-
-

autoprotocol-python SublimeText Snippets/another_gc.sublime-snippet

@@ -12,5 +12,3 @@
 	<scope>source.json</scope>
 	<description>adds group within choice option</description>
 </snippet>
-
-

autoprotocol-python SublimeText Snippets/another_stepthermo.sublime-snippet

@@ -12,5 +12,3 @@ ${4:"call another_stepthermo for more steps"}
 	<scope>source.json</scope>
   <description>adds step w/temp + time</description>
 </snippet>
-
-

autoprotocol-python SublimeText Snippets/another_thermo.sublime-snippet

@@ -17,5 +17,3 @@
 	<scope>source.json</scope>
   <description>adds another cycle group</description>
 </snippet>
-
-

autoprotocol-python SublimeText Snippets/append.sublime-snippet

@@ -2,5 +2,5 @@
 	<content><![CDATA[append(${1:Object})]]></content>
 	<tabTrigger>append</tabTrigger>
 	<scope>source.python</scope>
-	<description>Appends objects</description> 
-</snippet>
+	<description>Appends objects</description>
+</snippet>

autoprotocol-python SublimeText Snippets/as_dict.sublime-snippet

@@ -3,4 +3,4 @@
     <tabTrigger>as_dict</tabTrigger>
     <scope>source.python</scope>
     <description>Returns protocol as dict</description>
-</snippet>
+</snippet>

autoprotocol-python SublimeText Snippets/autopick.sublime-snippet

@@ -5,4 +5,4 @@ autopick(sources=${1:[Well sources]}, dests=${2:[Well dests]})
     <tabTrigger>autopick</tabTrigger>
     <scope>source.python</scope>
     <description>Pick colonies from agar</description>
-</snippet>
+</snippet>

autoprotocol-python SublimeText Snippets/boolean.sublime-snippet

@@ -13,5 +13,3 @@
 	<scope>source.json</scope>
 	<description>boolean input</description>
 </snippet>
-
-

autoprotocol-python SublimeText Snippets/choice.sublime-snippet

@@ -17,5 +17,3 @@
 	<scope>source.json</scope>
   <description>choice input</description>
 </snippet>
-
-

autoprotocol-python SublimeText Snippets/container_plus.sublime-snippet

@@ -12,5 +12,3 @@
 	<scope>source.json</scope>
 	<description>extendable group of container selector</description>
 </snippet>
-
-

autoprotocol-python SublimeText Snippets/container_type.sublime-snippet

@@ -3,4 +3,4 @@
 	<tabTrigger>container_type</tabTrigger>
 	<scope>source.python</scope>
 	<description>Returns ContainerTyper</description>
-</snippet>
+</snippet>

autoprotocol-python SublimeText Snippets/cover.sublime-snippet

@@ -5,4 +5,4 @@ cover(ref=${1:Container ref})
     <tabTrigger>cover</tabTrigger>
     <scope>source.python</scope>
     <description>Places lid on container</description>
-</snippet>
+</snippet>

autoprotocol-python SublimeText Snippets/csv_table.sublime-snippet

@@ -19,5 +19,3 @@
 	<scope>source.json</scope>
   <description>csv table input</description>
 </snippet>
-
-

autoprotocol-python SublimeText Snippets/decimal.sublime-snippet

@@ -13,5 +13,3 @@
 	<scope>source.json</scope>
 	<description>decimal input type</description>
 </snippet>
-
-

autoprotocol-python SublimeText Snippets/decompose.sublime-snippet

@@ -5,4 +5,4 @@ decompose(idx=${1:well_ref})
     <tabTrigger>decompose</tabTrigger>
     <scope>source.python</scope>
     <description>Returns a tuple</description>
-</snippet>
+</snippet>

autoprotocol-python SublimeText Snippets/discard.sublime-snippet

@@ -5,4 +5,4 @@ discard()
     <tabTrigger>discard</tabTrigger>
     <scope>source.python</scope>
     <description>Discards the container</description>
-</snippet>
+</snippet>

autoprotocol-python SublimeText Snippets/dispense.sublime-snippet

@@ -5,4 +5,4 @@ dispense(ref=${1:Container ref}, reagent="${2:Str reagent}", columns=[{"column":
     <tabTrigger>dispense</tabTrigger>
     <scope>source.python</scope>
     <description>Dispense reagent to columns</description>
-</snippet>
+</snippet>

autoprotocol-python SublimeText Snippets/dispense_full.sublime-snippet

@@ -5,4 +5,4 @@ dispense_full_plate(ref=${1:Container ref}, reagent="${2:Str reagent}", volume="
     <tabTrigger>dispense_full_plate</tabTrigger>
     <scope>source.python</scope>
     <description>Dispense to every well</description>
-</snippet>
+</snippet>

autoprotocol-python SublimeText Snippets/flash_freeze.sublime-snippet

@@ -5,4 +5,4 @@ flash_freeze(container=${1:Container container}, duration="${2:Str duration}")
     <tabTrigger>flash_freeze</tabTrigger>
     <scope>source.python</scope>
     <description>Flash freeze contents</description>
-</snippet>
+</snippet>

autoprotocol-python SublimeText Snippets/flow_analyze.sublime-snippet

@@ -5,4 +5,4 @@ flow_analyze(dataref="${1:Str dataref}", FSC=${2:Dict FSC}, SSC=${3:Dict SSC}, n
     <tabTrigger>flow_analyze</tabTrigger>
     <scope>source.python</scope>
     <description>Perform flow cytometry</description>
-</snippet>
+</snippet>

autoprotocol-python SublimeText Snippets/fluorescence.sublime-snippet

@@ -5,4 +5,4 @@ fluorescence(ref=${1:Container ref}, wells=${2:WellGroup wells}, excitation="${3
     <tabTrigger>fluorescence</tabTrigger>
     <scope>source.python</scope>
     <description>Read the fluoresence of well</description>
-</snippet>
+</snippet>

autoprotocol-python SublimeText Snippets/fromstring.sublime-snippet

@@ -5,4 +5,4 @@ fromstring(${1:Str s})
     <tabTrigger>fromstring</tabTrigger>
     <scope>source.python</scope>
     <description>Convert string to Unit</description>
-</snippet>
+</snippet>

autoprotocol-python SublimeText Snippets/gel_purify.sublime-snippet

@@ -5,4 +5,4 @@ gel_purify(extracts=${1:[Dict extracts]}, volume="${2:Str volume}", matrix="${3:
     <tabTrigger>gel_purify</tabTrigger>
     <scope>source.python</scope>
     <description>Purifies gel</description>
-</snippet>
+</snippet>

autoprotocol-python SublimeText Snippets/gel_separate.sublime-snippet

@@ -5,4 +5,4 @@ gel_separate(wells=${1:WellGroup wells}, volume="${2:Str volume}", matrix="${3:S
     <tabTrigger>gel_separate</tabTrigger>
     <scope>source.python</scope>
     <description>Agarose gel separation</description>
-</snippet>
+</snippet>

autoprotocol-python SublimeText Snippets/group.sublime-snippet

@@ -5,7 +5,7 @@
   "description": "${2:...}",
   "label": "${3:...}",
   "inputs": {
-    ${4:"input1_snippet"} 
+    ${4:"input1_snippet"}
     ${5:"input2_snippet"}
   },
 },
@@ -15,5 +15,3 @@
 	<!-- Optional: Set a scope to limit where the snippet will trigger -->
 	<scope>source.json</scope>
 </snippet>
-
-