Metadata-Version: 2.1
Name: wexample-wex-addon-package
Version: 7.6.4
Summary: Extends wex with commands to bump, publish to PyPI, and coordinate releases across a Python package suite
Author-Email: weeger <contact@wexample.com>
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Requires-Dist: wexample-wex-addon-app>=30.0.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Description-Content-Type: text/markdown

# wex_addon_package

Version: 7.6.4

`wex-addon-package` extends wex with commands that cover the full publication lifecycle of Python packages: bumping versions when commits are untagged, publishing builds to PyPI, committing and pushing changes, and running all of those steps in dependency order across an entire package suite. It is aimed at maintainers of multi-package Python projects who use wex as their project management layer and need a single, consistent path from a local change to a tagged, registry-published release.

## Table of Contents

- [Installation](#installation)
- [Quickstart](#quickstart)
- [Tests](#tests)
- [Architecture](#architecture)
- [Integration in the Suite](#integration-in-the-suite)
- [Dependencies](#dependencies)
- [Versioning & Compatibility Policy](#versioning--compatibility-policy)
- [License](#license)
- [About us](#about-us)
- [Known Limitations & Roadmap](#known-limitations--roadmap)
- [Status & Compatibility](#status--compatibility)
- [Useful Links](#useful-links)
- [Migration Notes](#migration-notes)

## Installation

```bash
pip install wexample-wex-addon-package
```

Requires Python >=3.10.

## Quickstart

Install the package:

```bash
pip install wexample-wex-addon-package
```

The public entry point is `PackageAddonManager`, defined in src/wexample_wex_addon_package/package_addon_manager.py:

```python
from wexample_wex_addon_package.package_addon_manager import PackageAddonManager
```

Pass it to the kernel's `setup()` call to register the package addon:

```python
from wexample_wex_core.common.kernel import Kernel

kernel = Kernel()
kernel.setup(addons=[PackageAddonManager])
```

After `setup()` returns, the kernel holds a `package` addon entry (the name is derived from the class by stripping the `AddonManager` suffix). The addon registers commands in the `package` namespace — for example, bump the current package's version when HEAD carries unreleased commits:

```bash
wex package version bump
```

To publish the built distribution to PyPI:

```bash
wex package version publish
```

To run bump, commit, push, and publish in one step:

```bash
wex package version release
```

To publish every package in a suite in dependency order:

```bash
wex package suite publish
```

## Tests

This project uses `pytest` for testing and `pytest-cov` for code coverage analysis.

### Installation

First, install the required testing dependencies:
```bash
.venv/bin/python -m pip install pytest pytest-cov
```

### Basic Usage

Run all tests with coverage:
```bash
.venv/bin/python -m pytest --cov --cov-report=html
```

### Common Commands
```bash
# Run tests with coverage for a specific module
.venv/bin/python -m pytest --cov=your_module

# Show which lines are not covered
.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing

# Generate an HTML coverage report
.venv/bin/python -m pytest --cov=your_module --cov-report=html

# Combine terminal and HTML reports
.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing --cov-report=html

# Run specific test file with coverage
.venv/bin/python -m pytest tests/test_file.py --cov=your_module --cov-report=term-missing
```

### Viewing HTML Reports

After generating an HTML report, open `htmlcov/index.html` in your browser to view detailed line-by-line coverage information.

### Coverage Threshold

To enforce a minimum coverage percentage:
```bash
.venv/bin/python -m pytest --cov=your_module --cov-fail-under=80
```

This will cause the test suite to fail if coverage drops below 80%.

## Architecture

The addon is a single Python package (`wexample_wex_addon_package`) with three layers: an entry point that registers the addon with the wex kernel, a command tree that wex discovers and exposes on the CLI, and a constants module that supplies the domain tags every command carries.

### Entry point

src/wexample_wex_addon_package/package_addon_manager.py defines `PackageAddonManager`, which extends `AppAddonManager` from `wexample_wex_addon_app`. It is decorated with `@base_class` and implements one method:

```python
@classmethod
def get_package_module(cls) -> Any:
    import wexample_wex_addon_package
    return wexample_wex_addon_package
```

This is the only object a host kernel needs: passing it to `kernel.setup(addons=[PackageAddonManager])` tells wex where to look for commands. The kernel derives the addon namespace (`package`) from the class name by stripping the `AddonManager` suffix.

### Command tree

Commands live under `src/wexample_wex_addon_package/commands/` in four sub-namespaces. Each command is a plain function whose name encodes its CLI path with double-underscore separators (`package__version__bump` → `wex package version bump`). The `@command` decorator registers it with the kernel; `@option` and `@middleware` decorators wrap it before registration.

**`dependency/`**

src/wexample_wex_addon_package/commands/dependency/check.py — validates that internal dependency version declarations are consistent across all packages in the suite. Uses `PackageSuiteMiddleware`, which injects a `FrameworkPackageSuiteWorkdir`.

**`version/`**

Per-package lifecycle steps, each operating on the package at the current working directory (or every package in the suite when `--all-packages` is supplied via `SuiteOrEachPackageMiddleware`):

- src/wexample_wex_addon_package/commands/version/bump.py — increments the version number when HEAD is not yet tagged; accepts `--force` and `--yes`.
- src/wexample_wex_addon_package/commands/version/publish.py — builds and uploads to PyPI via `app_workdir.publish()`.
- src/wexample_wex_addon_package/commands/version/push.py — commits local changes and pushes to the main branch of the deployment remote.
- src/wexample_wex_addon_package/commands/version/release.py — runs bump, push, and publish in sequence via `app_workdir.release()`.

**`suite/`**

Suite-wide operations that iterate over every package in dependency order. All four use `PackageSuiteMiddleware` and receive a `FrameworkPackageSuiteWorkdir`:

- src/wexample_wex_addon_package/commands/suite/packages.py — lists every package with its path and version; returns a `DictResponse`.
- src/wexample_wex_addon_package/commands/suite/status.py — shows each package's bump readiness, test count, and coverage in a table; rows are collected in parallel via `parallel_map`.
- src/wexample_wex_addon_package/commands/suite/run.py — dispatches an arbitrary wex command (e.g. `app::info/show`) to every package via `packages_execute_manager`.
- src/wexample_wex_addon_package/commands/suite/shell.py — runs an arbitrary shell command in every package directory via `packages_execute_shell`.
- src/wexample_wex_addon_package/commands/suite/publish.py — the full suite release pipeline: shows the status table, validates internal dependencies, runs the full test suite once, then calls `package.release()` on each package in order. Requires `@as_sudo()` because per-package subprocesses run detached from the TTY and must inherit root rather than prompt for it.

**`info/`**

src/wexample_wex_addon_package/commands/info/show.py — returns a `PropertiesResponse` confirming the addon name and the resolved `app_workdir` path. Uses `AppMiddleware` (injects `ManagedWorkdir`) and serves as a smoke test for workdir injection.

### Constants

src/wexample_wex_addon_package/const/tags.py defines `DomainTag` with three values — `domain:introspection`, `domain:package`, `domain:release` — that every command in this addon attaches to its `tags` list alongside the standard `EffectTag`, `AudienceTag`, and `ScopeTag` values from `wexample_cli`.

### Call path

When the user runs `wex package version bump`:

1. The kernel resolves `package` to the addon registered by `PackageAddonManager`.
2. It locates the function `package__version__bump` in the `version/` sub-namespace.
3. The decorator chain fires: `@command` supplies metadata; `@middleware(SuiteOrEachPackageMiddleware)` resolves the target directory (current package or all packages) and injects the `app_workdir` argument as a `RepoWorkdir`; `@option` decorators bind `--force` and `--yes` to their typed parameters.
4. The function body calls `app_workdir.bump(interactive=not yes, force=force)` — the workdir object owns all filesystem and git logic; the command function only decides which workdir method to call and how to report the result.

Suite commands follow the same chain, but `PackageSuiteMiddleware` widens the scope: it injects a `FrameworkPackageSuiteWorkdir` that exposes the full ordered list of packages, and the command iterates over them (sequentially or in parallel depending on the operation).

## Integration in the Suite

This package is part of the Wexample Suite — a collection of high-quality, modular tools designed to work seamlessly together across multiple languages and environments.

### Related Packages

The suite includes packages for configuration management, file handling, prompts, and more. Each package can be used independently or as part of the integrated suite.

Visit the [Wexample Suite documentation](https://docs.wexample.com) for the complete package ecosystem.

## Dependencies

- wexample-wex-addon-app: >=30.0.0

## Versioning & Compatibility Policy

Wexample packages follow **Semantic Versioning** (SemVer):

- **MAJOR**: Breaking changes
- **MINOR**: New features, backward compatible
- **PATCH**: Bug fixes, backward compatible

We maintain backward compatibility within major versions and provide clear migration guides for breaking changes.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

Free to use in both personal and commercial projects.

## About us

[Wexample](https://wexample.com) stands as a cornerstone of the digital ecosystem — a collective of seasoned engineers, researchers, and creators driven by a relentless pursuit of technological excellence. More than a media platform, it has grown into a vibrant community where innovation meets craftsmanship, and where every line of code reflects a commitment to clarity, durability, and shared intelligence.

This packages suite embodies this spirit. Trusted by professionals and enthusiasts alike, it delivers a consistent, high-quality foundation for modern development — open, elegant, and battle-tested. Its reputation is built on years of collaboration, refinement, and rigorous attention to detail, making it a natural choice for those who demand both robustness and beauty in their tools.

Wexample cultivates a culture of mastery. Each package, each contribution carries the mark of a community that values precision, ethics, and innovation — a community proud to shape the future of digital craftsmanship.

## Known Limitations & Roadmap

Current limitations and planned features are tracked in the GitHub issues.

See the [project roadmap](https://github.com/wexample/python-wex_addon_package/issues) for upcoming features and improvements.

## Status & Compatibility

**Maturity**: Production-ready

**Python Support**: >=3.10

**OS Support**: Linux, macOS, Windows

**Status**: Actively maintained

## Useful Links

- **Homepage**: https://github.com/wexample/python-wex-addon-package
- **Documentation**: [docs.wexample.com](https://docs.wexample.com)
- **Issue Tracker**: https://github.com/wexample/python-wex-addon-package/issues
- **Discussions**: https://github.com/wexample/python-wex-addon-package/discussions
- **PyPI**: [pypi.org/project/wexample-wex-addon-package](https://pypi.org/project/wexample-wex-addon-package/)

## Migration Notes

When upgrading between major versions, refer to the migration guides in the documentation.

Breaking changes are clearly documented with upgrade paths and examples.
