Upload pycurl/PYCURL_USER_GUIDE.txt with huggingface_hub

pycurl/PYCURL_USER_GUIDE.txt

@@ -0,0 +1,320 @@
+================================================================================
+  PYCURL - USER GUIDE (Android Python STB) - Generated by RIMI
+================================================================================
+  Covers: what pycurl is, install/verify, Curl object, HTTP GET/POST,
+          SSL, timeouts, write callbacks, and libcurl-impersonate features.
+
+  Written for: Python 3.12 (RIMI build) on Android
+  Version:     pycurl 7.45.6 (libcurl-impersonate)
+  Installed:   /data/user/0/com.pythonstb.rimi/files/python/lib/python3.12/site-packages/
+================================================================================
+
+
+--------------------------------------------------------------------------------
+1) WHAT IS PYCURL?
+--------------------------------------------------------------------------------
+
+pycurl is a Python interface to libcurl, the multiprotocol file transfer library.
+This build uses libcurl-impersonate (a patched libcurl that mimics real browsers).
+
+Features:
+  - HTTP, HTTPS, FTP, SFTP, SCP, and many other protocols
+  - SSL/TLS with BoringSSL backend (via libcurl-impersonate)
+  - Compression: zstd, brotli, gzip
+  - HTTP/2 via nghttp2
+  - Browser impersonation (Chrome, Firefox, Safari headers)
+
+    import pycurl
+    print(pycurl.version)
+    # libcurl/7.88.1 OpenSSL/3.1.4 ... brotli/1.0.9 ...
+
+
+--------------------------------------------------------------------------------
+2) INSTALL / VERIFY
+--------------------------------------------------------------------------------
+
+Install (already done, but if you ever reinstall):
+    pip install pycurl
+
+Quick smoke test:
+    import pycurl
+    c = pycurl.Curl()
+    c.setopt(c.URL, "http://httpbin.org/get")
+    buf = []
+    c.setopt(c.WRITEFUNCTION, buf.append)
+    c.perform()
+    print(c.getinfo(c.RESPONSE_CODE))   # 200
+    c.close()
+
+Expected output: 200
+
+
+--------------------------------------------------------------------------------
+3) CURL OBJECT
+--------------------------------------------------------------------------------
+
+    import pycurl
+
+    # Create a Curl handle (reusable for multiple requests)
+    c = pycurl.Curl()
+
+    # Set options
+    c.setopt(pycurl.URL, "http://httpbin.org/get")
+    c.setopt(pycurl.CONNECTTIMEOUT, 5)
+    c.setopt(pycurl.TIMEOUT, 10)
+
+    # Perform the request
+    buf = []
+    c.setopt(pycurl.WRITEFUNCTION, buf.append)
+    c.perform()
+
+    # Get info
+    print("status:", c.getinfo(pycurl.RESPONSE_CODE))
+    print("time:", c.getinfo(pycurl.TOTAL_TIME))
+    print("size:", c.getinfo(pycurl.SIZE_DOWNLOAD))
+
+    # Close when done
+    c.close()
+
+Note: Curl handles can be reused. Create once, setopt different URLs, perform.
+
+
+--------------------------------------------------------------------------------
+4) HTTP GET
+--------------------------------------------------------------------------------
+
+    import pycurl
+    from io import BytesIO
+
+    c = pycurl.Curl()
+    c.setopt(c.URL, "http://httpbin.org/get")
+    c.setopt(c.CONNECTTIMEOUT, 5)
+    c.setopt(c.TIMEOUT, 10)
+
+    buf = BytesIO()
+    c.setopt(c.WRITEDATA, buf)
+    c.perform()
+    print(buf.getvalue())     # response body
+    print(c.getinfo(c.RESPONSE_CODE))  # 200
+    c.close()
+
+
+--------------------------------------------------------------------------------
+5) HTTP POST
+--------------------------------------------------------------------------------
+
+    import pycurl
+
+    c = pycurl.Curl()
+    c.setopt(c.URL, "http://httpbin.org/post")
+    c.setopt(c.CONNECTTIMEOUT, 5)
+    c.setopt(c.TIMEOUT, 10)
+
+    # POST with form data
+    c.setopt(c.POSTFIELDS, "name=Alice&age=30")
+    c.setopt(c.HTTPHEADER, ["Content-Type: application/x-www-form-urlencoded"])
+
+    buf = []
+    c.setopt(c.WRITEFUNCTION, buf.append)
+    c.perform()
+    print("status:", c.getinfo(c.RESPONSE_CODE))
+    print("body:", "".join(buf)[:200])
+    c.close()
+
+    # POST JSON
+    import json
+    data = json.dumps({"name": "Alice", "age": 30})
+    c2 = pycurl.Curl()
+    c2.setopt(c2.URL, "http://httpbin.org/post")
+    c2.setopt(c2.CONNECTTIMEOUT, 5)
+    c2.setopt(c2.TIMEOUT, 10)
+    c2.setopt(c2.POST, True)
+    c2.setopt(c2.POSTFIELDS, data)
+    c2.setopt(c2.HTTPHEADER, ["Content-Type: application/json"])
+    buf2 = []
+    c2.setopt(c2.WRITEFUNCTION, buf2.append)
+    c2.perform()
+    print("status:", c2.getinfo(c2.RESPONSE_CODE))
+    c2.close()
+
+
+--------------------------------------------------------------------------------
+6) HEADERS
+--------------------------------------------------------------------------------
+
+    import pycurl
+
+    c = pycurl.Curl()
+    c.setopt(c.URL, "http://httpbin.org/get")
+    c.setopt(c.CONNECTTIMEOUT, 5)
+    c.setopt(c.TIMEOUT, 10)
+
+    # Custom headers
+    c.setopt(c.HTTPHEADER, [
+        "User-Agent: MyApp/1.0",
+        "Accept: application/json",
+        "X-Custom: test"
+    ])
+
+    # Capture response headers
+    resp_headers = []
+    c.setopt(c.HEADERFUNCTION, lambda h: resp_headers.append(h.strip()))
+    buf = []
+    c.setopt(c.WRITEFUNCTION, buf.append)
+    c.perform()
+    print("headers:", resp_headers[:5])
+    c.close()
+
+
+--------------------------------------------------------------------------------
+7) SSL / HTTPS
+--------------------------------------------------------------------------------
+
+    import pycurl
+
+    c = pycurl.Curl()
+    c.setopt(c.URL, "https://httpbin.org/get")
+    c.setopt(c.CONNECTTIMEOUT, 5)
+    c.setopt(c.TIMEOUT, 10)
+
+    # SSL verification (enabled by default)
+    c.setopt(c.SSL_VERIFYPEER, 1)
+    c.setopt(c.SSL_VERIFYHOST, 2)
+
+    buf = []
+    c.setopt(c.WRITEFUNCTION, buf.append)
+    c.perform()
+    print("status:", c.getinfo(c.RESPONSE_CODE))
+    ssl_verify = c.getinfo(c.SSL_VERIFYRESULT)
+    print("SSL verify:", ssl_verify)
+    c.close()
+
+    # Disable verification (NOT recommended for production)
+    c2 = pycurl.Curl()
+    c2.setopt(c2.URL, "https://httpbin.org/get")
+    c2.setopt(c2.SSL_VERIFYPEER, 0)
+    c2.setopt(c2.SSL_VERIFYHOST, 0)
+
+
+--------------------------------------------------------------------------------
+8) TIMEOUTS
+--------------------------------------------------------------------------------
+
+    import pycurl
+
+    c = pycurl.Curl()
+
+    # Connection timeout (DNS + TCP connect)
+    c.setopt(c.CONNECTTIMEOUT, 5)     # 5 seconds
+
+    # Total request timeout
+    c.setopt(c.TIMEOUT, 30)           # 30 seconds
+
+    # DNS cache timeout
+    c.setopt(c.DNS_CACHE_TIMEOUT, 300)  # 5 minutes
+
+    # Low speed limit (abort if speed < 1 byte/sec for 10 seconds)
+    c.setopt(c.LOW_SPEED_LIMIT, 1)
+    c.setopt(c.LOW_SPEED_TIME, 10)
+
+
+--------------------------------------------------------------------------------
+9) WRITE CALLBACKS
+--------------------------------------------------------------------------------
+
+    import pycurl
+    from io import BytesIO
+
+    # Method 1: WRITEFUNCTION callback
+    def on_data(data):
+        print("got %d bytes" % len(data))
+
+    c = pycurl.Curl()
+    c.setopt(c.URL, "http://httpbin.org/get")
+    c.setopt(c.WRITEFUNCTION, on_data)
+    c.perform()
+    c.close()
+
+    # Method 2: WRITEDATA file-like object
+    buf = BytesIO()
+    c = pycurl.Curl()
+    c.setopt(c.URL, "http://httpbin.org/get")
+    c.setopt(c.WRITEDATA, buf)
+    c.perform()
+    print(buf.getvalue()[:100])
+    c.close()
+
+
+--------------------------------------------------------------------------------
+10) LIBCURL-IMPERSONATE FEATURES
+--------------------------------------------------------------------------------
+
+This build uses libcurl-impersonate which supports browser impersonation:
+
+    import pycurl
+
+    c = pycurl.Curl()
+    c.setopt(c.URL, "https://example.com")
+
+    # Impersonate Chrome 99
+    c.setopt(c.HTTPHEADER, [
+        "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+                    "AppleWebKit/537.36 (KHTML, like Gecko) "
+                    "Chrome/99.0.4844.51 Safari/537.36"
+    ])
+
+    # The underlying libcurl-impersonate can also set TLS fingerprints
+    # to match Chrome/Firefox/Safari behavior.
+
+Available impersonation targets (depends on libcurl-impersonate version):
+  - Chrome 99, 100, 101, 104, 107, 110, 116, 119, 120
+  - Firefox 99, 102, 104, 113, 117, 118, 120
+  - Safari 15.3, 15.5, 15.6, 16.0
+
+
+--------------------------------------------------------------------------------
+11) ERROR HANDLING
+--------------------------------------------------------------------------------
+
+    import pycurl
+
+    # pycurl.error is raised on failures
+    try:
+        c = pycurl.Curl()
+        c.setopt(c.URL, "http://localhost:1")
+        c.setopt(c.CONNECTTIMEOUT, 2)
+        c.perform()
+    except pycurl.error as e:
+        code, message = e.args
+        print("error code:", code)       # e.g. CURLE_COULDNT_CONNECT (7)
+        print("message:", message)       # e.g. "Failed to connect..."
+    finally:
+        c.close()
+
+Common error codes:
+  CURLE_OK (0)            - Success
+  CURLE_COULDNT_RESOLVE (6) - DNS resolution failed
+  CURLE_COULDNT_CONNECT (7) - TCP connect failed
+  CURLE_OPERATION_TIMEDOUT (28) - Timeout
+  CURLE_SSL_CONNECT (35)   - SSL handshake failed
+
+
+--------------------------------------------------------------------------------
+12) PITFALLS & NOTES
+--------------------------------------------------------------------------------
+
+- Always close Curl handles when done: c.close()
+- Reuse Curl handles for multiple requests (avoids DNS re-resolution)
+- pycurl.Curl() is NOT thread-safe. Use one Curl per thread.
+- WRITEFUNCTION receives bytes, not str
+- Response headers include the trailing \r\n
+- libcurl-impersonate uses BoringSSL, not OpenSSL
+- Built with static deps: BoringSSL, zstd, brotli, nghttp2
+- Wheels are tagged cp312-cp312-android_24
+- Network tests are skippable (may fail on restricted networks)
+- HTTPS requests require valid CA certs in the system store
+- POSTFIELDS is a string or bytes; use POSTFIELDSIZE for binary data
+
+================================================================================
+  Generated by RIMI
+================================================================================