ursaproxy 0.2.0__tar.gz → 0.3.0__tar.gz

{ursaproxy-0.2.0 → ursaproxy-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: ursaproxy
-Version: 0.2.0
+Version: 0.3.0
 Summary: A Bearblog-to-Gemini proxy showcasing Xitzin
 Author: Alan Velasco
 Author-email: Alan Velasco <ursaproxy@alanbato.com>
@@ -44,47 +44,93 @@ pip install ursaproxy
 
 ## Configuration
 
-UrsaProxy is configured via environment variables:
+UrsaProxy can be configured via a TOML file or environment variables.
 
-### Required
+### TOML Configuration (Recommended)
 
-| Variable | Description |
-|----------|-------------|
-| `BEARBLOG_URL` | The Bearblog URL to proxy (e.g., `https://example.bearblog.dev`) |
-| `BLOG_NAME` | Display name for the blog |
-| `CERT_FILE` | Path to TLS certificate file |
-| `KEY_FILE` | Path to TLS private key file |
+Create an `ursaproxy.toml` file in your working directory:
 
-### Optional
+```toml
+bearblog_url = "https://example.bearblog.dev"
+blog_name = "My Gemini Blog"
+cert_file = "/path/to/cert.pem"
+key_file = "/path/to/key.pem"
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `PAGES` | `{}` | JSON dict of static pages `{"slug": "Title"}` |
-| `GEMINI_HOST` | `None` | Hostname for Gemini URLs in feed |
-| `CACHE_TTL_FEED` | `300` | Feed cache TTL in seconds (5 min) |
-| `CACHE_TTL_POST` | `1800` | Post cache TTL in seconds (30 min) |
-| `HOST` | `localhost` | Server bind address |
-| `PORT` | `1965` | Server port (Gemini default) |
+# Optional settings
+gemini_host = "gemini.example.com"
+cache_ttl_feed = 300
+cache_ttl_post = 1800
+host = "localhost"
+port = 1965
 
-### Example
-
-```bash
-export BEARBLOG_URL="https://example.bearblog.dev"
-export BLOG_NAME="My Gemini Blog"
-export CERT_FILE="/path/to/cert.pem"
-export KEY_FILE="/path/to/key.pem"
-export PAGES='{"about": "About Me", "now": "What I am doing now"}'
-export GEMINI_HOST="gemini.example.com"
+[pages]
+about = "About Me"
+now = "What I am doing now"
 ```
 
+### Environment Variables
+
+Environment variables override TOML settings:
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `BEARBLOG_URL` | Yes | - | The Bearblog URL to proxy |
+| `BLOG_NAME` | Yes | - | Display name for the blog |
+| `CERT_FILE` | No | `None` | Path to TLS certificate file |
+| `KEY_FILE` | No | `None` | Path to TLS private key file |
+| `PAGES` | No | `{}` | JSON dict of static pages |
+| `GEMINI_HOST` | No | `None` | Hostname for Gemini URLs in feed |
+| `CACHE_TTL_FEED` | No | `300` | Feed cache TTL in seconds |
+| `CACHE_TTL_POST` | No | `1800` | Post cache TTL in seconds |
+| `HOST` | No | `localhost` | Server bind address |
+| `PORT` | No | `1965` | Server port |
+
+### Configuration Priority
+
+Settings are loaded in this order (highest to lowest priority):
+
+1. Environment variables
+2. `ursaproxy.toml` file
+3. Default values
+
 ## Usage
 
+### Standalone
+
 ```bash
 ursaproxy
 ```
 
 The server will start on `gemini://localhost:1965/` by default.
 
+### As a Library
+
+UrsaProxy can be embedded in other Xitzin applications for virtual hosting:
+
+```python
+from ursaproxy import create_app, Settings
+
+# Create settings programmatically
+settings = Settings(
+    bearblog_url="https://myblog.bearblog.dev",
+    blog_name="My Blog",
+)
+
+# Create the app
+app = create_app(settings)
+
+# Mount in your main Xitzin app or run directly
+app.run(certfile="cert.pem", keyfile="key.pem")
+```
+
+Or load settings from TOML/environment:
+
+```python
+from ursaproxy import create_app, load_settings
+
+app = create_app(load_settings())
+```
+
 ### Routes
 
 | Route | Description |
@@ -151,7 +197,7 @@ src/ursaproxy/
 The test suite uses pytest with fixtures for offline testing:
 
 ```bash
-# Run all 111 tests
+# Run all tests
 uv run pytest
 
 # Run specific test file

{ursaproxy-0.2.0 → ursaproxy-0.3.0}/README.md

@@ -24,47 +24,93 @@ pip install ursaproxy
 
 ## Configuration
 
-UrsaProxy is configured via environment variables:
+UrsaProxy can be configured via a TOML file or environment variables.
 
-### Required
+### TOML Configuration (Recommended)
 
-| Variable | Description |
-|----------|-------------|
-| `BEARBLOG_URL` | The Bearblog URL to proxy (e.g., `https://example.bearblog.dev`) |
-| `BLOG_NAME` | Display name for the blog |
-| `CERT_FILE` | Path to TLS certificate file |
-| `KEY_FILE` | Path to TLS private key file |
+Create an `ursaproxy.toml` file in your working directory:
 
-### Optional
+```toml
+bearblog_url = "https://example.bearblog.dev"
+blog_name = "My Gemini Blog"
+cert_file = "/path/to/cert.pem"
+key_file = "/path/to/key.pem"
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `PAGES` | `{}` | JSON dict of static pages `{"slug": "Title"}` |
-| `GEMINI_HOST` | `None` | Hostname for Gemini URLs in feed |
-| `CACHE_TTL_FEED` | `300` | Feed cache TTL in seconds (5 min) |
-| `CACHE_TTL_POST` | `1800` | Post cache TTL in seconds (30 min) |
-| `HOST` | `localhost` | Server bind address |
-| `PORT` | `1965` | Server port (Gemini default) |
+# Optional settings
+gemini_host = "gemini.example.com"
+cache_ttl_feed = 300
+cache_ttl_post = 1800
+host = "localhost"
+port = 1965
 
-### Example
-
-```bash
-export BEARBLOG_URL="https://example.bearblog.dev"
-export BLOG_NAME="My Gemini Blog"
-export CERT_FILE="/path/to/cert.pem"
-export KEY_FILE="/path/to/key.pem"
-export PAGES='{"about": "About Me", "now": "What I am doing now"}'
-export GEMINI_HOST="gemini.example.com"
+[pages]
+about = "About Me"
+now = "What I am doing now"
 ```
 
+### Environment Variables
+
+Environment variables override TOML settings:
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `BEARBLOG_URL` | Yes | - | The Bearblog URL to proxy |
+| `BLOG_NAME` | Yes | - | Display name for the blog |
+| `CERT_FILE` | No | `None` | Path to TLS certificate file |
+| `KEY_FILE` | No | `None` | Path to TLS private key file |
+| `PAGES` | No | `{}` | JSON dict of static pages |
+| `GEMINI_HOST` | No | `None` | Hostname for Gemini URLs in feed |
+| `CACHE_TTL_FEED` | No | `300` | Feed cache TTL in seconds |
+| `CACHE_TTL_POST` | No | `1800` | Post cache TTL in seconds |
+| `HOST` | No | `localhost` | Server bind address |
+| `PORT` | No | `1965` | Server port |
+
+### Configuration Priority
+
+Settings are loaded in this order (highest to lowest priority):
+
+1. Environment variables
+2. `ursaproxy.toml` file
+3. Default values
+
 ## Usage
 
+### Standalone
+
 ```bash
 ursaproxy
 ```
 
 The server will start on `gemini://localhost:1965/` by default.
 
+### As a Library
+
+UrsaProxy can be embedded in other Xitzin applications for virtual hosting:
+
+```python
+from ursaproxy import create_app, Settings
+
+# Create settings programmatically
+settings = Settings(
+    bearblog_url="https://myblog.bearblog.dev",
+    blog_name="My Blog",
+)
+
+# Create the app
+app = create_app(settings)
+
+# Mount in your main Xitzin app or run directly
+app.run(certfile="cert.pem", keyfile="key.pem")
+```
+
+Or load settings from TOML/environment:
+
+```python
+from ursaproxy import create_app, load_settings
+
+app = create_app(load_settings())
+```
+
 ### Routes
 
 | Route | Description |
@@ -131,7 +177,7 @@ src/ursaproxy/
 The test suite uses pytest with fixtures for offline testing:
 
 ```bash
-# Run all 111 tests
+# Run all tests
 uv run pytest
 
 # Run specific test file

{ursaproxy-0.2.0 → ursaproxy-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ursaproxy"
-version = "0.2.0"
+version = "0.3.0"
 description = "A Bearblog-to-Gemini proxy showcasing Xitzin"
 readme = "README.md"
 authors = [

ursaproxy-0.3.0/src/ursaproxy/__init__.py

@@ -0,0 +1,234 @@
+from datetime import datetime
+from email.utils import parsedate_to_datetime
+
+import httpx
+from jinja2 import Environment, PackageLoader
+from xitzin import NotFound, Request, Response, TemporaryFailure, Xitzin
+
+from .cache import cache
+from .config import Settings, load_settings
+from .converter import extract_metadata, extract_slug, html_to_gemtext
+from .fetcher import NotFoundError, ServerError, fetch_feed, fetch_html
+
+__all__ = ["create_app", "Settings", "load_settings"]
+
+
+def _rfc822_to_iso(date_str: str) -> str:
+    """Convert RFC 822 date to ISO 8601 format for Atom feeds."""
+    if not date_str:
+        return datetime.now().isoformat() + "Z"
+    try:
+        dt = parsedate_to_datetime(date_str)
+        return dt.isoformat().replace("+00:00", "Z")
+    except (ValueError, TypeError):
+        return datetime.now().isoformat() + "Z"
+
+
+# Template environments
+templates = Environment(
+    loader=PackageLoader("ursaproxy", "templates"),
+    autoescape=False,  # Gemtext doesn't need HTML escaping
+)
+
+xml_templates = Environment(
+    loader=PackageLoader("ursaproxy", "templates"),
+    autoescape=True,  # XML escaping for feed
+)
+
+
+def create_app(settings: Settings) -> Xitzin:
+    """Create and configure an UrsaProxy application instance.
+
+    This factory function allows ursaproxy to be embedded in other Xitzin apps
+    for virtual hosting scenarios.
+
+    Args:
+        settings: Configuration for this ursaproxy instance.
+
+    Returns:
+        A configured Xitzin application.
+
+    Example:
+        For standalone use::
+
+            from ursaproxy import create_app, load_settings
+
+            app = create_app(load_settings())
+            app.run()
+
+        For embedding in another app::
+
+            from ursaproxy import create_app, Settings
+
+            ursaproxy_settings = Settings(
+                bearblog_url="https://myblog.bearblog.dev",
+                blog_name="My Blog",
+            )
+            ursaproxy_app = create_app(ursaproxy_settings)
+            # Mount ursaproxy_app in your main Xitzin app
+    """
+    app = Xitzin()
+    app.state.settings = settings
+
+    @app.on_startup
+    async def startup() -> None:
+        """Initialize shared HTTP client."""
+        app.state.client = httpx.AsyncClient(timeout=30.0)
+
+    @app.on_shutdown
+    async def shutdown() -> None:
+        """Close HTTP client."""
+        await app.state.client.aclose()
+
+    async def _get_feed(client: httpx.AsyncClient):
+        """Fetch feed with caching and error handling."""
+        if cached := cache.get("feed", settings.cache_ttl_feed):
+            return cached
+
+        try:
+            feed = await fetch_feed(client, settings.bearblog_url)
+            cache.set("feed", feed)
+            return feed
+        except ServerError as e:
+            raise TemporaryFailure(str(e)) from e
+        except NotFoundError as e:
+            raise NotFound(str(e)) from e
+
+    async def _render_content(
+        client: httpx.AsyncClient,
+        slug: str,
+        content_type: str,
+        include_date: bool = True,
+    ) -> str:
+        """Fetch and render content as gemtext with caching."""
+        cache_key = f"{content_type}:{slug}"
+
+        if cached := cache.get(cache_key, settings.cache_ttl_post):
+            return cached
+
+        try:
+            html = await fetch_html(client, settings.bearblog_url, slug)
+        except NotFoundError as e:
+            raise NotFound(str(e)) from e
+        except ServerError as e:
+            raise TemporaryFailure(str(e)) from e
+
+        title, date = extract_metadata(html)
+        content = html_to_gemtext(html)
+
+        template = templates.get_template("post.gmi")
+        gemtext = template.render(
+            title=title,
+            date=date if include_date else None,
+            content=content,
+            web_url=f"{settings.bearblog_url}/{slug}/",
+        )
+
+        cache.set(cache_key, gemtext)
+        return gemtext
+
+    @app.gemini("/")
+    async def index(request: Request) -> str:
+        """Landing page with recent posts and page links."""
+        feed = await _get_feed(request.app.state.client)
+
+        posts = []
+        for entry in feed.entries[:10]:
+            link = getattr(entry, "link", None)
+            if not link:
+                continue
+            slug = extract_slug(link)
+            if not slug:
+                continue
+            date = entry.get("published", "")[:16] if entry.get("published") else ""
+            title = getattr(entry, "title", "Untitled")
+            posts.append({"slug": slug, "title": title, "date": date})
+
+        template = templates.get_template("index.gmi")
+        return template.render(
+            blog_name=settings.blog_name,
+            description=feed.feed.get("description", ""),
+            pages=settings.pages,
+            posts=posts,
+        )
+
+    @app.gemini("/post/{slug}")
+    async def post(request: Request, slug: str) -> str:
+        """Individual blog post."""
+        return await _render_content(
+            request.app.state.client, slug, "post", include_date=True
+        )
+
+    @app.gemini("/page/{slug}")
+    async def page(request: Request, slug: str) -> str:
+        """Static page (projects, now, etc.)."""
+        return await _render_content(
+            request.app.state.client, slug, "page", include_date=False
+        )
+
+    @app.gemini("/about")
+    async def about(request: Request) -> str:
+        """About page from feed metadata."""
+        feed = await _get_feed(request.app.state.client)
+        description = feed.feed.get("description", "A personal blog.")
+
+        template = templates.get_template("about.gmi")
+        return template.render(
+            blog_name=settings.blog_name,
+            description=description,
+            bearblog_url=settings.bearblog_url,
+        )
+
+    @app.gemini("/feed")
+    async def feed_route(request: Request) -> Response:
+        """Atom feed with Gemini URLs."""
+        rss = await _get_feed(request.app.state.client)
+
+        # Use configured gemini_host or fall back to request hostname
+        host = settings.gemini_host or request.hostname or "localhost"
+        base_url = f"gemini://{host}"
+
+        # Get the most recent update time
+        updated = _rfc822_to_iso(rss.feed.get("updated", ""))
+
+        entries = []
+        for entry in rss.entries:
+            link = getattr(entry, "link", None)
+            if not link:
+                continue
+            slug = extract_slug(link)
+            if not slug:
+                continue
+
+            entries.append(
+                {
+                    "title": getattr(entry, "title", "Untitled"),
+                    "url": f"{base_url}/post/{slug}",
+                    "published": _rfc822_to_iso(entry.get("published", "")),
+                    "summary": getattr(entry, "description", ""),
+                }
+            )
+
+        template = xml_templates.get_template("feed.xml")
+        atom_xml = template.render(
+            blog_name=settings.blog_name,
+            base_url=base_url,
+            updated=updated,
+            entries=entries,
+        )
+
+        return Response(body=atom_xml, mime_type="application/atom+xml")
+
+    return app
+
+
+def main() -> None:
+    """Entry point for standalone execution."""
+    settings = load_settings()
+    app = create_app(settings)
+    app.run(
+        host=settings.host,
+        port=settings.port,
+        certfile=settings.cert_file,
+        keyfile=settings.key_file,
+    )

{ursaproxy-0.2.0 → ursaproxy-0.3.0}/src/ursaproxy/config.py

@@ -74,8 +74,12 @@ class Settings(BaseSettings):
         return v
 
 
-def _load_settings() -> Settings:
-    """Load settings, handling missing TOML file gracefully."""
+def load_settings() -> Settings:
+    """Load settings from TOML file and/or environment variables.
+
+    Use this when running ursaproxy standalone. For embedding in other apps,
+    create a Settings instance directly with the desired configuration.
+    """
     try:
         return Settings()  # type: ignore[call-arg]
     except FileNotFoundError:
@@ -93,6 +97,3 @@ def _load_settings() -> Settings:
                 return (env_settings,)
 
         return _EnvOnlySettings()  # type: ignore[call-arg]
-
-
-settings = _load_settings()

{ursaproxy-0.2.0 → ursaproxy-0.3.0}/src/ursaproxy/fetcher.py

@@ -1,8 +1,6 @@
 import feedparser
 import httpx
 
-from .config import settings
-
 
 class FetchError(Exception):
     """Base error for fetch operations."""
@@ -35,19 +33,30 @@ async def _fetch(
         raise ServerError(f"Network error: {e}") from e
 
 
-async def fetch_feed(client: httpx.AsyncClient) -> feedparser.FeedParserDict:
-    """Fetch RSS feed from Bearblog."""
-    url = f"{settings.bearblog_url}/feed/?type=rss"
+async def fetch_feed(
+    client: httpx.AsyncClient, bearblog_url: str
+) -> feedparser.FeedParserDict:
+    """Fetch RSS feed from Bearblog.
+
+    Args:
+        client: HTTP client instance.
+        bearblog_url: Base URL of the Bearblog site.
+    """
+    url = f"{bearblog_url}/feed/?type=rss"
     response = await _fetch(client, url, f"Feed not found at {url}")
     return feedparser.parse(response.text)
 
 
-async def fetch_html(client: httpx.AsyncClient, slug: str) -> str:
-    """
-    Fetch HTML page from Bearblog.
+async def fetch_html(client: httpx.AsyncClient, bearblog_url: str, slug: str) -> str:
+    """Fetch HTML page from Bearblog.
+
+    Args:
+        client: HTTP client instance.
+        bearblog_url: Base URL of the Bearblog site.
+        slug: Page slug (without leading/trailing slashes).
 
     Note: Bearblog URLs have trailing slashes: /{slug}/
     """
-    url = f"{settings.bearblog_url}/{slug}/"
+    url = f"{bearblog_url}/{slug}/"
     response = await _fetch(client, url, f"Page not found: {slug}")
     return response.text

ursaproxy-0.2.0/src/ursaproxy/__init__.py

@@ -1,203 +0,0 @@
-from datetime import datetime
-from email.utils import parsedate_to_datetime
-
-import httpx
-from jinja2 import Environment, PackageLoader
-from xitzin import NotFound, Request, Response, TemporaryFailure, Xitzin
-
-from .cache import cache
-from .config import settings
-from .converter import extract_metadata, extract_slug, html_to_gemtext
-from .fetcher import NotFoundError, ServerError, fetch_feed, fetch_html
-
-app = Xitzin()
-
-# Template environments
-templates = Environment(
-    loader=PackageLoader("ursaproxy", "templates"),
-    autoescape=False,  # Gemtext doesn't need HTML escaping
-)
-
-xml_templates = Environment(
-    loader=PackageLoader("ursaproxy", "templates"),
-    autoescape=True,  # XML escaping for feed
-)
-
-
-@app.on_startup
-async def startup() -> None:
-    """Initialize shared HTTP client."""
-    app.state.client = httpx.AsyncClient(timeout=30.0)
-
-
-@app.on_shutdown
-async def shutdown() -> None:
-    """Close HTTP client."""
-    await app.state.client.aclose()
-
-
-async def _get_feed(client: httpx.AsyncClient):
-    """Fetch feed with caching and error handling."""
-    if cached := cache.get("feed", settings.cache_ttl_feed):
-        return cached
-
-    try:
-        feed = await fetch_feed(client)
-        cache.set("feed", feed)
-        return feed
-    except ServerError as e:
-        raise TemporaryFailure(str(e)) from e
-    except NotFoundError as e:
-        raise NotFound(str(e)) from e
-
-
-async def _render_content(
-    client: httpx.AsyncClient,
-    slug: str,
-    content_type: str,
-    include_date: bool = True,
-) -> str:
-    """Fetch and render content as gemtext with caching."""
-    cache_key = f"{content_type}:{slug}"
-
-    if cached := cache.get(cache_key, settings.cache_ttl_post):
-        return cached
-
-    try:
-        html = await fetch_html(client, slug)
-    except NotFoundError as e:
-        raise NotFound(str(e)) from e
-    except ServerError as e:
-        raise TemporaryFailure(str(e)) from e
-
-    title, date = extract_metadata(html)
-    content = html_to_gemtext(html)
-
-    template = templates.get_template("post.gmi")
-    gemtext = template.render(
-        title=title,
-        date=date if include_date else None,
-        content=content,
-        web_url=f"{settings.bearblog_url}/{slug}/",
-    )
-
-    cache.set(cache_key, gemtext)
-    return gemtext
-
-
-@app.gemini("/")
-async def index(request: Request) -> str:
-    """Landing page with recent posts and page links."""
-    feed = await _get_feed(request.app.state.client)
-
-    posts = []
-    for entry in feed.entries[:10]:
-        link = getattr(entry, "link", None)
-        if not link:
-            continue
-        slug = extract_slug(link)
-        if not slug:
-            continue
-        date = entry.get("published", "")[:16] if entry.get("published") else ""
-        title = getattr(entry, "title", "Untitled")
-        posts.append({"slug": slug, "title": title, "date": date})
-
-    template = templates.get_template("index.gmi")
-    return template.render(
-        blog_name=settings.blog_name,
-        description=feed.feed.get("description", ""),
-        pages=settings.pages,
-        posts=posts,
-    )
-
-
-@app.gemini("/post/{slug}")
-async def post(request: Request, slug: str) -> str:
-    """Individual blog post."""
-    return await _render_content(
-        request.app.state.client, slug, "post", include_date=True
-    )
-
-
-@app.gemini("/page/{slug}")
-async def page(request: Request, slug: str) -> str:
-    """Static page (projects, now, etc.)."""
-    return await _render_content(
-        request.app.state.client, slug, "page", include_date=False
-    )
-
-
-@app.gemini("/about")
-async def about(request: Request) -> str:
-    """About page from feed metadata."""
-    feed = await _get_feed(request.app.state.client)
-    description = feed.feed.get("description", "A personal blog.")
-
-    template = templates.get_template("about.gmi")
-    return template.render(
-        blog_name=settings.blog_name,
-        description=description,
-        bearblog_url=settings.bearblog_url,
-    )
-
-
-def _rfc822_to_iso(date_str: str) -> str:
-    """Convert RFC 822 date to ISO 8601 format for Atom feeds."""
-    if not date_str:
-        return datetime.now().isoformat() + "Z"
-    try:
-        dt = parsedate_to_datetime(date_str)
-        return dt.isoformat().replace("+00:00", "Z")
-    except (ValueError, TypeError):
-        return datetime.now().isoformat() + "Z"
-
-
-@app.gemini("/feed")
-async def feed(request: Request) -> Response:
-    """Atom feed with Gemini URLs."""
-    rss = await _get_feed(request.app.state.client)
-
-    # Use configured gemini_host or fall back to request hostname
-    host = settings.gemini_host or request.hostname or "localhost"
-    base_url = f"gemini://{host}"
-
-    # Get the most recent update time
-    updated = _rfc822_to_iso(rss.feed.get("updated", ""))
-
-    entries = []
-    for entry in rss.entries:
-        link = getattr(entry, "link", None)
-        if not link:
-            continue
-        slug = extract_slug(link)
-        if not slug:
-            continue
-
-        entries.append(
-            {
-                "title": getattr(entry, "title", "Untitled"),
-                "url": f"{base_url}/post/{slug}",
-                "published": _rfc822_to_iso(entry.get("published", "")),
-                "summary": getattr(entry, "description", ""),
-            }
-        )
-
-    template = xml_templates.get_template("feed.xml")
-    atom_xml = template.render(
-        blog_name=settings.blog_name,
-        base_url=base_url,
-        updated=updated,
-        entries=entries,
-    )
-
-    return Response(body=atom_xml, mime_type="application/atom+xml")
-
-
-def main() -> None:
-    """Entry point."""
-    app.run(
-        host=settings.host,
-        port=settings.port,
-        certfile=settings.cert_file,
-        keyfile=settings.key_file,
-    )