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

simplibs/extractor_html/presets/html_clean_steps.py

@@ -0,0 +1,54 @@
+from simplibs.actions import Action
+from simplibs.extractor_css.presets import CSS_PLAIN_CLEAN
+from simplibs.extractor_javascript.presets import JS_CLEAN
+# Outers
+from ..actions import ApplyToHtmlBlocks, CleanupHtmlWhitespace, StripHtmlComments, StripTemplateComments
+from ..annotations import TemplateEngine
+
+
+def html_clean_steps(engine: TemplateEngine | None) -> Action:
+    """Build the steps that clean a page: the comments out, the code inside it cleaned, the whitespace tidied.
+
+    Args:
+        engine: The template language of the page; `None` for a page that is only HTML.
+
+    Returns:
+        The pipeline. Imports stay.
+    """
+
+    # 1. The comments of the page, and for a template its own comments as well
+    steps = StripHtmlComments(engine=engine)
+    if engine is not None:
+        steps = steps >> StripTemplateComments(engine=engine)
+
+    # 2. The code inside the page, then the page itself
+    return (
+        steps
+        >> ApplyToHtmlBlocks(script=JS_CLEAN, style=CSS_PLAIN_CLEAN, engine=engine)
+        >> CleanupHtmlWhitespace(engine=engine)
+    )
+
+
+_DESIGN_NOTES = """
+# html_clean_steps — The Everyday Clean Read of a Page
+
+## Purpose
+The steps of the profiles that clean pages and templates, for one engine.
+
+## Order
+1. The comments of the page, then the comments of the template: a template
+   comment inside an HTML comment is gone with it, and an HTML comment inside
+   a template comment is gone with that.
+2. The code inside the page. It comes after the comments, so a `{# note #}`
+   inside a `<script>` is not left for the JavaScript step to see.
+3. The whitespace of the page, last, as the steps before it leave blank lines.
+
+## Why a Function and Not a Constant
+A preset of the other add-ons is built once. Here it differs only in the
+engine, and three constants that differ in one argument would say the same
+thing three times.
+
+## The Code Inside
+The JavaScript is cleaned by `JS_CLEAN` of `simplibs-extractor-javascript`, the
+CSS by `CSS_PLAIN_CLEAN` of `simplibs-extractor-css`: a `<style>` is plain CSS.
+"""

simplibs/extractor_html/presets/html_no_imports_steps.py

@@ -0,0 +1,50 @@
+from simplibs.actions import Action
+from simplibs.extractor_css.presets import CSS_PLAIN_NO_IMPORTS
+from simplibs.extractor_javascript.presets import JS_NO_IMPORTS
+# Outers
+from ..actions import (
+    ApplyToHtmlBlocks,
+    CompactHtml,
+    RemoveTemplateImports,
+    StripHtmlComments,
+    StripTemplateComments,
+)
+from ..annotations import TemplateEngine
+
+
+def html_no_imports_steps(engine: TemplateEngine | None) -> Action:
+    """Build the steps that reduce a page to its content: no comments, no imports, no blank lines.
+
+    Args:
+        engine: The template language of the page; `None` for a page that is only HTML.
+
+    Returns:
+        The pipeline.
+    """
+
+    # 1. The comments of the page, and for a template its own comments and its imports
+    steps = StripHtmlComments(engine=engine)
+    if engine is not None:
+        steps = steps >> StripTemplateComments(engine=engine) >> RemoveTemplateImports(engine=engine)
+
+    # 2. The code inside the page without its imports, then the page itself without blank lines
+    return (
+        steps
+        >> ApplyToHtmlBlocks(script=JS_NO_IMPORTS, style=CSS_PLAIN_NO_IMPORTS, engine=engine)
+        >> CompactHtml(engine=engine)
+    )
+
+
+_DESIGN_NOTES = """
+# html_no_imports_steps — The Page and Nothing Around It
+
+## Purpose
+The steps of the profiles without imports. A page itself has no imports; what
+it has is the code inside it (`import` in a module script, `@import` in a
+style) and, for a template, the tags that bring in names (`{% load %}`,
+`{% import %}`). All of them go.
+
+## Order
+The same as for the clean steps: comments first, then the imports of the
+template, then the code inside the page, and the blank lines last.
+"""

simplibs/extractor_html/presets/html_outline_steps.py

@@ -0,0 +1,28 @@
+from simplibs.actions import Action
+# Outers
+from ..actions import HtmlOutline
+from ..annotations import TemplateEngine
+
+
+def html_outline_steps(engine: TemplateEngine | None) -> Action:
+    """Build the step that gives an overview of a page.
+
+    Args:
+        engine: The template language of the page; `None` for a page that is only HTML.
+
+    Returns:
+        The step.
+    """
+
+    # 1. One action; the engine only tells it how to read the page
+    return HtmlOutline(engine=engine)
+
+
+_DESIGN_NOTES = """
+# html_outline_steps — What a Page Is Made Of
+
+## Purpose
+The step of the profiles with an overview of the page. A single action, and a
+preset all the same: every profile asks for its steps by the engine, in the
+same way.
+"""

simplibs/extractor_html/presets/template_structure_steps.py

@@ -0,0 +1,27 @@
+from simplibs.actions import Action
+# Outers
+from ..actions import TemplateOutline
+from ..annotations import TemplateEngine
+
+
+def template_structure_steps(engine: TemplateEngine) -> Action:
+    """Build the step that gives the skeleton of a template: its `extends`, `include` and blocks.
+
+    Args:
+        engine: `"django"` or `"jinja"`.
+
+    Returns:
+        The step.
+    """
+
+    # 1. One action; a template cannot be read without knowing its engine
+    return TemplateOutline(engine=engine)
+
+
+_DESIGN_NOTES = """
+# template_structure_steps — What a Template Is Built Of
+
+## Purpose
+The step of the profiles with the skeleton of a template. The engine is
+required, as in the action.
+"""

simplibs/extractor_html/profiles/DJANGO_CLEAN.py

@@ -0,0 +1,36 @@
+from typing import Final
+from simplibs.extractor import Profile
+# Outers
+from ..file_rules import HTML_PLAIN_BASE, HTML_STRICT_EXCLUDE
+from ..presets import html_clean_steps
+# Inners
+from .steps_for_engine import steps_for_engine
+
+
+DJANGO_CLEAN: Final[Profile] = Profile(
+    system="html",
+    name="django-clean",
+    description="Django templates without HTML and template comments and extra blank lines (imports stay)",
+    include=HTML_PLAIN_BASE,
+    exclude=HTML_STRICT_EXCLUDE,
+    steps=steps_for_engine(html_clean_steps, "django"),
+    output_name="html_django_clean.md",
+)
+"""The profile `html/django-clean`."""
+
+
+_DESIGN_NOTES = """
+# DJANGO_CLEAN — `html/django-clean`
+
+## Purpose
+The templates of a Django project, read as templates: `{# #}` and
+`{% comment %}` go with the HTML comments, and `{% if a > b %}` or `{{ x }}`
+inside a tag cannot confuse the reading of the page.
+
+## Strict
+It leaves out packages and generated output (`staticfiles` among them), as a
+project of templates has no reason to read them.
+
+## Output
+`html_django_clean.md`.
+"""

simplibs/extractor_html/profiles/DJANGO_NO_IMPORTS.py

@@ -0,0 +1,32 @@
+from typing import Final
+from simplibs.extractor import Profile
+# Outers
+from ..file_rules import HTML_PLAIN_BASE, HTML_STRICT_EXCLUDE
+from ..presets import html_no_imports_steps
+# Inners
+from .steps_for_engine import steps_for_engine
+
+
+DJANGO_NO_IMPORTS: Final[Profile] = Profile(
+    system="html",
+    name="django-no-imports",
+    description="Django templates reduced to their content: no comments, {% load %}, imports in script and style, or blank lines",
+    include=HTML_PLAIN_BASE,
+    exclude=HTML_STRICT_EXCLUDE,
+    steps=steps_for_engine(html_no_imports_steps, "django"),
+    output_name="html_django_no_imports.md",
+)
+"""The profile `html/django-no-imports`."""
+
+
+_DESIGN_NOTES = """
+# DJANGO_NO_IMPORTS — `html/django-no-imports`
+
+## Purpose
+The Django templates without what only says where names come from: the
+`{% load %}` tags and the imports of the code inside. `{% extends %}` and
+`{% include %}` stay: they say what a page is made of.
+
+## Output
+`html_django_no_imports.md`.
+"""

simplibs/extractor_html/profiles/DJANGO_OUTLINE.py

@@ -0,0 +1,32 @@
+from typing import Final
+from simplibs.extractor import Profile
+# Outers
+from ..file_rules import HTML_PLAIN_BASE, HTML_STRICT_EXCLUDE
+from ..presets import html_outline_steps
+# Inners
+from .steps_for_engine import steps_for_engine
+
+
+DJANGO_OUTLINE: Final[Profile] = Profile(
+    system="html",
+    name="django-outline",
+    description="Overview of Django templates as pages: landmarks, headings and every element with an id",
+    include=HTML_PLAIN_BASE,
+    exclude=HTML_STRICT_EXCLUDE,
+    steps=steps_for_engine(html_outline_steps, "django"),
+    output_name="html_django_outline.md",
+)
+"""The profile `html/django-outline`."""
+
+
+_DESIGN_NOTES = """
+# DJANGO_OUTLINE — `html/django-outline`
+
+## Purpose
+The overview of the pages of a Django project, read as templates: an `id` or a
+heading that holds `{{ title }}` is written as it stands, and a condition with
+`>` inside a tag does not hide the rest of the page.
+
+## Output
+`html_django_outline.md`.
+"""

simplibs/extractor_html/profiles/DJANGO_STRUCTURE.py

@@ -0,0 +1,32 @@
+from typing import Final
+from simplibs.extractor import Profile
+# Outers
+from ..file_rules import HTML_PLAIN_BASE, HTML_STRICT_EXCLUDE
+from ..presets import template_structure_steps
+# Inners
+from .steps_for_engine import steps_for_engine
+
+
+DJANGO_STRUCTURE: Final[Profile] = Profile(
+    system="html",
+    name="django-structure",
+    description="Skeleton of Django templates: extends, include and blocks",
+    include=HTML_PLAIN_BASE,
+    exclude=HTML_STRICT_EXCLUDE,
+    steps=steps_for_engine(template_structure_steps, "django"),
+    output_name="html_django_structure.md",
+)
+"""The profile `html/django-structure`."""
+
+
+_DESIGN_NOTES = """
+# DJANGO_STRUCTURE — `html/django-structure`
+
+## Purpose
+How the templates of a Django project are put together: which one extends which,
+what they include and which blocks they define, in a few lines for each. A file
+with none of those tags gives an empty section.
+
+## Output
+`html_django_structure.md`.
+"""

simplibs/extractor_html/profiles/HTML_CODE_CLEAN.py

@@ -0,0 +1,32 @@
+from typing import Final
+from simplibs.extractor import Profile
+# Outers
+from ..file_rules import HTML_BASE
+from ..presets import html_clean_steps
+# Inners
+from .steps_for_pages import steps_for_pages
+
+
+HTML_CODE_CLEAN: Final[Profile] = Profile(
+    system="html",
+    name="code-clean",
+    description="Pages without comments and extra blank lines, the code inside cleaned too (imports stay)",
+    include=HTML_BASE,
+    steps=steps_for_pages(html_clean_steps),
+    output_name="html_code_clean.md",
+)
+"""The profile `html/code-clean`."""
+
+
+_DESIGN_NOTES = """
+# HTML_CODE_CLEAN — `html/code-clean`
+
+## Purpose
+Every page of the project with the comments taken out and the whitespace
+tidied, as it is otherwise: the everyday way to give a page to a reader. The
+JavaScript and CSS inside it are cleaned by the steps of their own add-ons.
+
+## Output
+`html_code_clean.md`. `.html` is read as a page without a template engine, the
+suffixes of the Jinja family as Jinja.
+"""

simplibs/extractor_html/profiles/HTML_CODE_NO_IMPORTS.py

@@ -0,0 +1,30 @@
+from typing import Final
+from simplibs.extractor import Profile
+# Outers
+from ..file_rules import HTML_BASE
+from ..presets import html_no_imports_steps
+# Inners
+from .steps_for_pages import steps_for_pages
+
+
+HTML_CODE_NO_IMPORTS: Final[Profile] = Profile(
+    system="html",
+    name="code-no-imports",
+    description="Pure content: no comments, imports (also inside script and style) or blank lines",
+    include=HTML_BASE,
+    steps=steps_for_pages(html_no_imports_steps),
+    output_name="html_code_no_imports.md",
+)
+"""The profile `html/code-no-imports`."""
+
+
+_DESIGN_NOTES = """
+# HTML_CODE_NO_IMPORTS — `html/code-no-imports`
+
+## Purpose
+The pages reduced to what they say: no comments, no imports of the code inside
+(and of the template, for a Jinja suffix), no blank lines.
+
+## Output
+`html_code_no_imports.md`.
+"""

simplibs/extractor_html/profiles/HTML_DATA_ALL.py

@@ -0,0 +1,26 @@
+from typing import Final
+from simplibs.extractor import Profile
+# Outers
+from ..file_rules import HTML_BASE
+
+
+HTML_DATA_ALL: Final[Profile] = Profile(
+    system="html",
+    name="data-all",
+    description="Every relevant page, as it is",
+    include=HTML_BASE,
+    output_name="html_data_all.md",
+)
+"""The profile `html/data-all`."""
+
+
+_DESIGN_NOTES = """
+# HTML_DATA_ALL — `html/data-all`
+
+## Purpose
+The files selected by `HTML_BASE`, untouched: comments, imports and generated
+pages included.
+
+## Output
+`html_data_all.md`.
+"""

simplibs/extractor_html/profiles/HTML_OUTLINE.py

@@ -0,0 +1,31 @@
+from typing import Final
+from simplibs.extractor import Profile
+# Outers
+from ..file_rules import HTML_BASE
+from ..presets import html_outline_steps
+# Inners
+from .steps_for_pages import steps_for_pages
+
+
+HTML_OUTLINE: Final[Profile] = Profile(
+    system="html",
+    name="outline",
+    description="Overview of the pages: landmarks, headings and every element with an id",
+    include=HTML_BASE,
+    steps=steps_for_pages(html_outline_steps),
+    output_name="html_outline.md",
+)
+"""The profile `html/outline`."""
+
+
+_DESIGN_NOTES = """
+# HTML_OUTLINE — `html/outline`
+
+## Purpose
+What a project's pages are made of, in a fraction of their size: for a reader
+with a limited window, the map of the pages.
+
+## Output
+`html_outline.md`; each file is a list of elements, one per line, indented by
+depth.
+"""

simplibs/extractor_html/profiles/HTML_PROFILES.py

@@ -0,0 +1,42 @@
+from typing import Final
+from simplibs.extractor import Profile
+# Inners
+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_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
+
+
+HTML_PROFILES: Final[tuple[Profile, ...]] = (
+    DJANGO_CLEAN,
+    DJANGO_NO_IMPORTS,
+    DJANGO_OUTLINE,
+    DJANGO_STRUCTURE,
+    HTML_CODE_CLEAN,
+    HTML_CODE_NO_IMPORTS,
+    HTML_DATA_ALL,
+    HTML_OUTLINE,
+    HTML_SRC_CLEAN,
+    JINJA_CLEAN,
+    JINJA_NO_IMPORTS,
+    JINJA_OUTLINE,
+    JINJA_STRUCTURE,
+)
+"""The profiles of the system `html`."""
+
+
+_DESIGN_NOTES = """
+# HTML_PROFILES — The `html` System
+
+## Purpose
+The profiles of one system in the order the listing commands show them.
+"""

simplibs/extractor_html/profiles/HTML_SRC_CLEAN.py

@@ -0,0 +1,31 @@
+from typing import Final
+from simplibs.extractor import Profile
+# Outers
+from ..file_rules import HTML_BASE, HTML_STRICT_EXCLUDE
+from ..presets import html_clean_steps
+# Inners
+from .steps_for_pages import steps_for_pages
+
+
+HTML_SRC_CLEAN: Final[Profile] = Profile(
+    system="html",
+    name="src-clean",
+    description="Like code-clean, without packages of other people and generated pages",
+    include=HTML_BASE,
+    exclude=HTML_STRICT_EXCLUDE,
+    steps=steps_for_pages(html_clean_steps),
+    output_name="html_src_clean.md",
+)
+"""The profile `html/src-clean`."""
+
+
+_DESIGN_NOTES = """
+# HTML_SRC_CLEAN — `html/src-clean`
+
+## Purpose
+Only the project's own pages, cleaned: no `node_modules` or `vendor`, no `dist`,
+`_build` or `staticfiles`, no coverage reports.
+
+## Output
+`html_src_clean.md`.
+"""

simplibs/extractor_html/profiles/JINJA_CLEAN.py

@@ -0,0 +1,35 @@
+from typing import Final
+from simplibs.extractor import Profile
+# Outers
+from ..file_rules import HTML_BASE, HTML_STRICT_EXCLUDE
+from ..presets import html_clean_steps
+# Inners
+from .steps_for_engine import steps_for_engine
+
+
+JINJA_CLEAN: Final[Profile] = Profile(
+    system="html",
+    name="jinja-clean",
+    description="Jinja templates without HTML and template comments and extra blank lines (imports stay)",
+    include=HTML_BASE,
+    exclude=HTML_STRICT_EXCLUDE,
+    steps=steps_for_engine(html_clean_steps, "jinja"),
+    output_name="html_jinja_clean.md",
+)
+"""The profile `html/jinja-clean`."""
+
+
+_DESIGN_NOTES = """
+# JINJA_CLEAN — `html/jinja-clean`
+
+## Purpose
+The templates of a Jinja (or Nunjucks) project, read as templates: `{# ... #}`,
+which may span lines, goes with the HTML comments, and `{% raw %}` is left
+alone.
+
+## Strict
+It leaves out packages and generated output.
+
+## Output
+`html_jinja_clean.md`.
+"""

simplibs/extractor_html/profiles/JINJA_NO_IMPORTS.py

@@ -0,0 +1,32 @@
+from typing import Final
+from simplibs.extractor import Profile
+# Outers
+from ..file_rules import HTML_BASE, HTML_STRICT_EXCLUDE
+from ..presets import html_no_imports_steps
+# Inners
+from .steps_for_engine import steps_for_engine
+
+
+JINJA_NO_IMPORTS: Final[Profile] = Profile(
+    system="html",
+    name="jinja-no-imports",
+    description="Jinja templates reduced to their content: no comments, {% import %} and {% from %}, imports in script and style, or blank lines",
+    include=HTML_BASE,
+    exclude=HTML_STRICT_EXCLUDE,
+    steps=steps_for_engine(html_no_imports_steps, "jinja"),
+    output_name="html_jinja_no_imports.md",
+)
+"""The profile `html/jinja-no-imports`."""
+
+
+_DESIGN_NOTES = """
+# JINJA_NO_IMPORTS — `html/jinja-no-imports`
+
+## Purpose
+The Jinja templates without what only says where macros come from
+(`{% import %}`, `{% from %}`) and without the imports of the code inside.
+`{% extends %}` and `{% include %}` stay.
+
+## Output
+`html_jinja_no_imports.md`.
+"""

simplibs/extractor_html/profiles/JINJA_OUTLINE.py

@@ -0,0 +1,30 @@
+from typing import Final
+from simplibs.extractor import Profile
+# Outers
+from ..file_rules import HTML_BASE, HTML_STRICT_EXCLUDE
+from ..presets import html_outline_steps
+# Inners
+from .steps_for_engine import steps_for_engine
+
+
+JINJA_OUTLINE: Final[Profile] = Profile(
+    system="html",
+    name="jinja-outline",
+    description="Overview of Jinja templates as pages: landmarks, headings and every element with an id",
+    include=HTML_BASE,
+    exclude=HTML_STRICT_EXCLUDE,
+    steps=steps_for_engine(html_outline_steps, "jinja"),
+    output_name="html_jinja_outline.md",
+)
+"""The profile `html/jinja-outline`."""
+
+
+_DESIGN_NOTES = """
+# JINJA_OUTLINE — `html/jinja-outline`
+
+## Purpose
+The overview of the pages of a Jinja project, read as templates.
+
+## Output
+`html_jinja_outline.md`.
+"""

simplibs/extractor_html/profiles/JINJA_STRUCTURE.py

@@ -0,0 +1,31 @@
+from typing import Final
+from simplibs.extractor import Profile
+# Outers
+from ..file_rules import HTML_BASE, HTML_STRICT_EXCLUDE
+from ..presets import template_structure_steps
+# Inners
+from .steps_for_engine import steps_for_engine
+
+
+JINJA_STRUCTURE: Final[Profile] = Profile(
+    system="html",
+    name="jinja-structure",
+    description="Skeleton of Jinja templates: extends, include, macros and blocks",
+    include=HTML_BASE,
+    exclude=HTML_STRICT_EXCLUDE,
+    steps=steps_for_engine(template_structure_steps, "jinja"),
+    output_name="html_jinja_structure.md",
+)
+"""The profile `html/jinja-structure`."""
+
+
+_DESIGN_NOTES = """
+# JINJA_STRUCTURE — `html/jinja-structure`
+
+## Purpose
+How the templates of a Jinja project are put together: what each extends and
+includes, which macros it defines and which blocks it has.
+
+## Output
+`html_jinja_structure.md`.
+"""