# Package Publishing

This guide details the process for publishing the package to PyPI using `uv`.

## PyPI Configuration

Before publishing, you need to configure your authentication tokens.

1.  **TestPyPI** (for testing): [Register](https://test.pypi.org/account/register/) and [generate a token](https://test.pypi.org/manage/account/token/).
2.  **PyPI** (production): [Register](https://pypi.org/account/register/) and [generate a token](https://pypi.org/manage/account/token/).

Set the scope to "Entire account" for the first upload.

## Manual Publishing


### 1. Versioning and Tags
TODO: Review this section. This should be automated

Before building, ensure your package version and git tag are synchronized.

**The Logic:**
- **Package Version** (`pyproject.toml`): Defines what pip installs (e.g., `0.1.0`).
- **Git Tag**: Marks the specific commit in history that corresponds to that release (e.g., `v0.1.0`).

**Workflow:**
1.  **Update Version**: Use `uv version` to bump the version in `pyproject.toml`.
```shell
# Check current version
uv version

# Bump patch (0.1.0 -> 0.1.1)
uv version --bump patch

# Bump minor (0.1.0 -> 0.2.0)
uv version --bump minor
```
See [uv versioning docs](https://docs.astral.sh/uv/guides/package/#updating-your-version) for more details.

2.  **Commit and Tag**:
```shell
git commit -am "Bump version to $(uv version)"
git tag v$(uv version --short)
git push origin main --tags
```

### 2. Build the Package

Build the distribution archives (source and wheel).

```shell
# Clean build
rm -rf dist/

# Build the package
uv build --no-sources
```

> **Why `--no-sources`?**
> This flag ensures the package builds using standard PyPI dependencies rather than any local or git overrides defined in `tool.uv.sources`. This guarantees that what you publish is what users will actually get when they install from PyPI.

### 3. Publish

**To TestPyPI:**
```shell
# Export your TestPyPI Token
export UV_PUBLISH_TOKEN="pypi-YOUR-TESTPYPI-TOKEN"

# Publish
uv publish --publish-url https://test.pypi.org/legacy/

# Verify the package can be installed
uv run --with dot-metrics --no-project --index-url https://test.pypi.org/simple/ -- python -c "import dot_metrics; print(dot_metrics.__name__)"
```

**To Production PyPI:**
```shell
# Export your PyPI Token
export UV_PUBLISH_TOKEN="pypi-YOUR-PYPI-TOKEN"

# Publish
uv publish

# Verify the package can be installed
uv run --with dot-metrics --no-project --refresh-package dot-metrics -- python -c "import dot_metrics; print(dot_metrics.__name__)"
```

## Automated Publishing
TODO: To be implemented