mm-http 0.1.4__tar.gz → 0.2.0__tar.gz

mm_http-0.2.0/.claude/settings.local.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run ruff:*)",
+      "Bash(uv run:*)",
+      "mcp__ide__getDiagnostics",
+      "Bash(just lint)",
+      "Bash(just test:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

mm_http-0.2.0/CLAUDE.md

@@ -0,0 +1,13 @@
+# Claude Guidelines
+
+## Critical Guidelines
+
+1. **Always communicate in English** - Regardless of the language the user speaks, always respond in English. All code, comments, and documentation must be in English.
+
+2. **Minimal documentation** - Only add comments/documentation when it simplifies understanding and isn't obvious from the code itself. Keep it strictly relevant and concise.
+
+3. **Critical thinking** - Always critically evaluate user ideas. Users can make mistakes. Think first about whether the user's idea is good before implementing.
+
+4. **Lint after changes** - After making code changes, always run `just lint` to verify code quality and fix any linter issues.
+
+5. **No disabling linter rules** - Never use special disabling comments (like `# noqa`, `# type: ignore`, `# ruff: noqa`, etc.) to turn off linter rules without explicit permission. If you believe a rule should be disabled, ask first.

{mm_http-0.1.4 → mm_http-0.2.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: mm-http
-Version: 0.1.4
+Version: 0.2.0
 Requires-Python: >=3.13
 Requires-Dist: aiohttp-socks~=0.10.1
-Requires-Dist: aiohttp~=3.12.15
-Requires-Dist: mm-result~=0.1.1
+Requires-Dist: aiohttp~=3.13.0
+Requires-Dist: mm-result~=0.1.2
+Requires-Dist: pydantic~=2.12.0
 Requires-Dist: pydash~=8.0.5
 Requires-Dist: requests[socks]~=2.32.5
-Requires-Dist: urllib3~=2.5.0

{mm_http-0.1.4 → mm_http-0.2.0}/README.md

@@ -21,7 +21,7 @@ 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
+user_name = response.parse_json("name")  # Navigate JSON with dot notation
 
 # POST with JSON data
 response = await http_request(
@@ -45,7 +45,7 @@ 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")
+user_name = response.parse_json("name")
 ```
 
 ## API Reference
@@ -60,9 +60,9 @@ user_name = response.parse_json_body("name")
 - `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
+- `data: dict[str, Any] | None = None` - Form data
+- `json: dict[str, Any] | None = None` - JSON data
+- `headers: dict[str, Any] | 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://)
@@ -71,25 +71,39 @@ user_name = response.parse_json_body("name")
 ### HttpResponse
 
 ```python
-@dataclass
-class HttpResponse:
+class HttpResponse(BaseModel):
     status_code: int | None
-    error: HttpError | None
-    error_message: str | None
     body: str | None
     headers: dict[str, str] | None
+    transport_error: TransportErrorDetail | 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
+    # JSON parsing
+    def parse_json(self, path: str | None = None, none_on_error: bool = False) -> Any
+
+    # Header access
+    def get_header(self, name: str) -> str | None
+    @property content_type(self) -> str | None
+
+    # Status checks
+    def is_success(self) -> bool  # 2xx status
+    def is_err(self) -> bool  # Has transport error or status >= 400
+
+    # Result conversion
     def to_result_ok[T](self, value: T) -> Result[T]
     def to_result_err[T](self, error: str | Exception | None = None) -> Result[T]
+
+    # Pydantic methods
+    def model_dump(self, mode: str = "python") -> dict[str, Any]
+
+class TransportErrorDetail(BaseModel):
+    type: TransportError
+    message: str
 ```
 
 ### Error Types
 
 ```python
-class HttpError(str, Enum):
+class TransportError(str, Enum):
     TIMEOUT = "timeout"
     PROXY = "proxy"
     INVALID_URL = "invalid_url"
@@ -105,11 +119,14 @@ class HttpError(str, Enum):
 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")
+plan_name = response.parse_json("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
+followers = response.parse_json("followers_count")
+nonexistent = response.parse_json("does.not.exist")  # Returns None
+
+# Or get full JSON
+data = response.parse_json()
 ```
 
 ### Error Handling
@@ -117,8 +134,16 @@ nonexistent = response.parse_json_body("does.not.exist")  # Returns None
 ```python
 response = await http_request("https://example.com", timeout=5.0)
 
+# Simple check
+if response.is_success():
+    data = response.parse_json()
+
+# Detailed error handling
 if response.is_err():
-    print(f"Request failed: {response.error} - {response.error_message}")
+    if response.transport_error:
+        print(f"Transport error: {response.transport_error.type} - {response.transport_error.message}")
+    elif response.status_code >= 400:
+        print(f"HTTP error: {response.status_code}")
 else:
     print(f"Success: {response.status_code}")
 ```
@@ -163,17 +188,17 @@ 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]
+        return response.to_result_err()  # Returns "HTTP 404" or TransportError.TIMEOUT
 
-    user_id = response.parse_json_body("id")
-    return response.to_result_ok(user_id)  # Convert success to Result[T]
+    user_id = response.parse_json("id")
+    return response.to_result_ok(user_id)
 
 # Usage
 result = await get_user_id()
 if result.is_ok():
     print(f"User ID: {result.value}")
 else:
-    print(f"Error: {result.error}")
+    print(f"Error: {result.error}")  # "HTTP 404" or TransportError.TIMEOUT
     print(f"HTTP details: {result.extra}")  # Contains full HTTP response data
 ```
 

{mm_http-0.1.4 → mm_http-0.2.0}/pyproject.toml

@@ -1,34 +1,33 @@
 [project]
 name = "mm-http"
-version = "0.1.4"
+version = "0.2.0"
 description = ""
 requires-python = ">=3.13"
 dependencies = [
-    "mm-result~=0.1.1",
+    "mm-result~=0.1.2",
     "requests[socks]~=2.32.5",
-    "aiohttp~=3.12.15",
+    "aiohttp~=3.13.0",
     "aiohttp-socks~=0.10.1",
     "pydash~=8.0.5",
-    "urllib3~=2.5.0",          # urllib3 is a dependency of requests, temporarily added to avoid GHSA-48p4-8xcf-vxj5, GHSA-pq67-6m6q-mj2v
-
+    "pydantic~=2.12.0",
 ]
 
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
-[tool.uv]
-dev-dependencies = [
-    "pytest~=8.4.1",
-    "pytest-asyncio~=1.1.0",
+[dependency-groups]
+dev = [
+    "pytest~=8.4.2",
+    "pytest-asyncio~=1.2.0",
     "pytest-xdist~=3.8.0",
     "pytest-httpserver~=1.1.3",
-    "ruff~=0.12.10",
-    "mypy~=1.17.1",
+    "ruff~=0.14.0",
+    "mypy~=1.18.2",
     "pip-audit~=2.9.0",
     "bandit~=1.8.6",
     "pre-commit~=4.3.0",
-    "types-requests~=2.32.4.20250809",
+    "types-requests~=2.32.4.20250913",
     "python-dotenv~=1.1.1",
 ]
 

mm_http-0.2.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 HttpResponse, TransportError, TransportErrorDetail
+
+__all__ = ["HttpResponse", "TransportError", "TransportErrorDetail", "http_request", "http_request_sync"]

{mm_http-0.1.4 → mm_http-0.2.0}/src/mm_http/http_request.py

@@ -1,12 +1,20 @@
 from typing import Any
 
 import aiohttp
-from aiohttp import ClientHttpProxyError, InvalidUrlClientError
+from aiohttp import (
+    ClientConnectionError,
+    ClientConnectorError,
+    ClientHttpProxyError,
+    ClientSSLError,
+    InvalidUrlClientError,
+    ServerConnectionError,
+    ServerDisconnectedError,
+)
 from aiohttp.typedefs import LooseCookies
 from aiohttp_socks import ProxyConnectionError, ProxyConnector
 from multidict import CIMultiDictProxy
 
-from .response import HttpError, HttpResponse
+from .response import HttpResponse, TransportError, TransportErrorDetail
 
 
 async def http_request(
@@ -14,9 +22,9 @@ async def http_request(
     *,
     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,
+    data: dict[str, Any] | None = None,
+    json: dict[str, Any] | None = None,
+    headers: dict[str, Any] | None = None,
     cookies: LooseCookies | None = None,
     user_agent: str | None = None,
     proxy: str | None = None,
@@ -56,13 +64,21 @@ async def http_request(
             timeout=timeout_,
         )
     except TimeoutError as err:
-        return HttpResponse(error=HttpError.TIMEOUT, error_message=str(err))
+        return HttpResponse(transport_error=TransportErrorDetail(type=TransportError.TIMEOUT, message=str(err)))
     except (aiohttp.ClientProxyConnectionError, ProxyConnectionError, ClientHttpProxyError) as err:
-        return HttpResponse(error=HttpError.PROXY, error_message=str(err))
+        return HttpResponse(transport_error=TransportErrorDetail(type=TransportError.PROXY, message=str(err)))
     except InvalidUrlClientError as e:
-        return HttpResponse(error=HttpError.INVALID_URL, error_message=str(e))
+        return HttpResponse(transport_error=TransportErrorDetail(type=TransportError.INVALID_URL, message=str(e)))
+    except (
+        ClientConnectorError,
+        ServerConnectionError,
+        ServerDisconnectedError,
+        ClientSSLError,
+        ClientConnectionError,
+    ) as err:
+        return HttpResponse(transport_error=TransportErrorDetail(type=TransportError.CONNECTION, message=str(err)))
     except Exception as err:
-        return HttpResponse(error=HttpError.ERROR, error_message=str(err))
+        return HttpResponse(transport_error=TransportErrorDetail(type=TransportError.ERROR, message=str(err)))
 
 
 async def _request_with_http_or_none_proxy(
@@ -70,9 +86,9 @@ async def _request_with_http_or_none_proxy(
     *,
     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,
+    data: dict[str, Any] | None = None,
+    json: dict[str, Any] | None = None,
+    headers: dict[str, Any] | None = None,
     cookies: LooseCookies | None = None,
     proxy: str | None = None,
     timeout: aiohttp.ClientTimeout | None,
@@ -82,9 +98,7 @@ async def _request_with_http_or_none_proxy(
     ) as res:
         return HttpResponse(
             status_code=res.status,
-            error=None,
-            error_message=None,
-            body=(await res.read()).decode(),
+            body=await res.text(),
             headers=headers_dict(res.headers),
         )
 
@@ -95,9 +109,9 @@ async def _request_with_socks_proxy(
     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,
+    data: dict[str, Any] | None = None,
+    json: dict[str, Any] | None = None,
+    headers: dict[str, Any] | None = None,
     cookies: LooseCookies | None = None,
     timeout: aiohttp.ClientTimeout | None,
 ) -> HttpResponse:
@@ -110,9 +124,7 @@ async def _request_with_socks_proxy(
     ):
         return HttpResponse(
             status_code=res.status,
-            error=None,
-            error_message=None,
-            body=(await res.read()).decode(),
+            body=await res.text(),
             headers=headers_dict(res.headers),
         )
 

{mm_http-0.1.4 → mm_http-0.2.0}/src/mm_http/http_request_sync.py

@@ -1,9 +1,17 @@
 from typing import Any
 
 import requests
-from requests.exceptions import InvalidSchema, MissingSchema, ProxyError
+from requests.exceptions import (
+    ConnectionError as RequestsConnectionError,
+)
+from requests.exceptions import (
+    InvalidSchema,
+    MissingSchema,
+    ProxyError,
+    SSLError,
+)
 
-from .response import HttpError, HttpResponse
+from .response import HttpResponse, TransportError, TransportErrorDetail
 
 
 def http_request_sync(
@@ -48,16 +56,16 @@ def http_request_sync(
         )
         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))
+        return HttpResponse(transport_error=TransportErrorDetail(type=TransportError.TIMEOUT, message=str(e)))
     except ProxyError as e:
-        return HttpResponse(error=HttpError.PROXY, error_message=str(e))
+        return HttpResponse(transport_error=TransportErrorDetail(type=TransportError.PROXY, message=str(e)))
     except (InvalidSchema, MissingSchema) as e:
-        return HttpResponse(error=HttpError.INVALID_URL, error_message=str(e))
+        return HttpResponse(transport_error=TransportErrorDetail(type=TransportError.INVALID_URL, message=str(e)))
+    except (RequestsConnectionError, SSLError) as e:
+        return HttpResponse(transport_error=TransportErrorDetail(type=TransportError.CONNECTION, message=str(e)))
     except Exception as e:
-        return HttpResponse(error=HttpError.ERROR, error_message=str(e))
+        return HttpResponse(transport_error=TransportErrorDetail(type=TransportError.ERROR, message=str(e)))

mm_http-0.2.0/src/mm_http/response.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import enum
+import json
+from typing import Any
+
+import pydash
+from mm_result import Result
+from pydantic import BaseModel, model_validator
+
+
+@enum.unique
+class TransportError(str, enum.Enum):
+    TIMEOUT = "timeout"
+    PROXY = "proxy"
+    INVALID_URL = "invalid_url"
+    CONNECTION = "connection"
+    ERROR = "error"
+
+
+class TransportErrorDetail(BaseModel):
+    """Transport error with type and message."""
+
+    type: TransportError
+    message: str
+
+
+class HttpResponse(BaseModel):
+    """HTTP response with status, body, headers, and optional transport error."""
+
+    status_code: int | None = None
+    body: str | None = None
+    headers: dict[str, str] | None = None
+    transport_error: TransportErrorDetail | None = None
+
+    @model_validator(mode="after")
+    def validate_mutually_exclusive_states(self) -> HttpResponse:
+        """Validate that response has either HTTP data or transport error, but not both."""
+        has_http_response = self.status_code is not None
+        has_transport_error = self.transport_error is not None
+
+        if has_http_response and has_transport_error:
+            msg = "Cannot have both HTTP response and transport error"
+            raise ValueError(msg)
+
+        if not has_http_response and not has_transport_error:
+            msg = "Must have either HTTP response or transport error"
+            raise ValueError(msg)
+
+        return self
+
+    def parse_json(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 get_header(self, name: str) -> str | None:
+        """Get header value (case-insensitive)."""
+        if self.headers is None:
+            return None
+        name_lower = name.lower()
+        for key, value in self.headers.items():
+            if key.lower() == name_lower:
+                return value
+        return None
+
+    def is_success(self) -> bool:
+        """Check if response has 2xx status."""
+        return self.status_code is not None and 200 <= self.status_code < 300
+
+    def is_err(self) -> bool:
+        """Check if response represents an error (has transport error or status >= 400)."""
+        return self.transport_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 with meaningful error message."""
+        if error is not None:
+            result_error = error
+        elif self.transport_error is not None:
+            result_error = self.transport_error.type
+        elif self.status_code is not None:
+            result_error = f"HTTP {self.status_code}"
+        else:
+            result_error = "error"
+        return Result.err(result_error, extra=self.model_dump(mode="json"))
+
+    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.model_dump(mode="json"))
+
+    @property
+    def content_type(self) -> str | None:
+        """Get Content-Type header value (case-insensitive)."""
+        return self.get_header("content-type")

{mm_http-0.1.4 → mm_http-0.2.0}/tests/test_http_request.py

@@ -5,19 +5,19 @@ from urllib.parse import urlencode, urlparse
 from pytest_httpserver import HTTPServer
 from werkzeug import Request, Response
 
-from mm_http import HttpError, http_request
+from mm_http import TransportError, http_request
 
 
 async def test_json_path(httpserver: HTTPServer):
     httpserver.expect_request("/test").respond_with_json({"a": {"b": {"c": 123}}})
     res = await http_request(httpserver.url_for("/test"))
-    assert res.parse_json_body("a.b.c") == 123
+    assert res.parse_json("a.b.c") == 123
 
 
 async def test_body_as_json_path_not_exists(httpserver: HTTPServer):
     httpserver.expect_request("/test").respond_with_json({"d": 1})
     res = await http_request(httpserver.url_for("/test"))
-    assert res.parse_json_body("a.b.c") is None
+    assert res.parse_json("a.b.c") is None
 
 
 async def test_body_as_json_no_body(httpserver: HTTPServer):
@@ -26,7 +26,7 @@ async def test_body_as_json_no_body(httpserver: HTTPServer):
 
     httpserver.expect_request("/test").respond_with_handler(handler)
     res = await http_request(httpserver.url_for("/test"))
-    assert res.parse_json_body("a.b.c", none_on_error=True) is None
+    assert res.parse_json("a.b.c", none_on_error=True) is None
 
 
 async def test_custom_user_agent(httpserver: HTTPServer):
@@ -36,21 +36,21 @@ async def test_custom_user_agent(httpserver: HTTPServer):
     httpserver.expect_request("/test").respond_with_handler(handler)
     user_agent = "moon cat"
     res = await http_request(httpserver.url_for("/test"), user_agent=user_agent)
-    assert res.parse_json_body()["user-agent"] == user_agent
+    assert res.parse_json()["user-agent"] == user_agent
 
 
 async def test_params(httpserver: HTTPServer):
     data = {"a": 123, "b": "bla bla"}
     httpserver.expect_request("/test", query_string="a=123&b=bla+bla").respond_with_json(data)
     res = await http_request(httpserver.url_for("/test"), params=data)
-    assert res.parse_json_body() == data
+    assert res.parse_json() == data
 
 
 async def test_post_with_params(httpserver: HTTPServer):
     data = {"a": 1}
     httpserver.expect_request("/test", query_string=urlencode(data)).respond_with_json(data)
     res = await http_request(httpserver.url_for("/test"), params=data)
-    assert res.parse_json_body() == data
+    assert res.parse_json() == data
 
 
 async def test_timeout(httpserver: HTTPServer):
@@ -60,26 +60,26 @@ async def test_timeout(httpserver: HTTPServer):
 
     httpserver.expect_request("/test").respond_with_handler(handler)
     res = await http_request(httpserver.url_for("/test"), timeout=1)
-    assert res.error == HttpError.TIMEOUT
+    assert res.transport_error.type == TransportError.TIMEOUT
 
 
 async def test_proxy_http(proxy_http: str):
     proxy = urlparse(proxy_http)
     res = await http_request("https://api.ipify.org?format=json", proxy=proxy_http, timeout=5)
-    assert proxy.hostname in res.parse_json_body()["ip"]
+    assert proxy.hostname in res.parse_json()["ip"]
 
 
 async def test_proxy_socks5(proxy_socks5):
     proxy = urlparse(proxy_socks5)
     res = await http_request("https://api.ipify.org?format=json", proxy=proxy_socks5, timeout=5)
-    assert proxy.hostname in res.parse_json_body()["ip"]
+    assert proxy.hostname in res.parse_json()["ip"]
 
 
 async def test_http_request_invalid_url() -> None:
     """Test that http_request returns INVALID_URL error for malformed URLs."""
     response = await http_request("not-a-valid-url")
-    assert response.error == HttpError.INVALID_URL
-    assert response.error_message is not None
+    assert response.transport_error.type == TransportError.INVALID_URL
+    assert response.transport_error.message is not None
     assert response.status_code is None
     assert response.body is None
     assert response.headers is None
@@ -88,8 +88,26 @@ async def test_http_request_invalid_url() -> None:
 async def test_http_request_invalid_url_with_proxy() -> None:
     """Test that http_request returns INVALID_URL error for malformed URLs even with proxy."""
     response = await http_request("not-a-valid-url", proxy="http://proxy.example.com:8080")
-    assert response.error == HttpError.INVALID_URL
-    assert response.error_message is not None
+    assert response.transport_error.type == TransportError.INVALID_URL
+    assert response.transport_error.message is not None
     assert response.status_code is None
     assert response.body is None
     assert response.headers is None
+
+
+async def test_connection_error_refused() -> None:
+    """Test CONNECTION error when port is not listening."""
+    response = await http_request("http://localhost:59999/test", timeout=2)
+    assert response.transport_error.type == TransportError.CONNECTION
+    assert response.transport_error.message is not None
+    assert response.status_code is None
+    assert response.body is None
+
+
+async def test_connection_error_dns() -> None:
+    """Test CONNECTION error when DNS resolution fails."""
+    response = await http_request("http://this-host-does-not-exist-xyz123.invalid/", timeout=5)
+    assert response.transport_error.type == TransportError.CONNECTION
+    assert response.transport_error.message is not None
+    assert response.status_code is None
+    assert response.body is None