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

python_eveonline-0.3.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: python-eveonline
+Version: 0.3.0
+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 with full type annotations
+- **15 endpoints** — public (server, character, corporation, universe) and authenticated (wallet, skills, location, industry, market, mail, fatigue)
+- **Abstract auth** — implement `AbstractAuth` to plug in any OAuth2 token source
+- **Type-safe** — PEP 561 compatible (`py.typed`), strict mypy configuration
+- **Tested** — 100% test coverage
+
+## Installation
+
+```bash
+pip install python-eveonline
+```
+
+## Quick start
+
+```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 (v{status.server_version})")
+
+asyncio.run(main())
+```
+
+## Documentation
+
+- [**Quickstart**](docs/quickstart.md) — public and authenticated endpoint examples
+- [**Authentication**](docs/authentication.md) — implementing `AbstractAuth`, required OAuth scopes
+- [**Endpoints**](docs/endpoints.md) — full reference with field tables for all 15 methods
+- [**Error Handling**](docs/error-handling.md) — exception hierarchy, rate limiting, ESI cache times
+
+## License
+
+[MIT](LICENSE)

python_eveonline-0.3.0/README.md

@@ -0,0 +1,52 @@
+# 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 with full type annotations
+- **15 endpoints** — public (server, character, corporation, universe) and authenticated (wallet, skills, location, industry, market, mail, fatigue)
+- **Abstract auth** — implement `AbstractAuth` to plug in any OAuth2 token source
+- **Type-safe** — PEP 561 compatible (`py.typed`), strict mypy configuration
+- **Tested** — 100% test coverage
+
+## Installation
+
+```bash
+pip install python-eveonline
+```
+
+## Quick start
+
+```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 (v{status.server_version})")
+
+asyncio.run(main())
+```
+
+## Documentation
+
+- [**Quickstart**](docs/quickstart.md) — public and authenticated endpoint examples
+- [**Authentication**](docs/authentication.md) — implementing `AbstractAuth`, required OAuth scopes
+- [**Endpoints**](docs/endpoints.md) — full reference with field tables for all 15 methods
+- [**Error Handling**](docs/error-handling.md) — exception hierarchy, rate limiting, ESI cache times
+
+## License
+
+[MIT](LICENSE)

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-eveonline"
-version = "0.2.2"
+version = "0.3.0"
 description = "Async Python client for the Eve Online ESI API"
 readme = "README.md"
 license = "MIT"
@@ -58,6 +58,10 @@ addopts = [
     "--cov-report=term-missing",
     "--cov-fail-under=90",
     "-v",
+    "-m", "not integration",
+]
+markers = [
+    "integration: live ESI API tests — require network access; authenticated tests also require ESI_TOKEN env var",
 ]
 
 # -- coverage ----------------------------------------------------------------
@@ -160,6 +164,13 @@ ignore = [
 "src/eveonline/const.py" = [
     "S105",   # SSO_TOKEN_URL is a URL, not a password
 ]
+"scripts/**/*.py" = [
+    "D",      # No docstring requirements in scripts
+    "T20",    # Allow print in scripts (CLI output)
+    "ANN",    # No annotation requirements in scripts
+    "S105",   # URL constants that look like passwords
+    "S310",   # URL open is expected in these scripts
+]
 
 [tool.ruff.lint.pydocstyle]
 convention = "google"
@@ -181,3 +192,4 @@ disable = [
 
 [tool.pylint.design]
 max-args = 10
+max-public-methods = 30

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

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from datetime import datetime
-from typing import Any
+from typing import Any, overload
 
 from aiohttp import ClientSession
 
@@ -17,21 +17,29 @@ from .exceptions import (
     EveOnlineRateLimitError,
 )
 from .models import (
+    CalendarEvent,
+    CharacterClones,
+    CharacterContact,
     CharacterLocation,
+    CharacterNotification,
     CharacterOnlineStatus,
     CharacterPortrait,
     CharacterPublicInfo,
     CharacterShip,
     CharacterSkillsSummary,
+    CloneHomeLocation,
     CorporationPublicInfo,
     IndustryJob,
+    JumpClone,
     JumpFatigue,
+    LoyaltyPoints,
     MailLabelsSummary,
     MarketOrder,
     ServerStatus,
     SkillQueueEntry,
     UniverseName,
     WalletBalance,
+    WalletJournalEntry,
 )
 
 
@@ -79,6 +87,8 @@ class EveOnlineClient:
         """
         self._auth = auth
         self._host = host
+        # ETag cache: maps cache_key -> (etag, cached_response_data)
+        self._etag_cache: dict[str, tuple[str, Any]] = {}
 
         if auth is not None:
             self._session = auth.websession
@@ -88,13 +98,81 @@ class EveOnlineClient:
             msg = "Either 'session' or 'auth' must be provided"
             raise EveOnlineError(msg)
 
+    def clear_etag_cache(self) -> None:
+        """Clear the ETag cache, forcing fresh responses on the next requests."""
+        self._etag_cache.clear()
+
     # -------------------------------------------------------------------------
     # Internal helpers
     # -------------------------------------------------------------------------
 
+    def _etag_key(self, path: str, params: dict[str, Any], authenticated: bool) -> str:
+        """Build a deterministic cache key for an ESI endpoint.
+
+        Args:
+            path: API path relative to the ESI base URL.
+            params: Query parameters (must already contain ``datasource``).
+            authenticated: Whether the request uses OAuth.
+
+        Returns:
+            A string key unique to this endpoint + parameter combination.
+        """
+        sorted_params = "&".join(f"{k}={v}" for k, v in sorted(params.items()))
+        auth_prefix = "auth" if authenticated else "pub"
+        return f"{auth_prefix}:{path}?{sorted_params}"
+
+    def _build_etag_headers(self, method: str, cache_key: str) -> dict[str, str]:
+        """Return an ``If-None-Match`` header dict if a cached ETag exists.
+
+        Args:
+            method: HTTP method (only ``"GET"`` uses ETags).
+            cache_key: Cache key produced by :meth:`_etag_key`.
+
+        Returns:
+            A headers dict with ``If-None-Match`` set, or an empty dict.
+        """
+        if method == "GET" and cache_key in self._etag_cache:
+            return {"If-None-Match": self._etag_cache[cache_key][0]}
+        return {}
+
+    def _store_etag(self, method: str, cache_key: str, response: Any, data: Any) -> None:
+        """Cache the ETag from a successful GET response.
+
+        Args:
+            method: HTTP method (only ``"GET"`` responses are cached).
+            cache_key: Cache key produced by :meth:`_etag_key`.
+            response: The aiohttp response object.
+            data: Parsed JSON data to cache alongside the ETag.
+        """
+        etag = response.headers.get("ETag")
+        if method == "GET" and etag:
+            self._etag_cache[cache_key] = (etag, data)
+
+    @staticmethod
+    def _parse_retry_after(response: Any) -> int | None:
+        """Extract the Retry-After delay in seconds from a rate-limit response.
+
+        Args:
+            response: The aiohttp response object.
+
+        Returns:
+            The delay in seconds, or ``None`` if the header is absent or
+            cannot be parsed as an integer.
+        """
+        if (retry_after := response.headers.get("Retry-After")) is None:
+            return None
+        try:
+            return int(retry_after)
+        except ValueError:
+            return None
+
     async def _request(self, method: str, path: str, *, authenticated: bool = False, **kwargs: Any) -> Any:
         """Make a request to the ESI API.
 
+        GET requests use ETag caching: a cached ``ETag`` is sent as
+        ``If-None-Match``; a ``304 Not Modified`` response returns the
+        previously cached data without consuming bandwidth.
+
         Args:
             method: HTTP method.
             path: API path relative to ESI base URL.
@@ -114,18 +192,21 @@ class EveOnlineClient:
         """
         params: dict[str, Any] = dict(kwargs.pop("params", {}) or {})
         params.setdefault("datasource", ESI_DATASOURCE)
+        cache_key = self._etag_key(path, params, authenticated)
+        headers = {**dict(kwargs.pop("headers", {}) or {}), **self._build_etag_headers(method, cache_key)}
 
         try:
             if authenticated:
                 if self._auth is None:
                     msg = "Authentication required but no auth provider configured"
                     raise EveOnlineAuthenticationError(msg)
-                response = await self._auth.request(method, path, params=params, **kwargs)
+                response = await self._auth.request(method, path, params=params, headers=headers, **kwargs)
             else:
                 response = await self._session.request(
                     method,
                     f"{self._host}/{path}",
                     params=params,
+                    headers=headers,
                     **kwargs,
                 )
         except EveOnlineError:
@@ -139,26 +220,46 @@ class EveOnlineClient:
             msg = f"Authentication failed ({response.status}): {text}"
             raise EveOnlineAuthenticationError(msg)
 
+        if response.status == 304:
+            # Not Modified — return the data we cached earlier if it still exists.
+            response.release()
+            if (cached := self._etag_cache.get(cache_key)) is None:
+                msg = (
+                    f"Received 304 Not Modified from ESI, but no matching ETag "
+                    f"cache entry exists for key {cache_key!r}."
+                )
+                raise EveOnlineError(msg)
+            return cached[1]
+
         if response.status == 404:
+            response.release()
             msg = f"Resource not found: {path}"
             raise EveOnlineNotFoundError(msg)
 
         if response.status in (420, 429):
-            retry_after = response.headers.get("Retry-After")
-            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)
+            response.release()
+            raise EveOnlineRateLimitError(retry_after=self._parse_retry_after(response))
 
         if response.status >= 400:
             text = await response.text()
             msg = f"ESI API error ({response.status}): {text}"
             raise EveOnlineError(msg)
 
-        return await response.json()
+        data = await response.json()
+        self._store_etag(method, cache_key, response, data)
+        return data
+
+    @staticmethod
+    @overload
+    def _parse_datetime(value: str) -> datetime: ...
+
+    @staticmethod
+    @overload
+    def _parse_datetime(value: None) -> None: ...
+
+    @staticmethod
+    @overload
+    def _parse_datetime(value: str | None) -> datetime | None: ...
 
     @staticmethod
     def _parse_datetime(value: str | None) -> datetime | None:
@@ -169,8 +270,8 @@ class EveOnlineClient:
                 ``None``.
 
         Returns:
-            A timezone-aware :class:`~datetime.datetime`, or ``None`` when
-            *value* is ``None``.
+            A :class:`~datetime.datetime` when *value* is a string, or
+            ``None`` when *value* is ``None``.
         """
         if value is None:
             return None
@@ -190,7 +291,7 @@ class EveOnlineClient:
         return ServerStatus(
             players=data["players"],
             server_version=data["server_version"],
-            start_time=datetime.fromisoformat(data["start_time"]),
+            start_time=self._parse_datetime(data["start_time"]),
             vip=data.get("vip"),
         )
 
@@ -208,7 +309,7 @@ class EveOnlineClient:
             character_id=character_id,
             name=data["name"],
             corporation_id=data["corporation_id"],
-            birthday=datetime.fromisoformat(data["birthday"]),
+            birthday=self._parse_datetime(data["birthday"]),
             gender=data["gender"],
             race_id=data["race_id"],
             bloodline_id=data["bloodline_id"],
@@ -438,8 +539,8 @@ class EveOnlineClient:
                 job_id=entry["job_id"],
                 activity_id=entry["activity_id"],
                 status=entry["status"],
-                start_date=datetime.fromisoformat(entry["start_date"]),
-                end_date=datetime.fromisoformat(entry["end_date"]),
+                start_date=self._parse_datetime(entry["start_date"]),
+                end_date=self._parse_datetime(entry["end_date"]),
                 blueprint_type_id=entry["blueprint_type_id"],
                 output_location_id=entry["output_location_id"],
                 runs=entry["runs"],
@@ -472,7 +573,7 @@ class EveOnlineClient:
                 volume_total=entry["volume_total"],
                 location_id=entry["location_id"],
                 region_id=entry["region_id"],
-                issued=datetime.fromisoformat(entry["issued"]),
+                issued=self._parse_datetime(entry["issued"]),
                 duration=entry["duration"],
                 range=entry["range"],
                 min_volume=entry.get("min_volume"),
@@ -497,3 +598,175 @@ class EveOnlineClient:
             last_jump_date=self._parse_datetime(data.get("last_jump_date")),
             last_update_date=self._parse_datetime(data.get("last_update_date")),
         )
+
+    async def async_get_notifications(self, character_id: int) -> list[CharacterNotification]:
+        """Get a character's recent notifications.
+
+        Requires scope: ``esi-characters.read_notifications.v1``
+
+        Args:
+            character_id: The Eve Online character ID.
+
+        Returns:
+            List of CharacterNotification entries, newest first.
+        """
+        data = await self._request("GET", f"characters/{character_id}/notifications/", authenticated=True)
+        return [
+            CharacterNotification(
+                notification_id=entry["notification_id"],
+                sender_id=entry["sender_id"],
+                sender_type=entry["sender_type"],
+                type=entry["type"],
+                timestamp=self._parse_datetime(entry["timestamp"]),
+                is_read=entry.get("is_read"),
+                text=entry.get("text"),
+            )
+            for entry in data
+        ]
+
+    async def async_get_clones(self, character_id: int) -> CharacterClones:
+        """Get a character's clone information.
+
+        Requires scope: ``esi-clones.read_clones.v1``
+
+        Args:
+            character_id: The Eve Online character ID.
+
+        Returns:
+            CharacterClones with home location and jump clones.
+        """
+        data = await self._request("GET", f"characters/{character_id}/clones/", authenticated=True)
+
+        home_loc = data.get("home_location")
+        home_location: CloneHomeLocation | None = None
+        if home_loc:
+            home_location = CloneHomeLocation(
+                location_id=home_loc["location_id"],
+                location_type=home_loc["location_type"],
+            )
+
+        jump_clones = tuple(
+            JumpClone(
+                jump_clone_id=jc["jump_clone_id"],
+                location_id=jc["location_id"],
+                location_type=jc["location_type"],
+                implants=tuple(jc.get("implants", [])),
+                name=jc.get("name"),
+            )
+            for jc in data.get("jump_clones", [])
+        )
+
+        return CharacterClones(
+            home_location=home_location,
+            jump_clones=jump_clones,
+            last_clone_jump_date=self._parse_datetime(data.get("last_clone_jump_date")),
+            last_station_change_date=self._parse_datetime(data.get("last_station_change_date")),
+        )
+
+    async def async_get_implants(self, character_id: int) -> tuple[int, ...]:
+        """Get the type IDs of a character's active implants.
+
+        Requires scope: ``esi-clones.read_implants.v1``
+
+        Args:
+            character_id: The Eve Online character ID.
+
+        Returns:
+            Tuple of implant type IDs.
+        """
+        data = await self._request("GET", f"characters/{character_id}/implants/", authenticated=True)
+        return tuple(data)
+
+    async def async_get_wallet_journal(self, character_id: int) -> list[WalletJournalEntry]:
+        """Get a character's wallet journal (recent transactions).
+
+        Requires scope: ``esi-wallet.read_character_wallet.v1``
+
+        Args:
+            character_id: The Eve Online character ID.
+
+        Returns:
+            List of WalletJournalEntry entries, newest first.
+        """
+        data = await self._request("GET", f"characters/{character_id}/wallet/journal/", authenticated=True)
+        return [
+            WalletJournalEntry(
+                id=entry["id"],
+                date=self._parse_datetime(entry["date"]),
+                ref_type=entry["ref_type"],
+                description=entry.get("description", ""),
+                amount=entry.get("amount"),
+                balance=entry.get("balance"),
+                first_party_id=entry.get("first_party_id"),
+                second_party_id=entry.get("second_party_id"),
+                reason=entry.get("reason"),
+            )
+            for entry in data
+        ]
+
+    async def async_get_contacts(self, character_id: int) -> list[CharacterContact]:
+        """Get a character's contacts.
+
+        Requires scope: ``esi-characters.read_contacts.v1``
+
+        Args:
+            character_id: The Eve Online character ID.
+
+        Returns:
+            List of CharacterContact entries.
+        """
+        data = await self._request("GET", f"characters/{character_id}/contacts/", authenticated=True)
+        return [
+            CharacterContact(
+                contact_id=entry["contact_id"],
+                contact_type=entry["contact_type"],
+                standing=entry["standing"],
+                is_blocked=entry.get("is_blocked"),
+                is_watched=entry.get("is_watched"),
+                label_ids=tuple(entry["label_ids"]) if entry.get("label_ids") else None,
+            )
+            for entry in data
+        ]
+
+    async def async_get_calendar(self, character_id: int) -> list[CalendarEvent]:
+        """Get a character's upcoming calendar events.
+
+        Requires scope: ``esi-calendar.read_calendar_events.v1``
+
+        Args:
+            character_id: The Eve Online character ID.
+
+        Returns:
+            List of CalendarEvent entries.
+        """
+        data = await self._request("GET", f"characters/{character_id}/calendar/", authenticated=True)
+        return [
+            CalendarEvent(
+                event_id=entry["event_id"],
+                event_date=self._parse_datetime(entry["event_date"]),
+                title=entry["title"],
+                importance=entry.get("importance"),
+                event_response=entry.get("event_response"),
+            )
+            for entry in data
+        ]
+
+    async def async_get_loyalty_points(self, character_id: int) -> list[LoyaltyPoints]:
+        """Get a character's loyalty points per corporation.
+
+        Requires scope: ``esi-characters.read_loyalty.v1``
+
+        Args:
+            character_id: The Eve Online character ID.
+
+        Returns:
+            List of LoyaltyPoints entries.
+        """
+        data = await self._request("GET", f"characters/{character_id}/loyalty/points/", authenticated=True)
+        return [
+            LoyaltyPoints(
+                corporation_id=entry["corporation_id"],
+                loyalty_points=entry["loyalty_points"],
+            )
+            for entry in data
+        ]

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

@@ -28,6 +28,9 @@ SCOPE_READ_FATIGUE: Final = "esi-characters.read_fatigue.v1"
 SCOPE_READ_MAIL: Final = "esi-mail.read_mail.v1"
 SCOPE_READ_INDUSTRY_JOBS: Final = "esi-industry.read_character_jobs.v1"
 SCOPE_READ_MARKET_ORDERS: Final = "esi-markets.read_character_orders.v1"
+SCOPE_READ_CONTACTS: Final = "esi-characters.read_contacts.v1"
+SCOPE_READ_CALENDAR: Final = "esi-calendar.read_calendar_events.v1"
+SCOPE_READ_LOYALTY: Final = "esi-characters.read_loyalty.v1"
 
 # Default scopes for a typical Home Assistant integration
 DEFAULT_SCOPES: Final = (