PyPI - pyxle-framework - Versions diffs - 0.2.2__tar.gz → 0.2.4__tar.gz - Mend

pyxle-framework 0.2.2tar.gz → 0.2.4tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (203) hide show

{pyxle_framework-0.2.2 → pyxle_framework-0.2.4}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyxle-framework
-Version: 0.2.2
+Version: 0.2.4
 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.2 → pyxle_framework-0.2.4}/docs/README.md RENAMED Viewed

@@ -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.2.2 (beta)
+**Current version:** 0.2.4 (beta)
 ---

{pyxle_framework-0.2.2 → pyxle_framework-0.2.4}/docs/faq.md RENAMED Viewed

@@ -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.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.
+Pyxle is in **beta** (version 0.2.4). 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?
@@ -193,7 +193,11 @@ Run `pyxle install` or `npm install` in your project directory.
 ### The page renders without styles
-Make sure Tailwind is compiled. Run `npm run dev:css` in a separate terminal, or ensure `pyxle dev` is started with `--tailwind` (the default).
+`pyxle dev` compiles Tailwind through PostCSS automatically when
+`postcss.config.cjs` is present (the scaffold default). If you removed
+that file or are on a custom stylesheet setup, re-check your
+[styling configuration](guides/styling.md) — specifically that the
+relevant CSS is imported from a page or layout.
 ### Hot reload is not working

{pyxle_framework-0.2.2 → pyxle_framework-0.2.4}/docs/getting-started/project-structure.md RENAMED Viewed

@@ -75,11 +75,17 @@ A `.pyxl` file combines Python server logic with a React component. The scaffold
 ```python
 # Python section
+from datetime import datetime, timezone
 from pyxle import __version__
 @server
 async def load_home(request):
-    return {"message": "Hello, world!"}
+    now = datetime.now(tz=timezone.utc)
+    return {
+        "version": __version__,
+        "time": now.strftime("%H:%M:%S UTC"),
+        "message": "You're ready to build with Pyxle.",
+    }
 ```
 ```jsx
@@ -88,12 +94,13 @@ import { Head } from 'pyxle/client';
 export default function HomePage({ data }) {
   return (
-    <>
+    <main>
       <Head>
-        <title>My App</title>
+        <title>Pyxle App</title>
       </Head>
       <h1>{data.message}</h1>
-    </>
+      <p>Pyxle v{data.version} &middot; {data.time}</p>
+    </main>
   );
 }
 ```
@@ -143,9 +150,12 @@ Defines Node.js dependencies and npm scripts:
 | Script | Purpose |
 |--------|---------|
 | `npm run dev` | Start Vite dev server (used internally by `pyxle dev`) |
-| `npm run build` | Build CSS + bundle with Vite (used by `pyxle build`) |
-| `npm run dev:css` | Watch Tailwind CSS compilation |
-| `npm run build:css` | One-shot minified Tailwind build |
+| `npm run build` | Bundle with Vite (used by `pyxle build`); Tailwind is compiled in-pipeline via PostCSS |
+Tailwind is wired through PostCSS (see `postcss.config.cjs`), so Vite
+handles CSS on both `dev` and `build` without a separate script. If you
+want a standalone Tailwind watcher anyway, see
+[Styling guide → Standalone Tailwind](../guides/styling.md).
 ### `tailwind.config.cjs`

{pyxle_framework-0.2.2 → pyxle_framework-0.2.4}/docs/getting-started/quick-start.md RENAMED Viewed

@@ -24,23 +24,15 @@ pip install -r requirements.txt
 npm install
 ```
-## 3. Build Tailwind CSS
-In a separate terminal, start the Tailwind watcher:
-```bash
-npm run dev:css
-```
-This compiles `pages/styles/tailwind.css` into `public/styles/tailwind.css` and watches for changes. The dev server also auto-starts Tailwind if it detects a config file, so this step is optional if you use `pyxle dev` with the `--tailwind` flag (enabled by default).
-## 4. Start the dev server
+## 3. Start the dev server
 ```bash
 pyxle dev
 ```
-Open [http://localhost:8000](http://localhost:8000) in your browser. You should see the Pyxle landing page with a hero section, feature cards, and a dark mode toggle.
+Open [http://localhost:8000](http://localhost:8000) in your browser. You should see the Pyxle starter page — a centered card showing the framework version, server time, and a link to edit `pages/index.pyxl`.
+Tailwind compiles automatically because the scaffold ships with `postcss.config.cjs` — PostCSS runs as part of the Vite pipeline, so there's nothing separate to start.
 ## What just happened?
@@ -53,24 +45,24 @@ When you ran `pyxle dev`, the framework:
 5. **Rendered HTML on the server** -- sent fully-rendered HTML to the browser (SSR)
 6. **Hydrated on the client** -- React took over the server-rendered HTML for interactivity
-## 5. Make a change
+## 4. Make a change
-Open `pages/index.pyxl` in your editor. Find the `title` value inside the `load_home` function and change it:
+Open `pages/index.pyxl` in your editor. Change the `message` returned by `load_home`:
 ```python
 @server
 async def load_home(request):
+    now = datetime.now(tz=timezone.utc)
     return {
-        "hero": {
-            "title": "Hello from Pyxle!",
-            # ...
-        },
+        "version": __version__,
+        "time": now.strftime("%H:%M:%S UTC"),
+        "message": "Hello from my Pyxle app!",
     }
 ```
-Save the file. The browser reloads automatically with your updated title.
+Save the file. The browser reloads automatically with your updated message.
-## 6. Check your routes
+## 5. Check your routes
 ```bash
 pyxle routes
@@ -84,7 +76,7 @@ Route          File                  Loader
 /api/pulse     pages/api/pulse.py    --
 ```
-## 7. Validate your project
+## 6. Validate your project
 ```bash
 pyxle check

{pyxle_framework-0.2.2 → pyxle_framework-0.2.4}/docs/guides/deployment.md RENAMED Viewed

@@ -11,7 +11,7 @@ pyxle build
 This:
 1. Compiles all `.pyxl` files into Python and JSX modules
-2. Runs `npm run build` (which runs `build:css` for Tailwind, then Vite bundling)
+2. Runs `npm run build` — Vite bundles JS and processes CSS through PostCSS (Tailwind is compiled in-pipeline when `postcss.config.cjs` is present, which is the scaffold default)
 3. Outputs production artifacts to the `dist/` directory
 ### Build options

{pyxle_framework-0.2.2 → pyxle_framework-0.2.4}/docs/guides/middleware.md RENAMED Viewed

@@ -98,10 +98,18 @@ The `context` object provides metadata about the matched route:
 | `target` | `"page" \| "api"` | Route type |
 | `path` | `str` | URL path pattern |
 | `source_relative_path` | `Path` | File path relative to project root |
+| `source_absolute_path` | `Path` | Absolute file path on disk |
 | `module_key` | `str` | Python import key |
+| `content_hash` | `str` | Hash of the compiled route module — changes when the source changes, stable across reloads |
 | `has_loader` | `bool` | Whether the page has a `@server` loader |
+| `head_elements` | `tuple[str, ...]` | Rendered `<head>` markup registered by the page/layout (SSR only) |
 | `allowed_methods` | `tuple[str, ...]` | HTTP methods the route handles |
+`RouteContext` is a frozen dataclass — fields are read-only. A shorthand
+`context.as_dict()` returns a JSON-friendly view (keys camelCased, paths
+as POSIX strings) that Pyxle attaches to `request.scope["pyxle"]["route"]`
+for downstream middleware.
 ### Built-in hooks
 Pyxle applies two default hooks:

{pyxle_framework-0.2.2 → pyxle_framework-0.2.4}/docs/reference/client-api.md RENAMED Viewed

@@ -6,7 +6,7 @@ All client-side components and hooks are importable from `pyxle/client`:
 import {
   Head, Script, Image, ClientOnly,
   Form, useAction,
-  Link, navigate, prefetch, refresh
+  Link, navigate, prefetch, refresh, usePathname
 } from 'pyxle/client';
 ```
@@ -204,6 +204,37 @@ const result = await actionFn(payload);
 ---
+### `usePathname()`
+Reactive hook that returns the current URL pathname and re-renders on
+client-side navigation.
+```jsx
+import { usePathname, Link } from 'pyxle/client';
+function NavLink({ href, children }) {
+  const pathname = usePathname();
+  const active = pathname === href;
+  return (
+    <Link href={href} className={active ? 'text-emerald-400' : 'text-zinc-400'}>
+      {children}
+    </Link>
+  );
+}
+```
+**Returns:** `string` — the current pathname (e.g. `/dashboard/settings`).
+**Behaviour:**
+- Reads `window.location.pathname` on the client
+- During SSR, returns the path currently being rendered (via
+  `globalThis.__PYXLE_CURRENT_PATHNAME__`) so the first client render matches
+  — no hydration mismatch
+- Subscribes to framework navigation events (`Link`, `navigate()`,
+  `refresh()`, `popstate`) and re-renders on change
+---
 ## Functions
 ### `navigate(path)`

{pyxle_framework-0.2.2 → pyxle_framework-0.2.4}/pyproject.toml RENAMED Viewed

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

{pyxle_framework-0.2.2 → pyxle_framework-0.2.4}/pyxle/cli/init.py RENAMED Viewed

@@ -57,11 +57,9 @@ def log_next_steps(
     if include_install_hint:
         logger.info("  2. pyxle install   # installs Python + Node dependencies")
         logger.info("     (or run 'pip install -r requirements.txt' and 'npm install')")
-        logger.info("  3. npm run dev:css   # watches Tailwind into public/styles/tailwind.css (separate terminal)")
-        logger.info("  4. pyxle dev")
-    else:
-        logger.info("  2. npm run dev:css   # watches Tailwind into public/styles/tailwind.css (separate terminal)")
         logger.info("  3. pyxle dev")
+    else:
+        logger.info("  2. pyxle dev")
 def run_init(

{pyxle_framework-0.2.2 → pyxle_framework-0.2.4}/pyxle/client/Form.jsx RENAMED Viewed

@@ -34,6 +34,10 @@ function resolveActionUrl(actionName, pagePath) {
   if (!page) {
     if (typeof window !== 'undefined') {
       page = window.location.pathname;
+    } else if (typeof globalThis.__PYXLE_CURRENT_PATHNAME__ === 'string') {
+      // SSR: use the framework-injected request path so the form's action
+      // URL matches the one the client will compute at hydration.
+      page = globalThis.__PYXLE_CURRENT_PATHNAME__;
     } else {
       page = '/';
     }

pyxle_framework-0.2.4/pyxle/client/Head.jsx ADDED Viewed

@@ -0,0 +1,122 @@
+/**
+ * <Head> — declare elements that belong in the document <head>.
+ *
+ * Works on both tiers of the render pipeline:
+ *
+ *   • SSR       — renders children to static markup and registers them
+ *                 with the framework's head registry, so they land in the
+ *                 initial HTML response.
+ *
+ *   • Client    — on mount, adopts the equivalent SSR-rendered elements
+ *                 (matched by tag + key attribute) so we don't duplicate
+ *                 them.  On update, the adopted nodes are removed and
+ *                 fresh ones inserted, so state-driven head changes (e.g.
+ *                 a dynamic <title>) actually update the document.
+ *                 On unmount, everything this instance owns is removed and
+ *                 the previous <title> is restored.
+ *
+ * Multiple <Head> components compose — each one owns the nodes it rendered.
+ */
+import { useEffect } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+const OWNER_ATTR = 'data-pyxle-head-client';
+// Key attributes that identify "the same" head element across renders.
+// Order matters: we pick the first one that the declared element has.
+const KEY_ATTRS = ['name', 'property', 'rel', 'href', 'src', 'charset', 'http-equiv'];
+function _findEquivalentHeadElement(target) {
+  const tag = target.tagName.toLowerCase();
+  const keyAttr = KEY_ATTRS.find((a) => target.hasAttribute(a));
+  if (!keyAttr) {
+    // Without a discriminating attribute we can't safely adopt — caller will
+    // insert a fresh copy instead.
+    return null;
+  }
+  const keyValue = target.getAttribute(keyAttr);
+  const escape = (typeof CSS !== 'undefined' && CSS.escape) || ((s) => s);
+  const selector = `${tag}[${keyAttr}="${escape(keyValue)}"]:not([${OWNER_ATTR}])`;
+  try {
+    return document.head.querySelector(selector);
+  } catch {
+    return null;
+  }
+}
+function _applyHeadMarkup(markup) {
+  if (!markup) return { nodes: [], previousTitle: null };
+  const template = document.createElement('template');
+  template.innerHTML = markup;
+  const parsed = Array.from(template.content.childNodes).filter(
+    (n) => n.nodeType === 1,
+  );
+  const nodes = [];
+  let previousTitle = null;
+  for (const declared of parsed) {
+    if (declared.tagName === 'TITLE') {
+      // Only one <title> wins; save the prior value so unmount can restore it.
+      if (previousTitle === null) previousTitle = document.title;
+      document.title = declared.textContent || '';
+      continue;
+    }
+    const existing = _findEquivalentHeadElement(declared);
+    if (existing) {
+      existing.setAttribute(OWNER_ATTR, '');
+      nodes.push(existing);
+    } else {
+      declared.setAttribute(OWNER_ATTR, '');
+      document.head.appendChild(declared);
+      nodes.push(declared);
+    }
+  }
+  return { nodes, previousTitle };
+}
+export function Head({ children }) {
+  // Server-side: register markup with the framework's head registry so
+  // the template emits it into the initial HTML.
+  if (typeof window === 'undefined') {
+    if (typeof globalThis.__PYXLE_HEAD_REGISTRY__ !== 'undefined') {
+      try {
+        const headMarkup = renderToStaticMarkup(<>{children}</>);
+        globalThis.__PYXLE_HEAD_REGISTRY__.register(headMarkup);
+      } catch (error) {
+        console.error('[Pyxle Head] SSR extraction failed:', error);
+      }
+    }
+    return null;
+  }
+  // Client-side: render children to a stable string so we can use it as
+  // the effect dependency (children itself changes identity every render).
+  let markup = '';
+  try {
+    markup = renderToStaticMarkup(<>{children}</>);
+  } catch (error) {
+    console.error('[Pyxle Head] client render failed:', error);
+  }
+  useEffect(() => {
+    const { nodes, previousTitle } = _applyHeadMarkup(markup);
+    return () => {
+      for (const node of nodes) {
+        if (node.parentNode) node.parentNode.removeChild(node);
+      }
+      if (previousTitle !== null) {
+        document.title = previousTitle;
+      }
+    };
+  }, [markup]);
+  return null;
+}

pyxle_framework-0.2.4/pyxle/client/Image.jsx ADDED Viewed

@@ -0,0 +1,134 @@
+/**
+ * <Image> — a thin wrapper around the native <img> with four useful
+ * behaviours on top:
+ *
+ *   1. Native lazy-loading    via the standard `loading` attribute,
+ *                             controlled by `priority` / `lazy`.
+ *   2. Blur-up placeholder    `placeholder="blur"` renders a blurred
+ *                             background image (from `blurDataURL`) or a
+ *                             solid color until the real image loads, then
+ *                             smoothly transitions to sharp.
+ *   3. Loading / error state  `onLoad` / `onError` callbacks fire once per
+ *                             transition; the element also exposes the
+ *                             state via `data-pyxle-image-state`.
+ *   4. Graceful fallback      An optional `fallbackSrc` kicks in on error
+ *                             so a broken image URL doesn't leave a blank
+ *                             box (can still be combined with `onError`).
+ *
+ * Everything else — `srcSet`, `sizes`, `className`, `style`, `onClick`, … —
+ * passes straight through to the underlying <img>.
+ */
+import { useEffect, useRef, useState } from 'react';
+const STATE_LOADING = 'loading';
+const STATE_LOADED = 'loaded';
+const STATE_ERROR = 'error';
+export function Image({
+  src,
+  alt = '',
+  width,
+  height,
+  priority = false,
+  lazy = true,
+  placeholder = 'empty',
+  blurDataURL,
+  placeholderColor = '#e5e5e5',
+  fallbackSrc,
+  onLoad,
+  onError,
+  className,
+  style,
+  ...props
+}) {
+  const [state, setState] = useState(STATE_LOADING);
+  const [currentSrc, setCurrentSrc] = useState(src);
+  const imgRef = useRef(null);
+  // Reset loading state when src changes.
+  useEffect(() => {
+    setState(STATE_LOADING);
+    setCurrentSrc(src);
+  }, [src]);
+  // If an image is already cached by the browser (common on hover-prefetch
+  // or client-side navigation), the `load` event never fires on the new
+  // element.  Check `complete` after mount and sync state manually.
+  //
+  // Symmetrically: when SSR renders an `<img>` with a broken `src`, the
+  // browser may finish the failed fetch before React hydrates, meaning the
+  // synthetic `onError` listener is attached too late to see the event.  In
+  // that case `complete` is still true but `naturalWidth` is 0 — treat as
+  // error and drive the fallback / onError path.
+  useEffect(() => {
+    const el = imgRef.current;
+    if (!el || !el.complete || state !== STATE_LOADING) return;
+    if (el.naturalWidth > 0) {
+      setState(STATE_LOADED);
+      if (onLoad) onLoad({ nativeEvent: null, target: el, fromCache: true });
+    } else {
+      // Image finished fetching but has no pixels — treat as error.
+      if (fallbackSrc && currentSrc !== fallbackSrc) {
+        setCurrentSrc(fallbackSrc);
+      } else {
+        setState(STATE_ERROR);
+        if (onError) onError({ nativeEvent: null, target: el });
+      }
+    }
+    // Only run on mount and when src changes; callbacks intentionally omitted.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [currentSrc]);
+  function handleLoad(event) {
+    setState(STATE_LOADED);
+    if (onLoad) onLoad(event);
+  }
+  function handleError(event) {
+    if (fallbackSrc && currentSrc !== fallbackSrc) {
+      setCurrentSrc(fallbackSrc);
+      return; // wait for the fallback to load / fail
+    }
+    setState(STATE_ERROR);
+    if (onError) onError(event);
+  }
+  const showPlaceholder = placeholder === 'blur' && state === STATE_LOADING;
+  const mergedStyle = {
+    ...(showPlaceholder
+      ? {
+          backgroundColor: blurDataURL ? undefined : placeholderColor,
+          backgroundImage: blurDataURL ? `url("${blurDataURL}")` : undefined,
+          backgroundSize: 'cover',
+          backgroundPosition: 'center',
+          backgroundRepeat: 'no-repeat',
+          filter: blurDataURL ? 'blur(20px)' : undefined,
+        }
+      : {}),
+    // Smooth transition once the image renders on top.
+    transition: placeholder === 'blur' ? 'filter 250ms ease-out' : undefined,
+    ...style,
+  };
+  return (
+    <img
+      ref={imgRef}
+      src={currentSrc}
+      alt={alt}
+      width={width}
+      height={height}
+      loading={priority ? 'eager' : lazy ? 'lazy' : 'eager'}
+      decoding={priority ? 'sync' : 'async'}
+      onLoad={handleLoad}
+      onError={handleError}
+      className={className}
+      style={mergedStyle}
+      data-pyxle-image-state={state}
+      {...props}
+    />
+  );
+}

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

pyxle-framework 0.2.2tar.gz → 0.2.4tar.gz