release

Author: thewebscraping

.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI/CD
+
+on:
+  push:
+    branches: ['master', 'main', 'dev', 'develop']
+
+  pull_request:
+    branches: ['master', 'main', 'dev', 'develop']
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      max-parallel: 4
+      matrix:
+        python-version: ['3.9', '3.10', '3.11']
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install Dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements.txt
+
+    - name: Run pre-commit
+      uses: pre-commit/action@v3.0.0
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install -r requirements.txt
+      - run: mkdocs gh-deploy --force

.gitignore

@@ -159,4 +159,4 @@ cython_debug/
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
+.idea/

.pre-commit-config.yaml

@@ -0,0 +1,33 @@
+exclude: '^docs.sh/|scripts/'
+default_stages: [commit]
+
+default_language_version:
+  python: python3.10
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-json
+      - id: check-toml
+      - id: check-xml
+      - id: check-yaml
+      - id: debug-statements
+      - id: check-builtin-literals
+      - id: check-case-conflict
+      - id: check-docstring-first
+      - id: detect-private-key
+
+  # run the isort.
+  - repo: https://github.com/PyCQA/isort
+    rev: 5.13.2
+    hooks:
+      - id: isort
+
+  # run the flake8.
+  - repo: https://github.com/PyCQA/flake8
+    rev: 7.0.0
+    hooks:
+      - id: flake8

CHANGELOG.md

@@ -0,0 +1,6 @@
+Release History
+===============
+
+1.0.0 (2024-12-04)
+-------------------
+* First release

MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+recursive-include tls_requests docs Makefile *.md *.rst

Makefile

@@ -0,0 +1,20 @@
+.PHONY: docs
+init:
+	python -m pip install -r requirements.txt
+
+test-readme:
+	python setup.py check --restructuredtext --strict && ([ $$? -eq 0 ] && echo "README.rst and CHANGELOG.md ok") || echo "Invalid markup in README.md or CHANGELOG.md!"
+
+lint:
+	python -m black tls_requests
+	python -m isort tls_requests
+	python -m flake8 tls_requests
+
+publish-pypi:
+	python -m pip install 'twine>=6.0.1'
+	python setup.py sdist bdist_wheel
+	twine upload dist/*
+	rm -rf build dist .egg tls_requests.egg-info
+
+docs:
+	mkdocs serve

README.md

@@ -1 +1,109 @@
-# tls-requests
+# TLS REQUESTS
+**A powerful and lightweight Python library for making secure and reliable HTTP/TLS fingerprint requests.**
+
+* * *
+
+**Installation**
+----------------
+
+Install TLS Requests using pip:
+
+```shell
+pip install tls-requests
+```
+
+### Quick Start
+
+Start using TLS Requests with just a few lines of code:
+
+```pycon
+>>> import tls_requests
+>>> r = tls_requests.get("https://httpbin.org/get")
+>>> r
+<Response [200 OK]>
+>>> r.status_code
+200
+```
+
+* * *
+
+**Introduction**
+----------------
+
+**TLS Requests** is a cutting-edge HTTP client for Python, offering a feature-rich,
+highly configurable alternative to the popular [`requests`](https://github.com/psf/requests) library.
+
+It is built on top of [`tls-client`](https://github.com/bogdanfinn/tls-client),
+combining ease of use with advanced functionality for secure networking.
+
+**Acknowledgment**: A big thank you to all contributors for their support!
+
+### **Key Benefits**
+
+*   **Bypass TLS Fingerprinting:** Mimic browser-like behaviors to navigate sophisticated anti-bot systems.
+*   **Customizable TLS Clients:** Select specific TLS fingerprints to meet your needs.
+*   **Ideal for Developers:** Build scrapers, API clients, or other custom networking tools effortlessly.
+
+* * *
+
+**Why Use TLS Requests?**
+-------------------------
+
+Modern websites increasingly use **TLS Fingerprinting** and anti-bot tools like Cloudflare Bot Fight Mode to block web crawlers.
+
+**TLS Requests** bypasses these obstacles by mimicking browser-like TLS behaviors,
+making it easy to scrape data or interact with websites that use sophisticated anti-bot measures.
+
+### Cloudflare Bot Fight Mode
+![coingecko.png](https://raw.githubusercontent.com/thewebscraping/tls-requests/refs/heads/master/docs/static/coingecko.png)
+
+### Unlock Content Behind Cloudflare Bot Fight Mode
+
+**Example Code:**
+
+```pycon
+>>> import tls_requests
+>>> r = tls_requests.get('https://www.coingecko.com/')
+>>> r
+<Response [200]>
+```
+* * *
+
+**Key Features**
+----------------
+
+### **Enhanced Capabilities**
+
+*   **Browser-like TLS Fingerprinting**: Enables secure and reliable browser-mimicking connections.
+*   **High-Performance Backend**: Built on a Go-based HTTP backend for speed and efficiency.
+*   **Synchronous & Asynchronous Support**: Seamlessly switch between synchronous and [asynchronous requests](https://github.com/thewebscraping/tls-requests/blob/main/docs/advanced/async_client).
+*   **Protocol Support**: Fully compatible with HTTP/1.1 and HTTP/2.
+*   **Strict Timeouts**: Reliable timeout management for precise control over request durations.
+
+### **Additional Features**
+
+*   **Internationalized Domain & URL Support**: Handles non-ASCII URLs effortlessly.
+*   **Cookie Management**: Ensures session-based cookie persistence.
+*   **Authentication**: Native support for Basic and Function authentication.
+*   **Content Decoding**: Automatic handling of gzip and brotli-encoded responses.
+*   **Hooks**: Perfect for logging, monitoring, tracing, or pre/post-processing requests and responses.
+*   **Unicode Support**: Effortlessly process Unicode response bodies.
+*   **File Uploads**: Simplified multipart file upload support.
+*   **Proxy Configuration**: Supports Socks5, HTTP, and HTTPS proxies for enhanced privacy.
+
+* * *
+
+**Documentation**
+-----------------
+
+Explore the full capabilities of TLS Requests in the documentation:
+
+*   **[Quickstart Guide](https://github.com/thewebscraping/tls-requests/blob/main/docs/quickstart.md)**: A beginner-friendly guide.
+*   **Advanced Topics**: Learn to leverage specialized features.
+*   **[Async Support](https://github.com/thewebscraping/tls-requests/blob/main/docs/docs/advanced/async_client)**: Handle high-concurrency scenarios.
+*   **Custom TLS Configurations**:
+    *   **[Wrapper TLS Client](https://github.com/thewebscraping/tls-requests/blob/main/docs/docs/tls/index)**
+    *   **[TLS Client Profiles](https://github.com/thewebscraping/tls-requests/blob/main/docs/docs/tls/profiles)**
+    *   **[Custom TLS Configurations](https://github.com/thewebscraping/tls-requests/blob/main/docs/docs/tls/configuration)**
+
+* * *

docs/advanced/async_client.md

@@ -0,0 +1,97 @@
+Async Support in TLS Requests
+=============================
+
+TLS Requests provides support for asynchronous HTTP requests using the `AsyncClient`. This is especially useful when working in an asynchronous environment, such as with modern web frameworks, or when you need the performance benefits of asynchronous I/O.
+
+* * *
+
+Why Use Async?
+--------------
+
+*   **Improved Performance:** Async is more efficient than multi-threading for handling high concurrency workloads.
+*   **Long-lived Connections:** Useful for protocols like WebSockets or long polling.
+*   **Framework Compatibility:** Essential when integrating with async web frameworks (e.g., FastAPI, Starlette).
+
+Advanced usage with syntax similar to Client, refer to the [Client documentation](client).
+
+* * *
+
+Making Async Requests
+---------------------
+
+To send asynchronous HTTP requests, use the `AsyncClient`:
+
+```pycon
+>>> import asyncio
+>>> async def fetch(url):
+        async with tls_requests.AsyncClient() as client:
+            r = await client.get("https://www.example.com/")
+            return r
+
+>>> r = asyncio.run(fetch("https://httpbin.org/get"))
+>>> r
+<Response [200 OK]>
+```
+
+!!! tip
+    Use [IPython](https://ipython.readthedocs.io/en/stable/) or Python 3.8+ with `python -m asyncio` to try this code interactively, as they support executing `async`/`await` expressions in the console.
+
+* * *
+
+Key API Differences
+-------------------
+
+When using `AsyncClient`, the API methods are asynchronous and must be awaited.
+
+### Making Requests
+
+Use `await` for all request methods:
+
+*   `await client.get(url, ...)`
+*   `await client.post(url, ...)`
+*   `await client.put(url, ...)`
+*   `await client.patch(url, ...)`
+*   `await client.delete(url, ...)`
+*   `await client.options(url, ...)`
+*   `await client.head(url, ...)`
+*   `await client.request(method, url, ...)`
+*   `await client.send(request, ...)`
+
+* * *
+
+### Managing Client Lifecycle
+
+#### Context Manager
+
+For proper resource cleanup, use `async with`:
+
+```python
+import asyncio
+
+async def fetch(url):
+    async with tls_requests.AsyncClient() as client:
+        response = await client.get(url)
+        return response
+
+r = asyncio.run(fetch("https://httpbin.org/get"))
+print(r)  # <Response [200 OK]>
+```
+
+#### Manual Closing
+
+Alternatively, explicitly close the client:
+
+```python
+import asyncio
+
+async def fetch(url):
+    client = tls_requests.AsyncClient()
+    try:
+        response = await client.get("https://www.example.com/")
+    finally:
+        await client.aclose()
+```
+
+* * *
+
+By using `AsyncClient`, you can unlock the full potential of asynchronous programming in Python while enjoying the simplicity and power of TLS Requests.