wexample-wex-addon-dev-python 0.0.44__py3-none-any.whl → 0.0.45__py3-none-any.whl

wexample_wex_addon_dev_python/config_value/python_package_readme_config_value.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import os
+
+from wexample_filestate.config_value.readme_content_config_value import (
+    ReadmeContentConfigValue,
+)
+from wexample_wex_addon_dev_python.workdir.python_package_workdir import (
+    PythonPackageWorkdir,
+)
+
+
+class PythonPackageReadmeContentConfigValue(ReadmeContentConfigValue):
+    workdir: PythonPackageWorkdir
+
+    def _get_doc_path(self, section: str) -> str:
+        """
+        Returns the path to a documentation section file
+        """
+        return os.path.join(
+            self.workdir.get_path(), ".wex", "doc", "readme", f"{section}.md"
+        )
+
+    def _add_section_if_exists(self, section: str) -> str:
+        """
+        Returns section content if the documentation file exists
+        """
+        doc_path = self._get_doc_path(section)
+
+        if os.path.exists(doc_path):
+            with open(doc_path, encoding="utf-8") as file:
+                content = file.read()
+                return f"## {section.title()}\n\n{content}\n\n"
+
+        return ""
+
+    def get_templates(self) -> list[str] | None:
+        # Use TOMLDocument from the workdir
+        doc = self.workdir.get_project_config()
+        project = doc.get("project", {}) if isinstance(doc, dict) else {}
+
+        # Extract information
+        description = project.get("description", "")
+        python_version = project.get("requires-python", "")
+        dependencies = project.get("dependencies", [])
+        urls = (
+            project.get("urls", {}) if isinstance(project.get("urls", {}), dict) else {}
+        )
+        # Accept both lowercase and capitalized homepage key variants
+        homepage = urls.get("homepage") or urls.get("Homepage") or ""
+        license_field = project.get("license", {})
+        if isinstance(license_field, dict):
+            license_info = license_field.get("text", "") or license_field.get(
+                "file", ""
+            )
+        else:
+            license_info = str(license_field) if license_field else ""
+
+        # Format dependencies list
+        deps_list = "\n".join([f"- {dep}" for dep in dependencies])
+
+        package_name = self.workdir.get_package_name()
+        return [
+            f"# {package_name}\n\n"
+            f"{description}\n\n"
+            f"Version: {self.workdir.get_project_version()}\n\n"
+            f'{self._add_section_if_exists("features")}'
+            "## Requirements\n\n"
+            f"- Python {python_version}\n\n"
+            "## Dependencies\n\n"
+            f"{deps_list}\n\n"
+            "## Installation\n\n"
+            "```bash\n"
+            f"pip install {package_name}\n"
+            "```\n\n"
+            f'{self._add_section_if_exists("usage")}'
+            "## Links\n\n"
+            f"- Homepage: {homepage}\n\n"
+            "## License\n\n"
+            f"{license_info}"
+        ]

wexample_wex_addon_dev_python/const/package.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+# Names of dev/build tools to remove from runtime [project.dependencies]
+# Keep this list in sync with tooling expectations.
+RUNTIME_DEPENDENCY_REMOVE_NAMES: set[str] = {
+    "pytest",
+    "pip-tools",
+    "black",
+    "ruff",
+    "flake8",
+    "mypy",
+    "isort",
+    "coverage",
+    "build",
+    "twine",
+    "pip",
+    "setuptools",
+    "wheel",
+    "typing-extensions",
+}

wexample_wex_addon_dev_python/file/python_package_toml_file.py

@@ -0,0 +1,304 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_filestate.item.file.toml_file import TomlFile
+from wexample_wex_core.workdir.mixin.as_suite_package_item import (
+    AsSuitePackageItem,
+)
+
+if TYPE_CHECKING:
+    from tomlkit import TOMLDocument
+    from wexample_wex_core.workdir.code_base_workdir import (
+        CodeBaseWorkdir,
+    )
+
+
+class PythonPackageTomlFile(AsSuitePackageItem, TomlFile):
+
+    def _project_table(self):
+        """Ensure and return the [project] table."""
+        from wexample_filestate_python.helpers.toml import toml_ensure_table
+
+        doc = self.read_parsed()
+        project, _ = toml_ensure_table(doc, ["project"])
+        return project
+
+    def _dependencies_array(self):
+        """Ensure and return project.dependencies as a multi-line TOML array."""
+        from wexample_filestate_python.helpers.toml import (
+            toml_ensure_array,
+        )
+
+        project = self._project_table()
+        deps, _ = toml_ensure_array(project, "dependencies")
+        deps.multiline(True)
+        return deps
+
+    def _optional_group_array(self, group: str):
+        """Ensure and return project.optional-dependencies[group] as multi-line array."""
+        from wexample_filestate_python.helpers.toml import (
+            toml_ensure_array,
+            toml_ensure_table,
+        )
+
+        project = self._project_table()
+        opt, _ = toml_ensure_table(project, ["optional-dependencies"])
+        arr, _ = toml_ensure_array(opt, group)
+        arr.multiline(True)
+        return arr
+
+    # --- Unified dependency accessors (runtime vs optional) ---
+    def _get_deps_array(self, optional: bool = False, group: str = "dev"):
+        """Return TOML array for runtime deps or optional group (multiline)."""
+        return (
+            self._optional_group_array(group)
+            if optional
+            else self._dependencies_array()
+        )
+
+    def list_dependencies(
+        self, optional: bool = False, group: str = "dev"
+    ) -> list[str]:
+        deps = self._get_deps_array(optional=optional, group=group)
+        return [str(x) for x in list(deps)]
+
+    def list_dependency_names(
+        self,
+        canonicalize_names: bool = True,
+        optional: bool = False,
+        group: str = "dev",
+    ) -> list[str]:
+        """Return dependency package names derived from list_dependencies().
+
+        If canonicalize_names is True, names are normalized using packaging's
+        canonicalize_name for robust comparisons (dash/underscore, case, etc.).
+        """
+        from packaging.requirements import Requirement
+        from packaging.utils import canonicalize_name
+
+        names: list[str] = []
+        for spec in self.list_dependencies(optional=optional, group=group):
+            try:
+                name = Requirement(spec).name
+                names.append(canonicalize_name(name) if canonicalize_names else name)
+            except Exception:
+                # Skip unparsable entries when deriving names
+                continue
+        return names
+
+    def add_dependency(
+        self, spec: str, optional: bool = False, group: str = "dev"
+    ) -> bool:
+        from packaging.requirements import Requirement
+        from packaging.utils import canonicalize_name
+        from wexample_filestate_python.helpers.toml import toml_sort_string_array
+
+        deps = self._get_deps_array(optional=optional, group=group)
+        # Remove existing entries for the same package name before adding the new spec.
+        new_name = canonicalize_name(Requirement(spec).name)
+        removed = self.remove_dependency_by_name(
+            new_name, optional=optional, group=group
+        )
+
+        # Append (or re-append) the new spec if it is not already present verbatim
+        if spec not in deps:
+            deps.append(spec)
+            toml_sort_string_array(deps)
+            return True
+
+        return removed
+
+    def remove_dependency_by_name(
+        self, package_name: str, optional: bool = False, group: str = "dev"
+    ) -> bool:
+        """Remove all dependency entries that match the given package name.
+
+        The provided package_name can be raw; it will be canonicalized to ensure
+        consistent matching against entries parsed from list_dependencies().
+        """
+        from packaging.requirements import Requirement
+        from packaging.utils import canonicalize_name
+
+        deps = self._get_deps_array(optional=optional, group=group)
+
+        target = canonicalize_name(package_name)
+        filtered: list[str] = []
+        for existing in list(deps):
+            try:
+                existing_name = canonicalize_name(Requirement(str(existing)).name)
+            except Exception:
+                # Keep unparsable entries untouched
+                filtered.append(existing)
+                continue
+            if existing_name != target:
+                filtered.append(existing)
+
+        if len(filtered) != len(deps):
+            deps.clear()
+            deps.extend(filtered)
+            return True
+        return False
+
+    def find_package_workdir(self) -> CodeBaseWorkdir | None:
+        from wexample_wex_core.workdir.code_base_workdir import (
+            CodeBaseWorkdir,
+        )
+
+        return self.find_closest(CodeBaseWorkdir)
+
+    def dumps(self, content: TOMLDocument | dict | None = None) -> str:
+        """Serialize a TOMLDocument (preferred) or a plain dict to TOML.
+        Using tomlkit.dumps preserves comments/formatting when content is a TOMLDocument.
+        """
+        from tomlkit import dumps, table
+        from wexample_filestate_python.helpers.package import package_normalize_name
+        from wexample_filestate_python.helpers.toml import (
+            toml_ensure_array_multiline,
+            toml_ensure_table,
+            toml_get_string_value,
+            toml_set_array_multiline,
+            toml_sort_string_array,
+        )
+        from wexample_wex_addon_dev_python.const.package import (
+            RUNTIME_DEPENDENCY_REMOVE_NAMES,
+        )
+
+        # Obtain the current TOML document (preserving formatting) if not provided
+        content = content or self.read_parsed()
+
+        # Try to get current package/workdir context
+        package = self.find_package_workdir()
+        import_name: str | None = None
+        project_version: str | None = None
+        project_name: str | None = None
+        if package:
+            project_name = package.get_package_name()
+            project_version = package.get_project_version()
+            import_name = package.get_package_import_name()
+
+        # --- [build-system] enforcement ---
+        build_tbl = content.get("build-system") if isinstance(content, dict) else None
+        if not build_tbl or not isinstance(build_tbl, dict):
+            build_tbl = table()
+            content["build-system"] = build_tbl
+        desired_requires = ["pdm-backend"]
+        if build_tbl.get("requires") != desired_requires:
+            build_tbl["requires"] = desired_requires
+        if build_tbl.get("build-backend") != "pdm.backend":
+            build_tbl["build-backend"] = "pdm.backend"
+
+        # --- [tool.pdm.build] enforcement ---
+        tool_tbl, _ = toml_ensure_table(content, ["tool"])
+        pdm_tbl, _ = toml_ensure_table(tool_tbl, ["pdm"])
+        build_pdm_tbl, _ = toml_ensure_table(pdm_tbl, ["build"])
+        includes_arr, _ = toml_ensure_array_multiline(build_pdm_tbl, "includes")
+
+        pdm_tbl["distribution"] = True
+        # Enforce src layout, packages, and includes (py.typed)
+        if build_pdm_tbl.get("package-dir") != "src":
+            build_pdm_tbl["package-dir"] = "src"
+        if import_name:
+            desired_pkgs = [{"include": import_name, "from": "src"}]
+            if build_pdm_tbl.get("packages") != desired_pkgs:
+                build_pdm_tbl["packages"] = desired_pkgs
+            desired_includes = [f"src/{import_name}/*"]
+            current_includes = [str(x) for x in list(includes_arr)]
+            if current_includes != desired_includes:
+                toml_set_array_multiline(build_pdm_tbl, "includes", desired_includes)
+
+        # --- [project] table and basic fields ---
+        project_tbl, _ = toml_ensure_table(content, ["project"])
+        # Name sync (best-effort)
+        if project_name:
+            project_tbl["name"] = project_name
+        # Version sync (best-effort)
+        if project_version:
+            project_tbl["version"] = project_version
+        # Python requirement
+        target_requires_python = ">=3.10"
+        if project_tbl.get("requires-python") != target_requires_python:
+            project_tbl["requires-python"] = target_requires_python
+
+        # --- Dependencies normalization ---
+        # Use class helper to ensure multiline dependencies array
+        deps_arr = self._dependencies_array()
+        # Sort dependencies array
+        toml_sort_string_array(deps_arr)
+
+        # Optional dependency groups
+        opt_tbl, _ = toml_ensure_table(project_tbl, ["optional-dependencies"])
+        # Ensure dev group exists (multiline)
+        dev_arr = self._optional_group_array("dev")
+
+        # Filestate configuration for keep/exclude-add
+        filestate_tbl = None
+        if isinstance(tool_tbl, dict):
+            filestate_tbl = tool_tbl.get("filestate")
+        keep_names: set[str] = set()
+        exclude_add: set[str] = set()
+        if isinstance(filestate_tbl, dict):
+            keep_list = filestate_tbl.get("keep")
+            if isinstance(keep_list, list):
+                keep_names = {package_normalize_name(str(x)) for x in keep_list}
+            ex_list = filestate_tbl.get("exclude-add")
+            if isinstance(ex_list, list):
+                exclude_add = {str(x).strip().lower() for x in ex_list}
+
+        # Remove unwanted dev/build tools from runtime deps (unless kept)
+
+        def _should_remove(item: object) -> bool:
+            name = package_normalize_name(toml_get_string_value(item))
+            if name in keep_names:
+                return False
+            if name == "typing-extensions":
+                # Safe to drop when python >= 3.10 and we manage deps
+                return True
+            return name in RUNTIME_DEPENDENCY_REMOVE_NAMES
+
+        to_keep = []
+        for it in list(deps_arr):
+            if not _should_remove(it):
+                to_keep.append(it)
+        if len(to_keep) != len(deps_arr):
+            deps_arr.clear()
+            deps_arr.extend(to_keep)
+            toml_sort_string_array(deps_arr)
+
+        # Normalize any pydantic spec to pydantic>=2,<3
+        normalized = False
+        new_deps = []
+        for it in list(deps_arr):
+            val = toml_get_string_value(it).strip()
+            base = package_normalize_name(val)
+            if base == "pydantic":
+                new_deps.append("pydantic>=2,<3")
+                normalized = True
+            else:
+                new_deps.append(it)
+        if normalized:
+            deps_arr.clear()
+            deps_arr.extend(new_deps)
+            toml_sort_string_array(deps_arr)
+
+        # Ensure pydantic>=2,<3 present unless excluded
+        existing_norm = {
+            package_normalize_name(toml_get_string_value(it)) for it in list(deps_arr)
+        }
+        if "pydantic" not in exclude_add and "pydantic" not in existing_norm:
+            deps_arr.append("pydantic>=2,<3")
+            toml_sort_string_array(deps_arr)
+
+        # Ensure optional dev group contains pytest unless already in runtime deps
+        runtime_has_pytest = any(
+            package_normalize_name(toml_get_string_value(it)) == "pytest"
+            for it in list(deps_arr)
+        )
+        dev_values = [toml_get_string_value(it) for it in list(dev_arr)]
+        if not runtime_has_pytest and not any(
+            v.strip() == "pytest" for v in dev_values
+        ):
+            dev_arr.append("pytest")
+            toml_sort_string_array(dev_arr)
+
+        return dumps(content)

wexample_wex_addon_dev_python/middleware/each_python_file_middleware.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import os.path
+from typing import TYPE_CHECKING
+
+from wexample_wex_core.middleware.each_file_middleware import EachFileMiddleware
+
+if TYPE_CHECKING:
+    from wexample_wex_core.common.command_request import CommandRequest
+
+
+class EachPythonFileMiddleware(EachFileMiddleware):
+    """
+    Middleware for processing Python files only.
+    - Filters files by .py extension by default
+    - Ignores special directories like __pycache__ during recursion
+    """
+
+    # Default extension to filter
+    python_extension_only: bool = True
+
+    # Default list of directories to ignore during recursion
+    ignored_directories: set[str] = {
+        "__pycache__",
+        ".git",
+        ".idea",
+        ".vscode",
+        "venv",
+        "env",
+        "node_modules",
+        ".pytest_cache",
+        ".mypy_cache",
+        ".ruff_cache",
+    }
+
+    def __init__(self, **kwargs) -> None:
+        # Allow overriding the default settings
+        if "python_extension_only" in kwargs:
+            self.python_extension_only = kwargs.pop("python_extension_only")
+
+        if "ignored_directories" in kwargs:
+            self.ignored_directories = set(kwargs.pop("ignored_directories"))
+
+        super().__init__(**kwargs)
+
+    def _should_process_item(self, request: CommandRequest, item_path: str) -> bool:
+        """
+        Only process Python files based on extension.
+
+        Args:
+            item_path: Path to the item to check
+
+        Returns:
+            True if the item should be processed, False otherwise
+        """
+        # First check if it's a file (parent class behavior)
+        if not os.path.isfile(item_path):
+            return False
+
+        # If python_extension_only is enabled, check file extension
+        if self.python_extension_only:
+            return item_path.endswith(".py")
+
+        # Otherwise, accept all files
+        return True
+
+    def _should_explore_directory(
+        self, request: CommandRequest, directory_name: str
+    ) -> bool:
+        """
+        Skip directories that are in the ignored_directories list.
+
+        Args:
+            directory_name: Name of the directory to check
+
+        Returns:
+            False if the directory is in the ignored list, True otherwise
+        """
+        return directory_name not in self.ignored_directories

wexample_wex_addon_dev_python/python_addon_manager.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from wexample_wex_core.common.abstract_addon_manager import AbstractAddonManager
+from wexample_wex_core.middleware.abstract_middleware import AbstractMiddleware
+
+
+class PythonAddonManager(AbstractAddonManager):
+    def get_middlewares_classes(self) -> list[type[AbstractMiddleware]]:
+        from wexample_wex_addon_dev_python.middleware.each_python_file_middleware import (
+            EachPythonFileMiddleware,
+        )
+
+        return [
+            EachPythonFileMiddleware,
+        ]