bitpoint 0.1.0__tar.gz

bitpoint-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,22 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

bitpoint-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/
+.pytest_cache/
+bitpoint.pid
+uv.lock
+CLAUDE.md

bitpoint-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.20
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format

bitpoint-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andros Fenollosa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bitpoint-0.1.0/PKG-INFO

@@ -0,0 +1,299 @@
+Metadata-Version: 2.4
+Name: bitpoint
+Version: 0.1.0
+Summary: Create HTTP endpoints quickly using files, without going through a framework.
+Project-URL: Homepage, https://github.com/tanrax/bitpoint
+Project-URL: Repository, https://github.com/tanrax/bitpoint
+Project-URL: Issues, https://github.com/tanrax/bitpoint/issues
+Author-email: Andros Fenollosa <andros@fenollosa.email>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: endpoints,file-based-routing,http,microframework,pep723,webhooks
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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 :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.9
+Requires-Dist: flask>=3.0
+Description-Content-Type: text/markdown
+
+# Bitpoint
+
+Create HTTP endpoints quickly using files, without going through a framework like Flask or FastAPI.
+
+- **File-based routing**: the directory structure defines the routes, the file name defines the HTTP method.
+- **Hot reload**: save the file and the server updates automatically. Deploy with a simple `git pull`.
+- **Per-endpoint dependencies**: each endpoint declares its dependencies with [PEP 723](https://peps.python.org/pep-0723/) and they are installed automatically in an isolated environment.
+
+Bitpoint is for the moments when a full project feels like too much: exposing a script as a webhook, mocking an API so the frontend can move forward, publishing a small internal service for your team, or keeping a handful of endpoints alive on a personal server. In all these cases the API is not the product, it is just plumbing, and spending an afternoon on scaffolding, virtual environments and deploy pipelines is out of proportion. With Bitpoint you write one file and you get one endpoint.
+
+Under the hood, Bitpoint stays out of your way. There is nothing to register and nothing to configure: no app object, no decorators, no config files, just a `handle` function per file. Dependency isolation is delegated to [uv](https://docs.astral.sh/uv/), with a cached environment per endpoint, so two endpoints can use incompatible versions of the same library without ever conflicting. Responses follow the type you return: a string becomes plain text, a dict becomes JSON, a tuple adds a status code and headers, and the sensible thing happens by default.
+
+## Installation
+
+```bash
+pip install bitpoint
+```
+
+Or, if you use [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install bitpoint
+```
+
+Python 3.9 or later. If you want per-endpoint dependencies, `uv` must be available on the server.
+
+## Quickstart
+
+Create a directory called `routes` and, inside it, a subdirectory called `hello` (this will be the route). Inside `hello`, create a file called `get.py` with the following content:
+
+```python
+# routes/hello/get.py
+
+def handle(request):
+    return "world"
+```
+
+Start the server with:
+
+```bash
+python -m bitpoint
+```
+
+You can now try your endpoint:
+
+```bash
+curl localhost:8000/hello
+```
+
+It will return:
+
+```
+world
+```
+
+## Routing
+
+The URL path maps to the directory path inside `routes`, and the HTTP method maps to the file name:
+
+```
+routes/
+├── hello/
+│   └── get.py          → GET  /hello
+├── users/
+│   ├── get.py          → GET  /users
+│   ├── post.py         → POST /users
+│   └── [id]/
+│       ├── get.py      → GET  /users/42
+│       └── delete.py   → DELETE /users/42
+└── lib/                → shared code, does not generate routes
+    └── db.py
+```
+
+Valid file names are the HTTP methods in lowercase: `get.py`, `post.py`, `put.py`, `patch.py`, `delete.py`, `head.py` and `options.py`. Any other file is ignored and does not generate routes, so you can keep helper modules next to your endpoints.
+
+### Dynamic routes
+
+A directory whose name is wrapped in brackets captures a URL segment:
+
+```python
+# routes/users/[id]/get.py
+
+def handle(request):
+    return {"user_id": request.params["id"]}
+```
+
+```bash
+curl localhost:8000/users/42
+# {"user_id": "42"}
+```
+
+Captured values always arrive as `str`. Type conversion is the endpoint's responsibility.
+
+## The `handle` contract
+
+Each endpoint exposes a `handle(request)` function. It is the only symbol Bitpoint looks for in the file, the rest of the module is yours.
+
+### The `request` object
+
+| Attribute | Type | Description |
+|---|---|---|
+| `request.method` | `str` | HTTP method in uppercase, for example `"GET"` |
+| `request.path` | `str` | Request path, for example `/users/42` |
+| `request.params` | `dict[str, str]` | Dynamic path segments |
+| `request.args` | `dict[str, str]` | Query string parameters |
+| `request.headers` | `dict[str, str]` | Headers, case-insensitive keys |
+| `request.body` | `bytes` | Raw request body |
+| `request.json()` | `Any` | Body parsed as JSON, raises a 400 error if invalid |
+
+Example with a query string:
+
+```python
+# routes/greet/get.py
+
+def handle(request):
+    name = request.args.get("name", "world")
+    return f"Hello, {name}!"
+```
+
+```bash
+curl "localhost:8000/greet?name=Bob"
+# Hello, Bob!
+```
+
+### Return values
+
+The return type determines the response:
+
+| Return | Response |
+|---|---|
+| `str` | `200`, `text/plain; charset=utf-8` |
+| `dict` or `list` | `200`, `application/json` |
+| `bytes` | `200`, `application/octet-stream` |
+| `(body, status)` | As above, with the given status code |
+| `(body, status, headers)` | Additionally with custom headers |
+| `None` | `204 No Content` |
+
+```python
+# routes/users/post.py
+
+def handle(request):
+    data = request.json()
+    return {"created": data["name"]}, 201
+```
+
+### Errors
+
+- If `handle` raises an exception, Bitpoint responds with `500`.
+- In development mode (the default) the body includes the traceback. In production (`--production`) the body is a generic message and the traceback goes to the log.
+- Path with no matching directory: `404`. Directory exists but there is no file for that method: `405` with the `Allow` header listing the available methods.
+
+## Dependencies
+
+Declare each endpoint's dependencies with a [PEP 723](https://peps.python.org/pep-0723/) block at the top of the file, the same format understood by `uv` and `pipx`:
+
+```python
+# routes/status/get.py
+
+# /// script
+# dependencies = ["requests"]
+# ///
+
+def handle(request):
+    import requests
+    return requests.get("https://example.com").json()
+```
+
+Bitpoint delegates resolution and installation to [uv](https://docs.astral.sh/uv/): each endpoint runs with its dependencies in an isolated, cached environment. Two endpoints can use incompatible versions of the same library without conflict.
+
+- An endpoint without a PEP 723 block runs in the base environment, with no extra cost.
+- Installation happens on first startup and whenever the dependency block changes, not on every request.
+
+> **Security note**: installing dependencies automatically after a `git pull` means running third-party code at deploy time. If you prefer to control that step, start with `--no-install` and Bitpoint will fail with a clear error on endpoints whose dependencies are not already installed.
+
+## Shared code
+
+The `routes/lib/` directory is reserved: it does not generate routes and is importable from any endpoint:
+
+```python
+# routes/lib/db.py
+
+def get_connection():
+    ...
+```
+
+```python
+# routes/users/get.py
+
+from lib.db import get_connection
+
+def handle(request):
+    conn = get_connection()
+    ...
+```
+
+## Configuration
+
+Everything is controlled from the command line, there is no configuration file:
+
+```bash
+python -m bitpoint [options]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--port` | `8000` | Listening port |
+| `--host` | `127.0.0.1` | Listening address |
+| `--dir` | `./routes` | Root directory for endpoints |
+| `--production` | disabled | Hides tracebacks and disables filesystem-based hot reload |
+| `--no-install` | disabled | Does not install dependencies automatically |
+
+## Hot reload
+
+In development mode, Bitpoint watches the `routes` directory and reloads each module when its file changes. There is no shared state across reloads: if your endpoint keeps in-memory state (caches, connections), it is lost on reload. For persistent state use external resources (a database, Redis, files).
+
+In production, filesystem-based reload is disabled. The recommended deploy flow is `git pull` followed by a reload signal:
+
+```bash
+git pull && kill -HUP $(cat bitpoint.pid)
+```
+
+## A real example
+
+A GitHub webhook that sends a Telegram message on every push:
+
+```python
+# routes/webhooks/github/post.py
+
+# /// script
+# dependencies = ["requests"]
+# ///
+import os
+import requests
+
+def handle(request):
+    if request.headers.get("x-github-event") != "push":
+        return None
+    payload = request.json()
+    pusher = payload["pusher"]["name"]
+    repo = payload["repository"]["name"]
+    commits = len(payload["commits"])
+    requests.post(
+        f"https://api.telegram.org/bot{os.environ['TELEGRAM_TOKEN']}/sendMessage",
+        json={
+            "chat_id": os.environ["TELEGRAM_CHAT_ID"],
+            "text": f"{pusher} pushed {commits} commit(s) to {repo}",
+        },
+    )
+    return None
+```
+
+One file, deployed with a `git pull`. No project, no virtualenv, no route registration, no restart.
+
+## Why not Flask or FastAPI?
+
+Use Flask or FastAPI when the API is your product: they are excellent frameworks and Bitpoint does not try to compete with them.
+
+Bitpoint is for when the API is just plumbing. A webhook here, an internal endpoint there, a mock for the frontend. In those cases a framework gives you power you will not use at the price of ceremony you have to pay every time: a project to scaffold, an app to configure, routes to register, a virtualenv to maintain and a server to restart. Bitpoint removes all of that by turning the decisions into conventions: the filesystem is the router, the file is the endpoint, and its header declares its dependencies.
+
+If an endpoint outgrows Bitpoint, nothing locks you in: `handle` is a plain function, and moving it to a Flask or FastAPI route is a copy-paste.
+
+## Small core
+
+Some areas are explicitly not covered in order to keep the core small:
+
+- Middleware and global hooks
+- Authentication
+- WebSockets and streaming
+- `async` endpoints
+- Static files
+
+If you need any of this today, Bitpoint is not your tool, you will have to use external tools.

bitpoint-0.1.0/README.md

@@ -0,0 +1,272 @@
+# Bitpoint
+
+Create HTTP endpoints quickly using files, without going through a framework like Flask or FastAPI.
+
+- **File-based routing**: the directory structure defines the routes, the file name defines the HTTP method.
+- **Hot reload**: save the file and the server updates automatically. Deploy with a simple `git pull`.
+- **Per-endpoint dependencies**: each endpoint declares its dependencies with [PEP 723](https://peps.python.org/pep-0723/) and they are installed automatically in an isolated environment.
+
+Bitpoint is for the moments when a full project feels like too much: exposing a script as a webhook, mocking an API so the frontend can move forward, publishing a small internal service for your team, or keeping a handful of endpoints alive on a personal server. In all these cases the API is not the product, it is just plumbing, and spending an afternoon on scaffolding, virtual environments and deploy pipelines is out of proportion. With Bitpoint you write one file and you get one endpoint.
+
+Under the hood, Bitpoint stays out of your way. There is nothing to register and nothing to configure: no app object, no decorators, no config files, just a `handle` function per file. Dependency isolation is delegated to [uv](https://docs.astral.sh/uv/), with a cached environment per endpoint, so two endpoints can use incompatible versions of the same library without ever conflicting. Responses follow the type you return: a string becomes plain text, a dict becomes JSON, a tuple adds a status code and headers, and the sensible thing happens by default.
+
+## Installation
+
+```bash
+pip install bitpoint
+```
+
+Or, if you use [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install bitpoint
+```
+
+Python 3.9 or later. If you want per-endpoint dependencies, `uv` must be available on the server.
+
+## Quickstart
+
+Create a directory called `routes` and, inside it, a subdirectory called `hello` (this will be the route). Inside `hello`, create a file called `get.py` with the following content:
+
+```python
+# routes/hello/get.py
+
+def handle(request):
+    return "world"
+```
+
+Start the server with:
+
+```bash
+python -m bitpoint
+```
+
+You can now try your endpoint:
+
+```bash
+curl localhost:8000/hello
+```
+
+It will return:
+
+```
+world
+```
+
+## Routing
+
+The URL path maps to the directory path inside `routes`, and the HTTP method maps to the file name:
+
+```
+routes/
+├── hello/
+│   └── get.py          → GET  /hello
+├── users/
+│   ├── get.py          → GET  /users
+│   ├── post.py         → POST /users
+│   └── [id]/
+│       ├── get.py      → GET  /users/42
+│       └── delete.py   → DELETE /users/42
+└── lib/                → shared code, does not generate routes
+    └── db.py
+```
+
+Valid file names are the HTTP methods in lowercase: `get.py`, `post.py`, `put.py`, `patch.py`, `delete.py`, `head.py` and `options.py`. Any other file is ignored and does not generate routes, so you can keep helper modules next to your endpoints.
+
+### Dynamic routes
+
+A directory whose name is wrapped in brackets captures a URL segment:
+
+```python
+# routes/users/[id]/get.py
+
+def handle(request):
+    return {"user_id": request.params["id"]}
+```
+
+```bash
+curl localhost:8000/users/42
+# {"user_id": "42"}
+```
+
+Captured values always arrive as `str`. Type conversion is the endpoint's responsibility.
+
+## The `handle` contract
+
+Each endpoint exposes a `handle(request)` function. It is the only symbol Bitpoint looks for in the file, the rest of the module is yours.
+
+### The `request` object
+
+| Attribute | Type | Description |
+|---|---|---|
+| `request.method` | `str` | HTTP method in uppercase, for example `"GET"` |
+| `request.path` | `str` | Request path, for example `/users/42` |
+| `request.params` | `dict[str, str]` | Dynamic path segments |
+| `request.args` | `dict[str, str]` | Query string parameters |
+| `request.headers` | `dict[str, str]` | Headers, case-insensitive keys |
+| `request.body` | `bytes` | Raw request body |
+| `request.json()` | `Any` | Body parsed as JSON, raises a 400 error if invalid |
+
+Example with a query string:
+
+```python
+# routes/greet/get.py
+
+def handle(request):
+    name = request.args.get("name", "world")
+    return f"Hello, {name}!"
+```
+
+```bash
+curl "localhost:8000/greet?name=Bob"
+# Hello, Bob!
+```
+
+### Return values
+
+The return type determines the response:
+
+| Return | Response |
+|---|---|
+| `str` | `200`, `text/plain; charset=utf-8` |
+| `dict` or `list` | `200`, `application/json` |
+| `bytes` | `200`, `application/octet-stream` |
+| `(body, status)` | As above, with the given status code |
+| `(body, status, headers)` | Additionally with custom headers |
+| `None` | `204 No Content` |
+
+```python
+# routes/users/post.py
+
+def handle(request):
+    data = request.json()
+    return {"created": data["name"]}, 201
+```
+
+### Errors
+
+- If `handle` raises an exception, Bitpoint responds with `500`.
+- In development mode (the default) the body includes the traceback. In production (`--production`) the body is a generic message and the traceback goes to the log.
+- Path with no matching directory: `404`. Directory exists but there is no file for that method: `405` with the `Allow` header listing the available methods.
+
+## Dependencies
+
+Declare each endpoint's dependencies with a [PEP 723](https://peps.python.org/pep-0723/) block at the top of the file, the same format understood by `uv` and `pipx`:
+
+```python
+# routes/status/get.py
+
+# /// script
+# dependencies = ["requests"]
+# ///
+
+def handle(request):
+    import requests
+    return requests.get("https://example.com").json()
+```
+
+Bitpoint delegates resolution and installation to [uv](https://docs.astral.sh/uv/): each endpoint runs with its dependencies in an isolated, cached environment. Two endpoints can use incompatible versions of the same library without conflict.
+
+- An endpoint without a PEP 723 block runs in the base environment, with no extra cost.
+- Installation happens on first startup and whenever the dependency block changes, not on every request.
+
+> **Security note**: installing dependencies automatically after a `git pull` means running third-party code at deploy time. If you prefer to control that step, start with `--no-install` and Bitpoint will fail with a clear error on endpoints whose dependencies are not already installed.
+
+## Shared code
+
+The `routes/lib/` directory is reserved: it does not generate routes and is importable from any endpoint:
+
+```python
+# routes/lib/db.py
+
+def get_connection():
+    ...
+```
+
+```python
+# routes/users/get.py
+
+from lib.db import get_connection
+
+def handle(request):
+    conn = get_connection()
+    ...
+```
+
+## Configuration
+
+Everything is controlled from the command line, there is no configuration file:
+
+```bash
+python -m bitpoint [options]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--port` | `8000` | Listening port |
+| `--host` | `127.0.0.1` | Listening address |
+| `--dir` | `./routes` | Root directory for endpoints |
+| `--production` | disabled | Hides tracebacks and disables filesystem-based hot reload |
+| `--no-install` | disabled | Does not install dependencies automatically |
+
+## Hot reload
+
+In development mode, Bitpoint watches the `routes` directory and reloads each module when its file changes. There is no shared state across reloads: if your endpoint keeps in-memory state (caches, connections), it is lost on reload. For persistent state use external resources (a database, Redis, files).
+
+In production, filesystem-based reload is disabled. The recommended deploy flow is `git pull` followed by a reload signal:
+
+```bash
+git pull && kill -HUP $(cat bitpoint.pid)
+```
+
+## A real example
+
+A GitHub webhook that sends a Telegram message on every push:
+
+```python
+# routes/webhooks/github/post.py
+
+# /// script
+# dependencies = ["requests"]
+# ///
+import os
+import requests
+
+def handle(request):
+    if request.headers.get("x-github-event") != "push":
+        return None
+    payload = request.json()
+    pusher = payload["pusher"]["name"]
+    repo = payload["repository"]["name"]
+    commits = len(payload["commits"])
+    requests.post(
+        f"https://api.telegram.org/bot{os.environ['TELEGRAM_TOKEN']}/sendMessage",
+        json={
+            "chat_id": os.environ["TELEGRAM_CHAT_ID"],
+            "text": f"{pusher} pushed {commits} commit(s) to {repo}",
+        },
+    )
+    return None
+```
+
+One file, deployed with a `git pull`. No project, no virtualenv, no route registration, no restart.
+
+## Why not Flask or FastAPI?
+
+Use Flask or FastAPI when the API is your product: they are excellent frameworks and Bitpoint does not try to compete with them.
+
+Bitpoint is for when the API is just plumbing. A webhook here, an internal endpoint there, a mock for the frontend. In those cases a framework gives you power you will not use at the price of ceremony you have to pay every time: a project to scaffold, an app to configure, routes to register, a virtualenv to maintain and a server to restart. Bitpoint removes all of that by turning the decisions into conventions: the filesystem is the router, the file is the endpoint, and its header declares its dependencies.
+
+If an endpoint outgrows Bitpoint, nothing locks you in: `handle` is a plain function, and moving it to a Flask or FastAPI route is a copy-paste.
+
+## Small core
+
+Some areas are explicitly not covered in order to keep the core small:
+
+- Middleware and global hooks
+- Authentication
+- WebSockets and streaming
+- `async` endpoints
+- Static files
+
+If you need any of this today, Bitpoint is not your tool, you will have to use external tools.

bitpoint-0.1.0/bitpoint/__init__.py

@@ -0,0 +1,8 @@
+"""Bitpoint: create HTTP endpoints quickly using files.
+
+This module is intentionally import-light: it is imported inside the
+per-endpoint environments (which only need `bitpoint.request` and
+`bitpoint.response`), so nothing here may import Flask.
+"""
+
+__version__ = "0.1.0"