wexample-wex-addon-dev-python 13.1.0__py3-none-any.whl → 13.2.0__py3-none-any.whl

wexample_wex_addon_dev_python/config_value/python_package_readme_config_value.py

@@ -10,25 +10,28 @@ from wexample_wex_addon_app.config_value.app_readme_config_value import (
 class PythonPackageReadmeContentConfigValue(AppReadmeConfigValue):
     """README generation for Python packages."""
 
-    def _get_app_description(self) -> str:
-        """Extract description from pyproject.toml."""
-        return self.workdir.get_app_config().get("project", {}).get("description")
+    def _get_app_description(self) -> str | None:
+        """Extract description from pyproject.toml, else from the wex config."""
+        description = self._get_project_table().get("description")
+        return description or super()._get_app_description()
 
     def _get_app_homepage(self) -> str:
         """Extract homepage URL from pyproject.toml."""
-        project = self.workdir.get_app_config()
-        raw_urls = project.get("urls", {})
+        raw_urls = self._get_project_table().get("urls", {})
         urls = raw_urls if isinstance(raw_urls, dict) else {}
         return urls.get("homepage") or urls.get("Homepage") or ""
 
     def _get_project_license(self) -> str | None:
         """Extract license information from pyproject.toml."""
-        project = self.workdir.get_app_config()
-        license_field = project.get("license", {})
+        license_field = self._get_project_table().get("license", {})
         if isinstance(license_field, dict):
             return license_field.get("text", "") or license_field.get("file", "")
         return str(license_field) if license_field else ""
 
+    def _get_project_table(self) -> dict:
+        """The `[project]` table, which is where PEP 621 puts every field read here."""
+        return self.workdir.get_app_config().get("project", {})
+
     def _get_template_context(self) -> dict:
         """Build template context with Python-specific variables.
 
@@ -36,9 +39,8 @@ class PythonPackageReadmeContentConfigValue(AppReadmeConfigValue):
         """
         context = super()._get_template_context()
 
-        # Add Python-specific variable
-        context["python_version"] = (
-            self.workdir.get_app_config().get("project", {}).get("requires-python", "")
-        )
+        project = self._get_project_table()
+        context["distribution_name"] = project.get("name", "")
+        context["python_version"] = project.get("requires-python", "")
 
         return context

wexample_wex_addon_dev_python/formatter/python_code_formatter.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar
+
+from wexample_helpers.decorator.base_class import base_class
+from wexample_wex_addon_ai.formatter.abstract_formatter import AbstractFormatter
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+@base_class
+class PythonCodeFormatter(AbstractFormatter):
+    """Python modules under a package's `src/`, the code the package actually ships.
+
+    Deliberately narrow: tests, examples and tooling scripts are Python too, but they
+    answer to different conventions and get their own formatter rather than a widened
+    match here.
+
+    The rules below say nothing about import placement, member ordering, blank lines,
+    f-strings or typing syntax — `wexample-filestate-python` rewrites all of those at
+    rectify time, so spending prompt on them would only ask an agent to imitate what a
+    deterministic pass fixes anyway. What is left is what no pass can decide.
+    """
+
+    FORMATTER_NAME: ClassVar[str] = "python-code"
+
+    def get_design_rules(self) -> str:
+        return self.read_resource("design_rules", "python_code.md")
+
+    def get_writing_rules(self) -> str:
+        return self.read_resource("writing_rules", "python_code.md")
+
+    def matches_path(self, path: Path) -> bool:
+        """A `.py` under the `src/` of a directory holding a `pyproject.toml`.
+
+        Anchored on the manifest rather than on the mere presence of a `src` segment,
+        so a vendored tree or a virtualenv that happens to contain `src/` is out.
+        """
+        if path.suffix != ".py":
+            return False
+
+        for parent in path.parents:
+            if parent.name == "src" and (parent.parent / "pyproject.toml").exists():
+                return True
+        return False

wexample_wex_addon_dev_python/operation/generated_description_operation.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_filestate.enum.scopes import Scope
+from wexample_filestate.operation.abstract_operation import AbstractOperation
+from wexample_helpers.classes.mixin.has_package_resources import HasPackageResources
+from wexample_helpers.classes.private_field import private_field
+from wexample_helpers.decorator.base_class import base_class
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+CONFIG_KEY_SECTION = "global"
+CONFIG_KEY_NAME = "description"
+DESCRIPTION_MAX_LENGTH = 200
+DESCRIPTION_PLACEHOLDER = "<one sentence, written by the describer agent on apply>"
+DESCRIPTION_UNKNOWN = "UNKNOWN"
+
+
+@base_class
+class GeneratedDescriptionOperation(HasPackageResources, AbstractOperation):
+    """Write `global.description` into the app config, asking an agent for the sentence.
+
+    The model call lives here rather than in the option that builds this operation:
+    `FileStateDryRunResult` never calls `apply_operation`, so a preview stays offline and
+    free, and shows the placeholder instead of a sentence it would then have to produce a
+    second time on apply.
+    """
+
+    _previous: str | None = private_field(
+        default=None,
+        description="Value this operation replaced, for `undo`. None when the key was absent.",
+    )
+
+    @classmethod
+    def get_scopes(cls) -> list[Scope]:
+        return [Scope.CONTENT]
+
+    def apply_operation(self) -> None:
+        description = self._generate()
+        if description is None:
+            return
+
+        config_file = self.target.get_config_file()
+        content = config_file.read_parsed() or {}
+        section = content.setdefault(CONFIG_KEY_SECTION, {})
+
+        self._previous = section.get(CONFIG_KEY_NAME)
+        section[CONFIG_KEY_NAME] = description
+        config_file.write_parsed(content)
+
+        self.target.success(f"Description: {description}")
+
+    def undo(self) -> None:
+        config_file = self.target.get_config_file()
+        content = config_file.read_parsed() or {}
+        section = content.get(CONFIG_KEY_SECTION)
+        if not isinstance(section, dict):
+            return
+
+        if self._previous is None:
+            section.pop(CONFIG_KEY_NAME, None)
+        else:
+            section[CONFIG_KEY_NAME] = self._previous
+        config_file.write_parsed(content)
+
+    def _agent_config_path(self) -> Path:
+        return self.get_resource_path("ai", "agents", "describer", "agent.yml")
+
+    def _generate(self) -> str | None:
+        """The sentence, or None when nothing should be written.
+
+        Every failure mode lands on None: the hole stays, the pass reports it and moves on.
+        A rectification must not fail because a model was unreachable.
+        """
+        from wexample_wex_addon_ai.agent.claude_agent import ClaudeAgent
+        from wexample_wex_addon_ai.file.agent_yaml_file import AgentYamlFile
+
+        try:
+            agent = ClaudeAgent(
+                io=self.target.io,
+                app_workdir=self.target,
+                config_file=AgentYamlFile.create_from_path(
+                    path=self._agent_config_path()
+                ),
+            )
+            sentence = agent.run_value_draft(self._prompt())
+        except Exception as exception:
+            self.target.warning(
+                f"Could not generate a description: {exception}. "
+                f"Leaving {CONFIG_KEY_SECTION}.{CONFIG_KEY_NAME} unset."
+            )
+            return None
+
+        return self._validate(sentence)
+
+    def _prompt(self) -> str:
+        return (
+            f"Package directory: {self.target.get_path()}\n"
+            f"Package name: {self.target.get_package_name()}\n"
+            f"\n"
+            f"Read the package and report its one-sentence description."
+        )
+
+    def _validate(self, sentence: str | None) -> str | None:
+        """Guard the one shape that would still poison a config file: a runaway sentence.
+
+        `report_value` already delimits the answer, so nothing has to be extracted from the
+        agent's prose — a missing report is simply `None`.
+        """
+        if sentence is None:
+            self.target.warning(
+                f"The describer reported nothing — "
+                f"leaving {CONFIG_KEY_SECTION}.{CONFIG_KEY_NAME} unset."
+            )
+            return None
+
+        if len(sentence) > DESCRIPTION_MAX_LENGTH:
+            self.target.warning(
+                f"The describer answered {len(sentence)} characters, over the "
+                f"{DESCRIPTION_MAX_LENGTH} allowed — leaving "
+                f"{CONFIG_KEY_SECTION}.{CONFIG_KEY_NAME} unset."
+            )
+            return None
+
+        return sentence

wexample_wex_addon_dev_python/option/generated_description_option.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Union
+
+from wexample_config.config_option.abstract_config_option import AbstractConfigOption
+from wexample_filestate.enum.scopes import Scope
+from wexample_filestate.option.mixin.option_mixin import OptionMixin
+from wexample_helpers.decorator.base_class import base_class
+
+if TYPE_CHECKING:
+    from wexample_filestate.const.types_state_items import TargetFileOrDirectoryType
+    from wexample_filestate.operation.abstract_operation import AbstractOperation
+
+
+@base_class
+class GeneratedDescriptionOption(OptionMixin, AbstractConfigOption):
+    """Ask an agent for `global.description` when the app config has none.
+
+    Only ever fills a hole: a description already written — by a human or by an earlier
+    run — is left alone, which is what makes the option convergent. It fires once per
+    package, then never again. To have one rewritten, clear the key.
+
+    Declared on the workdir, not on `pyproject.toml`: the toml's `description` is already
+    derived from this key by `PythonPyprojectTomlFile._enforce_project_metadata`, so
+    filling the config is enough for the value to reach the manifest through the ordinary
+    deterministic path.
+    """
+
+    @classmethod
+    def get_scopes(cls) -> list[Scope]:
+        return [Scope.CONTENT]
+
+    @staticmethod
+    def get_raw_value_allowed_type() -> Any:
+        return Union[bool, Callable]
+
+    def applicable_on_file(self) -> bool:
+        return False
+
+    def applicable_on_missing(self) -> bool:
+        return False
+
+    def create_required_operation(
+        self, target: TargetFileOrDirectoryType, scopes: set[Scope]
+    ) -> AbstractOperation | None:
+        from wexample_wex_addon_dev_python.operation.generated_description_operation import (
+            CONFIG_KEY_NAME,
+            CONFIG_KEY_SECTION,
+            DESCRIPTION_PLACEHOLDER,
+            GeneratedDescriptionOperation,
+        )
+
+        value = self.get_value()
+        raw = value.raw if value is not None else None
+        if callable(raw):
+            raw = raw(target)
+        if not bool(raw):
+            return None
+
+        existing = target.get_config().search(
+            f"{CONFIG_KEY_SECTION}.{CONFIG_KEY_NAME}"
+        )
+        if not existing.is_none() and existing.get_str().strip():
+            return None
+
+        return GeneratedDescriptionOperation(
+            option=self,
+            target=target,
+            description=(
+                f"Write {CONFIG_KEY_SECTION}.{CONFIG_KEY_NAME}: "
+                f"{DESCRIPTION_PLACEHOLDER}"
+            ),
+        )
+
+    def get_description(self) -> str:
+        return "Have an agent write the app description when none is set"

wexample_wex_addon_dev_python/options_provider/generative_options_provider.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_config.options_provider.abstract_options_provider import (
+    AbstractOptionsProvider,
+)
+
+if TYPE_CHECKING:
+    from wexample_config.config_option.abstract_config_option import (
+        AbstractConfigOption,
+    )
+
+
+class GenerativeOptionsProvider(AbstractOptionsProvider):
+    @classmethod
+    def get_options(cls) -> list[type[AbstractConfigOption]]:
+        if "_options_cache" not in cls.__dict__:
+            from wexample_wex_addon_dev_python.option.generated_description_option import (
+                GeneratedDescriptionOption,
+            )
+
+            cls._options_cache: list[type[AbstractConfigOption]] = [
+                GeneratedDescriptionOption
+            ]
+        return cls._options_cache

wexample_wex_addon_dev_python/python_addon_manager.py

@@ -2,6 +2,9 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
+from wexample_wex_addon_ai.formatter.formatter_contributing_addon_mixin import (
+    FormatterContributingAddonMixin,
+)
 from wexample_wex_addon_ai.selection.selection_contributing_addon_mixin import (
     SelectionContributingAddonMixin,
 )
@@ -9,10 +12,22 @@ from wexample_wex_core.common.abstract_addon_manager import AbstractAddonManager
 
 if TYPE_CHECKING:
     from wexample_cli.middleware.abstract_middleware import AbstractMiddleware
+    from wexample_wex_addon_ai.formatter.abstract_formatter import AbstractFormatter
     from wexample_wex_addon_ai.selection.abstract_selection import AbstractSelection
 
 
-class PythonAddonManager(SelectionContributingAddonMixin, AbstractAddonManager):
+class PythonAddonManager(
+    FormatterContributingAddonMixin,
+    SelectionContributingAddonMixin,
+    AbstractAddonManager,
+):
+    def get_formatter_classes(self) -> list[type[AbstractFormatter]]:
+        from wexample_wex_addon_dev_python.formatter.python_code_formatter import (
+            PythonCodeFormatter,
+        )
+
+        return [PythonCodeFormatter]
+
     def get_local_configurable_keys(self) -> list[dict]:
         from wexample_wex_addon_dev_python.helper.pdm import (
             apply_pdm_bin_dir,
@@ -43,3 +58,18 @@ class PythonAddonManager(SelectionContributingAddonMixin, AbstractAddonManager):
         )
 
         return [PythonCodePerformanceSelection]
+
+    def get_workdir_types(self) -> dict[str, type]:
+        from wexample_wex_addon_dev_python.workdir.python_package_workdir import (
+            PythonPackageWorkdir,
+        )
+        from wexample_wex_addon_dev_python.workdir.python_packages_suite_workdir import (
+            PythonPackagesSuiteWorkdir,
+        )
+        from wexample_wex_addon_dev_python.workdir.python_workdir import PythonWorkdir
+
+        return {
+            "python": PythonWorkdir,
+            "python-package": PythonPackageWorkdir,
+            "python-packages-suite": PythonPackagesSuiteWorkdir,
+        }

wexample_wex_addon_dev_python/resources/ai/agents/describer/agent.yml

@@ -0,0 +1,8 @@
+description: Writes the one-sentence description of a Python package
+model: claude:sonnet-5
+modes: structured
+todos: false
+allowed_tools:
+  - Read
+  - Glob
+  - Grep

wexample_wex_addon_dev_python/resources/ai/agents/describer/context.j2

@@ -0,0 +1,36 @@
+## Domain: describing one Python package in one sentence
+
+You are given a package directory. You read it and answer with a single sentence saying
+what the package is for. That sentence lands in `global.description`, from which it is
+copied verbatim into `pyproject.toml` and shown on the package registry.
+
+### Read before you write
+
+The package name alone is not enough — `wexample-filestate-python` tells a reader nothing.
+Look at what the code actually does: the public modules under `src/`, the README if there
+is one, the classes a caller would import. A description written from the name is worse
+than no description, because it reads as informative while saying nothing.
+
+### What the sentence has to do
+
+Name the thing and say what problem it solves, in terms a developer who has never seen the
+package would understand. Prefer the concrete over the categorical: "declares a desired
+file tree and rectifies the disk to match it" beats "provides file management utilities".
+
+### Constraints
+
+- One sentence. No trailing period is required, but do not write two.
+- No more than about 120 characters. Registries truncate.
+- Do not open with the package name, an article, or "A Python package that…" — the name is
+  already displayed next to the description. Start with the verb.
+- Plain prose: no Markdown, no quotes around the sentence, no backticks.
+- English.
+
+### Answering
+
+The sentence goes into `report_value`, and only what you pass there is written to the
+config file. Text you type outside that call is read by nobody.
+
+If the package is too empty to describe honestly — no source, no README, nothing but
+scaffolding — end your turn without calling `report_value`. The host writes nothing and
+leaves the field for a human. Guessing is the one failure that matters here.

wexample_wex_addon_dev_python/resources/design_rules/python_code.md

@@ -0,0 +1,13 @@
+This file is design rules for Python shipped by a package, under its `src/`. Decide the
+layout below before opening an editor — by the time a file is being written, its path is
+already a decision made.
+
+- One class per file, one file per class, and the file name is the class name in
+  snake_case — that last part is enforced, so a mismatch is an error, not a preference. A second class belongs in its own file, not appended to this one.
+- Kinds live apart, each in its own directory: classes in `classes/`, helper functions in
+  `helper/`, constants in `const/`, enums in `enums/`. A module holding a class plus the
+  two functions that serve it is the case to split, not the exception that justifies
+  keeping them together.
+- Content that is text rather than code — a prompt, a template, a long block of prose —
+  goes in a file under the package's `resources/`, read through `HasPackageResources`,
+  rather than a triple-quoted string in the class that uses it.

wexample_wex_addon_dev_python/resources/readme_templates/install.md.j2

@@ -0,0 +1,7 @@
+## Installation
+
+```bash
+pip install {{ distribution_name }}
+```
+
+Requires Python {{ python_version }}.

wexample_wex_addon_dev_python/resources/writing_rules/python_code.md

@@ -0,0 +1,41 @@
+This file is Python shipped by a package, under its `src/`. The file's path is already
+decided by the time these rules apply — see `ai::design/rules --formatter python-code` for
+the layout decisions that come before it.
+
+- Code, names, comments and docstrings are in English, whatever language the conversation
+  is held in.
+- Classes are attrs-based: `@base_class` (which applies `attrs.define(kw_only=True)`), and
+  attributes declared with `public_field(description=...)`, `protected_field(...)` or
+  `private_field(...)` from `wexample_helpers.classes`. No Pydantic — the description is
+  mandatory and is the field's documentation.
+- Within a field, `default=` carries a scalar and `factory=` a mutable container. A `list`
+  or `dict` passed as `default` is shared by every instance ever built, which surfaces
+  much later as one object mutating another's state.
+- Never write `__init__`: attrs generates it, and `private_field` is kept out of it by
+  design. Initialization logic goes in `__attrs_post_init__`, which must call
+  `super().__attrs_post_init__()` — parent classes rely on theirs running.
+- Annotate parameters and any return type that is not obvious. Only the trivially
+  inferable returns (`None`, `bool`, `str`, `int`, `float`) get filled in later; everything
+  else is yours to write.
+- A list literal written one item per line only stays sorted if you flag it: add
+  `# filestate: python-iterable-sort` above it. Without the marker nothing reorders it,
+  and it drifts.
+- Import placement, member ordering, blank lines, f-strings, `from __future__ import
+  annotations`, the `TYPE_CHECKING` block and typing modernisation are settled later by a
+  formatting pass the operator runs, not by you. Write what reads naturally and leave the
+  form alone: do not reshuffle a file to imitate the pass, and do not run it yourself to
+  finish a task — a file whose only fault is cosmetic is a file that is done.
+- A `try` is occasional and justified: it catches a named exception somewhere that knows
+  what to do about it. Wrapping a call defensively, catching `Exception`, or writing a
+  `finally` that lets the failure pass turns a bug into a wrong result reported nowhere.
+  Let it raise — a traceback at the point of failure is worth more than a silent fallback
+  discovered three layers later.
+- Defensive code goes the same way: a guard against a state that cannot happen, a fallback
+  for a value that is always there, an `isinstance` check on something the signature
+  already types. Validate at the boundary — operator input, an external API, a file on
+  disk — and trust what our own code hands you.
+- Comment only what the code cannot say: a constraint, an invariant, the reason a
+  surprising line is the way it is. A comment restating the line it sits above is noise,
+  and a docstring explaining what a well-named method obviously does is the same noise
+  indented. A comment that no longer matches the code it describes is deleted, not
+  updated around.

wexample_wex_addon_dev_python/workdir/python_package_workdir.py

@@ -48,6 +48,16 @@ class PythonPackageWorkdir(PythonWorkdir):
                 "Install: pipx install pdm — then run: wex core::env/configure"
             )
 
+    def get_required_knowledge_pages(self) -> dict[str, str]:
+        return {
+            **super().get_required_knowledge_pages(),
+            "usage/quickstart": (
+                "The shortest example that does something real: the import, the call, "
+                "the result. It must run as written against the published package. "
+                "Open with `## Quickstart`."
+            ),
+        }
+
     def prepare_value(self, raw_value: DictConfig | None = None) -> DictConfig:
         from wexample_helpers.helper.file import file_read
         from wexample_helpers.helper.module import module_get_path

wexample_wex_addon_dev_python/workdir/python_workdir.py

@@ -101,8 +101,10 @@ class PythonWorkdir(
         )
 
         config_file = self.find_by_type(PythonPyprojectTomlFile)
-        # Read once to populate content with file source.
-        config_file.read_text(reload=reload)
+        # Read once to populate content with file source. A package being
+        # bootstrapped has no pyproject.toml yet, and reads as an empty config.
+        if config_file.get_path().exists():
+            config_file.read_text(reload=reload)
         return config_file
 
     def get_dependencies_versions(self) -> dict[str, str]:
@@ -116,15 +118,24 @@ class PythonWorkdir(
             PythonOptionsProvider,
         )
 
+        from wexample_wex_addon_dev_python.options_provider.generative_options_provider import (
+            GenerativeOptionsProvider,
+        )
+
         options = super().get_options_providers()
 
         options.append(PythonOptionsProvider)
+        options.append(GenerativeOptionsProvider)
 
         return options
 
     def get_package_import_name(self) -> str:
         """Get the full package import name with vendor prefix."""
-        return f"{self.get_vendor_name()}_{self.get_project_name()}"
+        from wexample_helpers.helper.string import string_to_snake_case
+
+        # global.name may be written in any case: an import name has to be a
+        # valid Python identifier, matching the generated src/ directory.
+        return f"{self.get_vendor_name()}_{string_to_snake_case(self.get_project_name())}"
 
     def get_package_name(self) -> str:
         from wexample_helpers.helper.string import string_to_kebab_case
@@ -193,6 +204,7 @@ class PythonWorkdir(
         from wexample_filestate.option.sidecar_of_option import (
             SidecarOfOption,
         )
+        from wexample_filestate_python.file.python_file import PythonFile
         from wexample_filestate_python.file.python_test_stub_file import (
             PythonTestStubFile,
         )
@@ -200,11 +212,16 @@ class PythonWorkdir(
         from wexample_wex_addon_dev_python.file.python_pyproject_toml_file import (
             PythonPyprojectTomlFile,
         )
+        from wexample_wex_addon_dev_python.option.generated_description_option import (
+            GeneratedDescriptionOption,
+        )
 
         raw_value = super().prepare_value(raw_value=raw_value)
 
         self.append_agents(config=raw_value)
 
+        raw_value[GeneratedDescriptionOption.get_name()] = True
+
         children = raw_value["children"]
 
         self.add_gitignore_rules(
@@ -242,6 +259,11 @@ class PythonWorkdir(
                         self._create_python_file_children_filter(
                             exclude_dirs=("unit",),
                         ),
+                        {
+                            "name": ".gitkeep",
+                            "type": DiskItemType.FILE,
+                            "should_exist": True,
+                        },
                         # NOTE: tests/unit/ and tests/unit/helpers/ omit
                         # `should_exist` — we don't want filestate to delete
                         # them when sidecars haven't been generated yet (no
@@ -322,6 +344,13 @@ class PythonWorkdir(
                                 self._create_python_file_children_filter(
                                     exclude_dirs=("helpers",),
                                 ),
+                                {
+                                    # The factory above only reaches subdirectories.
+                                    "name": "__init__.py",
+                                    "class": PythonFile,
+                                    "type": DiskItemType.FILE,
+                                    "should_exist": True,
+                                },
                                 {
                                     "name": "py.typed",
                                     "type": DiskItemType.FILE,