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

jx/catalog.py

@@ -1,6 +1,7 @@
 """
-Jx | Copyright (c) Juan-Pablo Scaletti <juanpablo@jpscaletti.com>
+Jx | Copyright (c) Juan-Pablo Scaletti
 """
+
 import typing as t
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -23,18 +24,18 @@ class CData:
     mtime: float
     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 }
+    optional: dict[str, t.Any] = field(default_factory=dict)  # { attr: default_value }
+    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 uses a LRU cache (to limit the memory used)
+    # or even a shared Redis/Memcache cache.
     components: dict[str, CData]
 
     def __init__(
@@ -42,14 +43,38 @@ class Catalog:
         folder: str | Path | None = None,
         *,
         jinja_env: jinja2.Environment | None = None,
+        extensions: list | 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.
+            jinja_env:
+                Optional Jinja2 environment to use for rendering.
+            extensions:
+                Optional extra Jinja2 extensions to add to the environment.
+            filters:
+                Optional extra Jinja2 filters to add to the environment.
+            tests:
+                Optional extra Jinja2 tests to add to the environment.
+            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
+                component that uses a large number of child components.
+            **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 +85,18 @@ 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 = "",
+        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 +107,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("./@ ")
@@ -143,16 +139,121 @@ class Catalog:
                 logger.debug(f"Component already exists: {relpath}")
                 continue
             cdata = CData(
-                base_path=base_path,
-                path=filepath,
-                mtime=filepath.stat().st_mtime
+                base_path=base_path, path=filepath, mtime=filepath.stat().st_mtime
             )
             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 render_string(
+        self, source: str, globals: dict[str, t.Any] | None = None, **kwargs
+    ) -> str:
+        """
+        Render a component from a string source.
+        Works like `render`, but the component is not cached and cannot do relative imports.
+
+        Arguments:
+            source:
+                The Jinja2 source code of the component to render.
+            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.
+
+        """
+        meta = extract_metadata(source, base_path=Path(), fullpath=Path())
+        name = "<string>"
+
+        parser = JxParser(name=name, source=source, components=list(meta.imports.keys()))
+        parsed_source, slots = parser.parse()
+
+        code = self.jinja_env.compile(source=parsed_source, name=name, filename=name)
+        tmpl = jinja2.Template.from_code(self.jinja_env, code, self.jinja_env.globals)
+
+        co = Component(
+            relpath=name,
+            tmpl=tmpl,
+            get_component=self.get_component,
+            required=meta.required,
+            optional=meta.optional,
+            imports=meta.imports,
+            css=meta.css,
+            js=meta.js,
+            slots=slots,
+        )
+
+        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.
+        If the file has been updated, the component is re-processed.
+
+        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)
@@ -169,15 +270,11 @@ class Catalog:
         meta = extract_metadata(source, base_path=cdata.base_path, fullpath=cdata.path)
 
         parser = JxParser(
-            name=relpath,
-            source=source,
-            components=list(meta.imports.keys())
+            name=relpath, 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,
-            filename=cdata.path.as_posix()
+            source=parsed_source, name=relpath, filename=cdata.path.as_posix()
         )
 
         cdata.code = code
@@ -186,15 +283,23 @@ 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(
-            self.jinja_env,
-            cdata.code,
-            self.jinja_env.globals
+            self.jinja_env, cdata.code, self.jinja_env.globals
         )
 
         co = Component(
@@ -203,25 +308,74 @@ 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.
+
+        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:
+            # It could be `jinja_env.overlay()` instead, but that might
+            # might lead to confusion if the user expects changes
+            # to the original environment to be reflected here.
+            env = jinja_env
+        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,
-            },
-        })
-        co.globals = globals
+        globals.update(
+            {
+                # A unique ID generator for HTML elements, see `utils.get_random_id`
+                # docstring for more information.
+                "_get_random_id": utils.get_random_id,
+            }
+        )
+        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

@@ -1,7 +1,7 @@
 """
-Jx | Copyright (c) Juan-Pablo Scaletti <juanpablo@jpscaletti.com>
+Jx | Copyright (c) Juan-Pablo Scaletti
 """
-import re
+
 import typing as t
 from collections.abc import Callable
 
@@ -12,9 +12,6 @@ from .attrs import Attrs
 from .exceptions import MissingRequiredArgument
 
 
-rx_external_url = re.compile(r"^[a-z]+://", re.IGNORECASE)
-
-
 class Component:
     __slots__ = (
         "relpath",
@@ -22,9 +19,10 @@ class Component:
         "get_component",
         "required",
         "optional",
+        "imports",
         "css",
         "js",
-        "imports",
+        "slots",
         "globals",
     )
 
@@ -36,19 +34,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 +81,10 @@ class Component:
         *,
         content: str | None = None,
         attrs: Attrs | dict[str, t.Any] | None = None,
-        caller: Callable[[], str] | None = None,
-        **params: t.Any
+        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 +93,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 +125,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 +167,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 +179,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 +206,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/exceptions.py

@@ -1,7 +1,8 @@
 """
-Jx | Copyright (c) Juan-Pablo Scaletti <juanpablo@jpscaletti.com>
+Jx | Copyright (c) Juan-Pablo Scaletti
 """
 
+
 class JxException(Exception):
     """Base class for all Jx exceptions."""
 
@@ -18,6 +19,7 @@ class ImportError(JxException):
     Raised when an import fails.
     This is usually caused by a missing or inaccessible component.
     """
+
     def __init__(self, relpath: str, **kw) -> None:
         msg = f"Component not found: {relpath}"
         super().__init__(msg, **kw)

jx/meta.py

@@ -1,6 +1,7 @@
 """
-Jx | Copyright (c) Juan-Pablo Scaletti <juanpablo@jpscaletti.com>
+Jx | Copyright (c) Juan-Pablo Scaletti
 """
+
 import ast
 import re
 import typing as t
@@ -56,12 +57,13 @@ def extract_metadata(source: str, base_path: Path, fullpath: Path) -> Meta:
         source:
             The template source code.
         base_path:
-            Absolute base path for all the template files
+            Absolute base path for all the template files, for relative imports.
         fullpath:
-            The absolute full path of the current template.
+            The absolute full path of the current template, for relative imports.
 
     Returns:
-        A Meta object containing the extracted metadata.
+        A `Meta` object containing the extracted metadata.
+
     """
     meta = Meta()
 
@@ -138,7 +140,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: