httpp 0.1.0__tar.gz → 0.4.0__tar.gz

httpp-0.4.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.2
+Name: httpp
+Version: 0.4.0
+Summary: A Cython project with scikit-build
+Author-Email: Mohammad Raziei <mohammadraziei1375@gmail.com>
+License: MIT
+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.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Project-URL: Homepage, https://github.com/MohammadRaziei/httpp
+Project-URL: Bug Tracker, https://github.com/MohammadRaziei/httpp/issues
+Project-URL: Document, https://MohammadRaziei.github.io/httpp
+Requires-Python: >=3.8
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-xdist>=3.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0; extra == "test"
+Description-Content-Type: text/markdown
+
+# httpp
+
+<div align="center">
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.txt)
+[![CMake 3.21+](https://img.shields.io/badge/CMake-3.21+-blue.svg)](https://cmake.org/)
+[![C++17](https://img.shields.io/badge/C++-17-blue.svg)](https://en.cppreference.com/w/cpp/17)
+[![Python 3.8+](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/)
+
+</div>
+
+A lightweight HTTP **client + server** library for C++ and Python.
+`pip install httpp` and you get: a Python package, a CLI, a compiled C++
+library with headers and a CMake config — no system dependencies at all
+(no `apt`/`choco`/`brew`, nothing outside what `pip` already gives you).
+
+## Why
+
+- **Client and server in one library** — most lightweight HTTP libraries
+  only do one side.
+- **Zero system dependencies** — every third-party piece is vendored and
+  built from source.
+- **One `pip install`, three ways in** — Python API, a CLI, and a real C++
+  library (headers + `find_package(httpp)`) all come from the same wheel.
+- **A migration path for existing `libcurl` code** — `httpp/curl_compat.h`
+  gives you `curl_easy_*` so you can often switch with just a header swap.
+
+## Install
+
+```bash
+pip install httpp
+```
+
+## Quick start
+
+### Python
+
+```python
+from httpp import Client, Server, DownloadFile, CurlRequest
+
+# client
+res = Client.fetch("http://example.com/")
+print(res.status, res.body)
+
+# server — like `python -m http.server`, but embeddable in your own app
+srv = Server()
+srv.serve_directory("/", "./public")
+srv.listen("0.0.0.0", 8000)
+
+# download a file, with a tqdm-like progress bar
+DownloadFile("http://example.com/big.zip").output("big.zip").run()
+
+# a small curl-flavored request builder
+res = CurlRequest("http://example.com/api").method("POST").data("a=1").run()
+```
+
+### CLI
+
+```bash
+httpp server .                              # serve the current directory
+httpp download http://example.com/          # print body to stdout
+httpp download http://example.com/f.zip -o f.zip   # save to a file, with a progress bar
+httpp curl -X POST -H "X-Token: abc" -d "a=1" http://example.com/api
+httpp install --user                        # put headers/lib/cmake config on your system
+```
+
+### C++
+
+```cpp
+#include <httpp.h>
+
+auto res = httpp::client::fetch("http://example.com/");
+
+httpp::server srv;
+srv.get("/hello", [](const httpp::request&, httpp::response& res) {
+    res.status = 200;
+    res.body = "world";
+});
+srv.listen("0.0.0.0", 8000);
+
+httpp::download_file("http://example.com/f.zip").output("f.zip").run();
+
+auto res2 = httpp::curl::request("http://example.com/api")
+                .method("POST")
+                .header("X-Token", "abc")
+                .data("a=1")
+                .run();
+```
+
+### Migrating from libcurl
+
+```c
+#include <httpp/curl_compat.h>   /* was: #include <curl/curl.h> */
+
+CURL *curl = curl_easy_init();
+curl_easy_setopt(curl, CURLOPT_URL, "http://example.com/");
+curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_cb);
+curl_easy_setopt(curl, CURLOPT_WRITEDATA, &out);
+CURLcode rc = curl_easy_perform(curl);
+curl_easy_cleanup(curl);
+```
+
+Covers the common `curl_easy_*` subset (URL, method, headers, POST data,
+write callback, timeout, follow-redirect, response code) — not a full
+libcurl replacement. See the comment at the top of `curl_compat.h` for the
+exact list.
+
+### Using it from CMake, from a plain `pip install`
+
+No system-wide install needed — point CMake at the package Python already
+installed:
+
+```cmake
+execute_process(
+    COMMAND python3 -c "import httpp; print(httpp.get_cmake_dir())"
+    OUTPUT_VARIABLE httpp_DIR
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+)
+find_package(httpp CONFIG REQUIRED)
+target_link_libraries(app PRIVATE httpp::httpp_core)
+```
+
+Or, after `httpp install [--user]`, plain `find_package(httpp)` works with
+no Python involved at all — see [`tests/cmake/consumer_project`](tests/cmake/consumer_project)
+for a full working example.
+
+## Build from source
+
+```bash
+git clone --recurse-submodules https://github.com/MohammadRaziei/httpp.git
+cd httpp
+pip install -r requirements-dev.txt
+cmake -B build -DHTTPP_BUILD_TESTS=ON -DHTTPP_BUILD_PYTHON=ON
+cmake --build build -j4
+ctest --test-dir build --output-on-failure   # C++, Python, and CMake-integration tests
+```
+
+## Status
+
+- [x] `httpp::client` — GET requests; `.fetch(url)` parses a full URL in one call
+- [x] `httpp::server` — route handlers, static directory serving
+- [x] `httpp::curl` — a small curl-flavored fluent request builder (method/headers/data)
+- [x] `httpp::download_file` — fluent download builder with a terminal progress bar
+      (sync `.run()` and async `.run_async()`)
+- [x] `httpp::progress` — `bar` (tqdm-like) and `range` (trange-like)
+- [x] `httpp/curl_compat.h` — a `curl_easy_*` C API subset for migrating
+      existing libcurl code, built directly on `httpp::curl::request`
+- [x] CLI — `server`, `download`, `curl`, `install`/`uninstall`
+- [x] Python bindings for `Client`, `Server`, `DownloadFile`, `CurlRequest`
+- [ ] HTTPS
+- [ ] Route handlers from Python (directory serving works today; custom
+      routes are C++-only for now)
+
+## License
+
+MIT

httpp-0.4.0/README.md

@@ -0,0 +1,156 @@
+# httpp
+
+<div align="center">
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.txt)
+[![CMake 3.21+](https://img.shields.io/badge/CMake-3.21+-blue.svg)](https://cmake.org/)
+[![C++17](https://img.shields.io/badge/C++-17-blue.svg)](https://en.cppreference.com/w/cpp/17)
+[![Python 3.8+](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/)
+
+</div>
+
+A lightweight HTTP **client + server** library for C++ and Python.
+`pip install httpp` and you get: a Python package, a CLI, a compiled C++
+library with headers and a CMake config — no system dependencies at all
+(no `apt`/`choco`/`brew`, nothing outside what `pip` already gives you).
+
+## Why
+
+- **Client and server in one library** — most lightweight HTTP libraries
+  only do one side.
+- **Zero system dependencies** — every third-party piece is vendored and
+  built from source.
+- **One `pip install`, three ways in** — Python API, a CLI, and a real C++
+  library (headers + `find_package(httpp)`) all come from the same wheel.
+- **A migration path for existing `libcurl` code** — `httpp/curl_compat.h`
+  gives you `curl_easy_*` so you can often switch with just a header swap.
+
+## Install
+
+```bash
+pip install httpp
+```
+
+## Quick start
+
+### Python
+
+```python
+from httpp import Client, Server, DownloadFile, CurlRequest
+
+# client
+res = Client.fetch("http://example.com/")
+print(res.status, res.body)
+
+# server — like `python -m http.server`, but embeddable in your own app
+srv = Server()
+srv.serve_directory("/", "./public")
+srv.listen("0.0.0.0", 8000)
+
+# download a file, with a tqdm-like progress bar
+DownloadFile("http://example.com/big.zip").output("big.zip").run()
+
+# a small curl-flavored request builder
+res = CurlRequest("http://example.com/api").method("POST").data("a=1").run()
+```
+
+### CLI
+
+```bash
+httpp server .                              # serve the current directory
+httpp download http://example.com/          # print body to stdout
+httpp download http://example.com/f.zip -o f.zip   # save to a file, with a progress bar
+httpp curl -X POST -H "X-Token: abc" -d "a=1" http://example.com/api
+httpp install --user                        # put headers/lib/cmake config on your system
+```
+
+### C++
+
+```cpp
+#include <httpp.h>
+
+auto res = httpp::client::fetch("http://example.com/");
+
+httpp::server srv;
+srv.get("/hello", [](const httpp::request&, httpp::response& res) {
+    res.status = 200;
+    res.body = "world";
+});
+srv.listen("0.0.0.0", 8000);
+
+httpp::download_file("http://example.com/f.zip").output("f.zip").run();
+
+auto res2 = httpp::curl::request("http://example.com/api")
+                .method("POST")
+                .header("X-Token", "abc")
+                .data("a=1")
+                .run();
+```
+
+### Migrating from libcurl
+
+```c
+#include <httpp/curl_compat.h>   /* was: #include <curl/curl.h> */
+
+CURL *curl = curl_easy_init();
+curl_easy_setopt(curl, CURLOPT_URL, "http://example.com/");
+curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_cb);
+curl_easy_setopt(curl, CURLOPT_WRITEDATA, &out);
+CURLcode rc = curl_easy_perform(curl);
+curl_easy_cleanup(curl);
+```
+
+Covers the common `curl_easy_*` subset (URL, method, headers, POST data,
+write callback, timeout, follow-redirect, response code) — not a full
+libcurl replacement. See the comment at the top of `curl_compat.h` for the
+exact list.
+
+### Using it from CMake, from a plain `pip install`
+
+No system-wide install needed — point CMake at the package Python already
+installed:
+
+```cmake
+execute_process(
+    COMMAND python3 -c "import httpp; print(httpp.get_cmake_dir())"
+    OUTPUT_VARIABLE httpp_DIR
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+)
+find_package(httpp CONFIG REQUIRED)
+target_link_libraries(app PRIVATE httpp::httpp_core)
+```
+
+Or, after `httpp install [--user]`, plain `find_package(httpp)` works with
+no Python involved at all — see [`tests/cmake/consumer_project`](tests/cmake/consumer_project)
+for a full working example.
+
+## Build from source
+
+```bash
+git clone --recurse-submodules https://github.com/MohammadRaziei/httpp.git
+cd httpp
+pip install -r requirements-dev.txt
+cmake -B build -DHTTPP_BUILD_TESTS=ON -DHTTPP_BUILD_PYTHON=ON
+cmake --build build -j4
+ctest --test-dir build --output-on-failure   # C++, Python, and CMake-integration tests
+```
+
+## Status
+
+- [x] `httpp::client` — GET requests; `.fetch(url)` parses a full URL in one call
+- [x] `httpp::server` — route handlers, static directory serving
+- [x] `httpp::curl` — a small curl-flavored fluent request builder (method/headers/data)
+- [x] `httpp::download_file` — fluent download builder with a terminal progress bar
+      (sync `.run()` and async `.run_async()`)
+- [x] `httpp::progress` — `bar` (tqdm-like) and `range` (trange-like)
+- [x] `httpp/curl_compat.h` — a `curl_easy_*` C API subset for migrating
+      existing libcurl code, built directly on `httpp::curl::request`
+- [x] CLI — `server`, `download`, `curl`, `install`/`uninstall`
+- [x] Python bindings for `Client`, `Server`, `DownloadFile`, `CurlRequest`
+- [ ] HTTPS
+- [ ] Route handlers from Python (directory serving works today; custom
+      routes are C++-only for now)
+
+## License
+
+MIT

httpp-0.4.0/include/httpp/curl.hpp

@@ -0,0 +1,52 @@
+#pragma once
+
+#include "httpp/export.hpp"
+#include "httpp/client.hpp" // reuses httpp::response
+
+#include <memory>
+#include <string>
+
+namespace httpp::curl {
+
+// A small, curl-flavored fluent request builder — the common cases only
+// (-X method, -H headers, -d data), NOT a libcurl API/ABI compatible shim
+// (that's a much bigger, different project; see httpp::client for the
+// plain request API this is built on). Backed by the same vendored
+// cpp-httplib as the rest of httpp, hidden behind this pointer (see
+// src/core/curl.cpp) and never exposed in this public header.
+class HTTPP_API request {
+public:
+    explicit request(std::string url);
+    ~request();
+
+    request(request&&) noexcept;
+    request& operator=(request&&) noexcept;
+    request(const request&) = delete;
+    request& operator=(const request&) = delete;
+
+    // -X METHOD (GET/POST/PUT/PATCH/DELETE). If never called, defaults to
+    // GET, unless data() was called, in which case it defaults to POST —
+    // matching curl's own behavior.
+    request& method(std::string m);
+
+    // -H "Name: value"
+    request& header(std::string name, std::string value);
+
+    // -d "body" (sets Content-Type to application/x-www-form-urlencoded
+    // unless content_type() overrides it)
+    request& data(std::string body);
+
+    request& content_type(std::string type);
+
+    // -m/--max-time (seconds), -L/--location
+    request& timeout(long seconds);
+    request& follow_redirects(bool enable = true);
+
+    response run() const;
+
+private:
+    struct impl;
+    std::unique_ptr<impl> impl_;
+};
+
+} // namespace httpp::curl

httpp-0.4.0/include/httpp/curl_compat.h

@@ -0,0 +1,94 @@
+#pragma once
+
+/*
+ * A small, drop-in-ish subset of libcurl's `curl_easy_*` C API — meant to
+ * let existing code migrate to httpp with (ideally) just a header swap:
+ *
+ *     -#include <curl/curl.h>
+ *     +#include <httpp/curl_compat.h>
+ *
+ * This is NOT a full libcurl replacement: only the commonly used easy-API
+ * subset below is implemented, and every curl_easy_setopt() call is
+ * forwarded to (and reuses the exact same code as) httpp::curl::request
+ * (see include/httpp/curl.hpp, src/core/curl_compat.cpp) — there is no
+ * separate/duplicated HTTP implementation here.
+ *
+ * Covered: CURLOPT_URL, CURLOPT_CUSTOMREQUEST, CURLOPT_HTTPGET,
+ * CURLOPT_POST, CURLOPT_POSTFIELDS(+SIZE), CURLOPT_HTTPHEADER,
+ * CURLOPT_WRITEFUNCTION/DATA, CURLOPT_USERAGENT, CURLOPT_TIMEOUT,
+ * CURLOPT_FOLLOWLOCATION, curl_slist_*, curl_easy_getinfo
+ * (CURLINFO_RESPONSE_CODE), curl_easy_strerror, curl_global_init/cleanup.
+ *
+ * NOT covered (no such option exists here — curl_easy_setopt() returns
+ * CURLE_UNKNOWN_OPTION for anything not listed above): proxies, cookies,
+ * TLS/certificate options, auth (basic/digest/bearer), multipart forms,
+ * response header callbacks, multi/share handles, and everything else in
+ * real libcurl's ~300 CURLOPT_* options.
+ */
+
+#include "httpp/export.hpp"
+
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct CURL CURL;
+
+typedef enum {
+    CURLE_OK = 0,
+    CURLE_UNSUPPORTED_PROTOCOL,
+    CURLE_COULDNT_CONNECT,
+    CURLE_HTTP_RETURNED_ERROR,
+    CURLE_WRITE_ERROR,
+    CURLE_OUT_OF_MEMORY,
+    CURLE_OPERATION_TIMEDOUT,
+    CURLE_BAD_FUNCTION_ARGUMENT,
+    CURLE_UNKNOWN_OPTION
+} CURLcode;
+
+typedef enum {
+    CURLOPT_URL,
+    CURLOPT_CUSTOMREQUEST,
+    CURLOPT_HTTPGET,
+    CURLOPT_POST,
+    CURLOPT_POSTFIELDS,
+    CURLOPT_POSTFIELDSIZE,
+    CURLOPT_HTTPHEADER,
+    CURLOPT_WRITEFUNCTION,
+    CURLOPT_WRITEDATA,
+    CURLOPT_USERAGENT,
+    CURLOPT_TIMEOUT,
+    CURLOPT_FOLLOWLOCATION,
+    CURLOPT_VERBOSE /* accepted, has no effect */
+} CURLoption;
+
+typedef enum {
+    CURLINFO_RESPONSE_CODE
+} CURLINFO;
+
+typedef size_t (*curl_write_callback)(char* ptr, size_t size, size_t nmemb, void* userdata);
+
+struct curl_slist {
+    char* data;
+    struct curl_slist* next;
+};
+
+HTTPP_API CURL* curl_easy_init(void);
+HTTPP_API void curl_easy_cleanup(CURL* curl);
+HTTPP_API CURLcode curl_easy_setopt(CURL* curl, CURLoption option, ...);
+HTTPP_API CURLcode curl_easy_perform(CURL* curl);
+HTTPP_API CURLcode curl_easy_getinfo(CURL* curl, CURLINFO info, ...);
+HTTPP_API const char* curl_easy_strerror(CURLcode code);
+
+HTTPP_API struct curl_slist* curl_slist_append(struct curl_slist* list, const char* value);
+HTTPP_API void curl_slist_free_all(struct curl_slist* list);
+
+#define CURL_GLOBAL_DEFAULT 0L
+HTTPP_API CURLcode curl_global_init(long flags);
+HTTPP_API void curl_global_cleanup(void);
+
+#ifdef __cplusplus
+}
+#endif

{httpp-0.1.0 → httpp-0.4.0}/include/httpp.h

@@ -38,8 +38,8 @@
  *============================================================================*/
 
 #define HTTPP_VERSION_MAJOR 0
-#define HTTPP_VERSION_MINOR 1
-#define HTTPP_VERSION_PATCH 1
+#define HTTPP_VERSION_MINOR 4
+#define HTTPP_VERSION_PATCH 0
 
 /*==============================================================================
  * MARK: - Public API
@@ -51,5 +51,7 @@
 #include "httpp/server.hpp"
 #include "httpp/progress.hpp"
 #include "httpp/download.hpp"
+#include "httpp/curl.hpp"
+#include "httpp/curl_compat.h"
 
 #endif /* HTTPP_H */

{httpp-0.1.0 → httpp-0.4.0}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "scikit_build_core.build"
 
 [project]
 name = "httpp"
-version = "0.1.0"
+dynamic = ["version"]
 description = "A Cython project with scikit-build"
 authors = [
     {name = "Mohammad Raziei", email = "mohammadraziei1375@gmail.com"},
@@ -59,6 +59,16 @@ sdist.include = [
     "src/third_party/liburlparser/**/*",
 ]
 
+[tool.scikit-build.metadata.version]
+provider = "scikit_build_core.metadata.regex"
+input = "include/httpp.h"
+regex = '''(?sx)
+\#define \s+ HTTPP_VERSION_MAJOR \s+ (?P<major>\d+) .*?
+\#define \s+ HTTPP_VERSION_MINOR \s+ (?P<minor>\d+) .*?
+\#define \s+ HTTPP_VERSION_PATCH \s+ (?P<patch>\d+) .*?
+'''
+result = "{major}.{minor}.{patch}"
+
 
 [tool.cibuildwheel]
 skip = "*i686*"
@@ -85,4 +95,4 @@ target-version = ['py311']
 
 [tool.isort]
 profile = "black"
-multi_line_output = 3
+multi_line_output = 3

{httpp-0.1.0 → httpp-0.4.0}/src/bindings/python/httpp/__init__.py

@@ -17,7 +17,7 @@ if _sys.platform == "win32" and hasattr(_os, "add_dll_directory"):
     _os.add_dll_directory(_lib_dir)
 
 # Import the compiled Cython module
-from .httpp_cy import Client, Server, download, DownloadFile, DownloadResult
+from .httpp_cy import Client, Server, download, DownloadFile, DownloadResult, CurlRequest
 
 
 def get_include_dir():
@@ -38,6 +38,6 @@ def get_cmake_dir():
 
 
 __all__ = [
-    "Client", "Server", "download", "DownloadFile", "DownloadResult",
+    "Client", "Server", "download", "DownloadFile", "DownloadResult", "CurlRequest",
     "get_include_dir", "get_lib_dir", "get_cmake_dir",
 ]

{httpp-0.1.0 → httpp-0.4.0}/src/bindings/python/httpp/__main__.py

@@ -98,6 +98,33 @@ def _cmd_uninstall(args):
     return 0
 
 
+def _cmd_curl(args):
+    from httpp import CurlRequest
+
+    req = CurlRequest(args.url)
+    if args.request:
+        req.method(args.request)
+    for h in args.header or []:
+        if ":" not in h:
+            print(f"error: malformed header (expected 'Name: value'): {h!r}", file=sys.stderr)
+            return 1
+        name, value = h.split(":", 1)
+        req.header(name.strip(), value.strip())
+    if args.data is not None:
+        req.data(args.data)
+
+    res = req.run()
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as f:
+            f.write(res.body)
+    else:
+        print(res.body)
+    if not res.ok:
+        print(f"error: request failed with status {res.status}", file=sys.stderr)
+        return 1
+    return 0
+
+
 def build_parser():
     parser = argparse.ArgumentParser(
         prog="httpp", description="httpp: a lightweight HTTP client + server toolkit."
@@ -116,6 +143,14 @@ def build_parser():
     p_download.add_argument("-q", "--quiet", action="store_true", help="With -o, suppress the progress bar.")
     p_download.set_defaults(func=_cmd_download)
 
+    p_curl = sub.add_parser("curl", help="Make a request (limited curl-like subset: -X/-H/-d).")
+    p_curl.add_argument("url")
+    p_curl.add_argument("-X", "--request", default=None, help="HTTP method (default: GET, or POST if -d is given).")
+    p_curl.add_argument("-H", "--header", action="append", default=None, help="Extra header 'Name: value' (repeatable).")
+    p_curl.add_argument("-d", "--data", default=None, help="Request body.")
+    p_curl.add_argument("-o", "--output", default=None, help="Write the response body to this file instead of stdout.")
+    p_curl.set_defaults(func=_cmd_curl)
+
     sdk_parent = argparse.ArgumentParser(add_help=False)
     sdk_parent.add_argument("--prefix", default=None, help="Install location (parent of httpp/). Default: /usr/local.")
     sdk_parent.add_argument("--user", action="store_true", help="Use ~/.local instead of /usr/local.")

{httpp-0.1.0 → httpp-0.4.0}/src/bindings/python/httpp_cy.pyx

@@ -50,6 +50,16 @@ cdef extern from "httpp/download.hpp" namespace "httpp":
         download_result run() except + nogil
 
 
+cdef extern from "httpp/curl.hpp" namespace "httpp::curl":
+    cdef cppclass cpp_curl_request "httpp::curl::request":
+        cpp_curl_request(string url) except +
+        cpp_curl_request& method(string m) except +
+        cpp_curl_request& header(string name, string value) except +
+        cpp_curl_request& data(string body) except +
+        cpp_curl_request& content_type(string type) except +
+        response run() except + nogil
+
+
 cdef class Response:
     """A response to an HTTP request made via Client.get()."""
     cdef int _status
@@ -191,3 +201,41 @@ def download(str url, str dest_path, cbool show_progress=True):
     bar unless show_progress=False. Shorthand for
     DownloadFile(url).output(dest_path).run()."""
     return DownloadFile(url).output(dest_path).enable_progress(show_progress).run()
+
+cdef class CurlRequest:
+    """A small, curl-flavored fluent request builder — the common cases
+    only (-X method, -H headers, -d data). NOT a libcurl-compatible shim;
+    see Client for the plain request API this is built on.
+
+        CurlRequest(url).method("PUT").header("X-Token", "abc").data("body").run()
+    """
+    cdef cpp_curl_request* _req
+
+    def __init__(self, str url):
+        self._req = new cpp_curl_request(url.encode("utf-8"))
+
+    def __dealloc__(self):
+        if self._req is not NULL:
+            del self._req
+
+    def method(self, str m):
+        self._req.method(m.encode("utf-8"))
+        return self
+
+    def header(self, str name, str value):
+        self._req.header(name.encode("utf-8"), value.encode("utf-8"))
+        return self
+
+    def data(self, str body):
+        self._req.data(body.encode("utf-8"))
+        return self
+
+    def content_type(self, str type_):
+        self._req.content_type(type_.encode("utf-8"))
+        return self
+
+    def run(self):
+        cdef response res
+        with nogil:
+            res = self._req.run()
+        return Response(res.status, res.body)