Quick Start¶

This tutorial will show you how to make your first Spartan protocol requests using Teyaotlani.

Level: Beginner Time: 10 minutes

Prerequisites¶

Teyaotlani installed

Making a simple request¶

The easiest way to fetch content from a Spartan server is using the get() function:

import asyncio
from teyaotlani import get

async def main():
    response = await get("spartan://example.com/")
    print(f"Status: {response.status}")
    print(f"Meta: {response.meta}")
    print(f"Body: {response.body}")

asyncio.run(main())

The get() function is a convenience wrapper that handles creating and closing a client connection for you.

Using the SpartanClient¶

For multiple requests or more control, use SpartanClient as an async context manager:

import asyncio
from teyaotlani import SpartanClient

async def main():
    async with SpartanClient() as client:
        # Make multiple requests with the same client
        response1 = await client.get("spartan://example.com/")
        response2 = await client.get("spartan://example.com/about.gmi")

        print(response1.body)
        print(response2.body)

asyncio.run(main())

Understanding responses¶

Every response from a Spartan server includes:

Attribute	Description
`status`	The numeric status code (2, 3, 4, or 5)
`meta`	Additional information (MIME type for success, redirect URL, or error message)
`body`	The response body content (for successful requests)

Status codes¶

The Spartan protocol uses single-digit status codes:

Code	Meaning	Meta contains
2	Success	MIME type of the content
3	Redirect	URL to redirect to
4	Client error	Error message
5	Server error	Error message

Checking response status¶

Use the helper functions to check response status:

from teyaotlani import get, is_success, is_redirect, is_error

async def main():
    response = await get("spartan://example.com/")

    if is_success(response.status):
        print(f"Got content: {response.body[:100]}...")
    elif is_redirect(response.status):
        print(f"Redirected to: {response.meta}")
    elif is_error(response.status):
        print(f"Error: {response.meta}")

Using the CLI¶

Teyaotlani includes a command-line tool for quick requests:

# Fetch a page
teyaotlani get spartan://example.com/

# Save output to a file
teyaotlani get spartan://example.com/document.gmi -o document.gmi

Running a quick server¶

You can serve files from your current directory with a single command:

# Serve files from the current directory
teyaotlani serve .

# Serve from a specific directory on a custom port
teyaotlani serve ./my-capsule --port 3000

The server will start on port 300 (the default Spartan port) unless you specify otherwise.

Port 300 requires privileges

Ports below 1024 typically require root/administrator privileges. For development, use a higher port like --port 3000.

Next steps¶

Now that you know the basics, you can: