xitzin 0.1.2__py3-none-any.whl

xitzin/templating.py

@@ -0,0 +1,222 @@
+"""Gemtext template engine using Jinja2.
+
+This module provides a Jinja2-based template engine configured for
+rendering Gemtext (.gmi) templates.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from jinja2 import Environment, FileSystemLoader
+
+if TYPE_CHECKING:
+    from .application import Xitzin
+
+from nauyaca.protocol.response import GeminiResponse
+from nauyaca.protocol.status import StatusCode
+
+
+class TemplateResponse:
+    """Response from a rendered template.
+
+    Can be returned from handlers and will be converted to a GeminiResponse.
+    """
+
+    def __init__(self, content: str, mime_type: str = "text/gemini") -> None:
+        self.content = content
+        self.mime_type = mime_type
+
+    def to_gemini_response(self) -> GeminiResponse:
+        return GeminiResponse(
+            status=StatusCode.SUCCESS,
+            meta=self.mime_type,
+            body=self.content,
+        )
+
+
+def _link_filter(url: str, text: str | None = None) -> str:
+    """Generate a Gemtext link line.
+
+    Args:
+        url: The URL to link to.
+        text: Optional link text.
+
+    Returns:
+        A Gemtext link line.
+
+    Example:
+        {{ "/about" | link("About Us") }}
+        => /about About Us
+    """
+    if text:
+        return f"=> {url} {text}"
+    return f"=> {url}"
+
+
+def _heading_filter(text: str, level: int = 1) -> str:
+    """Generate a Gemtext heading.
+
+    Args:
+        text: The heading text.
+        level: Heading level (1-3).
+
+    Returns:
+        A Gemtext heading line.
+
+    Example:
+        {{ "Welcome" | heading(1) }}
+        # Welcome
+    """
+    prefix = "#" * min(max(level, 1), 3)
+    return f"{prefix} {text}"
+
+
+def _list_filter(items: list[str]) -> str:
+    """Generate a Gemtext list.
+
+    Args:
+        items: List of items.
+
+    Returns:
+        Gemtext list lines joined by newlines.
+
+    Example:
+        {{ ["Apple", "Banana", "Cherry"] | list }}
+        * Apple
+        * Banana
+        * Cherry
+    """
+    return "\n".join(f"* {item}" for item in items)
+
+
+def _quote_filter(text: str) -> str:
+    """Generate a Gemtext blockquote.
+
+    Args:
+        text: The text to quote. Multi-line text is supported.
+
+    Returns:
+        Gemtext quote lines.
+
+    Example:
+        {{ "Hello world" | quote }}
+        > Hello world
+    """
+    lines = text.split("\n")
+    return "\n".join(f"> {line}" for line in lines)
+
+
+def _preformat_filter(text: str, alt_text: str = "") -> str:
+    """Generate a Gemtext preformatted block.
+
+    Args:
+        text: The preformatted text.
+        alt_text: Optional alt text for the preformat toggle.
+
+    Returns:
+        Gemtext preformatted block.
+
+    Example:
+        {{ code | preformat("python") }}
+        ```python
+        def hello():
+            print("Hello!")
+        ```
+    """
+    return f"```{alt_text}\n{text}\n```"
+
+
+class GemtextEnvironment(Environment):
+    """Jinja2 environment configured for Gemtext templates.
+
+    This environment:
+    - Disables HTML autoescaping (not needed for Gemtext)
+    - Trims blocks and strips leading whitespace
+    - Adds Gemtext-specific filters
+    - Provides a `reverse()` global function for URL reversing (when app is provided)
+    """
+
+    def __init__(self, templates_dir: Path, app: Xitzin | None = None) -> None:
+        loader = FileSystemLoader(str(templates_dir))
+        super().__init__(
+            loader=loader,
+            autoescape=False,  # Gemtext doesn't need HTML escaping
+            trim_blocks=True,
+            lstrip_blocks=True,
+        )
+
+        # Register Gemtext-specific filters
+        self.filters["link"] = _link_filter
+        self.filters["heading"] = _heading_filter
+        self.filters["list"] = _list_filter
+        self.filters["quote"] = _quote_filter
+        self.filters["preformat"] = _preformat_filter
+
+        # Register reverse() global if app is provided
+        if app is not None:
+            self.globals["reverse"] = app.reverse
+
+
+class TemplateEngine:
+    """High-level template rendering interface.
+
+    Example:
+        engine = TemplateEngine(Path("templates"))
+        response = engine.render("page.gmi", title="Welcome", items=["a", "b"])
+
+    With app integration (enables reverse() in templates):
+        engine = TemplateEngine(Path("templates"), app=app)
+        # In templates:
+        # {{ reverse("user_profile", username="alice") | link("Profile") }}
+    """
+
+    def __init__(self, templates_dir: Path, app: Xitzin | None = None) -> None:
+        """Create a template engine.
+
+        Args:
+            templates_dir: Directory containing template files.
+            app: Optional Xitzin app instance for URL reversing in templates.
+
+        Raises:
+            ValueError: If templates_dir doesn't exist.
+        """
+        if not templates_dir.exists():
+            msg = f"Templates directory does not exist: {templates_dir}"
+            raise ValueError(msg)
+
+        self._env = GemtextEnvironment(templates_dir, app=app)
+
+    def render(self, template_name: str, **context: Any) -> TemplateResponse:
+        """Render a template file.
+
+        Args:
+            template_name: Name of the template file (e.g., "page.gmi").
+            **context: Variables to pass to the template.
+
+        Returns:
+            TemplateResponse that can be returned from handlers.
+
+        Example:
+            return engine.render("user.gmi", username="alice", posts=posts)
+        """
+        template = self._env.get_template(template_name)
+        content = template.render(**context)
+        return TemplateResponse(content)
+
+    def render_string(self, source: str, **context: Any) -> str:
+        """Render a template from a string.
+
+        Args:
+            source: Template source string.
+            **context: Variables to pass to the template.
+
+        Returns:
+            Rendered string.
+
+        Example:
+            result = engine.render_string("# {{ title }}", title="Hello")
+        """
+        template = self._env.from_string(source)
+        return template.render(**context)

xitzin/testing.py

@@ -0,0 +1,267 @@
+"""Testing utilities for Xitzin applications.
+
+This module provides a TestClient for testing Gemini handlers
+without running a real server.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Generator
+from urllib.parse import quote_plus
+
+from nauyaca.protocol.request import GeminiRequest
+from nauyaca.protocol.response import GeminiResponse
+
+if TYPE_CHECKING:
+    from .application import Xitzin
+
+
+@dataclass
+class TestResponse:
+    """Response from the test client.
+
+    Provides convenient access to response data and status checking methods.
+    """
+
+    status: int
+    """The status code (10-62)."""
+
+    meta: str
+    """The meta field (MIME type, prompt, redirect URL, or error message)."""
+
+    body: str | None
+    """The response body (only present for 2x success responses)."""
+
+    @property
+    def is_success(self) -> bool:
+        """Check if this is a success response (2x)."""
+        return 20 <= self.status < 30
+
+    @property
+    def is_input_required(self) -> bool:
+        """Check if input is required (1x)."""
+        return 10 <= self.status < 20
+
+    @property
+    def is_redirect(self) -> bool:
+        """Check if this is a redirect (3x)."""
+        return 30 <= self.status < 40
+
+    @property
+    def is_error(self) -> bool:
+        """Check if this is an error response (4x, 5x, 6x)."""
+        return 40 <= self.status < 70
+
+    @property
+    def is_certificate_required(self) -> bool:
+        """Check if a client certificate is required (6x)."""
+        return 60 <= self.status < 70
+
+    @property
+    def redirect_url(self) -> str | None:
+        """Get the redirect URL if this is a redirect response."""
+        if self.is_redirect:
+            return self.meta
+        return None
+
+    @property
+    def input_prompt(self) -> str | None:
+        """Get the input prompt if input is required."""
+        if self.is_input_required:
+            return self.meta
+        return None
+
+    @property
+    def mime_type(self) -> str | None:
+        """Get the MIME type if this is a success response."""
+        if self.is_success:
+            return self.meta.split(";")[0].strip()
+        return None
+
+    def __str__(self) -> str:
+        lines = [f"TestResponse(status={self.status}, meta={self.meta!r})"]
+        if self.body:
+            preview = self.body[:100] + "..." if len(self.body) > 100 else self.body
+            lines.append(f"  body={preview!r}")
+        return "\n".join(lines)
+
+
+class TestClient:
+    """Test client for Xitzin applications.
+
+    Allows testing handlers without running a real Gemini server.
+
+    Example:
+        app = Xitzin()
+
+        @app.gemini("/")
+        def home(request: Request):
+            return "# Welcome"
+
+        client = TestClient(app)
+        response = client.get("/")
+        assert response.status == 20
+        assert "Welcome" in response.body
+    """
+
+    def __init__(self, app: "Xitzin") -> None:
+        """Create a test client for an application.
+
+        Args:
+            app: The Xitzin application to test.
+        """
+        self._app = app
+        self._default_fingerprint: str | None = None
+
+    def get(
+        self,
+        path: str,
+        *,
+        query: str | None = None,
+        cert_fingerprint: str | None = None,
+    ) -> TestResponse:
+        """Make a test request.
+
+        Args:
+            path: The request path (e.g., "/user/alice").
+            query: Optional query string (for input responses).
+            cert_fingerprint: Mock client certificate fingerprint.
+
+        Returns:
+            TestResponse with status, meta, and body.
+
+        Example:
+            response = client.get("/")
+            assert response.is_success
+        """
+        # Build URL
+        url = f"gemini://testserver{path}"
+        if query:
+            url += f"?{quote_plus(query)}"
+
+        # Create mock GeminiRequest
+        request = GeminiRequest.from_line(url)
+
+        # Set certificate info
+        fingerprint = cert_fingerprint or self._default_fingerprint
+        if fingerprint:
+            request.client_cert_fingerprint = fingerprint
+
+        # Handle request through the app
+        response = self._handle_sync(request)
+
+        return TestResponse(
+            status=response.status,
+            meta=response.meta,
+            body=response.body,
+        )
+
+    def get_input(
+        self,
+        path: str,
+        input_value: str,
+        *,
+        cert_fingerprint: str | None = None,
+    ) -> TestResponse:
+        """Make a request with an input value.
+
+        Simulates a user responding to a status 10/11 input prompt.
+
+        Args:
+            path: The request path.
+            input_value: The user's input (will be URL-encoded).
+            cert_fingerprint: Mock client certificate fingerprint.
+
+        Returns:
+            TestResponse from the handler.
+
+        Example:
+            # First request gets input prompt
+            response = client.get("/search")
+            assert response.is_input_required
+
+            # Second request with input value
+            response = client.get_input("/search", "hello world")
+            assert response.is_success
+        """
+        return self.get(path, query=input_value, cert_fingerprint=cert_fingerprint)
+
+    def with_certificate(self, fingerprint: str) -> "TestClient":
+        """Create a new client with a default certificate fingerprint.
+
+        Args:
+            fingerprint: The certificate fingerprint to use for all requests.
+
+        Returns:
+            A new TestClient with the default fingerprint set.
+
+        Example:
+            # Create authenticated client
+            auth_client = client.with_certificate("abc123...")
+
+            # All requests from this client include the certificate
+            response = auth_client.get("/admin")
+            assert response.is_success
+        """
+        new_client = TestClient(self._app)
+        new_client._default_fingerprint = fingerprint
+        return new_client
+
+    def _handle_sync(self, request: GeminiRequest) -> GeminiResponse:
+        """Handle a request synchronously."""
+        try:
+            loop = asyncio.get_event_loop()
+        except RuntimeError:
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+
+        return loop.run_until_complete(self._app._handle_request(request))
+
+
+@contextmanager
+def test_app(app: "Xitzin") -> Generator[TestClient, None, None]:
+    """Context manager that runs the app's lifespan for testing.
+
+    This runs startup handlers before yielding and shutdown handlers
+    when the context exits.
+
+    Args:
+        app: The Xitzin application to test.
+
+    Yields:
+        A TestClient bound to the application.
+
+    Example:
+        app = Xitzin()
+
+        @app.on_startup
+        async def startup():
+            app.state.db = await connect_db()
+
+        @app.on_shutdown
+        async def shutdown():
+            await app.state.db.close()
+
+        with test_app(app) as client:
+            # Startup has run, db is connected
+            response = client.get("/")
+            assert response.is_success
+        # Shutdown has run, db is closed
+    """
+    try:
+        loop = asyncio.get_event_loop()
+    except RuntimeError:
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+
+    # Run startup
+    loop.run_until_complete(app._run_startup())
+
+    try:
+        yield TestClient(app)
+    finally:
+        # Run shutdown
+        loop.run_until_complete(app._run_shutdown())

xitzin-0.1.2.dist-info/METADATA

@@ -0,0 +1,118 @@
+Metadata-Version: 2.3
+Name: xitzin
+Version: 0.1.2
+Summary: A Gemini Application Framework
+Keywords: gemini,protocol,framework,async,geminispace
+Author: Alan Velasco
+Author-email: Alan Velasco <alanvelasco.a@gmail.com>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: nauyaca>=0.3.2
+Requires-Dist: rich>=14.2.0
+Requires-Dist: typing-extensions>=4.15.0
+Requires-Python: >=3.10
+Project-URL: Changelog, https://xitzin.readthedocs.io/changelog/
+Project-URL: Documentation, https://xitzin.readthedocs.io
+Project-URL: Homepage, https://github.com/alanbato/xitzin
+Project-URL: Issues, https://github.com/alanbato/xitzin/issues
+Project-URL: Repository, https://github.com/alanbato/xitzin.git
+Description-Content-Type: text/markdown
+
+# Xitzin
+
+**Application Framework for the Geminispace**
+
+Xitzin brings a modern Python developer experience to the [Gemini protocol](https://geminiprotocol.net/). Build Gemini capsules with familiar patterns: decorators for routing and type-annotated path parameters.
+
+```python
+from xitzin import Xitzin, Request
+
+app = Xitzin()
+
+@app.gemini("/")
+def home(request: Request):
+    return "# Welcome to my capsule!"
+
+@app.gemini("/user/{username}")
+def profile(request: Request, username: str):
+    return f"# {username}'s Profile"
+
+@app.input("/search", prompt="Enter query:")
+def search(request: Request, query: str):
+    return f"# Results for: {query}"
+
+if __name__ == "__main__":
+    app.run()
+```
+
+## Features
+
+- **Decorator-based routing** with `@app.gemini()` and automatic path parameter extraction
+- **User input handling** via `@app.input()` for Gemini's status 10/11 prompts
+- **Certificate authentication** with `@require_certificate` and fingerprint whitelisting
+- **Jinja2 templates** with Gemtext-aware filters (links, headings, lists)
+- **Middleware support** for logging, rate limiting, and custom processing
+- **Testing utilities** with in-memory `TestClient`
+- **Async support** for both sync and async handlers
+
+## Installation
+
+```bash
+pip install xitzin
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add xitzin
+```
+
+## Quick Start
+
+1. Create `app.py`:
+
+```python
+from xitzin import Xitzin, Request
+
+app = Xitzin()
+
+@app.gemini("/")
+def home(request: Request):
+    return "# Hello, Geminispace!"
+
+if __name__ == "__main__":
+    app.run()
+```
+
+2. Generate TLS certificates:
+
+```bash
+openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes -subj "/CN=localhost"
+```
+
+3. Run your capsule:
+
+```bash
+python app.py
+```
+
+4. Visit `gemini://localhost/` with a Gemini client like [Astronomo](https://github.com/alanbato/astronomo/).
+
+## Documentation
+
+Full documentation is available at [xitzin.readthedocs.io](https://xitzin.readthedocs.io/).
+
+## License
+
+MIT

xitzin-0.1.2.dist-info/RECORD

@@ -0,0 +1,15 @@
+xitzin/__init__.py,sha256=9zCk_h4rI-QGLE3q95NSgPha-dtvSOEdwiZuTQmbBR4,1637
+xitzin/application.py,sha256=GWcL-u1C6xiUwYwMxg60kQxprJ_KaLcJFPcIBf8xCzU,17909
+xitzin/auth.py,sha256=KT1WprT4qF1u03T8lAGO_UzQBLQcg-OegIFubay7VlA,4511
+xitzin/cgi.py,sha256=nmKaeLwYfk3esRnxQnn1Rx-6EHKq2zL-Xvpw5hdI-rk,17627
+xitzin/exceptions.py,sha256=JdxAXHtnXMf6joXeFQMfxlcdbv_R5odb-qYPMbgRTZY,3382
+xitzin/middleware.py,sha256=z2QJJjMEinz5e4NeZvjsCeyMLt8ZD2a3Ox2V2vuTnk8,6748
+xitzin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xitzin/requests.py,sha256=EeDqh0roz7eTItqarEDj53iFxMZlVsEIcimybKdqAHI,4612
+xitzin/responses.py,sha256=N4HeP9Yy2PIHY0zsGa2pj8xvX2OFHAjtqR5nogNh8UQ,6545
+xitzin/routing.py,sha256=SiT9J617GfQR_rPDD3Ivw0_N4CTh8-Jb_AZjWJnT5sw,12409
+xitzin/templating.py,sha256=spjxb05wgwKA4txOMbWJuwEVMaoLovo13_ukbXAcBDY,6040
+xitzin/testing.py,sha256=JO41TeIJeb1CqHVqBOjCVAvv9BOlvDJYzAeG83ZofdE,7572
+xitzin-0.1.2.dist-info/WHEEL,sha256=RRVLqVugUmFOqBedBFAmA4bsgFcROUBiSUKlERi0Hcg,79
+xitzin-0.1.2.dist-info/METADATA,sha256=wCUUakIFCbz5xTxqYnn5OymfmjoAIxJpxI-YD5v910E,3272
+xitzin-0.1.2.dist-info/RECORD,,

xitzin-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.21
+Root-Is-Purelib: true
+Tag: py3-none-any