0x676e67 · 0x676e67 · Mar 27, 2026 · Mar 27, 2026 · Mar 27, 2026
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -8,7 +8,7 @@ version: 2
 build:
   os: ubuntu-24.04
   tools:
-    python: "3.13"
+    python: "3.11"
     rust: "latest"
   apt_packages:
     - build-essential
@@ -23,10 +23,17 @@ build:
       - pip install maturin
       - maturin build --out dist
       - pip install --find-links=dist wreq
-
-# Build documentation with Mkdocs
-mkdocs:
-  configuration: docs/mkdocs.yml
+    # We recommend using a requirements file for reproducible builds.
+    # This is just a quick example to get started.
+    # https://docs.readthedocs.io/page/guides/reproducible-builds.html
+    install:
+      - pip install zensical
+    build:
+      html:
+        - zensical build -f docs/mkdocs.yml
+    post_build:
+      - mkdir -p $READTHEDOCS_OUTPUT/html/
+      - cp --recursive site/* $READTHEDOCS_OUTPUT/html/
 # Optionally, but recommended,
 # declare the Python requirements required to build your documentation
 # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html

diff --git a/Cargo.toml b/Cargo.toml
@@ -1,7 +1,7 @@
 [package]
 name = "wreq-python"
 version = "0.10.0"
-description = "An ergonomic Python HTTP client with TLS fingerprint"
+description = "An ergonomic Python HTTP Client with TLS fingerprint"
 license = "Apache-2.0"
 readme = "README.md"
 repository = "https://github.com/0x676e67/wreq-python"

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -1,4 +1,4 @@
-site_name: wreq
+site_name: wreq-python
 site_description: Ergonomic Python HTTP Client with TLS Fingerprint
 site_author: "0x676e67"
 site_url: https://0x676e67.github.io/wreq-python
@@ -14,6 +14,8 @@ extra:
 
 theme:
   name: material
+  font:
+    code: Roboto Mono
   palette:
     - media: "(prefers-color-scheme)"
       toggle:
@@ -34,16 +36,21 @@ theme:
         icon: material/toggle-switch-off
         name: Switch to system preference
   features:
+    - search.highlight
+    - search.share
+    - content.code.copy
+    - content.code.annotate
+    - header.autohide
+    - toc.follow
+    - toc.integrate
+    - navigation.path
     - navigation.tabs
     - navigation.sections
     - navigation.top
     - navigation.tracking
     - navigation.indexes
-    - toc.integrate
-    - search.highlight
-    - search.share
-    - content.code.copy
-    - content.code.annotate
+    - navigation.instant
+    - navigation.instant.progress
 
 plugins:
   - search
@@ -52,7 +59,10 @@ plugins:
         python:
           paths: [../python]
           options:
-            docstring_style: google
+            extensions:
+              - unpack_typeddict
+              - dataclasses
+            docstring_style: auto
             show_source: true
             show_root_heading: true
             show_symbol_type_heading: true
@@ -76,15 +86,29 @@ markdown_extensions:
   - pymdownx.details
   - attr_list
   - md_in_html
+  - pymdownx.emoji
+  - pymdownx.tasklist
+  - pymdownx.caret
+  - pymdownx.mark
+  - pymdownx.tilde
 
 nav:
-  - Home: index.md
   - Getting Started:
+      - Introduction: getting-started/introduction.md
       - Installation: getting-started/installation.md
       - Quick Start: getting-started/quickstart.md
+  - Guides:
+      - Basic Usage: guide/basic.md
+      - Emulation: guide/emulation.md
+      - Authentication: guide/auth.md
+      - WebSocket: guide/websocket.md
+      - Proxy: guide/proxy.md
+      - Redirect & Errors: guide/redirect-errors.md
+      - Advanced Features: guide/advanced.md
+      - Blocking/Sync API: guide/blocking.md
   - API Reference:
-      - Core Module: api/core.md
       - Modules:
+          - wreq: api/wreq.md
           - wreq.blocking: api/blocking.md
           - wreq.header: api/header.md
           - wreq.cookie: api/cookie.md
@@ -96,13 +120,4 @@ nav:
           - wreq.dns: api/dns.md
           - wreq.proxy: api/proxy.md
           - wreq.redirect: api/redirect.md
-  - Examples:
-      - Basic Usage: examples/basic.md
-      - Browser Emulation: examples/emulation.md
-      - Authentication: examples/auth.md
-      - WebSocket: examples/websocket.md
-      - Proxy: examples/proxy.md
-      - Redirect & Errors: examples/redirect-errors.md
-      - Advanced Features: examples/advanced.md
-      - Blocking/Sync API: examples/blocking.md
   - Sponsors: sponsors.md
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,4 +1,4 @@
-mkdocs>=1.5.0
+zensical
 mkdocs-material>=9.5.0
-mkdocstrings[python]>=0.24.0
+mkdocstrings[python]>=1.0.3
 mike>=2.0.0
diff --git a/docs/source/api/core.md → docs/source/api/wreq.md b/docs/source/api/core.md → docs/source/api/wreq.md
@@ -1,9 +1,7 @@
-# wreq (Main Module)
+# wreq
 
 The main `wreq` module contains core classes and types used throughout the library.
 
-## Core Classes
-
 ::: wreq.Client
     options:
       show_root_heading: true

diff --git a/docs/source/getting-started/installation.md b/docs/source/getting-started/installation.md
@@ -1,43 +1,57 @@
-# Installation
+# :package: Installation
 
-## Requirements
+!!! info "Supported Platforms"
+	- **Python 3.11+ is required**
+	- Linux (glibc/musl): `x86_64`, `aarch64`, `armv7`, `i686`
+	- macOS: `x86_64`, `aarch64`
+	- Windows: `x86_64`, `i686`, `aarch64`
+	- Android: `aarch64`, `x86_64`
 
-- Python 3.11 or higher
-- pip or uv package manager
+---
 
 ## Install from PyPI
 
-The simplest way to install wreq is from PyPI:
+The easiest way to install wreq is via PyPI:
 
 ```bash
 pip install wreq
 ```
 
-Or using uv:
+Or with [uv](https://github.com/astral-sh/uv):
 
 ```bash
 uv pip install wreq
 ```
 
-## Install from Source
+---
 
-To install the latest development version:
+## Build from Source
+
+To build from source, first set up the BoringSSL build environment. See the [boringssl build guide](https://github.com/google/boringssl/blob/main/BUILDING.md) for details.
+
+Example (Ubuntu/Debian):
 
 ```bash
-git clone https://github.com/0x676e67/wreq.git
-cd wreq
-pip install -e .
-```
+sudo apt install -y build-essential cmake perl pkg-config libclang-dev musl-tools git
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+pip install uv maturin
 
-## Verify Installation
+uv venv
+source .venv/bin/activate
 
-Verify that wreq is installed correctly:
+# Development install
+maturin develop --uv
 
-```python
-import wreq
-print(wreq.__version__)
+# Build wheel
+maturin build --release
+
+# Install from local wheel
+pip install target/wheels/wreq-*.whl
 ```
 
+---
+
 ## Next Steps
 
-Continue to the [Quick Start](quickstart.md) guide to learn how to use wreq.
+- See the [Guides](../guide/basic.md) for usage examples
+- Browse the [API Reference](../api/wreq.md) for full documentation
diff --git a/docs/source/getting-started/introduction.md b/docs/source/getting-started/introduction.md
@@ -0,0 +1,103 @@
+# Introduction
+
+[![CI](https://github.com/0x676e67/wreq-python/actions/workflows/ci.yml/badge.svg)](https://github.com/0x676e67/wreq-python/actions/workflows/ci.yml)
+![GitHub License](https://img.shields.io/github/license/0x676e67/wreq-python?color=blue)
+![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2F0x676e67%2Fwreq-python%2Fmain%2Fpyproject.toml&logo=python)
+[![PyPI](https://img.shields.io/pypi/v/wreq?logo=python)](https://pypi.org/project/wreq/)
+[![Discord chat][discord-badge]][discord-url]
+
+[discord-badge]: https://img.shields.io/discord/1486741856397164788.svg?logo=discord
+[discord-url]: https://discord.gg/rfbvyFkgq3
+
+> 🚀 Help me work seamlessly with open source sharing by [sponsoring me on GitHub](https://github.com/0x676e67/0x676e67/blob/main/SPONSOR.md)
+
+
+An ergonomic and modular **Python** HTTP Client for advanced and low-level emulation, featuring customizable **TLS**, **JA3/JA4**, and **HTTP/2** fingerprinting capabilities, powered by [wreq].
+
+## Features
+
+- Async and Blocking `Client`s
+- Plain bodies, JSON, urlencoded, multipart
+- HTTP Trailer
+- Cookie Store
+- Redirect Policy
+- Original Header
+- Rotating Proxies
+- Connection Pooling
+- Streaming Transfers
+- Zero-Copy Transfers
+- WebSocket Upgrade
+- HTTPS via BoringSSL
+- Free-Threaded Safety
+- Automatic Decompression
+- Certificate Store (CAs & mTLS)
+
+
+## Why wreq?
+
+
+1. When your **HTTP** requests succeed in a browser but get blocked in Python due to network fingerprint issues, this tool bridges the gap. [wreq-python] allows you to customize your **TLS**, **JA3/JA4**, and **HTTP/2** fingerprints to mimic real browsers, making it ideal for web scraping, penetration testing, and security research.
+
+2. The standard **HTTP Client**, such as [requests] and [httpx], have different network fingerprints from browsers. The main differences lie in **TLS handshake**, **HTTP/2 frame characteristics**, and **JA3/JA4** fingerprints. Browsers use specific encryption suites and extensions in the TLS handshake, while standard HTTP clients may use different default settings, causing servers to recognize and block these requests.
+
+3. [wreq-python] uses the **BoringSSL** library, which is fully sufficient to set TLS fingerprints that match mainstream browsers while maintaining native performance.
+
+4. In addition, the basic functions of [wreq-python] are similar to those of the standard **HTTP Client**, offering a wide range of features such as connection pooling, redirection policies, Cookie storage, and streaming transmission, which can meet various complex HTTP request requirements.
+
+
+## Behavior
+
+1. **HTTP/2 over TLS**
+
+Due to the complexity of **TLS** encryption and the widespread adoption of **HTTP/2**, browser fingerprints such as **JA3**, **JA4**, and **Akamai** cannot be reliably emulated using simple fingerprint strings. Instead of parsing and emulating these string-based fingerprints, [wreq-python] provides fine-grained control over **TLS** and **HTTP/2** extensions and settings for precise browser behavior emulation.
+
+2. **Device Emulation**
+
+**TLS** and **HTTP/2** fingerprints are often identical across various browser models because these underlying protocols evolve slower than browser release cycles. **100+ browser device emulation profiles** are maintained in **[wreq-python]**.
+
+??? note "Available OS emulations"
+
+    | **OS**      | **Description**                |
+    | ----------- | ------------------------------ |
+    | **Windows** | Windows (any version)          |
+    | **MacOS**   | macOS (any version)            |
+    | **Linux**   | Linux (any distribution)       |
+    | **Android** | Android (mobile)               |
+    | **iOS**     | iOS (iPhone/iPad)              |
+
+??? note "Available browser emulations"
+
+    | **Browser** | **Versions**                                                                                                                                                                                                                                                                                                                                                                            |
+    | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+    | **Chrome**  | `Chrome100`, `Chrome101`, `Chrome104`, `Chrome105`, `Chrome106`, `Chrome107`, `Chrome108`, `Chrome109`, `Chrome110`, `Chrome114`, `Chrome116`, `Chrome117`, `Chrome118`, `Chrome119`, `Chrome120`, `Chrome123`, `Chrome124`, `Chrome126`, `Chrome127`, `Chrome128`, `Chrome129`, `Chrome130`, `Chrome131`, `Chrome132`, `Chrome133`, `Chrome134`, `Chrome135`, `Chrome136`, `Chrome137`, `Chrome138`, `Chrome139`, `Chrome140`, `Chrome141`, `Chrome142`, `Chrome143`, `Chrome144`, `Chrome145` |
+    | **Safari**  | `SafariIos17_2`, `SafariIos17_4_1`, `SafariIos16_5`, `Safari15_3`, `Safari15_5`, `Safari15_6_1`, `Safari16`, `Safari16_5`, `Safari17_0`, `Safari17_2_1`, `Safari17_4_1`, `Safari17_5`, `Safari18`, `SafariIPad18`, `Safari18_2`, `SafariIos18_1_1`, `Safari18_3`, `Safari18_3_1`, `Safari18_5`,  `Safari26`, `Safari26_1`, `Safari26_2`, `SafariIos26`, `SafariIos26_2`, `SafariIPad26`, `SafariIPad26_2`  |
+    | **Firefox** | `Firefox109`, `Firefox117`, `Firefox128`, `Firefox133`, `Firefox135`, `FirefoxPrivate135`, `FirefoxAndroid135`, `Firefox136`, `FirefoxPrivate136`, `Firefox139`, `Firefox142`, `Firefox143`, `Firefox144`, `Firefox145`, `Firefox146`, `Firefox147` |
+    | **OkHttp**  | `OkHttp3_9`, `OkHttp3_11`, `OkHttp3_13`, `OkHttp3_14`, `OkHttp4_9`, `OkHttp4_10`, `OkHttp4_12`, `OkHttp5`                                                                                                                                                                                                                                                                               |
+    | **Edge**    | `Edge101`, `Edge122`, `Edge127`, `Edge131`, `Edge134`, `Edge135`, `Edge136`, `Edge137`, `Edge138`, `Edge139`, `Edge140`, `Edge141`, `Edge142`, `Edge143`, `Edge144`, `Edge145` |
+    | **Opera**   | `Opera116`, `Opera117`, `Opera118`, `Opera119`    
+
+
+## Performance
+
+1. [wreq-python] This is designed to achieve high performance, leveraging the efficiency of the **BoringSSL** library in **TLS** operations and optimized **HTTP/2** processing. Although its running speed may not be comparable to that of low-level languages like **Rust** or **C++**, it offers significant performance improvements compared to traditional Python **HTTP** clients. 
+
+2. In terms of API module design, [wreq-python] adopts dual support for both asynchronous and blocking clients, allowing developers to choose the appropriate programming model according to their needs.
+
+3. API calls have made every effort to release the [GIL], which means that performance can be maximally exploited. In terms of data transmission, [wreq-python] implements Python's [Buffer] Protocol, supporting zero-copy transmission, further enhancing performance.
+
+
+## License
+
+Licensed under either of Apache License, Version 2.0 ([LICENSE](./LICENSE) or http://www.apache.org/licenses/LICENSE-2.0).
+
+## Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the [Apache-2.0](./LICENSE) license, shall be licensed as above, without any additional terms or conditions.
+
+
+[wreq]: https://github.com/0x676e67/wreq
+[wreq-python]: https://github.com/0x676e67/wreq-python
+[requests]: https://github.com/psf/requests
+[httpx]: https://github.com/encode/httpx
+[Buffer]: https://docs.python.org/3/c-api/buffer.html
+[GIL]: https://docs.python.org/3/c-api/init.html#thread-and-gil-management