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

{python_eveonline-0.3.0/src/python_eveonline.egg-info → python_eveonline-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-eveonline
-Version: 0.3.0
+Version: 0.4.0
 Summary: Async Python client for the Eve Online ESI API
 Author: Ronald van der Meer
 License-Expression: MIT
@@ -45,10 +45,10 @@ Built for use with [Home Assistant](https://www.home-assistant.io/) but can be u
 
 - **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)
+- **23 endpoints** — public (server, character, corporation, universe) and authenticated (wallet, skills, location, industry, market, mail, notifications, clones, fatigue, contacts, calendar, loyalty, killmails)
 - **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
+- **Tested** — ≥98% test coverage
 
 ## Installation
 
@@ -76,7 +76,7 @@ asyncio.run(main())
 
 - [**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
+- [**Endpoints**](docs/endpoints.md) — full reference with field tables for all 23 methods
 - [**Error Handling**](docs/error-handling.md) — exception hierarchy, rate limiting, ESI cache times
 
 ## License

{python_eveonline-0.3.0 → python_eveonline-0.4.0}/README.md

@@ -13,10 +13,10 @@ Built for use with [Home Assistant](https://www.home-assistant.io/) but can be u
 
 - **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)
+- **23 endpoints** — public (server, character, corporation, universe) and authenticated (wallet, skills, location, industry, market, mail, notifications, clones, fatigue, contacts, calendar, loyalty, killmails)
 - **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
+- **Tested** — ≥98% test coverage
 
 ## Installation
 
@@ -44,7 +44,7 @@ asyncio.run(main())
 
 - [**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
+- [**Endpoints**](docs/endpoints.md) — full reference with field tables for all 23 methods
 - [**Error Handling**](docs/error-handling.md) — exception hierarchy, rate limiting, ESI cache times
 
 ## License

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

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

{python_eveonline-0.3.0 → python_eveonline-0.4.0}/src/eveonline/__init__.py

@@ -13,6 +13,7 @@ from .exceptions import (
     EveOnlineNotFoundError,
     EveOnlineRateLimitError,
 )
+from .models import CharacterKillmail
 
 try:
     __version__ = version("python-eveonline")
@@ -21,6 +22,7 @@ except PackageNotFoundError:
 
 __all__ = [
     "AbstractAuth",
+    "CharacterKillmail",
     "EveOnlineAuthenticationError",
     "EveOnlineClient",
     "EveOnlineConnectionError",

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

@@ -2,7 +2,9 @@
 
 from __future__ import annotations
 
-from datetime import datetime
+import contextlib
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
 from typing import Any, overload
 
 from aiohttp import ClientSession
@@ -20,6 +22,7 @@ from .models import (
     CalendarEvent,
     CharacterClones,
     CharacterContact,
+    CharacterKillmail,
     CharacterLocation,
     CharacterNotification,
     CharacterOnlineStatus,
@@ -87,8 +90,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]] = {}
+        # ETag cache: maps cache_key -> (etag, cached_response_data, x_pages, expires_at)
+        self._etag_cache: dict[str, tuple[str, Any, int, datetime | None]] = {}
 
         if auth is not None:
             self._session = auth.websession
@@ -135,18 +138,44 @@ class EveOnlineClient:
             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.
+    def _store_etag(self, method: str, cache_key: str, response: Any, data: Any, *, x_pages: int = 1) -> None:
+        """Cache the ETag and expiry 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.
+            x_pages: Total number of pages from the ``X-Pages`` header.
         """
         etag = response.headers.get("ETag")
         if method == "GET" and etag:
-            self._etag_cache[cache_key] = (etag, data)
+            self._etag_cache[cache_key] = (
+                etag,
+                data,
+                x_pages,
+                self._parse_expires(response),
+            )
+
+    @staticmethod
+    def _parse_expires(response: Any) -> datetime | None:
+        """Parse the ``Expires`` header into a timezone-aware datetime.
+
+        Args:
+            response: The aiohttp response object.
+
+        Returns:
+            A timezone-aware :class:`datetime` from the ``Expires`` header, or
+            ``None`` if the header is absent or cannot be parsed.
+        """
+        if not (expires_str := response.headers.get("Expires")):
+            return None
+        with contextlib.suppress(TypeError, ValueError):
+            parsed: datetime = parsedate_to_datetime(expires_str)
+            if parsed.tzinfo is None:
+                parsed = parsed.replace(tzinfo=UTC)
+            return parsed
+        return None
 
     @staticmethod
     def _parse_retry_after(response: Any) -> int | None:
@@ -166,12 +195,62 @@ class EveOnlineClient:
         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.
+    def _get_fresh_cached(self, method: str, cache_key: str) -> tuple[Any, int] | None:
+        """Return cached ``(data, x_pages)`` if the entry is still within its TTL.
+
+        Args:
+            method: HTTP method (only ``"GET"`` cache entries are considered).
+            cache_key: Cache key produced by :meth:`_etag_key`.
+
+        Returns:
+            A ``(data, x_pages)`` tuple if a fresh cache entry exists,
+            or ``None`` if the cache is empty, expired, or the method is not GET.
+        """
+        if method != "GET":
+            return None
+        cached = self._etag_cache.get(cache_key)
+        if cached is None or cached[3] is None:
+            return None
+        if datetime.now(UTC) < cached[3]:
+            return cached[1], cached[2]
+        return None
+
+    async def _finalize_response(self, method: str, cache_key: str, response: Any) -> tuple[Any, int]:
+        """Parse the response JSON, store ETag/Expires, and return ``(data, x_pages)``.
+
+        Used for any successful 2xx response. ETag/Expires-based caching is only
+        applied for ``GET`` requests (see :meth:`_store_etag`).
+
+        Args:
+            method: HTTP method used for the request.
+            cache_key: Cache key produced by :meth:`_etag_key`.
+            response: The aiohttp response object for a successful 2xx response.
 
-        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.
+        Returns:
+            A ``(data, x_pages)`` tuple ready to be returned by the caller.
+        """
+        data = await response.json()
+        try:
+            x_pages = int(response.headers.get("X-Pages", "1"))
+        except (TypeError, ValueError):
+            x_pages = 1
+        self._store_etag(method, cache_key, response, data, x_pages=x_pages)
+        return data, x_pages
+
+    async def _request_full(
+        self, method: str, path: str, *, authenticated: bool = False, **kwargs: Any
+    ) -> tuple[Any, int]:
+        """Make a request to the ESI API and return the data with pagination info.
+
+        Two caching layers are applied for GET requests:
+
+        1. **TTL caching** — if a cache entry exists with an ``Expires`` value
+           that has not passed, the cached data is returned immediately without
+           making any HTTP request.
+        2. **ETag caching** — when the TTL has expired (or no ``Expires`` was
+           stored), a ``If-None-Match`` header is sent if a cached ETag exists.
+           A ``304 Not Modified`` response returns the previously cached data
+           without downloading a response body.
 
         Args:
             method: HTTP method.
@@ -180,7 +259,9 @@ class EveOnlineClient:
             **kwargs: Additional arguments for the HTTP request.
 
         Returns:
-            Parsed JSON response.
+            A ``(data, x_pages)`` tuple where *data* is the parsed JSON
+            response and *x_pages* is the total number of pages from the
+            ``X-Pages`` response header (``1`` if the header is absent).
 
         Raises:
             EveOnlineAuthenticationError: If auth is required but not provided,
@@ -193,6 +274,11 @@ class EveOnlineClient:
         params: dict[str, Any] = dict(kwargs.pop("params", {}) or {})
         params.setdefault("datasource", ESI_DATASOURCE)
         cache_key = self._etag_key(path, params, authenticated)
+
+        # Short-circuit if the cached data is still fresh (Expires not yet reached).
+        if (fresh := self._get_fresh_cached(method, cache_key)) is not None:
+            return fresh
+
         headers = {**dict(kwargs.pop("headers", {}) or {}), **self._build_etag_headers(method, cache_key)}
 
         try:
@@ -222,6 +308,7 @@ class EveOnlineClient:
 
         if response.status == 304:
             # Not Modified — return the data we cached earlier if it still exists.
+            # Also refresh the Expires timestamp if the server sent an updated one.
             response.release()
             if (cached := self._etag_cache.get(cache_key)) is None:
                 msg = (
@@ -229,7 +316,9 @@ class EveOnlineClient:
                     f"cache entry exists for key {cache_key!r}."
                 )
                 raise EveOnlineError(msg)
-            return cached[1]
+            expires_at = self._parse_expires(response) or cached[3]
+            self._etag_cache[cache_key] = (cached[0], cached[1], cached[2], expires_at)
+            return cached[1], cached[2]
 
         if response.status == 404:
             response.release()
@@ -245,10 +334,56 @@ class EveOnlineClient:
             msg = f"ESI API error ({response.status}): {text}"
             raise EveOnlineError(msg)
 
-        data = await response.json()
-        self._store_etag(method, cache_key, response, data)
+        return await self._finalize_response(method, cache_key, response)
+
+    async def _request(self, method: str, path: str, *, authenticated: bool = False, **kwargs: Any) -> Any:
+        """Make a request to the ESI API.
+
+        Thin wrapper around :meth:`_request_full` that discards pagination
+        metadata. Use for non-paginated endpoints.
+
+        Args:
+            method: HTTP method.
+            path: API path relative to ESI base URL.
+            authenticated: Whether this request requires authentication.
+            **kwargs: Additional arguments for the HTTP request.
+
+        Returns:
+            Parsed JSON response.
+        """
+        data, _ = await self._request_full(method, path, authenticated=authenticated, **kwargs)
         return data
 
+    async def _request_all_pages(self, path: str, *, authenticated: bool = False, **kwargs: Any) -> list[Any]:
+        """Fetch all pages of a paginated ESI GET endpoint.
+
+        Sends ``?page=1``, reads the ``X-Pages`` response header to determine
+        the total page count, then fetches any remaining pages sequentially.
+        Results from all pages are combined into a single flat list.
+
+        Args:
+            path: API path relative to ESI base URL.
+            authenticated: Whether this request requires authentication.
+            **kwargs: Additional arguments forwarded to each page request.
+
+        Returns:
+            A flat list containing the combined JSON objects from all pages.
+        """
+        base_params: dict[str, Any] = dict(kwargs.pop("params", {}) or {})
+
+        page1_data, total_pages = await self._request_full(
+            "GET", path, authenticated=authenticated, params={**base_params, "page": 1}, **kwargs
+        )
+        all_data: list[Any] = list(page1_data)
+
+        for page in range(2, total_pages + 1):
+            page_data, _ = await self._request_full(
+                "GET", path, authenticated=authenticated, params={**base_params, "page": page}, **kwargs
+            )
+            all_data.extend(page_data)
+
+        return all_data
+
     @staticmethod
     @overload
     def _parse_datetime(value: str) -> datetime: ...
@@ -680,15 +815,19 @@ class EveOnlineClient:
     async def async_get_wallet_journal(self, character_id: int) -> list[WalletJournalEntry]:
         """Get a character's wallet journal (recent transactions).
 
+        All pages are fetched automatically. ESI returns up to 50 entries
+        per page; characters with long transaction histories will require
+        multiple pages.
+
         Requires scope: ``esi-wallet.read_character_wallet.v1``
 
         Args:
             character_id: The Eve Online character ID.
 
         Returns:
-            List of WalletJournalEntry entries, newest first.
+            List of WalletJournalEntry entries across all pages, newest first.
         """
-        data = await self._request("GET", f"characters/{character_id}/wallet/journal/", authenticated=True)
+        data = await self._request_all_pages(f"characters/{character_id}/wallet/journal/", authenticated=True)
         return [
             WalletJournalEntry(
                 id=entry["id"],
@@ -707,15 +846,18 @@ class EveOnlineClient:
     async def async_get_contacts(self, character_id: int) -> list[CharacterContact]:
         """Get a character's contacts.
 
+        All pages are fetched automatically. ESI returns up to 500 contacts
+        per page.
+
         Requires scope: ``esi-characters.read_contacts.v1``
 
         Args:
             character_id: The Eve Online character ID.
 
         Returns:
-            List of CharacterContact entries.
+            List of CharacterContact entries across all pages.
         """
-        data = await self._request("GET", f"characters/{character_id}/contacts/", authenticated=True)
+        data = await self._request_all_pages(f"characters/{character_id}/contacts/", authenticated=True)
         return [
             CharacterContact(
                 contact_id=entry["contact_id"],
@@ -770,3 +912,26 @@ class EveOnlineClient:
             )
             for entry in data
         ]
+
+    async def async_get_killmails(self, character_id: int) -> list[CharacterKillmail]:
+        """Get a character's recent killmail references.
+
+        All pages are fetched automatically. ESI returns up to 50 entries
+        per page; characters with high kill activity will require multiple pages.
+
+        Requires scope: ``esi-killmails.read_killmails.v1``
+
+        Args:
+            character_id: The Eve Online character ID.
+
+        Returns:
+            List of CharacterKillmail entries across all pages.
+        """
+        data = await self._request_all_pages(f"characters/{character_id}/killmails/recent/", authenticated=True)
+        return [
+            CharacterKillmail(
+                killmail_id=entry["killmail_id"],
+                killmail_hash=entry["killmail_hash"],
+            )
+            for entry in data
+        ]

{python_eveonline-0.3.0 → python_eveonline-0.4.0}/src/eveonline/models.py

@@ -455,3 +455,20 @@ class LoyaltyPoints:
 
     corporation_id: int
     loyalty_points: int
+
+
+@dataclass(frozen=True, slots=True)
+class CharacterKillmail:
+    """A killmail reference from a character's recent kill/loss history (requires auth).
+
+    This represents a reference to a killmail, not the full killmail detail.
+    Use the ``killmail_id`` and ``killmail_hash`` to fetch the full killmail
+    from ``GET /killmails/{killmail_id}/{killmail_hash}/`` if needed.
+
+    Attributes:
+        killmail_id: Unique killmail identifier.
+        killmail_hash: Hash string required to fetch the full killmail detail.
+    """
+
+    killmail_id: int
+    killmail_hash: str

{python_eveonline-0.3.0 → python_eveonline-0.4.0/src/python_eveonline.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-eveonline
-Version: 0.3.0
+Version: 0.4.0
 Summary: Async Python client for the Eve Online ESI API
 Author: Ronald van der Meer
 License-Expression: MIT
@@ -45,10 +45,10 @@ Built for use with [Home Assistant](https://www.home-assistant.io/) but can be u
 
 - **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)
+- **23 endpoints** — public (server, character, corporation, universe) and authenticated (wallet, skills, location, industry, market, mail, notifications, clones, fatigue, contacts, calendar, loyalty, killmails)
 - **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
+- **Tested** — ≥98% test coverage
 
 ## Installation
 
@@ -76,7 +76,7 @@ asyncio.run(main())
 
 - [**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
+- [**Endpoints**](docs/endpoints.md) — full reference with field tables for all 23 methods
 - [**Error Handling**](docs/error-handling.md) — exception hierarchy, rate limiting, ESI cache times
 
 ## License

{python_eveonline-0.3.0 → python_eveonline-0.4.0}/tests/test_client_authenticated.py

@@ -15,6 +15,7 @@ from eveonline.models import (
     CalendarEvent,
     CharacterClones,
     CharacterContact,
+    CharacterKillmail,
     CharacterLocation,
     CharacterNotification,
     CharacterOnlineStatus,
@@ -194,6 +195,14 @@ class TestAuthRequired:
             with pytest.raises(EveOnlineAuthenticationError):
                 await client.async_get_loyalty_points(CHARACTER_ID)
 
+    @pytest.mark.asyncio
+    async def test_killmails_without_auth_raises(self):
+        """Calling killmails endpoint without auth raises error."""
+        async with aiohttp.ClientSession() as session:
+            client = EveOnlineClient(session=session)
+            with pytest.raises(EveOnlineAuthenticationError):
+                await client.async_get_killmails(CHARACTER_ID)
+
 
 class TestCharacterOnline:
     """Test GET /characters/{character_id}/online/ endpoint."""
@@ -848,10 +857,10 @@ class TestWalletJournal:
 
     @pytest.mark.asyncio
     async def test_get_wallet_journal_success(self, wallet_journal_data):
-        """Successful wallet journal fetch."""
+        """Successful wallet journal fetch (single page)."""
         with aioresponses() as mocked:
             mocked.get(
-                f"{ESI_BASE_URL}/characters/{CHARACTER_ID}/wallet/journal/?datasource=tranquility",
+                f"{ESI_BASE_URL}/characters/{CHARACTER_ID}/wallet/journal/?datasource=tranquility&page=1",
                 payload=wallet_journal_data,
             )
             async with aiohttp.ClientSession() as session:
@@ -881,7 +890,7 @@ class TestWalletJournal:
         """No journal entries returns empty list."""
         with aioresponses() as mocked:
             mocked.get(
-                f"{ESI_BASE_URL}/characters/{CHARACTER_ID}/wallet/journal/?datasource=tranquility",
+                f"{ESI_BASE_URL}/characters/{CHARACTER_ID}/wallet/journal/?datasource=tranquility&page=1",
                 payload=[],
             )
             async with aiohttp.ClientSession() as session:
@@ -891,16 +900,58 @@ class TestWalletJournal:
 
         assert journal == []
 
+    @pytest.mark.asyncio
+    async def test_get_wallet_journal_multiple_pages(self):
+        """Wallet journal spanning two pages returns combined results."""
+        page1 = [
+            {
+                "id": 1,
+                "date": "2026-03-27T12:00:00Z",
+                "ref_type": "bounty_prizes",
+                "description": "Bounties",
+                "amount": 1000000.0,
+                "balance": 2000000.0,
+            }
+        ]
+        page2 = [
+            {
+                "id": 2,
+                "date": "2026-03-26T10:00:00Z",
+                "ref_type": "market_escrow",
+                "description": "Escrow",
+                "amount": -500000.0,
+                "balance": 1000000.0,
+            }
+        ]
+        with aioresponses() as mocked:
+            mocked.get(
+                f"{ESI_BASE_URL}/characters/{CHARACTER_ID}/wallet/journal/?datasource=tranquility&page=1",
+                payload=page1,
+                headers={"X-Pages": "2"},
+            )
+            mocked.get(
+                f"{ESI_BASE_URL}/characters/{CHARACTER_ID}/wallet/journal/?datasource=tranquility&page=2",
+                payload=page2,
+            )
+            async with aiohttp.ClientSession() as session:
+                auth = MockAuth(session)
+                client = EveOnlineClient(auth=auth)
+                journal = await client.async_get_wallet_journal(CHARACTER_ID)
+
+        assert len(journal) == 2
+        assert journal[0].id == 1
+        assert journal[1].id == 2
+
 
 class TestContacts:
     """Test GET /characters/{character_id}/contacts/ endpoint."""
 
     @pytest.mark.asyncio
     async def test_get_contacts_success(self, contacts_data):
-        """Successful contacts fetch."""
+        """Successful contacts fetch (single page)."""
         with aioresponses() as mocked:
             mocked.get(
-                f"{ESI_BASE_URL}/characters/{CHARACTER_ID}/contacts/?datasource=tranquility",
+                f"{ESI_BASE_URL}/characters/{CHARACTER_ID}/contacts/?datasource=tranquility&page=1",
                 payload=contacts_data,
             )
             async with aiohttp.ClientSession() as session:
@@ -930,7 +981,7 @@ class TestContacts:
         """No contacts returns empty list."""
         with aioresponses() as mocked:
             mocked.get(
-                f"{ESI_BASE_URL}/characters/{CHARACTER_ID}/contacts/?datasource=tranquility",
+                f"{ESI_BASE_URL}/characters/{CHARACTER_ID}/contacts/?datasource=tranquility&page=1",
                 payload=[],
             )
             async with aiohttp.ClientSession() as session:
@@ -940,6 +991,34 @@ class TestContacts:
 
         assert contacts == []
 
+    @pytest.mark.asyncio
+    async def test_get_contacts_multiple_pages(self):
+        """Contacts spanning two pages returns combined results."""
+        page1 = [
+            {"contact_id": 111, "contact_type": "character", "standing": 5.0},
+        ]
+        page2 = [
+            {"contact_id": 222, "contact_type": "corporation", "standing": -5.0},
+        ]
+        with aioresponses() as mocked:
+            mocked.get(
+                f"{ESI_BASE_URL}/characters/{CHARACTER_ID}/contacts/?datasource=tranquility&page=1",
+                payload=page1,
+                headers={"X-Pages": "2"},
+            )
+            mocked.get(
+                f"{ESI_BASE_URL}/characters/{CHARACTER_ID}/contacts/?datasource=tranquility&page=2",
+                payload=page2,
+            )
+            async with aiohttp.ClientSession() as session:
+                auth = MockAuth(session)
+                client = EveOnlineClient(auth=auth)
+                contacts = await client.async_get_contacts(CHARACTER_ID)
+
+        assert len(contacts) == 2
+        assert contacts[0].contact_id == 111
+        assert contacts[1].contact_id == 222
+
 
 class TestCalendar:
     """Test GET /characters/{character_id}/calendar/ endpoint."""
@@ -1028,3 +1107,85 @@ class TestLoyaltyPoints:
                 lp = await client.async_get_loyalty_points(CHARACTER_ID)
 
         assert lp == []
+
+
+class TestKillmails:
+    """Test GET /characters/{character_id}/killmails/recent/ endpoint."""
+
+    @pytest.mark.asyncio
+    async def test_get_killmails_success(self, killmails_data):
+        """Successful killmails fetch with multiple entries (single page)."""
+        with aioresponses() as mocked:
+            mocked.get(
+                f"{ESI_BASE_URL}/characters/{CHARACTER_ID}/killmails/recent/?datasource=tranquility&page=1",
+                payload=killmails_data,
+            )
+            async with aiohttp.ClientSession() as session:
+                auth = MockAuth(session)
+                client = EveOnlineClient(auth=auth)
+                killmails = await client.async_get_killmails(CHARACTER_ID)
+
+        assert len(killmails) == 2
+        assert all(isinstance(km, CharacterKillmail) for km in killmails)
+
+        first = killmails[0]
+        assert first.killmail_id == 112830692
+        assert first.killmail_hash == "a01f278642069a91c09009da6d4b0e0e4c6f9b20"
+
+        second = killmails[1]
+        assert second.killmail_id == 112830693
+        assert second.killmail_hash == "b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0"
+
+    @pytest.mark.asyncio
+    async def test_get_killmails_empty(self):
+        """No recent killmails returns empty list."""
+        with aioresponses() as mocked:
+            mocked.get(
+                f"{ESI_BASE_URL}/characters/{CHARACTER_ID}/killmails/recent/?datasource=tranquility&page=1",
+                payload=[],
+            )
+            async with aiohttp.ClientSession() as session:
+                auth = MockAuth(session)
+                client = EveOnlineClient(auth=auth)
+                killmails = await client.async_get_killmails(CHARACTER_ID)
+
+        assert killmails == []
+
+    @pytest.mark.asyncio
+    async def test_get_killmails_not_found_raises(self):
+        """HTTP 404 raises EveOnlineNotFoundError."""
+        with aioresponses() as mocked:
+            mocked.get(
+                f"{ESI_BASE_URL}/characters/{CHARACTER_ID}/killmails/recent/?datasource=tranquility&page=1",
+                status=404,
+                body="Character not found",
+            )
+            async with aiohttp.ClientSession() as session:
+                auth = MockAuth(session)
+                client = EveOnlineClient(auth=auth)
+                with pytest.raises(EveOnlineNotFoundError):
+                    await client.async_get_killmails(CHARACTER_ID)
+
+    @pytest.mark.asyncio
+    async def test_get_killmails_multiple_pages(self):
+        """Killmails spanning two pages returns combined results."""
+        page1 = [{"killmail_id": 100, "killmail_hash": "aaa"}]
+        page2 = [{"killmail_id": 101, "killmail_hash": "bbb"}]
+        with aioresponses() as mocked:
+            mocked.get(
+                f"{ESI_BASE_URL}/characters/{CHARACTER_ID}/killmails/recent/?datasource=tranquility&page=1",
+                payload=page1,
+                headers={"X-Pages": "2"},
+            )
+            mocked.get(
+                f"{ESI_BASE_URL}/characters/{CHARACTER_ID}/killmails/recent/?datasource=tranquility&page=2",
+                payload=page2,
+            )
+            async with aiohttp.ClientSession() as session:
+                auth = MockAuth(session)
+                client = EveOnlineClient(auth=auth)
+                killmails = await client.async_get_killmails(CHARACTER_ID)
+
+        assert len(killmails) == 2
+        assert killmails[0].killmail_id == 100
+        assert killmails[1].killmail_id == 101

{python_eveonline-0.3.0 → python_eveonline-0.4.0}/tests/test_etag_caching.py

@@ -2,6 +2,10 @@
 
 from __future__ import annotations
 
+import time
+from datetime import UTC, datetime
+from email.utils import formatdate
+
 import aiohttp
 import pytest
 from aioresponses import aioresponses
@@ -523,3 +527,127 @@ class TestETagEdgeCases:
             assert len(client._etag_cache) == 1
             client.clear_etag_cache()
             assert client._etag_cache == {}
+
+    @pytest.mark.asyncio
+    async def test_malformed_x_pages_header_defaults_to_single_page(self):
+        """A non-integer X-Pages header falls back to 1 without raising."""
+        with aioresponses() as mocked:
+            mocked.get(
+                f"{ESI_BASE_URL}/status/?datasource=tranquility",
+                payload={"players": 5000, "server_version": "DEADSPACE", "start_time": "2025-01-01T00:00:00Z"},
+                headers={"ETag": '"abc"', "X-Pages": "not-a-number"},
+            )
+            async with aiohttp.ClientSession() as session:
+                client = EveOnlineClient(session=session)
+                result = await client.async_get_server_status()
+
+        assert result.players == 5000
+        cache_key = client._etag_key("status/", {"datasource": "tranquility"}, authenticated=False)
+        assert client._etag_cache[cache_key][2] == 1
+
+
+class TestExpiresTTLCaching:
+    """Expires/TTL caching: skip HTTP when cached data is still fresh."""
+
+    @pytest.mark.asyncio
+    async def test_expires_stored_in_cache(self):
+        """A valid Expires header is parsed and stored as expires_at in the cache."""
+        future_expires = formatdate(time.time() + 3600, usegmt=True)
+        with aioresponses() as mocked:
+            mocked.get(
+                f"{ESI_BASE_URL}/status/?datasource=tranquility",
+                payload=_SERVER_STATUS,
+                headers={"ETag": '"abc"', "Expires": future_expires},
+            )
+            async with aiohttp.ClientSession() as session:
+                client = EveOnlineClient(session=session)
+                await client.async_get_server_status()
+
+        cache_key = client._etag_key("status/", {"datasource": "tranquility"}, authenticated=False)
+        expires_at = client._etag_cache[cache_key][3]
+        assert isinstance(expires_at, datetime)
+        assert expires_at > datetime.now(UTC)
+
+    @pytest.mark.asyncio
+    async def test_fresh_cache_skips_http_request(self):
+        """A cached entry with Expires in the future is returned without making an HTTP request."""
+        future_expires = formatdate(time.time() + 3600, usegmt=True)
+        url = f"{ESI_BASE_URL}/status/?datasource=tranquility"
+        async with aiohttp.ClientSession() as session:
+            client = EveOnlineClient(session=session)
+
+            with aioresponses() as mocked:
+                mocked.get(
+                    url,
+                    payload=_SERVER_STATUS,
+                    headers={"ETag": '"abc"', "Expires": future_expires},
+                )
+                result1 = await client.async_get_server_status()
+                # Second call — no additional mock registered; must be served from cache.
+                result2 = await client.async_get_server_status()
+
+        assert result1 == result2
+
+    @pytest.mark.asyncio
+    async def test_expired_cache_sends_etag_request(self):
+        """A cache entry with an expired Expires falls through to the ETag/If-None-Match flow."""
+        past_expires = formatdate(time.time() - 3600, usegmt=True)
+        async with aiohttp.ClientSession() as session:
+            client = EveOnlineClient(session=session)
+
+            with aioresponses() as mocked:
+                mocked.get(
+                    f"{ESI_BASE_URL}/status/?datasource=tranquility",
+                    payload=_SERVER_STATUS,
+                    headers={"ETag": '"abc"', "Expires": past_expires},
+                )
+                await client.async_get_server_status()
+
+            # TTL expired — expect an ETag request; ESI responds 304.
+            with aioresponses() as mocked:
+                mocked.get(
+                    f"{ESI_BASE_URL}/status/?datasource=tranquility",
+                    status=304,
+                )
+                result = await client.async_get_server_status()
+
+            # Verify that an HTTP request was made with the stored ETag.
+            assert mocked.requests, "Expected an HTTP request after cache expiry"
+            (_method, _url), calls = next(iter(mocked.requests.items()))
+            assert _method == "GET"
+            sent_headers = calls[0].kwargs.get("headers") or {}
+            assert sent_headers.get("If-None-Match") == '"abc"'
+
+        assert result.players == _SERVER_STATUS["players"]
+
+    @pytest.mark.asyncio
+    async def test_malformed_expires_stores_none(self):
+        """An unparseable Expires header stores None rather than raising."""
+        with aioresponses() as mocked:
+            mocked.get(
+                f"{ESI_BASE_URL}/status/?datasource=tranquility",
+                payload=_SERVER_STATUS,
+                headers={"ETag": '"abc"', "Expires": "not-a-valid-date"},
+            )
+            async with aiohttp.ClientSession() as session:
+                client = EveOnlineClient(session=session)
+                await client.async_get_server_status()
+
+        cache_key = client._etag_key("status/", {"datasource": "tranquility"}, authenticated=False)
+        assert client._etag_cache[cache_key][3] is None
+
+    @pytest.mark.asyncio
+    async def test_no_expires_header_stores_none(self):
+        """A response without an Expires header stores None as expires_at."""
+        with aioresponses() as mocked:
+            mocked.get(
+                f"{ESI_BASE_URL}/status/?datasource=tranquility",
+                payload=_SERVER_STATUS,
+                headers={"ETag": '"abc"'},
+            )
+            async with aiohttp.ClientSession() as session:
+                client = EveOnlineClient(session=session)
+                await client.async_get_server_status()
+
+        cache_key = client._etag_key("status/", {"datasource": "tranquility"}, authenticated=False)
+        assert client._etag_cache[cache_key][3] is None