bas-http 1.0.0__py3-none-any.whl

bas/models.py

@@ -0,0 +1,339 @@
+"""
+Request and Response data models.
+
+Clean, typed data structures for HTTP communication.
+"""
+
+import json as _json
+from typing import Any, Optional, Union
+from urllib.parse import urlparse
+
+
+class Headers(dict):
+    """
+    Case-insensitive HTTP headers container.
+
+    Mirrors the behavior of requests.structures.CaseInsensitiveDict
+    but without the dependency.
+    """
+
+    def __init__(self, data=None, **kwargs):
+        if data:
+            if isinstance(data, dict):
+                for key, value in data.items():
+                    self.__setitem__(key, value)
+            elif isinstance(data, (list, tuple)):
+                for key, value in data:
+                    self.__setitem__(key, value)
+            else:
+                for key, value in data.items():
+                    self.__setitem__(key, value)
+        for key, value in kwargs.items():
+            self.__setitem__(key, value)
+
+    def __setitem__(self, key, value):
+        super().__setitem__(key.lower(), value)
+        # Store the original case as an attribute
+        if not hasattr(self, "_original_case"):
+            self._original_case = {}
+        self._original_case[key.lower()] = key
+
+    def __getitem__(self, key):
+        return super().__getitem__(key.lower())
+
+    def __contains__(self, key):
+        return super().__contains__(key.lower())
+
+    def get(self, key, default=None):
+        return super().get(key.lower(), default)
+
+    def get_original_key(self, key):
+        """Get the original-case version of a key."""
+        if hasattr(self, "_original_case"):
+            return self._original_case.get(key.lower(), key)
+        return key
+
+    def to_original_case(self) -> dict:
+        """Return a dict with original-case keys."""
+        result = {}
+        for key, value in self.items():
+            orig_key = self.get_original_key(key)
+            result[orig_key] = value
+        return result
+
+    def title(self) -> "Headers":
+        """Return headers with keys in Title-Case (for curl)."""
+        result = Headers()
+        for key, value in self.items():
+            title_key = "-".join(w.capitalize() for w in key.split("-"))
+            result[title_key] = value
+        return result
+
+
+class PreparedRequest:
+    """
+    A fully prepared HTTP request, ready to be sent.
+
+    Contains everything needed to make the request: method, URL,
+    headers, body, and metadata.
+    """
+
+    __slots__ = (
+        "method", "url", "headers", "body", "files",
+        "json_data", "params", "auth", "cookies",
+        "_parsed_url",
+    )
+
+    def __init__(
+        self,
+        method: str = "GET",
+        url: str = "",
+        headers: Optional[Union[dict, Headers]] = None,
+        body: Optional[Union[str, bytes]] = None,
+        json_data: Optional[Any] = None,
+        params: Optional[dict] = None,
+        auth: Optional[tuple] = None,
+        cookies: Optional[dict] = None,
+    ):
+        self.method = method.upper()
+        self.url = url
+        self.headers = Headers(headers) if headers and not isinstance(headers, Headers) else (headers or Headers())
+        self.body = body
+        self.files = None
+        self.json_data = json_data
+        self.params = params
+        self.auth = auth
+        self.cookies = cookies or {}
+        self._parsed_url = None
+
+    @property
+    def parsed_url(self):
+        if self._parsed_url is None:
+            self._parsed_url = urlparse(self.url)
+        return self._parsed_url
+
+    @property
+    def scheme(self) -> str:
+        return self.parsed_url.scheme
+
+    @property
+    def host(self) -> str:
+        return self.parsed_url.hostname or ""
+
+    @property
+    def port(self) -> Optional[int]:
+        return self.parsed_url.port
+
+    @property
+    def path(self) -> str:
+        return self.parsed_url.path or "/"
+
+    @property
+    def full_path(self) -> str:
+        """Path with query string."""
+        path = self.parsed_url.path or "/"
+        if self.parsed_url.query:
+            path += "?" + self.parsed_url.query
+        return path
+
+    def prepare_body(self) -> Optional[bytes]:
+        """Prepare the request body for sending."""
+        if self.json_data is not None:
+            self.headers["Content-Type"] = "application/json"
+            return _json.dumps(self.json_data).encode("utf-8")
+
+        if self.body is not None:
+            if isinstance(self.body, str):
+                return self.body.encode("utf-8")
+            return self.body
+
+        return None
+
+    def prepare_url(self, base_url: str) -> str:
+        """
+        Prepare the full URL, resolving relative paths against base_url.
+        """
+        if self.url.startswith(("http://", "https://")):
+            return self.url
+
+        from urllib.parse import urljoin
+        return urljoin(base_url, self.url)
+
+    def clone(self) -> "PreparedRequest":
+        """Create a deep copy of this request."""
+        return PreparedRequest(
+            method=self.method,
+            url=self.url,
+            headers=Headers(dict(self.headers)),
+            body=self.body,
+            json_data=self.json_data,
+            params=dict(self.params) if self.params else None,
+            auth=self.auth,
+            cookies=dict(self.cookies) if self.cookies else None,
+        )
+
+    def __repr__(self):
+        return f"PreparedRequest(method={self.method!r}, url={self.url!r})"
+
+
+class Response:
+    """
+    An HTTP response object.
+
+    Provides access to status code, headers, body, cookies,
+    and convenience methods for content parsing.
+    """
+
+    __slots__ = (
+        "status_code", "headers", "body", "url", "request",
+        "elapsed", "encoding", "cookies", "history",
+        "http_version", "ip", "port",
+    )
+
+    def __init__(
+        self,
+        status_code: int = 0,
+        headers: Optional[Union[dict, Headers]] = None,
+        body: bytes = b"",
+        url: str = "",
+        request: Optional[PreparedRequest] = None,
+        elapsed: float = 0.0,
+        cookies=None,
+        history: Optional[list] = None,
+        http_version: str = "1.1",
+        ip: str = "",
+        port: int = 0,
+    ):
+        self.status_code = status_code
+        self.headers = Headers(headers) if headers and not isinstance(headers, Headers) else (headers or Headers())
+        self.body = body
+        self.url = url
+        self.request = request
+        self.elapsed = elapsed
+        self.encoding = self._guess_encoding()
+        self.cookies = cookies  # Will be set by session
+        self.history = history or []
+        self.http_version = http_version
+        self.ip = ip
+        self.port = port
+
+    def _guess_encoding(self) -> str:
+        """Guess encoding from Content-Type header."""
+        content_type = self.headers.get("content-type", "")
+        if "charset=" in content_type:
+            charset = content_type.split("charset=")[-1].split(";")[0].strip()
+            if charset:
+                return charset
+
+        # Check for BOM
+        if self.body.startswith(b'\xef\xbb\xbf'):
+            return 'utf-8-sig'
+        if self.body.startswith(b'\xff\xfe'):
+            return 'utf-16-le'
+        if self.body.startswith(b'\xfe\xff'):
+            return 'utf-16-be'
+
+        return 'utf-8'
+
+    @property
+    def ok(self) -> bool:
+        """True if status_code < 400."""
+        return self.status_code < 400
+
+    @property
+    def is_redirect(self) -> bool:
+        """True if this is a redirect response."""
+        return self.status_code in (301, 302, 303, 307, 308)
+
+    @property
+    def is_permanent_redirect(self) -> bool:
+        """True if this is a permanent redirect."""
+        return self.status_code in (301, 308)
+
+    @property
+    def location(self) -> Optional[str]:
+        """Get the Location header for redirects."""
+        return self.headers.get("location")
+
+    @property
+    def content_type(self) -> Optional[str]:
+        """Get the Content-Type header."""
+        return self.headers.get("content-type")
+
+    @property
+    def text(self) -> str:
+        """Decoded text content."""
+        try:
+            return self.body.decode(self.encoding)
+        except (UnicodeDecodeError, LookupError):
+            return self.body.decode("utf-8", errors="replace")
+
+    @property
+    def json(self) -> Any:
+        """Parse JSON response body."""
+        return _json.loads(self.body)
+
+    def iter_content(self, chunk_size: int = 8192):
+        """Iterate over response body in chunks."""
+        for i in range(0, len(self.body), chunk_size):
+            yield self.body[i:i + chunk_size]
+
+    def iter_lines(self, chunk_size: int = 8192, encoding: Optional[str] = None):
+        """Iterate over response body lines."""
+        enc = encoding or self.encoding
+        for chunk in self.iter_content(chunk_size):
+            for line in chunk.decode(enc, errors="replace").splitlines():
+                yield line
+
+    def raise_for_status(self) -> None:
+        """Raise an exception if the status code indicates an error."""
+        if self.status_code >= 400:
+            raise HTTPError(
+                f"{self.status_code} {self.reason_phrase} for url: {self.url}",
+                response=self,
+            )
+
+    @property
+    def reason_phrase(self) -> str:
+        """Get a human-readable reason phrase for the status code."""
+        phrases = {
+            200: "OK", 201: "Created", 204: "No Content",
+            301: "Moved Permanently", 302: "Found", 303: "See Other",
+            304: "Not Modified", 307: "Temporary Redirect",
+            308: "Permanent Redirect",
+            400: "Bad Request", 401: "Unauthorized", 403: "Forbidden",
+            404: "Not Found", 405: "Method Not Allowed",
+            429: "Too Many Requests",
+            500: "Internal Server Error", 502: "Bad Gateway",
+            503: "Service Unavailable",
+        }
+        return phrases.get(self.status_code, "Unknown")
+
+    def __repr__(self):
+        return f"<Response [{self.status_code}]>"
+
+    def __bool__(self):
+        return self.ok
+
+
+class HTTPError(Exception):
+    """Exception raised for HTTP error responses."""
+
+    def __init__(self, message: str, response: Optional[Response] = None):
+        super().__init__(message)
+        self.response = response
+
+
+class ConnectionError(Exception):
+    """Exception raised for connection failures."""
+    pass
+
+
+class Timeout(Exception):
+    """Exception raised when a request times out."""
+    pass
+
+
+class TooManyRedirects(Exception):
+    """Exception raised when redirect limit is exceeded."""
+    pass