jx 0.1.0__py3-none-any.whl

jx/__init__.py

@@ -0,0 +1,5 @@
+"""
+Jx | Copyright (c) Juan-Pablo Scaletti <juanpablo@jpscaletti.com>
+"""
+from .catalog import CData, Catalog  # noqa
+from .exceptions import *  # noqa

jx/attrs.py

@@ -0,0 +1,352 @@
+"""
+Jx | Copyright (c) Juan-Pablo Scaletti <juanpablo@jpscaletti.com>
+"""
+import re
+import typing as t
+from collections import UserString
+from functools import cached_property
+
+from markupsafe import Markup
+
+
+CLASS_KEY = "class"
+CLASS_ALT_KEY = "classes"
+CLASS_KEYS = (CLASS_KEY, CLASS_ALT_KEY)
+
+
+def split(ssl: str) -> list[str]:
+    return re.split(r"\s+", ssl.strip())
+
+
+def quote(text: str) -> str:
+    if '"' in text:
+        if "'" in text:
+            text = text.replace('"', "&quot;")
+            return f'"{text}"'
+        else:
+            return f"'{text}'"
+
+    return f'"{text}"'
+
+
+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):
+        self._seq = seq
+
+    @cached_property
+    def data(self):  # type: ignore
+        return str(self._seq)
+
+
+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.
+
+    **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()
+
+        class_names = split(" ".join([
+            str(attrs.pop(CLASS_KEY, "")),
+            str(attrs.get(CLASS_ALT_KEY, "")),
+        ]))
+        self.__classes = {name for name in class_names if name}
+
+        for name, value in attrs.items():
+            if name.startswith("_"):
+                continue
+            name = name.replace("_", "-")
+            if value is True:
+                properties.add(name)
+            elif value is not False and value is not None:
+                attributes[name] = LazyString(value)
+
+        self.__attributes = attributes
+        self.__properties = properties
+
+    @property
+    def classes(self) -> str:
+        """
+        All the HTML classes alphabetically sorted and separated by a space.
+
+        Example:
+
+            ```python
+            attrs = HTMLAttrs({"class": "italic bold bg-blue wide abcde"})
+            attrs.set(class="bold text-white")
+            print(attrs.classes)
+            abcde bg-blue bold italic text-white wide
+            ```
+
+        """
+        return " ".join(sorted((self.__classes)))
+
+    @property
+    def as_dict(self) -> dict[str, t.Any]:
+        """
+        An ordered dict of all the attributes and properties, both
+        sorted by name before join.
+
+        Example:
+
+            ```python
+            attrs = HTMLAttrs({
+            "class": "lorem ipsum",
+            "data_test": True,
+            "hidden": True,
+            "aria_label": "hello",
+            "id": "world",
+            })
+            attrs.as_dict
+            {
+                "aria_label": "hello",
+                "class": "ipsum lorem",
+                "id": "world",
+                "data_test": True,
+                "hidden": True
+            }
+            ```
+
+        """
+        attributes = self.__attributes.copy()
+        classes = self.classes
+        if classes:
+            attributes[CLASS_KEY] = classes
+
+        out: dict[str, t.Any] = dict(sorted(attributes.items()))
+        for name in sorted((self.__properties)):
+            out[name] = True
+        return out
+
+    def __getitem__(self, name: str) -> t.Any:
+        return self.get(name)
+
+    def __delitem__(self, name: str) -> None:
+        self._remove(name)
+
+    def __str__(self) -> str:
+        return str(self.as_dict)
+
+    def set(self, **kw) -> None:
+        """
+        Sets an attribute or property
+
+        - 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`)
+        - Use `False` to remove an attribute or property
+        - If the attribute is "class", the new classes are appended to
+          the old ones (if not repeated) instead of replacing them.
+        - The underscores in the names will be translated automatically to dashes,
+          so `aria_selected` becomes the attribute `aria-selected`.
+
+        Example:
+
+            ```python
+            attrs = HTMLAttrs({"secret": "qwertyuiop"})
+            attrs.set(secret=False)
+            attrs.as_dict
+            {}
+
+            attrs.set(unknown=False, lorem="ipsum", count=42, data_good=True)
+            attrs.as_dict
+            {"count":42, "lorem":"ipsum", "data_good": True}
+
+            attrs = HTMLAttrs({"class": "b c a"})
+            attrs.set(class="c b f d e")
+            attrs.as_dict
+            {"class": "a b c d e f"}
+            ```
+
+        """
+        for name, value in kw.items():
+            name = name.replace("_", "-")
+            if value is False or value is None:
+                self._remove(name)
+                continue
+
+            if name in CLASS_KEYS:
+                self.add_class(value)
+            elif value is True:
+                self.__properties.add(name)
+            else:
+                self.__attributes[name] = value
+
+    def setdefault(self, **kw) -> None:
+        """
+        Adds an attribute, but only if it's not already present.
+
+        The underscores in the names will be translated automatically to dashes,
+        so `aria_selected` becomes the attribute `aria-selected`.
+
+        Example:
+
+            ```python
+            attrs = HTMLAttrs({"lorem": "ipsum"})
+            attrs.setdefault(tabindex=0, lorem="meh")
+            attrs.as_dict
+            # "tabindex" changed but "lorem" didn't
+            {"lorem": "ipsum", tabindex: 0}
+            ```
+
+        """
+        for name, value in kw.items():
+            if value in (True, False, None):
+                continue
+
+            if name in CLASS_KEYS:
+                self.add_class(value)
+
+            name = name.replace("_", "-")
+            if name not in self.__attributes:
+                self.set(**{name: value})
+
+    def add_class(self, *values: str) -> None:
+        """
+        Adds one or more classes to the list of classes, if not already present.
+
+        Example:
+
+            ```python
+            attrs = HTMLAttrs({"class": "a b c"})
+            attrs.add_class("c", "d")
+            attrs.as_dict
+            {"class": "a b c d"}
+            ```
+
+        """
+        for names in values:
+            for name in split(names):
+                self.__classes.add(name)
+
+    def remove_class(self, *names: str) -> None:
+        """
+        Removes one or more classes from the list of classes.
+
+        Example:
+
+            ```python
+            attrs = HTMLAttrs({"class": "a b c"})
+            attrs.remove_class("c", "d")
+            attrs.as_dict
+            {"class": "a b"}
+            ```
+
+        """
+        for name in names:
+            self.__classes.remove(name)
+
+    def get(self, name: str, default: t.Any = None) -> t.Any:
+        """
+        Returns the value of the attribute or property,
+        or the default value if it doesn't exists.
+
+        Example:
+
+            ```python
+            attrs = HTMLAttrs({"lorem": "ipsum", "hidden": True})
+
+            attrs.get("lorem", defaut="bar")
+            'ipsum'
+
+            attrs.get("foo")
+            None
+
+            attrs.get("foo", defaut="bar")
+            'bar'
+
+            attrs.get("hidden")
+            True
+            ```
+
+        """
+        name = name.replace("_", "-")
+        if name in CLASS_KEYS:
+            return self.classes
+        if name in self.__attributes:
+            return self.__attributes[name]
+        if name in self.__properties:
+            return True
+        return default
+
+    def render(self, **kw) -> str:
+        """
+        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:
+
+        - 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`)
+        - Use `False` to remove an attribute or property
+        - If the attribute is "class", the new classes are appended to
+          the old ones (if not repeated) instead of replacing them.
+        - The underscores in the names will be translated automatically to dashes,
+          so `aria_selected` becomes the attribute `aria-selected`.
+
+        To provide consistent output, the attributes and properties
+        are sorted by name and rendered like this:
+        `<sorted attributes> + <sorted properties>`.
+
+        Example:
+
+            ```python
+            attrs = HTMLAttrs({"class": "ipsum", "data_good": True, "width": 42})
+
+            attrs.render()
+            'class="ipsum" width="42" data-good'
+
+            attrs.render(class="abc", data_good=False, tabindex=0)
+            'class="abc ipsum" width="42" tabindex="0"'
+            ```
+
+        """
+        if kw:
+            self.set(**kw)
+
+        attributes = self.__attributes.copy()
+
+        classes = self.classes
+        if classes:
+            attributes[CLASS_KEY] = classes
+
+        attributes = dict(sorted(attributes.items()))
+        properties = sorted((self.__properties))
+
+        html_attrs = [
+            f"{name}={quote(str(value))}"
+            for name, value in attributes.items()
+        ]
+        html_attrs.extend(properties)
+
+        return Markup(" ".join(html_attrs))
+
+    # Private
+
+    def _remove(self, name: str) -> None:
+        """
+        Removes an attribute or property.
+        """
+        if name in CLASS_KEYS:
+            self.__classes = set()
+        if name in self.__attributes:
+            del self.__attributes[name]
+        if name in self.__properties:
+            self.__properties.remove(name)

jx/catalog.py

@@ -0,0 +1,227 @@
+"""
+Jx | Copyright (c) Juan-Pablo Scaletti <juanpablo@jpscaletti.com>
+"""
+import typing as t
+from dataclasses import dataclass, field
+from pathlib import Path
+from types import CodeType
+
+import jinja2
+
+from . import utils
+from .component import Component
+from .exceptions import ImportError
+from .meta import extract_metadata
+from .parser import JxParser
+from .utils import logger
+
+
+@dataclass(slots=True)
+class CData:
+    base_path: Path
+    path: Path
+    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 }
+    css: tuple[str, ...] = ()
+    js: tuple[str, ...] = ()
+
+
+class Catalog:
+    """
+    The object that manages the components and their global settings.
+
+    Arguments:
+    """
+    components: dict[str, CData]
+
+    def __init__(
+        self,
+        folder: str | Path | None = None,
+        *,
+        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:
+        self.components = {}
+        self.jinja_env = self.make_jinja_env(
+            jinja_env=jinja_env,
+            globals=globals,
+            filters=filters,
+            tests=tests,
+            extensions=extensions,
+        )
+        self.auto_reload = auto_reload
+        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 = "",
+    ) -> 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`.
+
+        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
+        import can also be used, e.g.: `./component.jinja`.
+
+        All the folders added under the same prefix will be treated as if they
+        were a single folder. This means if you add two folders, under the same prefix,
+        with a component with the same subpath/filename, the one in the folder
+        added **first** will be used and the other ignored.
+
+        """
+        base_path = Path(path).resolve()
+        prefix = prefix.replace("\\", "/").strip("./@ ")
+        prefix = f"@{prefix}/" if prefix else ""
+        if prefix:
+            logger.debug(f"Adding folder `{base_path}` with the prefix `{prefix}`")
+        else:
+            logger.debug(f"Adding folder `{base_path}`")
+
+        for filepath in base_path.rglob("*.jinja"):
+            relpath = f"{prefix}{filepath.relative_to(base_path).as_posix()}"
+            if relpath in self.components:
+                logger.debug(f"Component already exists: {relpath}")
+                continue
+            cdata = CData(
+                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)
+
+    def get_component_data(self, relpath: str) -> CData:
+        cdata = self.components.get(relpath)
+        if not cdata:
+            raise ImportError(relpath)
+
+        mtime = cdata.path.stat().st_mtime if self.auto_reload else 0
+        if cdata.code is not None:
+            if self.auto_reload:
+                if mtime == cdata.mtime:
+                    return cdata
+            else:
+                return cdata
+
+        source = cdata.path.read_text()
+        meta = extract_metadata(source, base_path=cdata.base_path, fullpath=cdata.path)
+
+        parser = JxParser(
+            name=relpath,
+            source=source,
+            components=list(meta.imports.keys())
+        )
+        parsed_source = parser.parse()
+        code = self.jinja_env.compile(
+            source=parsed_source,
+            name=relpath,
+            filename=cdata.path.as_posix()
+        )
+
+        cdata.code = code
+        cdata.required = meta.required
+        cdata.optional = meta.optional
+        cdata.imports = meta.imports
+        cdata.css = meta.css
+        cdata.js = meta.js
+        return cdata
+
+    def get_component(self, relpath: str) -> Component:
+        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
+        )
+
+        co = Component(
+            relpath=relpath,
+            tmpl=tmpl,
+            get_component=self.get_component,
+            required=cdata.required,
+            optional=cdata.optional,
+            css=cdata.css,
+            js=cdata.js,
+            imports=cdata.imports
+        )
+        return co
+
+    def render(self, relpath: str, globals: dict[str, t.Any] | None = None, **kwargs) -> str:
+        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)

jx/component.py

@@ -0,0 +1,181 @@
+"""
+Jx | Copyright (c) Juan-Pablo Scaletti <juanpablo@jpscaletti.com>
+"""
+import re
+import typing as t
+from collections.abc import Callable
+
+import jinja2
+from markupsafe import Markup
+
+from .attrs import Attrs
+from .exceptions import MissingRequiredArgument
+
+
+rx_external_url = re.compile(r"^[a-z]+://", re.IGNORECASE)
+
+
+class Component:
+    __slots__ = (
+        "relpath",
+        "tmpl",
+        "get_component",
+        "required",
+        "optional",
+        "css",
+        "js",
+        "imports",
+        "globals",
+    )
+
+    def __init__(
+        self,
+        *,
+        relpath: str,
+        tmpl: jinja2.Template,
+        get_component: Callable[[str], "Component"],
+        required: tuple[str, ...] = (),
+        optional: dict[str, t.Any] | None = None,
+        css: tuple[str, ...] = (),
+        js: tuple[str, ...] = (),
+        imports: dict[str, str] | None = None,
+    ) -> None:
+        self.relpath = relpath
+        self.tmpl = tmpl
+        self.get_component = get_component
+
+        self.required = required
+        self.optional = optional or {}
+        self.css = css
+        self.js = js
+        self.imports = imports or {}
+
+        self.globals: dict[str, t.Any] = {}
+
+    def render(
+        self,
+        *,
+        content: str | None = None,
+        attrs: Attrs | dict[str, t.Any] | None = None,
+        caller: Callable[[], str] | None = None,
+        **params: t.Any
+    ) -> Markup:
+        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)
+
+        globals = {**self.globals, "_get": self.get_child}
+        globals.setdefault("attrs", Attrs(attrs))
+        globals.setdefault("content", content)
+
+        html = self.tmpl.render({**props, **globals}).lstrip()
+        return Markup(html)
+
+    def filter_attrs(
+        self, kw: dict[str, t.Any]
+    ) -> tuple[dict[str, t.Any], dict[str, t.Any]]:
+        props = {}
+
+        for key in self.required:
+            if key not in kw:
+                raise MissingRequiredArgument(self.relpath, key)
+            props[key] = kw.pop(key)
+
+        for key in self.optional:
+            props[key] = kw.pop(key, self.optional[key])
+        extra = kw.copy()
+        return props, extra
+
+    def get_child(self, name: str) -> "Component":
+        relpath = self.imports[name]
+        child = self.get_component(relpath)
+        child.globals = self.globals
+        return child
+
+    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)
+
+        for name, relpath in self.imports.items():
+            if relpath in visited:
+                continue
+            co = self.get_child(name)
+            for file in co.collect_css(visited=visited):
+                if file not in urls:
+                    urls[file] = 1
+            visited.add(relpath)
+
+        return list(urls.keys())
+
+    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)
+
+        for name, relpath in self.imports.items():
+            if relpath in visited:
+                continue
+            co = self.get_child(name)
+            for file in co.collect_js(visited=visited):
+                if file not in urls:
+                    urls[file] = 1
+            visited.add(relpath)
+
+        return list(urls.keys())
+
+    def render_css(self) -> Markup:
+        """
+        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():
+            html.append(f'<link rel="stylesheet" href="{url}">')
+
+        return Markup("\n".join(html))
+
+    def render_js(self, module: bool = True, defer: bool = True) -> Markup:
+        """
+        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`.
+        """
+        html = []
+        for url in self.collect_js():
+            if module:
+                tag = f'<script type="module" src="{url}"></script>'
+            elif defer:
+                tag = f'<script src="{url}" defer></script>'
+            else:
+                tag = f'<script src="{url}"></script>'
+            html.append(tag)
+
+        return Markup("\n".join(html))
+
+    def render_assets(self, module: bool = True, defer: bool = False) -> Markup:
+        """
+        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`.
+        """
+        html_css = self.render_css()
+        html_js = self.render_js()
+        return Markup(("\n".join([html_css, html_js]).strip()))

jx/exceptions.py

@@ -0,0 +1,57 @@
+"""
+Jx | Copyright (c) Juan-Pablo Scaletti <juanpablo@jpscaletti.com>
+"""
+
+class JxException(Exception):
+    """Base class for all Jx exceptions."""
+
+
+class TemplateSyntaxError(JxException):
+    """
+    Raised when the template syntax is invalid.
+    This is usually caused by a missing or extra closing tag.
+    """
+
+
+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)
+
+
+class MissingRequiredArgument(JxException):
+    """
+    Raised when a component is used/invoked without passing one or more
+    of its required arguments (those without a default value).
+    """
+
+    def __init__(self, component: str, arg: str, **kw) -> None:
+        msg = f"{component} component requires a `{arg}` argument"
+        super().__init__(msg, **kw)
+
+
+class DuplicateDefDeclaration(JxException):
+    """
+    Raised when a component has more then one `{#def ... #}` declarations.
+    """
+
+    def __init__(self, component: str, **kw) -> None:
+        msg = f"{component} has two `{{#def ... #}}` declarations"
+        super().__init__(msg, **kw)
+
+
+class InvalidArgument(JxException):
+    """
+    Raised when the arguments passed to the component cannot be parsed
+    because of an invalid syntax.
+    """
+
+
+class InvalidImport(JxException):
+    """
+    Raised when the import cannot be parsed
+    """

jx/meta.py

@@ -0,0 +1,166 @@
+"""
+Jx | Copyright (c) Juan-Pablo Scaletti <juanpablo@jpscaletti.com>
+"""
+import ast
+import re
+import typing as t
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .exceptions import DuplicateDefDeclaration, InvalidArgument, InvalidImport
+from .parser import re_tag_name
+
+
+# This regexp matches the meta declarations (`{#def .. #}``, `{#css .. #}``,
+# and `{#js .. #}`) and regular Jinja comments AT THE BEGINNING of the components source.
+# You can also have comments inside the declarations.
+RX_META_HEADER = re.compile(r"^(\s*{#.*?#})+", re.DOTALL)
+
+# This regexep matches comments (everything after a `#`)
+# Used to remove them from inside meta declarations
+RX_INTER_COMMENTS = re.compile(r"\s*#[^\n]*")
+
+RX_DEF_START = re.compile(r"{#-?\s*def\s+")
+RX_IMPORT_START = re.compile(r"{#-?\s*import\s+")
+RX_CSS_START = re.compile(r"{#-?\s*css\s+")
+RX_JS_START = re.compile(r"{#-?\s*js\s+")
+RX_COMMA = re.compile(r"\s*,\s*")
+RX_IMPORT = re.compile(fr'"([^"]+)"\s+as\s+({re_tag_name})')
+
+ALLOWED_NAMES_IN_EXPRESSION_VALUES = {
+    "len": len,
+    "max": max,
+    "min": min,
+    "pow": pow,
+    "sum": sum,
+    # Jinja allows using lowercase booleans, so we do it too for consistency
+    "false": False,
+    "true": True,
+}
+
+
+@dataclass(slots=True)
+class Meta:
+    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 }
+    css: tuple[str, ...] = ()
+    js: tuple[str, ...] = ()
+
+
+def extract_metadata(source: str, base_path: Path, fullpath: Path) -> Meta:
+    """
+    Extract metadata from the Jx template source.
+
+    Arguments:
+        source:
+            The template source code.
+        base_path:
+            Absolute base path for all the template files
+        fullpath:
+            The absolute full path of the current template.
+
+    Returns:
+        A Meta object containing the extracted metadata.
+    """
+    meta = Meta()
+
+    match = RX_META_HEADER.match(source)
+    if not match:
+        return meta
+
+    header = match.group(0)
+    # Reversed because I will use `header.pop()`
+    header = header.split("#}")[:-1][::-1]
+    def_found = False
+
+    while header:
+        item = header.pop().strip(" -\n")
+
+        expr = read_metadata_item(item, RX_DEF_START)
+        if expr:
+            if def_found:
+                raise DuplicateDefDeclaration(str(fullpath))
+            meta.required, meta.optional = parse_args_expr(expr)
+            def_found = True
+            continue
+
+        expr = read_metadata_item(item, RX_IMPORT_START)
+        if expr:
+            expr = RX_INTER_COMMENTS.sub("", expr).replace("\n", " ")
+            import_path, import_name = parse_import_expr(expr)
+            if import_path.startswith("."):
+                import_path = (fullpath.parent / import_path).resolve().relative_to(base_path).as_posix()
+            meta.imports[import_name] = import_path
+            continue
+
+        expr = read_metadata_item(item, RX_CSS_START)
+        if expr:
+            expr = RX_INTER_COMMENTS.sub("", expr).replace("\n", " ")
+            meta.css = (*meta.css, *parse_files_expr(expr))
+            continue
+
+        expr = read_metadata_item(item, RX_JS_START)
+        if expr:
+            expr = RX_INTER_COMMENTS.sub("", expr).replace("\n", " ")
+            meta.js = (*meta.js, *parse_files_expr(expr))
+            continue
+
+    return meta
+
+
+def read_metadata_item(source: str, rx_start: re.Pattern) -> str:
+    start = rx_start.match(source)
+    if not start:
+        return ""
+    return source[start.end():].strip()
+
+
+def parse_args_expr(expr: str) -> tuple[tuple[str, ...], dict[str, t.Any]]:
+    expr = expr.strip(" *,/")
+    required = []
+    optional = {}
+
+    try:
+        p = ast.parse(f"def component(*,\n{expr}\n): pass")
+    except SyntaxError as err:
+        raise InvalidArgument(err) from err
+
+    args = p.body[0].args  # type: ignore
+    arg_names = [arg.arg for arg in args.kwonlyargs]
+    for name, value in zip(arg_names, args.kw_defaults):  # noqa: B905
+        if value is None:
+            required.append(name)
+            continue
+        expr = ast.unparse(value)
+        optional[name] = eval_expression(expr)
+
+    return tuple(required), optional
+
+
+def eval_expression(input_string):
+    code = compile(input_string, "<string>", "eval")
+    for name in code.co_names:
+        if name not in ALLOWED_NAMES_IN_EXPRESSION_VALUES:
+            raise InvalidArgument(f"Use of {name} not allowed")
+    return eval(code, {"__builtins__": {}}, ALLOWED_NAMES_IN_EXPRESSION_VALUES)
+
+
+def parse_files_expr(expr: str) -> list[str]:
+    files = []
+    for url in RX_COMMA.split(expr):
+        url = url.strip("\"'").rstrip("/")
+        if not url:
+            continue
+        if url.startswith(("/", "http://", "https://")):
+            files.append(url)
+        else:
+            files.append(url)
+    return files
+
+
+def parse_import_expr(expr: str) -> tuple[str, str]:
+    match = RX_IMPORT.match(expr)
+    if not match:
+        raise InvalidImport(expr)
+    return match.group(1), match.group(2)

jx/parser.py

@@ -0,0 +1,215 @@
+"""
+Jx | Copyright (c) Juan-Pablo Scaletti <juanpablo@jpscaletti.com>
+"""
+import re
+import typing as t
+from uuid import uuid4
+
+from markupsafe import Markup
+
+from .exceptions import TemplateSyntaxError
+from .utils import logger
+
+
+BLOCK_CALL = '{% call _get("[TAG]").render([ATTRS]) -%}[CONTENT]{%- endcall %}'
+INLINE_CALL = '{{ _get("[TAG]").render([ATTRS]) }}'
+
+re_raw = r"\{%-?\s*raw\s*-?%\}.+?\{%-?\s*endraw\s*-?%\}"
+RX_RAW = re.compile(re_raw, re.DOTALL)
+
+re_tag_name = r"[A-Z][0-9A-Za-z_.:$-]*"
+RX_TAG_NAME = re.compile(rf"<(?P<tag>{re_tag_name})(\s|\n|/|>)")
+
+re_attr_name = r""
+re_equal = r""
+re_attr = r"""
+(?P<name>[:a-zA-Z@$_][a-zA-Z@:$_0-9-]*)
+(?:
+    \s*=\s*
+    (?P<value>".*?"|'.*?'|\{\{.*?\}\})
+)?
+(?:\s+|/|"|$)
+"""
+RX_ATTR = re.compile(re_attr, re.VERBOSE | re.DOTALL)
+
+
+def escape(s: t.Any, /) -> Markup:
+    return Markup(
+        str(s)
+        .replace("&", "&amp;")
+        .replace(">", "&gt;")
+        .replace("<", "&lt;")
+        .replace("'", "&#39;")
+        .replace('"', "&#34;")
+    )
+
+
+class JxParser:
+    def __init__(self, *, name: str, source: str, components: list[str]) :
+        self.name = name
+        self.source = source
+        self.components = components
+
+    def parse(self, *, validate_tags: bool = True) -> str:
+        raw_blocks = {}
+        source = self.source
+        source, raw_blocks = self.replace_raw_blocks(source)
+        source = self.process_tags(source, validate_tags=validate_tags)
+        source = self.restore_raw_blocks(source, raw_blocks)
+        return source
+
+    def replace_raw_blocks(self, source: str) -> tuple[str, dict[str, str]]:
+        raw_blocks = {}
+        while True:
+            match = RX_RAW.search(source)
+            if not match:
+                break
+            start, end = match.span(0)
+            repl = escape(match.group(0))
+            key = f"--RAW-{uuid4().hex}--"
+            raw_blocks[key] = repl
+            source = f"{source[:start]}{key}{source[end:]}"
+
+        return source, raw_blocks
+
+    def restore_raw_blocks(self, source: str, raw_blocks: dict[str, str]) -> str:
+        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:
+        while True:
+            match = RX_TAG_NAME.search(source)
+            if not match:
+                break
+            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:
+        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}")
+
+        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}")
+
+        inline = source[end - 2:end] == "/>"
+        if inline:
+            content = ""
+        else:
+            close_tag = f"</{tag}>"
+            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}")
+
+            content = source[end:index]
+            end = index + len(close_tag)
+
+        attrs_list = self._parse_attrs(attrs)
+        repl = self._build_call(tag, attrs_list, content)
+
+        return f"{source[:start]}{repl}{source[end:]}"
+
+    def _parse_opening_tag(self, source: str, *, lineno: int, start: int) -> tuple[str, int]:
+        eof = len(source)
+        in_single_quotes = in_double_quotes = in_braces = False   # dentro de '…'  /  "…"
+        i = start
+        end = -1
+
+        while i < eof:
+            ch = source[i]
+            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")
+                    in_braces = True
+                    i += 2
+                    continue
+
+                if ch2 == "}}":
+                    if not in_braces:
+                        raise TemplateSyntaxError(f"[{self.name}:{lineno}] Unmatched braces")
+                    in_braces = False
+                    i += 2
+                    continue
+
+            if ch == "'" and not in_double_quotes:
+                in_single_quotes = not in_single_quotes
+                i += 1
+                continue
+
+            if ch == '"' and not in_single_quotes:
+                in_double_quotes = not in_double_quotes
+                i += 1
+                continue
+
+            # End of the tag: ‘>’ outside of quotes and outside of {{ … }}
+            if ch == ">" and not (in_single_quotes or in_double_quotes or in_braces):
+                end = i + 1
+                break
+
+            i += 1
+
+        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:
+            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:
+            name = name.strip().replace("-", "_")
+            value = value.strip()
+
+            if not value:
+                attrs.append(f'"{name}"=True')
+            else:
+                # vue-like syntax
+                # if (
+                #     name[0] == ":"
+                #     and value[0] in ("\"'")
+                #     and value[-1] in ("\"'")
+                # ):
+                #     value = value[1:-1].strip()
+                #     name = name.lstrip(":")
+
+                # double curly braces syntax
+                if value[:2] == "{{" and value[-2:] == "}}":
+                    value = value[2:-2].strip()
+
+                attrs.append(f'"{name}"={value}')
+
+        str_attrs = ""
+        if attrs:
+            str_attrs = "**{" + ", ".join([a.replace("=", ":", 1) for a in attrs]) + "}"
+
+        if content:
+            return (
+                BLOCK_CALL
+                .replace("[TAG]", tag)
+                .replace("[ATTRS]", str_attrs)
+                .replace("[CONTENT]", content)
+            )
+        else:
+            return INLINE_CALL.replace("[TAG]", tag).replace("[ATTRS]", str_attrs)

jx/utils.py

@@ -0,0 +1,13 @@
+"""
+Jx | Copyright (c) Juan-Pablo Scaletti <juanpablo@jpscaletti.com>
+"""
+import logging
+import uuid
+
+
+logger = logging.getLogger("jx")
+
+
+def get_random_id(prefix: str = "id") -> str:
+    return f"{prefix}-{str(uuid.uuid4().hex)}"
+

jx-0.1.0.dist-info/METADATA

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: jx
+Version: 0.1.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/
+Project-URL: repository, https://github.com/jpsca/jx
+Project-URL: documentation, https://jx.scaletti.dev/
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Classifier: Typing :: Typed
+Requires-Python: <4,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jinja2>=3.0
+Requires-Dist: markupsafe>=2.0
+Dynamic: license-file
+
+<h1>
+  <img src="https://github.com/jpsca/jx/raw/main/docs/logo-jx.png" height="100" align="top">
+</h1>
+
+Super components powers for your Jinja templates.
+
+<p>
+  <img alt="python: 3.11, 3.12, 3.13, 3.14" src="https://github.com/jpsca/jx/raw/main/docs/python.svg">
+  <img alt="license: MIT" src="https://github.com/jpsca/jx/raw/main/docs/license.svg">
+</p>
+
+From chaos to clarity: The power of components in your server-side-rendered Python web app.
+
+<!-- Documentation: https://jx.scaletti.dev/ -->

jx-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+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,,

jx-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

jx-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Juan-Pablo Scaletti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jx-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+jx