jx 0.1.0__tar.gz → 0.3.0__tar.gz

jx-0.3.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: jx
+Version: 0.3.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: GitHub, https://github.com/jpsca/jx
+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.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jinja2>=3.0
+Dynamic: license-file
+
+<h1>
+  <img src="./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="./docs/python.svg">
+  <img alt="license: MIT" src="./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.3.0/README.md

@@ -0,0 +1,49 @@
+<h1>
+  <img src="./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="./docs/python.svg">
+  <img alt="license: MIT" src="./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.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ requires = ["setuptools"]
 
 [project]
 name = "jx"
-version = "0.1.0"
+version = "0.3.0"
 description = "Replace your HTML templates with Python server-Side components"
 authors = [
     {name = "Juan Pablo Scaletti", email = "juanpablo@jpscaletti.com"},
@@ -26,24 +26,24 @@ classifiers = [
     "Topic :: Text Processing :: Markup :: HTML",
     "Typing :: Typed",
 ]
-requires-python = ">=3.11,<4"
+requires-python = ">=3.12,<4"
 dependencies = [
     "jinja2 >= 3.0",
-    "markupsafe >= 2.0",
 ]
 
 [project.urls]
-homepage = "https://jx.scaletti.dev/"
-repository = "https://github.com/jpsca/jx"
-documentation = "https://jx.scaletti.dev/"
+Homepage = "https://jx.scaletti.dev/"
+GitHub = "https://github.com/jpsca/jx"
 
 [dependency-groups]
 dev = [
-    "ipdb >= 0.13",
+    "ipdb",
     "pre-commit",
-    "ruff >= 0.2.0",
     "tox-uv",
-    "ty>=0.0.1a15",
+    "ty",
+]
+docs = [
+    "writeadoc>=0.7.0",
 ]
 test = [
     "pytest >= 7.2",
@@ -81,10 +81,9 @@ addopts = "--doctest-modules"
 legacy_tox_ini = """
 [tox]
 env_list =
-    3.11
-    3.12
-    3.13
     3.14
+    3.13
+    3.12
 
 [testenv]
 runner = uv-venv-lock-runner
@@ -99,7 +98,7 @@ commands =
 [tool.ruff]
 line-length = 90
 indent-width = 4
-target-version = "py311"
+target-version = "py312"
 exclude = [
   ".*",
   "_build",

{jx-0.1.0 → jx-0.3.0}/src/jx/__init__.py

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

{jx-0.1.0 → jx-0.3.0}/src/jx/attrs.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 import UserString
 from functools import cached_property
@@ -14,10 +14,6 @@ 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:
@@ -30,14 +26,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,29 +41,36 @@ 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.
+    __classes: tuple[str, ...]
+    __attributes: dict[str, str | LazyString]
+    __properties: set[str]
 
-    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()
 
-        class_names = split(" ".join([
+        class_names = (" ".join([
             str(attrs.pop(CLASS_KEY, "")),
             str(attrs.get(CLASS_ALT_KEY, "")),
-        ]))
-        self.__classes = {name for name in class_names if name}
+        ])).strip().split()
+        classes = []
+        for name in class_names:
+            if name and name not in classes:
+                classes.append(name)
+        self.__classes = tuple(classes)
 
         for name, value in attrs.items():
             if name.startswith("_"):
@@ -85,19 +87,19 @@ class Attrs:
     @property
     def classes(self) -> str:
         """
-        All the HTML classes alphabetically sorted and separated by a space.
+        All the HTML classes separated by a space.
 
         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
+            italic bold bg-blue wide abcde text-white
             ```
 
         """
-        return " ".join(sorted((self.__classes)))
+        return " ".join(self.__classes)
 
     @property
     def as_dict(self) -> dict[str, t.Any]:
@@ -108,7 +110,7 @@ class Attrs:
         Example:
 
             ```python
-            attrs = HTMLAttrs({
+            attrs = Attrs({
             "class": "lorem ipsum",
             "data_test": True,
             "hidden": True,
@@ -118,7 +120,7 @@ class Attrs:
             attrs.as_dict
             {
                 "aria_label": "hello",
-                "class": "ipsum lorem",
+                "class": "lorem ipsum",
                 "id": "world",
                 "data_test": True,
                 "hidden": True
@@ -160,7 +162,7 @@ class Attrs:
         Example:
 
             ```python
-            attrs = HTMLAttrs({"secret": "qwertyuiop"})
+            attrs = Attrs({"secret": "qwertyuiop"})
             attrs.set(secret=False)
             attrs.as_dict
             {}
@@ -169,10 +171,10 @@ 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"}
+            {"class": "b c a f d e"}
             ```
 
         """
@@ -199,7 +201,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
@@ -212,7 +214,9 @@ class Attrs:
                 continue
 
             if name in CLASS_KEYS:
-                self.add_class(value)
+                if not self.__classes:
+                    self.add_class(value)
+                continue
 
             name = name.replace("_", "-")
             if name not in self.__attributes:
@@ -220,21 +224,55 @@ class Attrs:
 
     def add_class(self, *values: str) -> None:
         """
-        Adds one or more classes to the list of classes, if not already present.
+        Adds one or more classes to the end of 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.add_class("c", "d")
+            attrs = Attrs({"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)
+            for name in names.strip().split():
+                if name not in self.__classes:
+                    self.__classes += (name,)
+
+    def prepend_class(self, *values: str) -> None:
+        """
+        Adds one or more classes to the beginning of the list of classes,
+        if not already present.
+
+        Arguments:
+            values:
+                One or more class names to add, separated by spaces.
+
+        Example:
+
+            ```python
+            attrs = Attrs({"class": "a b c"})
+            attrs.add_class("c d |")
+            attrs.as_dict
+            {"class": "d | a b c"}
+            ```
+
+        """
+        new_classes = [
+            name
+            for names in values
+            for name in names.strip().split()
+            if name not in self.__classes
+        ]
+
+        self.__classes = tuple(new_classes) + self.__classes
 
     def remove_class(self, *names: str) -> None:
         """
@@ -243,25 +281,32 @@ 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"}
             ```
 
         """
-        for name in names:
-            self.__classes.remove(name)
+        self.__classes = tuple(c for c in self.__classes if c not in names)
 
     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.
 
+        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 +336,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 +353,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'
@@ -345,7 +390,7 @@ class Attrs:
         Removes an attribute or property.
         """
         if name in CLASS_KEYS:
-            self.__classes = set()
+            self.__classes = ()
         if name in self.__attributes:
             del self.__attributes[name]
         if name in self.__properties: