useragentgen 1.0__tar.gz

useragentgen-1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv
+*.pyc
+A*.md
+
+/dist

useragentgen-1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 [Masrkai]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

useragentgen-1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: useragentgen
+Version: 1.0
+Summary: Random User-Agent string generator with embedded browser templates
+Project-URL: Homepage, https://github.com/Masrkai/useragentgen
+Project-URL: Repository, https://github.com/Masrkai/useragentgen
+Project-URL: Issues, https://github.com/Masrkai/useragentgen/issues
+Author: Masrkai
+License: MIT
+License-File: LICENSE
+Keywords: browser,fake-user-agent,http,scraping,testing,user-agent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# useragentgen
+
+Random User-Agent string generator for Chrome, Firefox, Safari, Edge, and Opera.
+All browser templates are **embedded inside the package** — no external files needed after install.
+
+## Installation
+
+```bash
+pip install useragentgen
+```
+
+## Quick start
+
+```python
+import useragentgen
+
+# Single UA, random browser
+useragentgen.generate()
+
+# Single UA, specific browser
+useragentgen.generate("chrome")
+useragentgen.generate("firefox")
+useragentgen.generate("safari")
+useragentgen.generate("edge")
+useragentgen.generate("opera")
+
+# Batch generation
+useragentgen.generate_many(10)            # 10 random-browser UAs
+useragentgen.generate_many(5, "chrome")   # 5 Chrome UAs
+```
+
+Reproducible output with a seed:
+
+```python
+import useragentgen
+
+useragentgen.init(42)
+print(useragentgen.generate("chrome"))  # same result every run
+```
+
+## Supported browsers
+
+| Key        | Covers                         |
+|------------|-------------------------------|
+| `chrome`   | Windows, macOS, Linux, Android |
+| `firefox`  | All platforms                  |
+| `safari`   | macOS, iOS, Windows            |
+| `edge`     | Windows, macOS, Linux, Android |
+| `opera`    | Windows, macOS, Linux          |
+
+## License
+
+[MIT License Copyright (c) 2026 Masrkai, rights reserved](LICENSE)

useragentgen-1.0/README.md

@@ -0,0 +1,53 @@
+# useragentgen
+
+Random User-Agent string generator for Chrome, Firefox, Safari, Edge, and Opera.
+All browser templates are **embedded inside the package** — no external files needed after install.
+
+## Installation
+
+```bash
+pip install useragentgen
+```
+
+## Quick start
+
+```python
+import useragentgen
+
+# Single UA, random browser
+useragentgen.generate()
+
+# Single UA, specific browser
+useragentgen.generate("chrome")
+useragentgen.generate("firefox")
+useragentgen.generate("safari")
+useragentgen.generate("edge")
+useragentgen.generate("opera")
+
+# Batch generation
+useragentgen.generate_many(10)            # 10 random-browser UAs
+useragentgen.generate_many(5, "chrome")   # 5 Chrome UAs
+```
+
+Reproducible output with a seed:
+
+```python
+import useragentgen
+
+useragentgen.init(42)
+print(useragentgen.generate("chrome"))  # same result every run
+```
+
+## Supported browsers
+
+| Key        | Covers                         |
+|------------|-------------------------------|
+| `chrome`   | Windows, macOS, Linux, Android |
+| `firefox`  | All platforms                  |
+| `safari`   | macOS, iOS, Windows            |
+| `edge`     | Windows, macOS, Linux, Android |
+| `opera`    | Windows, macOS, Linux          |
+
+## License
+
+[MIT License Copyright (c) 2026 Masrkai, rights reserved](LICENSE)

useragentgen-1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "useragentgen"
+version = "1.0"
+authors = [
+    { name = "Masrkai" },
+]
+description = "Random User-Agent string generator with embedded browser templates"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+keywords = [
+    "http",
+    "testing",
+    "browser",
+    "scraping",
+    "user-agent",
+    "fake-user-agent",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+# No third-party runtime deps — stdlib only
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/Masrkai/useragentgen"
+Repository = "https://github.com/Masrkai/useragentgen"
+Issues = "https://github.com/Masrkai/useragentgen/issues"
+
+# ---------------------------------------------------------------------------
+# Hatchling: include data files (.txt templates + configs.json)
+# ---------------------------------------------------------------------------
+[tool.hatch.build.targets.wheel]
+packages = ["useragentgen"]
+
+[tool.hatch.build.targets.sdist]
+include = ["README.md", "useragentgen/", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

useragentgen-1.0/useragentgen/__init__.py

@@ -0,0 +1,18 @@
+"""
+useragentgen
+============
+Random User-Agent string generator with embedded templates.
+
+Quick start
+-----------
+>>> from useragentgen import generate, generate_many, init
+>>> init(42)                    # optional seed for reproducibility
+>>> generate()                  # random browser
+>>> generate("firefox")         # specific browser
+>>> generate_many(5)            # list of 5 random UAs
+"""
+
+from .generator import generate, generate_many, init
+from .parser import init_parser, parse_line
+
+__all__ = ["generate", "generate_many", "init", "parse_line", "init_parser"]

useragentgen-1.0/useragentgen/data/__init__.py

@@ -0,0 +1 @@
+# required for importlib.resources

useragentgen-1.0/useragentgen/data/configs.json

@@ -0,0 +1,79 @@
+{
+  "chrome": {
+    "os_exclude": [
+      "ios"
+    ],
+    "engine": "webkit_chrome",
+    "version_prefix": "Chrome/",
+    "mobile_token": {
+      "if": "android",
+      "value": "android_chrome"
+    },
+    "suffix": "Safari/537.36"
+  },
+  "firefox": {
+    "os_allow": "*",
+    "engine": "gecko",
+    "version_prefix": [
+      "Firefox/",
+      {
+        "prefix": "rv:",
+        "os_exclude": [
+          "android",
+          "ios"
+        ]
+      }
+    ],
+    "mobile_token": null,
+    "suffix": null
+  },
+  "safari": {
+    "os_allow": [
+      "macos",
+      "ios",
+      "windows"
+    ],
+    "engine": "webkit_safari",
+    "version_prefix": "Version/",
+    "mobile_token": {
+      "if": "ios",
+      "value": "ios_safari"
+    },
+    "suffix": {
+      "method": "_safari_suffix"
+    }
+  },
+  "edge": {
+    "os_exclude": [
+      "ios"
+    ],
+    "engine": "webkit_chrome",
+    "version_prefix": "Edg/",
+    "mobile_token": {
+      "if": "android",
+      "value": "android_chrome"
+    },
+    "suffix": {
+      "template": "Chrome/{rnd}.0.0.0 Safari/537.36",
+      "rnd": [
+        115,
+        134
+      ]
+    }
+  },
+  "opera": {
+    "os_exclude": [
+      "ios"
+    ],
+    "engine": "webkit_chrome",
+    "version_prefix": "OPR/",
+    "mobile_token": null,
+    "suffix": {
+      "template": "Chrome/{rnd}.0.0.0 Safari/537.36",
+      "rnd": [
+        115,
+        134
+      ]
+    }
+  }
+}

useragentgen-1.0/useragentgen/data/engine.txt

@@ -0,0 +1,14 @@
+# Engine strings by name
+# Referenced in configs.json as "engine": "name"
+
+# Chrome / Edge / Opera
+webkit_chrome = AppleWebKit/537.36 (KHTML, like Gecko)
+
+# Safari (desktop & iOS)
+webkit_safari = AppleWebKit/605.1.15 (KHTML, like Gecko)
+
+# Firefox (desktop)
+gecko = Gecko/20100101
+
+# Firefox (Android variant — version inline, no separate engine token)
+gecko_android = Gecko/{115-122}.0

useragentgen-1.0/useragentgen/data/exclusions.txt

@@ -0,0 +1,25 @@
+# Browser-OS exclusion rules
+# Format: browser:os_substring_pattern
+# Lines starting with # are ignored
+
+# Safari was discontinued on Windows
+safari:Windows NT
+
+# Edge and Opera don't exist on iOS
+edge:iPhone
+edge:iPad
+opera:iPhone
+opera:iPad
+
+# Firefox on iOS uses WebKit (different UA format)
+# So exclude from our desktop Firefox generator
+firefox:iPhone
+firefox:iPad
+
+# Safari on Linux doesn't exist
+safari:Linux
+
+# Chrome on iOS uses WebKit (still valid but different)
+# Keep if you want, or uncomment to exclude:
+# chrome:iPhone
+# chrome:iPad

useragentgen-1.0/useragentgen/data/mobile_token.txt

@@ -0,0 +1,13 @@
+# Mobile token strings by name
+# Referenced in configs.json as "mobile_token": {"value": "name"}
+
+# iOS Safari (iPhone & iPad)
+ios_safari = Mobile/15E148
+
+# Chrome on Android
+android_chrome = Mobile Safari/537.36
+
+# Safari fallback tokens (desktop & iOS)
+safari_604 = Safari/604.1
+safari_605 = Safari/605.1.15
+safari_537 = Safari/537.36

useragentgen-1.0/useragentgen/data/os.txt

@@ -0,0 +1,18 @@
+# Windows
+Windows NT 10.0; Win64; x64
+Windows NT 6.3; Win64; x64
+Windows NT 6.1; Win64; x64
+
+# macOS
+Macintosh; Intel Mac OS X {10|11|12|13|14|15}_{0|1|2|3|4|5|6|7}_0
+
+# Linux
+X11; {|Ubuntu; |Fedora; |Linux Mint; }Linux {x86_64|i686}
+
+# Android
+Linux; Android {11-15}; {Pixel 6|Pixel 7|Pixel 8|Pixel 9|Pixel 10}
+Linux; Android {11-15}; {SM-G991B|SM-G998B|SM-S918B|SM-A546B|SM-F946B}
+
+# iOS
+iPhone; CPU iPhone OS {15|16|17|18}_{0|1|2|3|4|5|6} like Mac OS X
+iPad; CPU OS {15|16|17|18}_{0|1|2|3|4|5|6} like Mac OS X

useragentgen-1.0/useragentgen/data/prefix.txt

@@ -0,0 +1 @@
+Mozilla/5.0

useragentgen-1.0/useragentgen/data/version.txt

@@ -0,0 +1,17 @@
+# Chrome
+Chrome/{115-134}.0.{5000-6999}.{0-250}
+
+# Firefox
+Firefox/{115-135}.0
+
+# Firefox (rv tag, desktop only)
+rv:{115-135}.0
+
+# Safari
+Version/{15-18}.{0-6}
+
+# Edge (Edg token)
+Edg/{115-134}.0.{1000-2500}.{0-150}
+
+# Opera (OPR token)
+OPR/{100-117}.0.{4000-5500}.{0-150}

useragentgen-1.0/useragentgen/generator.py

@@ -0,0 +1,269 @@
+import json
+import random
+from importlib.resources import files
+from typing import Any, Dict, List, Optional
+
+from . import parser
+
+_DATA_PKG = "useragentgen.data"
+
+# Module-level state
+_rng = random.Random()
+_data: Dict[str, Any] = {}
+_configs: Dict[str, Any] = {}
+_exclusions: Dict[str, List[str]] = {}
+_engines: Dict[str, str] = {}
+_mobile_tokens: Dict[str, str] = {}
+_initialized = False
+
+
+def _read_resource(filename: str) -> str:
+    return files(_DATA_PKG).joinpath(filename).read_text(encoding="utf-8")
+
+
+def _parse_single(filename: str) -> str:
+    for raw in _read_resource(filename).splitlines():
+        line = raw.strip()
+        if line and not line.startswith("#"):
+            return parser.parse_line(line)
+    return ""
+
+
+def _parse_list(filename: str) -> List[str]:
+    results = []
+    for raw in _read_resource(filename).splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        results.append(parser.parse_line(line))
+    return results
+
+
+def _parse_lookup(filename: str) -> Dict[str, str]:
+    results = {}
+    for raw in _read_resource(filename).splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        results[key.strip()] = parser.parse_line(value.strip())
+    return results
+
+
+# OS detection helpers (same as before)
+def _is_windows(s: str) -> bool:
+    return s.startswith("Windows")
+
+
+def _is_macos(s: str) -> bool:
+    return s.startswith("Macintosh")
+
+
+def _is_android(s: str) -> bool:
+    return "Android" in s and "iPhone" not in s and "iPad" not in s
+
+
+def _is_ios(s: str) -> bool:
+    return "iPhone" in s or "iPad" in s
+
+
+def _is_excluded(browser: str, os_str: str) -> bool:
+    for pattern in _exclusions.get(browser, []):
+        if pattern in os_str:
+            return True
+    return False
+
+
+def _safari_suffix(os_str: str) -> str:
+    if _is_ios(os_str):
+        return _rng.choice(["Safari/604.1", "Safari/605.1.15"])
+    return "Safari/605.1.15"
+
+
+# Rule interpreters (same logic, using module _rng)
+def _check_os(rule: Dict[str, Any], os_str: str) -> bool:
+    if "os_allow" in rule:
+        allowed = rule["os_allow"]
+        if allowed == "*":
+            return True
+        return any(globals()[f"_is_{opt}"](os_str) for opt in allowed)
+    if "os_exclude" in rule:
+        excluded = rule["os_exclude"]
+        return not any(globals()[f"_is_{opt}"](os_str) for opt in excluded)
+    return True
+
+
+def _check_version(rule: Dict[str, Any], version: str, os_str: str) -> bool:
+    """Evaluate version_prefix rules, with optional OS conditions."""
+    prefixes = rule["version_prefix"]
+    if isinstance(prefixes, str):
+        prefixes = [prefixes]
+
+    for p in prefixes:
+        if isinstance(p, str):
+            # Simple string prefix
+            if version.startswith(p):
+                return True
+        else:
+            # Dict with OS conditions: {"prefix": "rv:", "os_exclude": ["android"]}
+            if not version.startswith(p["prefix"]):
+                continue
+
+            # Check OS conditions if present
+            excluded = p.get("os_exclude", [])
+            if any(globals()[f"_is_{opt}"](os_str) for opt in excluded):
+                continue
+            allowed = p.get("os_allow", [])
+            if allowed:  # Only check if explicitly defined
+                if not any(globals()[f"_is_{opt}"](os_str) for opt in allowed):
+                    continue
+                return True
+            else:
+                return True  # No restrictions means it's allowed
+    return False
+
+
+def _get_mobile_token(rule: Dict[str, Any], os_str: str) -> Optional[str]:
+    mobile_cfg = rule.get("mobile_token")
+    if not mobile_cfg:
+        return None
+    condition = mobile_cfg["if"]
+    if globals()[f"_is_{condition}"](os_str):
+        token_name = mobile_cfg["value"]
+        return _mobile_tokens.get(token_name, token_name)
+    return None
+
+
+def _get_suffix(rule: Dict[str, Any], version: str, os_str: str) -> Optional[str]:
+    suffix_rule = rule.get("suffix")
+    if suffix_rule is None:
+        return None
+    if isinstance(suffix_rule, str):
+        return suffix_rule
+    if "method" in suffix_rule:
+        return globals()[suffix_rule["method"]](os_str)
+    if "template" in suffix_rule:
+        template = suffix_rule["template"]
+        result = template
+        for key, val in suffix_rule.items():
+            if key == "template":
+                continue
+            if isinstance(val, list) and len(val) == 2:
+                result = result.replace(f"{{{key}}}", str(_rng.randint(val[0], val[1])))
+        return result
+    return None
+
+
+def init(seed: Optional[int] = None) -> None:
+    """Initialize or reinitialize the generator with an optional seed."""
+    global _initialized, _rng, _data, _configs, _exclusions, _engines, _mobile_tokens
+
+    _rng = random.Random(seed)
+    parser.init_parser(seed)  # Sync parser RNG
+
+    # Core data
+    _data = {
+        "prefix": _parse_single("prefix.txt"),
+        "os_list": _parse_list("os.txt"),
+        "versions": _parse_list("version.txt"),
+    }
+
+    # Browser configs from JSON
+    _configs = json.loads(_read_resource("configs.json"))
+
+    # Engine and mobile token lookups
+    _engines = _parse_lookup("engine.txt")
+    _mobile_tokens = _parse_lookup("mobile_token.txt")
+
+    # Exclusion rules
+    browsers = ("chrome", "firefox", "safari", "edge", "opera")
+    _exclusions = {b: [] for b in browsers}
+    try:
+        content = _read_resource("exclusions.txt")
+        for line in content.splitlines():
+            line = line.strip()
+            if not line or line.startswith("#") or ":" not in line:
+                continue
+            browser, pattern = line.split(":", 1)
+            browser = browser.strip().lower()
+            if browser in _exclusions:
+                _exclusions[browser].append(pattern.strip())
+    except FileNotFoundError:
+        pass
+
+    _initialized = True
+
+
+def _ensure_init() -> None:
+    if not _initialized:
+        init()
+
+
+def generate(browser: Optional[str] = None) -> str:
+    """Generate a single User-Agent string."""
+    _ensure_init()
+
+    browsers = ("chrome", "firefox", "safari", "edge", "opera")
+    if browser is None:
+        browser = _rng.choice(browsers)
+    else:
+        browser = browser.lower()
+
+    cfg = _configs.get(browser)
+    if not cfg:
+        raise ValueError(f"Unknown browser: {browser!r}. Choose from: {browsers}")
+
+    valid_os = [
+        os_str
+        for os_str in _data["os_list"]
+        if _check_os(cfg, os_str) and not _is_excluded(browser, os_str)
+    ]
+    if not valid_os:
+        raise ValueError(f"No valid OS found for browser: {browser!r}")
+    os_str = _rng.choice(valid_os)
+
+
+
+    # In generate() function, after selecting OS:
+    if browser == "firefox":
+        # Firefox needs both rv: (in parens) and Firefox/ (after engine)
+        version_num = _rng.randint(115, 135)
+        rv_version = f"rv:{version_num}.0"
+        fx_version = f"Firefox/{version_num}.0"
+        
+        # Insert rv: into OS parentheses
+        os_str = os_str.rstrip(')') + f"; {rv_version})"
+        engine = _engines.get(cfg["engine"], cfg["engine"])
+        parts = [_data["prefix"], f"({os_str}", engine, fx_version]
+    else:
+        # valid_versions = [v for v in _data["versions"] if _check_version(cfg, v)]
+        valid_versions = [v for v in _data["versions"] if _check_version(cfg, v, os_str)]
+
+        if not valid_versions:
+            raise ValueError(f"No valid version tokens found for browser: {browser!r}")
+        version = _rng.choice(valid_versions)
+
+        parts = [_data["prefix"], f"({os_str})"]
+
+        if cfg.get("engine"):
+            engine = _engines.get(cfg["engine"], cfg["engine"])
+            parts.append(engine)
+
+        mobile = _get_mobile_token(cfg, os_str)
+        if mobile:
+            parts.append(mobile)
+
+        parts.append(version)
+
+        suffix = _get_suffix(cfg, version, os_str)
+        if suffix:
+            parts.append(suffix)
+
+    return " ".join(parts)
+
+
+def generate_many(count: int = 10, browser: Optional[str] = None) -> List[str]:
+    """Generate multiple User-Agent strings."""
+    return [generate(browser) for _ in range(count)]

useragentgen-1.0/useragentgen/parser.py

@@ -0,0 +1,31 @@
+import re
+import random
+from typing import Optional
+
+# Module-level RNG (can be seeded via init_parser)
+_rng: random.Random = random.Random()
+
+CHOICE_PATTERN = re.compile(r"\{([^}]+)\}")
+RANGE_PATTERN = re.compile(r"^(\d+)-(\d+)$")
+
+
+def init_parser(seed: Optional[int] = None) -> None:
+    """Initialize or reseed the parser's RNG."""
+    global _rng
+    _rng = random.Random(seed)
+
+
+def parse_line(line: str) -> str:
+    """Expand all {a|b} and {1-10} patterns in a template string."""
+
+    def replace_match(match: re.Match) -> str:
+        content = match.group(1)
+        range_match = RANGE_PATTERN.match(content)
+        if range_match:
+            start, end = int(range_match.group(1)), int(range_match.group(2))
+            return str(_rng.randint(start, end))
+        if "|" in content:
+            return _rng.choice(content.split("|"))
+        return content
+
+    return CHOICE_PATTERN.sub(replace_match, line)