Use render options during rendering

Author: MaddyGuthridge

meta/generate_tag_defs.py

@@ -70,8 +70,10 @@ def generate_tag_class(output: TextIO, tag: TagInfo):
 
     attr_args = "\n".join(attr_args_gen).strip()
     attr_unions = "\n".join(attr_unions_gen).strip()
-    attr_docs_outer = "\n".join(increase_indent(attr_docs_gen, 4)).strip()
-    attr_docs_inner = "\n".join(increase_indent(attr_docs_gen, 8)).strip()
+    attr_docs_outer = "\n".join(increase_indent(attr_docs_gen, "    ")).strip()
+    attr_docs_inner = "\n".join(
+        increase_indent(attr_docs_gen, "        ")
+    ).strip()
 
     # Determine whether the class should mandate keyword-only args
     # If there are no named attributes, we set it to '' to avoid a syntax error

pyhtml/__render_options.py

@@ -70,3 +70,17 @@ def default() -> FullOptions:
             indent="  ",
             spacing="\n",
         )
+
+    def union(self, other: "Options | FullOptions") -> "Options":
+        """
+        Union this set of options with the other options, returning a new
+        `Options` object as the result.
+
+        Any non-`None` options in `other` will overwrite the original values.
+        """
+        values = asdict(self)
+        for field in values:
+            if (other_value := getattr(other, field)) is not None:
+                values[field] = other_value
+
+        return Options(**values)

pyhtml/__tag_base.py

@@ -3,18 +3,21 @@
 
 Tag base class, including rendering logic
 """
+
 from typing import Optional, TypeVar
 
 from . import __util as util
+from .__render_options import FullOptions, Options
 from .__types import AttributeType, ChildrenType
 
-SelfType = TypeVar('SelfType', bound='Tag')
+SelfType = TypeVar("SelfType", bound="Tag")
 
 
 class Tag:
     """
     Base tag class
     """
+
     def __init__(
         self,
         *children: ChildrenType,
@@ -23,26 +26,32 @@ def __init__(
         """
         Create a new tag instance
         """
-        self.children = util.flatten_list(list(children))
+        flattened, options = util.flatten_children(list(children))
+        self.children = flattened
         """Children of this tag"""
 
         self.attributes = util.filter_attributes(attributes)
         """Attributes of this tag"""
 
+        self.options = options
+        """Render options specified for this element"""
+
     def __call__(
         self: SelfType,
         *children: ChildrenType,
         **attributes: AttributeType,
-    ) -> 'SelfType':
+    ) -> "SelfType":
         """
         Create a new tag instance derived from this tag. Its children and
         attributes are based on this original tag, but with additional children
         appended and additional attributes unioned.
         """
-        new_children = self.children + util.flatten_list(list(children))
+        flattened, options = util.flatten_children(list(children))
+        new_children = self.children + flattened
         new_attributes = util.dict_union(self.attributes, attributes)
+        new_options = self.options.union(options)
 
-        return self.__class__(*new_children, **new_attributes)
+        return self.__class__(*new_children, new_options, **new_attributes)
 
     def __iter__(self) -> None:
         """
@@ -59,7 +68,7 @@ def _get_tag_name(self) -> str:
         """
         Returns the name of the tag
         """
-        return type(self).__name__.removesuffix('_')
+        return type(self).__name__.removesuffix("_")
 
     def _get_default_attributes(
         self,
@@ -94,18 +103,35 @@ def _escape_children(self) -> bool:
         """
         return True
 
-    def _render(self, indent: int) -> list[str]:
+    def _render(self, indent: str, options: FullOptions) -> list[str]:
         """
         Renders tag and its children to a list of strings where each string is
-        a single line of output
+        a single line of output.
+
+        Parameters
+        ----------
+        indent : str
+            string to use for indentation
+        options : FullOptions
+            rendering options
+
+        Returns
+        -------
+        list[str]
+            list of lines of output
         """
-        attributes = util.filter_attributes(util.dict_union(
-            self._get_default_attributes(self.attributes),
-            self.attributes,
-        ))
+        # Determine what the options for this element are
+        options = options.union(self.options)
+
+        attributes = util.filter_attributes(
+            util.dict_union(
+                self._get_default_attributes(self.attributes),
+                self.attributes,
+            )
+        )
 
         # Tag and attributes
-        opening = f"{' ' * indent}<{self._get_tag_name()}"
+        opening = f"{indent}<{self._get_tag_name()}"
 
         # Add pre-content
         if (pre := self._get_tag_pre_content()) is not None:
@@ -126,19 +152,20 @@ def _render(self, indent: int) -> list[str]:
                 util.render_children(
                     self.children,
                     self._escape_children(),
-                    indent + 2,
+                    indent + options.indent,
+                    options,
                 )
             )
             # Closing tag
-            out.append(f"{' ' * indent}</{self._get_tag_name()}>")
+            out.append(f"{indent}</{self._get_tag_name()}>")
 
             return out
 
     def render(self) -> str:
         """
         Render this tag and its contents to a string
         """
-        return '\n'.join(self._render(0))
+        return "\n".join(self._render("", Options.default()))
 
     def __str__(self) -> str:
         return self.render()
@@ -151,32 +178,36 @@ class SelfClosingTag(Tag):
     """
     Self-closing tags don't contain child elements
     """
+
     def __init__(self, **attributes: AttributeType) -> None:
         # Self-closing tags don't allow children
         super().__init__(**attributes)
 
-    def _render(self, indent: int) -> list[str]:
+    def _render(self, indent: str, options: FullOptions) -> list[str]:
         """
         Renders tag and its children to a list of strings where each string is
         a single line of output
         """
-        attributes = util.filter_attributes(util.dict_union(
-            self._get_default_attributes(self.attributes),
-            self.attributes,
-        ))
+        attributes = util.filter_attributes(
+            util.dict_union(
+                self._get_default_attributes(self.attributes),
+                self.attributes,
+            )
+        )
         if len(attributes):
             return [
-                f"{' ' * indent}<{self._get_tag_name()} "
+                f"{indent}<{self._get_tag_name()} "
                 f"{util.render_tag_attributes(attributes)}/>"
             ]
         else:
-            return [f"{' ' * indent}<{self._get_tag_name()}/>"]
+            return [f"{indent}<{self._get_tag_name()}/>"]
 
 
 class WhitespaceSensitiveTag(Tag):
     """
     Whitespace-sensitive tags are tags where whitespace needs to be respected.
     """
+
     def __init__(
         self,
         *children: ChildrenType,
@@ -193,25 +224,30 @@ def __call__(  # type: ignore
         attributes |= {}
         return super().__call__(*children, **attributes)
 
-    def _render(self, indent: int) -> list[str]:
-        attributes = util.filter_attributes(util.dict_union(
-            self._get_default_attributes(self.attributes),
-            self.attributes,
-        ))
+    def _render(self, indent: str, options: FullOptions) -> list[str]:
+        attributes = util.filter_attributes(
+            util.dict_union(
+                self._get_default_attributes(self.attributes),
+                self.attributes,
+            )
+        )
 
         # Tag and attributes
-        output = f"{' ' * indent}<{self._get_tag_name()}"
+        output = f"{indent}<{self._get_tag_name()}"
 
         if len(attributes):
             output += f" {util.render_tag_attributes(attributes)}>"
         else:
             output += ">"
 
-        output += '\n'.join(util.render_children(
-            self.children,
-            self._escape_children(),
-            0,
-        ))
+        output += "\n".join(
+            util.render_children(
+                self.children,
+                self._escape_children(),
+                "",
+                options,
+            )
+        )
 
         output += f"</{self._get_tag_name()}>"
         return output.splitlines()

pyhtml/__tags/comment.py

@@ -3,7 +3,9 @@
 
 Definition for the comment tag.
 """
+
 from .. import __util as util
+from ..__render_options import FullOptions
 from ..__tag_base import Tag
 
 
@@ -19,6 +21,7 @@ class Comment(Tag):
 
     Note that this does not render as a `<comment>` tag
     """
+
     def __init__(self, text: str) -> None:
         """
         An HTML comment.
@@ -35,24 +38,24 @@ def __init__(self, text: str) -> None:
         super().__init__()
 
     def __call__(self, *args, **kwargs):
-        raise TypeError('Comment tags are not callable')
+        raise TypeError("Comment tags are not callable")
 
     def _get_tag_name(self) -> str:
         # Ignore coverage since this is only implemented to satisfy inheritance
         # and is never used since we override _render
-        return '!--'  # pragma: no cover
+        return "!--"  # pragma: no cover
 
-    def _render(self, indent: int) -> list[str]:
+    def _render(self, indent: str, options: FullOptions) -> list[str]:
         """
         Override of render, to render comments
         """
 
         return util.increase_indent(
-            ['<!--']
+            ["<!--"]
             + util.increase_indent(
                 util.escape_string(self.comment_data).splitlines(),
-                indent+2,
+                indent + options.indent,
             )
-            + ['-->'],
+            + ["-->"],
             indent,
         )

pyhtml/__tags/dangerous_raw_html.py

@@ -3,6 +3,8 @@
 
 Definition for the DangerousRawHtml tag.
 """
+
+from ..__render_options import FullOptions
 from ..__tag_base import Tag
 from ..__util import increase_indent
 
@@ -20,6 +22,7 @@ class DangerousRawHtml(Tag):
 
     Do not use this unless absolutely necessary.
     """
+
     def __init__(self, text: str) -> None:
         """
         Raw HTML as a string. This is embedded directly within the rendered
@@ -38,12 +41,12 @@ def __init__(self, text: str) -> None:
         super().__init__()
 
     def __call__(self, *args, **kwargs):
-        raise TypeError('DangerousRawHtml tags are not callable')
+        raise TypeError("DangerousRawHtml tags are not callable")
 
     def _get_tag_name(self) -> str:
         # Ignore coverage since this is only implemented to satisfy inheritance
         # and is never used since we override _render
-        return '!!!DANGEROUS RAW HTML!!!'  # pragma: no cover
+        return "!!!DANGEROUS RAW HTML!!!"  # pragma: no cover
 
-    def _render(self, indent: int) -> list[str]:
+    def _render(self, indent: str, options: FullOptions) -> list[str]:
         return increase_indent(self.html_data.splitlines(), indent)

pyhtml/__types.py

@@ -3,10 +3,12 @@
 
 Type definitions
 """
+
 from collections.abc import Generator, Sequence
 from typing import TYPE_CHECKING, Union
 
 if TYPE_CHECKING:
+    from .__render_options import Options
     from .__tag_base import Tag
 
 
@@ -21,7 +23,7 @@
 """
 
 
-ChildElementType = Union['Tag', type['Tag'], str]
+ChildElementType = Union["Tag", type["Tag"], str]
 """
 Objects that are valid as a child element of an HTML element.
 
@@ -33,14 +35,16 @@
 ChildrenType = Union[
     ChildElementType,
     Sequence[ChildElementType],
-    'Generator[ChildElementType, None, None]',
     # TODO: Would an `Any` type for the generator return be better, even though
     # it would be discarded?
+    "Generator[ChildElementType, None, None]",
+    "Options",
 ]
 """
 Objects that are valid when passed to a `Tag` for use as children.
 
 * `ChildElementType`: a singular element
 * `list[ChildElementType]`: a list of elements
 * `GeneratorType[ChildElementType, None, None]`: a generator of elements
+* `Options`: PyHTML render options.
 """