pybearings 0.2.0__tar.gz

pybearings-0.2.0/.gitignore

@@ -0,0 +1,24 @@
+# build output (compiles, benchmarks, test runs, fetched tools)
+/build/
+# fpmake output (tools/install-package.sh)
+/units/
+/fpmake
+/*.fpm
+/conformance/target/
+target/
+__pycache__/
+*.o
+*.ppu
+*.a
+*.compiled
+# editors and temporary files
+*~
+*.swp
+*.orig
+*.rej
+.DS_Store
+# python/: compiled by python/hatch_build.py
+/python/src/bearings/libbearings.so
+/python/src/bearings/bearings.h
+/python/.venv/
+/python/dist/

pybearings-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Juan-Pablo Scaletti
+
+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.

pybearings-0.2.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.5
+Name: pybearings
+Version: 0.2.0
+Summary: Bearings, the Free Pascal HTTP/1.1 server, as a WSGI server for Python
+Author-email: Juan Pablo Scaletti <juanpablo@jpscaletti.com>
+License-Expression: MIT
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
+Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Server
+Requires-Python: >=3.14
+Requires-Dist: cffi>=2.0
+Description-Content-Type: text/markdown
+
+# pyBearings
+
+[Bearings](https://github.com/fp-40/Bearings), the Free Pascal HTTP/1.1 server, as a WSGI server for Python. Linux only (x86_64 and ARM64); free-threaded Python works.
+
+```python
+from bearings import serve
+
+serve(app, port=8000)  # until SIGINT or SIGTERM
+```
+
+The event loops are Bearings' own threads and never run Python. Every request runs the WSGI app on a thread of the worker pool, so the app may block.
+
+`Server(app, **options)` starts and stops a server from code (tests, a process that does other things): `start()`, `port`, `stop(grace)`, `wait()`, `metrics()`, or `with Server(app) as server:`. Its docstring lists the options: the address, a Unix socket or an inherited socket, the number of event loops and workers, a queue limit answered with 503, a connection limit, the access log and the metrics.
+
+With `websocket=`, a `WebSocketHandler`, the server also accepts WebSockets on `ws_path`: its `opened`, `received` and `closed` run on the worker pool, one event at a time per connection, and `ws_send`, `ws_close`, `subscribe`, `unsubscribe` and `publish` reach the connections by id, from any thread. A publish goes to every subscriber of a topic, encoded once.
+
+With `raw=True`, the server calls `app(head, input, listener)` instead of a WSGI app. `head` is the request head as Bearings sends it (the method, path, query, version, client address and port, then a name and a value per header, each followed by `"\0"`), `input` is the body and `listener` says where the server listens. The app returns `(status, headers, body)`. A framework that builds its own request object saves building an environ only to take it apart again. `RawHandler` describes the arguments.
+
+The package loads `libbearings.so` (`src/capi/` in this repository) with cffi in ABI mode, so it needs no C compiler: building the wheel needs Free Pascal 3.2.2 (`fpc`), which `hatch_build.py` runs.
+
+## Development
+
+```sh
+uv sync --python 3.14t     # compiles libbearings.so into src/bearings/
+uv run pytest
+```
+
+## Wheels
+
+`uv build --wheel` builds the wheel for this machine's CPU (`manylinux_2_34_x86_64` here).
+The manylinux tag is the newest glibc symbol version `libbearings.so` needs, read with `objdump -T` (binutils).
+For ARM64, give it the cross compiler of `tools/get-cross-aarch64.sh`; the wheel is tagged for the CPU that compiler targets:
+
+```sh
+PYBEARINGS_FPC=../build/tools/bin/fpc-aarch64 uv build --wheel   # manylinux_2_34_aarch64
+```
+
+`uv build` also builds the sdist, which holds the Pascal sources of `../src/` in `pascal/`, and builds the wheel from it.
+Installing from the sdist needs Free Pascal 3.2.2 and binutils.
+
+`./test-aarch64.sh` does that, installs the wheel in a free-threaded CPython
+for ARM64 run under qemu-user, and runs the tests against it. qemu-user runs
+on the host's memory model, which is stronger than ARM's: it shows that the
+wheel builds, loads and works, not races that only ARM hardware has.

pybearings-0.2.0/README.md

@@ -0,0 +1,44 @@
+# pyBearings
+
+[Bearings](https://github.com/fp-40/Bearings), the Free Pascal HTTP/1.1 server, as a WSGI server for Python. Linux only (x86_64 and ARM64); free-threaded Python works.
+
+```python
+from bearings import serve
+
+serve(app, port=8000)  # until SIGINT or SIGTERM
+```
+
+The event loops are Bearings' own threads and never run Python. Every request runs the WSGI app on a thread of the worker pool, so the app may block.
+
+`Server(app, **options)` starts and stops a server from code (tests, a process that does other things): `start()`, `port`, `stop(grace)`, `wait()`, `metrics()`, or `with Server(app) as server:`. Its docstring lists the options: the address, a Unix socket or an inherited socket, the number of event loops and workers, a queue limit answered with 503, a connection limit, the access log and the metrics.
+
+With `websocket=`, a `WebSocketHandler`, the server also accepts WebSockets on `ws_path`: its `opened`, `received` and `closed` run on the worker pool, one event at a time per connection, and `ws_send`, `ws_close`, `subscribe`, `unsubscribe` and `publish` reach the connections by id, from any thread. A publish goes to every subscriber of a topic, encoded once.
+
+With `raw=True`, the server calls `app(head, input, listener)` instead of a WSGI app. `head` is the request head as Bearings sends it (the method, path, query, version, client address and port, then a name and a value per header, each followed by `"\0"`), `input` is the body and `listener` says where the server listens. The app returns `(status, headers, body)`. A framework that builds its own request object saves building an environ only to take it apart again. `RawHandler` describes the arguments.
+
+The package loads `libbearings.so` (`src/capi/` in this repository) with cffi in ABI mode, so it needs no C compiler: building the wheel needs Free Pascal 3.2.2 (`fpc`), which `hatch_build.py` runs.
+
+## Development
+
+```sh
+uv sync --python 3.14t     # compiles libbearings.so into src/bearings/
+uv run pytest
+```
+
+## Wheels
+
+`uv build --wheel` builds the wheel for this machine's CPU (`manylinux_2_34_x86_64` here).
+The manylinux tag is the newest glibc symbol version `libbearings.so` needs, read with `objdump -T` (binutils).
+For ARM64, give it the cross compiler of `tools/get-cross-aarch64.sh`; the wheel is tagged for the CPU that compiler targets:
+
+```sh
+PYBEARINGS_FPC=../build/tools/bin/fpc-aarch64 uv build --wheel   # manylinux_2_34_aarch64
+```
+
+`uv build` also builds the sdist, which holds the Pascal sources of `../src/` in `pascal/`, and builds the wheel from it.
+Installing from the sdist needs Free Pascal 3.2.2 and binutils.
+
+`./test-aarch64.sh` does that, installs the wheel in a free-threaded CPython
+for ARM64 run under qemu-user, and runs the tests against it. qemu-user runs
+on the host's memory model, which is stronger than ARM's: it shows that the
+wheel builds, loads and works, not races that only ARM hardware has.

pybearings-0.2.0/hatch_build.py

@@ -0,0 +1,110 @@
+"""Compiles libbearings.so with Free Pascal.
+
+An editable install gets it next to the package's modules (for this
+machine). A wheel gets it from a directory of its own per CPU, so a wheel
+for another CPU leaves the editable install alone: `PYBEARINGS_FPC` names
+the compiler, for example the ARM64 cross compiler of
+tools/get-cross-aarch64.sh, and the wheel is tagged for the CPU that
+compiler targets (`fpc -iTP`), and for the newest glibc symbol version
+libbearings.so needs (`objdump -T`).
+
+    PYBEARINGS_FPC=../build/tools/bin/fpc-aarch64 uv build --wheel
+
+The Pascal sources are in src/ of the repository, or in pascal/ of an
+unpacked sdist (force-include in pyproject.toml).
+"""
+
+import os
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+UNITS = ("rt", "http", "http1", "server", "ws", "capi")
+
+# fpc -iTP -> the wheel's platform tag
+CPUS = {
+    "x86_64": "x86_64",
+    "aarch64": "aarch64",
+}
+
+
+def manylinux(library: Path) -> str:
+    """The manylinux tag for `library`: the newest glibc symbol version it
+    needs, which is the oldest glibc that loads it."""
+    objdump = shutil.which("objdump")
+    if not objdump:
+        raise RuntimeError("tagging the pybearings wheel needs objdump (binutils)")
+
+    symbols = subprocess.run(
+        [objdump, "-T", str(library)], check=True, capture_output=True, text=True
+    ).stdout
+    versions = {
+        tuple(int(n) for n in v.split("."))
+        for v in re.findall(r"\bGLIBC_(\d+(?:\.\d+)+)\b", symbols)
+    }
+    if not versions:
+        raise RuntimeError(f"no glibc symbol in {library}: is it linked against glibc?")
+
+    major, minor = max(versions)[:2]
+    return f"manylinux_{major}_{minor}"
+
+
+class CustomBuildHook(BuildHookInterface):
+    def initialize(self, version: str, build_data: dict) -> None:
+        if not sys.platform.startswith("linux"):
+            raise RuntimeError("Bearings runs only on Linux")
+
+        fpc = os.environ.get("PYBEARINGS_FPC") or shutil.which("fpc")
+        if not fpc:
+            raise RuntimeError("building pybearings needs Free Pascal >= 3.2.2 (fpc)")
+
+        fpc = str(Path(fpc).resolve()) if os.sep in fpc else fpc
+        cpu = subprocess.run([fpc, "-iTP"], check=True, capture_output=True, text=True).stdout.strip()
+
+        if cpu not in CPUS:
+            raise RuntimeError(f"pybearings builds for {', '.join(CPUS)}, not {cpu}")
+
+        if (Path(self.root) / "pascal").is_dir():  # an unpacked sdist
+            root = Path(self.root)
+            src = root / "pascal"
+        else:  # python/ of the repository
+            root = Path(self.root).parent
+            src = root / "src"
+        if version == "editable":
+            out = Path(self.root) / "src" / "bearings"  # imported from here
+        else:
+            out = root / "build" / f"python-{cpu}"
+
+        units = root / "build" / f"python-units-{cpu}"
+        for directory in (out, units):
+            directory.mkdir(parents=True, exist_ok=True)
+
+        command = [
+            fpc,
+            "-Mobjfpc",
+            "-Sh",
+            "-O2",
+            "-fPIC",
+            "-vew",
+            *(f"-Fu{src / unit}" for unit in UNITS),
+            f"-Fi{src / 'rt'}",
+            f"-FU{units}",
+            f"-o{out / 'libbearings.so'}",
+            str(src / "capi" / "libbearings.pas"),
+        ]
+        subprocess.run(command, check=True)
+        shutil.copyfile(src / "capi" / "bearings.h", out / "bearings.h")
+
+        if version != "editable":
+            build_data["force_include"][str(out / "libbearings.so")] = (
+                "bearings/libbearings.so"
+            )
+            build_data["force_include"][str(out / "bearings.h")] = "bearings/bearings.h"
+
+        build_data["pure_python"] = False
+        build_data["tag"] = f"py3-none-{manylinux(out / 'libbearings.so')}_{CPUS[cpu]}"