simplibs-extractor-python 0.1.0__py3-none-any.whl

simplibs/extractor_python/logic/remove_python_imports.py

@@ -0,0 +1,48 @@
+from simplibs.validate import validate_call
+# Outers
+from ..annotations import OnError
+# Inners
+from ._helpers import SourceOffsets, cut_statements, find_imports, parse_python
+
+
+@validate_call
+def remove_python_imports(text: str, *, on_error: OnError = "raise") -> str:
+    """Remove the import statements of a Python source, at any depth.
+
+    Args:
+        text: The Python source.
+        on_error: `"raise"` for a card when the text cannot be parsed, `"keep"` to return it unchanged.
+
+    Returns:
+        The text without imports. A body left empty gets a `pass`; `import a; x = 1` keeps `x = 1`.
+
+    Raises:
+        ParamError: The text cannot be parsed and `on_error` is `"raise"`.
+    """
+
+    # 1. Parse; a text that could not be read is not touched
+    tree = parse_python(text, on_error)
+    if tree is None:
+        return text
+
+    # 2. Cut the import statements
+    return cut_statements(text, tree, find_imports(tree), SourceOffsets(text))
+
+
+_DESIGN_NOTES = """
+# remove_python_imports — The Logic Without Its Dependencies
+
+## Purpose
+A step of the profile `python/code-no-imports`.
+
+## Guarantee
+For a text that parses, the syntax tree of the result equals the tree of the
+original without the `Import` and `ImportFrom` statements (and a `Pass` where a
+body would be empty).
+
+## What Is Left Behind
+Names that were imported are still used further down; the reader of the
+output sees code that refers to `Path` or `np` without the line that says
+where they come from. That is what the profile is for: the logic, not the
+wiring.
+"""

simplibs/extractor_python/plugin/__init__.py

@@ -0,0 +1,14 @@
+from .register_all import register_all
+
+
+_DESIGN_NOTES = """
+# plugin — The Meeting Point With the Extractor
+
+Plain imports, no `__all__`.
+
+## Internal Components Registry
+
+| Component      | Type     | Description                                           |
+| :------------- | :------- | :---------------------------------------------------- |
+| `register_all` | Function | Registers the profiles; the target of the entry point. |
+"""

simplibs/extractor_python/plugin/register_all.py

@@ -0,0 +1,45 @@
+from simplibs.extractor import register_profile
+from simplibs.validate import validate_call
+# Outers
+from ..profiles import PYTHON_PROFILES
+
+
+@validate_call
+def register_all(*, replace_existing: bool = True) -> list[str]:
+    """Register every profile of this library in the registry of the extractor.
+
+    The extractor calls it, with no arguments, for every installed add-on
+    (entry-point group `simplibs.extractor.plugins`).
+
+    Args:
+        replace_existing: Replace a profile that already has the key (the default, so calling it twice changes nothing).
+
+    Returns:
+        The keys of the registered profiles (`"python/code-clean"`...).
+
+    Raises:
+        StateError: A key is taken and `replace_existing` is `False`.
+    """
+
+    # 1. Register each profile
+    keys: list[str] = []
+    for profile in PYTHON_PROFILES:
+        registered = register_profile(profile, replace_existing=replace_existing)
+        keys.append(registered.key)
+
+    return keys
+
+
+_DESIGN_NOTES = """
+# register_all — What the Entry Point Calls
+
+## Purpose
+`pip install simplibs-extractor-python` is the whole installation: the entry
+point `python = "simplibs.extractor_python:register_all"` makes the extractor
+find this function, and the five profiles appear in `--list-systems`.
+
+## The Rules of an Add-On Function
+It takes no required argument, registers with `replace_existing=True`, only
+registers (no scanning, no network, no printing) and uses only the public API
+of the extractor (`Profile`, `register_profile`).
+"""

simplibs/extractor_python/presets/PYTHON_CLEAN.py

@@ -0,0 +1,29 @@
+from typing import Final
+from simplibs.text.presets import CLEANUP_WHITESPACE
+# Outers
+from ..actions import RemovePythonComments, RemovePythonDocstrings
+
+
+PYTHON_CLEAN: Final = (
+    RemovePythonComments()
+    >> RemovePythonDocstrings()
+    >> CLEANUP_WHITESPACE
+)
+"""Python without comments and docstrings, whitespace tidied: the imports stay."""
+
+
+_DESIGN_NOTES = """
+# PYTHON_CLEAN — The Everyday Clean Read
+
+## Purpose
+The steps of `python/code-clean` and `python/src-clean` as one object, built once.
+
+## Order
+Comments first, then docstrings (both find their targets in the original
+structure), whitespace last, to tidy the holes the first two left.
+
+## The Whitespace Step
+`CLEANUP_WHITESPACE` squeezes blank runs to one line; it does not remove them.
+Code stays in paragraphs a person can read. See `PYTHON_NO_IMPORTS` for the
+compact form.
+"""

simplibs/extractor_python/presets/PYTHON_NO_IMPORTS.py

@@ -0,0 +1,32 @@
+from typing import Final
+from simplibs.text.presets import COMPACT
+# Outers
+from ..actions import (
+    RemovePythonComments,
+    RemovePythonDecorators,
+    RemovePythonDocstrings,
+    RemovePythonImports,
+)
+
+
+PYTHON_NO_IMPORTS: Final = (
+    RemovePythonComments()
+    >> RemovePythonDocstrings()
+    >> RemovePythonImports()
+    >> RemovePythonDecorators()
+    >> COMPACT
+)
+"""Python reduced to its logic: no comments, docstrings, imports or decorators, and no blank lines."""
+
+
+_DESIGN_NOTES = """
+# PYTHON_NO_IMPORTS — The Logic and Nothing Else
+
+## Purpose
+The steps of `python/code-no-imports`.
+
+## Compact, Not Tidy
+`COMPACT` removes every blank line, also those inside multi-line strings. This is
+the shortest form, meant for a reader (or a model) that needs the code and
+not its layout.
+"""

simplibs/extractor_python/presets/__init__.py

@@ -0,0 +1,30 @@
+from .PYTHON_CLEAN import PYTHON_CLEAN
+from .PYTHON_NO_IMPORTS import PYTHON_NO_IMPORTS
+
+
+__all__ = [
+    "PYTHON_CLEAN",
+    "PYTHON_NO_IMPORTS",
+]
+
+
+_DESIGN_NOTES = """
+# simplibs.extractor_python.presets — Ready-Made Pipeline Steps
+
+## Purpose
+Chains of actions that the profiles use, built once.
+
+    from simplibs.extractor_python.presets import PYTHON_CLEAN
+    steps = PYTHON_CLEAN
+
+## Domain Folder
+`presets/` has its own `__all__` and is not re-exported from the package root.
+It stands to the right of `actions` (it uses them) and to the left of `profiles`.
+
+## Internal Components Registry
+
+| Component           | Type   | Description                                                |
+| :------------------ | :----- | :--------------------------------------------------------- |
+| `PYTHON_CLEAN`      | Preset | Python without comments and docstrings, whitespace tidied. |
+| `PYTHON_NO_IMPORTS` | Preset | Python logic only, compact.                                |
+"""

simplibs/extractor_python/profiles/PYTHON_CODE_CLEAN.py

@@ -0,0 +1,29 @@
+from typing import Final
+from simplibs.extractor import Profile, by_suffix
+# Outers
+from ..constants import PYTHON_SUFFIXES
+from ..file_rules import PYTHON_BASE
+from ..presets import PYTHON_CLEAN
+
+
+PYTHON_CODE_CLEAN: Final[Profile] = Profile(
+    system="python",
+    name="code-clean",
+    description="Python without comments, docstrings and extra blank lines (imports stay)",
+    include=PYTHON_BASE,
+    steps=by_suffix(PYTHON_CLEAN, PYTHON_SUFFIXES),
+    output_name="python_code_clean.md",
+)
+"""The profile `python/code-clean`."""
+
+
+_DESIGN_NOTES = """
+# PYTHON_CODE_CLEAN — `python/code-clean`
+
+## Purpose
+The old `PYTHON_CODE_CLEAN`: the code with its prose taken away.
+
+## Output
+`python_code_clean.md`. A file that is not valid Python makes THAT file an
+`error` in the report; the others are not affected.
+"""

simplibs/extractor_python/profiles/PYTHON_CODE_NO_IMPORTS.py

@@ -0,0 +1,29 @@
+from typing import Final
+from simplibs.extractor import Profile, by_suffix
+# Outers
+from ..constants import PYTHON_SUFFIXES
+from ..file_rules import PYTHON_BASE
+from ..presets import PYTHON_NO_IMPORTS
+
+
+PYTHON_CODE_NO_IMPORTS: Final[Profile] = Profile(
+    system="python",
+    name="code-no-imports",
+    description="Pure logic: no imports, decorators, comments, docstrings or blank lines",
+    include=PYTHON_BASE,
+    steps=by_suffix(PYTHON_NO_IMPORTS, PYTHON_SUFFIXES),
+    output_name="python_code_no_imports.md",
+)
+"""The profile `python/code-no-imports`."""
+
+
+_DESIGN_NOTES = """
+# PYTHON_CODE_NO_IMPORTS — `python/code-no-imports`
+
+## Purpose
+The old `PYTHON_CODE_CLEAN_NO_IMPORTS`: what the code does, not what it is
+wired to.
+
+## Output
+`python_code_no_imports.md`.
+"""

simplibs/extractor_python/profiles/PYTHON_DATA_ALL.py

@@ -0,0 +1,26 @@
+from typing import Final
+from simplibs.extractor import Profile
+# Outers
+from ..file_rules import PYTHON_BASE
+
+
+PYTHON_DATA_ALL: Final[Profile] = Profile(
+    system="python",
+    name="data-all",
+    description="Every relevant .py file, as it is",
+    include=PYTHON_BASE,
+    output_name="python_data_all.md",
+)
+"""The profile `python/data-all`."""
+
+
+_DESIGN_NOTES = """
+# PYTHON_DATA_ALL — `python/data-all`
+
+## Purpose
+The old `PYTHON_DATA_ALL`: the files selected by `PYTHON_BASE` and no
+transformation. A file that is not valid Python cannot fail here.
+
+## Output
+`python_data_all.md`.
+"""

simplibs/extractor_python/profiles/PYTHON_OUTLINE.py

@@ -0,0 +1,30 @@
+from typing import Final
+from simplibs.extractor import Profile, by_suffix
+# Outers
+from ..actions import PythonOutline
+from ..constants import PYTHON_SUFFIXES
+from ..file_rules import PYTHON_BASE
+
+
+PYTHON_OUTLINE: Final[Profile] = Profile(
+    system="python",
+    name="outline",
+    description="Overview of classes and functions: signatures without bodies",
+    include=PYTHON_BASE,
+    steps=by_suffix(PythonOutline(), PYTHON_SUFFIXES),
+    output_name="python_outline.md",
+)
+"""The profile `python/outline`."""
+
+
+_DESIGN_NOTES = """
+# PYTHON_OUTLINE — `python/outline`
+
+## Purpose
+New, not in the old code: what a project offers, in a fraction of the size.
+For a reader with a limited window the signatures are most of what is needed
+to ask the right questions.
+
+## Output
+`python_outline.md`; each file is valid Python again.
+"""

simplibs/extractor_python/profiles/PYTHON_PROFILES.py

@@ -0,0 +1,26 @@
+from typing import Final
+from simplibs.extractor import Profile
+# Inners
+from .PYTHON_CODE_CLEAN import PYTHON_CODE_CLEAN
+from .PYTHON_CODE_NO_IMPORTS import PYTHON_CODE_NO_IMPORTS
+from .PYTHON_DATA_ALL import PYTHON_DATA_ALL
+from .PYTHON_OUTLINE import PYTHON_OUTLINE
+from .PYTHON_SRC_CLEAN import PYTHON_SRC_CLEAN
+
+
+PYTHON_PROFILES: Final[tuple[Profile, ...]] = (
+    PYTHON_CODE_CLEAN,
+    PYTHON_CODE_NO_IMPORTS,
+    PYTHON_DATA_ALL,
+    PYTHON_OUTLINE,
+    PYTHON_SRC_CLEAN,
+)
+"""The profiles of the system `python`."""
+
+
+_DESIGN_NOTES = """
+# PYTHON_PROFILES — The `python` System
+
+## Purpose
+The profiles of one system in the order the listing commands show them.
+"""

simplibs/extractor_python/profiles/PYTHON_SRC_CLEAN.py

@@ -0,0 +1,30 @@
+from typing import Final
+from simplibs.extractor import Profile, by_suffix
+# Outers
+from ..constants import PYTHON_SUFFIXES
+from ..file_rules import PYTHON_BASE, PYTHON_STRICT_EXCLUDE
+from ..presets import PYTHON_CLEAN
+
+
+PYTHON_SRC_CLEAN: Final[Profile] = Profile(
+    system="python",
+    name="src-clean",
+    description="Like code-clean, without tests, configuration, environments and build folders",
+    include=PYTHON_BASE,
+    exclude=PYTHON_STRICT_EXCLUDE,
+    steps=by_suffix(PYTHON_CLEAN, PYTHON_SUFFIXES),
+    output_name="python_src_clean.md",
+)
+"""The profile `python/src-clean`."""
+
+
+_DESIGN_NOTES = """
+# PYTHON_SRC_CLEAN — `python/src-clean`
+
+## Purpose
+The old strict file filter made visible: the old code defined it and no profile
+ever used it. Only what the project does.
+
+## Output
+`python_src_clean.md`.
+"""

simplibs/extractor_python/profiles/__init__.py

@@ -0,0 +1,47 @@
+from .PYTHON_CODE_CLEAN import PYTHON_CODE_CLEAN
+from .PYTHON_CODE_NO_IMPORTS import PYTHON_CODE_NO_IMPORTS
+from .PYTHON_DATA_ALL import PYTHON_DATA_ALL
+from .PYTHON_OUTLINE import PYTHON_OUTLINE
+from .PYTHON_PROFILES import PYTHON_PROFILES
+from .PYTHON_SRC_CLEAN import PYTHON_SRC_CLEAN
+
+
+__all__ = [
+    "PYTHON_CODE_CLEAN",
+    "PYTHON_CODE_NO_IMPORTS",
+    "PYTHON_DATA_ALL",
+    "PYTHON_OUTLINE",
+    "PYTHON_PROFILES",
+    "PYTHON_SRC_CLEAN",
+]
+
+
+_DESIGN_NOTES = """
+# simplibs.extractor_python.profiles — The Profiles Themselves
+
+## Purpose
+The five profiles as `Profile` objects of the extractor. Registering them is
+the job of `register_all`; having them as objects lets a program use one
+directly or build its own on top of it.
+
+    from simplibs.extractor_python.profiles import PYTHON_SRC_CLEAN
+    from dataclasses import replace
+    mine = replace(PYTHON_SRC_CLEAN, name="mine", output_name="mine.md")
+
+## Domain Folder
+`profiles/` has its own `__all__` and is not re-exported from the package root.
+
+## Internal Components Registry
+
+| Component                | Type    | Description                                              |
+| :----------------------- | :------ | :------------------------------------------------------- |
+| `PYTHON_CODE_CLEAN`      | Profile | `python/code-clean`: comments and docstrings removed.    |
+| `PYTHON_CODE_NO_IMPORTS` | Profile | `python/code-no-imports`: the logic only.                |
+| `PYTHON_DATA_ALL`        | Profile | `python/data-all`: every Python file as it is.           |
+| `PYTHON_OUTLINE`         | Profile | `python/outline`: signatures without bodies.             |
+| `PYTHON_PROFILES`        | Tuple   | All five profiles, in the order the listings show them.  |
+| `PYTHON_SRC_CLEAN`       | Profile | `python/src-clean`: the project's own logic, cleaned.    |
+
+## Layering & Design
+- `by_suffix` (one step for a family of file types) is a tool of `simplibs-extractor`.
+"""

simplibs/extractor_python/py.typed

@@ -0,0 +1 @@
+