Metadata-Version: 2.4
Name: wads
Version: 0.2.9
Summary: Tools for packaging and publishing to pypi for those who just do not want to deal with it
Project-URL: Homepage, https://github.com/i2mint/wads
Author: Thor Whalen
License: Apache Software License
License-File: LICENSE
Keywords: documentation,packaging,publishing
Requires-Python: >=3.10
Requires-Dist: argh
Requires-Dist: jinja2
Requires-Dist: packaging
Requires-Dist: pyyaml
Requires-Dist: tomli-w>=0.4.0
Requires-Dist: tomli>=1.0.0; python_version < '3.11'
Provides-Extra: all
Requires-Dist: build; extra == 'all'
Requires-Dist: epythet; extra == 'all'
Requires-Dist: requests; extra == 'all'
Requires-Dist: ruamel-yaml; extra == 'all'
Requires-Dist: tomlkit; extra == 'all'
Requires-Dist: wheel; extra == 'all'
Provides-Extra: create
Requires-Dist: build; extra == 'create'
Requires-Dist: requests; extra == 'create'
Requires-Dist: ruamel-yaml; extra == 'create'
Requires-Dist: tomlkit; extra == 'create'
Requires-Dist: wheel; extra == 'create'
Provides-Extra: docs
Requires-Dist: epythet; extra == 'docs'
Provides-Extra: skills
Requires-Dist: skill; extra == 'skills'
Provides-Extra: test
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: pytest>=7.0; extra == 'test'
Description-Content-Type: text/markdown

# wads

Modern Python project packaging and CI/CD tools for developers who want to focus on code, not configuration.

[![PyPI version](https://img.shields.io/pypi/v/wads.svg)](https://pypi.org/project/wads/)
[![Python versions](https://img.shields.io/pypi/pyversions/wads.svg)](https://pypi.org/project/wads/)

## What is Wads?

Wads helps you:
- **Create new Python projects** with modern tooling (pyproject.toml, GitHub Actions)
- **Manage CI/CD workflows** with configuration-driven GitHub Actions
- **Handle system dependencies** declaratively in pyproject.toml
- **Migrate legacy projects** from setup.cfg to modern formats
- **Debug CI failures** with automated diagnostics

## Installation

```bash
pip install wads          # light core: config reading + templating engine
pip install wads[create]  # full project-creation / publishing toolchain
pip install wads[all]     # create + docs
```

`wads` ships a **light core** (just enough to read `[tool.wads.ci]` /
`package.json` config and run the templating engine — handy in CI) plus a
heavier `create` extra (`requests`, `build`, `wheel`, `ruamel.yaml`) for
scaffolding and publishing. Use `wads[create]` (or `wads[all]`) when running
`populate`/`pack` to create or publish projects.

## Quick Start

### Create a New Project

```bash
populate my-project --root-url https://github.com/user/my-project
cd my-project
```

This creates a complete project structure with:
- `pyproject.toml` (modern build configuration)
- `README.md`, `LICENSE`, `.gitignore`
- Package directory with `__init__.py`
- GitHub Actions CI/CD workflow (optional)

### Add a frontend component for JS/TS parts (optional)

Python projects often ship a frontend component (a widget, a browser UI, a
TypeScript library). `populate --frontend <profile>` adds a parametrized
**NPM CI** alongside the Python one, following the same
"config-file-driven, fixed-workflow" model. Pick one or more **profiles**:

| Profile | Adds | Subdir | CI |
|---|---|---|---|
| `js` | `package.json` (npm) | `js/` | single-package `npm-ci.yml` |
| `ts` | `package.json` + `tsconfig.json` + `src/index.ts` (tsup build, vitest) | `ts/` | single-package `npm-ci.yml` |
| `ts-monorepo` | pnpm workspace root + `turbo.json` + an example `packages/core` | `ts/` | matrixed `npm-ci-monorepo.yml` |

```bash
# A single TypeScript component:
populate my-project --root-url https://github.com/user/my-project --frontend ts

# Several components at once — each in its own subdir, no workflow collision:
populate my-project --root-url https://github.com/user/my-project --frontend js,ts
```

`--with-npm` is kept as a back-compat alias for `--frontend js`.

Each component gets:
- a `package.json` with a namespaced `"wads"` config block (`wads.ci.*`)
  controlling node versions, lint/test/build commands, and publishing —
  analogous to `[tool.wads.ci]` in `pyproject.toml`;
- a path-filtered `.github/workflows/npm-ci[-<subdir>].yml` stub calling wads's
  reusable NPM workflow (the `js` component keeps the bare `npm-ci.yml`; every
  other component gets `npm-ci-<subdir>.yml`, so multiple components never
  collide).

**Validation runs on every push/PR; publishing is opt-in.** It publishes only
when `wads.ci.publish.enabled` is `true` **and** the commit message contains
the marker **`[publish-npm]`** (deliberately distinct from the Python side).
Publishing uses npm OIDC trusted publishing + provenance by default (no
long-lived token). For a single component, customize the subdirectory and
package name with `--npm-subdir` / `--npm-package-name`.

**Package manager: npm or pnpm.** The single-package reusable workflow drives
**npm** by default and **pnpm** when selected — either explicitly via
`wads.ci.packageManager` (or `populate --npm-package-manager pnpm`) or
auto-detected from a `pnpm-lock.yaml` in the package directory. pnpm consumers
should declare a `"packageManager": "pnpm@x.y.z"` field in their `package.json`
(pnpm's own convention); the CI reads the pnpm version from there. Existing npm
consumers are unaffected (no `pnpm-lock.yaml` → npm). The `ts-monorepo` profile
is pnpm-based by design.

The profile set is extensible: register your own with
`wads.profiles.register_frontend_profile(...)`.

### Configure CI in pyproject.toml

Edit your `pyproject.toml` to configure CI behavior:

```toml
[tool.wads.ci.testing]
python_versions = ["3.10", "3.12"]
pytest_args = ["-v", "--tb=short"]
coverage_enabled = true
test_on_windows = true

[tool.wads.ci.quality.ruff]
enabled = true

[tool.wads.ci.build]
sdist = true
wheel = true
```

The default `ci.yml` is a small stub that calls wads's reusable workflow
(`i2mint/wads/.github/workflows/uv-ci.yml@master`); all behavior is driven by
`[tool.wads.ci.*]` above. Publishing to PyPI happens automatically on your
repo's **default branch** — but only when the Linux test matrix passes.

### Configure Secrets (CI environment variables)

If your tests need API keys or other secrets, declare them once and let wads
wire up both the GitHub Actions transport and the job environment:

```bash
wads-secrets add OPENAI_API_KEY            # env var == GitHub secret name
wads-secrets add HF_TOKEN HF_WRITE_TOKEN    # env var <- differently-named secret
wads-secrets add DATABASE_URL --kind required   # fail CI if the secret is unset
wads-secrets list                           # show what's configured
```

`wads-secrets add` (a) records the variable in `[tool.wads.ci.env]`, (b) adds
the pass-through line to your `ci.yml`, and (c) runs `gh secret set` if `gh` is
installed (value taken from `$VAR_NAME` or `--value`). Under the hood there are
two layers: a **transport superset** (the secret names the reusable workflow can
receive, in `wads.ci_secrets.DEFAULT_CI_SECRETS`) and an **env policy**
(`[tool.wads.ci.env]` — `required_envvars` / `test_envvars` / `extra_envvars` /
`defaults` / `secret_aliases`) that decides which become job env vars. A
`required` secret that's missing fails the build; an undeclared secret is never
written to the environment. To use a name outside the superset, open a one-line
PR to wads or use the inline-workflow escape valve.

### Declare System Dependencies

Need ffmpeg, ODBC drivers, or other system packages in CI? Declare them in `pyproject.toml`:

```toml
[tool.wads.ops.ffmpeg]
description = "Multimedia framework for video/audio processing"
url = "https://ffmpeg.org/"

check.linux = "which ffmpeg"
check.macos = "which ffmpeg"

install.linux = "sudo apt-get install -y ffmpeg"
install.macos = "brew install ffmpeg"
install.windows = "choco install ffmpeg -y"

note = "Required for audio processing features"
```

The `install-system-deps` action in your CI workflow will automatically install these.

## Core Features

### 1. Project Setup (`populate`)

Create new Python projects with modern best practices:

```bash
# Basic usage
populate my-project

# With custom settings
populate my-project \
  --root-url https://github.com/myorg/my-project \
  --description "My awesome project" \
  --author "Your Name" \
  --license apache
```

**Options:**
- `--root-url`: GitHub repository URL
- `--description`: Project description
- `--author`: Author name
- `--license`: License type (mit, apache, bsd, etc.)
- `--keywords`: Comma-separated keywords
- `--overwrite`: Files to overwrite if they exist

**Tip:** Configure defaults in `wads_configs.json` or use `WADS_CONFIGS_FILE` environment variable to point to your custom config.

### 2. Package and Publish (`pack`)

Build and publish packages to PyPI:

```bash
# See current configuration
pack current-configs

# Increment version and publish
pack go .

# Or step-by-step
pack increment-configs-version
pack run-setup
pack twine-upload-dist
```

### 3. Migration Tools (`wads-migrate`)

Migrate legacy projects to modern format:

```bash
# Migrate setup.cfg to pyproject.toml
wads-migrate setup-to-pyproject setup.cfg -o pyproject.toml

# Migrate old CI workflow to new format
wads-migrate ci-old-to-new .github/workflows/old-ci.yml -o .github/workflows/ci.yml
```

**Python API:**

```python
from wads.migration import migrate_setuptools_to_hatching, migrate_github_ci_old_to_new

# From setup.cfg file
pyproject_content = migrate_setuptools_to_hatching('setup.cfg')

# From setup.cfg dict
config = {'metadata': {'name': 'myproject', 'version': '1.0.0'}}
pyproject_content = migrate_setuptools_to_hatching(config)

# Migrate CI workflow
new_ci = migrate_github_ci_old_to_new('.github/workflows/ci.yml')
```

### 4. CI Debugging (`wads-ci-debug`)

Diagnose and fix GitHub Actions CI failures:

```bash
# Analyze latest failure
wads-ci-debug myorg/myrepo

# Analyze specific run
wads-ci-debug myorg/myrepo --run-id 1234567890

# Generate fix instructions
wads-ci-debug myorg/myrepo --fix --local-repo .
```

The tool will:
- Fetch CI logs from GitHub
- Parse test failures and errors
- Identify root causes
- Generate fix instructions with file locations and suggested changes

## CI Configuration Reference

Wads uses `pyproject.toml` as a single source of truth for CI configuration. Here's what you can configure:

### Install Extras

By default CI installs only your package's core dependencies. If your test suite
needs an extra (e.g. a heavier `create`/`dev` group), declare it so CI installs
`.[extras]`:

```toml
[tool.wads.ci.install]
extras = "dev"          # or a list, e.g. ["dev", "test"]
```

### Python Versions and Testing

```toml
[tool.wads.ci.testing]
python_versions = ["3.10", "3.11", "3.12"]  # Test matrix
pytest_args = ["-v", "--tb=short"]           # Pytest arguments
coverage_enabled = true                      # Enable coverage
coverage_threshold = 80                      # Minimum coverage %
exclude_paths = ["examples", "scrap"]        # Paths to exclude
test_on_windows = true                       # Run Windows tests
```

### Code Quality Tools

```toml
[tool.wads.ci.quality.ruff]
enabled = true
# line_length = 88

[tool.wads.ci.quality.mypy]
enabled = false
# strict = true
```

### Custom Commands

```toml
[tool.wads.ci.commands]
pre_test = [
    "python scripts/setup_test_data.py",
]
post_test = [
    "python scripts/cleanup.py",
]
```

### Build and Publish

```toml
[tool.wads.ci.build]
sdist = true
wheel = true

[tool.wads.ci.publish]
enabled = true  # Publish to PyPI on main/master
```

## System Dependencies

System dependencies are declared using the `[tool.wads.ops.*]` format and automatically installed in CI via the `install-system-deps` action.

**Format:**

```toml
[tool.wads.ops.{package-name}]
description = "Description of the package"
url = "https://package-homepage.com"

# Check if already installed (exit code 0 = present)
check.linux = "which package-name"
check.macos = "brew list package-name"
check.windows = "where package-name"

# Install commands (string or list of strings)
install.linux = "sudo apt-get install -y package-name"
install.macos = "brew install package-name"
install.windows = "choco install package-name -y"

# Optional metadata
note = "Additional installation notes"
alternatives = ["alternative-package"]
```

**Real-world example (ODBC drivers):**

```toml
[tool.wads.ops.unixodbc]
description = "ODBC driver interface for database connectivity"
url = "https://www.unixodbc.org/"

check.linux = "dpkg -s unixodbc || rpm -q unixODBC"
check.macos = "brew list unixodbc"

install.linux = [
    "sudo apt-get update",
    "sudo apt-get install -y unixodbc unixodbc-dev"
]
install.macos = "brew install unixodbc"

note = "On Alpine: apk add unixodbc unixodbc-dev"
alternatives = ["iodbc"]
```

See [docs/SYSTEM_DEPENDENCIES.md](docs/SYSTEM_DEPENDENCIES.md) for comprehensive examples.

## Claude Code Skills

Wads ships with [Claude Code](https://docs.anthropic.com/en/docs/claude-code) skills for AI-assisted workflows. Install them globally so they're available in every project:

```bash
wads-install-skills
```

This symlinks skills to `~/.claude/skills/`, so they stay in sync when wads is updated:

| Command | Description |
|---------|-------------|
| `/setup-py-project` | AI-guided Python project creation: name suggestions, PyPI/GitHub availability checking, repo creation, file population |
| `/wads-migrate` | Migrate projects to modern wads setup (pyproject.toml + uv CI) |

**Example:**
```
/setup-py-project "a tool for audio signal processing"
```

To list available skills without installing: `wads-install-skills --list`
To update existing skills: `wads-install-skills --force`

## Documentation

- **[System Dependencies Guide](misc/docs/SYSTEM_DEPENDENCIES.md)** - `[tool.wads.ops.*]` format and examples
- **[Migration Guide](misc/docs/MIGRATION.md)** - Migrate from setup.cfg to pyproject.toml
- **[Utilities Reference](misc/docs/UTILITIES.md)** - CLI tools (`wads-ci-debug`, `wads-migrate`)
- **[CLAUDE.md](CLAUDE.md)** - AI agent guide for working with this project

## Troubleshooting

### Version Tag Misalignment

If PyPI publishing fails with "appears to already exist":

```
WARNING  Skipping mypackage-0.1.4-py3-none-any.whl because it appears to already exist
```

This means your git tags are misaligned with the version in `pyproject.toml`.

**Fix:**

1. Check the current PyPI version: https://pypi.org/project/your-package/
2. Update `version` in `pyproject.toml` to a higher number
3. Create and push git tag:
   ```bash
   git tag 0.1.5
   git push origin 0.1.5
   ```

### CI Failures

Use `wads-ci-debug` to analyze failures:

```bash
wads-ci-debug myorg/myrepo --fix
```

Common issues:
- Missing system dependencies → Add to `[tool.wads.ops.*]`
- Python version incompatibilities → Check `python_versions` in `[tool.wads.ci.testing]`
- Test failures → Review generated fix instructions

## Development

### Running Tests

```bash
pytest wads/tests/
```

### Building Documentation

```bash
pip install -e ".[docs]"
epythet build
```

## License

Apache Software License 2.0

## Links

- **PyPI:** https://pypi.org/project/wads/
- **GitHub:** https://github.com/i2mint/wads
- **Issues:** https://github.com/i2mint/wads/issues
