cookiecutter-uv

To initiate a new Python project using this template, use cookiecutter to clone and run the template. You can do this using uvx (recommended if you have uv installed) or via pip.

1. Navigate to the directory where you want your project to reside.
2. Run one of the following commands:
   • Using uvx (preferred):

     uvx cookiecutter https://github.com/osprey-oss/cookiecutter-uv.git

   • Using pip:

     pip install cookiecutter
     cookiecutter https://github.com/osprey-oss/cookiecutter-uv.git

3. Follow the interactive prompts to configure your project settings.
4. Once the process completes, a new directory will be created. Navigate into that directory and follow the project-specific README.md instructions to finish the setup.

If you enabled PyPI publishing during project creation, follow these steps to release a new version:

1. Create an API Token on PyPI.
2. Add the API Token to your GitHub repository secrets with the name PYPI_TOKEN.
3. Create a new release on GitHub.
4. Create a new tag using the semantic versioning format *.*.*.

After generating your project, initialize a Git repository and push it to a new, empty GitHub repository. Replace <project-name> with your project directory name and <github_author_handle> with your GitHub username.

cd <project_name>
git init -b main
git add .
git commit -m "Init commit"
git remote add origin git@github.com:<github_author_handle>/<project_name>.git
git push -u origin main

When generating a project with this template, you can enable GitHub Actions workflows by setting include_github_actions to "y" in your configuration.

This adds a .github directory containing several workflows:

• on-pull-request.yml: Runs when a pull request is opened or updated.
• on-merge-to-main.yml: Runs whenever a new commit is made to the main branch.
• on-release-main.yml: Runs when a new release is created on the main branch.

Both on-pull-request.yml and on-merge-to-main.yml execute environment setup, tests, and code formatting checks using local actions defined in .github/workflows/run-checks and .github/workflows/setup-python-env.

If tox is set to "y", all workflows will additionally check for compatibility across multiple Python versions.

To include a Dockerfile in your generated project, set the dockerfile configuration option to "y" during the cookiecutter generation process.

When enabled, the generated Dockerfile performs the following actions:

1. Installs uv.
2. Sets up the project environment.
3. Executes foo.py as the default entrypoint when the container runs.

To trigger the on-release-main.yml workflow and initiate automated publishing/deployment, you must create a new release on GitHub:

1. Navigate to your repository on GitHub.
2. Click Releases in the right-hand sidebar.
3. Select Draft a new release (or visit https://github./<username>/<repository-name>/releases/new).
4. Provide a release title.
5. Create a new tag using the semantic versioning format *.*.* (where * is alphanumeric).
6. Click Publish release.

To scaffold a new project using this template, navigate to your desired parent directory and run uvx cookiecutter pointing to the repository URL. You will be prompted for various arguments to customize your project.

uvx cookiecutter https://github.com/osprey-oss/cookiecutter-uv.git

The project automatically includes pytest in the environment. A template unit test is provided in the tests directory upon project creation. You can execute the test suite using the make command.

To run tests locally, use:

make test

When generating a project using this template, you can enable VSCode devcontainer support by setting the devcontainer option to "y".

This creates a .devcontainer directory that uses the VSCode devcontainer specification to build a reproducible development environment. The environment automatically:

• Pre-installs all uv dependencies required for development, testing, and building.
• Installs pre-commit hooks.
• Configures the VSCode Python extension to use the correct Python interpreter and pytest paths.

Once the Dockerfile is generated, you can build and run the container using either Docker or Podman.

Building the image

Use the build command with a tag (-t) to name your image.

Running in the background

Use the run command with the -d flag to run the container in detached mode.

Running in interactive mode

To explore the container environment, run it in interactive mode (-it) with the --rm flag (to remove the container after exit) and override the entrypoint to bash.