pyardent 1.0.0__tar.gz

pyardent-1.0.0/LICENSE.md

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

pyardent-1.0.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: pyardent
+Version: 1.0.0
+Summary: Python client for the Ardent Insight API (Elite Dangerous trade/system data)
+Author: ProsD
+Author-email: ProsD <me@prosd.dev>
+License-Expression: MIT
+License-File: LICENSE.md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic==2.13.5
+Requires-Python: >=3.12
+Project-URL: Issues, https://github.com/ProsD03/pyardent/issues
+Project-URL: Repository, https://github.com/ProsD03/pyardent
+Description-Content-Type: text/markdown
+
+# pyardent
+
+[![PyPI version](https://badge.fury.io/py/pyardent.svg)](https://badge.fury.io/py/pyardent)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.md)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](pyproject.toml)
+[![Type Check](https://github.com/ProsD03/pyardent/actions/workflows/type_check.yml/badge.svg)](https://github.com/ProsD03/pyardent/actions/workflows/type_check.yml)
+[![Tests badge](https://raw.githubusercontent.com/ProsD03/pyardent/tests-badge-data/tests-badge.svg)](https://github.com/ProsD03/pyardent/actions/workflows/tests.yml)
+[![Coverage badge](https://raw.githubusercontent.com/ProsD03/pyardent/python-coverage-comment-action-data/badge.svg)](https://github.com/ProsD03/pyardent/tree/python-coverage-comment-action-data)
+
+A Python client for the [Ardent Insight](https://ardent-insight.com) API: trade and system data for Elite Dangerous.
+
+Built on `httpx` and `pydantic`, fully type-hinted (ships a `py.typed` marker), with zero runtime dependencies beyond those two.
+
+## Installation
+
+```bash
+pip install pyardent
+```
+
+Requires Python 3.12+.
+
+## Quickstart
+
+```python
+from pyardent import ArdentClient
+
+client = ArdentClient()
+
+gold = client.commodity.get_by_name("gold")
+print(gold)
+#> commodity_name='gold' rare=False rare_station_id=None rare_max_count=None min_buy_price=3800 ...
+
+
+sol = client.system.get_by_name("Sol")
+stations = sol.get_stations()
+lincoln = next(s for s in stations if s.station_name == "Abraham Lincoln")
+print(lincoln)
+#> system_address=10477373803 station_id=128016896 station_name='Abraham Lincoln' ...
+```
+
+## Why pyardent
+
+Models aren't flat DTOs: they carry a reference back to the client, so you can traverse straight from one resource to another without manually threading IDs through further calls:
+
+```python
+gold = client.commodity.get_by_name("gold")
+
+# Where can I sell gold for at least 50,000 credits, near Sol?
+sol = client.system.get_by_name("Sol")
+buyers = gold.get_nearby_importers(sol, min_price=50_000, max_distance=50)
+
+for order in buyers:
+    station = order.get_station()  # one more hop, still through the same client
+    print(station.station_name, order.sell_price)
+```
+
+This graph-traversal pattern is consistent across the library: `System.get_stations()`, `Station.get_full_details()`, `Commodity.get_exporters()`, `CommodityMarket.get_station()`, and more.
+
+## Error handling
+
+Failed requests raise a typed exception instead of a bare `httpx.HTTPStatusError`:
+
+```python
+from pyardent import ArdentClient, SystemNotFoundError
+
+client = ArdentClient()
+
+try:
+    client.system.get_by_name("Not A Real System")
+except SystemNotFoundError:
+    ...
+```
+
+All exceptions inherit from `PyArdentError`; more specific subclasses (`CommodityNotFoundError`, `ServiceNotFoundError`, `ResourceNotFoundError`) are raised where the API's error response is specific enough to tell them apart.
+
+## Features
+
+- Full pydantic models for every major resource: `System`, `Station`, `Commodity`, `CommodityMarket`
+- Graph-traversal methods to move between related resources without re-fetching by hand
+- A typed exception hierarchy instead of raw HTTP errors
+- Custom `base_url` support, for pointing at a self-hosted or staging Ardent deployment
+- Fully typed public API (`py.typed` included, so your type checker sees real types, not `Any`)
+
+## Development
+
+This project uses [`uv`](https://docs.astral.sh/uv/) for dependency management.
+
+```bash
+uv sync                                                        # install dependencies
+uv run pytest                                                  # run tests
+uv run pytest --cov=src/pyardent --cov-report=term-missing     # run tests with coverage
+uv run mypy src                                                # type check
+```
+
+Contributions are welcome. Please make sure the commands above are clean before opening a pull request.
+
+## AI Usage Disclosure
+
+AI assistance (Claude Code) was used for parts of this project: documentation, the test suite, and general bug fixing.
+
+The research into Ardent Insight's documented and undocumented API surface, the overall structure of the library, and most of the core implementation were written by hand.
+
+## License
+
+MIT. See [LICENSE.md](LICENSE.md) for details.

pyardent-1.0.0/README.md

@@ -0,0 +1,105 @@
+# pyardent
+
+[![PyPI version](https://badge.fury.io/py/pyardent.svg)](https://badge.fury.io/py/pyardent)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.md)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](pyproject.toml)
+[![Type Check](https://github.com/ProsD03/pyardent/actions/workflows/type_check.yml/badge.svg)](https://github.com/ProsD03/pyardent/actions/workflows/type_check.yml)
+[![Tests badge](https://raw.githubusercontent.com/ProsD03/pyardent/tests-badge-data/tests-badge.svg)](https://github.com/ProsD03/pyardent/actions/workflows/tests.yml)
+[![Coverage badge](https://raw.githubusercontent.com/ProsD03/pyardent/python-coverage-comment-action-data/badge.svg)](https://github.com/ProsD03/pyardent/tree/python-coverage-comment-action-data)
+
+A Python client for the [Ardent Insight](https://ardent-insight.com) API: trade and system data for Elite Dangerous.
+
+Built on `httpx` and `pydantic`, fully type-hinted (ships a `py.typed` marker), with zero runtime dependencies beyond those two.
+
+## Installation
+
+```bash
+pip install pyardent
+```
+
+Requires Python 3.12+.
+
+## Quickstart
+
+```python
+from pyardent import ArdentClient
+
+client = ArdentClient()
+
+gold = client.commodity.get_by_name("gold")
+print(gold)
+#> commodity_name='gold' rare=False rare_station_id=None rare_max_count=None min_buy_price=3800 ...
+
+
+sol = client.system.get_by_name("Sol")
+stations = sol.get_stations()
+lincoln = next(s for s in stations if s.station_name == "Abraham Lincoln")
+print(lincoln)
+#> system_address=10477373803 station_id=128016896 station_name='Abraham Lincoln' ...
+```
+
+## Why pyardent
+
+Models aren't flat DTOs: they carry a reference back to the client, so you can traverse straight from one resource to another without manually threading IDs through further calls:
+
+```python
+gold = client.commodity.get_by_name("gold")
+
+# Where can I sell gold for at least 50,000 credits, near Sol?
+sol = client.system.get_by_name("Sol")
+buyers = gold.get_nearby_importers(sol, min_price=50_000, max_distance=50)
+
+for order in buyers:
+    station = order.get_station()  # one more hop, still through the same client
+    print(station.station_name, order.sell_price)
+```
+
+This graph-traversal pattern is consistent across the library: `System.get_stations()`, `Station.get_full_details()`, `Commodity.get_exporters()`, `CommodityMarket.get_station()`, and more.
+
+## Error handling
+
+Failed requests raise a typed exception instead of a bare `httpx.HTTPStatusError`:
+
+```python
+from pyardent import ArdentClient, SystemNotFoundError
+
+client = ArdentClient()
+
+try:
+    client.system.get_by_name("Not A Real System")
+except SystemNotFoundError:
+    ...
+```
+
+All exceptions inherit from `PyArdentError`; more specific subclasses (`CommodityNotFoundError`, `ServiceNotFoundError`, `ResourceNotFoundError`) are raised where the API's error response is specific enough to tell them apart.
+
+## Features
+
+- Full pydantic models for every major resource: `System`, `Station`, `Commodity`, `CommodityMarket`
+- Graph-traversal methods to move between related resources without re-fetching by hand
+- A typed exception hierarchy instead of raw HTTP errors
+- Custom `base_url` support, for pointing at a self-hosted or staging Ardent deployment
+- Fully typed public API (`py.typed` included, so your type checker sees real types, not `Any`)
+
+## Development
+
+This project uses [`uv`](https://docs.astral.sh/uv/) for dependency management.
+
+```bash
+uv sync                                                        # install dependencies
+uv run pytest                                                  # run tests
+uv run pytest --cov=src/pyardent --cov-report=term-missing     # run tests with coverage
+uv run mypy src                                                # type check
+```
+
+Contributions are welcome. Please make sure the commands above are clean before opening a pull request.
+
+## AI Usage Disclosure
+
+AI assistance (Claude Code) was used for parts of this project: documentation, the test suite, and general bug fixing.
+
+The research into Ardent Insight's documented and undocumented API surface, the overall structure of the library, and most of the core implementation were written by hand.
+
+## License
+
+MIT. See [LICENSE.md](LICENSE.md) for details.

pyardent-1.0.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "pyardent"
+version = "1.0.0"
+description = "Python client for the Ardent Insight API (Elite Dangerous trade/system data)"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE.md"]
+authors = [
+    { name = "ProsD", email = "me@prosd.dev" }
+]
+requires-python = ">=3.12"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic==2.13.5",
+]
+
+[project.urls]
+Repository = "https://github.com/ProsD03/pyardent"
+Issues = "https://github.com/ProsD03/pyardent/issues"
+
+[build-system]
+requires = ["uv_build>=0.8.12,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mypy>=2.1.0",
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.4.0",
+    "pytest-cov>=7.1.0",
+    "respx>=0.23.1",
+]
+
+[tool.coverage.run]
+relative_files = true

pyardent-1.0.0/src/pyardent/__init__.py

@@ -0,0 +1,10 @@
+import logging
+
+from .client import ArdentClient
+from .exceptions import PyArdentError, ResourceNotFoundError, CommodityNotFoundError, SystemNotFoundError, ServiceNotFoundError
+from .types import StationServices, LandingPad
+from .models import System, Station, Commodity, CommodityMarket
+
+logging.getLogger("pyardent").addHandler(logging.NullHandler())
+
+__all__ = ['ArdentClient', 'ResourceNotFoundError', 'CommodityNotFoundError', 'SystemNotFoundError', 'ServiceNotFoundError', 'PyArdentError', "StationServices", "LandingPad", "System", "Station", "Commodity", "CommodityMarket"]

pyardent-1.0.0/src/pyardent/client.py

@@ -0,0 +1,95 @@
+"""Top-level client for the Ardent Insight API.
+
+Wires up an `httpx.Client` shared by all `*Module` instances and installs the
+response hook that translates HTTP error responses into `PyArdentError`
+subclasses.
+"""
+
+import logging
+
+import httpx
+from .modules import MetaModule, CommodityModule, SystemModule
+from .exceptions import PyArdentError, ResourceNotFoundError, CommodityNotFoundError, SystemNotFoundError, \
+    ServiceNotFoundError
+from .modules.station import StationModule
+
+logger = logging.getLogger("pyardent.client")
+
+
+def _handle_response_errors(response: httpx.Response):
+    """Translate failed HTTP responses into `PyArdentError` subclasses.
+
+    Registered as an `httpx.Client` "response" event hook, so it runs on
+    every request made through `ArdentClient`. Successful responses pass
+    through unchanged.
+
+    Args:
+        response: The `httpx.Response` returned by the underlying request.
+
+    Raises:
+        CommodityNotFoundError: On a 404 whose API error message mentions a commodity.
+        SystemNotFoundError: On a 404 whose API error message mentions a system.
+        ServiceNotFoundError: On a 404 whose API error message mentions a service.
+        ResourceNotFoundError: On a 404 with no recognizable error message.
+        PyArdentError: On any other HTTP error status, a 404 with an
+            unrecognized message, or a network-level error.
+    """
+    response.read()
+    try:
+        response.raise_for_status()
+    except httpx.HTTPStatusError as e:
+
+        logger.error(f"HTTP error {e.response.status_code} for URL: {response.url}")
+
+        if e.response.status_code == 404:
+            error_payload = e.response.json()
+            api_msg = error_payload.get("message")
+            if api_msg:
+                if "commodity" in api_msg.lower():
+                    raise CommodityNotFoundError(str(response.url)) from e
+                elif "system" in api_msg.lower():
+                    raise SystemNotFoundError(str(response.url)) from e
+                elif "service" in api_msg.lower():
+                    raise ServiceNotFoundError(str(response.url)) from e
+                else:
+                    raise PyArdentError(api_msg) from e
+            raise ResourceNotFoundError(str(response.url)) from e
+        else:
+            raise PyArdentError(f"HTTP error {e.response.status_code} for URL: {response.url}") from e
+
+
+class ArdentClient:
+    """Entry point for the Ardent Insight API client.
+
+    Holds the shared `httpx.Client` and exposes one module per API resource
+    area (`meta`, `commodity`, `system`, `station`). Methods on those modules
+    return rich pydantic models (e.g. `System`, `Station`, `Commodity`,
+    `CommodityMarket`) that carry a reference back to this client so they can
+    make further API calls themselves (e.g. `system.get_stations()`).
+    """
+
+    DEFAULT_BASE_URL = "https://api.ardent-insight.com/v2"
+    _client: httpx.Client
+
+    meta: MetaModule
+    commodity: CommodityModule
+    system: SystemModule
+    station: StationModule
+
+    def __init__(self, base_url: str | None = None):
+        """Create a client and its underlying HTTP session.
+
+        Args:
+            base_url: Override for the API base URL. Defaults to
+                `ArdentClient.DEFAULT_BASE_URL` when omitted.
+        """
+        self._base_url = base_url or self.DEFAULT_BASE_URL
+
+        self._client = httpx.Client(base_url=self._base_url, event_hooks={"response": [_handle_response_errors, ]})
+
+        self.meta = MetaModule(self._client)
+        self.commodity = CommodityModule(self._client)
+        self.system = SystemModule(self._client)
+        self.station = StationModule(self._client)
+
+        logger.info(f"Initialized ArdentClient pointing to {self._base_url}")

pyardent-1.0.0/src/pyardent/exceptions.py

@@ -0,0 +1,56 @@
+"""Exception hierarchy raised by pyardent.
+
+All errors raised by the client are `PyArdentError` or one of its subclasses
+below, translated from HTTP responses by `client._handle_response_errors`.
+"""
+
+
+class PyArdentError(Exception):
+    """Base class for all errors raised by this library.
+
+    Args:
+        message: Human-readable description of the failure.
+    """
+
+    def __init__(self, message: str):
+        super().__init__(message)
+
+class ResourceNotFoundError(PyArdentError):
+    """Raised on a 404 whose API error message didn't match a more specific case.
+
+    Args:
+        url: The request URL that returned the 404.
+    """
+
+    def __init__(self, url: str):
+        super().__init__(f"Resource not found at endpoint: {url}")
+
+class CommodityNotFoundError(PyArdentError):
+    """Raised when the requested commodity does not exist.
+
+    Args:
+        url: The request URL that returned the 404.
+    """
+
+    def __init__(self, url: str):
+        super().__init__(f"Commodity does not exist. Endpoint: {url}")
+
+class SystemNotFoundError(PyArdentError):
+    """Raised when the requested system does not exist.
+
+    Args:
+        url: The request URL that returned the 404.
+    """
+
+    def __init__(self, url: str):
+        super().__init__(f"System does not exist. Endpoint: {url}")
+
+class ServiceNotFoundError(PyArdentError):
+    """Raised when the requested station service type is unknown to the API.
+
+    Args:
+        url: The request URL that returned the 404.
+    """
+
+    def __init__(self, url: str):
+        super().__init__(f"Service does not exist. Endpoint: {url}")

pyardent-1.0.0/src/pyardent/models/__init__.py

@@ -0,0 +1,7 @@
+from .meta import APIVersion, APIStats, APIEconomies, APIStations
+from .commodity import Commodity
+from .system import System
+from .station import Station
+from .market import CommodityMarket
+
+__all__ = ["APIVersion", "APIStats", "APIEconomies", "APIStations", "Commodity", "System", "Station", "CommodityMarket"]