jx 0.5.0__tar.gz → 0.6.0__tar.gz

{jx-0.5.0/src/jx.egg-info → jx-0.6.0}/PKG-INFO

@@ -1,8 +1,9 @@
 Metadata-Version: 2.4
 Name: jx
-Version: 0.5.0
+Version: 0.6.0
 Summary: Replace your HTML templates with Python server-Side components
 Author-email: Juan Pablo Scaletti <juanpablo@jpscaletti.com>
+License-Expression: MIT
 Project-URL: Code, https://github.com/jpsca/jx
 Project-URL: Documentation, https://jx.scaletti.dev/
 Classifier: Development Status :: 4 - Beta

{jx-0.5.0 → jx-0.6.0}/pyproject.toml

@@ -4,12 +4,12 @@ requires = ["setuptools"]
 
 [project]
 name = "jx"
-version = "0.5.0"
+version = "0.6.0"
 description = "Replace your HTML templates with Python server-Side components"
 authors = [
     {name = "Juan Pablo Scaletti", email = "juanpablo@jpscaletti.com"},
 ]
-license = { "file" = "MIT-LICENSE" }
+license = "MIT"
 readme = "README.md"
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -31,6 +31,9 @@ dependencies = [
     "jinja2 >= 3.0",
 ]
 
+[project.scripts]
+jx = "jx.cli:main"
+
 [project.urls]
 Code = "https://github.com/jpsca/jx"
 Documentation = "https://jx.scaletti.dev/"
@@ -43,7 +46,7 @@ dev = [
     "ty",
 ]
 docs = [
-    "writeadoc>=0.7.0",
+    "writeadoc>=0.14",
 ]
 test = [
     "pytest >= 7.2",
@@ -58,7 +61,9 @@ where = ["src"]
 
 [tool.ty.src]
 exclude = [
+    "benchmark",
     "docs",
+    "tests",
 ]
 
 

{jx-0.5.0 → jx-0.6.0}/src/jx/attrs.py

@@ -36,7 +36,7 @@ class LazyString(UserString):
         self._seq = seq
 
     @cached_property
-    def data(self):  # type: ignore
+    def data(self):
         return str(self._seq)
 
 

{jx-0.5.0 → jx-0.6.0}/src/jx/catalog.py

@@ -2,6 +2,7 @@
 Jx | Copyright (c) Juan-Pablo Scaletti
 """
 
+import threading
 import typing as t
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -11,7 +12,7 @@ import jinja2
 
 from . import utils
 from .component import Component
-from .exceptions import ImportError
+from .exceptions import FileEncodingError, ImportError
 from .meta import extract_metadata
 from .parser import JxParser
 from .utils import logger
@@ -23,8 +24,8 @@ class CData:
     path: Path
     mtime: float
     code: CodeType | None = None
-    required: tuple[str, ...] = ()
-    optional: dict[str, t.Any] = field(default_factory=dict)  # { attr: default_value }
+    required: dict[str, type | None] = field(default_factory=dict)  # { attr: type or None }
+    optional: dict[str, tuple[t.Any, type | None]] = field(default_factory=dict)  # { attr: (default, type or None) }
     imports: dict[str, str] = field(default_factory=dict)  # { name: relpath }
     css: tuple[str, ...] = ()
     js: tuple[str, ...] = ()
@@ -73,6 +74,7 @@ class Catalog:
                 Variables to make available to all components by default.
 
         """
+        self._lock = threading.RLock()  # Protects self.components access
         self.components = {}
         self.jinja_env = self._make_jinja_env(
             jinja_env=jinja_env,
@@ -97,8 +99,8 @@ class Catalog:
 
         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
+        Components added with a prefix must be imported using the `@prefix/`
+        syntax: `@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`.
 
@@ -133,19 +135,25 @@ class Catalog:
         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
-
+        with self._lock:
+            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
+
+            if preload:
+                # Take a snapshot of keys to avoid "dict changed size during iteration"
+                relpaths = list(self.components.keys())
+
+        # Preload outside the lock to avoid holding it during compilation
         if preload:
-            for relpath in self.components:
-                self.components[relpath] = self.get_component_data(relpath)
+            for relpath in relpaths:
+                self.get_component_data(relpath)
 
     def render(
         self, relpath: str, globals: dict[str, t.Any] | None = None, **kwargs
@@ -172,17 +180,15 @@ class Catalog:
         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,
-                },
+        globals.update({
+            "assets": {
+                "collect_css": co.collect_css,
+                "collect_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)
@@ -254,37 +260,46 @@ class Catalog:
                 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)
-
-        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:
+        with self._lock:
+            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
-            else:
-                return cdata
 
-        source = cdata.path.read_text()
-        meta = extract_metadata(source, base_path=cdata.base_path, fullpath=cdata.path)
+            # Need to recompile - read file and parse while holding the lock
+            # to prevent other threads from seeing partial state
+            try:
+                source = cdata.path.read_text(encoding="utf-8")
+            except UnicodeDecodeError as err:
+                raise FileEncodingError(cdata.path.as_posix()) from err
+            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, slots = parser.parse()
-        code = self.jinja_env.compile(
-            source=parsed_source, name=relpath, filename=cdata.path.as_posix()
-        )
+            parser = JxParser(
+                name=relpath, source=source, components=list(meta.imports.keys())
+            )
+            parsed_source, slots = parser.parse()
+            logger.debug(f"Parsed {relpath}:\n{parsed_source}")
+            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
-        cdata.slots = slots
-        return cdata
+            # Update all fields atomically (from other threads' perspective)
+            cdata.mtime = mtime
+            cdata.code = code
+            cdata.required = meta.required
+            cdata.optional = meta.optional
+            cdata.imports = meta.imports
+            cdata.css = meta.css
+            cdata.js = meta.js
+            cdata.slots = slots
+            return cdata
 
     def get_component(self, relpath: str) -> Component:
         """
@@ -296,24 +311,63 @@ class Catalog:
                 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
-        )
+        with self._lock:
+            cdata = self.get_component_data(relpath)
+            assert cdata.code is not None  # for type checker
+            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,
-            imports=cdata.imports,
-            css=cdata.css,
-            js=cdata.js,
-            slots=cdata.slots,
-        )
-        return co
+            co = Component(
+                relpath=relpath,
+                tmpl=tmpl,
+                get_component=self.get_component,
+                required=cdata.required,
+                optional=cdata.optional,
+                imports=cdata.imports,
+                css=cdata.css,
+                js=cdata.js,
+                slots=cdata.slots,
+            )
+            return co
+
+    def list_components(self) -> list[str]:
+        """
+        Return all registered component paths.
+
+        Returns:
+            A list of component relative paths (e.g., ["button.jinja", "card.jinja"]).
+
+        """
+        with self._lock:
+            return list(self.components.keys())
+
+    def get_signature(self, relpath: str) -> dict[str, t.Any]:
+        """
+        Return a component's signature including its arguments and metadata.
+
+        Arguments:
+            relpath:
+                The path of the component, including the extension, relative to its view folder.
+                e.g.: "sub/component.jinja". Always use the forward slash (/) as the path separator.
+
+        Returns:
+            A dictionary containing:
+                - required: dict of required argument names mapped to their type (or None)
+                - optional: dict of optional arguments mapped to (default_value, type or None)
+                - slots: tuple of slot names
+                - css: tuple of CSS file URLs
+                - js: tuple of JS file URLs
+
+        """
+        cdata = self.get_component_data(relpath)
+        return {
+            "required": cdata.required,
+            "optional": cdata.optional,
+            "slots": cdata.slots,
+            "css": cdata.css,
+            "js": cdata.js,
+        }
 
     # Private
 

jx-0.6.0/src/jx/cli.py

@@ -0,0 +1,186 @@
+"""
+Jx | Copyright (c) Juan-Pablo Scaletti
+"""
+
+import argparse
+import re
+import sys
+from difflib import get_close_matches
+from pathlib import Path
+
+from .catalog import Catalog
+from .exceptions import JxException
+from .meta import extract_metadata
+from .parser import RX_TAG_NAME
+
+
+def find_component_tags(source: str) -> list[tuple[str, int]]:
+    """
+    Find all component tags in the source and their line numbers.
+
+    Returns:
+        List of (tag_name, line_number) tuples.
+    """
+    tags = []
+    lines = source.split("\n")
+    for line_num, line in enumerate(lines, start=1):
+        for match in RX_TAG_NAME.finditer(line):
+            tags.append((match.group("tag"), line_num))
+    return tags
+
+
+def check_component(
+    catalog: Catalog,
+    relpath: str,
+    all_components: set[str],
+) -> list[str]:
+    """
+    Check a single component for issues.
+
+    Returns:
+        List of error messages (empty if no errors).
+    """
+    errors = []
+    cdata = catalog.components[relpath]
+
+    try:
+        source = cdata.path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        return [f"{relpath} - Not valid UTF-8"]
+
+    try:
+        meta = extract_metadata(source, base_path=cdata.base_path, fullpath=cdata.path)
+    except JxException as err:
+        return [f"{relpath} - {err}"]
+
+    # Check that all imports exist
+    for _import_name, import_path in meta.imports.items():
+        if import_path not in all_components:
+            suggestion = suggest_component(import_path, all_components)
+            msg = f"{relpath} - Unknown import '{import_path}'"
+            if suggestion:
+                msg += f" (did you mean '{suggestion}'?)"
+            errors.append(msg)
+
+    # Build set of available component names for this file
+    available = set(meta.imports.keys())
+
+    # Check all component tags used in the source
+    for tag, line_num in find_component_tags(source):
+        if tag not in available:
+            # Check if it exists in the catalog without being imported
+            matching = [c for c in all_components if component_matches_tag(c, tag)]
+            if matching:
+                errors.append(
+                    f"{relpath}:{line_num} - Component '{tag}' used but not imported"
+                )
+            else:
+                suggestion = suggest_tag(tag, available, all_components)
+                msg = f"{relpath}:{line_num} - Unknown component '{tag}'"
+                if suggestion:
+                    msg += f" (did you mean '{suggestion}'?)"
+                errors.append(msg)
+
+    return errors
+
+
+def component_matches_tag(relpath: str, tag: str) -> bool:
+    """Check if a component relpath could match a tag name."""
+    # "button.jinja" -> "Button", "close-btn.jinja" -> "CloseBtn"
+    name = Path(relpath).stem
+    normalized = "".join(part.capitalize() for part in re.split(r"[-_]", name))
+    return normalized == tag
+
+
+def suggest_component(path: str, all_components: set[str]) -> str | None:
+    """Suggest a similar component path."""
+    matches = get_close_matches(path, all_components, n=1, cutoff=0.6)
+    return matches[0] if matches else None
+
+
+def suggest_tag(tag: str, imported: set[str], all_components: set[str]) -> str | None:
+    """Suggest a similar tag name."""
+    # First try imported names
+    matches = get_close_matches(tag, imported, n=1, cutoff=0.6)
+    if matches:
+        return matches[0]
+
+    # Then try deriving tag names from all components
+    all_tags = set()
+    for relpath in all_components:
+        name = Path(relpath).stem
+        normalized = "".join(part.capitalize() for part in re.split(r"[-_]", name))
+        all_tags.add(normalized)
+
+    matches = get_close_matches(tag, all_tags, n=1, cutoff=0.6)
+    return matches[0] if matches else None
+
+
+def check(paths: list[Path]) -> int:
+    """
+    Check components in the given paths.
+
+    Returns:
+        Exit code (0 for success, 1 for errors).
+    """
+    catalog = Catalog()
+
+    for path in paths:
+        if path.is_dir():
+            catalog.add_folder(path, preload=False)
+        elif path.is_file():
+            # Single file - add its parent folder
+            catalog.add_folder(path.parent, preload=False)
+
+    all_components = set(catalog.components.keys())
+
+    if not all_components:
+        print("No components found")
+        return 1
+
+    total_errors = 0
+    checked = 0
+
+    for relpath in sorted(all_components):
+        errors = check_component(catalog, relpath, all_components)
+        checked += 1
+
+        if errors:
+            for error in errors:
+                print(f"\u2717 {error}")
+            total_errors += len(errors)
+        else:
+            print(f"\u2713 {relpath} - OK")
+
+    print()
+    print(f"{checked} component{'s' if checked != 1 else ''} checked, {total_errors} error{'s' if total_errors != 1 else ''}")
+
+    return 1 if total_errors > 0 else 0
+
+
+def main() -> None:  # pragma: no cover
+    parser = argparse.ArgumentParser(
+        prog="jx",
+        description="Jx component validation tool",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    check_parser = subparsers.add_parser("check", help="Validate components")
+    check_parser.add_argument(
+        "paths",
+        nargs="+",
+        type=Path,
+        help="Paths to component folders or files",
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "check":
+        sys.exit(check(args.paths))
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

{jx-0.5.0 → jx-0.6.0}/src/jx/component.py

@@ -9,7 +9,10 @@ import jinja2
 from markupsafe import Markup
 
 from .attrs import Attrs
-from .exceptions import MissingRequiredArgument
+from .exceptions import InvalidPropType, MaxRecursionDepthError, MissingRequiredArgument
+
+
+MAX_COMPONENT_DEPTH = 100
 
 
 class Component:
@@ -32,8 +35,8 @@ class Component:
         relpath: str,
         tmpl: jinja2.Template,
         get_component: Callable[[str], "Component"],
-        required: tuple[str, ...] = (),
-        optional: dict[str, t.Any] | None = None,
+        required: dict[str, type | None] | None = None,
+        optional: dict[str, tuple[t.Any, type | None]] | None = None,
         imports: dict[str, str] | None = None,
         css: tuple[str, ...] = (),
         js: tuple[str, ...] = (),
@@ -50,9 +53,9 @@ class Component:
             get_component:
                 A callable that retrieves a component by its name/relpath.
             required:
-                A tuple of required attribute names.
+                A dictionary of required attribute names mapped to their type (or None).
             optional:
-                A dictionary of optional attributes and their default values.
+                A dictionary of optional attributes mapped to (default_value, type or None).
             imports:
                 A dictionary of imported component names as "name": "relpath" pairs.
             css:
@@ -67,7 +70,7 @@ class Component:
         self.tmpl = tmpl
         self.get_component = get_component
 
-        self.required = required
+        self.required = required or {}
         self.optional = optional or {}
         self.imports = imports or {}
         self.css = css
@@ -84,6 +87,14 @@ class Component:
         caller: Callable[[str], str] | None = None,
         **params: t.Any,
     ) -> Markup:
+        # Check recursion depth
+        depth = self.globals.get("_depth", 0)
+        if depth > MAX_COMPONENT_DEPTH:
+            raise MaxRecursionDepthError(MAX_COMPONENT_DEPTH)
+
+        # Increment depth for child components
+        self.globals = {**self.globals, "_depth": depth + 1}
+
         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}
@@ -109,13 +120,20 @@ class Component:
     ) -> tuple[dict[str, t.Any], dict[str, t.Any]]:
         props = {}
 
-        for key in self.required:
+        for key, expected_type in self.required.items():
             if key not in kw:
                 raise MissingRequiredArgument(self.relpath, key)
-            props[key] = kw.pop(key)
+            value = kw.pop(key)
+            if expected_type is not None and not isinstance(value, expected_type):
+                raise InvalidPropType(self.relpath, key, expected_type, type(value))
+            props[key] = value
+
+        for key, (default, expected_type) in self.optional.items():
+            value = kw.pop(key, default)
+            if expected_type is not None and not isinstance(value, expected_type):
+                raise InvalidPropType(self.relpath, key, expected_type, type(value))
+            props[key] = value
 
-        for key in self.optional:
-            props[key] = kw.pop(key, self.optional[key])
         extra = kw.copy()
         return props, extra
 

{jx-0.5.0 → jx-0.6.0}/src/jx/exceptions.py

@@ -36,6 +36,18 @@ class MissingRequiredArgument(JxException):
         super().__init__(msg, **kw)
 
 
+class InvalidPropType(JxException):
+    """
+    Raised when a component prop has an invalid type.
+    """
+
+    def __init__(
+        self, component: str, arg: str, expected: type, got: type, **kw
+    ) -> None:
+        msg = f"{component}: `{arg}` expected {expected.__name__}, got {got.__name__}"
+        super().__init__(msg, **kw)
+
+
 class DuplicateDefDeclaration(JxException):
     """
     Raised when a component has more then one `{#def ... #}` declarations.
@@ -57,3 +69,33 @@ class InvalidImport(JxException):
     """
     Raised when the import cannot be parsed
     """
+
+
+class PathTraversalError(JxException):
+    """
+    Raised when an import path attempts to escape the component root directory.
+    """
+
+    def __init__(self, path: str, **kw) -> None:
+        msg = f"Import path escapes component root: {path}"
+        super().__init__(msg, **kw)
+
+
+class MaxRecursionDepthError(JxException):
+    """
+    Raised when component nesting exceeds the maximum allowed depth.
+    """
+
+    def __init__(self, max_depth: int, **kw) -> None:
+        msg = f"Maximum component nesting depth exceeded ({max_depth})"
+        super().__init__(msg, **kw)
+
+
+class FileEncodingError(JxException):
+    """
+    Raised when a component file cannot be read due to encoding issues.
+    """
+
+    def __init__(self, path: str, **kw) -> None:
+        msg = f"Cannot read {path}: not valid UTF-8"
+        super().__init__(msg, **kw)