A template to help you start a new project in the SDyPy ecosystem.
To use this template, you have multiple options. The following two will cover most use cases:
You can use GitHub's templating functionality. A new repository will be created on GitHub for your project. Use this option if your project does not yet have an online repository.
Click the "Use this template" button on the project template GitHub repository (see image below).
Select and confirm a name for your new repository, and a copy of this template will be created for you.
You can now clone your new repository onto your local machine. If your new repository is located at
https://github.com/<your_name>/<my_new_project>, for example:$ git clone https://github.com/<your_name>/<my_new_project>A folder named
<my_new_project>will be created on your machine. It is already connected to your new GitHub repository, and you can begin developing your package!If you already have a repository for your project, located for example at
https://github.com/<your_name>/<my_existing_project>, clone the template onto your local machine:$ git clone https://github.com/sdypy/sdypy_template_projectThe template files will be downloaded into the
sdypy_template_projectfolder. This clone is connected to the template repository, not to yours.You can now either copy these files into your existing local project folder, or connect the cloned repository in the
sdypy_template_projectfolder with your existing online repository:$ git remote rm origin $ git remote add origin https://github.com/<your_name>/<my_existing_project>.git
You are now set up to begin working on your project.
To begin development, create a virtual environment and install the project in editable mode using uv:
$ uv venv
$ uv pip install -e ".[dev]"Activate the environment, so that the python, pytest and make commands below use it:
$ source .venv/bin/activate(On Windows, run .venv\Scripts\activate instead.)
All dependencies are declared in pyproject.toml: the runtime ones under
[project] dependencies, the development and documentation ones under
[project.optional-dependencies] (dev and docs).
Now you can replace the core source code modules in sdypy_template_project/ with your code.
Remember to replace the project name with your own. The import name (sdypy_template_project) and the distribution name (sdypy-template-project) appear in the following places:
pyproject.toml—name(the distribution name, and the self-reference in thedevextra),authors,maintainers,description,keywords,[project.urls], and theincludepaths of the wheel and sdist build targetsREADME.rstandCONTRIBUTING.rstdocs/source/conf.py—project,author,copyright, andrepository_url/repository_branchinhtml_theme_optionsdocs/source/code.rst— theautomodulepathssync_version.py— thepackage_namevariable at the top.readthedocs.yaml— nothing project-specific, but check the Python version.github/workflows/release-and-publish-to-pypi.yml— the branch name in thegit pushstep (masterormain) and the PyPI project name in theenvironmenturltests/andexamples/— the imports- the
sdypy_template_project/directory name itself, and the usage text in its__main__.py
To find any occurrence you missed, search the project:
$ git grep -n -e sdypy_template_project -e sdypy-template-projectConsider adding unit tests for your project by modifying the files found in tests/. The provided test files are set up to work with pytest.
To also use the Sphinx documentation, modify files in docs/source, or remove the docs/ folder and quickstart a fresh documentation version using the sphinx-quickstart command (see Sphinx - Getting started for more info).
The project code is structured as follows:
- pyproject.toml
- the main project configuration file: package metadata, dependencies, and build system
- sync_version.py
- helper script to keep the version consistent across
pyproject.toml,__init__.py, anddocs/source/conf.py - README.rst
- the main project description / documentation file
- CONTRIBUTING.rst
- a document containing information for potential contributors (developers) of the package
- License
- the project license
- .github/
- GitHub Actions workflow definitions for CI testing and automated PyPI releases, and the Dependabot configuration that keeps those actions up to date
- .readthedocs.yaml
- the Read the Docs build configuration (required by Read the Docs)
- .gitignore
- defines the files in the project directory to be excluded from version control
- tests/
- contains project unit tests
- sdypy_template_project/
- contains the core project source code, separated into meaningful sub-modules
- examples/
- scripts and notebooks with examples to showcase the project
- docs/
- the documentation source (the build output in
docs/build/is not version-controlled)
(For a more complex and customizable project structure, see the Cookiecutter project.)
Use sync_version.py to keep the version consistent across pyproject.toml, __init__.py, and docs/source/conf.py.
Bump the patch/minor/major version:
$ python sync_version.py --bump patch
$ python sync_version.py --bump minor
$ python sync_version.py --bump majorOr set an explicit version:
$ python sync_version.py --set-version 1.2.3The script updates all three files in one step, so you never have to edit them manually.
By setting up Read the Docs, your project documentation can automatically be built and published as a publicly available website.
To test your documentation locally, install the documentation dependencies
(uv pip install -e ".[docs]", already included in [dev]) and run the
following (starting from the main project directory):
$ cd docs
$ make clean
$ make htmlYour documentation files will be built inside the docs/build/html folder.
The included GitHub Actions workflows run automatically once you push your project to GitHub:
- Testing (
.github/workflows/python-package.yml) — runs flake8 and pytest on every push and pull request, across Python 3.13 to 3.15. - Release (
.github/workflows/release-and-publish-to-pypi.yml) — triggered when you push av*tag; syncs the version, builds the distribution, creates a GitHub Release, and publishes to PyPI.
Publishing uses PyPI Trusted Publishing, so no API token is stored in the repository. Register your GitHub repository as a trusted publisher on PyPI with these values:
- Workflow name:
release-and-publish-to-pypi.yml - Environment name:
pypi
For a project that is not yet on PyPI, add a pending publisher under Account
settings → Publishing and use the name from pyproject.toml as the PyPI
project name. The first tagged release creates the project. For a project that
already exists, go to Your projects → Manage → Publishing instead.
PyPI trusts only this exact workflow file name. If you rename the file, update the trusted publisher on PyPI, or publishing fails.
The release job runs in the pypi GitHub environment. GitHub creates it on the
first run. To require manual approval before each release, add a protection rule
under Settings → Environments → pypi.
If you cannot use Trusted Publishing, the workflow contains a commented-out
fallback that uses a PYPI_API_TOKEN repository secret instead.
.github/dependabot.yml opens a monthly pull request when a newer version of a
used GitHub Action is available; without it the actions quietly fall behind (and
eventually run on an unsupported Node runtime).
Automated (recommended)
- Bump and sync the version:
$ python sync_version.py --bump patch- Commit, tag, and push:
$ git add -u
$ git commit -m "bump version to X.Y.Z"
$ git tag vX.Y.Z
$ git push && git push --tagsThe release workflow will build the package and publish it to PyPI automatically.
Manual (fallback)
Build the distribution:
$ python -m buildTest the resulting .whl locally in a fresh environment:
$ uv venv test-env
$ uv pip install --python test-env dist/sdypy_template_project-X.Y.Z-py3-none-any.whlUpload to TestPyPI first to verify, then to the main index:
$ python -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*
$ python -m twine upload dist/*For more information on the publishing process, see the Python packaging tutorial.
Once published, the package can be installed with:
$ pip install sdypy-template-projectThe distribution name (sdypy-template-project, used with pip) corresponds to the
import name (sdypy_template_project, used in Python). Keep the two in sync
when you rename the project.
After installing the package, you can use it like any other Python module.
Here is a simple example with the current example code:
import sdypy_template_project as iep
import numpy as np
import matplotlib.pyplot as plt
video = np.load('examples/speckle.npy', mmap_mode='r')
results = iep.get_displacements(video, point=[5, 5], roi_size=[7, 7])
plt.figure()
plt.plot(results[0], label='x')
plt.plot(results[1], label='y')
plt.xlabel('frame [/]')
plt.ylabel('displacement [pixel]')
plt.legend()
plt.show()You can also run this example with the following command in the project base directory:
$ python -m examples.basic_exampleOnce Read the Docs is set up, the documentation is published at
https://<your-project>.readthedocs.io.