reclie 0.1.0__tar.gz

reclie-0.1.0/LICENSE

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

reclie-0.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+# Ship the Zig sources + build script in the sdist so a source build can run
+# `zig build` (requires Zig on the build machine).
+include build.zig
+recursive-include src *.zig *.c
+include LICENSE README.md
+# Do not ship prebuilt binaries in the sdist.
+recursive-exclude reclie *.pyd *.so

reclie-0.1.0/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: reclie
+Version: 0.1.0
+Summary: A high-performance async HTTP client with a native Zig core.
+Author: Victor Chibuogwu Chukwuemeka
+License: MIT
+Project-URL: Homepage, https://github.com/emekadefirst/reclie
+Keywords: http,https,async,client,zig,tls
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: certifi
+Dynamic: license-file
+
+Reclie - pronouced re -cly
+
+A High peformance python request client that allows developer to make request in python, utilizing the  python simplicity and leveraging on zig to do the heavy lifting, and also bypassing python runtime gil, buffer and bytecode delay
+
+
+with the aim of outperforming all existing client in python. makking super fast light and clean
+
+First is to start with HTTP, HTTPS, and support HTTP2
+
+Next SSE
+
+Lastly WebSocker WS WSS

reclie-0.1.0/README.md

@@ -0,0 +1,12 @@
+Reclie - pronouced re -cly
+
+A High peformance python request client that allows developer to make request in python, utilizing the  python simplicity and leveraging on zig to do the heavy lifting, and also bypassing python runtime gil, buffer and bytecode delay
+
+
+with the aim of outperforming all existing client in python. makking super fast light and clean
+
+First is to start with HTTP, HTTPS, and support HTTP2
+
+Next SSE
+
+Lastly WebSocker WS WSS

reclie-0.1.0/build.zig

@@ -0,0 +1,101 @@
+//! Build the reclie native engine (`_reclie`) as a CPython extension.
+//!
+//! Strategy (see src/root.zig): hand-declared Zig externs for the ABI-stable
+//! CPython functions, plus one tiny C shim (`src/py_module.c`) the C compiler
+//! expands. Targets Py_LIMITED_API 3.11, so a single abi3 wheel serves 3.11+.
+//!
+//! Linking libpython differs per OS:
+//!   * Windows  - link `python3.lib` (the limited-API import lib).
+//!   * else     - do NOT link libpython; the interpreter resolves those
+//!                symbols at import time (`linker_allow_shlib_undefined`).
+//!
+//! Options:
+//!   -Dpython="C:/path/PythonXY"    convenience: derives Include/ and libs/
+//!   -Dpython-include="/path"       explicit dir containing Python.h
+//!   -Dpython-libs="/path"          explicit dir with python3.lib (Windows)
+//!
+//! Output: the built shared library is copied into the package as
+//! `reclie/_reclie.pyd` (Windows) or `reclie/_reclie.abi3.so` (else).
+
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});
+    const os_tag = target.result.os.tag;
+
+    const py_prefix = b.option(
+        []const u8,
+        "python",
+        "Python install prefix (Windows layout: contains Include/ and libs/)",
+    ) orelse "C:/Users/PC/AppData/Local/Programs/Python/Python311";
+
+    const py_include = b.option(
+        []const u8,
+        "python-include",
+        "Directory containing Python.h",
+    ) orelse b.pathJoin(&.{ py_prefix, "Include" });
+
+    const py_libs = b.option(
+        []const u8,
+        "python-libs",
+        "Directory containing python3.lib (Windows only)",
+    ) orelse b.pathJoin(&.{ py_prefix, "libs" });
+
+    const mod = b.createModule(.{
+        .root_source_file = b.path("src/root.zig"),
+        .target = target,
+        .optimize = optimize,
+        .link_libc = true,
+    });
+
+    // CPython headers for the C shim.
+    mod.addIncludePath(.{ .cwd_relative = py_include });
+    mod.addCSourceFile(.{ .file = b.path("src/py_module.c") });
+
+    if (os_tag == .windows) {
+        // Windows requires linking the limited-API import library.
+        mod.addLibraryPath(.{ .cwd_relative = py_libs });
+        // `.use_pkg_config = .no`: without this, Zig may consult a stray
+        // pkg-config on the machine (e.g. Strawberry Perl's on GitHub's Windows
+        // runners) and wrongly link `python3.9`. We just want `python3.lib`
+        // from the path above.
+        mod.linkSystemLibrary("python3", .{ .use_pkg_config = .no }); // -> python3.lib -> python3.dll
+    }
+
+    const lib = b.addLibrary(.{
+        .name = "_reclie",
+        .linkage = .dynamic,
+        .root_module = mod,
+    });
+
+    if (os_tag != .windows) {
+        // libpython symbols are undefined until the interpreter loads us. This
+        // emits `-fallow-shlib-undefined`, which on ELF permits the undefined
+        // symbols and on Mach-O maps to `-undefined dynamic_lookup` (verified:
+        // a macOS-targeted dynamic lib with an undefined extern links only with
+        // this set). So both Linux and macOS are covered.
+        lib.linker_allow_shlib_undefined = true;
+    }
+
+    // Copy the built shared library into the Python package under its abi3
+    // extension name so `from reclie import _reclie` resolves and packaging
+    // picks it up.
+    const ext_name = if (os_tag == .windows)
+        "reclie/_reclie.pyd"
+    else
+        "reclie/_reclie.abi3.so";
+
+    const install_ext = b.addUpdateSourceFiles();
+    install_ext.addCopyFileToSource(lib.getEmittedBin(), ext_name);
+    install_ext.step.dependOn(&lib.step);
+    b.getInstallStep().dependOn(&install_ext.step);
+
+    b.installArtifact(lib);
+
+    // `zig build test` — run the bridge + core unit tests.
+    const tests = b.addTest(.{ .root_module = mod });
+    const run_tests = b.addRunArtifact(tests);
+    const test_step = b.step("test", "Run unit tests");
+    test_step.dependOn(&run_tests.step);
+}

reclie-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "reclie"
+version = "0.1.0"
+description = "A high-performance async HTTP client with a native Zig core."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Victor Chibuogwu Chukwuemeka" }]
+keywords = ["http", "https", "async", "client", "zig", "tls"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+]
+dependencies = ["certifi"]
+
+[project.urls]
+Homepage = "https://github.com/emekadefirst/reclie"
+
+[tool.setuptools]
+# The compiled extension is produced by `zig build` and placed into the wheel
+# by setup.py's build_ext (into build_lib), so it does NOT need to be listed as
+# package-data — and listing it would wrongly ship a stale platform binary
+# (e.g. a Windows _reclie.pyd) that happens to sit in the source tree.
+packages = ["reclie", "reclie.core", "reclie.utils"]
+
+# ---------------------------------------------------------------------------
+# cibuildwheel: build one abi3 wheel per platform (cp311 covers 3.11+).
+# ---------------------------------------------------------------------------
+[tool.cibuildwheel]
+build = "cp311-*"
+skip = ["*-musllinux*", "*_i686", "*-win32"]
+build-frontend = "build"
+# Zig is installed per-OS by the workflow / before-all; confirm it's visible.
+before-build = "zig version"
+test-command = "python -c \"import reclie; print('reclie', reclie.__all__)\""
+
+[tool.cibuildwheel.linux]
+# manylinux containers don't have Zig; fetch a pinned build into the container.
+before-all = "bash {project}/.github/install-zig.sh"
+# RECLIE_ZIG_TARGET pins glibc to the manylinux policy so auditwheel accepts the
+# wheel (Zig otherwise emits glibc-2.36 relocations even in the 2.28 container).
+environment = { PATH = "/opt/zig:$PATH", RECLIE_ZIG_TARGET = "x86_64-linux-gnu.2.28" }
+# Alias (cibuildwheel appends the arch -> quay.io/pypa/manylinux_2_28_x86_64).
+# auditwheel still runs to retag the wheel manylinux; our .so has no third-party
+# shared libs to bundle (only libpython, resolved by the interpreter).
+manylinux-x86_64-image = "manylinux_2_28"
+
+[tool.cibuildwheel.macos]
+# The extension has no third-party dylibs to bundle and the build already tags
+# the wheel macosx_*; delocate has nothing to do, so skip it.
+repair-wheel-command = ""
+
+[tool.uv.workspace]
+members = [
+    "example",
+]

reclie-0.1.0/reclie/__init__.py

@@ -0,0 +1,40 @@
+"""reclie — a high-performance async HTTP client with a native Zig core.
+
+v0.1 scope: HTTP/1.1 and HTTP/2 over ``http`` and ``https``
+
+Public surface::
+
+    import reclie
+
+    client = reclie.Client("api.example.com")
+    resp = await client.get("/products")
+    data = await resp.json()
+"""
+
+from __future__ import annotations
+
+from ._client import Client
+from .core import Method
+from .utils import (
+    ConnectionError,
+    PoolExhaustedError,
+    ProtocolError,
+    RecliError,
+    RecliHeaders,
+    RecliResponse,
+    TimeoutError,
+    TlsError,
+)
+
+__all__ = [
+    "Client",
+    "Method",
+    "RecliResponse",
+    "RecliHeaders",
+    "RecliError",
+    "ConnectionError",
+    "TimeoutError",
+    "TlsError",
+    "ProtocolError",
+    "PoolExhaustedError",
+]

reclie-0.1.0/reclie/_client.py

@@ -0,0 +1,183 @@
+"""The reclie Client facade.
+
+A single, long-lived ``Client`` exposes HTTP/1.1 and HTTP/2 over one
+connection pool. The Python layer is intentionally thin: request
+orchestration lives in :mod:`reclie.core`; this class just owns the pool and
+dispatches to it. (SSE and WebSocket are deferred to a later phase.)
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .core import Headers, Method, Params, request
+from .utils import RecliResponse, TlsError, extension
+
+__all__ = ["Client", "Method"]
+
+
+def _default_ca_bundle_path() -> Optional[str]:
+    """Return a path to a CA bundle file. Tries ``certifi`` first, then
+    ``ssl.get_default_verify_paths().cafile``. Returns ``None`` if neither is
+    available — Client then refuses to construct with ``tls=True``."""
+    try:
+        import certifi
+
+        return certifi.where()
+    except ImportError:
+        try:
+            import ssl
+
+            return ssl.get_default_verify_paths().cafile
+        except Exception:
+            return None
+
+
+class Client:
+    """Origin-bound, reusable async client for HTTP/1.1 and HTTP/2.
+
+    Instantiating a ``Client`` allocates the native connection pool. Keep it
+    alive for the lifetime of your application; do not create one per request.
+    """
+
+    __slots__ = ("host", "port", "tls", "version", "pool_size", "ttl", "timeout", "_ca_path", "_pool")
+
+    def __init__(
+        self,
+        host: str,
+        *,
+        port: Optional[int] = None,
+        tls: Optional[bool] = None,
+        version: int = 2,
+        pool_size: int = 64,
+        ttl: int = 60,
+        timeout: float = 30.0,
+        ca_bundle: Optional[bytes] = None,
+        ca_bundle_path: Optional[str] = None,
+    ) -> None:
+        if version not in (1, 2):
+            raise ValueError("version must be 1 or 2")
+
+        # Scheme/port inference: https on 443, http otherwise.
+        if tls is None:
+            tls = port is None or port == 443
+        if port is None:
+            port = 443 if tls else 80
+
+        self.host = host
+        self.port = port
+        self.tls = tls
+        self.version = version
+        self.pool_size = pool_size
+        self.ttl = ttl
+        self.timeout = timeout
+
+        # Resolve a CA bundle *file path* for TLS (the native engine loads it).
+        # Precedence:
+        #   1. Caller-supplied ``ca_bundle_path``
+        #   2. Caller-supplied ``ca_bundle`` (raw PEM bytes -> temp file)
+        #   3. ``certifi.where()`` if installed
+        #   4. ``ssl.get_default_verify_paths().cafile``
+        if not tls:
+            self._ca_path = ""
+        elif ca_bundle_path is not None:
+            self._ca_path = ca_bundle_path
+        elif ca_bundle is not None:
+            import tempfile
+
+            tmp = tempfile.NamedTemporaryFile(
+                prefix="reclie-ca-", suffix=".pem", delete=False
+            )
+            tmp.write(ca_bundle)
+            tmp.close()
+            self._ca_path = tmp.name
+        else:
+            self._ca_path = _default_ca_bundle_path() or ""
+
+        if tls and not self._ca_path:
+            raise TlsError(
+                "No CA bundle available for TLS. Install `certifi` or pass "
+                "`ca_bundle`/`ca_bundle_path` to Client(...)."
+            )
+
+        self._pool = extension().pool_create(
+            host, port, tls, version, pool_size, ttl, self._timeout_ms,
+            self._ca_path,
+        )
+
+    @property
+    def _timeout_ms(self) -> int:
+        return int(self.timeout * 1000)
+
+    # ---- HTTP -----------------------------------------------------------
+
+    async def get(
+        self,
+        path: str,
+        *,
+        headers: Optional[Headers] = None,
+        params: Optional[Params] = None,
+    ) -> RecliResponse:
+        return await request(
+            self._pool, Method.GET, path,
+            version=self.version, timeout_ms=self._timeout_ms,
+            headers=headers, params=params,
+        )
+
+    async def post(
+        self,
+        path: str,
+        *,
+        json: Optional[Any] = None,
+        data: Optional[bytes] = None,
+        headers: Optional[Headers] = None,
+        params: Optional[Params] = None,
+    ) -> RecliResponse:
+        return await request(
+            self._pool, Method.POST, path,
+            version=self.version, timeout_ms=self._timeout_ms,
+            headers=headers, params=params, json=json, data=data,
+        )
+
+    async def put(
+        self,
+        path: str,
+        *,
+        json: Optional[Any] = None,
+        data: Optional[bytes] = None,
+        headers: Optional[Headers] = None,
+        params: Optional[Params] = None,
+    ) -> RecliResponse:
+        return await request(
+            self._pool, Method.PUT, path,
+            version=self.version, timeout_ms=self._timeout_ms,
+            headers=headers, params=params, json=json, data=data,
+        )
+
+    async def patch(
+        self,
+        path: str,
+        *,
+        json: Optional[Any] = None,
+        data: Optional[bytes] = None,
+        headers: Optional[Headers] = None,
+        params: Optional[Params] = None,
+    ) -> RecliResponse:
+        return await request(
+            self._pool, Method.PATCH, path,
+            version=self.version, timeout_ms=self._timeout_ms,
+            headers=headers, params=params, json=json, data=data,
+        )
+
+    async def delete(
+        self,
+        path: str,
+        *,
+        headers: Optional[Headers] = None,
+        params: Optional[Params] = None,
+    ) -> RecliResponse:
+        return await request(
+            self._pool, Method.DELETE, path,
+            version=self.version, timeout_ms=self._timeout_ms,
+            headers=headers, params=params,
+        )

reclie-0.1.0/reclie/core/__init__.py

@@ -0,0 +1,10 @@
+"""Protocol orchestration for reclie.
+
+Scope for v0.1: HTTP/1.1 and HTTP/2 over plain TCP (http) and TLS (https).
+SSE and WebSocket are deferred; they will land here as ``sse`` / ``ws``
+modules once the HTTP core is solid.
+"""
+
+from .http import Headers, Method, Params, request
+
+__all__ = ["Headers", "Method", "Params", "request"]

reclie-0.1.0/reclie/core/http.py

@@ -0,0 +1,144 @@
+"""HTTP request orchestration.
+
+Builds the request descriptor (path + query, flat header list, byte body),
+creates the ``asyncio.Future``, and hands everything to the native engine. The
+engine performs all I/O off the GIL and settles the Future via
+``loop.call_soon_threadsafe``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import enum
+import json as _json
+from typing import Any, Mapping, Optional, Union
+from urllib.parse import urlencode
+
+from ..utils import (
+    ConnectionError,
+    ProtocolError,
+    RecliError,
+    RecliResponse,
+    TimeoutError,
+    TlsError,
+    extension,
+)
+
+__all__ = ["Method", "Headers", "Params", "request"]
+
+# Error-kind ordinals shared with the Zig engine (src/root.zig). 0 == success.
+_ERR_CLASSES = {
+    1: ConnectionError,
+    2: TimeoutError,
+    3: TlsError,
+    4: ProtocolError,
+}
+
+
+def _settle(
+    future: "asyncio.Future[RecliResponse]",
+    status: int,
+    headers: dict,
+    body: bytes,
+    err_kind: int,
+    err_msg: str,
+) -> None:
+    """Resolve ``future`` from the engine callback.
+
+    Scheduled via ``loop.call_soon_threadsafe`` from the Zig I/O thread, so this
+    always runs on the event-loop thread — the only safe place to touch a Future.
+    """
+    if future.cancelled():
+        return
+    if err_kind:
+        exc_cls = _ERR_CLASSES.get(err_kind, RecliError)
+        future.set_exception(exc_cls(err_msg))
+    else:
+        future.set_result(RecliResponse(status, headers, body=body))
+
+Headers = Mapping[str, str]
+Params = Mapping[str, Union[str, int, float, bool]]
+
+
+class Method(enum.IntEnum):
+    """HTTP methods, matching the Zig ``Method`` enum ordinals."""
+
+    GET = 0
+    POST = 1
+    PUT = 2
+    PATCH = 3
+    DELETE = 4
+    HEAD = 5
+    OPTIONS = 6
+
+
+def _build_path(path: str, params: Optional[Params]) -> str:
+    if not params:
+        return path
+    query = urlencode({k: str(v) for k, v in params.items()})
+    sep = "&" if "?" in path else "?"
+    return f"{path}{sep}{query}"
+
+
+def _prepare_body(
+    headers: Optional[Headers],
+    json: Optional[Any],
+    data: Optional[bytes],
+) -> tuple[list[tuple[str, str]], bytes]:
+    """Normalize headers + body into a flat header list and raw byte body."""
+    if json is not None and data is not None:
+        raise ValueError("Pass either `json` or `data`, not both.")
+
+    header_list: list[tuple[str, str]] = []
+    has_content_type = False
+    if headers:
+        for key, value in headers.items():
+            if key.lower() == "content-type":
+                has_content_type = True
+            header_list.append((key, str(value)))
+
+    if json is not None:
+        body = _json.dumps(json, separators=(",", ":")).encode("utf-8")
+        if not has_content_type:
+            header_list.append(("Content-Type", "application/json"))
+    elif data is not None:
+        body = data
+    else:
+        body = b""
+
+    return header_list, body
+
+
+async def request(
+    pool: Any,
+    method: Method,
+    path: str,
+    *,
+    version: int,
+    timeout_ms: int,
+    headers: Optional[Headers] = None,
+    params: Optional[Params] = None,
+    json: Optional[Any] = None,
+    data: Optional[bytes] = None,
+) -> RecliResponse:
+    """Issue a single HTTP request and await its response."""
+    loop = asyncio.get_running_loop()
+    future: asyncio.Future[RecliResponse] = loop.create_future()
+
+    full_path = _build_path(path, params)
+    header_list, body = _prepare_body(headers, json, data)
+
+    # Non-blocking hand-off: the engine drops the GIL, performs all I/O,
+    # then settles `future` via loop.call_soon_threadsafe.
+    extension().submit(
+        pool,
+        int(method),
+        full_path,
+        header_list,
+        body,
+        version,
+        timeout_ms,
+        future,
+        loop,
+    )
+    return await future

reclie-0.1.0/reclie/main.py

@@ -0,0 +1,6 @@
+def main():
+    print("Hello from reclie!")
+
+
+if __name__ == "__main__":
+    main()

reclie-0.1.0/reclie/utils/__init__.py

@@ -0,0 +1,28 @@
+"""Internal helpers: extension loader, response types, exceptions.
+
+This subpackage aggregates the implementation details so the top-level
+package can re-export the public surface from one place.
+"""
+
+from ._exceptions import (
+    ConnectionError,
+    PoolExhaustedError,
+    ProtocolError,
+    RecliError,
+    TimeoutError,
+    TlsError,
+)
+from ._ext import extension
+from ._response import RecliHeaders, RecliResponse
+
+__all__ = [
+    "extension",
+    "RecliHeaders",
+    "RecliResponse",
+    "RecliError",
+    "ConnectionError",
+    "TimeoutError",
+    "TlsError",
+    "ProtocolError",
+    "PoolExhaustedError",
+]