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

simplibs/extractor_html/profiles/__init__.py

@@ -0,0 +1,86 @@
+from .DJANGO_CLEAN import DJANGO_CLEAN
+from .DJANGO_NO_IMPORTS import DJANGO_NO_IMPORTS
+from .DJANGO_OUTLINE import DJANGO_OUTLINE
+from .DJANGO_STRUCTURE import DJANGO_STRUCTURE
+from .HTML_CODE_CLEAN import HTML_CODE_CLEAN
+from .HTML_CODE_NO_IMPORTS import HTML_CODE_NO_IMPORTS
+from .HTML_DATA_ALL import HTML_DATA_ALL
+from .HTML_OUTLINE import HTML_OUTLINE
+from .HTML_PROFILES import HTML_PROFILES
+from .HTML_SRC_CLEAN import HTML_SRC_CLEAN
+from .JINJA_CLEAN import JINJA_CLEAN
+from .JINJA_NO_IMPORTS import JINJA_NO_IMPORTS
+from .JINJA_OUTLINE import JINJA_OUTLINE
+from .JINJA_STRUCTURE import JINJA_STRUCTURE
+
+
+__all__ = [
+    "DJANGO_CLEAN",
+    "DJANGO_NO_IMPORTS",
+    "DJANGO_OUTLINE",
+    "DJANGO_STRUCTURE",
+    "HTML_CODE_CLEAN",
+    "HTML_CODE_NO_IMPORTS",
+    "HTML_DATA_ALL",
+    "HTML_OUTLINE",
+    "HTML_PROFILES",
+    "HTML_SRC_CLEAN",
+    "JINJA_CLEAN",
+    "JINJA_NO_IMPORTS",
+    "JINJA_OUTLINE",
+    "JINJA_STRUCTURE",
+]
+
+
+_DESIGN_NOTES = """
+# simplibs.extractor_html.profiles — The Profiles Themselves
+
+## Purpose
+The thirteen 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_html.profiles import DJANGO_CLEAN
+    from dataclasses import replace
+    mine = replace(DJANGO_CLEAN, name="mine", output_name="mine.md")
+
+## Domain Folder
+`profiles/` has its own `__all__` and is not re-exported from the package root.
+
+## Three Families
+* **Pages** (`code-clean`, `code-no-imports`, `data-all`, `src-clean`, `outline`):
+  `.html` is read as a page without an engine, the suffixes of the Jinja family
+  as Jinja.
+* **Django** (`django-clean`, `django-no-imports`, `django-outline`,
+  `django-structure`): every `.html` file is read as a Django template.
+* **Jinja** (`jinja-clean`, `jinja-no-imports`, `jinja-outline`,
+  `jinja-structure`): every page and template suffix is read as Jinja.
+
+The profiles named after an engine are strict: they leave out packages and
+generated output.
+
+## Internal Components Registry
+
+| Component             | Type    | Description                                                             |
+| :-------------------- | :------ | :---------------------------------------------------------------------- |
+| `DJANGO_CLEAN`        | Profile | `html/django-clean`.                                                    |
+| `DJANGO_NO_IMPORTS`   | Profile | `html/django-no-imports`.                                               |
+| `DJANGO_OUTLINE`      | Profile | `html/django-outline`.                                                  |
+| `DJANGO_STRUCTURE`    | Profile | `html/django-structure`.                                                |
+| `HTML_CODE_CLEAN`     | Profile | `html/code-clean`.                                                      |
+| `HTML_CODE_NO_IMPORTS`| Profile | `html/code-no-imports`.                                                 |
+| `HTML_DATA_ALL`       | Profile | `html/data-all`.                                                        |
+| `HTML_OUTLINE`        | Profile | `html/outline`.                                                         |
+| `HTML_PROFILES`       | Tuple   | All thirteen profiles, in the order the listings show them.             |
+| `HTML_SRC_CLEAN`      | Profile | `html/src-clean`.                                                       |
+| `JINJA_CLEAN`         | Profile | `html/jinja-clean`.                                                     |
+| `JINJA_NO_IMPORTS`    | Profile | `html/jinja-no-imports`.                                                |
+| `JINJA_OUTLINE`       | Profile | `html/jinja-outline`.                                                   |
+| `JINJA_STRUCTURE`     | Profile | `html/jinja-structure`.                                                 |
+| `steps_for_engine`    | Module  | Private: the steps of a project written for one engine.                 |
+| `steps_for_pages`     | Module  | Private: the engine chosen by the suffix.                               |
+
+## Layering & Design
+- `by_suffix` (one step for a family of file types) is a tool of `simplibs-extractor`.
+- The steps for the code inside a page come from the add-ons of its languages.
+"""

simplibs/extractor_html/profiles/steps_for_engine.py

@@ -0,0 +1,39 @@
+from collections.abc import Callable
+from simplibs.actions import Action
+from simplibs.extractor import by_suffix
+# Outers
+from ..annotations import TemplateEngine
+from ..constants import HTML_PLAIN_SUFFIXES, HTML_SUFFIXES
+
+
+def steps_for_engine(make: Callable[[TemplateEngine], Action], engine: TemplateEngine) -> dict[str, Action]:
+    """Give every suffix of a project written for one engine the steps of that engine.
+
+    Args:
+        make: A function from the engine to the steps (`html_clean_steps`...).
+        engine: `"django"` or `"jinja"`.
+
+    Returns:
+        A mapping `suffix -> step`, the form of `Profile.steps` that chooses by file type.
+    """
+
+    # 1. A Django project keeps its templates in `.html` files; a Jinja project may use every suffix
+    suffixes = HTML_PLAIN_SUFFIXES if engine == "django" else HTML_SUFFIXES
+    return by_suffix(make(engine), suffixes)
+
+
+_DESIGN_NOTES = """
+# steps_for_engine — A Project of One Engine
+
+## Purpose
+The profiles named after an engine (`django-clean`, `jinja-outline`...) say
+which engine every file is written for, so each suffix gets the same engine.
+
+## Which Suffixes
+Django reads `.html`, `.htm` and `.xhtml`. Jinja (and Nunjucks) also have
+suffixes of their own, and a Jinja project may keep its pages in `.html` or in
+those, so all of them are taken.
+
+## Not Exported
+A tool of the profiles' own: it is not in `__all__` of the folder.
+"""

simplibs/extractor_html/profiles/steps_for_pages.py

@@ -0,0 +1,36 @@
+from collections.abc import Callable
+from simplibs.actions import Action
+from simplibs.extractor import by_suffix
+# Outers
+from ..annotations import TemplateEngine
+from ..constants import HTML_PLAIN_SUFFIXES, HTML_TEMPLATE_SUFFIXES, HTML_WRAPPED_SUFFIXES
+
+
+def steps_for_pages(make: Callable[[TemplateEngine | None], Action]) -> dict[str, Action]:
+    """Give each kind of page its own steps: HTML as HTML, and the Jinja suffixes as Jinja.
+
+    Args:
+        make: A function from the engine to the steps (`html_clean_steps`...).
+
+    Returns:
+        A mapping `suffix -> step`, the form of `Profile.steps` that chooses by file type.
+    """
+
+    # 1. `.html` and the like are pages; the suffixes of the Jinja family say what the engine is
+    return {
+        **by_suffix(make(None), HTML_PLAIN_SUFFIXES),
+        **by_suffix(make("jinja"), HTML_TEMPLATE_SUFFIXES + HTML_WRAPPED_SUFFIXES),
+    }
+
+
+_DESIGN_NOTES = """
+# steps_for_pages — The Engine Is Chosen by the Suffix
+
+## Purpose
+The profiles without an engine in their name read `.html` as a page that is
+only HTML, because a `.html` file can be written for any engine or for none,
+and a suffix of the Jinja family leaves no doubt.
+
+## Not Exported
+A tool of the profiles' own: it is not in `__all__` of the folder.
+"""

simplibs/extractor_html/py.typed

@@ -0,0 +1 @@
+