pyxle-framework 0.2.0__tar.gz → 0.2.2__tar.gz

{pyxle_framework-0.2.0 → pyxle_framework-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyxle-framework
-Version: 0.2.0
+Version: 0.2.2
 Summary: Python-first full-stack framework with an intelligent CLI.
 Project-URL: Homepage, https://pyxle.dev
 Project-URL: Repository, https://github.com/pyxle-framework/pyxle

{pyxle_framework-0.2.0 → pyxle_framework-0.2.2}/docs/README.md

@@ -2,7 +2,7 @@
 
 Pyxle is a Python-first full-stack web framework that brings the Next.js developer experience to the Python ecosystem. Write server logic in Python, UI in React, and ship them together in `.pyxl` files.
 
-**Current version:** 0.1.0 (beta)
+**Current version:** 0.2.2 (beta)
 
 ---
 

{pyxle_framework-0.2.0 → pyxle_framework-0.2.2}/docs/faq.md

@@ -22,7 +22,7 @@ Django and Flask are backend frameworks that render templates. Pyxle is a full-s
 
 ### Is Pyxle production-ready?
 
-Pyxle is in **beta** (version 0.1.0). The core features are implemented and tested (940+ tests, 95%+ coverage), but the API may change before 1.0. Use it for new projects and experiments, but be prepared for breaking changes.
+Pyxle is in **beta** (version 0.2.2). The core features are implemented and tested (1100+ tests, 95%+ coverage), but the API may change before 1.0. Use it for new projects and experiments, but be prepared for breaking changes.
 
 ### What Python version do I need?
 

{pyxle_framework-0.2.0 → pyxle_framework-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pyxle-framework"
-version = "0.2.0"
+version = "0.2.2"
 description = "Python-first full-stack framework with an intelligent CLI."
 readme = "README.md"
 authors = [

{pyxle_framework-0.2.0 → pyxle_framework-0.2.2}/pyxle/build/manifest.py

@@ -32,8 +32,11 @@ def load_manifest(path: Path | str) -> Dict[str, Any]:
 def _validate_asset_paths(data: Dict[str, Any], manifest_path: Path) -> None:
     """Ensure no asset file path escapes the expected build directory.
 
-    Rejects paths containing ``..`` or starting with ``/`` to prevent a
-    compromised Vite build from referencing arbitrary filesystem locations.
+    Rejects paths containing ``../`` (path traversal) or starting with ``/``
+    to prevent a compromised Vite build from referencing arbitrary filesystem
+    locations.  Note: we check for ``../`` rather than ``..`` because Vite
+    may produce filenames like ``__...slug__-hash.js`` for catch-all routes,
+    which legitimately contain ``..`` as a substring.
     """
     for route_key, entry in data.items():
         if not isinstance(entry, dict):
@@ -52,7 +55,7 @@ def _validate_asset_paths(data: Dict[str, Any], manifest_path: Path) -> None:
 def _check_safe_path(
     value: str, route_key: str, field: str, manifest_path: Path
 ) -> None:
-    if ".." in value or value.startswith("/"):
+    if "/../" in value or value.startswith("../") or value.startswith("/"):
         raise ValueError(
             f"Manifest {field} entry for '{route_key}' in "
             f"'{manifest_path}' contains unsafe path: '{value}'"

{pyxle_framework-0.2.0 → pyxle_framework-0.2.2}/pyxle/cli/__init__.py

@@ -661,7 +661,8 @@ def serve(
         public_dir = resolved_dist / "public"
         if not public_dir.exists():
             logger.warning(
-                f"Public assets directory '{public_dir}' does not exist; falling back to '{settings.public_dir}'."
+                f"Public assets directory '{public_dir}' does not exist — did you run 'pyxle build' first? "
+                f"Falling back to source directory '{settings.public_dir}'."
             )
             public_static_dir = settings.public_dir
         else:

{pyxle_framework-0.2.0 → pyxle_framework-0.2.2}/pyxle/client/index.js

@@ -12,6 +12,7 @@ export { Script } from './Script.jsx';
 export { Image } from './Image.jsx';
 export { ClientOnly } from './ClientOnly.jsx';
 export { useAction } from './useAction.jsx';
+export { usePathname } from './usePathname.jsx';
 export { Form } from './Form.jsx';
 
 // Re-export Link and navigation from existing runtime

pyxle_framework-0.2.2/pyxle/client/usePathname.jsx

@@ -0,0 +1,35 @@
+/**
+ * usePathname — reactively track the current URL pathname.
+ *
+ * Usage:
+ *   const pathname = usePathname();
+ *   // Re-renders whenever Pyxle performs a client-side navigation.
+ *
+ * Returns window.location.pathname on the client. During SSR returns '/'.
+ */
+
+import { useState, useEffect } from 'react';
+
+export function usePathname() {
+  const [pathname, setPathname] = useState(
+    typeof window !== 'undefined' ? window.location.pathname : '/'
+  );
+
+  useEffect(() => {
+    // Sync on mount in case the SSR value differs.
+    setPathname(window.location.pathname);
+
+    function onRouteChange() {
+      setPathname(window.location.pathname);
+    }
+
+    window.addEventListener('pyxle:routechange', onRouteChange);
+    window.addEventListener('popstate', onRouteChange);
+    return () => {
+      window.removeEventListener('pyxle:routechange', onRouteChange);
+      window.removeEventListener('popstate', onRouteChange);
+    };
+  }, []);
+
+  return pathname;
+}

{pyxle_framework-0.2.0 → pyxle_framework-0.2.2}/pyxle/devserver/client_files.py

@@ -37,6 +37,7 @@ def write_client_bootstrap_files(settings: DevServerSettings) -> None:
         "pyxle/head.jsx": _render_head_component(),
         "pyxle/client-only.jsx": _render_client_only_component(),
         "pyxle/use-action.jsx": _render_use_action_component(),
+        "pyxle/use-pathname.jsx": _render_use_pathname_component(),
         "pyxle/form.jsx": _render_form_component(),
         "pyxle/client.js": _render_client_barrel(),
         "pyxle/index.d.ts": _render_client_runtime_index_types(),
@@ -46,6 +47,7 @@ def write_client_bootstrap_files(settings: DevServerSettings) -> None:
         "pyxle/image.d.ts": _render_image_component_types(),
         "pyxle/head.d.ts": _render_head_component_types(),
         "pyxle/client-only.d.ts": _render_client_only_component_types(),
+        "pyxle/use-pathname.d.ts": _render_use_pathname_component_types(),
     }
 
     for relative_path, contents in files.items():
@@ -1450,6 +1452,8 @@ def _render_client_entry(settings: DevServerSettings) -> str:
                   window.history[method]({ pyxle: true, pagePath: nextPagePath }, '', `${url.pathname}${url.search}${url.hash}`);
                 }
 
+                window.dispatchEvent(new CustomEvent('pyxle:routechange'));
+
                 if (options.scroll !== 'preserve') {
                   window.scrollTo(0, 0);
                 }
@@ -1491,6 +1495,7 @@ def _render_client_entry(settings: DevServerSettings) -> str:
                   '',
                   `${url.pathname}${url.search}${url.hash}`,
                 );
+                window.dispatchEvent(new CustomEvent('pyxle:routechange'));
                 return true;
               } catch (error) {
                 if (!(error instanceof DOMException && error.name === 'AbortError')) {
@@ -2407,6 +2412,65 @@ def _render_form_component() -> str:
     )
 
 
+def _render_use_pathname_component() -> str:
+    return (
+        dedent(
+            """
+            import { useState, useEffect } from 'react';
+
+            /**
+             * usePathname — reactively track the current URL pathname.
+             *
+             * Returns window.location.pathname on the client.  Re-renders
+             * the component whenever Pyxle performs a client-side navigation.
+             * During SSR returns '/'.
+             */
+            export function usePathname() {
+              const [pathname, setPathname] = useState(
+                typeof window !== 'undefined' ? window.location.pathname : '/'
+              );
+
+              useEffect(() => {
+                // Sync on mount in case the SSR value differs.
+                setPathname(window.location.pathname);
+
+                function onRouteChange() {
+                  setPathname(window.location.pathname);
+                }
+
+                window.addEventListener('pyxle:routechange', onRouteChange);
+                window.addEventListener('popstate', onRouteChange);
+                return () => {
+                  window.removeEventListener('pyxle:routechange', onRouteChange);
+                  window.removeEventListener('popstate', onRouteChange);
+                };
+              }, []);
+
+              return pathname;
+            }
+            """
+        ).strip()
+        + "\n"
+    )
+
+
+def _render_use_pathname_component_types() -> str:
+    return (
+        dedent(
+            """
+            /**
+             * Reactively track the current URL pathname.
+             *
+             * Re-renders the component on every client-side navigation.
+             * Returns `'/'` during SSR.
+             */
+            export declare function usePathname(): string;
+            """
+        ).strip()
+        + "\n"
+    )
+
+
 def _render_client_barrel() -> str:
     return (
         dedent(
@@ -2416,6 +2480,7 @@ def _render_client_barrel() -> str:
             export { Image } from './image.jsx';
             export { default as ClientOnly } from './client-only.jsx';
             export { useAction } from './use-action.jsx';
+            export { usePathname } from './use-pathname.jsx';
             export { Form } from './form.jsx';
             export { Link, navigate, prefetch, refresh, Slot, SlotProvider, useSlot, useSlots } from './index.js';
             """
@@ -2439,5 +2504,7 @@ __all__ = [
     "_render_slot_runtime_types",
     "_render_tsconfig",
     "_render_vite_config",
+    "_render_use_pathname_component",
+    "_render_use_pathname_component_types",
     "_build_public_env_defines",
 ]

{pyxle_framework-0.2.0 → pyxle_framework-0.2.2}/pyxle/devserver/registry.py

@@ -379,3 +379,62 @@ def find_layout_head_jsx_blocks(
                     layout_head_blocks.extend(metadata.head_elements)
     
     return tuple(layout_head_blocks)
+
+
+@dataclass(frozen=True, slots=True)
+class LayoutLoaderInfo:
+    """Metadata needed to execute a layout's ``@server`` loader."""
+
+    relative_path: Path
+    server_module_path: Path
+    module_key: str
+    loader_name: str
+
+
+def find_layout_loaders(
+    settings: DevServerSettings,
+    page_relative_path: Path,
+) -> tuple[LayoutLoaderInfo, ...]:
+    """Discover layout/template files with ``@server`` loaders that wrap *page_relative_path*.
+
+    Walks ancestor directories from the page's location (closest first, root last)
+    and returns a :class:`LayoutLoaderInfo` for each layout or template whose
+    compiled metadata declares a loader.  The order matches the wrapping order
+    used by :func:`find_layout_head_jsx_blocks`.
+    """
+
+    parts = list(page_relative_path.parent.parts)
+    ancestors: List[Path] = []
+
+    if page_relative_path.parent.name:
+        ancestors.append(page_relative_path.parent)
+
+    for index in range(len(parts) - 1, 0, -1):
+        ancestors.append(Path(*parts[:index]))
+
+    ancestors.append(Path("."))
+
+    loaders: List[LayoutLoaderInfo] = []
+
+    for ancestor_dir in ancestors:
+        for filename in ("layout.pyxl", "template.pyxl"):
+            relative = ancestor_dir / filename if ancestor_dir != Path(".") else Path(filename)
+            metadata_path = settings.metadata_build_dir / "pages" / relative.with_suffix(".json")
+            if ancestor_dir == Path("."):
+                metadata_path = settings.metadata_build_dir / "pages" / Path(filename).with_suffix(".json")
+
+            metadata = _load_page_metadata(metadata_path)
+            if metadata is None or not metadata.loader_name:
+                continue
+
+            server_module = settings.server_build_dir / "pages" / relative.with_suffix(".py")
+            module_key = relative.with_suffix("").as_posix().replace("/", ".")
+
+            loaders.append(LayoutLoaderInfo(
+                relative_path=relative,
+                server_module_path=server_module,
+                module_key=module_key,
+                loader_name=metadata.loader_name,
+            ))
+
+    return tuple(loaders)

{pyxle_framework-0.2.0 → pyxle_framework-0.2.2}/pyxle/ssr/view.py

@@ -364,6 +364,43 @@ async def _execute_loader(
     return payload, status_code, module
 
 
+async def _execute_layout_loaders(
+    *,
+    settings: DevServerSettings,
+    page: PageRoute,
+    request: Request,
+) -> dict[str, Any] | None:
+    """Execute ``@server`` loaders declared in ancestor layout/template files.
+
+    Returns a dict of loader results (one entry per layout that has a loader),
+    or ``None`` if no layout declares a loader.
+    """
+    from pyxle.devserver.registry import find_layout_loaders
+
+    layout_loader_infos = find_layout_loaders(settings, page.source_relative_path)
+    if not layout_loader_infos:
+        return None
+
+    layout_data: dict[str, Any] = {}
+    for info in layout_loader_infos:
+        module = _import_server_module(info.module_key, info.server_module_path, debug=settings.debug)
+        loader_fn = getattr(module, info.loader_name, None)
+        if loader_fn is None:
+            continue
+
+        result = loader_fn(request)
+        if hasattr(result, "__await__"):
+            result = await result
+
+        # Layout loaders return a plain dict (no status code).
+        if isinstance(result, tuple) and result:
+            result = result[0]
+        if isinstance(result, Mapping):
+            layout_data.update(result)
+
+    return layout_data or None
+
+
 def _resolve_head_elements(
     page: PageRoute,
     module,
@@ -404,8 +441,14 @@ def _normalize_loader_result(result: Any, page: PageRoute) -> Tuple[dict[str, An
     return dict(payload), status_code
 
 
-def _compose_component_props(loader_payload: dict[str, Any]) -> dict[str, Any]:
-    return {"data": loader_payload}
+def _compose_component_props(
+    loader_payload: dict[str, Any],
+    layout_data: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    props: dict[str, Any] = {"data": loader_payload}
+    if layout_data:
+        props["layoutData"] = layout_data
+    return props
 
 
 async def _create_page_artifacts(
@@ -434,14 +477,21 @@ async def _create_page_artifacts(
         loader_breadcrumb["detail"] = f"Returned {len(loader_props)} key(s) with status {status_code}"
 
     head_elements = _resolve_head_elements(page, module, loader_props, debug=settings.debug)
-    
+
     # Merge HEAD variable with JSX Head blocks and layout head blocks
-    from pyxle.devserver.registry import find_layout_head_jsx_blocks
+    from pyxle.devserver.registry import find_layout_head_jsx_blocks, find_layout_loaders
     from pyxle.ssr.head_merger import merge_head_elements
-    
+
     layout_head_jsx_blocks = find_layout_head_jsx_blocks(settings, page.source_relative_path)
-    
-    component_props = _compose_component_props(loader_props)
+
+    # Execute layout loaders (if any layout has a @server decorator)
+    layout_data = await _execute_layout_loaders(
+        settings=settings,
+        page=page,
+        request=request,
+    )
+
+    component_props = _compose_component_props(loader_props, layout_data)
     render_result = await renderer.render(page.client_module_path, component_props)
     body_html = render_result.html
     inline_styles = render_result.inline_styles

{pyxle_framework-0.2.0 → pyxle_framework-0.2.2}/tests/devserver/test_client_files.py

@@ -15,6 +15,8 @@ from pyxle.devserver.client_files import (
     _render_slot_runtime,
     _render_slot_runtime_types,
     _render_tsconfig,
+    _render_use_pathname_component,
+    _render_use_pathname_component_types,
     _render_vite_config,
     write_client_bootstrap_files,
 )
@@ -335,3 +337,48 @@ def test_client_entry_includes_bfcache_pageshow_handler(tmp_path: Path) -> None:
     assert "addEventListener('pageshow'" in entry or 'addEventListener("pageshow"' in entry
     assert "event.persisted" in entry
     assert "router.refresh()" in entry
+
+
+# ---------------------------------------------------------------------------
+# usePathname hook
+# ---------------------------------------------------------------------------
+
+
+def test_client_entry_dispatches_route_change_event(tmp_path: Path) -> None:
+    """The client runtime dispatches a ``pyxle:routechange`` custom event
+    after both ``navigateTo`` and ``refreshCurrentPage`` complete.  This
+    is the signal consumed by ``usePathname()``."""
+    settings = create_project(tmp_path)
+    entry = _render_client_entry(settings)
+
+    assert "pyxle:routechange" in entry
+    # Must appear at least twice: once in navigateTo, once in refreshCurrentPage.
+    assert entry.count("pyxle:routechange") >= 2
+
+
+def test_use_pathname_component_is_ssr_safe() -> None:
+    """The generated usePathname hook must guard window access for SSR."""
+    source = _render_use_pathname_component()
+    assert "typeof window" in source
+    assert "usePathname" in source
+    assert "pyxle:routechange" in source
+
+
+def test_use_pathname_component_types() -> None:
+    """Type definition declares usePathname returning a string."""
+    types = _render_use_pathname_component_types()
+    assert "usePathname" in types
+    assert "string" in types
+
+
+def test_write_client_bootstrap_files_generates_use_pathname(tmp_path: Path) -> None:
+    """Bootstrap writes both the JSX hook and its type declaration."""
+    settings = create_project(tmp_path)
+    write_client_bootstrap_files(settings)
+
+    hook = (settings.client_build_dir / "pyxle" / "use-pathname.jsx").read_text(encoding="utf-8")
+    assert "usePathname" in hook
+    assert "pyxle:routechange" in hook
+
+    types = (settings.client_build_dir / "pyxle" / "use-pathname.d.ts").read_text(encoding="utf-8")
+    assert "usePathname" in types

{pyxle_framework-0.2.0 → pyxle_framework-0.2.2}/tests/devserver/test_registry.py

@@ -278,3 +278,68 @@ def test_find_layout_head_jsx_blocks_layout_hierarchy(project: DevServerSettings
     assert "root" in all_blocks
     assert "posts" in all_blocks
 
+
+# ---------------------------------------------------------------------------
+# find_layout_loaders
+# ---------------------------------------------------------------------------
+
+
+def test_find_layout_loaders_no_layout(project: DevServerSettings) -> None:
+    """Returns empty tuple when no layout file exists."""
+    from pyxle.devserver.registry import find_layout_loaders
+
+    build_once(project)
+    loaders = find_layout_loaders(project, Path("index.pyxl"))
+    assert loaders == ()
+
+
+def test_find_layout_loaders_layout_without_loader(project: DevServerSettings) -> None:
+    """Layout file with no @server decorator yields no loader info."""
+    from pyxle.devserver.registry import find_layout_loaders
+
+    write_file(
+        project.pages_dir / "layout.pyxl",
+        "import React from 'react';\n\nexport default function Layout({ children }) {\n    return <div>{children}</div>;\n}\n",
+    )
+
+    build_once(project)
+    loaders = find_layout_loaders(project, Path("index.pyxl"))
+    assert loaders == ()
+
+
+def test_find_layout_loaders_layout_with_loader(project: DevServerSettings) -> None:
+    """Layout file with @server decorator is discovered."""
+    from pyxle.devserver.registry import find_layout_loaders
+
+    write_file(
+        project.pages_dir / "layout.pyxl",
+        "@server\nasync def load_layout(request):\n    return {'app': 'test'}\n\nimport React from 'react';\n\nexport default function Layout({ children }) {\n    return <div>{children}</div>;\n}\n",
+    )
+
+    build_once(project)
+    loaders = find_layout_loaders(project, Path("index.pyxl"))
+    assert len(loaders) == 1
+    assert loaders[0].loader_name == "load_layout"
+    assert loaders[0].server_module_path.exists()
+
+
+def test_find_layout_loaders_nested_hierarchy(project: DevServerSettings) -> None:
+    """Both root and nested layout loaders are discovered in order."""
+    from pyxle.devserver.registry import find_layout_loaders
+
+    write_file(
+        project.pages_dir / "layout.pyxl",
+        "@server\nasync def load_root(request):\n    return {'level': 'root'}\n\nimport React from 'react';\n\nexport default function RootLayout({ children }) {\n    return <html>{children}</html>;\n}\n",
+    )
+    write_file(
+        project.pages_dir / "posts" / "layout.pyxl",
+        "@server\nasync def load_posts(request):\n    return {'level': 'posts'}\n\nimport React from 'react';\n\nexport default function PostsLayout({ children }) {\n    return <section>{children}</section>;\n}\n",
+    )
+
+    build_once(project)
+    loaders = find_layout_loaders(project, Path("posts/[id].pyxl"))
+    assert len(loaders) == 2
+    # Closest layout first
+    assert loaders[0].loader_name == "load_posts"
+    assert loaders[1].loader_name == "load_root"
+