wex_addon_package

Version: 7.6.7

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
• Quickstart
• Tests
• Architecture
• Integration in the Suite
• Dependencies
• Versioning & Compatibility Policy
• License
• About us
• Known Limitations & Roadmap
• Status & Compatibility
• Useful Links
• Migration Notes

Installation

pip install wexample-wex-addon-package

Requires Python >=3.10.

Quickstart

Install the package:

pip install wexample-wex-addon-package

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

from wexample_wex_addon_package.package_addon_manager import PackageAddonManager

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

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:

wex package version bump

To publish the built distribution to PyPI:

wex package version publish

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

wex package version release

To publish every package in a suite in dependency order:

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:

.venv/bin/python -m pip install pytest pytest-cov

Basic Usage

Run all tests with coverage:

.venv/bin/python -m pytest --cov --cov-report=html

Common Commands

# 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:

.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:

@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 for the complete package ecosystem.

Dependencies

• wexample-wex-addon-app: >=31.1.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 file for details.

Free to use in both personal and commercial projects.

About us

Wexample 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 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
• 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

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.