python-eveonline 0.2.0__tar.gz → 0.2.2__tar.gz

python_eveonline-0.2.2/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: python-eveonline
+Version: 0.2.2
+Summary: Async Python client for the Eve Online ESI API
+Author: Ronald van der Meer
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ronaldvdmeer/python-eveonline
+Project-URL: Repository, https://github.com/ronaldvdmeer/python-eveonline
+Project-URL: Issues, https://github.com/ronaldvdmeer/python-eveonline/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment
+Classifier: Typing :: Typed
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: aioresponses>=0.7; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: pylint>=3.0; extra == "dev"
+Requires-Dist: ruff>=0.3; extra == "dev"
+Dynamic: license-file
+
+# python-eveonline
+
+[![PyPI](https://img.shields.io/pypi/v/python-eveonline.svg)](https://pypi.org/project/python-eveonline/)
+[![Python](https://img.shields.io/pypi/pyversions/python-eveonline.svg)](https://pypi.org/project/python-eveonline/)
+[![License](https://img.shields.io/github/license/ronaldvdmeer/python-eveonline.svg)](https://github.com/ronaldvdmeer/python-eveonline/blob/main/LICENSE)
+[![GitHub Release](https://img.shields.io/github/v/release/ronaldvdmeer/python-eveonline.svg)](https://github.com/ronaldvdmeer/python-eveonline/releases)
+
+Async Python client library for the [Eve Online ESI API](https://esi.evetech.net/ui/).
+
+Built for use with [Home Assistant](https://www.home-assistant.io/) but can be used standalone in any async Python project.
+
+## Features
+
+- **Fully async** — built on [aiohttp](https://docs.aiohttp.org/)
+- **Typed models** — all API responses are frozen dataclasses
+- **Public endpoints** — server status, character info, corporation info, portraits, universe name resolution
+- **Authenticated endpoints** — online status, location, ship, wallet, skills, skill queue, mail, industry jobs, market orders, jump fatigue
+- **Abstract auth** — implement `AbstractAuth` to provide your own token management (e.g. Home Assistant OAuth2)
+- **Type-safe** — PEP 561 compatible (`py.typed`), strict mypy configuration
+- **Tested** — 100% test coverage
+
+## Installation
+
+```bash
+pip install python-eveonline
+```
+
+## Quick start
+
+### Public endpoints (no authentication required)
+
+```python
+import asyncio
+import aiohttp
+from eveonline import EveOnlineClient
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        client = EveOnlineClient(session=session)
+        status = await client.async_get_server_status()
+        print(f"{status.players} players online (version {status.server_version})")
+
+asyncio.run(main())
+```
+
+### Authenticated endpoints
+
+To access character-specific data, implement the `AbstractAuth` class with your own token management:
+
+```python
+from eveonline import EveOnlineClient
+from eveonline.auth import AbstractAuth
+
+class MyAuth(AbstractAuth):
+    async def async_get_access_token(self) -> str:
+        return "your-access-token"
+
+auth = MyAuth(websession)
+client = EveOnlineClient(auth=auth)
+
+online = await client.async_get_character_online(character_id)
+wallet = await client.async_get_wallet_balance(character_id)
+```
+
+## Available endpoints
+
+| Method | Scope required | Returns |
+|--------|---------------|---------|
+| `async_get_server_status()` | — | `ServerStatus` |
+| `async_get_character_public(id)` | — | `CharacterPublicInfo` |
+| `async_get_character_portrait(id)` | — | `CharacterPortrait` |
+| `async_get_corporation_public(id)` | — | `CorporationPublicInfo` |
+| `async_resolve_names(ids)` | — | `list[UniverseName]` |
+| `async_get_character_online(id)` | `esi-location.read_online.v1` | `CharacterOnlineStatus` |
+| `async_get_character_location(id)` | `esi-location.read_location.v1` | `CharacterLocation` |
+| `async_get_character_ship(id)` | `esi-location.read_ship_type.v1` | `CharacterShip` |
+| `async_get_wallet_balance(id)` | `esi-wallet.read_character_wallet.v1` | `WalletBalance` |
+| `async_get_skills(id)` | `esi-skills.read_skills.v1` | `CharacterSkillsSummary` |
+| `async_get_skill_queue(id)` | `esi-skills.read_skillqueue.v1` | `list[SkillQueueEntry]` |
+| `async_get_mail_labels(id)` | `esi-mail.read_mail.v1` | `MailLabelsSummary` |
+| `async_get_industry_jobs(id)` | `esi-industry.read_character_jobs.v1` | `list[IndustryJob]` |
+| `async_get_market_orders(id)` | `esi-markets.read_character_orders.v1` | `list[MarketOrder]` |
+| `async_get_jump_fatigue(id)` | `esi-characters.read_fatigue.v1` | `JumpFatigue` |
+
+## Error handling
+
+All exceptions inherit from `EveOnlineError`:
+
+```python
+from eveonline import EveOnlineClient, EveOnlineError
+from eveonline.exceptions import (
+    EveOnlineAuthenticationError,  # 401/403 or missing auth
+    EveOnlineConnectionError,      # Network/connection failures
+    EveOnlineRateLimitError,       # 429 with optional retry_after
+)
+
+try:
+    status = await client.async_get_server_status()
+except EveOnlineAuthenticationError:
+    # Token expired or invalid
+    ...
+except EveOnlineRateLimitError as err:
+    # Back off for err.retry_after seconds
+    ...
+except EveOnlineError:
+    # Any other ESI error
+    ...
+```
+
+## License
+
+[MIT](LICENSE)

python_eveonline-0.2.2/README.md

@@ -0,0 +1,112 @@
+# python-eveonline
+
+[![PyPI](https://img.shields.io/pypi/v/python-eveonline.svg)](https://pypi.org/project/python-eveonline/)
+[![Python](https://img.shields.io/pypi/pyversions/python-eveonline.svg)](https://pypi.org/project/python-eveonline/)
+[![License](https://img.shields.io/github/license/ronaldvdmeer/python-eveonline.svg)](https://github.com/ronaldvdmeer/python-eveonline/blob/main/LICENSE)
+[![GitHub Release](https://img.shields.io/github/v/release/ronaldvdmeer/python-eveonline.svg)](https://github.com/ronaldvdmeer/python-eveonline/releases)
+
+Async Python client library for the [Eve Online ESI API](https://esi.evetech.net/ui/).
+
+Built for use with [Home Assistant](https://www.home-assistant.io/) but can be used standalone in any async Python project.
+
+## Features
+
+- **Fully async** — built on [aiohttp](https://docs.aiohttp.org/)
+- **Typed models** — all API responses are frozen dataclasses
+- **Public endpoints** — server status, character info, corporation info, portraits, universe name resolution
+- **Authenticated endpoints** — online status, location, ship, wallet, skills, skill queue, mail, industry jobs, market orders, jump fatigue
+- **Abstract auth** — implement `AbstractAuth` to provide your own token management (e.g. Home Assistant OAuth2)
+- **Type-safe** — PEP 561 compatible (`py.typed`), strict mypy configuration
+- **Tested** — 100% test coverage
+
+## Installation
+
+```bash
+pip install python-eveonline
+```
+
+## Quick start
+
+### Public endpoints (no authentication required)
+
+```python
+import asyncio
+import aiohttp
+from eveonline import EveOnlineClient
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        client = EveOnlineClient(session=session)
+        status = await client.async_get_server_status()
+        print(f"{status.players} players online (version {status.server_version})")
+
+asyncio.run(main())
+```
+
+### Authenticated endpoints
+
+To access character-specific data, implement the `AbstractAuth` class with your own token management:
+
+```python
+from eveonline import EveOnlineClient
+from eveonline.auth import AbstractAuth
+
+class MyAuth(AbstractAuth):
+    async def async_get_access_token(self) -> str:
+        return "your-access-token"
+
+auth = MyAuth(websession)
+client = EveOnlineClient(auth=auth)
+
+online = await client.async_get_character_online(character_id)
+wallet = await client.async_get_wallet_balance(character_id)
+```
+
+## Available endpoints
+
+| Method | Scope required | Returns |
+|--------|---------------|---------|
+| `async_get_server_status()` | — | `ServerStatus` |
+| `async_get_character_public(id)` | — | `CharacterPublicInfo` |
+| `async_get_character_portrait(id)` | — | `CharacterPortrait` |
+| `async_get_corporation_public(id)` | — | `CorporationPublicInfo` |
+| `async_resolve_names(ids)` | — | `list[UniverseName]` |
+| `async_get_character_online(id)` | `esi-location.read_online.v1` | `CharacterOnlineStatus` |
+| `async_get_character_location(id)` | `esi-location.read_location.v1` | `CharacterLocation` |
+| `async_get_character_ship(id)` | `esi-location.read_ship_type.v1` | `CharacterShip` |
+| `async_get_wallet_balance(id)` | `esi-wallet.read_character_wallet.v1` | `WalletBalance` |
+| `async_get_skills(id)` | `esi-skills.read_skills.v1` | `CharacterSkillsSummary` |
+| `async_get_skill_queue(id)` | `esi-skills.read_skillqueue.v1` | `list[SkillQueueEntry]` |
+| `async_get_mail_labels(id)` | `esi-mail.read_mail.v1` | `MailLabelsSummary` |
+| `async_get_industry_jobs(id)` | `esi-industry.read_character_jobs.v1` | `list[IndustryJob]` |
+| `async_get_market_orders(id)` | `esi-markets.read_character_orders.v1` | `list[MarketOrder]` |
+| `async_get_jump_fatigue(id)` | `esi-characters.read_fatigue.v1` | `JumpFatigue` |
+
+## Error handling
+
+All exceptions inherit from `EveOnlineError`:
+
+```python
+from eveonline import EveOnlineClient, EveOnlineError
+from eveonline.exceptions import (
+    EveOnlineAuthenticationError,  # 401/403 or missing auth
+    EveOnlineConnectionError,      # Network/connection failures
+    EveOnlineRateLimitError,       # 429 with optional retry_after
+)
+
+try:
+    status = await client.async_get_server_status()
+except EveOnlineAuthenticationError:
+    # Token expired or invalid
+    ...
+except EveOnlineRateLimitError as err:
+    # Back off for err.retry_after seconds
+    ...
+except EveOnlineError:
+    # Any other ESI error
+    ...
+```
+
+## License
+
+[MIT](LICENSE)

{python_eveonline-0.2.0 → python_eveonline-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-eveonline"
-version = "0.2.0"
+version = "0.2.2"
 description = "Async Python client for the Eve Online ESI API"
 readme = "README.md"
 license = "MIT"

{python_eveonline-0.2.0 → python_eveonline-0.2.2}/src/eveonline/__init__.py

@@ -1,15 +1,23 @@
 """Async Python client for the Eve Online ESI API."""
 
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
 from .auth import AbstractAuth
 from .client import EveOnlineClient
 from .exceptions import (
     EveOnlineAuthenticationError,
     EveOnlineConnectionError,
     EveOnlineError,
+    EveOnlineNotFoundError,
     EveOnlineRateLimitError,
 )
 
-__version__ = "0.2.0"
+try:
+    __version__ = version("python-eveonline")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
 
 __all__ = [
     "AbstractAuth",
@@ -17,6 +25,7 @@ __all__ = [
     "EveOnlineClient",
     "EveOnlineConnectionError",
     "EveOnlineError",
+    "EveOnlineNotFoundError",
     "EveOnlineRateLimitError",
     "__version__",
 ]

{python_eveonline-0.2.0 → python_eveonline-0.2.2}/src/eveonline/client.py

@@ -145,7 +145,13 @@ class EveOnlineClient:
 
         if response.status in (420, 429):
             retry_after = response.headers.get("Retry-After")
-            raise EveOnlineRateLimitError(retry_after=int(retry_after) if retry_after else None)
+            retry_after_seconds: int | None = None
+            if retry_after is not None:
+                try:
+                    retry_after_seconds = int(retry_after)
+                except ValueError:
+                    retry_after_seconds = None
+            raise EveOnlineRateLimitError(retry_after=retry_after_seconds)
 
         if response.status >= 400:
             text = await response.text()
@@ -156,11 +162,19 @@ class EveOnlineClient:
 
     @staticmethod
     def _parse_datetime(value: str | None) -> datetime | None:
-        """Parse an ISO8601 datetime string from ESI."""
+        """Parse an ISO 8601 datetime string from ESI.
+
+        Args:
+            value: An ISO 8601 string (e.g. ``"2025-01-15T12:34:56Z"``) or
+                ``None``.
+
+        Returns:
+            A timezone-aware :class:`~datetime.datetime`, or ``None`` when
+            *value* is ``None``.
+        """
         if value is None:
             return None
-        # ESI returns times like "2025-01-15T12:34:56Z"
-        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+        return datetime.fromisoformat(value)
 
     # -------------------------------------------------------------------------
     # Public endpoints (no auth required)
@@ -176,7 +190,7 @@ class EveOnlineClient:
         return ServerStatus(
             players=data["players"],
             server_version=data["server_version"],
-            start_time=datetime.fromisoformat(data["start_time"].replace("Z", "+00:00")),
+            start_time=datetime.fromisoformat(data["start_time"]),
             vip=data.get("vip"),
         )
 
@@ -194,7 +208,7 @@ class EveOnlineClient:
             character_id=character_id,
             name=data["name"],
             corporation_id=data["corporation_id"],
-            birthday=datetime.fromisoformat(data["birthday"].replace("Z", "+00:00")),
+            birthday=datetime.fromisoformat(data["birthday"]),
             gender=data["gender"],
             race_id=data["race_id"],
             bloodline_id=data["bloodline_id"],
@@ -424,8 +438,8 @@ class EveOnlineClient:
                 job_id=entry["job_id"],
                 activity_id=entry["activity_id"],
                 status=entry["status"],
-                start_date=datetime.fromisoformat(entry["start_date"].replace("Z", "+00:00")),
-                end_date=datetime.fromisoformat(entry["end_date"].replace("Z", "+00:00")),
+                start_date=datetime.fromisoformat(entry["start_date"]),
+                end_date=datetime.fromisoformat(entry["end_date"]),
                 blueprint_type_id=entry["blueprint_type_id"],
                 output_location_id=entry["output_location_id"],
                 runs=entry["runs"],
@@ -458,7 +472,7 @@ class EveOnlineClient:
                 volume_total=entry["volume_total"],
                 location_id=entry["location_id"],
                 region_id=entry["region_id"],
-                issued=datetime.fromisoformat(entry["issued"].replace("Z", "+00:00")),
+                issued=datetime.fromisoformat(entry["issued"]),
                 duration=entry["duration"],
                 range=entry["range"],
                 min_volume=entry.get("min_volume"),

{python_eveonline-0.2.0 → python_eveonline-0.2.2}/src/eveonline/const.py

@@ -1,5 +1,7 @@
 """Constants for the Eve Online ESI API."""
 
+from __future__ import annotations
+
 from typing import Final
 
 # ESI API
@@ -28,7 +30,7 @@ SCOPE_READ_INDUSTRY_JOBS: Final = "esi-industry.read_character_jobs.v1"
 SCOPE_READ_MARKET_ORDERS: Final = "esi-markets.read_character_orders.v1"
 
 # Default scopes for a typical Home Assistant integration
-DEFAULT_SCOPES: Final = [
+DEFAULT_SCOPES: Final = (
     SCOPE_READ_ONLINE,
     SCOPE_READ_LOCATION,
     SCOPE_READ_SHIP_TYPE,
@@ -39,4 +41,4 @@ DEFAULT_SCOPES: Final = [
     SCOPE_READ_MAIL,
     SCOPE_READ_INDUSTRY_JOBS,
     SCOPE_READ_MARKET_ORDERS,
-]
+)

{python_eveonline-0.2.0 → python_eveonline-0.2.2}/src/eveonline/exceptions.py

@@ -1,5 +1,7 @@
 """Exceptions for the Eve Online ESI client."""
 
+from __future__ import annotations
+
 
 class EveOnlineError(Exception):
     """Base exception for Eve Online ESI errors."""
@@ -14,10 +16,20 @@ class EveOnlineAuthenticationError(EveOnlineError):
 
 
 class EveOnlineRateLimitError(EveOnlineError):
-    """Exception raised when the ESI rate limit is exceeded."""
+    """Exception raised when the ESI rate limit is exceeded.
+
+    Attributes:
+        retry_after: Seconds to wait before retrying, or ``None`` if the
+            server did not provide the header.
+    """
 
     def __init__(self, retry_after: int | None = None) -> None:
-        """Initialize the rate limit error."""
+        """Initialize the rate limit error.
+
+        Args:
+            retry_after: Optional number of seconds the server asks us to
+                wait before retrying.
+        """
         self.retry_after = retry_after
         message = "ESI rate limit exceeded"
         if retry_after is not None: