SSEC-JHU <package_name>

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/.
• Update zenodo.json. For more details see zenodo.json docs and zenodo docs on contributors vs creators.
• Update quickstart guide below.

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.

Quickstart Guide

Add here, streamlined instructions on how to get the code running as swiftly as possible, and provide usage example(s). This shouldn't attempt to cover all OS's and/or build variations - just the canonical. Since users are most likely viewing this README from GitHub.com, assuming a repo context might be best, where instructions look like those below. Alternatively, if this package is distributed on PyPi, perhaps just pip install <package-name>, followed by quick user instructions, will suffice.

• git clone https://github.com/ssec-jhu/base-template
• conda create -n package_name python pip
• conda activate package_name
• pip pinstall -e .
• Add user instructions.

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:

• Follow the above Build with Python ecosystem instructions.
• Run uvicorn package_name.app.main:app --host 0.0.0.0 --port", "8000. NOTE: This is just an example and is obviously application dependent.

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.