wexample-wex-addon-dev-python 15.2.1__py3-none-any.whl → 15.3.1__py3-none-any.whl

wexample_wex_addon_dev_python/common/pypi_registry_gateway.py

@@ -39,12 +39,22 @@ class PypiRegistryGateway(AbstractGateway):
     def has_version(self, package: str, version: str) -> bool:
         """Return True iff `package==version` is published on this index.
 
-        Uses the PEP 503 Simple index and matches the version string against
-        the HTML body. Returns False on 404 (unknown package, or version not
-        yet propagated through the registry's CDN).
+        Uses the Simple index and matches the version string against its
+        body. Returns False on 404 (unknown package, or version not yet
+        propagated through the registry's CDN).
+
+        Asked for exactly as pip asks for it: PyPI's CDN caches each
+        representation of the page apart, and they do not refresh together.
+        The gzipped HTML one stayed without a release for over ten minutes
+        after pip's JSON one listed it, so a check reading the former waited
+        on a version pip could already install.
         """
         response = self.make_request(
             endpoint=f"simple/{package}/",
+            headers={
+                "Accept": "application/vnd.pypi.simple.v1+json, "
+                "application/vnd.pypi.simple.v1+html; q=0.1, text/html; q=0.01",
+            },
             expected_status_codes=_HAS_VERSION_STATUS_CODES,
             fatal_if_unexpected=False,
             quiet=True,

wexample_wex_addon_dev_python/resources/package_gitlab_ci.yml

@@ -0,0 +1,4 @@
+include:
+  - remote: 'https://gitlab.wexample.com/wexample-public/ci-cd/-/raw/main/.gitlab-ci.type.python.package.yml'
+variables:
+  MAIN_BRANCH_NAME: main

wexample_wex_addon_dev_python/workdir/python_package_workdir.py

@@ -58,6 +58,18 @@ class PythonPackageWorkdir(PythonWorkdir):
                 "Install: pipx install pdm — then run: wex core::env/configure"
             )
 
+    def get_gitlab_registry_url(self) -> str | None:
+        """The GitLab PyPI registry of the group, when the suite publishes there.
+
+        `python.gitlab_registry.url`, the group's endpoint without `/simple`:
+        `https://gitlab.example.com/api/v4/groups/<group>/-/packages/pypi`.
+        Installs read its `/simple` index; each package uploads to its own
+        project's registry, which the group one gathers.
+        """
+        return self.search_app_or_suite_runtime_config(
+            "python.gitlab_registry.url", default=None
+        ).get_str_or_none()
+
     def get_required_knowledge_pages(self) -> dict[str, str]:
         return {
             **super().get_required_knowledge_pages(),
@@ -77,22 +89,28 @@ class PythonPackageWorkdir(PythonWorkdir):
         raw_value = super().prepare_value(raw_value=raw_value)
         children = raw_value.get("children")
 
-        # Add .gitlab-ci.yml for private GitLab registry packages.
-        # Both callbacks are evaluated after configure() completes, so base_name
-        # and runtime config are fully available at that point.
+        # Every package is tested by GitLab at each push, the way a consumer
+        # installs it: the file only includes the job, which lives in the ci-cd
+        # repository. A package published to the private GitLab registry gets
+        # the job publishing it on a tag instead, and no tests: the base
+        # template's workflow runs no tag pipeline. Created when absent, never
+        # rewritten. The callback is evaluated after configure() completes, so
+        # the runtime config is available at that point.
         children.append(
             {
                 "name": ".gitlab-ci.yml",
                 "type": DiskItemType.FILE,
-                "should_exist": lambda _target, _self=self: bool(
-                    _self.search_app_or_suite_runtime_config(
-                        "pdm.repository.url", default=None
-                    ).get_str_or_none()
-                ),
-                "default_content": lambda _: file_read(
+                "should_exist": True,
+                "default_content": lambda _, _self=self: file_read(
                     module_get_path(wexample_wex_addon_dev_python)
                     / "resources"
-                    / "package_publish_gitlab.yml"
+                    / (
+                        "package_publish_gitlab.yml"
+                        if _self.search_app_or_suite_runtime_config(
+                            "pdm.repository.url", default=None
+                        ).get_str_or_none()
+                        else "package_gitlab_ci.yml"
+                    )
                 ),
             }
         )
@@ -414,8 +432,9 @@ class PythonPackageWorkdir(PythonWorkdir):
         self.push_to_deployment_remote(branch_name=GIT_BRANCH_MAIN)
 
     def _publish(self, force: bool = False) -> None:
-        from wexample_filestate_python.common.pipy_gateway import PipyGateway
-        from wexample_helpers.helper.shell import shell_run
+        from wexample_helpers.exception.shell_command_failed_exception import (
+            ShellCommandFailedException,
+        )
         from wexample_helpers_git.helper.git import (
             git_push_tag,
             git_tag_annotated,
@@ -443,10 +462,75 @@ class PythonPackageWorkdir(PythonWorkdir):
             git_push_tag(tag, cwd=cwd, remote=remote, inherit_stdio=True)
             return
 
-        # TODO: align public PyPI packages with the private registry approach — publish
-        #       via a GitLab CI pipeline triggered by a git tag rather than running
-        #       `pdm publish` locally.
-        # PyPI public: publish locally
+        # Our own registry first, where the release counts: what installs read
+        # (wex, the apps) and what the publication waits for. PyPI then only
+        # mirrors it, and a refusal there no longer stops the suite.
+        if self.get_gitlab_registry_url():
+            self._publish_to_gitlab_registry(force=force)
+            try:
+                self._publish_to_pypi(force=force)
+            except ShellCommandFailedException as exception:
+                self.warning(
+                    f"PyPI refused {package_name} {version}, published on the GitLab "
+                    f"registry all the same: {exception}"
+                )
+            return
+
+        self._publish_to_pypi(force=force)
+
+    def _publish_to_gitlab_registry(self, force: bool = False) -> None:
+        import re
+        from urllib.parse import quote
+
+        from wexample_helpers.helper.shell import shell_run
+        from wexample_helpers_git.helper.git import git_get_remote_url
+
+        from wexample_wex_addon_dev_python.common.pypi_registry_gateway import (
+            PypiRegistryGateway,
+        )
+
+        package_name = self.get_package_name()
+        version = self.get_setup_version()
+        registry_url = self.get_gitlab_registry_url()
+
+        index = PypiRegistryGateway(base_url=registry_url, io=self.io, timeout=10)
+        if index.has_version(package_name, version) and not force:
+            self.log(f"{package_name} {version} is already on the GitLab registry.")
+            return
+
+        # The project is the package's origin: ssh://git@host:port/<group>/<name>.git
+        project_path = re.sub(
+            r"^(ssh://[^/]+/|git@[^:]+:|https?://[^/]+/)",
+            "",
+            git_get_remote_url(cwd=self.get_path()),
+        ).removesuffix(".git")
+        project = quote(project_path, safe="")
+        api_url = registry_url.split("/groups/", 1)[0]
+
+        self.subtitle("Publishing to the GitLab registry")
+        shell_run(
+            [
+                "pdm",
+                "publish",
+                "--repository",
+                f"{api_url}/projects/{project}/packages/pypi",
+                # GitLab authenticates the token alone; the name is required, not read.
+                "--username",
+                "__token__",
+                "--password",
+                self.get_env_parameter_or_suite_fallback("GITLAB_API_TOKEN"),
+            ],
+            inherit_stdio=True,
+            cwd=self.get_path(),
+        )
+
+    def _publish_to_pypi(self, force: bool = False) -> None:
+        from wexample_filestate_python.common.pipy_gateway import PipyGateway
+        from wexample_helpers.helper.shell import shell_run
+
+        package_name = self.get_package_name()
+        version = self.get_setup_version()
+
         client = PipyGateway(parent_io_handler=self)
         if client.package_release_exists(package_name=package_name, version=version):
             self.warning(
@@ -487,8 +571,12 @@ class PythonPackageWorkdir(PythonWorkdir):
             PypiRegistryGateway,
         )
 
+        # The GitLab registry, when the suite publishes there, is what installs
+        # read: it serves a version as soon as it is uploaded, where PyPI's CDN
+        # can lag for many minutes.
         repository_url = (
-            self.search_app_or_suite_runtime_config(
+            self.get_gitlab_registry_url()
+            or self.search_app_or_suite_runtime_config(
                 "pdm.repository.url", default=None
             ).get_str_or_none()
             or "https://pypi.org"

wexample_wex_addon_dev_python/workdir/python_workdir.py

@@ -476,6 +476,23 @@ class PythonWorkdir(
 
         pyproject_path = self.get_path() / "pyproject.toml"
 
+        # The suite's GitLab registry beside PyPI: the wexample packages are
+        # there first. Written into requirements.txt, so `pip install -r` reads
+        # it too. Best match across both, as pip does: a package published
+        # before the registry existed is only on PyPI.
+        index_arguments: list[str] = []
+        registry_url = self.search_app_or_suite_runtime_config(
+            "python.gitlab_registry.url", default=None
+        ).get_str_or_none()
+        if registry_url:
+            index_arguments = [
+                "--extra-index-url",
+                f"{registry_url}/simple",
+                "--index-strategy",
+                "unsafe-best-match",
+                "--emit-index-url",
+            ]
+
         def _run_uv_compile() -> None:
             result = subprocess.run(
                 [
@@ -494,6 +511,7 @@ class PythonWorkdir(
                     # long as they satisfy constraints — causing stale
                     # transitives even after their direct dependents bumped.
                     "--upgrade",
+                    *index_arguments,
                 ],
                 capture_output=True,
                 text=True,

wexample_wex_addon_dev_python-15.3.1.dist-info/METADATA

@@ -0,0 +1,121 @@
+Metadata-Version: 2.1
+Name: wexample-wex-addon-dev-python
+Version: 15.3.1
+Summary: Extends wex with commands to format, lint, and rename Python symbols, plus workdir types for Python packages and suites
+Author-Email: weeger <contact@wexample.com>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Project-URL: homepage, https://github.com/wexample/python-wex-dev-python
+Requires-Python: >=3.10
+Requires-Dist: attrs>=23.1.0
+Requires-Dist: black
+Requires-Dist: cattrs>=23.1.0
+Requires-Dist: griffe>=2.0.2
+Requires-Dist: isort
+Requires-Dist: networkx
+Requires-Dist: pylint
+Requires-Dist: pyright
+Requires-Dist: wexample-api>=6.8.0
+Requires-Dist: wexample-filestate-python>=9.1.4
+Requires-Dist: wexample-wex-addon-ai>=19.0.2
+Requires-Dist: wexample-wex-addon-app>=34.2.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Description-Content-Type: text/markdown
+
+# wex_addon_dev_python
+
+Version: 15.3.1
+
+Extends wex with commands to format, lint, and rename Python symbols, plus workdir types for Python packages and suites
+
+## Table of Contents
+
+- [Install](#install)
+- [Tests](#tests)
+- [Roadmap](#roadmap)
+- [Status Compatibility](#status-compatibility)
+- [Useful Links](#useful-links)
+
+## Installation
+
+```bash
+pip install wexample-wex-addon-dev-python
+```
+
+Requires Python >=3.10.
+
+## 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%.
+
+## 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_dev_python/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-dev-python
+- **Issue Tracker**: https://github.com/wexample/python-wex-addon-dev-python/issues
+- **Discussions**: https://github.com/wexample/python-wex-addon-dev-python/discussions
+- **PyPI**: [pypi.org/project/wexample-wex-addon-dev-python](https://pypi.org/project/wexample-wex-addon-dev-python/)

{wexample_wex_addon_dev_python-15.2.1.dist-info → wexample_wex_addon_dev_python-15.3.1.dist-info}/RECORD

@@ -1,8 +1,7 @@
-wexample_wex_addon_dev_python-15.2.1.dist-info/METADATA,sha256=PjUNzyCjiV7GgYImPKLk-Y5Dv_eB43IAkiEQNpQWLtU,17370
-wexample_wex_addon_dev_python-15.2.1.dist-info/WHEEL,sha256=IuIk3wbaEnFH1cx75iM2R1CmliRI3dFLXTbRakgvgFQ,90
-wexample_wex_addon_dev_python-15.2.1.dist-info/entry_points.txt,sha256=4WCjdYUa09eJPSM1ahhnId0BTg7ncgmLgeKtfKjuUy4,127
+wexample_wex_addon_dev_python-15.3.1.dist-info/METADATA,sha256=-7678Y_0wsDsSxdGcKV69ZBZol1sLzmHQV8eyF6PkoI,3508
+wexample_wex_addon_dev_python-15.3.1.dist-info/WHEEL,sha256=IuIk3wbaEnFH1cx75iM2R1CmliRI3dFLXTbRakgvgFQ,90
+wexample_wex_addon_dev_python-15.3.1.dist-info/entry_points.txt,sha256=4WCjdYUa09eJPSM1ahhnId0BTg7ncgmLgeKtfKjuUy4,127
 wexample_wex_addon_dev_python/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-wexample_wex_addon_dev_python/__pycache__/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 wexample_wex_addon_dev_python/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 wexample_wex_addon_dev_python/commands/code/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 wexample_wex_addon_dev_python/commands/code/check.py,sha256=TN2gsIjcte11cOCVq4hq4-8cJPemft7iIffYqsTqyus,3662
@@ -21,17 +20,14 @@ wexample_wex_addon_dev_python/commands/examples/utils/some_example_type.py,sha25
 wexample_wex_addon_dev_python/commands/examples/validate.py,sha256=Ab_rIX2XElVSLLGypNPsuxRX6100vsfffaUaPgRV_wc,917
 wexample_wex_addon_dev_python/commands/release/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 wexample_wex_addon_dev_python/common/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-wexample_wex_addon_dev_python/common/pypi_registry_gateway.py,sha256=uGsbQcVACsYur673HXvMVqUOjDFyBJK2X4twfkrVaoM,1994
+wexample_wex_addon_dev_python/common/pypi_registry_gateway.py,sha256=U-E21T_244IX66HKFFa2bwX1U6vxSgOfjZBPLh2Ku_s,2511
 wexample_wex_addon_dev_python/config_value/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-wexample_wex_addon_dev_python/config_value/__pycache__/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 wexample_wex_addon_dev_python/config_value/python_package_readme_config_value.py,sha256=Teq9-j7NCXsZpkxAM9FHilV7fL_BtQS70xmIFRJWCGc,1865
 wexample_wex_addon_dev_python/const/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-wexample_wex_addon_dev_python/const/__pycache__/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 wexample_wex_addon_dev_python/const/package.py,sha256=oRCPhaazJp5TujxF-35rrIYA4FJsqMqCns8lOFKOLeA,451
 wexample_wex_addon_dev_python/const/python.py,sha256=swBdTT6GHCZMdFMBLL0eiqt1PKZUwyRCqEpBYbKcvEo,330
 wexample_wex_addon_dev_python/const/tags.py,sha256=isvxhaBbendC6k_rluiJkQ2-yO7OwCEw9wse4wgEOIo,338
 wexample_wex_addon_dev_python/file/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-wexample_wex_addon_dev_python/file/__pycache__/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 wexample_wex_addon_dev_python/file/python_app_iml_file.py,sha256=O6OpMjB_Zn4Mt1sIi9AaGvQP4jM1I2_L_6O6S5-syJM,1206
 wexample_wex_addon_dev_python/file/python_pyproject_toml_file.py,sha256=2H0XismkdR-fF4wvCcGON3b1SKbnbG_GaRx5gW9bMOk,17108
 wexample_wex_addon_dev_python/formatter/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -39,7 +35,6 @@ wexample_wex_addon_dev_python/formatter/python_code_formatter.py,sha256=KIv2ddw0
 wexample_wex_addon_dev_python/helper/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 wexample_wex_addon_dev_python/helper/pdm.py,sha256=Q75RgR4xnJCQaGSY24Y4O3Y7qLSyUl0iUyYIbBtXUho,473
 wexample_wex_addon_dev_python/middleware/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-wexample_wex_addon_dev_python/middleware/__pycache__/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 wexample_wex_addon_dev_python/middleware/each_python_file_middleware.py,sha256=0BmUS1BlL8NY_imwBtykWxf4dnabA3nTrpVHhl9qjLE,2314
 wexample_wex_addon_dev_python/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 wexample_wex_addon_dev_python/python_addon_manager.py,sha256=0ayvkqn9uJYyK7IXqHKcWRP9w8WmRJwcJDWjef-Nh94,2725
@@ -61,6 +56,7 @@ wexample_wex_addon_dev_python/resources/ai/agents/describer/agent.yml,sha256=afT
 wexample_wex_addon_dev_python/resources/ai/agents/describer/context.j2,sha256=OTFLDQhKikePO20fRviui74Upwiyp42bMi6KPw_h1ws,2026
 wexample_wex_addon_dev_python/resources/design_rules/python_code.md,sha256=Xl6oGZnhuWIzmlcCI49p6SJmLFaQAQeGpr4hqjquWC4,974
 wexample_wex_addon_dev_python/resources/docker/Dockerfile.python-profiling,sha256=5ujzXfWNN2nv8qQzCLel6dlOwLQ1XhIGZuqplCNB_vQ,290
+wexample_wex_addon_dev_python/resources/package_gitlab_ci.yml,sha256=X2aaKG710DyiWlMaeO1sMHs8YbtRDOj_1kMROKdS4s8,155
 wexample_wex_addon_dev_python/resources/package_publish_gitlab.yml,sha256=WVMj-DeFedQak5s5FraEnM1Rx1-ut4KgPodvAVv25ZM,304
 wexample_wex_addon_dev_python/resources/readme_templates/install.md.j2,sha256=PDfD-2_HQXKtgq8seSRDL5SGbZ2BRrxDEKoFpO7qhb8,104
 wexample_wex_addon_dev_python/resources/readme_templates/tests.md.j2,sha256=tKLcDwx7jhQkryXIxWr12AK-hKEaP6Rusu2MrluiABs,1289
@@ -87,10 +83,9 @@ wexample_wex_addon_dev_python/services/python/samples/docker/images/Dockerfile.d
 wexample_wex_addon_dev_python/services/python/samples/docker/images/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 wexample_wex_addon_dev_python/services/python/service.yml,sha256=28gvNQIzZ0T0PBwQLH-Mbn-_T92sbfhXe0tZHMBairs,105
 wexample_wex_addon_dev_python/workdir/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-wexample_wex_addon_dev_python/workdir/__pycache__/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 wexample_wex_addon_dev_python/workdir/mixin/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 wexample_wex_addon_dev_python/workdir/mixin/with_profiling_python_workdir_mixin.py,sha256=PA_kqwe2kF5t1nKakX5Q-6fant2R18aEnZfkjr6iJ6k,3097
-wexample_wex_addon_dev_python/workdir/python_package_workdir.py,sha256=VJDIuJ-WrebCMt4TGRisHfQfyaj-XXoW9AgCioEWt5k,19609
+wexample_wex_addon_dev_python/workdir/python_package_workdir.py,sha256=zxPagcd9CvYc0nvX6Ry7kJj_0VLcI7fmvBAisvDQy4M,23310
 wexample_wex_addon_dev_python/workdir/python_packages_suite_workdir.py,sha256=7Jb5mKGNV2RjFtrFhUm6jbkiTfLDmy7sA97UGHITVdw,2902
-wexample_wex_addon_dev_python/workdir/python_workdir.py,sha256=NTqtMa88LW4MVDj_ndf0aVibQUl2mrNmewW1q4IjJu0,32061
-wexample_wex_addon_dev_python-15.2.1.dist-info/RECORD,,
+wexample_wex_addon_dev_python/workdir/python_workdir.py,sha256=1t4k3GX-3aNaV4aUb-NSstlDNtwPvmeGolPs9g3laI8,32833
+wexample_wex_addon_dev_python-15.3.1.dist-info/RECORD,,

wexample_wex_addon_dev_python-15.2.1.dist-info/METADATA

@@ -1,315 +0,0 @@
-Metadata-Version: 2.1
-Name: wexample-wex-addon-dev-python
-Version: 15.2.1
-Summary: Extends wex with commands to format, lint, and rename Python symbols, plus workdir types for Python packages and suites
-Author-Email: weeger <contact@wexample.com>
-License: MIT
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Project-URL: homepage, https://github.com/wexample/python-wex-dev-python
-Requires-Python: >=3.10
-Requires-Dist: attrs>=23.1.0
-Requires-Dist: black
-Requires-Dist: cattrs>=23.1.0
-Requires-Dist: griffe>=2.0.2
-Requires-Dist: isort
-Requires-Dist: networkx
-Requires-Dist: pylint
-Requires-Dist: pyright
-Requires-Dist: wexample-api>=6.8.0
-Requires-Dist: wexample-filestate-python>=9.1.0
-Requires-Dist: wexample-wex-addon-ai>=19.0.0
-Requires-Dist: wexample-wex-addon-app>=34.0.0
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Description-Content-Type: text/markdown
-
-# wex_addon_dev_python
-
-Version: 15.2.1
-
-`wex_addon_dev_python` extends the wex CLI with a `python::` command group that formats source files with isort and black (`python::code/format`), checks them with mypy, pylint, and pyright (`python::code/check`), and renames Python symbols — packages, modules, classes, functions, constants — while propagating every affected import statement across the workdir (`python::code/rename`). It also ships `PythonPackageWorkdir` and `PythonPackagesSuiteWorkdir`, two workdir types that let wex manage a single PDM-based package or a multi-package suite as a first-class project structure. The intended users are wex operators who develop and maintain Python packages within the wexample ecosystem.
-
-## 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-dev-python
-```
-
-Requires Python >=3.10.
-
-## Quickstart
-
-Install from PyPI:
-
-```bash
-pip install wexample-wex-addon-dev-python
-```
-
-That makes the `python::` command group available to wex. Pass any file or directory to `--file`; the middleware expands globs and recurses automatically.
-
-Format a source tree — isort sorts imports, black reformats the rest:
-
-```bash
-wex python::code/format --file src/mypackage/
-```
-
-Run the three static-analysis tools (mypy, pylint, pyright) against the same tree:
-
-```bash
-wex python::code/check --file src/mypackage/
-```
-
-Rename a Python symbol and rewrite every import statement that references it across the workdir. The `--dry_run` flag prints which files would change without touching them:
-
-```bash
-wex python::code/rename \
-  --source mylib.helpers \
-  --target mylib.helper \
-  --kind package \
-  --dry_run
-```
-
-Drop `--dry_run` to apply. Valid `--kind` values are `package`, `module`, `class`, `function`, and `constant`.
-
-## 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 package is a wex addon. Its single registration point is src/wexample_wex_addon_dev_python/python_addon_manager.py — a `PythonAddonManager` that inherits `AbstractAddonManager` and declares four contributions:
-
-- **middlewares** — `EachPythonFileMiddleware`
-- **selections** — `PythonCodePerformanceSelection`
-- **workdir types** — `python`, `python-package`, `python-packages-suite`
-- **configurable keys** — `PDM_BIN_DIR`, detected and applied by src/wexample_wex_addon_dev_python/helper/pdm.py
-
-Everything else in the package implements one of those four surfaces.
-
-### Middleware
-
-src/wexample_wex_addon_dev_python/middleware/each_python_file_middleware.py extends `EachFileMiddleware`. It filters `.py` files by extension and refuses to recurse into `__pycache__`, `.git`, `.venv`, `.mypy_cache`, and similar directories. Commands that operate file-by-file declare `@middleware(name="each_python_file")` to let the kernel expand a path argument into individual files before calling the command function.
-
-### Commands
-
-All three live under `src/wexample_wex_addon_dev_python/commands/code/`.
-
-**Format** — src/wexample_wex_addon_dev_python/commands/code/format.py runs isort then black in that order on one file. An optional `--tool` flag restricts execution to a single tool. The command returns `False` on the first failure when `--stop_on_failure` is set.
-
-**Check** — src/wexample_wex_addon_dev_python/commands/code/check.py runs mypy, pylint, and pyright in sequence. Pylint is invoked with `--output-format=json`; only messages of type `error` or `fatal` cause a `False` return; warnings and conventions are reported but do not fail the check.
-
-**Rename** — src/wexample_wex_addon_dev_python/commands/code/rename.py accepts `--source`, `--target`, and `--kind`. It resolves the `SymbolKind` enum, picks a handler class, delegates to `handler.run()`, and returns a `TableResponse` listing the changed files. A `--dry_run` flag stops the handler after the plan phase, touching nothing on disk.
-
-### Refactor subsystem
-
-The refactor package implements a three-phase rename pipeline.
-
-src/wexample_wex_addon_dev_python/refactor/abstract_python_rename_handler.py defines the pipeline: `compute_plan()` (scan only, no writes) → `preflight()` (detect permission errors and missing parents) → `apply()` (hand the plan to a `RenameApplier`). Subclasses implement `compute_plan` and `_build_report`.
-
-src/wexample_wex_addon_dev_python/refactor/rename_plan.py is the data structure. It carries:
-- `rewrites` — per-file new source text
-- `path_renames` — `(old, new)` pairs for files or directories
-- `directories_to_create` — dirs that must exist before rewrites run
-- `files_to_delete`, `directories_to_remove`, `directories_to_purge` — cleanup after moves
-
-src/wexample_wex_addon_dev_python/refactor/applier.py defines `RenameApplier` (abstract strategy) and `NaiveRenameApplier` (direct `os`/`shutil` calls). The sequencing is: create dirs → write files → rename paths → delete files → purge artefact dirs → remove empty dirs.
-
-src/wexample_wex_addon_dev_python/refactor/symbol_kind.py lists the supported kinds: `package`, `module`, `class`, `function`, `constant`. `method` is declared in the enum but not implemented; the comment explains why (dynamic typing makes safe method-rename impossible without a full type-inference pipeline).
-
-The package handler adds merge logic: when the target directory already exists, each child of the source is moved in, identical `__init__.py` files are dropped, and the empty source dir is removed. Non-identical file conflicts abort with a descriptive error.
-
-### Workdir hierarchy
-
-**`PythonWorkdir`** — src/wexample_wex_addon_dev_python/workdir/python_workdir.py is the base for every Python project. It mixes in `WithAiWorkdirMixin`, `WithProfilingPythonWorkdirMixin`, and `CodeBaseWorkdir`. Responsibilities:
-
-- venv path resolution (local `.venv` or a suite-level `python.venv_path` from runtime config)
-- `app_install` — creates the venv, then calls `_install_dependencies_in_venv`
-- test execution via `test_run` / `test_get_command` (pytest + pytest-cov, JSON report stored in `.wex/local/`)
-- filestate layout declaration in `prepare_value`: `src/{vendor}_{name}/`, `tests/`, `helpers/`, plus the full set of Python file options (future annotations, sort imports, modernize typing, order class members, format, …)
-- `get_app_config_file` — returns the managed `PythonPyprojectTomlFile`
-- `update_dependencies` — updates `pyproject.toml` then re-pins `requirements.txt` via `uv pip compile` with retry logic for PyPI propagation races
-
-**`PythonPackageWorkdir`** — src/wexample_wex_addon_dev_python/workdir/python_package_workdir.py extends `PythonWorkdir` for distributable packages. Additional responsibilities:
-
-- publish via `pdm publish` (PyPI) or a git tag push (private GitLab registry when `pdm.repository.url` is set)
-- `_wait_for_registry` — polls the PEP 503 Simple index through `PypiRegistryGateway` until the new version appears
-- `_classify_version_bump` — uses `griffe` to compare the current AST against the previous git tag and determine major vs. intermediate bump
-- suite-aware install in local env: external deps are pip-installed normally; suite packages are installed in editable mode, leaf-to-trunk order, skipping packages already editable at the right path
-- `get_required_knowledge_pages` adds `usage/quickstart` to the pages the workdir expects to exist
-
-**`PythonPackagesSuiteWorkdir`** — src/wexample_wex_addon_dev_python/workdir/python_packages_suite_workdir.py extends `FrameworkPackageSuiteWorkdir`. It treats any subdirectory of `pip/` that contains a `pyproject.toml` as a package. `build_dependencies_stack` builds a `networkx` directed graph from the local dependency map and returns the shortest path from one package to another as concrete `PythonPackageWorkdir` objects.
-
-**`WithProfilingPythonWorkdirMixin`** — src/wexample_wex_addon_dev_python/workdir/mixin/with_profiling_python_workdir_mixin.py runs `pytest --benchmark-only` in the project's venv, writes a temporary JSON report, parses benchmark stats (min, mean, median, max in ms, rounds), and returns the result as a structured dict.
-
-### File objects
-
-src/wexample_wex_addon_dev_python/file/python_pyproject_toml_file.py wraps `pyproject.toml` as a managed filestate object. Its `dumps` method enforces canonical structure on every write: build-system pinned to `pdm-backend`, PDM build config derived from the workdir's `get_src_import_name()`, project metadata from wex config, dependencies sorted, dev group always containing `pytest` and `pytest-cov`, pytest and coverage tool config injected, and sections reordered (`build-system` → `project` → `tool`).
-
-### Selection
-
-src/wexample_wex_addon_dev_python/selection/abstract_python_code_selection.py establishes the Python-file baseline for AI agent selections: `.py` extension only, skip `__init__.py`, skip `__pycache__` / `/tests/` / `/build/` / `/dist/` / `/.venv/` / `/.pdm-build/`, 50-byte minimum.
-
-src/wexample_wex_addon_dev_python/selection/python_code_performance_selection.py inherits that baseline and adds two constraints: the file must be under `/src/`, and its AST must contain at least one non-trivial function. Trivial is defined as: `pass`, `...`, docstring-only, `raise NotImplementedError`, a same-name `super()` pass-through, or any `@abstractmethod`.
-
-src/wexample_wex_addon_dev_python/selection/package_description_missing_selection.py selects the package's own `.wex/config.yml`, and only when `global.description` is empty. Selecting the config file rather than the package makes the item what is to be edited, so the agent writes that one field and leaves the rest of the file alone. The description is copied verbatim into `pyproject.toml` and shown on the package registry.
-
-This replaced a filestate operation that called the agent from inside `apply_operation`. Writing a description is a job given to an agent, not a file state to converge on: rectification retried it every pass, and an agent declining to invent a description for a package with no code kept the hole open, which kept the retry going.
-
-### Supporting pieces
-
-src/wexample_wex_addon_dev_python/common/pypi_registry_gateway.py is a thin HTTP client over the PEP 503 Simple index. It accepts optional Basic auth (`username` + `token`) and exposes `has_version(package, version) -> bool`.
-
-src/wexample_wex_addon_dev_python/services/python/app_service.py contributes the initial `pyproject.toml` and `src/app/` scaffolding when a new Python app service is set up.
-
-src/wexample_wex_addon_dev_python/const/tags.py declares the `DomainTag` constants (`domain:format`, `domain:language-python`, `domain:lint`, `domain:service`) used in command `@command(tags=[…])` decorators.
-
-### Call path for a rename
-
-1. `python__code__rename` validates `--kind`, selects a handler class, calls `app_workdir.get_code_scope_paths(kernel)` for the set of roots.
-2. The handler's `__attrs_post_init__` splits the dotted names and validates they are non-empty.
-3. `handler.run()` calls `compute_plan()` — the handler scans every root for the source pattern, builds a `RenamePlan` (rewrites + path moves), returns it.
-4. If not `dry_run`, `plan.preflight()` checks writability and parent existence. Any problem raises `RuntimeError` before a single file is touched.
-5. `NaiveRenameApplier().apply(plan)` executes the six steps in sequence.
-6. The command formats the report into a `TableResponse`.
-
-## 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.
-
-## Dependencies
-
-- attrs: >=23.1.0
-- black: 
-- cattrs: >=23.1.0
-- griffe: >=2.0.2
-- isort: 
-- networkx: 
-- pylint: 
-- pyright: 
-- wexample-api: >=6.8.0
-- wexample-filestate-python: >=9.1.0
-- wexample-wex-addon-ai: >=19.0.0
-- wexample-wex-addon-app: >=34.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.
-
-Built and maintained by [Romain Weeger](https://weeger.io).
-
-## 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_dev_python/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-dev-python
-- **Issue Tracker**: https://github.com/wexample/python-wex-addon-dev-python/issues
-- **Discussions**: https://github.com/wexample/python-wex-addon-dev-python/discussions
-- **PyPI**: [pypi.org/project/wexample-wex-addon-dev-python](https://pypi.org/project/wexample-wex-addon-dev-python/)
-
-## 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.