Development¶
If you wish to contribute PRs to pyNTM, the sections below describe how to set up your development environment.
Currently, pyNTM adheres to the black code formatting and flake8. More info on black is below.
The black code formatting and flake8 checks occur in the CI/CD pipeline.
The sections below cover how to set up your local dev environment to run these checks prior to submitting a pull request.
Set Up Your Virtual Environment¶
Set up your virtual environment.
Virtualenv is a tool for creating isolated ‘virtual’ python environments. For directions on how to run this modeler in a virtual environment and auto-download all dependencies, follow the steps below (authored by nelsg).
Create your virtualenv¶
Create an isolated virtual environment under the directory “network_traffic_modeler_py3” with python3:
$ virtualenv -p python3 venv
Activate “venv” that sets up the required env variables:
$ source venv/bin/activate
Clone the repo per https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository#cloning-a-repository:
(venv) % git clone https://github.com/tim-fiola/network_traffic_modeler_py3.git
Cloning into 'network_traffic_modeler_py3'...
remote: Enumerating objects: 1622, done.
remote: Counting objects: 100% (378/378), done.
remote: Compressing objects: 100% (256/256), done.
remote: Total 1622 (delta 247), reused 214 (delta 120), pack-reused 1244
Receiving objects: 100% (1622/1622), 770.31 KiB | 1.89 MiB/s, done.
Resolving deltas: 100% (1107/1107), done.
(venv) %
- Install pyNTM’s required packages with “pip3”::
- (venv) % cd network_traffic_modeler_py3 (venv) % pip3 install -r requirements.txt
Installing Development Requirements¶
To install the Python modules required for development, run:
% pip3 install -r requirements_dev.txt
The Black Code Formatter¶
pyNTM uses the black code formatter. black
is an opinionated formatter that
will make changes to your files to bring them in line with the black
standards.
Setting Up Pre-Commit Hooks¶
The pre-commit
package is installed when you install the requirements_dev.txt
.
To run black
automatically after each commit, you will need to install the pre-commit hooks.
Run pre-commit install
:
% pre-commit install
You should see a response that the hook has been installed:
pre-commit installed at .git/hooks/pre-commit
This will set up a check that runs black
prior to allowing a commit, allowing you to focus on making your code, instead of worrying about your formatting.
Local Unit Testing¶
To run the unit tests locally:
Go to the repository’s
network_traffic_modeler_py3
directory:(venv) % pwd /path/to/network_traffic_modeler_py3 (venv) %
Run
pytest
:``% pytest``
If the tests fail to run due to ImportError
, depending on your OS, you may need to run one of the following pytest
variations:
``python -m pytest``
or:
``python3 -m pytest``
Tip
When submitting a pull request, your build will be tested against black and the unit tests, so it’s advantageous to test them locally prior so they don’t fail in the CI pipeline.
Remove your virtualenv¶
If you wish to remove your virtualenv when you are complete, follow the steps below.
Deactivate “venv” that unsets the virtual env variables:
$ deactivate
Remove directory “venv”:
$ rm -rf venv
pypy3¶
pyNTM is compatible with the pypy3 interpreter. The pypy3 interpreter provides a 70-80% performance improvement over the python3 interpreter.
Tip
By performance, we mean the time it takes to converge the model to produce a simulation (running update_simulation
).
It is recommended, however, to develop in python3. Developing in pypy3 is NOT recommended, because some of the developer tools are not compatible in a pypy3 environment.