wasat 0.0.1__tar.gz

wasat-0.0.1/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: wasat
+Version: 0.0.1
+Summary: A async client library for the Gemini protocol
+Keywords: API,async,client,library,Gemini
+Author: Dave Pearson
+Author-email: Dave Pearson <davep@davep.org>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Project-URL: Homepage, https://wasat.davep.dev/
+Project-URL: Repository, https://github.com/davep/wasat
+Project-URL: Documentation, https://wasat.davep.dev/
+Project-URL: Source, https://github.com/davep/wasat
+Project-URL: Issues, https://github.com/davep/wasat/issues
+Project-URL: Discussions, https://github.com/davep/wasat/discussions
+Description-Content-Type: text/markdown
+
+# Wasat: Async Gemini Protocol Client Library
+
+Wasat is an object-oriented, fully type-hinted asynchronous client library for the [Gemini Protocol](gemini://geminiprotocol.net), built with zero external dependencies.
+
+## Features
+
+- **Async All the Way**: Built on top of Python's standard `asyncio` loop with streaming/chunking support.
+- **Type Safe**: Fully typed API utilizing Python 3.14 standards (strictly avoiding `Any`).
+- **TOFU (Trust-On-First-Use) Support**: Secure by default with a built-in file-based TOFU store and custom interactive trust confirmation hooks.
+- **Auto Redirect Handling**: Automatically handles temporary and permanent redirects (with protection against loops and infinite redirect limits), caching permanent redirects locally.
+- **Client Authentication**: Native support for client TLS certificates.
+- **Zero-Dependency**: Runs purely on Python's standard library.
+- **CLI Utility**: Includes a `wasat` command-line interface out of the box.
+
+---
+
+## Installation
+
+You can install `wasat` directly in your project virtual environment using `uv` or `pip`:
+
+```bash
+uv pip install -e .
+# or
+pip install -e .
+```
+
+---
+
+## Quick Start
+
+### 1. Make a Simple Request
+Use `Client` with standard async context managers to query a Gemini capsule and decode the response:
+
+```python
+import asyncio
+from wasat import Client, WasatError
+
+async def main():
+    # 'tofu' mode is ideal for standard Gemini capsules (self-signed certs)
+    client = Client(verify_mode="tofu")
+
+    try:
+        # Perform the request (automatically resolves host, port, TLS, and redirects)
+        async with await client.request("gemini://geminiprotocol.net/") as response:
+            print(f"Status: {response.status.value} ({response.status.name})")
+            print(f"MIME type: {response.mime_type}")
+
+            # Fetch the decoded body text
+            body = await response.text()
+            print(body)
+
+    except WasatError as e:
+        print(f"Request failed: {e}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### 2. Streaming Chunk Responses
+For large files or media streams, read the response body in chunks to prevent exhausting memory:
+
+```python
+async with await client.request("gemini://example.com/large-file.txt") as response:
+    if response.status.is_success:
+        async for chunk in response.iter_chunks(chunk_size=1024):
+            # Process each chunk as it arrives
+            sys.stdout.buffer.write(chunk)
+```
+
+### 3. Client Certificate Authentication
+If a server requires client auth (status code `60`), supply your certificate files to the client configuration:
+
+```python
+client = Client(
+    verify_mode="tofu",
+    client_cert="/path/to/client.crt",
+    client_key="/path/to/client.key"  # Optional if key is embedded in cert
+)
+```
+
+### 4. Interactive TOFU Confirmation
+Implement a custom asynchronous callback to prompt the user before trusting new self-signed certificates:
+
+```python
+import sys
+
+async def confirm_cert(host: str, port: int, fingerprint: str) -> bool:
+    print(f"New certificate encountered for {host}:{port}")
+    print(f"Fingerprint: sha256:{fingerprint}")
+    response = input("Do you trust this certificate? [y/N]: ").strip().lower()
+    return response == "y"
+
+client = Client(
+    verify_mode="tofu",
+    on_new_certificate=confirm_cert
+)
+```
+
+---
+
+## Command Line Interface (CLI)
+
+Wasat comes with a command-line interface to fetch Gemini capsules from your shell:
+
+```bash
+# Basic fetch using the entrypoint script (uses TOFU)
+uv run wasat gemini://geminiprotocol.net/
+
+# Alternatively, execute the package directly using python -m
+uv run python -m wasat gemini://geminiprotocol.net/
+
+# Fetch a local or custom port capsule
+uv run wasat gemini://localhost:1965/index.gmi
+```
+
+## License
+
+MIT
+
+[//]: # (README.md ends here)

wasat-0.0.1/README.md

@@ -0,0 +1,120 @@
+# Wasat: Async Gemini Protocol Client Library
+
+Wasat is an object-oriented, fully type-hinted asynchronous client library for the [Gemini Protocol](gemini://geminiprotocol.net), built with zero external dependencies.
+
+## Features
+
+- **Async All the Way**: Built on top of Python's standard `asyncio` loop with streaming/chunking support.
+- **Type Safe**: Fully typed API utilizing Python 3.14 standards (strictly avoiding `Any`).
+- **TOFU (Trust-On-First-Use) Support**: Secure by default with a built-in file-based TOFU store and custom interactive trust confirmation hooks.
+- **Auto Redirect Handling**: Automatically handles temporary and permanent redirects (with protection against loops and infinite redirect limits), caching permanent redirects locally.
+- **Client Authentication**: Native support for client TLS certificates.
+- **Zero-Dependency**: Runs purely on Python's standard library.
+- **CLI Utility**: Includes a `wasat` command-line interface out of the box.
+
+---
+
+## Installation
+
+You can install `wasat` directly in your project virtual environment using `uv` or `pip`:
+
+```bash
+uv pip install -e .
+# or
+pip install -e .
+```
+
+---
+
+## Quick Start
+
+### 1. Make a Simple Request
+Use `Client` with standard async context managers to query a Gemini capsule and decode the response:
+
+```python
+import asyncio
+from wasat import Client, WasatError
+
+async def main():
+    # 'tofu' mode is ideal for standard Gemini capsules (self-signed certs)
+    client = Client(verify_mode="tofu")
+
+    try:
+        # Perform the request (automatically resolves host, port, TLS, and redirects)
+        async with await client.request("gemini://geminiprotocol.net/") as response:
+            print(f"Status: {response.status.value} ({response.status.name})")
+            print(f"MIME type: {response.mime_type}")
+
+            # Fetch the decoded body text
+            body = await response.text()
+            print(body)
+
+    except WasatError as e:
+        print(f"Request failed: {e}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### 2. Streaming Chunk Responses
+For large files or media streams, read the response body in chunks to prevent exhausting memory:
+
+```python
+async with await client.request("gemini://example.com/large-file.txt") as response:
+    if response.status.is_success:
+        async for chunk in response.iter_chunks(chunk_size=1024):
+            # Process each chunk as it arrives
+            sys.stdout.buffer.write(chunk)
+```
+
+### 3. Client Certificate Authentication
+If a server requires client auth (status code `60`), supply your certificate files to the client configuration:
+
+```python
+client = Client(
+    verify_mode="tofu",
+    client_cert="/path/to/client.crt",
+    client_key="/path/to/client.key"  # Optional if key is embedded in cert
+)
+```
+
+### 4. Interactive TOFU Confirmation
+Implement a custom asynchronous callback to prompt the user before trusting new self-signed certificates:
+
+```python
+import sys
+
+async def confirm_cert(host: str, port: int, fingerprint: str) -> bool:
+    print(f"New certificate encountered for {host}:{port}")
+    print(f"Fingerprint: sha256:{fingerprint}")
+    response = input("Do you trust this certificate? [y/N]: ").strip().lower()
+    return response == "y"
+
+client = Client(
+    verify_mode="tofu",
+    on_new_certificate=confirm_cert
+)
+```
+
+---
+
+## Command Line Interface (CLI)
+
+Wasat comes with a command-line interface to fetch Gemini capsules from your shell:
+
+```bash
+# Basic fetch using the entrypoint script (uses TOFU)
+uv run wasat gemini://geminiprotocol.net/
+
+# Alternatively, execute the package directly using python -m
+uv run python -m wasat gemini://geminiprotocol.net/
+
+# Fetch a local or custom port capsule
+uv run wasat gemini://localhost:1965/index.gmi
+```
+
+## License
+
+MIT
+
+[//]: # (README.md ends here)

wasat-0.0.1/pyproject.toml

@@ -0,0 +1,108 @@
+[project]
+name = "wasat"
+version = "0.0.1"
+description = "A async client library for the Gemini protocol"
+readme = "README.md"
+authors = [
+    { name = "Dave Pearson", email = "davep@davep.org" }
+]
+requires-python = ">=3.12"
+dependencies = []
+license = "MIT"
+keywords = [
+    "API",
+    "async",
+    "client",
+    "library",
+    "Gemini",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://wasat.davep.dev/"
+Repository = "https://github.com/davep/wasat"
+Documentation = "https://wasat.davep.dev/"
+Source = "https://github.com/davep/wasat"
+Issues = "https://github.com/davep/wasat/issues"
+Discussions = "https://github.com/davep/wasat/discussions"
+
+[project.scripts]
+wasat = "wasat.__main__:main"
+
+[build-system]
+requires = ["uv_build>=0.11.21,<0.12.0"]
+build-backend = "uv_build"
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true
+
+[dependency-groups]
+dev = [
+    "codespell>=2.4.2",
+    "mypy>=2.1.0",
+    "pre-commit>=4.6.0",
+    "ruff>=0.15.17",
+]
+docs = [
+    "mkdocs>=1.6.1,<2",
+    "mkdocs-material>=9.7.6",
+    "mkdocstrings[python]>=1.0.4",
+]
+test = [
+    "pytest>=9.1.0",
+    "pytest-cov>=7.1.0",
+]
+
+[tool.pyright]
+venvPath="."
+venv=".venv"
+exclude=[".venv"]
+
+[tool.ruff.lint]
+select = [
+    # pycodestyle
+    "E",
+    # Pyflakes
+    "F",
+    # pyupgrade
+    "UP",
+    # flake8-bugbear
+    "B",
+    # flake8-simplify
+    "SIM",
+    # isort
+    "I",
+]
+
+[tool.ruff.lint.pycodestyle]
+max-line-length = 120
+
+[tool.coverage.run]
+omit = [
+     "tests/*"
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+    "class .*\\bProtocol\\):",
+    "@(abc\\.)?abstractmethod",
+]

wasat-0.0.1/src/wasat/__init__.py

@@ -0,0 +1,51 @@
+"""Wasat: An asynchronous, type-hinted client library for the Gemini Protocol."""
+
+##############################################################################
+# Python imports.
+from importlib.metadata import version
+
+######################################################################
+# Main library information.
+__author__ = "Dave Pearson"
+__copyright__ = "Copyright 2026, Dave Pearson"
+__credits__ = ["Dave Pearson"]
+__maintainer__ = "Dave Pearson"
+__email__ = "davep@davep.org"
+__version__: str = version("wasat")
+__licence__ = "MIT"
+
+##############################################################################
+# Local imports.
+from .client import Client
+from .exceptions import (
+    ConnectionError,
+    ProtocolError,
+    RedirectError,
+    SecurityError,
+    URIError,
+    WasatError,
+)
+from .response import Response
+from .status import StatusCode
+from .trust import FileTrustStore, TrustStore
+from .uri import GEMINI_DEFAULT_PORT, GeminiURI
+
+##############################################################################
+# Exports.
+__all__ = [
+    "Client",
+    "Response",
+    "StatusCode",
+    "GeminiURI",
+    "GEMINI_DEFAULT_PORT",
+    "TrustStore",
+    "FileTrustStore",
+    "WasatError",
+    "URIError",
+    "ProtocolError",
+    "ConnectionError",
+    "SecurityError",
+    "RedirectError",
+]
+
+### __init__.py ends here

wasat-0.0.1/src/wasat/__main__.py

@@ -0,0 +1,78 @@
+"""Entry point for executing the wasat package directly."""
+
+##############################################################################
+# Python imports.
+from argparse import ArgumentParser, Namespace
+from asyncio import run
+from sys import exit, stderr
+
+##############################################################################
+# Local imports.
+from . import Client, WasatError, __version__
+
+
+##############################################################################
+def get_args() -> Namespace:
+    """Parse command-line arguments.
+
+    Returns:
+        Namespace: Parsed command-line arguments.
+    """
+    parser = ArgumentParser(
+        prog="wasat",
+        description="An asynchronous client library and CLI for the Gemini protocol.",
+    )
+    parser.add_argument(
+        "url",
+        help="The Gemini URL to request.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Enable verbose output.",
+    )
+
+    return parser.parse_args()
+
+
+##############################################################################
+async def run_cli() -> None:
+    """Run the Wasat CLI asynchronously."""
+    args = get_args()
+
+    try:
+        async with await Client(verify_mode="tofu").request(args.url) as response:
+            if args.verbose or not response.status.is_success:
+                print("--- Gemini Response ---")
+                print(f"Status: {response.status.value} ({response.status.name})")
+                print(f"Meta: {response.meta}")
+                print("-----------------------")
+            if response.status.is_success:
+                print(await response.text())
+            else:
+                exit(1)
+    except WasatError as e:
+        print(f"Error: {e}", file=stderr)
+        exit(1)
+
+
+##############################################################################
+def main() -> None:
+    """CLI entry point."""
+    try:
+        run(run_cli())
+    except KeyboardInterrupt:
+        exit(130)
+
+
+##############################################################################
+if __name__ == "__main__":
+    main()
+
+### __main__.py ends here