mm-http 0.1.0__tar.gz

mm_http-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+.idea
+.vscode
+.venv
+.env
+.coverage
+/htmlcov
+__pycache__
+*.egg-info
+pip-wheel-metadata
+.pytest_cache
+.mypy_cache
+.ruff_cache
+/dist
+/build
+/tmp
+.DS_Store

mm_http-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,10 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-json
+      - id: check-added-large-files

mm_http-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: mm-http
+Version: 0.1.0
+Requires-Python: >=3.13
+Requires-Dist: aiohttp-socks~=0.10.1
+Requires-Dist: aiohttp~=3.12.12
+Requires-Dist: mm-result~=0.1.1
+Requires-Dist: pydash~=8.0.5
+Requires-Dist: requests[socks]~=2.32.4

mm_http-0.1.0/README.md

@@ -0,0 +1,197 @@
+# mm-http
+
+A simple and convenient HTTP client library for Python with both synchronous and asynchronous support.
+
+## Features
+
+- **Simple API** for one-off HTTP requests
+- **Sync and Async** support with identical interfaces
+- **JSON path navigation** with dot notation (`response.parse_json_body("user.profile.name")`)
+- **Proxy support** (HTTP and SOCKS5)
+- **Unified error handling**
+- **Type-safe** with full type annotations
+- **No sessions** - optimized for simple, stateless requests
+
+## Quick Start
+
+### Async Usage
+
+```python
+from mm_http import http_request
+
+# Simple GET request
+response = await http_request("https://api.github.com/users/octocat")
+user_name = response.parse_json_body("name")  # Navigate JSON with dot notation
+
+# POST with JSON data
+response = await http_request(
+    "https://httpbin.org/post",
+    method="POST",
+    json={"key": "value"},
+    headers={"Authorization": "Bearer token"}
+)
+
+# With proxy
+response = await http_request(
+    "https://api.ipify.org?format=json",
+    proxy="socks5://127.0.0.1:1080"
+)
+```
+
+### Sync Usage
+
+```python
+from mm_http import http_request_sync
+
+# Same API, but synchronous
+response = http_request_sync("https://api.github.com/users/octocat")
+user_name = response.parse_json_body("name")
+```
+
+## API Reference
+
+### Functions
+
+- `http_request(url, **kwargs)` - Async HTTP request
+- `http_request_sync(url, **kwargs)` - Sync HTTP request
+
+### Parameters
+
+- `url: str` - Request URL
+- `method: str = "GET"` - HTTP method
+- `params: dict[str, Any] | None = None` - URL query parameters
+- `data: dict[str, object] | None = None` - Form data
+- `json: dict[str, object] | None = None` - JSON data
+- `headers: dict[str, str] | None = None` - HTTP headers
+- `cookies: LooseCookies | None = None` - Cookies
+- `user_agent: str | None = None` - User-Agent header
+- `proxy: str | None = None` - Proxy URL (supports http://, https://, socks4://, socks5://)
+- `timeout: float | None = 10.0` - Request timeout in seconds
+
+### HttpResponse
+
+```python
+@dataclass
+class HttpResponse:
+    status_code: int | None
+    error: HttpError | None
+    error_message: str | None
+    body: str | None
+    headers: dict[str, str] | None
+
+    def parse_json_body(self, path: str | None = None, none_on_error: bool = False) -> Any
+    def is_err(self) -> bool
+    def content_type(self) -> str | None
+    def to_result_ok[T](self, value: T) -> Result[T]
+    def to_result_err[T](self, error: str | Exception | None = None) -> Result[T]
+```
+
+### Error Types
+
+```python
+class HttpError(str, Enum):
+    TIMEOUT = "timeout"
+    PROXY = "proxy"
+    INVALID_URL = "invalid_url"
+    CONNECTION = "connection"
+    ERROR = "error"
+```
+
+## Examples
+
+### JSON Path Navigation
+
+```python
+response = await http_request("https://api.github.com/users/octocat")
+
+# Instead of: json.loads(response.body)["plan"]["name"]
+plan_name = response.parse_json_body("plan.name")
+
+# Safe navigation - returns None if path doesn't exist
+followers = response.parse_json_body("followers_count")
+nonexistent = response.parse_json_body("does.not.exist")  # Returns None
+```
+
+### Error Handling
+
+```python
+response = await http_request("https://example.com", timeout=5.0)
+
+if response.is_err():
+    print(f"Request failed: {response.error} - {response.error_message}")
+else:
+    print(f"Success: {response.status_code}")
+```
+
+### Proxy Usage
+
+```python
+# HTTP proxy
+response = await http_request(
+    "https://httpbin.org/ip",
+    proxy="http://proxy.example.com:8080"
+)
+
+# SOCKS5 proxy
+response = await http_request(
+    "https://httpbin.org/ip",
+    proxy="socks5://127.0.0.1:1080"
+)
+```
+
+### Custom Headers and User-Agent
+
+```python
+response = await http_request(
+    "https://api.example.com/data",
+    headers={
+        "Authorization": "Bearer your-token",
+        "Accept": "application/json"
+    },
+    user_agent="MyApp/1.0"
+)
+```
+
+### Result Type Integration
+
+For applications using `Result[T, E]` pattern, `HttpResponse` provides convenient methods to convert responses into Result types:
+
+```python
+from mm_result import Result
+
+async def get_user_id() -> Result[int]:
+    response = await http_request("https://api.example.com/user")
+
+    if response.is_err():
+        return response.to_result_err()  # Convert error to Result[T]
+
+    user_id = response.parse_json_body("id")
+    return response.to_result_ok(user_id)  # Convert success to Result[T]
+
+# Usage
+result = await get_user_id()
+if result.is_ok():
+    print(f"User ID: {result.value}")
+else:
+    print(f"Error: {result.error}")
+    print(f"HTTP details: {result.extra}")  # Contains full HTTP response data
+```
+
+**Result Methods:**
+- `to_result_ok(value)` - Create `Result[T]` with success value, preserving HTTP details in `extra`
+- `to_result_err(error?)` - Create `Result[T]` with error, preserving HTTP details in `extra`
+
+## When to Use
+
+**Use mm-http when you need:**
+- Simple, one-off HTTP requests
+- JSON API interactions with easy data access
+- Proxy support for requests
+- Unified sync/async interface
+
+**Use requests/aiohttp directly when you need:**
+- Session management and connection pooling
+- Complex authentication flows
+- Streaming responses
+- Advanced HTTP features
+- Custom retry logic

mm_http-0.1.0/justfile

@@ -0,0 +1,40 @@
+version := `uv run python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])'`
+
+
+clean:
+    rm -rf .pytest_cache .mypy_cache .ruff_cache .coverage dist build src/*.egg-info
+
+build: clean
+    uv build
+
+format:
+    uv run ruff check --select I --fix src tests
+    uv run ruff format src tests
+
+test:
+    uv run pytest -n auto tests
+
+lint: format pre-commit
+    uv run ruff check src tests
+    uv run mypy src
+
+audit:
+    uv export --no-dev --all-extras --format requirements-txt --no-emit-project > requirements.txt
+    uv run pip-audit -r requirements.txt --disable-pip
+    rm requirements.txt
+    uv run bandit --silent --recursive --configfile "pyproject.toml" src
+
+publish: build lint audit test
+    git diff-index --quiet HEAD
+    printf "Enter PyPI token: " && IFS= read -rs TOKEN && echo && uv publish --token "$TOKEN"
+    git tag -a 'v{{version}}' -m 'v{{version}}'
+    git push origin v{{version}}
+
+sync:
+    uv sync --all-extras
+
+pre-commit:
+    uv run pre-commit run --all-files
+
+pre-commit-autoupdate:
+    uv run pre-commit autoupdate

mm_http-0.1.0/pyproject.toml

@@ -0,0 +1,84 @@
+[project]
+name = "mm-http"
+version = "0.1.0"
+description = ""
+requires-python = ">=3.13"
+dependencies = [
+    "mm-result~=0.1.1",
+    "requests[socks]~=2.32.4",
+    "aiohttp~=3.12.12",
+    "aiohttp-socks~=0.10.1",
+    "pydash~=8.0.5",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv]
+dev-dependencies = [
+    "pytest~=8.4.0",
+    "pytest-asyncio~=1.0.0",
+    "pytest-xdist~=3.7.0",
+    "pytest-httpserver~=1.1.3",
+    "ruff~=0.11.13",
+    "mypy~=1.16.0",
+    "pip-audit~=2.9.0",
+    "bandit~=1.8.3",
+    "pre-commit~=4.2.0",
+    "types-requests~=2.32.4.20250611",
+    "python-dotenv~=1.1.0",
+]
+
+[tool.mypy]
+python_version = "3.13"
+warn_no_return = false
+strict = true
+exclude = ["^tests/", "^tmp/"]
+
+[tool.ruff]
+line-length = 130
+target-version = "py313"
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "TC",       # flake8-type-checking, TYPE_CHECKING is dangerous, for example it doesn't work with pydantic
+    "A005",     # flake8-builtins: stdlib-module-shadowing
+    "ERA001",   # eradicate: commented-out-code
+    "PT",       # flake8-pytest-style
+    "D",        # pydocstyle
+    "FIX",      # flake8-fixme
+    "PLR0911",  # pylint: too-many-return-statements
+    "PLR0912",  # pylint: too-many-branches
+    "PLR0913",  # pylint: too-many-arguments
+    "PLR2004",  # pylint: magic-value-comparison
+    "PLC0414",  # pylint: useless-import-alias
+    "FBT",      # flake8-boolean-trap
+    "EM",       # flake8-errmsg
+    "TRY003",   # tryceratops: raise-vanilla-args
+    "C901",     # mccabe: complex-structure,
+    "BLE001",   # flake8-blind-except
+    "S311",     # bandit: suspicious-non-cryptographic-random-usage
+    "TD002",    # flake8-todos: missing-todo-author
+    "TD003",    # flake8-todos: missing-todo-link
+    "RET503",   # flake8-return: implicit-return
+    "COM812",   # it's used in ruff formatter
+    "ASYNC109",
+    "G004",
+]
+[tool.ruff.lint.pep8-naming]
+classmethod-decorators = ["field_validator"]
+[tool.ruff.lint.per-file-ignores]
+"tests/*.py" = ["ANN", "S"]
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.bandit]
+exclude_dirs = ["tests"]
+skips = ["B311"]
+
+[tool.pytest.ini_options]
+markers = ["proxy: requires access proxies"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

mm_http-0.1.0/src/mm_http/__init__.py

@@ -0,0 +1,5 @@
+from .http_request import http_request
+from .http_request_sync import http_request_sync
+from .response import HttpError, HttpResponse
+
+__all__ = ["HttpError", "HttpResponse", "http_request", "http_request_sync"]

mm_http-0.1.0/src/mm_http/http_request.py

@@ -0,0 +1,128 @@
+from typing import Any
+
+import aiohttp
+from aiohttp import ClientHttpProxyError, InvalidUrlClientError
+from aiohttp.typedefs import LooseCookies
+from aiohttp_socks import ProxyConnectionError, ProxyConnector
+from multidict import CIMultiDictProxy
+
+from .response import HttpError, HttpResponse
+
+
+async def http_request(
+    url: str,
+    *,
+    method: str = "GET",
+    params: dict[str, Any] | None = None,
+    data: dict[str, object] | None = None,
+    json: dict[str, object] | None = None,
+    headers: dict[str, str] | None = None,
+    cookies: LooseCookies | None = None,
+    user_agent: str | None = None,
+    proxy: str | None = None,
+    timeout: float | None = 10.0,
+) -> HttpResponse:
+    """
+    Send an HTTP request and return the response.
+    """
+    timeout_ = aiohttp.ClientTimeout(total=timeout) if timeout else None
+    if user_agent:
+        if not headers:
+            headers = {}
+        headers["User-Agent"] = user_agent
+
+    try:
+        if proxy and proxy.startswith("socks"):
+            return await _request_with_socks_proxy(
+                url,
+                method=method,
+                params=params,
+                data=data,
+                json=json,
+                headers=headers,
+                cookies=cookies,
+                proxy=proxy,
+                timeout=timeout_,
+            )
+        return await _request_with_http_or_none_proxy(
+            url,
+            method=method,
+            params=params,
+            data=data,
+            json=json,
+            headers=headers,
+            cookies=cookies,
+            proxy=proxy,
+            timeout=timeout_,
+        )
+    except TimeoutError as err:
+        return HttpResponse(error=HttpError.TIMEOUT, error_message=str(err))
+    except (aiohttp.ClientProxyConnectionError, ProxyConnectionError, ClientHttpProxyError) as err:
+        return HttpResponse(error=HttpError.PROXY, error_message=str(err))
+    except InvalidUrlClientError as e:
+        return HttpResponse(error=HttpError.INVALID_URL, error_message=str(e))
+    except Exception as err:
+        return HttpResponse(error=HttpError.ERROR, error_message=str(err))
+
+
+async def _request_with_http_or_none_proxy(
+    url: str,
+    *,
+    method: str = "GET",
+    params: dict[str, Any] | None = None,
+    data: dict[str, object] | None = None,
+    json: dict[str, object] | None = None,
+    headers: dict[str, str] | None = None,
+    cookies: LooseCookies | None = None,
+    proxy: str | None = None,
+    timeout: aiohttp.ClientTimeout | None,
+) -> HttpResponse:
+    async with aiohttp.request(
+        method, url, params=params, data=data, json=json, headers=headers, cookies=cookies, proxy=proxy, timeout=timeout
+    ) as res:
+        return HttpResponse(
+            status_code=res.status,
+            error=None,
+            error_message=None,
+            body=(await res.read()).decode(),
+            headers=headers_dict(res.headers),
+        )
+
+
+async def _request_with_socks_proxy(
+    url: str,
+    *,
+    method: str = "GET",
+    proxy: str,
+    params: dict[str, Any] | None = None,
+    data: dict[str, object] | None = None,
+    json: dict[str, object] | None = None,
+    headers: dict[str, str] | None = None,
+    cookies: LooseCookies | None = None,
+    timeout: aiohttp.ClientTimeout | None,
+) -> HttpResponse:
+    connector = ProxyConnector.from_url(proxy)
+    async with (
+        aiohttp.ClientSession(connector=connector) as session,
+        session.request(
+            method, url, params=params, data=data, json=json, headers=headers, cookies=cookies, timeout=timeout
+        ) as res,
+    ):
+        return HttpResponse(
+            status_code=res.status,
+            error=None,
+            error_message=None,
+            body=(await res.read()).decode(),
+            headers=headers_dict(res.headers),
+        )
+
+
+def headers_dict(headers: CIMultiDictProxy[str]) -> dict[str, str]:
+    result: dict[str, str] = {}
+    for key in headers:
+        values = headers.getall(key)
+        if len(values) == 1:
+            result[key] = values[0]
+        else:
+            result[key] = ", ".join(values)
+    return result

mm_http-0.1.0/src/mm_http/http_request_sync.py

@@ -0,0 +1,63 @@
+from typing import Any
+
+import requests
+from requests.exceptions import InvalidSchema, MissingSchema, ProxyError
+
+from .response import HttpError, HttpResponse
+
+
+def http_request_sync(
+    url: str,
+    *,
+    method: str = "GET",
+    params: dict[str, Any] | None = None,
+    data: dict[str, Any] | None = None,
+    json: dict[str, Any] | None = None,
+    headers: dict[str, Any] | None = None,
+    cookies: dict[str, Any] | None = None,
+    user_agent: str | None = None,
+    proxy: str | None = None,
+    timeout: float | None = 10.0,
+) -> HttpResponse:
+    """
+    Send a synchronous HTTP request and return the response.
+    """
+    if user_agent:
+        if headers is None:
+            headers = {}
+        headers["User-Agent"] = user_agent
+
+    proxies: dict[str, str] | None = None
+    if proxy:
+        proxies = {
+            "http": proxy,
+            "https": proxy,
+        }
+
+    try:
+        res = requests.request(
+            method=method,
+            url=url,
+            params=params,
+            data=data,
+            json=json,
+            headers=headers,
+            cookies=cookies,
+            timeout=timeout,
+            proxies=proxies,
+        )
+        return HttpResponse(
+            status_code=res.status_code,
+            error=None,
+            error_message=None,
+            body=res.text,
+            headers=dict(res.headers),
+        )
+    except requests.Timeout as e:
+        return HttpResponse(error=HttpError.TIMEOUT, error_message=str(e))
+    except ProxyError as e:
+        return HttpResponse(error=HttpError.PROXY, error_message=str(e))
+    except (InvalidSchema, MissingSchema) as e:
+        return HttpResponse(error=HttpError.INVALID_URL, error_message=str(e))
+    except Exception as e:
+        return HttpResponse(error=HttpError.ERROR, error_message=str(e))

mm_http-0.1.0/src/mm_http/response.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import enum
+import json
+from dataclasses import dataclass
+from typing import Any
+
+import pydash
+from mm_result import Result
+
+
+@enum.unique
+class HttpError(str, enum.Enum):
+    TIMEOUT = "timeout"
+    PROXY = "proxy"
+    INVALID_URL = "invalid_url"
+    CONNECTION = "connection"
+    ERROR = "error"
+
+
+@dataclass
+class HttpResponse:
+    """HTTP response with status, error, body, and headers."""
+
+    status_code: int | None = None
+    error: HttpError | None = None
+    error_message: str | None = None
+    body: str | None = None
+    headers: dict[str, str] | None = None
+
+    def parse_json_body(self, path: str | None = None, none_on_error: bool = False) -> Any:  # noqa: ANN401
+        """Parse JSON body and optionally extract value by path."""
+        if self.body is None:
+            if none_on_error:
+                return None
+            raise ValueError("Body is None")
+
+        try:
+            res = json.loads(self.body)
+            return pydash.get(res, path, None) if path else res
+        except json.JSONDecodeError:
+            if none_on_error:
+                return None
+            raise
+
+    def is_err(self) -> bool:
+        """Check if response represents an error (has error or status >= 400)."""
+        return self.error is not None or (self.status_code is not None and self.status_code >= 400)
+
+    def to_result_err[T](self, error: str | Exception | tuple[str, Exception] | None = None) -> Result[T]:
+        """Create error Result[T] from HttpResponse."""
+        return Result.err(error or self.error or "error", extra=self.to_dict())
+
+    def to_result_ok[T](self, value: T) -> Result[T]:
+        """Create success Result[T] from HttpResponse with given value."""
+        return Result.ok(value, extra=self.to_dict())
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert HttpResponse to dictionary."""
+        return {
+            "status_code": self.status_code,
+            "error": self.error.value if self.error else None,
+            "error_message": self.error_message,
+            "body": self.body,
+            "headers": self.headers,
+        }
+
+    @property
+    def content_type(self) -> str | None:
+        """Get Content-Type header value (case-insensitive)."""
+        if self.headers is None:
+            return None
+        for key in self.headers:
+            if key.lower() == "content-type":
+                return self.headers[key]
+        return None
+
+    def __repr__(self) -> str:
+        parts: list[str] = []
+        if self.status_code is not None:
+            parts.append(f"status_code={self.status_code!r}")
+        if self.error is not None:
+            parts.append(f"error={self.error!r}")
+        if self.error_message is not None:
+            parts.append(f"error_message={self.error_message!r}")
+        if self.body is not None:
+            parts.append(f"body={self.body!r}")
+        if self.headers is not None:
+            parts.append(f"headers={self.headers!r}")
+        return f"HttpResponse({', '.join(parts)})"

mm_http-0.1.0/tests/conftest.py

@@ -0,0 +1,22 @@
+import os
+
+import pytest
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+@pytest.fixture
+def proxy_http() -> str:
+    proxy = os.getenv("PROXY_HTTP")
+    if not proxy:
+        raise ValueError("PROXY_HTTP environment variable must be set")
+    return proxy
+
+
+@pytest.fixture
+def proxy_socks5() -> str:
+    proxy = os.getenv("PROXY_SOCKS5")
+    if not proxy:
+        raise ValueError("PROXPROXY_SOCKS5Y_HTTP environment variable must be set")
+    return proxy