Metadata-Version: 2.3
Name: uv-demo
Version: 0.3.2
Summary: Just a demo of the uv package manager for Python.
Author: Lucas Parzianello
Author-email: Lucas Parzianello <lucaspar@users.noreply.github.com>
License: MIT License
         
         Copyright (c) 2024 lucaspar
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Terminals
Classifier: Typing :: Typed
Requires-Dist: loguru>=0.7.2
Requires-Python: >=3.11
Project-URL: Issues, https://github.com/lucaspar/uv-demo/issues
Project-URL: Releases, https://github.com/lucaspar/uv-demo/releases
Project-URL: Repository, https://github.com/lucaspar/uv-demo
Description-Content-Type: text/markdown

# `uv-demo` PyPI package

[![PyPI - Version](https://img.shields.io/pypi/v/uv-demo)](https://pypi.org/project/uv-demo/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/uv-demo)](https://pypi.org/project/uv-demo/)
[![Pepy Total Downloads](https://img.shields.io/pepy/dt/uv-demo)](https://pypi.org/project/uv-demo/)
[![Code Quality Check](https://github.com/lucaspar/uv-demo/actions/workflows/code-quality.yaml/badge.svg)](https://github.com/lucaspar/uv-demo/actions/workflows/code-quality.yaml)

A demo and template for a modern Python package managed by `uv`. Very useless as a
package.

Use this as a template for new projects, or as a reference for how to set up a Python
project with the following:

+ [x] `uv` as the Python package manager.
+ [x] [`pre-commit` hooks](./.pre-commit-config.yaml) for code formatting, linting, and
  quality checks.
+ [x] [GitHub Actions](./.github/workflows/) for testing and publishing.
+ [x] Multiple Python versions tested with `uv -p ${python-version} run pytest [...]`.
+ [x] `gh-act` for running GitHub Actions locally.
+ [x] [Justfile](./justfile) with common recipes.
+ [x] Documentation with `pdoc` + GitHub Pages.
+ [x] Deptry to highlight missing and unused dependencies.

## System Dependencies

+ `uv`
    + `curl -LsSf https://astral.sh/uv/install.sh | sh`
+ `just`
    + `sudo apt install just`
    + `sudo pacman -S just`
    + [More](https://github.com/casey/just#linux) installation methods.
+ For running GitHub Actions locally
    + [Docker](https://docs.docker.com/desktop/install/linux/)
    + `gh` (GitHub CLI)
        + `sudo pacman -S github-cli`
        + [Others](https://github.com/cli/cli/blob/trunk/docs/install_linux.md)
    + [`gh-act`](https://github.com/nektos/gh-act)
        + `gh extension install nektos/gh-act`

## Quick start

This will install all dependencies (`uv sync`) and run the entrypoint script:

```bash
uv run uv-demo
```

## `just` Recipes

```bash
# just --list
Available recipes:
    list                      # List available recipes
    clean                     # Clean up generated files

    [dev]
    install                   # Install pre-commit hooks and development project dependencies with uv
    upgrade                   # Upgrade all project and pre-commit dependencies respecting pyproject.toml constraints [alias: update]
    pre-commit                # Run pre-commit hooks on all files [alias: check]
    deptry                    # Run deptry to check for unused and missing dependencies

    [build]
    build                     # Build the package and run tests
    publish                   # Build and publish the package to PyPI

    [test]
    test *pytest_args         # Simple execution of tests with coverage
    test-lowest *pytest_args  # runs tests with the lowest compatible versions of dependencies, to check compatibility issues
    test-verbose *pytest_args # Run tests with coverage and increased output
    test-all                  # Run static checker and tests for all compatible python versions
    serve-coverage            # Serve the coverage report with a simple HTTP server

    [docs]
    docs                      # Generate and serve documentation
    docs-gen                  # Generate documentation using pdoc
    docs-serve                # Serve the docs with a simple HTTP server

    [ci]
    gact                      # Run the GitHub Actions workflow for all branches
    gact-pull-request         # Run the GitHub Actions workflow for pull requests [alias: gact-pr]
    gact-release              # Run the GitHub Actions workflow for release
```

## Integration with GitHub Actions

See the [Upload Python Package workflow file](.github/workflows/python-publish.yaml) for
this package.

### Running actions locally

You can use `act` to run GitHub Actions locally. Use cases:

1. While writing a workflow, to test the workflow locally before pushing to the
   repository.
2. Run the publishing workflow without setting secrets on GitHub.
3. Before opening a pull request, to check the workflow will pass.

Copy the example secrets file:

```bash
cp "config/secrets.env.example" "config/secrets.env"
```

Then edit the new file to add your secrets.

After that, run `just gact` to run the GitHub Actions workflow locally.
