hakiapi 1.0.0__tar.gz

hakiapi-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gugilla-Aakash
+
+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.

hakiapi-1.0.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: hakiapi
+Version: 1.0.0
+Summary: A modern Python framework for building clean, typed, and extensible API clients.
+Author-email: Gugilla Aakash <gugillaaakash6@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Gugilla-Aakash/hakiapi
+Project-URL: Source Code, https://github.com/Gugilla-Aakash/hakiapi
+Project-URL: Bug Tracker, https://github.com/Gugilla-Aakash/hakiapi/issues
+Keywords: api-client,retry,pagination,rest-api,http
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.32.0
+Requires-Dist: urllib3>=1.26.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: responses; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# HakiAPI
+
+> A modern, typed, and extensible Python framework for building resilient API clients.
+
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+---
+
+## 🚀 Vision
+
+HakiAPI aims to make building Python SDKs simple, consistent, and developer-friendly by providing reusable components for:
+
+- Authentication
+- Automatic retries
+- Request handling
+- Pagination
+- Error management
+- Typed API clients
+
+---
+
+## ✨ Current Features
+
+- ✅ Custom exception hierarchy
+- ✅ Configurable retry adapter
+- ✅ Authentication
+- ✅ Base API client
+- ✅ Pagination
+- 🚧 Built-in API clients (in progress)
+
+---
+
+## 📄 License
+
+Released under the MIT License.

hakiapi-1.0.0/README.md

@@ -0,0 +1,36 @@
+# HakiAPI
+
+> A modern, typed, and extensible Python framework for building resilient API clients.
+
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+---
+
+## 🚀 Vision
+
+HakiAPI aims to make building Python SDKs simple, consistent, and developer-friendly by providing reusable components for:
+
+- Authentication
+- Automatic retries
+- Request handling
+- Pagination
+- Error management
+- Typed API clients
+
+---
+
+## ✨ Current Features
+
+- ✅ Custom exception hierarchy
+- ✅ Configurable retry adapter
+- ✅ Authentication
+- ✅ Base API client
+- ✅ Pagination
+- 🚧 Built-in API clients (in progress)
+
+---
+
+## 📄 License
+
+Released under the MIT License.

hakiapi-1.0.0/hakiapi/clients/github.py

@@ -0,0 +1,74 @@
+from typing import Any, Iterator
+
+from hakiapi.core.base_client import BaseAPIClient
+from hakiapi.core.auth import BearerTokenAuth
+from hakiapi.core.paginator import paginate
+
+
+class GitHubClient(BaseAPIClient):
+    def __init__(self, token: str | None = None, **kwargs: Any) -> None:
+        auth_obj = BearerTokenAuth(token) if token else None
+
+        super().__init__(
+            base_url="https://api.github.com",
+            auth=auth_obj,
+            **kwargs,
+        )
+
+        self.session.headers.update(
+            {
+                "Accept": "application/vnd.github+json",
+                "X-GitHub-Api-Version": "2022-11-28",
+                "User-Agent": "HakiAPI/0.1.0",
+            }
+        )
+
+    def get_user(self, username: str, **kwargs: Any) -> dict[str, Any]:
+        """Fetch a GitHub user's profile."""
+        return self.get(f"users/{username}", **kwargs)
+
+    def get_user_repos(self, username: str, **kwargs: Any) -> list[dict[str, Any]]:
+        """Fetch a single page of public repositories of a GitHub user."""
+        return self.get(f"users/{username}/repos", **kwargs)
+
+    def get_all_user_repos(
+        self, username: str, **kwargs: Any
+    ) -> Iterator[dict[str, Any]]:
+        """Fetch ALL public repositories using automatic pagination."""
+        return paginate(self, f"users/{username}/repos", **kwargs)
+
+    def get_repo_languages(
+        self, owner: str, repo: str, **kwargs: Any
+    ) -> dict[str, int]:
+        """Fetch the exact byte breakdown of all languages used in a specific repository."""
+        return self.get(f"repos/{owner}/{repo}/languages", **kwargs)
+
+    def get_aggregate_user_languages(
+        self, username: str, **kwargs: Any
+    ) -> dict[str, int]:
+        """
+        Iterate through all of a user's repositories and get a repository-independent
+        map of all languages used, down to the smallest byte.
+        """
+        aggregate_languages: dict[str, int] = {}
+
+        # Pull all repos lazily via our paginator engine
+        repos = self.get_all_user_repos(username, **kwargs)
+
+        for repo in repos:
+            repo_name = repo.get("name")
+            if not repo_name:
+                continue
+
+            try:
+                # Query the specific byte-breakdown for this exact repo pointer
+                languages = self.get_repo_languages(username, repo_name)
+                for lang, bytes_count in languages.items():
+                    aggregate_languages[lang] = (
+                        aggregate_languages.get(lang, 0) + bytes_count
+                    )
+            except Exception:
+                # Shield the iteration sequence if a single repo is deleted or inaccessible
+                continue
+
+        return aggregate_languages

hakiapi-1.0.0/hakiapi/core/auth.py

@@ -0,0 +1,123 @@
+import hashlib
+import hmac
+import time
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+from requests.auth import AuthBase
+from requests import PreparedRequest
+
+
+class BearerTokenAuth(AuthBase):
+    """Authenticate using a Bearer token."""
+
+    def __init__(self, token: str) -> None:
+        self.token = token
+
+    def __call__(self, r: PreparedRequest) -> PreparedRequest:
+        r.headers["Authorization"] = f"Bearer {self.token}"
+        return r
+
+
+class HeaderApiKeyAuth(AuthBase):
+    """Authenticate using a custom API key header."""
+
+    def __init__(self, header_name: str, api_key: str) -> None:
+        self.header_name = header_name
+        self.api_key = api_key
+
+    def __call__(self, r: PreparedRequest) -> PreparedRequest:
+        r.headers[self.header_name] = self.api_key
+        return r
+
+
+class QueryApiKeyAuth(AuthBase):
+    """Authenticate by appending an API key as a query parameter."""
+
+    def __init__(self, param_name: str, api_key: str) -> None:
+        self.param_name = param_name
+        self.api_key = api_key
+
+    def __call__(self, r: PreparedRequest) -> PreparedRequest:
+        if not r.url:
+            return r
+
+        parts = urlsplit(r.url)
+
+        # Maintain as list of tuples to avoid dropping duplicate keys
+        query_params = parse_qsl(parts.query, keep_blank_values=True)
+        query_params.append((self.param_name, self.api_key))
+
+        r.url = urlunsplit(
+            (
+                parts.scheme,
+                parts.netloc,
+                parts.path,
+                urlencode(query_params),
+                parts.fragment,
+            )
+        )
+
+        return r
+
+
+class HmacAuth(AuthBase):
+    """
+    Authenticate requests using HMAC-SHA256 signatures.
+
+    The signature is generated from the HTTP method,
+    request path, timestamp, and request body.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        secret_key: str,
+        api_key_header: str = "X-API-Key",
+        signature_header: str = "X-Signature",
+        timestamp_header: str = "X-Timestamp",
+    ) -> None:
+        self.api_key = api_key
+        self.secret_key = secret_key.encode()
+        self.api_key_header = api_key_header
+        self.signature_header = signature_header
+        self.timestamp_header = timestamp_header
+
+    def __call__(self, r: PreparedRequest) -> PreparedRequest:
+        timestamp = str(int(time.time()))
+
+        body = r.body
+
+        if body is None:
+            body_bytes = b""
+        elif isinstance(body, bytes):
+            body_bytes = body
+        elif isinstance(body, str):
+            body_bytes = body.encode()
+        else:
+            raise TypeError("Streaming request bodies are not supported.")
+
+        if not r.method:
+            raise ValueError("Cannot sign a request with no HTTP method set.")
+
+        method = r.method.upper()
+        path_url = getattr(r, "path_url", "/")
+
+        message = b"\n".join(
+            [
+                method.encode(),
+                path_url.encode(),
+                timestamp.encode(),
+                body_bytes,
+            ]
+        )
+
+        signature = hmac.new(
+            self.secret_key,
+            message,
+            hashlib.sha256,
+        ).hexdigest()
+
+        r.headers[self.api_key_header] = self.api_key
+        r.headers[self.timestamp_header] = timestamp
+        r.headers[self.signature_header] = signature
+
+        return r

hakiapi-1.0.0/hakiapi/core/base_client.py

@@ -0,0 +1,133 @@
+import requests
+from typing import Any, TypeVar
+from requests.auth import AuthBase
+
+from .retry import create_retry_adapter
+from .exceptions import (
+    HakiAPIError,
+    ClientError,
+    ServerError,
+    RateLimitError,
+    AuthenticationError,
+    RequestTimeoutError,
+)
+
+T = TypeVar("T", bound="BaseAPIClient")
+
+
+class BaseAPIClient:
+    def __init__(
+        self,
+        base_url: str,
+        auth: AuthBase | tuple[str, str] | None = None,
+        timeout: float = 10.0,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+        self.session = requests.Session()
+
+        if auth is not None:
+            self.session.auth = auth
+
+        adapter = create_retry_adapter()
+        self.session.mount("http://", adapter)
+        self.session.mount("https://", adapter)
+
+    def close(self) -> None:
+        self.session.close()
+
+    def __enter__(self: T) -> T:
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self.close()
+
+    def _request(
+        self, method: str, endpoint: str, raw_response: bool = False, **kwargs: Any
+    ) -> Any:
+        full_url = f"{self.base_url}/{endpoint.lstrip('/')}"
+
+        # Safely extract timeout to pass to the exception engine if needed
+        request_timeout = kwargs.pop("timeout", self.timeout)
+
+        try:
+            response = self.session.request(
+                method=method,
+                url=full_url,
+                timeout=request_timeout,
+                **kwargs,
+            )
+
+        except requests.exceptions.Timeout as e:
+            raise RequestTimeoutError(
+                message="Request timed out.",
+                timeout_duration=float(request_timeout) if request_timeout else None,
+            ) from e
+
+        except requests.exceptions.RequestException as e:
+            raise HakiAPIError(message=str(e)) from e
+
+        # Rate limiting
+        if response.status_code == 429:
+            retry_after_str = response.headers.get("Retry-After")
+            retry_after = None
+            if retry_after_str:
+                try:
+                    retry_after = float(retry_after_str)
+                except ValueError:
+                    pass  # Ignore HTTP date formats; fallback to None
+
+            raise RateLimitError(
+                message="Rate limit exceeded.",
+                status_code=response.status_code,
+                retry_after=retry_after,
+                response=response,
+            )
+
+        # Authentication
+        if response.status_code in (401, 403):
+            raise AuthenticationError(
+                message="Authentication failed.",
+                status_code=response.status_code,
+                response=response,
+            )
+
+        # Client errors
+        if 400 <= response.status_code < 500:
+            raise ClientError(
+                message=f"HTTP {response.status_code} Client Error",
+                status_code=response.status_code,
+                response=response,
+            )
+
+        # Server errors
+        if response.status_code >= 500:
+            raise ServerError(
+                message=f"HTTP {response.status_code} Server Error",
+                status_code=response.status_code,
+                response=response,
+            )
+
+        if raw_response:
+            return response
+
+        try:
+            return response.json()
+        except ValueError:
+            return response.text
+
+    def get(self, endpoint: str, **kwargs: Any) -> Any:
+        return self._request("GET", endpoint, **kwargs)
+
+    def post(self, endpoint: str, **kwargs: Any) -> Any:
+        return self._request("POST", endpoint, **kwargs)
+
+    def put(self, endpoint: str, **kwargs: Any) -> Any:
+        return self._request("PUT", endpoint, **kwargs)
+
+    def delete(self, endpoint: str, **kwargs: Any) -> Any:
+        return self._request("DELETE", endpoint, **kwargs)
+
+    def patch(self, endpoint: str, **kwargs: Any) -> Any:
+        return self._request("PATCH", endpoint, **kwargs)

hakiapi-1.0.0/hakiapi/core/exceptions.py

@@ -0,0 +1,70 @@
+from typing import Any
+
+
+class HakiAPIError(Exception):
+    """Base exception for all Haki API errors."""
+
+    def __init__(
+        self, message: str, status_code: int | None = None, response: Any | None = None
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.response = response
+
+    def __str__(self) -> str:
+        if self.status_code:
+            return f"[{self.status_code}] {self.message}"
+        return self.message
+
+
+class ClientError(HakiAPIError):
+    """Raised when the API returns a 4xx status code."""
+
+    pass
+
+
+class ServerError(HakiAPIError):
+    """Raised when the API returns a 5xx status code."""
+
+    pass
+
+
+class RateLimitError(ClientError):
+    """Raised for HTTP 429 Too Many Requests."""
+
+    def __init__(
+        self,
+        message: str,
+        retry_after: int | float | None = None,
+        status_code: int | None = 429,
+        response: Any | None = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, response=response)
+        self.retry_after = retry_after
+
+
+class AuthenticationError(ClientError):
+    """Raised for HTTP 401 Unauthorized and 403 Forbidden."""
+
+    def __init__(
+        self,
+        message: str,
+        auth_method: str | None = None,
+        status_code: int | None = None,
+        response: Any | None = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, response=response)
+        self.auth_method = auth_method
+
+
+class RequestTimeoutError(HakiAPIError):
+    """
+    Raised when a request times out at the network level.
+    Inherits directly from base, as timeouts lack HTTP status codes.
+    """
+
+    def __init__(self, message: str, timeout_duration: float | None = None) -> None:
+        # Status code and response are explicitly None for network timeouts
+        super().__init__(message, status_code=None, response=None)
+        self.timeout_duration = timeout_duration

hakiapi-1.0.0/hakiapi/core/paginator.py

@@ -0,0 +1,93 @@
+from typing import Any, Iterator
+from urllib.parse import parse_qsl, urlparse
+
+from .base_client import BaseAPIClient
+
+
+def paginate(
+    client: BaseAPIClient, endpoint: str, max_pages: int | None = None, **kwargs: Any
+) -> Iterator[Any]:
+    """
+    Fetches all pages from APIs that use different pagination methods,
+    figuring out which one to use based on the response.
+
+    Supported pagination styles:
+
+    1. Link header pagination (used by APIs like GitHub)
+    - Looks for a `next` link in the HTTP `Link` header.
+    - Each response is expected to be a JSON list.
+
+    2. Token-based pagination (used by APIs like Twitter/X API v2)
+    - Reads `meta.next_token` from the response body.
+    - Requests the next page by sending the same endpoint with the
+     updated `pagination_token` query parameter.
+    - Responses are expected to look like:
+     {"data": [...], "meta": {"next_token": "..."}}
+
+    If a `next` link is available, it takes priority. Otherwise, the
+    paginator checks for a `next_token`. If neither is found, there are
+    no more pages to fetch.
+    """
+
+    # Extract initial params and ensure they are a list of tuples
+    # to prevent dropping duplicate keys.
+    raw_params = kwargs.pop("params", None) or {}
+    if isinstance(raw_params, dict):
+        params = list(raw_params.items())
+    else:
+        params = list(raw_params)
+
+    pages_fetched = 0
+
+    while endpoint:
+        # Safety valve: Prevent infinite loops caused by API routing bugs
+        if max_pages is not None and pages_fetched >= max_pages:
+            break
+
+        response = client._request(
+            "GET",
+            endpoint,
+            raw_response=True,
+            params=params or None,
+            **kwargs,
+        )
+
+        pages_fetched += 1
+        data = response.json()
+
+        if isinstance(data, list):
+            items = data
+        elif isinstance(data, dict) and isinstance(data.get("data"), list):
+            items = data["data"]
+        else:
+            raise ValueError(
+                "Paginator expected a list response, or a dict with a "
+                "'data' list (e.g. {'data': [...]})."
+            )
+
+        for item in items:
+            yield item
+
+        # RFC 5988 Link header (GitHub-style)
+        if "next" in response.links:
+            next_url = response.links["next"]["url"]
+            parsed = urlparse(next_url)
+
+            # Strictly extract only the path to prevent query string duplication
+            # in requests, and completely bypass brittle base_url prefix matching.
+            endpoint = parsed.path.lstrip("/")
+            params = parse_qsl(parsed.query) if parsed.query else []
+            continue
+
+        # cursor/token pagination (Twitter-style)
+        next_token = (
+            data.get("meta", {}).get("next_token") if isinstance(data, dict) else None
+        )
+
+        if next_token:
+            # Filters out the old pagination_token tuple, then append the new one
+            params = [(k, v) for k, v in params if k != "pagination_token"]
+            params.append(("pagination_token", next_token))
+            continue
+
+        break

hakiapi-1.0.0/hakiapi/core/retry.py

@@ -0,0 +1,28 @@
+from typing import Collection
+
+from requests.adapters import HTTPAdapter
+from urllib3.util import Retry
+
+
+def create_retry_adapter(
+    total_retries: int = 3,
+    backoff_factor: float = 1.0,
+    status_forcelist: Collection[int] | None = None,
+    allowed_methods: Collection[str] | None = None,
+) -> HTTPAdapter:
+    """
+    Creates an HTTPAdapter configured with exponential backoff and retry behavior.
+    """
+
+    if status_forcelist is None:
+        status_forcelist = [429, 500, 502, 503, 504]
+
+    retry_strategy = Retry(
+        total=total_retries,
+        backoff_factor=backoff_factor,
+        status_forcelist=status_forcelist,
+        allowed_methods=allowed_methods,  # Explicitly expose method filtering
+        raise_on_status=False,  # Defer error handling to HakiAPI exceptions
+    )
+
+    return HTTPAdapter(max_retries=retry_strategy)