A basic template for building Python packages.

A package built from this starter code will have the following features:

• Easy to install with uv sync (creates .venv; see pyproject.toml and uv.lock)
• Continuous integration with GitHub Actions (see .github/workflows/ci.yml and run_ci_checks.sh)
• Autoformatting with Ruff (see run_autoformat.sh)
• Linting with Ruff (see pyproject.toml)
• Type checking with ty (see pyproject.toml)
• Unit tests with pytest (see tests/)

1. Go to https://github.com/new and follow the instructions on the first page. No need to include a .gitignore, README, or LICENSE; these will be added later. After clicking "Create repository", stop -- don't follow the command line instructions. Remember the NAME of the repository and then go on to step 2.

2. Clone this repository and give it the name of your repo: git clone https://github.com/MTDickens/research-code-python-starter-template <NAME>. You now have a directory called NAME. Enter it: cd <NAME>.
3. Configure the repository: Make changes to config.json and then save.
4. Apply the configuration: Make sure that your changes to config.json are finalized because they can only be applied once. When you are ready, run python apply_configuration.py.
5. Push your changes: For example, run git add . && git commit -m "First commit" && git push -u origin main.

🎉 That's it! Your code is ready to use 🎉 You should see your code back on GitHub where you previously had an empty repository.

6. Make changes to pyproject.toml, especially in the dependencies section.
7. Set up your dev environment (uv):
   • Install runtime dependencies only (creates .venv): uv sync
   • Install dev tools (formatting/tests/type-checking): uv sync --extra develop
   • Common commands (run inside the uv environment):
     • uv run ruff format .
     • uv run ruff check .
     • uv run ty check
     • uv run pytest tests/
   • This template commits uv.lock. After changing dependencies, run uv lock and commit the updated lockfile. CI uses uv sync --frozen --extra develop.
8. Replace the starter files (README.md, LICENSE, config.json, apply_configuration.py, structs.py, utils.py and the analogous files in tests/) with some of your own.

9. Set up branch protections to prevent accidental changes to your main branch. In https://github.com/<USER>/<NAME>/settings/branches:
   • Click Add classic branch protection rule.
   • The branch pattern name is main.
   • Check "Require a pull request before merging (optionally: uncheck "Require approvals").
   • Check "Require status checks to pass before merging".
   • Check "Require branches to be up to date before merging".
   • Then type in autoformat, static-type-checking, linting, unit-tests.
   • Check "Do not allow bypassing the above settings".
10. Set up repository settings in https://github.com/<USER>/<NAME>/settings:
    • Check "Allow auto-merge".
    • Check "Automatically delete head branches".
    • Uncheck "Allow merge commits".
    • Uncheck "Allow rebase merging".
11. Set up contributor settings to lower the barrier for external contributions. In https://github.com/<USER>/<NAME>/settings/actions:
    • Update "Fork pull request workflows from outside collaborators" to "Require approval for first-time contributors who are new to GitHub".

• Branch protections only work if you have a public repository or an Enterprise account.
• You can include your repository as a dependency if it's hosted on GitHub. For example, alongside requirements like numpy or matplotlib in a pyproject.toml or requirements.txt or setup.py, you can list "<PACKAGE-NAME>@git+https://github.com/<USER>/<NAME>.git".
• You can still install the package with pip (e.g., pip install -e . for runtime-only, or pip install -e ".[develop]" to include dev tools), but this template's developer tooling and CI are optimized around uv.
• Feel free to open pull requests to improve this repository.
• You can use this code and modify it in any way without any attributions or acknowledgements (see LICENSE).