Metadata-Version: 2.3
Name: uv-demo
Version: 0.2.4
Summary: Just a demo of the uv package manager for Python.
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
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.
License-File: LICENSE
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 :: Implementation :: CPython
Classifier: Topic :: Terminals
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: loguru>=0.7.2
Provides-Extra: tox-uv
Requires-Dist: tox>=4.23.2; extra == 'tox-uv'
Description-Content-Type: text/markdown

# `uv-demo` PyPI package

![PyPI - Version](https://img.shields.io/pypi/v/uv-demo)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/uv-demo)
![Pepy Total Downloads](https://img.shields.io/pepy/dt/uv-demo)
[![Action | Upload Python Package](https://github.com/lucaspar/uv-demo/actions/workflows/python-publish.yaml/badge.svg)](https://github.com/lucaspar/uv-demo/actions/workflows/python-publish.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] [`tox`](./tox.ini) for testing the three latest Python versions.
+ [x] [`pre-commit` hooks](./.pre-commit-config.yaml) for code formatting and linting.
+ [x] [GitHub Actions](./.github/workflows/) for testing and publishing.
+ [x] `gh-act` for running GitHub Actions locally.
+ [x] [Makefile](./makefile) with common targets.

## System Dependencies

+ `uv`
    + `curl -LsSf https://astral.sh/uv/install.sh | sh`
+ `make`
    + `sudo apt install make`
    + `sudo pacman -S make`
+ 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
```

## Make targets

```bash
make
# equivalent to make install test

make install
# runs uv sync

make test
# runs tests for supported python versions

make serve-coverage
# serves coverage report on localhost:8000

make gact
# runs GitHub Actions locally with gh-act
#
# >>> WARNING: if the secrets file has a valid API key,
#   this target will actually publish the package to PyPI.
#
# Install with:     gh extension install nektos/gh-act
# or see            https://github.com/nektos/act

make clean
# removes all venv, tox, cache, and generated files

make update
# updates uv and pre-commit hooks

make publish
# publishes the package to PyPI
```

## 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 and edit it with the required secrets:

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

Then run `make gact` to run the GitHub Actions workflow locally.
