python-src-template

A template I use for most projects.

Straight forward to use!

Kind of...

While this is the way I usually start my Python project setup this is far from the only way to do things. I invite you to use my template. I also challenge you to craft the structure that works both for your project and you, creating your own template. The amount of learning in doing so is well worth the effort.

---

Quick setup:

Clone the repo or click the "Use this template" button in GitHub

If you clone the repo instead of using it as a template; be sure to delete the .git folder and run git init before making any changes.

Run the init_template.py script found in the root of the repo. You will be prompted for details and the steps listed below completed for you. You may then delete the init_template.py file, commit all changes, and dev on.

---

What to change for manual setup:

• Remove the following place-holder files:
  • src/module_name/sample_data
  • src/module_name/sample.py
  • tests/test_sample.py
• Raname src/module_name to the desired project name
• Update pyproject.toml:
  • [project] section:
    • name, version, description, authors
    • dependencies
      • see alternative for requirements.in if desired
  • [project.urls]
    • Update github homepage values
  • [tool.coverage.run]
    • source_pkgs : Update to reflect new module_name and any additional modules
• Coverage badge setup:
  • If needed: Create an empty, private gist
  • Save the gist's id to repository secret COV_BADGE_GIST
  • If needed: Create a personal access token (PAT) with gist access
  • Save the PAT to repository secret COV_BADGE_TOKEN
  • Note: The coverage step is completely optional and will be skipped if above secrets are missing.
• Update README.md - Badges:
  • Update owner and repo name of urls for pre-commit.ci badge
  • Update owner and repo name of urls for python tests badge
  • Update owner and repo name of gist url for coverage badge
  • Replace gistId (from coverage setup) for coverage badge
• Update README.md - Content:
  • Replace title and this setup information
  • Under Local developer installation
    • Replace {{ORG_NAME}} with github name
    • Replace {{REPO_NAME}} with repo name

Why src/ structure:

The benefit I get from this project structure comes from testing. The src/ structure forces us to test on the installed version of the modules within site-packages/ and not our local code. Even though these files are symlinked in most cases with the dev install, the calls and import references are the same. This ensures we are testing on what will be setup in the not-my machine.

---

Local developer installation

It is strongly recommended to use a virtual environment (venv) when working with python projects. Leveraging a venv will ensure the installed dependency files will not impact other python projects or any system dependencies.

The following steps outline how to install this repo for local development. See the CONTRIBUTING.md file in the repo root for information on contributing to the repo.

Windows users: Depending on your python install you will use py in place of python to create the venv.

Linux/Mac users: Replace python, if needed, with the appropriate call to the desired version while creating the venv. (e.g. python3 or python3.8)

All users: Once inside an active venv all systems should allow the use of python for command line instructions. This will ensure you are using the venv's python and not the system level python.

---

Installation steps

Clone this repo and enter root directory of repo:

$ git clone https://github.com/[ORG NAME]/[REPO NAME]
$ cd [REPO NAME]

Create the venv:

$ python -m venv venv

Activate the venv:

# Linux/Mac
$ . venv/bin/activate

# Windows
$ venv\Scripts\activate

The command prompt should now have a (venv) prefix on it. python will now call the version of the interpreter used to create the venv

Install editable library and development requirements:

# Update pip and tools
$ python -m pip install --upgrade pip

# Install editable version of library
$ python -m pip install --editable .[dev]

Install pre-commit (see below for details):

$ pre-commit install

---

Misc Steps

Run pre-commit on all files:

$ pre-commit run --all-files

Run tests:

$ tox [-r] [-e py3x]

Build dist:

$ python -m pip install --upgrade build

$ python -m build

To deactivate (exit) the venv:

$ deactivate

---

Note on flake8:

flake8 is included in the requirements-dev.txt of the project. However it disagrees with black, the formatter of choice, on max-line-length and two general linting errors. .pre-commit-config.yaml is already configured to ignore these. flake8 doesn't support pyproject.toml so be sure to add the following to the editor of choice as needed.

--ignore=W503,E203
--max-line-length=88

---

pre-commit

A framework for managing and maintaining multi-language pre-commit hooks.

This repo is setup with a .pre-commit-config.yaml with the expectation that any code submitted for review already passes all selected pre-commit checks. pre-commit is installed with the development requirements and runs seemlessly with git hooks.

---

Makefile

This repo has a Makefile with some quality of life scripts if the system supports make. Please note there are no checks for an active venv in the Makefile.

PHONY	Description
init	Update pip to newest version
install	install the project
install-dev	install development/test requirements and project as editable install
upgrade-dev	update all dependencies, regenerate requirements.txt (disabled by default)
build-dist	Build source distribution and wheel distribution
clean	Deletes build, tox, coverage, pytest, mypy, cache, and pyc artifacts