Upload curl-cffi/CURL_CFFI_USER_GUIDE.txt with huggingface_hub

curl-cffi/CURL_CFFI_USER_GUIDE.txt

@@ -0,0 +1,190 @@
+================================================================================
+  CURL_CFFI - USER GUIDE (Android Python STB) - Generated by RIMI
+================================================================================
+  Covers: what curl_cffi is, install/verify, sessions, impersonation, requests,
+          responses, SSL, proxies, HTTP/2, and comparison with requests.
+
+  Written for: Python 3.12.2 (RIMI build) on Android
+  Version:     curl_cffi 0.7.x (or latest)
+  Installed:   /data/user/0/com.pythonstb.rimi/files/python/lib/python3.12/site-packages/
+================================================================================
+
+
+--------------------------------------------------------------------------------
+1) WHAT IS CURL_CFFI?
+--------------------------------------------------------------------------------
+
+curl_cffi is a Python binding for curl-impersonate, allowing you to make HTTP
+requests that impersonate real browsers (Chrome, Safari, Firefox, Edge, etc.).
+
+Key advantages over requests/httpx:
+  - Browser impersonation (TLS fingerprint matches real browsers)
+  - HTTP/2 support
+  - Built on libcurl (battle-tested C library)
+  - BoringSSL for TLS (not OpenSSL)
+  - Handles JavaScript-heavy sites that block automated requests
+
+Dependencies: curl-impersonate (static), BoringSSL (built into .so).
+
+    import curl_cffi
+    print(curl_cffi.__version__)          # 0.7.x
+
+
+--------------------------------------------------------------------------------
+2) INSTALL / VERIFY
+--------------------------------------------------------------------------------
+
+Install (already done, but if you ever reinstall):
+    pip install curl_cffi
+
+Quick smoke test:
+    from curl_cffi.requests import Session
+    with Session(impersonate="chrome") as s:
+        r = s.get("https://httpbin.org/get")
+        print("status:", r.status_code)
+
+
+--------------------------------------------------------------------------------
+3) BASIC USAGE
+--------------------------------------------------------------------------------
+
+    from curl_cffi.requests import Session
+
+    # simple GET
+    with Session(impersonate="chrome") as s:
+        r = s.get("https://example.com")
+        print(r.status_code)
+        print(r.text)
+
+    # POST with JSON
+    with Session(impersonate="chrome") as s:
+        r = s.post("https://httpbin.org/post", json={"key": "value"})
+        print(r.json())
+
+
+--------------------------------------------------------------------------------
+4) IMPERSONATION PROFILES
+--------------------------------------------------------------------------------
+
+    from curl_cffi.requests import Session
+
+    # Chrome
+    s = Session(impersonate="chrome")
+    s = Session(impersonate="chrome120")   # specific version
+
+    # Safari
+    s = Session(impersonate="safari")
+    s = Session(impersonate="safari15_5")
+
+    # Firefox
+    s = Session(impersonate="firefox")
+    s = Session(impersonate="firefox120")
+
+    # Edge
+    s = Session(impersonate="edge")
+    s = Session(impersonate="edge99")
+
+
+--------------------------------------------------------------------------------
+5) REQUEST OPTIONS
+--------------------------------------------------------------------------------
+
+    with Session(impersonate="chrome") as s:
+        # custom headers
+        r = s.get(url, headers={"X-Custom": "val"})
+
+        # query parameters
+        r = s.get(url, params={"q": "search"})
+
+        # timeout (seconds)
+        s = Session(impersonate="chrome", timeout=10)
+
+        # proxy
+        r = s.get(url, proxy="http://proxy:8080")
+
+        # disable SSL verification
+        r = s.get(url, verify=False)
+
+        # cookies
+        r = s.get(url, cookies={"session": "abc123"})
+
+
+--------------------------------------------------------------------------------
+6) RESPONSE
+--------------------------------------------------------------------------------
+
+    with Session(impersonate="chrome") as s:
+        r = s.get("https://httpbin.org/get")
+        r.status_code       # int: 200
+        r.text              # str: decoded body
+        r.content           # bytes: raw body
+        r.headers           # dict: response headers
+        r.url               # str: final URL (after redirects)
+        r.json()            # dict: parsed JSON
+        r.ok                # bool: status < 400
+
+
+--------------------------------------------------------------------------------
+7) HTTP/2
+--------------------------------------------------------------------------------
+
+    with Session(impersonate="chrome") as s:
+        # HTTP/2 is used automatically when the server supports it
+        r = s.get("https://httpbin.org/get")
+        # check the protocol version if needed
+
+
+--------------------------------------------------------------------------------
+8) COOKIES / SESSIONS
+--------------------------------------------------------------------------------
+
+    with Session(impersonate="chrome") as s:
+        # cookies persist across requests in the same session
+        s.get("https://httpbin.org/cookies/set?name=value")
+        r = s.get("https://httpbin.org/cookies")
+        print(r.json())
+
+
+--------------------------------------------------------------------------------
+9) ERROR HANDLING
+--------------------------------------------------------------------------------
+
+    from curl_cffi.requests import Session
+    from curl_cffi.requests.errors import CurlError
+
+    try:
+        with Session(impersonate="chrome") as s:
+            r = s.get("https://httpbin.org/get")
+    except CurlError as e:
+        print("curl error:", e)
+
+
+--------------------------------------------------------------------------------
+10) COMPARISON: CURL_CFFI VS REQUESTS
+--------------------------------------------------------------------------------
+
+Feature             curl_cffi          requests
+-----------------------------------------------
+Browser imperson    Yes                No
+HTTP/2              Yes (auto)         No (needs httpx)
+TLS fingerprint     Real browser      Default Python
+C++ backend         libcurl           urllib3
+Connection pool     Yes                Yes
+Streaming           Yes                Yes
+
+
+--------------------------------------------------------------------------------
+11) ANDROID NOTES
+--------------------------------------------------------------------------------
+
+- curl_cffi bundles curl-impersonate and BoringSSL as static .so files.
+- Network access requires INTERNET permission in AndroidManifest.xml.
+- HTTP/2 works automatically when the server supports it.
+- Impersonation helps bypass bot detection on restrictive sites.
+- For simple HTTP without impersonation, aiohttp or requests may be lighter.
+- SSL certificate verification may need adjustment on Android.
+
+
+================================================================================
+  Generated by RIMI
+================================================================================