Development Notes

The development notes below assume a PowerShell prompt is being used on a Windows machine.

Run the following before any of the following tasks (once the virtual environment itself has been built):

# update the following to your local paths
$VIRTUALENV="C:\VirtualEnvs\mappyfile3"
$MAPPYFILE_PATH="D:\GitHub\mappyfile"

.$VIRTUALENV\Scripts\activate.ps1
cd $MAPPYFILE_PATH

Building the Dev Virtual Environment

Run from the root of the mappyfile project folder:

$VIRTUALENV="C:\VirtualEnvs\mappyfile"
$MAPPYFILE_PATH="D:\GitHub\mappyfile"

cd "C:\Python310\Scripts"
.\pip install virtualenv
.\virtualenv $VIRTUALENV
.$VIRTUALENV\Scripts\activate.ps1
cd $MAPPYFILE_PATH
pip install -e .
pip install -r requirements-dev.txt
# optionally install lark_cython
pip install -e .[lark_cython]

Testing Locally

Ensure the development code has been deployed to a virtual environment as in the step above.

Then run from the root of the mappyfile project folder:

pytest

To see a list of which tests will run, without actually running them:

pytest --collect-only

To run a single test file:

pytest tests/test_snippets.py

To also include doctests:

pytest --doctest-modules --ignore=./docs/examples/pretty_printing.py

Linting

flake8 .

Or to export to file:

flake8 . > D:\Temp\lint.txt

Prospector

pip install prospector
prospector
# or just the main source code folder
prospector ./mappyfile

Mypy

To run static type checking:

mypy mappyfile tests

Documentation

To build the Sphinx documentation:

sphinx-build -b html "$MAPPYFILE_PATH\docs" "$MAPPYFILE_PATH\_build"
# to force a rebuild of all files
sphinx-build -a -E -b html "$MAPPYFILE_PATH\docs" "$MAPPYFILE_PATH\_build"

To run in a local browser:

.$VIRTUALENV\Scripts\activate.ps1
C:\Python310\python -m http.server --directory="$MAPPYFILE_PATH\_build" 57921

# open browser and go to http://localhost:57921

To automatically rebuild docs using watchdog:

# run the following to automatically rebuild the project
# python -m pip install -U "watchdog[watchmedo]"
cd $MAPPYFILE_PATH
watchmedo shell-command --patterns="*.rst;*.txt" --recursive --command='sphinx-build -b html "./docs" "./_build"' ./docs