pyhtb 0.1.0__tar.gz

pyhtb-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: pyhtb
+Version: 0.1.0
+Summary: Unofficial Hack The Box Python SDK
+Author: Hack The Box Community
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: The Unlicense (Unlicense)
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: attrs>=26.1.0
+
+# Unofficial Hack The Box (HTB) Python SDK & API Client (`pyhtb`)
+
+[![PyPI Version](https://img.shields.io/pypi/v/pyhtb.svg?color=blue)](https://pypi.org/project/pyhtb/)
+[![Supported Python Versions](https://img.shields.io/pypi/pyversions/pyhtb.svg)](https://pypi.org/project/pyhtb/)
+[![License](https://img.shields.io/github/license/goober/pyhtb.svg)](LICENSE)
+[![Code Style: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+An unofficial, modern, and type-safe Python SDK and API client wrapper for the **Hack The Box (HTB)** platform. This library exposes fully type-hinted synchronous and asynchronous interfaces to interact programmatically with HTB APIs.
+
+Whether you are automating machine status checking, managing teams, tracking starting point progression, or scripting challenge submissions, `pyhtb` provides a single unified interface.
+
+---
+
+## Key Features
+
+* **Complete API Coverage**: Seamlessly combines the HTB API `v4`, `v5`, and `experience/v1` specifications.
+* **Cookie-Simple Developer Experience**: No deep package imports or manually passing connection objects. Endpoints are dynamically bound directly onto the version clients.
+* **Modern Async & Sync Backend**: Powered by `httpx` for fast, lightweight HTTP execution with full async support out of the box.
+* **Type Safety & IDE Autocomplete**: Generated with strict model definitions utilizing `attrs` and type hints for robust code completion.
+* **Zero Overhead Boilerplate**: Authenticate once, and credentials automatically propagate across all supported API versions.
+
+---
+
+## Installation
+
+Install the package via `pip` from PyPI:
+
+```bash
+pip install pyhtb
+```
+
+For local development or running modifications, clone the repository and install in editable mode:
+
+```bash
+pip install -e .
+```
+
+---
+
+## Quick Start
+
+### 1. Basic Client Initialization
+
+Initialize the `PyHTB` client wrapper. If you want to access protected endpoints, provide your Hack The Box API token (generated on the app.hackthebox.com settings page).
+
+```python
+from pyhtb import PyHTB
+
+# Initialize authenticated SDK
+client = PyHTB(token="YOUR_HTB_API_TOKEN")
+
+# The unified client organizes endpoints by API version:
+# - client.v4
+# - client.v5
+# - client.experience_v1
+```
+
+### 2. Accessing Endpoints (v5 Example)
+
+All OpenAPI operations are dynamically bound as callable methods directly on the version clients.
+
+#### Synchronous Call
+```python
+from pyhtb import PyHTB
+
+client = PyHTB(token="YOUR_HTB_API_TOKEN")
+
+# Call any endpoint directly. Client authentication parameters are injected automatically!
+machines_response = client.v5.get_machines()
+
+for machine in machines_response.data:
+    print(f"Machine: {machine.name} | OS: {machine.os} | Difficulty: {machine.difficulty}")
+```
+
+#### Asynchronous Call
+All asynchronous methods share the same name as sync ones but are postfixed with `_async`.
+
+```python
+import asyncio
+from pyhtb import PyHTB
+
+async def main():
+    client = PyHTB(token="YOUR_HTB_API_TOKEN")
+    
+    # Asynchronous endpoint invocation
+    machines_response = await client.v5.get_machines_async()
+    
+    for machine in machines_response.data:
+        print(f"Async loaded: {machine.name}")
+
+asyncio.run(main())
+```
+
+#### Accessing Detailed Responses (Metadata & Headers)
+If you need to inspect HTTP status codes or response headers, append `_detailed` or `_async_detailed` to the method name:
+
+```python
+response = client.v5.get_machines_detailed()
+print(f"HTTP Status: {response.status_code}")
+print(f"Response Headers: {response.headers}")
+print(f"Parsed Body Model: {response.parsed}")
+```
+
+---
+
+## Supported APIs and Specs
+
+The SDK is compiled from official and community-maintained reverse-engineered OpenAPI specifications:
+
+| Version | Description | Target Submodule |
+| :--- | :--- | :--- |
+| **API v4** | Primary platform endpoints (User, Teams, Challenges, Tracks, etc.) | `client.v4` |
+| **API v5** | Modern dashboard & user activity endpoints (Machines status, University, User dashboard) | `client.v5` |
+| **Experience v1** | Experience, Levels, and Streak endpoints | `client.experience_v1` |
+
+---
+
+## Code Regeneration
+
+The SDK contains a build pipeline to automatically compile clients from raw OpenAPI YAML specs. To regenerate the submodules after modifying any specification, execute:
+
+```bash
+./api/regen.sh
+```
+
+This requires `openapi-python-client` to be installed in your active Python environment.

pyhtb-0.1.0/README.md

@@ -0,0 +1,126 @@
+# Unofficial Hack The Box (HTB) Python SDK & API Client (`pyhtb`)
+
+[![PyPI Version](https://img.shields.io/pypi/v/pyhtb.svg?color=blue)](https://pypi.org/project/pyhtb/)
+[![Supported Python Versions](https://img.shields.io/pypi/pyversions/pyhtb.svg)](https://pypi.org/project/pyhtb/)
+[![License](https://img.shields.io/github/license/goober/pyhtb.svg)](LICENSE)
+[![Code Style: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+An unofficial, modern, and type-safe Python SDK and API client wrapper for the **Hack The Box (HTB)** platform. This library exposes fully type-hinted synchronous and asynchronous interfaces to interact programmatically with HTB APIs.
+
+Whether you are automating machine status checking, managing teams, tracking starting point progression, or scripting challenge submissions, `pyhtb` provides a single unified interface.
+
+---
+
+## Key Features
+
+* **Complete API Coverage**: Seamlessly combines the HTB API `v4`, `v5`, and `experience/v1` specifications.
+* **Cookie-Simple Developer Experience**: No deep package imports or manually passing connection objects. Endpoints are dynamically bound directly onto the version clients.
+* **Modern Async & Sync Backend**: Powered by `httpx` for fast, lightweight HTTP execution with full async support out of the box.
+* **Type Safety & IDE Autocomplete**: Generated with strict model definitions utilizing `attrs` and type hints for robust code completion.
+* **Zero Overhead Boilerplate**: Authenticate once, and credentials automatically propagate across all supported API versions.
+
+---
+
+## Installation
+
+Install the package via `pip` from PyPI:
+
+```bash
+pip install pyhtb
+```
+
+For local development or running modifications, clone the repository and install in editable mode:
+
+```bash
+pip install -e .
+```
+
+---
+
+## Quick Start
+
+### 1. Basic Client Initialization
+
+Initialize the `PyHTB` client wrapper. If you want to access protected endpoints, provide your Hack The Box API token (generated on the app.hackthebox.com settings page).
+
+```python
+from pyhtb import PyHTB
+
+# Initialize authenticated SDK
+client = PyHTB(token="YOUR_HTB_API_TOKEN")
+
+# The unified client organizes endpoints by API version:
+# - client.v4
+# - client.v5
+# - client.experience_v1
+```
+
+### 2. Accessing Endpoints (v5 Example)
+
+All OpenAPI operations are dynamically bound as callable methods directly on the version clients.
+
+#### Synchronous Call
+```python
+from pyhtb import PyHTB
+
+client = PyHTB(token="YOUR_HTB_API_TOKEN")
+
+# Call any endpoint directly. Client authentication parameters are injected automatically!
+machines_response = client.v5.get_machines()
+
+for machine in machines_response.data:
+    print(f"Machine: {machine.name} | OS: {machine.os} | Difficulty: {machine.difficulty}")
+```
+
+#### Asynchronous Call
+All asynchronous methods share the same name as sync ones but are postfixed with `_async`.
+
+```python
+import asyncio
+from pyhtb import PyHTB
+
+async def main():
+    client = PyHTB(token="YOUR_HTB_API_TOKEN")
+    
+    # Asynchronous endpoint invocation
+    machines_response = await client.v5.get_machines_async()
+    
+    for machine in machines_response.data:
+        print(f"Async loaded: {machine.name}")
+
+asyncio.run(main())
+```
+
+#### Accessing Detailed Responses (Metadata & Headers)
+If you need to inspect HTTP status codes or response headers, append `_detailed` or `_async_detailed` to the method name:
+
+```python
+response = client.v5.get_machines_detailed()
+print(f"HTTP Status: {response.status_code}")
+print(f"Response Headers: {response.headers}")
+print(f"Parsed Body Model: {response.parsed}")
+```
+
+---
+
+## Supported APIs and Specs
+
+The SDK is compiled from official and community-maintained reverse-engineered OpenAPI specifications:
+
+| Version | Description | Target Submodule |
+| :--- | :--- | :--- |
+| **API v4** | Primary platform endpoints (User, Teams, Challenges, Tracks, etc.) | `client.v4` |
+| **API v5** | Modern dashboard & user activity endpoints (Machines status, University, User dashboard) | `client.v5` |
+| **Experience v1** | Experience, Levels, and Streak endpoints | `client.experience_v1` |
+
+---
+
+## Code Regeneration
+
+The SDK contains a build pipeline to automatically compile clients from raw OpenAPI YAML specs. To regenerate the submodules after modifying any specification, execute:
+
+```bash
+./api/regen.sh
+```
+
+This requires `openapi-python-client` to be installed in your active Python environment.

pyhtb-0.1.0/pyhtb/__init__.py

@@ -0,0 +1,139 @@
+import pkgutil
+import importlib
+import functools
+from typing import Optional
+import httpx
+
+from .v4.client import AuthenticatedClient as AuthenticatedClientV4Gen, Client as ClientV4Gen
+from .v5.client import AuthenticatedClient as AuthenticatedClientV5Gen, Client as ClientV5Gen
+from .experience.v1.client import AuthenticatedClient as AuthenticatedClientV1Gen, Client as ClientV1Gen
+
+# Import the API modules for binding
+from .v4 import api as api_v4
+from .v5 import api as api_v5
+from .experience.v1 import api as api_exp_v1
+
+# Subclass the generated clients so they support dynamic attribute/method binding
+# (since attrs classes with slots=True don't have a __dict__ by default)
+class ClientV4(ClientV4Gen):
+    pass
+
+class AuthenticatedClientV4(AuthenticatedClientV4Gen):
+    pass
+
+class ClientV5(ClientV5Gen):
+    pass
+
+class AuthenticatedClientV5(AuthenticatedClientV5Gen):
+    pass
+
+class ClientV1(ClientV1Gen):
+    pass
+
+class AuthenticatedClientV1(AuthenticatedClientV1Gen):
+    pass
+
+def _bind_api_methods(client_instance, api_package):
+    """
+    Dynamically scans an API subpackage and attaches its endpoints as methods
+    directly on the client instance, automatically injecting the client parameter.
+    """
+    for _, module_name, is_pkg in pkgutil.walk_packages(api_package.__path__, api_package.__name__ + "."):
+        if is_pkg:
+            continue
+        try:
+            mod = importlib.import_module(module_name)
+        except Exception:
+            continue
+        
+        endpoint_name = module_name.split(".")[-1]
+        
+        # We bind the following:
+        # - sync -> client.endpoint_name()
+        # - sync_detailed -> client.endpoint_name_detailed()
+        # - asyncio -> client.endpoint_name_async()
+        # - asyncio_detailed -> client.endpoint_name_async_detailed()
+        for attr_name, bound_name in [
+            ("sync", endpoint_name),
+            ("asyncio", f"{endpoint_name}_async"),
+            ("sync_detailed", f"{endpoint_name}_detailed"),
+            ("asyncio_detailed", f"{endpoint_name}_async_detailed"),
+        ]:
+            func = getattr(mod, attr_name, None)
+            if func and callable(func):
+                def make_wrapper(f):
+                    @functools.wraps(f)
+                    def wrapper(*args, **kwargs):
+                        kwargs["client"] = client_instance
+                        return f(*args, **kwargs)
+                    return wrapper
+
+                setattr(client_instance, bound_name, make_wrapper(func))
+
+class PyHTB:
+    """
+    Main entrypoint wrapper for the Hack The Box Python SDK.
+    Manages API clients for:
+    - v4 (via client.v4)
+    - v5 (via client.v5)
+    - experience/v1 (via client.experience_v1)
+
+    All generated endpoints are bound directly as methods on the client instances
+    so you don't need to import them manually or pass the client parameter.
+    For example:
+        client = PyHTB(token="my_token")
+        machines = client.v5.get_machines()
+    """
+    def __init__(
+        self,
+        token: Optional[str] = None,
+        base_url_v4: str = "https://labs.hackthebox.com/api/v4",
+        base_url_v5: str = "https://labs.hackthebox.com/api/v5",
+        base_url_experience_v1: str = "https://labs.hackthebox.com/api/experience/v1",
+        timeout: Optional[float] = None,
+        verify_ssl: bool = True,
+    ):
+        httpx_timeout = httpx.Timeout(timeout) if timeout is not None else None
+
+        if token:
+            self.v4 = AuthenticatedClientV4(
+                base_url=base_url_v4,
+                token=token,
+                timeout=httpx_timeout,
+                verify_ssl=verify_ssl,
+            )
+            self.v5 = AuthenticatedClientV5(
+                base_url=base_url_v5,
+                token=token,
+                timeout=httpx_timeout,
+                verify_ssl=verify_ssl,
+            )
+            self.experience_v1 = AuthenticatedClientV1(
+                base_url=base_url_experience_v1,
+                token=token,
+                timeout=httpx_timeout,
+                verify_ssl=verify_ssl,
+            )
+        else:
+            self.v4 = ClientV4(
+                base_url=base_url_v4,
+                timeout=httpx_timeout,
+                verify_ssl=verify_ssl,
+            )
+            self.v5 = ClientV5(
+                base_url=base_url_v5,
+                timeout=httpx_timeout,
+                verify_ssl=verify_ssl,
+            )
+            self.experience_v1 = ClientV1(
+                base_url=base_url_experience_v1,
+                timeout=httpx_timeout,
+                verify_ssl=verify_ssl,
+            )
+
+        # Bind API methods directly to client instances for ultimate developer simplicity
+        _bind_api_methods(self.v4, api_v4)
+        _bind_api_methods(self.v5, api_v5)
+        _bind_api_methods(self.experience_v1, api_exp_v1)
+
+__all__ = ["PyHTB"]

pyhtb-0.1.0/pyhtb/experience/v1/__init__.py

@@ -0,0 +1,8 @@
+"""A client library for accessing HTB Unofficial API experience/v1"""
+
+from .client import AuthenticatedClient, Client
+
+__all__ = (
+    "AuthenticatedClient",
+    "Client",
+)

pyhtb-0.1.0/pyhtb/experience/v1/api/__init__.py

@@ -0,0 +1 @@
+"""Contains methods for accessing the API"""

pyhtb-0.1.0/pyhtb/experience/v1/api/account/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""

pyhtb-0.1.0/pyhtb/experience/v1/api/account/get_account_account_id.py

@@ -0,0 +1,168 @@
+from http import HTTPStatus
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from ... import errors
+from ...client import AuthenticatedClient, Client
+from ...models.account_response import AccountResponse
+from ...models.generic_error_response import GenericErrorResponse
+from ...types import Response
+
+
+def _get_kwargs(
+    account_id: str,
+) -> dict[str, Any]:
+    _kwargs: dict[str, Any] = {
+        "method": "get",
+        "url": "/account/{account_id}".format(
+            account_id=quote(str(account_id), safe=""),
+        ),
+    }
+
+    return _kwargs
+
+
+def _parse_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> AccountResponse | GenericErrorResponse | None:
+    if response.status_code == 200:
+        response_200 = AccountResponse.from_dict(response.json())
+
+        return response_200
+
+    if response.status_code == 400:
+        response_400 = GenericErrorResponse.from_dict(response.json())
+
+        return response_400
+
+    if client.raise_on_unexpected_status:
+        raise errors.UnexpectedStatus(response.status_code, response.content)
+    else:
+        return None
+
+
+def _build_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> Response[AccountResponse | GenericErrorResponse]:
+    return Response(
+        status_code=HTTPStatus(response.status_code),
+        content=response.content,
+        headers=response.headers,
+        parsed=_parse_response(client=client, response=response),
+    )
+
+
+def sync_detailed(
+    account_id: str,
+    *,
+    client: AuthenticatedClient | Client,
+) -> Response[AccountResponse | GenericErrorResponse]:
+    """Get Account
+
+     Account
+
+    Args:
+        account_id (str):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[AccountResponse | GenericErrorResponse]
+    """
+
+    kwargs = _get_kwargs(
+        account_id=account_id,
+    )
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+
+def sync(
+    account_id: str,
+    *,
+    client: AuthenticatedClient | Client,
+) -> AccountResponse | GenericErrorResponse | None:
+    """Get Account
+
+     Account
+
+    Args:
+        account_id (str):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        AccountResponse | GenericErrorResponse
+    """
+
+    return sync_detailed(
+        account_id=account_id,
+        client=client,
+    ).parsed
+
+
+async def asyncio_detailed(
+    account_id: str,
+    *,
+    client: AuthenticatedClient | Client,
+) -> Response[AccountResponse | GenericErrorResponse]:
+    """Get Account
+
+     Account
+
+    Args:
+        account_id (str):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[AccountResponse | GenericErrorResponse]
+    """
+
+    kwargs = _get_kwargs(
+        account_id=account_id,
+    )
+
+    response = await client.get_async_httpx_client().request(**kwargs)
+
+    return _build_response(client=client, response=response)
+
+
+async def asyncio(
+    account_id: str,
+    *,
+    client: AuthenticatedClient | Client,
+) -> AccountResponse | GenericErrorResponse | None:
+    """Get Account
+
+     Account
+
+    Args:
+        account_id (str):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        AccountResponse | GenericErrorResponse
+    """
+
+    return (
+        await asyncio_detailed(
+            account_id=account_id,
+            client=client,
+        )
+    ).parsed