Contributing

Dependencies

This project requires Python 3.7.2+.

This project uses Poetry to manage dependencies, virtual environments, builds, and packaging. Install it by following the instructions here.

Environment

1. Create a root folder for the package, as outlined at Root Folder:

   $ ROOT=powertools-dev
   $ mkdir $ROOT
   $ cd $ROOT
   

2. Clone the repo:

   ROOT $ git clone https://github.com/PrincetonCS-UCA/codepost-powertools.git
   ROOT $ cd codepost-powertools
   

3. Create/update the virtual environment with Poetry:

   ROOT/codepost-powertools $ poetry install --with dev
   

   If editing the docs, be sure to include the optional docs group:

   ROOT/codepost-powertools $ poetry install --with dev,docs
   

Writing Code

• The code is linted with pylint. See the .pylintrc file for the configuration.

• The code is formatted with black, using a line length of 79 characters.

• Imports are formatted with isort, using the black profile. See the pyproject.toml file for the configuration.

Running Commands

• For commands that require the virtual environment, prefix the command with poetry run:

  ROOT/codepost-powertools $ poetry run pytest
  ROOT/codepost-powertools $ poetry run mypy src
  

  Alternatively, start the Poetry shell:

  ROOT/codepost-powertools $ poetry shell
  (codepost-powertools-py3.X) ROOT/codepost-powertools $ pytest
  (codepost-powertools-py3.X) ROOT/codepost-powertools $ mypy src
  

• To run the Powertools CLI, you must be in the root folder. Since the poetry command requires a visible pyproject.toml file, you will need to activate the virtual environment before switching back to the root folder.

  ROOT/codepost-powertools $ poetry shell
  (codepost-powertools-py3.X) ROOT/codepost-powertools $ cd ..
  (codepost-powertools-py3.X) ROOT $ cptools ...
  

  It might be easier to have a separate terminal tab/window open for this purpose.

Testing

• The tests are defined in the tests/ directory using pytest. The pyproject.toml file is already configured to run the tests with the command:

  ROOT/codepost-powertools $ poetry run pytest
  # Or, with the virtual environment activated:
  (codepost-powertools-py3.X) ROOT/codepost-powertools $ pytest
  

• The codebase can be statically type-checked using mypy:

  ROOT/codepost-powertools $ poetry run mypy src
  # Or, with the virtual environment activated:
  (codepost-powertools-py3.X) ROOT/codepost-powertools $ mypy src
  

  Note that there are a few expected warnings that are explained at mypy warnings.

• Test the test coverage with coverage:

  ROOT/codepost-powertools $ poetry run coverage run -m pytest
  # Or, with the virtual environment activated:
  (codepost-powertools-py3.X) ROOT/codepost-powertools $ coverage run -m pytest
  

  Note that there are no tests written for the CLI, so files pertaining to that will not have full coverage.

Documentation

The documentation is written in the docs/ folder using Sphinx and hosted on Read the Docs.

To build the documentation, run the following:

(codepost-powertools-py3.X) ROOT/codepost-powertools $ cd docs
(codepost-powertools-py3.X) ROOT/codepost-powertools/docs $ make html

To activate a local server at http://localhost:8000/ that auto-updates on changes, run the following:

(codepost-powertools-py3.X) ROOT/codepost-powertools/docs $ make livehtml