/base-template

Base repo template

Primary LanguagePythonBSD 3-Clause "New" or "Revised" LicenseBSD-3-Clause

SSEC-JHU <package_name>

CI Documentation Status codecov Security

SSEC-JHU Logo

Base repo template to be used by all others.

Things to do when using this template:

  • Run python project_setup.py
  • Uncomment above DOI in README.md and correct <insert_ID_number>.
  • Correct "description" field in .zenodo.json to reflect description of child repo.
  • Correct the CI Status badge with the correct token in the URL.
  • Import package into https://readthedocs.org/.

What's included in this template:

  • Licence file
  • Code of Conduct
  • Build & Setup, inc. pip dependency requirements.
  • Dependabot GitHub action
  • CI for GitHub actions: lint, pytest, build & publish docker image to GitHub Packages.
  • Dockerfile.
  • Pytest example(s).
  • Githooks.

Installation, Build, & Run instructions

Conda:

For additional cmds see the Conda cheat-sheet.

  • Download and install either miniconda or anaconda.
  • Create new environment (env) and install conda create -n <environment_name>
  • Activate/switch to new env conda activate <environment_name>
  • cd into repo dir.
  • Install python and pip conda install python=3.11 pip
  • Install all required dependencies (assuming local dev work), there are two ways to do this
    • If working with tox (recommended) pip install -r requirements/dev.txt.
    • If you would like to setup an environment with all requirements to run outside of tox pip install -r requirements/all.txt.

Build:

with Docker:

  • Download & install Docker - see Docker install docs.
  • cd into repo dir.
  • Build image: docker build -t <image_name> .

with Python ecosystem:

  • cd into repo dir.
  • conda activate <environment_name>
  • Build and install package in <environment_name> conda env: pip install .
  • Do the same but in dev/editable mode (changes to repo will be reflected in env installation upon python kernel restart) NOTE: This is the preferred installation method for dev work. pip install -e .. NOTE: If you didn't install dependencies from requirements/dev.txt, you can install a looser constrained set of deps using: pip install -e .[dev].

Run

with Docker:

  • Follow the above Build with Docker instructions.
  • Run container from image: docker run -d -p 8000:8000 <image_name>. NOTE: -p 8000:8000 is specific to the example application using port 8000.
  • Alternatively, images can be pulled from ghcr.io/ssec-jhu/ e.g., docker pull ghcr.io/ssec-jhu/base-template:pr-1.

with Python ecosystem:

Usage:

To be completed by child repo.

Testing

NOTE: The following steps require pip install -r requirements/dev.txt.

Using tox

  • Run tox tox. This will run all of linting, security, test, docs and package building within tox virtual environments.
  • To run an individual step, use tox -e {step} for example, tox -e test, tox -e build-docs, etc.

Typically, the CI tests run in github actions will use tox to run as above. See also ci.yml.

Outside of tox:

The below assume you are running steps without tox, and that all requirements are installed into a conda environment, e.g. with pip install -r requirements/all.txt.

NOTE: Tox will run these for you, this is specifically if there is a requirement to setup environment and run these outside the purview of tox.

Linting:

Facilitates in testing typos, syntax, style, and other simple code analysis tests.

  • cd into repo dir.
  • Switch/activate correct environment: conda activate <environment_name>
  • Run ruff .
  • This can be automatically run (recommended for devs) every time you git push by installing the provided pre-push git hook available in ./githooks. Instructions are in that file - just cp ./githooks/pre-push .git/hooks/;chmod +x .git/hooks/pre-push.

Security Checks:

Facilitates in checking for security concerns using Bandit.

  • cd into repo dir.
  • bandit --severity-level=medium -r package_name

Unit Tests:

Facilitates in testing core package functionality at a modular level.

  • cd into repo dir.
  • Run all available tests: pytest .
  • Run specific test: pytest tests/test_util.py::test_base_dummy.

Regression tests:

Facilitates in testing whether core data results differ during development.

  • WIP

Smoke Tests:

Facilitates in testing at the application and infrastructure level.

  • WIP

Build Docs:

Facilitates in building, testing & viewing the docs.

  • cd into repo dir.
  • pip install -r requirements/docs.txt
  • cd docs
  • make clean
  • make html
  • To view the docs in your default browser run open docs/_build/html/index.html.