jx 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

jx/attrs.py

@@ -30,14 +30,13 @@ def quote(text: str) -> str:
 
 
 class LazyString(UserString):
-    """
-    Behave like regular strings, but the actual casting of the initial value
-    is deferred until the value is actually required.
-    """
-
     __slots__ = ("_seq",)
 
     def __init__(self, seq):
+        """
+        Behave like regular strings, but the actual casting of the initial value
+        is deferred until the value is actually required.
+        """
         self._seq = seq
 
     @cached_property
@@ -46,21 +45,20 @@ class LazyString(UserString):
 
 
 class Attrs:
-    """
-    Contains all the HTML attributes/properties (a property is an
-    attribute without a value) passed to a component but that weren't
-    in the declared attributes list.
-
-    For HTML classes you can use the name "classes" (instead of "class")
-    if you need to.
+    def __init__(self, attrs: "dict[str, t.Any| LazyString]") -> None:
+        """
+        Contains all the HTML attributes/properties (a property is an
+        attribute without a value) passed to a component but that weren't
+        in the declared attributes list.
 
-    **NOTE**: The string values passed to this class, are not cast to `str` until
-    the string representation is actually needed, for example when
-    `attrs.render()` is invoked.
+        For HTML classes you can use the name "classes" (instead of "class")
+        if you need to.
 
-    """
+        **NOTE**: The string values passed to this class, are not cast to `str` until
+        the string representation is actually needed, for example when
+        `attrs.render()` is invoked.
 
-    def __init__(self, attrs: "dict[str, t.Any| LazyString]") -> None:
+        """
         attributes: "dict[str, str | LazyString]" = {}
         properties: set[str] = set()
 
@@ -90,7 +88,7 @@ class Attrs:
         Example:
 
             ```python
-            attrs = HTMLAttrs({"class": "italic bold bg-blue wide abcde"})
+            attrs = Attrs({"class": "italic bold bg-blue wide abcde"})
             attrs.set(class="bold text-white")
             print(attrs.classes)
             abcde bg-blue bold italic text-white wide
@@ -108,7 +106,7 @@ class Attrs:
         Example:
 
             ```python
-            attrs = HTMLAttrs({
+            attrs = Attrs({
             "class": "lorem ipsum",
             "data_test": True,
             "hidden": True,
@@ -157,10 +155,12 @@ class Attrs:
         - The underscores in the names will be translated automatically to dashes,
           so `aria_selected` becomes the attribute `aria-selected`.
 
+        TODO: vue-style
+
         Example:
 
             ```python
-            attrs = HTMLAttrs({"secret": "qwertyuiop"})
+            attrs = Attrs({"secret": "qwertyuiop"})
             attrs.set(secret=False)
             attrs.as_dict
             {}
@@ -169,7 +169,7 @@ class Attrs:
             attrs.as_dict
             {"count":42, "lorem":"ipsum", "data_good": True}
 
-            attrs = HTMLAttrs({"class": "b c a"})
+            attrs = Attrs({"class": "b c a"})
             attrs.set(class="c b f d e")
             attrs.as_dict
             {"class": "a b c d e f"}
@@ -199,7 +199,7 @@ class Attrs:
         Example:
 
             ```python
-            attrs = HTMLAttrs({"lorem": "ipsum"})
+            attrs = Attrs({"lorem": "ipsum"})
             attrs.setdefault(tabindex=0, lorem="meh")
             attrs.as_dict
             # "tabindex" changed but "lorem" didn't
@@ -222,10 +222,15 @@ class Attrs:
         """
         Adds one or more classes to the list of classes, if not already present.
 
+        Arguments:
+
+            values:
+                One or more class names to add, separated by spaces.
+
         Example:
 
             ```python
-            attrs = HTMLAttrs({"class": "a b c"})
+            attrs = Attrs({"class": "a b c"})
             attrs.add_class("c", "d")
             attrs.as_dict
             {"class": "a b c d"}
@@ -243,7 +248,7 @@ class Attrs:
         Example:
 
             ```python
-            attrs = HTMLAttrs({"class": "a b c"})
+            attrs = Attrs({"class": "a b c"})
             attrs.remove_class("c", "d")
             attrs.as_dict
             {"class": "a b"}
@@ -258,10 +263,18 @@ class Attrs:
         Returns the value of the attribute or property,
         or the default value if it doesn't exists.
 
+        Arguments:
+
+            name:
+                The name of the attribute or property to get.
+
+            default:
+                The default value to return if the attribute or property doesn't exist.
+
         Example:
 
             ```python
-            attrs = HTMLAttrs({"lorem": "ipsum", "hidden": True})
+            attrs = Attrs({"lorem": "ipsum", "hidden": True})
 
             attrs.get("lorem", defaut="bar")
             'ipsum'
@@ -291,7 +304,7 @@ class Attrs:
         Renders the attributes and properties as a string.
 
         Any arguments you use with this function are merged with the existing
-        attibutes/properties by the same rules as the `HTMLAttrs.set()` function:
+        attibutes/properties by the same rules as the `Attrs.set()` function:
 
         - Pass a name and a value to set an attribute (e.g. `type="text"`)
         - Use `True` as a value to set a property (e.g. `disabled`)
@@ -308,7 +321,7 @@ class Attrs:
         Example:
 
             ```python
-            attrs = HTMLAttrs({"class": "ipsum", "data_good": True, "width": 42})
+            attrs = Attrs({"class": "ipsum", "data_good": True, "width": 42})
 
             attrs.render()
             'class="ipsum" width="42" data-good'

jx/catalog.py

@@ -24,32 +24,55 @@ class CData:
     code: CodeType | None = None
     required: tuple[str, ...] = ()
     optional: dict[str, t.Any] = field(default_factory=dict) # { attr: default_value }
-    imports: dict[str, str] = field(default_factory=dict)  # { component_name: relpath }
+    imports: dict[str, str] = field(default_factory=dict)  # { name: relpath }
     css: tuple[str, ...] = ()
     js: tuple[str, ...] = ()
+    slots: tuple[str, ...] = ()
 
 
 class Catalog:
-    """
-    The object that manages the components and their global settings.
-
-    Arguments:
-    """
+    # IDEA: This dict could be replaced by a dict-like object
+    # that usesa LRU cache (to limit the memory used)
+    # or even a shared Redis/Memcache cache.
     components: dict[str, CData]
 
     def __init__(
         self,
         folder: str | Path | None = None,
         *,
+        auto_reload: bool = True,
         jinja_env: jinja2.Environment | None = None,
         filters: dict[str, t.Any] | None = None,
         tests: dict[str, t.Any] | None = None,
         extensions: list | None = None,
-        auto_reload: bool = True,
         **globals: t.Any,
     ) -> None:
+        """
+        Manager of the components and their global settings.
+
+        Arguments:
+            folder:
+                Optional folder path to scan for components. It's a shortcut to
+                calling `add_folder` when only one is used.
+            auto_reload:
+                Whether to check the last-modified time of the components files and
+                automatically re-process them if they change. The performance impact of
+                leaving it on is minimal, but *might* be noticeable when rendering a page
+                that uses a large number of different components.
+            jinja_env:
+                Optional Jinja2 environment to use for rendering.
+            filters:
+                Optional extra Jinja2 filters to add to the environment.
+            extensions:
+                Optional extra Jinja2 extensions to add to the environment.
+            tests:
+                Optional extra Jinja2 tests to add to the environment.
+            **globals:
+                Variables to make available to all components by default.
+
+        """
         self.components = {}
-        self.jinja_env = self.make_jinja_env(
+        self.jinja_env = self._make_jinja_env(
             jinja_env=jinja_env,
             globals=globals,
             filters=filters,
@@ -60,64 +83,22 @@ class Catalog:
         if folder:
             self.add_folder(folder)
 
-    def make_jinja_env(
-        self,
-        *,
-        jinja_env: jinja2.Environment | None = None,
-        globals: dict[str, t.Any] | None = None,
-        filters: dict[str, t.Any] | None = None,
-        tests: dict[str, t.Any] | None = None,
-        extensions: list | None = None,
-    ) -> jinja2.Environment:
-        env = jinja2.Environment()
-        jinja_env = jinja_env or getattr(self, "jinja_env", None)
-        if jinja_env:
-            env = jinja_env.overlay()
-
-        globals = globals or {}
-        globals.update({
-            "_get_random_id": utils.get_random_id,
-        })
-        env.globals.update(globals)
-
-        filters = filters or {}
-        env.filters.update(filters)
-
-        tests = tests or {}
-        env.tests.update(tests)
-
-        extensions = extensions or []
-        extensions.extend(["jinja2.ext.do"])
-        for ext in extensions:
-            env.add_extension(ext)
-
-        env.autoescape = True
-        env.undefined = jinja2.StrictUndefined
-
-        return env
-
     def add_folder(
         self,
         path: str | Path,
         *,
         prefix: str = "",
+        preload: bool = True
     ) -> None:
         """
         Add a folder path from which to search for components, optionally under a prefix.
 
-        Arguments:
-
-            path:
-                Absolute path of the folder with component files.
-
-            prefix:
-                Optional path prefix that all the components in the folder
-                will have. The default is empty.
-
         Components without a prefix can be imported as a path relative to the folder,
         e.g.: `sub/folder/component.jinja` or with a path relative to the component
         where it is used: `./folder/component.jinja`.
 
+        Relative imports cannot go outside the folder.
+
         Components added with a prefix must be imported using the prefix followed
         by a colon: `prefix:sub/folder/component.jinja`. If the importing is
         done from within a component with the prefix itself, a relative
@@ -128,6 +109,23 @@ class Catalog:
         with a component with the same subpath/filename, the one in the folder
         added **first** will be used and the other ignored.
 
+        WARNING: You cannot move or delete components files from the folder after
+        calling this method, but you can call it again to add new components added
+        to the folder. This is unrelated to the value of `preload`.
+
+        Arguments:
+            path:
+                Absolute path of the folder with component files.
+            prefix:
+                Optional path prefix that all the components in the folder
+                will have. The default is empty.
+            preload:
+                Whether to preload the data of components in the folder.
+                If set to `True` (the default), the component data will be loaded into
+                memory when the folder is added, instead of just before rendering it.
+                This makes the first render faster at the expense of a few
+                microseconds upfront.
+
         """
         base_path = Path(path).resolve()
         prefix = prefix.replace("\\", "/").strip("./@ ")
@@ -149,10 +147,57 @@ class Catalog:
             )
             self.components[relpath] = cdata
 
-        for relpath in self.components:
-            self.components[relpath] = self.get_component_data(relpath)
+        if preload:
+            for relpath in self.components:
+                self.components[relpath] = self.get_component_data(relpath)
+
+    def render(self, relpath: str, globals: dict[str, t.Any] | None = None, **kwargs) -> str:
+        """
+        Render a component with the given relative path and context.
+
+        Arguments:
+            relpath:
+                The path of the component to render, including the extension,relative to its view folder.
+                e.g.: "sub/component.jinja". Always use the forward slash (/) as the path separator.
+            globals:
+                Optional global variables to make available to the component and all its
+                imported components.
+            **kwargs:
+                Keyword arguments to pass to the component.
+                They will be available in the component's context but not to its imported components.
+
+        Returns:
+            The rendered component as a string.
+
+        """
+        relpath = relpath.replace("\\", "/").strip("/")
+        co = self.get_component(relpath)
+
+        globals = globals or {}
+        globals.update({
+            "assets": {
+                "css": co.collect_css,
+                "js": co.collect_js,
+                "render_css": co.render_css,
+                "render_js": co.render_js,
+                "render": co.render_assets,
+            },
+        })
+        co.globals = globals
+
+        return co.render(**kwargs)
 
     def get_component_data(self, relpath: str) -> CData:
+        """
+        Get the component data from the cache, or load it from the file system
+        if needed.
+
+        Arguments:
+            relpath:
+                The path of the component to render, including the extension,relative to its view folder.
+                e.g.: "sub/component.jinja". Always use the forward slash (/) as the path separator.
+
+        """
         cdata = self.components.get(relpath)
         if not cdata:
             raise ImportError(relpath)
@@ -173,7 +218,7 @@ class Catalog:
             source=source,
             components=list(meta.imports.keys())
         )
-        parsed_source = parser.parse()
+        parsed_source, slots = parser.parse()
         code = self.jinja_env.compile(
             source=parsed_source,
             name=relpath,
@@ -186,9 +231,19 @@ class Catalog:
         cdata.imports = meta.imports
         cdata.css = meta.css
         cdata.js = meta.js
+        cdata.slots = slots
         return cdata
 
     def get_component(self, relpath: str) -> Component:
+        """
+        Instantiate and return a component object by its relative path.
+
+        Arguments:
+            relpath:
+                The path of the component to render, including the extension,relative to its view folder.
+                e.g.: "sub/component.jinja". Always use the forward slash (/) as the path separator.
+
+        """
         cdata = self.get_component_data(relpath)
         assert cdata.code is not None
         tmpl = jinja2.Template.from_code(
@@ -203,25 +258,72 @@ class Catalog:
             get_component=self.get_component,
             required=cdata.required,
             optional=cdata.optional,
+            imports=cdata.imports,
             css=cdata.css,
             js=cdata.js,
-            imports=cdata.imports
+            slots=cdata.slots,
         )
         return co
 
-    def render(self, relpath: str, globals: dict[str, t.Any] | None = None, **kwargs) -> str:
-        co = self.get_component(relpath)
+    # Private
+
+    def _make_jinja_env(
+        self,
+        *,
+        jinja_env: jinja2.Environment | None = None,
+        globals: dict[str, t.Any] | None = None,
+        filters: dict[str, t.Any] | None = None,
+        tests: dict[str, t.Any] | None = None,
+        extensions: list | None = None,
+    ) -> jinja2.Environment:
+        """
+        Create a new Jinja2 environment with the specified settings.
+
+        If an existing environment is provided, an "overlay" of it will
+        be created and used.
+
+        Arguments:
+            jinja_env:
+                Optional Jinja2 environment to use as a base.
+            globals:
+                Optional global variables to add to the environment.
+            filters:
+                Optional extra Jinja2 filters to add to the environment.
+            extensions:
+                Optional extra Jinja2 extensions to add to the environment.
+            tests:
+                Optional extra Jinja2 tests to add to the environment.
+
+        """
+        jinja_env = jinja_env or getattr(self, "jinja_env", None)
+        if jinja_env:
+            env = jinja_env.overlay()
+        else:
+            env = jinja2.Environment()
 
         globals = globals or {}
         globals.update({
-            "assets": {
-                "css": co.collect_css,
-                "js": co.collect_js,
-                "render_css": co.render_css,
-                "render_js": co.render_js,
-                "render": co.render_assets,
-            },
+            # A unique ID generator for HTML elements, see `utils.get_random_id`
+            # docstring for more information.
+            "_get_random_id": utils.get_random_id,
         })
-        co.globals = globals
+        env.globals.update(globals)
 
-        return co.render(**kwargs)
+        filters = filters or {}
+        env.filters.update(filters)
+
+        tests = tests or {}
+        env.tests.update(tests)
+
+        extensions = extensions or []
+        # The "jinja2.ext.do" extension allows the use of the "do" statement in templates,
+        # that execute statements without outputting a value.
+        # Is specially useful for manipulating the `attrs` object.
+        extensions.extend(["jinja2.ext.do"])
+        for ext in extensions:
+            env.add_extension(ext)
+
+        env.autoescape = True
+        env.undefined = jinja2.StrictUndefined
+
+        return env

jx/component.py

@@ -22,9 +22,10 @@ class Component:
         "get_component",
         "required",
         "optional",
+        "imports",
         "css",
         "js",
-        "imports",
+        "slots",
         "globals",
     )
 
@@ -36,19 +37,45 @@ class Component:
         get_component: Callable[[str], "Component"],
         required: tuple[str, ...] = (),
         optional: dict[str, t.Any] | None = None,
+        imports: dict[str, str] | None = None,
         css: tuple[str, ...] = (),
         js: tuple[str, ...] = (),
-        imports: dict[str, str] | None = None,
+        slots: tuple[str, ...] = (),
     ) -> None:
+        """
+        Internal object that represents a Jx component.
+
+        Arguments:
+            relpath:
+                The "name" of the component.
+            tmpl:
+                The jinja2.Template for the component.
+            get_component:
+                A callable that retrieves a component by its name/relpath.
+            required:
+                A tuple of required attribute names.
+            optional:
+                A dictionary of optional attributes and their default values.
+            imports:
+                A dictionary of imported component names as "name": "relpath" pairs.
+            css:
+                A tuple of CSS file URLs.
+            js:
+                A tuple of JS file URLs.
+            slots:
+                A tuple of slot names.
+
+        """
         self.relpath = relpath
         self.tmpl = tmpl
         self.get_component = get_component
 
         self.required = required
         self.optional = optional or {}
+        self.imports = imports or {}
         self.css = css
         self.js = js
-        self.imports = imports or {}
+        self.slots = slots
 
         self.globals: dict[str, t.Any] = {}
 
@@ -57,10 +84,10 @@ class Component:
         *,
         content: str | None = None,
         attrs: Attrs | dict[str, t.Any] | None = None,
-        caller: Callable[[], str] | None = None,
+        caller: Callable[[str], str] | None = None,
         **params: t.Any
     ) -> Markup:
-        content = content if content is not None else caller() if caller else ""
+        content = content if content is not None else caller("") if caller else ""
         attrs = attrs.as_dict if isinstance(attrs, Attrs) else attrs or {}
         params = {**attrs, **params}
         props, attrs = self.filter_attrs(params)
@@ -69,6 +96,14 @@ class Component:
         globals.setdefault("attrs", Attrs(attrs))
         globals.setdefault("content", content)
 
+        slots = {}
+        if caller:
+            for name in self.slots:
+                body = caller(name)
+                if body != content:
+                    slots[name] = body
+        props["_slots"] = slots
+
         html = self.tmpl.render({**props, **globals}).lstrip()
         return Markup(html)
 
@@ -93,41 +128,41 @@ class Component:
         child.globals = self.globals
         return child
 
-    def collect_css(self, visited: set[str] | None = None) -> list[str]:
+    def collect_css(self, _visited: set[str] | None = None) -> list[str]:
         """
         Returns a list of CSS files for the component and its children.
         """
         urls = dict.fromkeys(self.css, 1)
-        visited = visited or set()
-        visited.add(self.relpath)
+        _visited = _visited or set()
+        _visited.add(self.relpath)
 
         for name, relpath in self.imports.items():
-            if relpath in visited:
+            if relpath in _visited:
                 continue
             co = self.get_child(name)
-            for file in co.collect_css(visited=visited):
+            for file in co.collect_css(_visited=_visited):
                 if file not in urls:
                     urls[file] = 1
-            visited.add(relpath)
+            _visited.add(relpath)
 
         return list(urls.keys())
 
-    def collect_js(self, visited: set[str] | None = None) -> list[str]:
+    def collect_js(self, _visited: set[str] | None = None) -> list[str]:
         """
         Returns a list of JS files for the component and its children.
         """
         urls = dict.fromkeys(self.js, 1)
-        visited = visited or set()
-        visited.add(self.relpath)
+        _visited = _visited or set()
+        _visited.add(self.relpath)
 
         for name, relpath in self.imports.items():
-            if relpath in visited:
+            if relpath in _visited:
                 continue
             co = self.get_child(name)
-            for file in co.collect_js(visited=visited):
+            for file in co.collect_js(_visited=_visited):
                 if file not in urls:
                     urls[file] = 1
-            visited.add(relpath)
+            _visited.add(relpath)
 
         return list(urls.keys())
 
@@ -135,10 +170,6 @@ class Component:
         """
         Uses the `collect_css()` list to generate an HTML fragment
         with `<link rel="stylesheet" href="{url}">` tags.
-
-        Unless it's an external URL (e.g.: beginning with "http://" or "https://")
-        or a root-relative URL (e.g.: starting with "/"),
-        the URL is prefixed by `base_url`.
         """
         html = []
         for url in self.collect_css():
@@ -151,9 +182,15 @@ class Component:
         Uses the `collected_js()` list to generate an HTML fragment
         with `<script type="module" src="{url}"></script>` tags.
 
-        Unless it's an external URL (e.g.: beginning with "http://" or "https://"),
-        the URL is prefixed by `base_url`. A hash can also be added to
-        invalidate the cache if the content changes, if `fingerprint` is `True`.
+        Arguments:
+            module:
+                Whether to render the script tags as modules, e.g.:
+                `<script type="module" src="..."></script>`
+            defer:
+                Whether to add the `defer` attribute to the script tags,
+                if `module` is `False` (all module scripts are also deferred), e.g.:
+                `<script src="..." defer></script>`
+
         """
         html = []
         for url in self.collect_js():
@@ -172,9 +209,16 @@ class Component:
         Calls `render_css()` and `render_js()` to generate
         an HTML fragment with `<link rel="stylesheet" href="{url}">`
         and `<script type="module" src="{url}"></script>` tags.
-        Unless it's an external URL (e.g.: beginning with "http://" or "https://"),
-        the URL is prefixed by `base_url`. A hash can also be added to
-        invalidate the cache if the content changes, if `fingerprint` is `True`.
+
+        Arguments:
+            module:
+                Whether to render the script tags as modules, e.g.:
+                `<script type="module" src="..."></script>`
+            defer:
+                Whether to add the `defer` attribute to the script tags,
+                if `module` is `False` (all module scripts are also deferred), e.g.:
+                `<script src="..." defer></script>`
+
         """
         html_css = self.render_css()
         html_js = self.render_js()

jx/meta.py

@@ -61,7 +61,8 @@ def extract_metadata(source: str, base_path: Path, fullpath: Path) -> Meta:
             The absolute full path of the current template.
 
     Returns:
-        A Meta object containing the extracted metadata.
+        A `Meta` object containing the extracted metadata.
+
     """
     meta = Meta()
 
@@ -138,7 +139,7 @@ def parse_args_expr(expr: str) -> tuple[tuple[str, ...], dict[str, t.Any]]:
     return tuple(required), optional
 
 
-def eval_expression(input_string):
+def eval_expression(input_string: str) -> t.Any:
     code = compile(input_string, "<string>", "eval")
     for name in code.co_names:
         if name not in ALLOWED_NAMES_IN_EXPRESSION_VALUES:

jx/parser.py

@@ -1,6 +1,7 @@
 """
 Jx | Copyright (c) Juan-Pablo Scaletti <juanpablo@jpscaletti.com>
 """
+
 import re
 import typing as t
 from uuid import uuid4
@@ -11,7 +12,7 @@ from .exceptions import TemplateSyntaxError
 from .utils import logger
 
 
-BLOCK_CALL = '{% call _get("[TAG]").render([ATTRS]) -%}[CONTENT]{%- endcall %}'
+BLOCK_CALL = '{% call(_slot="") _get("[TAG]").render([ATTRS]) -%}[CONTENT]{%- endcall %}'
 INLINE_CALL = '{{ _get("[TAG]").render([ATTRS]) }}'
 
 re_raw = r"\{%-?\s*raw\s*-?%\}.+?\{%-?\s*endraw\s*-?%\}"
@@ -32,6 +33,17 @@ re_attr = r"""
 """
 RX_ATTR = re.compile(re_attr, re.VERBOSE | re.DOTALL)
 
+RE_LSTRIP = r"\s*(?P<lstrip>-?)%}"
+RE_RSTRIP = r"{%(?P<rstrip>-?)\s*"
+
+RE_SLOT_OPEN = r"{%-?\s*slot\s+(?P<name>[0-9A-Za-z_.:$-]+)" + RE_LSTRIP
+RE_SLOT_CLOSE = RE_RSTRIP + r"endslot\s*-?%}"
+RX_SLOT = re.compile(rf"{RE_SLOT_OPEN}(?P<default>.*?)({RE_SLOT_CLOSE})", re.DOTALL)
+
+RE_FILL_OPEN = r"{%-?\s*fill\s+(?P<name>[0-9A-Za-z_.:$-]+)" + RE_LSTRIP
+RE_FILL_CLOSE = RE_RSTRIP + r"endfill\s*-?%}"
+RX_FILL = re.compile(rf"{RE_FILL_OPEN}(?P<body>.*?)({RE_FILL_CLOSE})", re.DOTALL)
+
 
 def escape(s: t.Any, /) -> Markup:
     return Markup(
@@ -45,20 +57,66 @@ def escape(s: t.Any, /) -> Markup:
 
 
 class JxParser:
-    def __init__(self, *, name: str, source: str, components: list[str]) :
+    def __init__(
+        self,
+        *,
+        name: str,
+        source: str,
+        components: list[str],
+    ):
+        """
+        A parser that transforms a template's source code by replacing
+        TitledCased HTML tags with their corresponding component calls.
+
+        Only the names defined in the `components` list are allowed.
+
+        Arguments:
+            name:
+                The name of the template for error reporting.
+            source:
+                The source code of the template.
+            components:
+                A list of allowed component names.
+
+        """
         self.name = name
         self.source = source
         self.components = components
 
-    def parse(self, *, validate_tags: bool = True) -> str:
+    def parse(self, *, validate_tags: bool = True) -> tuple[str, tuple[str, ...]]:
+        """
+        Parses the template source code.
+
+        Arguments:
+            validate_tags:
+                Whether to raise an error for unknown TitleCased tags.
+
+        Returns:
+            - The transformed template source code
+            - The list of slot names.
+
+        Raises:
+            TemplateSyntaxError:
+                If the template contains unknown components or syntax errors.
+
+        """
         raw_blocks = {}
         source = self.source
         source, raw_blocks = self.replace_raw_blocks(source)
         source = self.process_tags(source, validate_tags=validate_tags)
+        source, slots = self.process_slots(source)
         source = self.restore_raw_blocks(source, raw_blocks)
-        return source
+        return source, slots
 
     def replace_raw_blocks(self, source: str) -> tuple[str, dict[str, str]]:
+        """
+        Replace the `{% raw %}` blocks with temporary placeholders.
+
+        Arguments:
+            source:
+                The template source code.
+
+        """
         raw_blocks = {}
         while True:
             match = RX_RAW.search(source)
@@ -73,11 +131,32 @@ class JxParser:
         return source, raw_blocks
 
     def restore_raw_blocks(self, source: str, raw_blocks: dict[str, str]) -> str:
+        """
+        Restores the original `{% raw %}` blocks from the temporary placeholders.
+
+        Arguments:
+            source:
+                The template source code.
+            raw_blocks:
+                A dictionary mapping placeholder keys to their original raw block content.
+
+        """
         for uid, code in raw_blocks.items():
             source = source.replace(uid, code)
         return source
 
     def process_tags(self, source: str, *, validate_tags: bool = True) -> str:
+        """
+        Search for TitledCased HTML tags in the template source code and replace
+        them with their corresponding component calls.
+
+        Arguments:
+            source:
+                The template source code.
+            validate_tags:
+                Whether to raise an error for unknown TitleCased tags.
+
+        """
         while True:
             match = RX_TAG_NAME.search(source)
             if not match:
@@ -85,21 +164,43 @@ class JxParser:
             source = self.replace_tag(source, match, validate_tags=validate_tags)
         return source
 
-    def replace_tag(self, source: str, match: re.Match, *, validate_tags: bool = True) -> str:
+    def replace_tag(
+        self,
+        source: str,
+        match: re.Match,
+        *,
+        validate_tags: bool = True,
+    ) -> str:
+        """
+        Replaces a single TitledCased HTML tag with its corresponding component call.
+
+        Arguments:
+            source:
+                The template source code.
+            match:
+                The regex match object for the tag.
+            validate_tags:
+                Whether to raise an error for unknown TitleCased tags.
+
+        """
         start, curr = match.span(0)
         lineno = source[:start].count("\n") + 1
 
         tag = match.group("tag")
         if validate_tags and tag not in self.components:
             line = self.source.split("\n")[lineno - 1]
-            raise TemplateSyntaxError(f"[{self.name}:{lineno}] Unknown component `{tag}`\n{line}")
+            raise TemplateSyntaxError(
+                f"[{self.name}:{lineno}] Unknown component `{tag}`\n{line}"
+            )
 
-        attrs, end = self._parse_opening_tag(source, lineno=lineno, start=curr - 1)
+        raw_attrs, end = self._parse_opening_tag(source, lineno=lineno, start=curr - 1)
         if end == -1:
             line = self.source.split("\n")[lineno - 1]
-            raise TemplateSyntaxError(f"[{self.name}:{lineno}] Syntax error: `{tag}`\n{line}")
+            raise TemplateSyntaxError(
+                f"[{self.name}:{lineno}] Syntax error: `{tag}`\n{line}"
+            )
 
-        inline = source[end - 2:end] == "/>"
+        inline = source[end - 2 : end] == "/>"
         if inline:
             content = ""
         else:
@@ -107,39 +208,135 @@ class JxParser:
             index = source.find(close_tag, end, None)
             if index == -1:
                 line = self.source.split("\n")[lineno - 1]
-                raise TemplateSyntaxError(f"[{self.name}:{lineno}] Unclosed component `{tag}`\n{line}")
+                raise TemplateSyntaxError(
+                    f"[{self.name}:{lineno}] Unclosed component `{tag}`\n{line}"
+                )
 
             content = source[end:index]
             end = index + len(close_tag)
 
-        attrs_list = self._parse_attrs(attrs)
-        repl = self._build_call(tag, attrs_list, content)
+        if content:
+            content = self.process_fills(content)
 
+        attrs = self._parse_attrs(raw_attrs)
+        repl = self._build_call(tag, attrs, content)
         return f"{source[:start]}{repl}{source[end:]}"
 
-    def _parse_opening_tag(self, source: str, *, lineno: int, start: int) -> tuple[str, int]:
+    def process_slots(self, source: str) -> tuple[str, tuple[str, ...]]:
+        """
+        Extracts slot content from the template source code.
+
+        Arguments:
+            source:
+                The template source code
+
+        Returns:
+            - The transformed template source code
+            - The list of slot names.
+
+        """
+        slots = {}
+        while True:
+            match = RX_SLOT.search(source)
+            if not match:
+                break
+            start, end = match.span(0)
+            slot_name = match.group("name")
+            slot_default = match.group("default") or ""
+            lstrip = match.group("lstrip") == "-"
+            rstrip = match.group("rstrip") == "-"
+            if lstrip:
+                slot_default = slot_default.lstrip()
+            if rstrip:
+                slot_default = slot_default.rstrip()
+
+            slot_expr = "".join([
+                "{% if _slots.get('", slot_name,
+                "') %}{{ _slots['", slot_name,
+                "'] }}{% else %}", slot_default,
+                "{% endif %}"
+            ])
+            source = f"{source[:start]}{slot_expr}{source[end:]}"
+            slots[slot_name] = 1
+
+        return source, tuple(slots.keys())
+
+    def process_fills(self, source: str) -> str:
+        """
+        Processes `{% fill slot_name %}...{% endfill %}` blocks in the template source code.
+
+        Arguments:
+            source:
+                The template source code.
+
+        Returns:
+            The modified source code prepended by fill contents as `if` statements.
+
+        """
+        fills = {}
+
+        while True:
+            match = RX_FILL.search(source)
+            if not match:
+                break
+            start, end = match.span(0)
+            fill_name = match.group("name")
+            fill_body = match.group("body") or ""
+            lstrip = match.group("lstrip") == "-"
+            rstrip = match.group("rstrip") == "-"
+            if lstrip:
+                fill_body = fill_body.lstrip()
+            if rstrip:
+                fill_body = fill_body.rstrip()
+            fills[fill_name] = fill_body
+            source = f"{source[:start]}{source[end:]}"
+
+        if not fills:
+            return source
+
+        ifs = []
+        for fill_name, fill_body in fills.items():
+            ifs.append(f"{{% elif _slot == '{fill_name}' %}}{fill_body}")
+        # Replace the first occurrence of "elif" with "if"
+        str_ifs = f"\n{{% {''.join(ifs)[5:]}"
+
+        return f"{str_ifs}{{% else -%}}\n{source.strip()}\n{{%- endif %}}\n"
+
+    # Private
+
+    def _parse_opening_tag(
+        self, source: str, *, lineno: int, start: int
+    ) -> tuple[str, int]:
+        """
+        Parses the opening tag and returns the raw attributes and the position
+        where the opening tag ends.
+        """
         eof = len(source)
-        in_single_quotes = in_double_quotes = in_braces = False   # dentro de '…'  /  "…"
+        in_single_quotes = in_double_quotes = in_braces = False
         i = start
         end = -1
 
         while i < eof:
             ch = source[i]
-            ch2 = source[i:i + 2]
+            ch2 = source[i : i + 2]
             # print(ch, ch2, in_single_quotes, in_double_quotes, in_braces)
 
             # Detects {{ … }} only when NOT inside quotes
             if not in_single_quotes and not in_double_quotes:
                 if ch2 == "{{":
                     if in_braces:
-                        raise TemplateSyntaxError(f"[{self.name}:{lineno}] Unmatched braces")
+                        raise TemplateSyntaxError(
+                            f"[{self.name}:{lineno}] Unmatched braces"
+                        )
                     in_braces = True
                     i += 2
                     continue
 
                 if ch2 == "}}":
                     if not in_braces:
-                        raise TemplateSyntaxError(f"[{self.name}:{lineno}] Unmatched braces")
+                        raise TemplateSyntaxError(
+                            f"[{self.name}:{lineno}] Unmatched braces"
+                        )
                     in_braces = False
                     i += 2
                     continue
@@ -164,33 +361,25 @@ class JxParser:
         attrs = source[start:end].strip().removesuffix("/>").removesuffix(">")
         return attrs, end
 
-    def _parse_attrs(self, attrs: str) -> list[tuple[str, str]]:
-        attrs = attrs.replace("\n", " ").strip()
-        if not attrs:
+    def _parse_attrs(self, raw_attrs: str) -> list[str]:
+        """
+        Parses the HTML attributes string and returns a list of '"key":value'
+        strings to be used in a components call.
+        """
+        raw_attrs = raw_attrs.replace("\n", " ").strip()
+        if not raw_attrs:
             return []
-        return RX_ATTR.findall(attrs)
 
-    def _build_call(
-        self,
-        tag: str,
-        attrs_list: list[tuple[str, str]],
-        content: str = "",
-    ) -> str:
-        logger.debug(f"{tag} {attrs_list} {'inline' if not content else ''}")
         attrs = []
-        for name, value in attrs_list:
+        for name, value in RX_ATTR.findall(raw_attrs):
             name = name.strip().replace("-", "_")
             value = value.strip()
 
             if not value:
-                attrs.append(f'"{name}"=True')
+                attrs.append(f'"{name}":True')
             else:
-                # vue-like syntax
-                # if (
-                #     name[0] == ":"
-                #     and value[0] in ("\"'")
-                #     and value[-1] in ("\"'")
-                # ):
+                # vue-like syntax could be possible
+                # if (name[0] == ":" and value[0] in ("\"'") and value[-1] in ("\"'")):
                 #     value = value[1:-1].strip()
                 #     name = name.lstrip(":")
 
@@ -198,16 +387,23 @@ class JxParser:
                 if value[:2] == "{{" and value[-2:] == "}}":
                     value = value[2:-2].strip()
 
-                attrs.append(f'"{name}"={value}')
+                attrs.append(f'"{name}":{value}')
+
+        return attrs
+
+    def _build_call(self, tag: str, attrs: list[str], content: str = "") -> str:
+        """
+        Builds a component call string.
+        """
+        logger.debug(f"{tag} {attrs} {'inline' if not content else ''}")
 
         str_attrs = ""
         if attrs:
-            str_attrs = "**{" + ", ".join([a.replace("=", ":", 1) for a in attrs]) + "}"
+            str_attrs = "**{" + ", ".join(attrs) + "}"
 
         if content:
             return (
-                BLOCK_CALL
-                .replace("[TAG]", tag)
+                BLOCK_CALL.replace("[TAG]", tag)
                 .replace("[ATTRS]", str_attrs)
                 .replace("[CONTENT]", content)
             )

jx/utils.py

@@ -9,5 +9,17 @@ logger = logging.getLogger("jx")
 
 
 def get_random_id(prefix: str = "id") -> str:
+    """
+    Returns an unique string suitable to be used for HTML element IDs.
+
+    HTML form elements, popovers, and other components require unique IDs
+    to function correctly. When you are writing custom components, this function
+    can be used to generate default IDs for such elements, so you don't have to
+    make it a required argument.
+
+    Arguments:
+        prefix: The prefix to use for the ID. Defaults to "id".
+
+    """
     return f"{prefix}-{str(uuid.uuid4().hex)}"
 

{jx-0.1.0.dist-info → jx-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jx
-Version: 0.1.0
+Version: 0.2.0
 Summary: Replace your HTML templates with Python server-Side components
 Author-email: Juan Pablo Scaletti <juanpablo@jpscaletti.com>
 Project-URL: homepage, https://jx.scaletti.dev/
@@ -24,6 +24,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: jinja2>=3.0
 Requires-Dist: markupsafe>=2.0
+Requires-Dist: ty>=0.0.1a15
 Dynamic: license-file
 
 <h1>
@@ -40,3 +41,38 @@ Super components powers for your Jinja templates.
 From chaos to clarity: The power of components in your server-side-rendered Python web app.
 
 <!-- Documentation: https://jx.scaletti.dev/ -->
+
+## How It Works
+
+Jx is a Python library for creating reusable template components with Jinja2. It works by pre-parsing the template source and replacing TitleCased HTML tags with Jinja calls that render the component.
+
+### Component Definition
+
+Components are defined as regular Jinja2 templates (.jinja files) with special metadata comments:
+
+- `{# def parameter1 parameter2=default_value #}` - Defines required and optional parameters
+- `{# import "path/to/component.jinja" as ComponentName #}` - Imports other components
+- `{# css "/path/to/style.css" #}` - Includes CSS files
+- `{# js "/path/to/script.js" #}` - Includes JavaScript files
+
+Example component:
+
+```jinja
+{# def message #}
+{# import "button.jinja" as Button #}
+
+<div class="greeting">{{ message }}</div>
+<Button text="OK" />
+```
+
+### Usage Example
+
+```python
+from jx import Catalog
+
+# Create a catalog and add a components folder
+catalog = Catalog("templates/components")
+
+# Render a component with parameters
+html = catalog.render("card.jinja", title="Hello", content="This is a card")
+```

jx-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+jx/__init__.py,sha256=MZ7KbNZkQx2D5CJpccSKuyJi179iAff3a9jG7DwEBAE,152
+jx/attrs.py,sha256=_Cj1s4PEHiq_TiG2IvKiUkTqyThH4YgS4HwUn09zzGU,10414
+jx/catalog.py,sha256=EaG0jNqf4JJkif9Nrnp72vEr8kX1BslJGRig9pOGgC8,11567
+jx/component.py,sha256=9TkyX10brWRCDw6AC0tEJ70DWaDmkl_UE8i_Uqfta6M,7100
+jx/exceptions.py,sha256=rDWxkgOqeMPptmQ21joB2ujfpIU5EwMKtAL-ImB9nuA,1518
+jx/meta.py,sha256=lh3EFyp2_Y0R80aXaT3kVPNPcB3CREdHHePdQP4ZnR4,5148
+jx/parser.py,sha256=LW1iHh5_Ac8B368RhfiBPe3w7_1tdLf5LjCl3rfNKu8,12868
+jx/utils.py,sha256=dZMIAdVLdmkyPsiX14a9aIkZRfgAnf0SNEnvfyg8K98,669
+jx-0.2.0.dist-info/licenses/LICENSE,sha256=RHwNifuIFfQM9QUhA2FQfnqlBcnhBHlJEVp8QcRllew,1076
+jx-0.2.0.dist-info/METADATA,sha256=F0kiqI8PoNntEX_EuiOkdu9OzHbHiaYZ8eWsvAWZptA,2761
+jx-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+jx-0.2.0.dist-info/top_level.txt,sha256=P61YQxqfmzVpxTMe3C48gt0vc6fnHLF8Ml0JXC-QuEI,3
+jx-0.2.0.dist-info/RECORD,,

jx-0.1.0.dist-info/RECORD

@@ -1,13 +0,0 @@
-jx/__init__.py,sha256=MZ7KbNZkQx2D5CJpccSKuyJi179iAff3a9jG7DwEBAE,152
-jx/attrs.py,sha256=zjcZhaVxpgqE0nAE-kDDqKLG3J_AuZg_q4pk6iHy9FE,10054
-jx/catalog.py,sha256=0YDOz3QJnQC2MMCKfL_Zbkrff7CQaK4M-DCMh2lA6Cs,7037
-jx/component.py,sha256=Iv4ixTbof02N3cAXW6QcluoT30vFe3aHaRRWEJX1znw,5845
-jx/exceptions.py,sha256=rDWxkgOqeMPptmQ21joB2ujfpIU5EwMKtAL-ImB9nuA,1518
-jx/meta.py,sha256=8PWv09laXiIb-6rwcJ0KFT0rmuIpOfR59wiH_GZ1hZw,5131
-jx/parser.py,sha256=BlOcLH83A0xxbzQYijzbGukVpotDUg3uj32qTTLYxHc,7103
-jx/utils.py,sha256=UDuyu3pIXirct71XbTClhMFeMaHr2ujmcQ6s2tKGBrY,232
-jx-0.1.0.dist-info/licenses/LICENSE,sha256=RHwNifuIFfQM9QUhA2FQfnqlBcnhBHlJEVp8QcRllew,1076
-jx-0.1.0.dist-info/METADATA,sha256=DuJ03AieE3hsJMKN8SLtlIAeXqre4oypWAIvCA5CVa0,1674
-jx-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-jx-0.1.0.dist-info/top_level.txt,sha256=P61YQxqfmzVpxTMe3C48gt0vc6fnHLF8Ml0JXC-QuEI,3
-jx-0.1.0.dist-info/RECORD,,