Apppublic

federicobravetti/arc-agi-3

sourceHugging Faceupdated 3mo agoView on Hugging Face

0likes

App README

uv-powered Python Project Template

A Python project template built with uv. It already includes:

—Ruff for linting and formatting;
—mypy for type checking;
—pytest for testing;
—coverage for test coverage reporting;
—Poe the Poet for task management;
—Renovate configuration for automated dependency updates;
—semantic-release configuration with conventional commits for automated releases to PyPI.

The template starts with a minimal package named uv_python_project_template, which will be renamed when you create a new repository from this template.

Project Structure

bash

<root directory>
├── src/                              # source root for the Python package
│   └── uv_python_project_template/   # main package (renamed into your project name)
│       ├── __init__.py
│       └── main.py                   # application entry point
├── test/                            # test package
│   └── test_my_class.py              # pytest example
├── .github/                          # configuration of GitHub Actions
│   └── workflows/
│       ├── check.yml                 # runs checks and tests on multiple OSs and Python versions
│       ├── deploy.yml                # releases to PyPI/TestPyPI with semantic-release
│       └── init.yml                  # initializes repositories created from this template
├── CHANGELOG.md                      # generated release changelog
├── LICENSE                           # license file
├── package.json                      # Node.js dependencies for semantic-release
├── pyproject.toml                    # Python project configuration, dependencies, and tasks
├── renovate.json                     # configuration of Renovate bot for dependency updates
├── release.config.mjs                # semantic-release configuration
├── rename-template.sh                # CI helper script used by init.yml to rename the project
└── uv.lock                           # locked Python dependency versions

Requirements

—Only uv and
—Node.js and npm, for semantic-release and package publishing.

You can install uv following the instructions in the documentation.

Python Installation

You can install and handle Python versions with uv:

bash

uv python install 3.12
uv python pin 3.12
uv python list

Creating a Project from this Template

1.Create a new repository from this template on GitHub.

1.Let the initialization workflow run.

The .github/workflows/init.yml workflow runs automatically on main or master when the repository is not marked as a template. It calls rename-template.sh to replace the template placeholders with the repository name, removes the initialization workflow, and commits the result.

1.Install dependencies:

bash

    uv run poe sync

1.Run the checks:

bash

    uv run poe static-checks
    uv run poe format-check
    uv run poe test

1.Start building your project in src/uv_python_project_template/ and add tests under test/.

Main Commands

Running the Application

uv run uv_python_project_template to run the application entry point defined in pyproject.toml.

Dependency Management

Command	Description
`uv sync`	Create or update the local environment from `pyproject.toml` and `uv.lock`.
`uv run uv_python_project_template`	Run the application entry point.
`uv add <package>`	Add a runtime dependency.
`uv add --dev <package>`	Add a development dependency.
`uv remove <package>`	Remove a dependency.
`uv lock`	Update the lock file after dependency changes.
`uv sync --locked`	Sync the environment strictly to the locked versions.

Configured Tasks

Project task aliases are defined in pyproject.toml under [tool.poe.tasks] and can be run through uv.

Command	Description
`uv run poe test`	Run the pytest test suite.
`uv run poe coverage`	Run tests through coverage.
`uv run poe coverage-report`	Print a terminal coverage report with missing lines.
`uv run poe coverage-html`	Generate an HTML coverage report in `htmlcov/`.
`uv run poe ruff-check`	Run Ruff lint checks.
`uv run poe ruff-fix`	Run Ruff and apply automatic fixes.
`uv run poe format`	Format code with Ruff.
`uv run poe format-check`	Check formatting without changing files.
`uv run poe mypy`	Type-check `src/` and `test/` with Mypy.
`uv run poe compile`	Compile `src/` and `test/` to catch syntax errors.
`uv run poe static-checks`	Run the configured static checks, currently Ruff and Mypy.

Release a new version on PyPi

New versions are automatically released on PyPi via GitHub Actions, when a push is made on the main or master branch.

The version number is updated automatically by the semantic-release tool, which uses the commit messages to infer the type of the release (major, minor, patch).

It is paramount that the commit messages follow the Conventional Commits specification, in order for semantic-release to compute version numbers correctly.

For successfully publishing, configure these repository secrets as needed:

—PYPI_TOKEN: token for publishing to PyPI.
—TEST_PYPI_TOKEN: token for publishing to TestPyPI.
—RELEASE_TOKEN: GitHub token used by semantic-release.

The workflow dry-runs releases outside main or master, and also dry-runs the initial commit.

Automatic updates of dependencies (via Renovate)

The project is configured to use Renovate to automatically open pull-requests to update dependencies declared in pyproject.toml.

By default, Renovate will assign such pull-requests to the user who created the repository from this template.

If the project has tests (which is the case for this template), Renovate will only merge such pull-requests if all tests pass.

When some test fails, Renovate will leave a comment on the pull-request, so that you can fix the issue manually.

To make Renovate work, you need to enable it for your repository. To do so, please follow the instruction at <https://docs.renovatebot.com/getting-started/installing-onboarding/#hosted-githubcom-app>

Finally, please remember to enable PR auto-merging in your repository settings, otherwise Renovate will not be able to merge the pull-requests it opens, even if all tests pass. To do so, please follow the instructions available here.

Notice that the combination between Renovate, and Semantic Release may lead to a number of releases being created automatically.

License

This template is distributed under the license included in LICENSE.