Metadata-Version: 2.4
Name: antorc
Version: 0.0.1
Summary: A lightweight, dependency-free communication bridge between frontend and backend applications.
Project-URL: Homepage, https://github.com/yourname/antorc
Project-URL: Issues, https://github.com/yourname/antorc/issues
Author: Your Name
License: MIT
License-File: LICENSE
Keywords: antorc,backend,beginner-friendly,bridge,communication,frontend,http
Classifier: Development Status :: 3 - Alpha
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: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# Antorc

**Antorc** is a lightweight communication bridge between a frontend application and a backend application.

It is **not** a web framework. It does not replace Flask, Django, or FastAPI. It does one small thing well: it lets a frontend send structured data to a backend, and lets a backend respond, without either side dealing with raw HTTP requests, sockets, or JSON serialization by hand.

- ✅ Zero third-party dependencies (pure Python standard library)
- ✅ Simple, Flask-like API
- ✅ Full type hints
- ✅ Clear, catchable exceptions
- ✅ Small enough to read in one sitting

## Install

```bash
pip install antorc
```

(For local development, see [Development](#development) below.)

## Quick start

### 1. Write a backend

```python
# backend.py
from antorc import AntorcServer

server = AntorcServer()

@server.route("/user")
def user(data: dict) -> dict:
    name = data.get("name", "stranger")
    return {"status": "ok", "message": f"Hello, {name}!"}

server.run()  # starts listening on http://127.0.0.1:8000
```

### 2. Write a frontend / client

```python
# frontend.py
from antorc import AntorcClient

client = AntorcClient("http://127.0.0.1:8000")

response = client.send(endpoint="user", data={"name": "John"})
print(response)  # {'status': 'ok', 'message': 'Hello, John!'}
```

That's it. Run `backend.py`, then run `frontend.py` in another terminal.

## Core concepts

Antorc has exactly four things to learn:

### `AntorcClient`

The frontend-side object. It sends a dict of data to a named endpoint and returns the backend's dict response.

```python
client = AntorcClient("http://127.0.0.1:8000", timeout=10.0)
response = client.send(endpoint="user", data={"name": "John"})
```

### `AntorcServer`

The backend-side object. Register a function per endpoint with `@server.route(...)`. Every handler receives a `dict` and must return a `dict` (or `None`).

```python
server = AntorcServer()

@server.route("/user")
def user(data: dict) -> dict:
    return {"status": "ok"}

server.run(host="127.0.0.1", port=8000)
```

### `AntorcMessage`

An optional helper for structuring and serializing `{endpoint, data}` pairs yourself, if you need to store or log messages instead of sending them immediately.

```python
from antorc import AntorcMessage

message = AntorcMessage(endpoint="user", data={"name": "John"})
raw = message.to_json()
restored = AntorcMessage.from_json(raw)
```

### Exceptions

Every error Antorc raises inherits from `AntorcError`, so you can catch broadly or specifically:

```python
from antorc import AntorcClient, AntorcError, AntorcTimeoutError

client = AntorcClient("http://127.0.0.1:8000")

try:
    client.send("user", {"name": "John"})
except AntorcTimeoutError:
    print("The backend took too long to respond.")
except AntorcError as exc:
    print(f"Something went wrong: {exc}")
```

| Exception | Raised when |
|---|---|
| `AntorcConnectionError` | The backend could not be reached at all |
| `AntorcTimeoutError` | The request took longer than the configured timeout |
| `AntorcServerError` | The backend responded with an error status |
| `AntorcValidationError` | Data isn't a JSON-serializable dict, or JSON couldn't be parsed |
| `AntorcRouteNotFoundError` | No handler is registered for the requested endpoint |

## What Antorc is *not*

To keep it simple and focused, Antorc intentionally does **not** include:

- A database or ORM
- An authentication/session system
- HTML templating
- Frontend build tooling
- WebSockets or streaming (may be considered in a future major version)

If you need any of the above, pair Antorc with a real framework — that's exactly what it's designed to sit alongside.

## Development

```bash
git clone https://github.com/yourname/antorc.git
cd antorc
pip install -e ".[dev]"
pytest
```

## License

MIT
