jx 0.1.0__tar.gz → 0.2.0__tar.gz

{jx-0.1.0/src/jx.egg-info → jx-0.2.0}/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,49 @@
+<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/ -->
+
+## 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.1.0 → jx-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ requires = ["setuptools"]
 
 [project]
 name = "jx"
-version = "0.1.0"
+version = "0.2.0"
 description = "Replace your HTML templates with Python server-Side components"
 authors = [
     {name = "Juan Pablo Scaletti", email = "juanpablo@jpscaletti.com"},
@@ -30,6 +30,7 @@ requires-python = ">=3.11,<4"
 dependencies = [
     "jinja2 >= 3.0",
     "markupsafe >= 2.0",
+    "ty>=0.0.1a15",
 ]
 
 [project.urls]

{jx-0.1.0 → jx-0.2.0}/src/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-0.1.0 → jx-0.2.0}/src/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