uaforger 0.1.0__tar.gz

uaforger-0.1.0/MANIFEST.in

@@ -0,0 +1,13 @@
+include README.md
+include LICENSE
+
+recursive-include uaforge/data *.json *.txt
+
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude *.so
+global-exclude .DS_Store
+
+prune scripts
+prune bench
+prune tests

uaforger-0.1.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: uaforger
+Version: 0.1.0
+Summary: Statistically-weighted User-Agent + Sec-CH-UA Client-Hint generator backed by real-world market-share data.
+Author-email: Sarper AVCI <sarperavci20@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/sarperavci/UAForge
+Project-URL: Source, https://github.com/sarperavci/UAForge
+Project-URL: Issues, https://github.com/sarperavci/UAForge/issues
+Keywords: user-agent,client-hints,fingerprint,browser,scraping,automation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# UAForge
+
+**Enterprise-grade, deterministic User Agent & Client Hint generator based on real-world browser statistics**
+
+[![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Auto-Updated](https://img.shields.io/badge/data-auto--updated%20weekly-orange)](https://caniuse.com/usage-table)
+
+---
+
+Most "random user-agent" libraries are broken. They generate outdated browser strings, mix incompatible OS combinations, or lack the modern headers that fingerprinting systems now check.
+
+**UAForge takes a different approach.** Instead of picking random strings, it simulates real users based on **statistical probability**. If Chrome 143 on Android holds 40% global market share, UAForge generates that identity 40% of the time.
+
+It also generates matching **Client Hints (`Sec-CH-UA`)** headers automatically—allowing your automation to pass modern fingerprinting checks that go beyond the legacy User-Agent string.
+
+### Key Features
+
+*   **Statistically Accurate** — Weighted by real-world global usage data, updated weekly from caniuse.com
+*   **Smart Correlations** — Enforces valid browser↔OS mappings (no Safari on Windows)
+*    **Real Hardware** — Injects actual device models (Pixel 9, Galaxy S24, etc.) for mobile agents
+*   **Client Hints** — Generates Sec-CH-UA, Sec-CH-UA-Mobile, Sec-CH-UA-Platform, and GREASE tokens
+*    **Deterministic** — Seed support for consistent, reproducible identities across sessions
+
+
+## Installation
+
+```bash
+pip install git+https://github.com/sarperavci/uaforge.git
+```
+
+*Note:* The repo does not contain the market-share data files due to size constraints. They are automatically downloaded from the release assets while installing.
+
+
+## Quick Start
+
+The API is designed to be simple. You generate an "Identity" object, which contains everything you need for your requests.
+
+```python
+from uaforge.core.generator import UserAgentGenerator
+
+# 1. Initialize the generator
+agent = UserAgentGenerator()
+
+# 2. Generate an identity
+identity = agent.generate()
+
+# 3. Get the headers (includes User-Agent AND Client Hints)
+headers = identity.get_headers()
+full_client_hints = identity.get_all_client_hints()
+
+# Use with requests/httpx
+# response = requests.get("https://httpbin.org/headers", headers=headers)
+
+print(f"Browser: {identity.meta_browser.value}")
+print(f"OS:      {identity.meta_os.value}")
+print(headers)
+print(full_client_hints)
+```
+
+### Sample Output
+
+Default Headers:
+
+```json
+{
+"User-Agent": "Mozilla/5.0 (Linux; Android 13; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/144.0.0.0 Mobile Safari/537.36",
+"Sec-CH-UA": "\"Not A Brand\";v=\"99\", \"Chromium\";v=\"144\", \"Google Chrome\";v=\"144\"",
+"Sec-CH-UA-Mobile": "?1",
+"Sec-CH-UA-Platform": "\"Android\""
+}
+```
+
+Full Client Hints:
+
+```json
+{
+"Sec-CH-UA": "\"Not A Brand\";v=\"99\", \"Chromium\";v=\"144\", \"Google Chrome\";v=\"144\"",
+"Sec-CH-UA-Mobile": "?1",
+"Sec-CH-UA-Platform": "\"Android\"",
+"Sec-CH-UA-Full-Version-List": "\"Not A Brand\";v=\"99.0.0.0\", \"Chromium\";v=\"144.0.7559.59\", \"Google Chrome\";v=\"144.0.7559.59\"",
+"Sec-CH-UA-Platform-Version": "13.0.0",
+"Sec-CH-UA-Model": "\"Pixel 9\"",
+"Sec-CH-UA-Arch": "\"arm\"",
+"Sec-CH-UA-Bitness": "\"64\"",
+"Sec-CH-UA-Full-Version": "\"144.0.7559.59\"",
+"Sec-CH-UA-Form-Factors": "\"Mobile\"",
+"Sec-CH-UA-WoW64": "?0",
+"Sec-CH-Prefers-Color-Scheme": "dark"
+}
+```
+
+## Advanced Usage
+
+### Deterministic Generation (Sessions)
+If you are managing long-running sessions, you need the User Agent to stay consistent across restarts. Use a seed.
+
+```python
+# The identity generated here will ALWAYS be the same for seed 42
+user = UserAgentGenerator(seed=42).generate()
+
+print(user.user_agent) 
+# Useful for associating a UA with a specific database UserID
+```
+
+### Accessing Granular Data
+Sometimes you need just the OS version or just the device model for analytics.
+
+```python
+identity = agent.generate()
+
+if identity.meta_device == "mobile":
+    print(f"Device Model: {identity.ch_model}")  # e.g. "Pixel 8 Pro"
+    print(f"Architecture: {identity.ch_arch}")   # e.g. "arm"
+```
+
+## How it works
+
+### The Data Sources
+
+We don't guess. We utilize three distinct data layers:
+
+1.  **`market_share.json`**: Global browser usage stats (Chrome, Safari, Edge, Firefox).
+2.  **`os_distribution.json`**: The probability of an OS given a specific browser (e.g., Safari is 100% macOS/iOS, but Chrome is split between Windows, Mac, Linux, and Android).
+3.  **`device_models.json`**: A curated list of ~500 real-world mobile device fingerprints.
+
+## Maintenance & Updates
+
+The browser ecosystem moves fast. Market share data is **automatically updated weekly** via GitHub Actions by parsing the latest data from [caniuse.com](https://caniuse.com/usage-table).
+
+You can also trigger a manual update by running:
+```bash
+python scripts/parse_caniuse.py
+```
+
+## Current Market Share Distribution
+
+The table below shows the aggregated browser market share from the current dataset. Data is sourced from caniuse.com and updated automatically.
+
+| Browser | Market Share |
+|---------|-------------|
+| Chrome for Android | 57.48% |
+| Chrome (Desktop) | 17.61% |
+| iOS Safari | 12.43% |
+| Edge | 4.60% |
+| Safari (Desktop) | 2.20% |
+| Samsung Internet | 1.73% |
+| Firefox | 1.62% |
+| Opera Mobile | 0.80% |
+| UC Browser | 0.57% |
+| Opera | 0.39% |
+| Firefox for Android | 0.31% |
+| IE | 0.26% |
+
+*Last updated: 03-05-2026*
+
+## License
+
+MIT License. Feel free to use this in your commercial scrapers, bots or testing suites.

uaforger-0.1.0/README.md

@@ -0,0 +1,159 @@
+# UAForge
+
+**Enterprise-grade, deterministic User Agent & Client Hint generator based on real-world browser statistics**
+
+[![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Auto-Updated](https://img.shields.io/badge/data-auto--updated%20weekly-orange)](https://caniuse.com/usage-table)
+
+---
+
+Most "random user-agent" libraries are broken. They generate outdated browser strings, mix incompatible OS combinations, or lack the modern headers that fingerprinting systems now check.
+
+**UAForge takes a different approach.** Instead of picking random strings, it simulates real users based on **statistical probability**. If Chrome 143 on Android holds 40% global market share, UAForge generates that identity 40% of the time.
+
+It also generates matching **Client Hints (`Sec-CH-UA`)** headers automatically—allowing your automation to pass modern fingerprinting checks that go beyond the legacy User-Agent string.
+
+### Key Features
+
+*   **Statistically Accurate** — Weighted by real-world global usage data, updated weekly from caniuse.com
+*   **Smart Correlations** — Enforces valid browser↔OS mappings (no Safari on Windows)
+*    **Real Hardware** — Injects actual device models (Pixel 9, Galaxy S24, etc.) for mobile agents
+*   **Client Hints** — Generates Sec-CH-UA, Sec-CH-UA-Mobile, Sec-CH-UA-Platform, and GREASE tokens
+*    **Deterministic** — Seed support for consistent, reproducible identities across sessions
+
+
+## Installation
+
+```bash
+pip install git+https://github.com/sarperavci/uaforge.git
+```
+
+*Note:* The repo does not contain the market-share data files due to size constraints. They are automatically downloaded from the release assets while installing.
+
+
+## Quick Start
+
+The API is designed to be simple. You generate an "Identity" object, which contains everything you need for your requests.
+
+```python
+from uaforge.core.generator import UserAgentGenerator
+
+# 1. Initialize the generator
+agent = UserAgentGenerator()
+
+# 2. Generate an identity
+identity = agent.generate()
+
+# 3. Get the headers (includes User-Agent AND Client Hints)
+headers = identity.get_headers()
+full_client_hints = identity.get_all_client_hints()
+
+# Use with requests/httpx
+# response = requests.get("https://httpbin.org/headers", headers=headers)
+
+print(f"Browser: {identity.meta_browser.value}")
+print(f"OS:      {identity.meta_os.value}")
+print(headers)
+print(full_client_hints)
+```
+
+### Sample Output
+
+Default Headers:
+
+```json
+{
+"User-Agent": "Mozilla/5.0 (Linux; Android 13; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/144.0.0.0 Mobile Safari/537.36",
+"Sec-CH-UA": "\"Not A Brand\";v=\"99\", \"Chromium\";v=\"144\", \"Google Chrome\";v=\"144\"",
+"Sec-CH-UA-Mobile": "?1",
+"Sec-CH-UA-Platform": "\"Android\""
+}
+```
+
+Full Client Hints:
+
+```json
+{
+"Sec-CH-UA": "\"Not A Brand\";v=\"99\", \"Chromium\";v=\"144\", \"Google Chrome\";v=\"144\"",
+"Sec-CH-UA-Mobile": "?1",
+"Sec-CH-UA-Platform": "\"Android\"",
+"Sec-CH-UA-Full-Version-List": "\"Not A Brand\";v=\"99.0.0.0\", \"Chromium\";v=\"144.0.7559.59\", \"Google Chrome\";v=\"144.0.7559.59\"",
+"Sec-CH-UA-Platform-Version": "13.0.0",
+"Sec-CH-UA-Model": "\"Pixel 9\"",
+"Sec-CH-UA-Arch": "\"arm\"",
+"Sec-CH-UA-Bitness": "\"64\"",
+"Sec-CH-UA-Full-Version": "\"144.0.7559.59\"",
+"Sec-CH-UA-Form-Factors": "\"Mobile\"",
+"Sec-CH-UA-WoW64": "?0",
+"Sec-CH-Prefers-Color-Scheme": "dark"
+}
+```
+
+## Advanced Usage
+
+### Deterministic Generation (Sessions)
+If you are managing long-running sessions, you need the User Agent to stay consistent across restarts. Use a seed.
+
+```python
+# The identity generated here will ALWAYS be the same for seed 42
+user = UserAgentGenerator(seed=42).generate()
+
+print(user.user_agent) 
+# Useful for associating a UA with a specific database UserID
+```
+
+### Accessing Granular Data
+Sometimes you need just the OS version or just the device model for analytics.
+
+```python
+identity = agent.generate()
+
+if identity.meta_device == "mobile":
+    print(f"Device Model: {identity.ch_model}")  # e.g. "Pixel 8 Pro"
+    print(f"Architecture: {identity.ch_arch}")   # e.g. "arm"
+```
+
+## How it works
+
+### The Data Sources
+
+We don't guess. We utilize three distinct data layers:
+
+1.  **`market_share.json`**: Global browser usage stats (Chrome, Safari, Edge, Firefox).
+2.  **`os_distribution.json`**: The probability of an OS given a specific browser (e.g., Safari is 100% macOS/iOS, but Chrome is split between Windows, Mac, Linux, and Android).
+3.  **`device_models.json`**: A curated list of ~500 real-world mobile device fingerprints.
+
+## Maintenance & Updates
+
+The browser ecosystem moves fast. Market share data is **automatically updated weekly** via GitHub Actions by parsing the latest data from [caniuse.com](https://caniuse.com/usage-table).
+
+You can also trigger a manual update by running:
+```bash
+python scripts/parse_caniuse.py
+```
+
+## Current Market Share Distribution
+
+The table below shows the aggregated browser market share from the current dataset. Data is sourced from caniuse.com and updated automatically.
+
+| Browser | Market Share |
+|---------|-------------|
+| Chrome for Android | 57.48% |
+| Chrome (Desktop) | 17.61% |
+| iOS Safari | 12.43% |
+| Edge | 4.60% |
+| Safari (Desktop) | 2.20% |
+| Samsung Internet | 1.73% |
+| Firefox | 1.62% |
+| Opera Mobile | 0.80% |
+| UC Browser | 0.57% |
+| Opera | 0.39% |
+| Firefox for Android | 0.31% |
+| IE | 0.26% |
+
+*Last updated: 03-05-2026*
+
+## License
+
+MIT License. Feel free to use this in your commercial scrapers, bots or testing suites.

uaforger-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "uaforger"
+version = "0.1.0"
+description = "Statistically-weighted User-Agent + Sec-CH-UA Client-Hint generator backed by real-world market-share data."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{ name = "Sarper AVCI", email = "sarperavci20@gmail.com" }]
+license = { text = "MIT" }
+keywords = ["user-agent", "client-hints", "fingerprint", "browser", "scraping", "automation"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/sarperavci/UAForge"
+Source = "https://github.com/sarperavci/UAForge"
+Issues = "https://github.com/sarperavci/UAForge/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["uaforge*"]
+exclude = ["scripts*", "bench*", "tests*"]
+
+[tool.setuptools.package-data]
+"uaforge" = ["data/*.json", "data/*.txt"]

uaforger-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

uaforger-0.1.0/uaforge/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

uaforger-0.1.0/uaforge/core/alias_sampler.py

@@ -0,0 +1,97 @@
+import random
+from typing import List
+
+
+class AliasSampler:
+    """
+    O(1) weighted random sampler using Vose's Alias Method.
+    
+    Usage:
+        sampler = AliasSampler(weights, rng)
+        index = sampler.sample()  # O(1) per call
+    """
+    
+    def __init__(self, weights: List[float], rng=None):
+        """
+        Preprocess weights into alias table.
+        
+        Args:
+            weights: List of weights (need not sum to 1, will be normalized)
+            rng: Random instance to use (defaults to random module)
+        """
+        self.rng = rng if rng is not None else random
+        n = len(weights)
+        
+        if n == 0:
+            raise ValueError("Cannot create AliasSampler with empty weights")
+        
+        self.n = n
+        
+        # Normalize weights
+        total = sum(weights)
+        if total <= 0:
+            raise ValueError("Sum of weights must be positive")
+        
+        # probabilities normalized to sum to n (for the algorithm)
+        prob = [w * n / total for w in weights]
+        
+        # Alias tables
+        self.prob = [0.0] * n
+        self.alias = [0] * n
+        
+        # Partition into small and large
+        small = []
+        large = []
+        
+        for i, p in enumerate(prob):
+            if p < 1.0:
+                small.append(i)
+            else:
+                large.append(i)
+        
+        # Build alias table
+        while small and large:
+            l = small.pop()
+            g = large.pop()
+            
+            self.prob[l] = prob[l]
+            self.alias[l] = g
+            
+            prob[g] = prob[g] + prob[l] - 1.0
+            
+            if prob[g] < 1.0:
+                small.append(g)
+            else:
+                large.append(g)
+        
+        # Remaining items (due to floating point, both could have leftovers)
+        while large:
+            g = large.pop()
+            self.prob[g] = 1.0
+        
+        while small:
+            l = small.pop()
+            self.prob[l] = 1.0
+    
+    def sample(self, rand: random.Random = None) -> int:
+        """
+        Sample an index in O(1) time.
+
+        Args:
+            rand: Optional random instance to use instead of self.rng
+
+        Returns:
+            Sampled index
+        """
+        rng = rand if rand is not None else self.rng
+        # Generate fair die roll
+        i = rng.randrange(self.n)
+        # Flip biased coin
+        if rng.random() < self.prob[i]:
+            return i
+        else:
+            return self.alias[i]
+    
+    def sample_n(self, n: int) -> List[int]:
+        """Sample n indices efficiently."""
+        return [self.sample() for _ in range(n)]