MacWinUA

[!NOTE] A library for generating realistic browser headers for macOS and Windows platforms — always the freshest Chrome headers.

🔄 Why MacWinUA?

1. Always fresh: Focus on providing the most up-to-date Chrome headers!
2. Platform specific: Tailored for macOS and Windows environments
3. Smart caching: API calls only once per week to minimize overhead
4. Simple API: Easy-to-use, property-based interface
5. Zero dependencies: No external dependencies required
6. Thread-safe: Built for concurrent applications
7. Clean architecture: SOLID principles with proper separation of concerns

Installation

pip install MacWinUA

With Poetry:

poetry add MacWinUA

Requirements

• Python 3.10 or higher

🔥 Usage

Simple UA Strings

from macwinua import ua

# Get any Chrome User-Agent string (random)
ua_string = ua.chrome

# Get a macOS Chrome UA
mac_ua = ua.mac

# Get a Windows Chrome UA
win_ua = ua.windows

# Get the latest available version's UA
latest_ua = ua.latest

# Alias for random Chrome UA
random_ua = ua.random

Complete Browser Headers

from macwinua import ua

# Basic Chrome headers
headers = ua.get_headers()

# macOS Chrome headers
mac_headers = ua.get_headers(platform="mac")

# Windows Chrome headers
win_headers = ua.get_headers(platform="win")

# Specific Chrome version
ver_headers = ua.get_headers(chrome_version="139")

# Specific platform + version
combo_headers = ua.get_headers(platform="mac", chrome_version="138")

# Add custom headers (merged)
custom_headers = ua.get_headers(extra_headers={"X-API-KEY": "mykey"})

# Use with requests
import requests
response = requests.get("https://example.com", headers=ua.get_headers())

Compatibility Function

For even more concise code:

from macwinua import get_chrome_headers

headers = get_chrome_headers()  # random
mac_headers = get_chrome_headers(platform="mac")
win_headers = get_chrome_headers(platform="win", chrome_version="139")

Custom Instances

from macwinua import HeaderGenerator

# Create a new instance (uses singleton DataManager internally)
my_ua = HeaderGenerator()

# Force refresh data from API (bypasses 7-day cache)
my_ua.force_update()

# Use the same methods as the singleton
headers = my_ua.get_headers(platform="win")

Force Update

from macwinua import force_update

# Force refresh the global singleton with latest data from API
force_update()

# Now all calls will use the refreshed data
headers = ua.get_headers()

Example Usage with HTTP Clients

With requests

import requests
from macwinua import ua

# Create a session
session = requests.Session()

# Configure with macOS Chrome headers
session.headers.update(ua.get_headers(platform="mac"))

# Make requests
response = session.get("https://httpbin.org/headers")
print(response.json()["headers"]["User-Agent"])

# Change to Windows headers for next request
session.headers.update(ua.get_headers(platform="win"))
response = session.get("https://httpbin.org/headers")
print(response.json()["headers"]["User-Agent"])

With httpx

import httpx
from macwinua import get_chrome_headers

async def fetch_data():
    headers = get_chrome_headers(platform="mac", chrome_version="139")

    async with httpx.AsyncClient(headers=headers) as client:
        response = await client.get("https://httpbin.org/headers")
        return response.json()

# Run the async function
import asyncio
result = asyncio.run(fetch_data())
print(result["headers"]["User-Agent"])

Custom User-Agent Rotation

from macwinua import HeaderGenerator
import random
import requests
import time

class UARotator:
    def __init__(self):
        self.ua_generator = HeaderGenerator()
        self.platforms = ["mac", "win"]
        self.used_uas = set()

    def get_fresh_headers(self, max_attempts=10):
        """Get headers that haven't been used recently."""
        for _ in range(max_attempts):
            platform = random.choice(self.platforms)
            headers = self.ua_generator.get_headers(platform=platform)
            ua_string = headers["User-Agent"]

            if ua_string not in self.used_uas:
                self.used_uas.add(ua_string)
                # Keep only last 20 UAs to prevent infinite growth
                if len(self.used_uas) > 20:
                    self.used_uas.pop()
                return headers

        # If all attempts failed, return any headers
        return self.ua_generator.get_headers()

# Usage
rotator = UARotator()
session = requests.Session()

for i in range(5):
    fresh_headers = rotator.get_fresh_headers()
    session.headers.update(fresh_headers)

    response = session.get("https://httpbin.org/headers")
    ua_string = response.json()["headers"]["User-Agent"]
    platform = "macOS" if "Macintosh" in ua_string else "Windows"
    print(f"Request {i+1} ({platform}): ...{ua_string[-50:]}")
    time.sleep(1)

Supported Platforms and Browsers

Currently supports:

• Chrome versions: Latest 3 versions - automatically updated
• Platforms: macOS and Windows
• Automatic version detection: Fetches latest versions from Google's API
• Smart caching: Updates version data weekly

API Reference

ua (Singleton Instance)

Properties

• ua.chrome → Random Chrome User-Agent string
• ua.mac → Random macOS Chrome User-Agent string
• ua.windows → Random Windows Chrome User-Agent string
• ua.latest → User-Agent from latest Chrome version
• ua.random → Alias for ua.chrome

Methods

• ua.get_headers(platform=None, chrome_version=None, extra_headers=None) → Complete headers dict
• ua.force_update() → Force refresh data from API

Functions

• get_chrome_headers(**kwargs) → Convenience function using singleton
• force_update() → Force refresh singleton data

Classes

• HeaderGenerator(data_manager=None) → Create header generator instance
• UAError → Base exception class
• APIFetchError → API-related errors
• CacheError → Cache-related errors
• DataValidationError → Data validation errors

Architecture

MacWinUA follows clean architecture principles with proper separation of concerns:

Core Components

• constants.py: Configuration, supported versions, type definitions
• exceptions.py: Custom exception classes for different error types
• core.py: Data processing components (caching, API fetching, data management)
• ua.py: User-facing interface for header generation

Design Principles

• Single Responsibility Principle: Each class has one clear purpose
• Open/Closed Principle: Easy to extend with new platforms or features
• Dependency Injection: Components are loosely coupled and testable
• Thread Safety: All operations are thread-safe for concurrent use

How It Works

1. Version Detection: Fetches latest 3 Chrome versions from Google's official API
2. Smart Caching: Caches version data locally for 7 days to minimize API calls
3. Header Generation: Creates realistic headers with proper sec-ch-ua values
4. Fallback System: Uses hardcoded latest 3 versions (139, 138, 137) if API fails
5. Thread Safety: All operations are thread-safe for concurrent applications

Cache Behavior

• Cache Location: ~/.macwinua/macwinua_cache.json in user's home directory
• Cache Duration: 7 days
• Auto Refresh: Automatically refreshes expired cache on next use
• Force Refresh: Use force_update() to bypass cache
• Fallback: Uses built-in versions (139, 138, 137) if API is unavailable

Error Handling

from macwinua import ua, UAError, APIFetchError, CacheError, DataValidationError

try:
    headers = ua.get_headers(platform="mac", chrome_version="139")
except UAError as e:
    print(f"UA Error: {e}")
except APIFetchError as e:
    print(f"API Error: {e}")
except CacheError as e:
    print(f"Cache Error: {e}")
except DataValidationError as e:
    print(f"Data Validation Error: {e}")

Development

This project uses Poetry for dependency management and packaging.

Setup Development Environment

# Clone the repository
git clone https://github.com/Nuung/MacWinUA.git
cd MacWinUA

# Setup Python 3.10+ with pyenv (optional)
pyenv install 3.13.0
pyenv local 3.13.0

# Install dependencies
poetry install

# Activate the virtual environment
poetry shell

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=macwinua --cov-report=html

# Run specific test file
pytest tests/test_ua.py
pytest tests/test_core.py

# Run with verbose output
pytest -v

Code Quality

# Run linter
poetry run ruff check macwinua/ tests/

# Run formatter
poetry run ruff format macwinua/ tests/

# Run type checker
poetry run mypy macwinua/

Pre-commit Hooks

# Install pre-commit hooks
pre-commit install

# Run manually on all files
pre-commit run --all-files

The pre-commit hooks automatically run:

1. Ruff linting and formatting
2. MyPy type checking
3. Pytest tests

[!WARNING] > These checks run in CI pipeline, ensuring consistency between local development and automated testing.

Performance

MacWinUA is designed for high performance:

• Singleton Pattern: Shared data manager reduces memory usage
• Smart Caching: Minimizes API calls (once per week maximum)
• Thread Safety: Efficient concurrent access with minimal locking
• Memory Efficient: Lightweight data structures and minimal dependencies

Benchmark Results

# Simple performance test
import time
from macwinua import ua

# Test header generation speed
start = time.time()
for _ in range(1000):
    headers = ua.get_headers()
end = time.time()

print(f"Generated 1000 headers in {end-start:.3f}s")
# Typical result: ~0.010s (100,000 headers/second)

Comparison with Other Libraries

Unlike fake-useragent and similar libraries, MacWinUA focuses specifically on:

1. Always up-to-date headers (including sec-ch-ua values)
2. Realistic header combinations for perfect browser impersonation
3. Chrome-only focus with macOS and Windows platforms
4. Zero dependencies and lightweight design
5. Smart caching to minimize API overhead
6. Thread-safe operations for production applications
7. Clean architecture following SOLID principles

Contributing

We welcome contributions! Please ensure your code follows our standards:

1. Code Style: Use Ruff for linting and formatting
2. Type Hints: Full type coverage with MyPy
3. Tests: 100% test coverage for new code
4. Documentation: Update README and docstrings
5. Architecture: Follow SOLID principles and existing patterns

License

This project is licensed under the MIT License - see the LICENSE.md file for details.