General Notes

Requirements for Preferred Setup

Run Locally w/ Docker

  • Copy the docker environment (i.e. *-docker-compose.yaml) of your choice corresponding to your usage to docker-compose.yaml. This file is untracked so feel free to modify as necessary. Idea is to commit anything generic but system/setup dependent should go on ‘your’ version i.e. local UID/GID, etc.

  • Check the first header comment which will provide the best instruction on how to start the service; yes, it is a bit long. Note: Any of the keyword arguments prepended to the docker-compose command can be safely moved into a dedicated .env and read automatically if they are not evaluated i.e. $(...). Below is a brief description of the non-evaluated environment variables:

    PY_VER=3.8    # Python version: 3.6|3.7|3.8
IMAGE=djtest  # Image type:     djbase|djtest|djlab|djlabhub
DISTRO=alpine # Distribution:   alpine|debian
AS_SCRIPT=    # If 'TRUE', will not keep container alive but run tests and exit

Note

Deployment options currently being considered are Docker Compose and Kubernetes.

Run Locally w/ Python

  • Set environment variables for port assignment (PHARUS_PORT, defaults to 5000) and API route prefix (PHARUS_PREFIX e.g. /api, defaults to empty string).

  • For development, use CLI command pharus. This method supports hot-reloading so probably best coupled with pip install -e ....

  • For production, use gunicorn --bind 0.0.0.0:${PHARUS_PORT} pharus.server:app.

Run Tests for Development w/ Pytest, Flake8, Black

  • Set pharus testing environment variables:

    PKG_DIR=/opt/conda/lib/python3.8/site-packages/pharus # path to pharus installation
TEST_DB_SERVER=example.com:3306 # testing db server address
TEST_DB_USER=root # testing db server user (needs DDL privilege)
TEST_DB_PASS=unsecure # testing db server password

  • For syntax tests, run flake8 ${PKG_DIR} --count --select=E9,F63,F7,F82 --show-source --statistics

  • For pytest integration tests, run pytest -sv --cov-report term-missing --cov=${PKG_DIR} /main/tests

  • For style tests, run:

    black ${PKG_DIR} --check -v --extend-exclude "^.*dynamic_api.py$"
flake8 ${PKG_DIR} --count --max-complexity=20 --max-line-length=94 --statistics --exclude=*dynamic_api.py --ignore=W503

Creating Sphinx Documentation from Scratch

Recommend the follow to be ran within the pharus container in docs Docker Compose environment.

  • Run the following commands and complete the prompts as requested.

    mkdir docs
cd docs
sphinx-quickstart

  • In docs/conf.py add to the beginning:

    import os
import sys
sys.path.insert(0, os.path.abspath('..'))

  • In docs/conf.py:extensions append ['sphinx.ext.autodoc', 'sphinxcontrib.httpdomain']. See requirements_docs.txt and docker-compose-docs.yaml for details on documentation dependencies.

  • Run the following to automatically generate the API docs:

    sphinx-apidoc -o . .. ../tests/* ../setup.py

  • Add modules within the toctree directive in index.rst.

  • Build the docs by running:

    make html

References