forceupdate 0.1.0__py3-none-any.whl

forceupdate/parsers/toml_spans.py

@@ -0,0 +1,297 @@
+"""Retrouver où sont écrites les chaînes d'un document TOML.
+
+``tomllib`` donne les valeurs d'un document, pas leur position. Ce module parcourt
+le texte d'un document que ``tomllib`` a déjà accepté, et rend, pour chaque chaîne
+écrite sur une seule ligne, sa ligne et ses colonnes. C'est ce qui donne
+l'emplacement exact d'une contrainte dans un ``pyproject.toml`` ou un ``Pipfile``,
+pour la réécrire sans toucher au reste (E10).
+
+Une chaîne est repérée par son chemin dans le document, le même que dans ce que
+rend ``tomllib`` : des clés et des indices de tableaux. ``dependencies = ["a", "b"]``
+dans ``[project]`` donne ``("project", "dependencies", 1)`` pour ``"b"`` ; le
+troisième ``[[package]]`` d'un lockfile donne ``("package", 2, …)``.
+"""
+
+import bisect
+import logging
+from dataclasses import dataclass
+
+from forceupdate.models import Location
+
+logger = logging.getLogger(__name__)
+
+TomlPath = tuple[str | int, ...]
+"""Le chemin d'une valeur : clés et indices de tableaux, comme dans ``tomllib``."""
+
+_BARE_KEY_CHARS = frozenset("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-")
+_ESCAPE_LENGTHS = {"u": 6, "U": 10, "x": 4}
+"""Longueur écrite des échappements qui ne font pas deux caractères (``\\u00e9``…)."""
+_SIMPLE_ESCAPES = {"b": "\b", "t": "\t", "n": "\n", "f": "\f", "r": "\r", "e": "\x1b"}
+
+
+@dataclass(frozen=True)
+class StringSpan:
+    """Une chaîne TOML écrite sur une seule ligne, et sa position.
+
+    Sert aussi aux chaînes JSON (``json_spans``) : leurs échappements sont ceux de
+    TOML, plus les paires de substituts (``\\ud83d\\ude00``), qui font un seul caractère.
+    """
+
+    line: int
+    """Sa ligne, à partir de 1."""
+    column: int
+    """Colonne du premier caractère après le guillemet ouvrant, à partir de 0."""
+    raw: str
+    """Le contenu tel qu'il est écrit, sans les guillemets (échappements compris)."""
+    literal: bool
+    """Vrai pour une chaîne littérale (``'…'``), qui n'a pas d'échappements."""
+
+    def location(self, start: int, end: int) -> Location | None:
+        """L'emplacement des caractères ``start`` à ``end`` (exclu) de la valeur décodée.
+
+        ``None`` si ce morceau contient un échappement (``\\"``…) : le texte écrit
+        n'y est pas la valeur, on ne saurait pas le réécrire.
+        """
+        offsets = self._offsets()
+        if not 0 <= start <= end < len(offsets):
+            return None
+        first, last = offsets[start], offsets[end]
+        if last - first != end - start:
+            return None
+        return Location(line=self.line, column=self.column + first, end_column=self.column + last)
+
+    def _offsets(self) -> list[int]:
+        """Pour chaque caractère de la valeur décodée, sa colonne dans ``raw`` ; plus la fin."""
+        if self.literal:
+            return list(range(len(self.raw) + 1))
+        offsets = []
+        index = 0
+        while index < len(self.raw):
+            offsets.append(index)
+            if self.raw[index] == "\\":
+                length = _ESCAPE_LENGTHS.get(self.raw[index + 1 : index + 2], 2)
+                if length == 6 and _starts_surrogate_pair(self.raw, index):
+                    length = 12
+                index += length
+            else:
+                index += 1
+        offsets.append(len(self.raw))
+        return offsets
+
+
+def _starts_surrogate_pair(raw: str, index: int) -> bool:
+    """Vrai si ``raw[index:]`` commence par deux ``\\uXXXX`` qui forment une paire de
+    substituts (JSON) : ``json`` les décode en un seul caractère."""
+    if not raw.startswith("\\u", index + 6):
+        return False
+    try:
+        high = int(raw[index + 2 : index + 6], 16)
+        low = int(raw[index + 8 : index + 12], 16)
+    except ValueError:
+        return False
+    return 0xD800 <= high <= 0xDBFF and 0xDC00 <= low <= 0xDFFF
+
+
+def string_spans(text: str) -> dict[TomlPath, StringSpan]:
+    """Les chaînes sur une ligne du document TOML ``text``, par chemin.
+
+    ``text`` doit avoir été accepté par ``tomllib`` : il n'est pas revalidé. Les
+    chaînes sur plusieurs lignes (``\"\"\"…\"\"\"``) ne sont pas rendues. Les lignes
+    sont comptées sur ``\\n`` seulement, comme ``Location``.
+    """
+    scanner = _Scanner(text)
+    try:
+        scanner.document()
+    except (IndexError, ValueError) as err:
+        # Ne devrait pas arriver sur un document valide : on garde ce qui a été trouvé.
+        logger.debug("TOML parcouru en partie seulement : %s", err)
+    return scanner.spans
+
+
+def decode_basic_string(raw: str) -> str:
+    """Décode le contenu d'une chaîne TOML entre guillemets doubles (``\\"``, ``\\u00e9``…)."""
+    chars = []
+    index = 0
+    while index < len(raw):
+        char = raw[index]
+        if char != "\\":
+            chars.append(char)
+            index += 1
+            continue
+        kind = raw[index + 1]
+        if kind in _ESCAPE_LENGTHS:
+            length = _ESCAPE_LENGTHS[kind]
+            chars.append(chr(int(raw[index + 2 : index + length], 16)))
+            index += length
+        else:
+            chars.append(_SIMPLE_ESCAPES.get(kind, kind))
+            index += 2
+    return "".join(chars)
+
+
+class _Scanner:
+    """Parcourt un document TOML valide et note la position des chaînes."""
+
+    def __init__(self, text: str) -> None:
+        self.text = text
+        self.pos = 0
+        self.spans: dict[TomlPath, StringSpan] = {}
+        self._line_starts = [0] + [i + 1 for i, char in enumerate(text) if char == "\n"]
+        self._array_tables: dict[TomlPath, int] = {}
+        """Dernier indice de chaque tableau de tables (``[[package]]``)."""
+
+    def document(self) -> None:
+        table: TomlPath = ()
+        while True:
+            self._skip_blank()
+            if self.pos >= len(self.text):
+                return
+            if self.text[self.pos] == "[":
+                table = self._header()
+            else:
+                self._key_value(table)
+
+    def _header(self) -> TomlPath:
+        """Lit ``[a.b]`` ou ``[[a.b]]`` ; rend le chemin de la table ainsi ouverte."""
+        self.pos += 1
+        array = self.text[self.pos] == "["
+        if array:
+            self.pos += 1
+        keys = self._key()
+        self._skip_spaces()
+        self.pos += 2 if array else 1
+        path: TomlPath = ()
+        for i, key in enumerate(keys):
+            path = (*path, key)
+            if array and i == len(keys) - 1:
+                index = self._array_tables.get(path, -1) + 1
+                self._array_tables[path] = index
+                return (*path, index)
+            if path in self._array_tables:
+                path = (*path, self._array_tables[path])
+        return path
+
+    def _key_value(self, table: TomlPath) -> None:
+        keys = self._key()
+        self._skip_spaces()
+        self.pos += 1  # le signe =
+        self._skip_spaces()
+        self._value((*table, *keys))
+
+    def _key(self) -> list[str]:
+        """Lit une clé, pointée ou non (``a."b c".d``)."""
+        keys = []
+        while True:
+            self._skip_spaces()
+            char = self.text[self.pos]
+            if char == '"':
+                start = self.pos + 1
+                self._skip_basic_string()
+                keys.append(decode_basic_string(self.text[start : self.pos - 1]))
+            elif char == "'":
+                start = self.pos + 1
+                self.pos = self.text.index("'", start) + 1
+                keys.append(self.text[start : self.pos - 1])
+            else:
+                start = self.pos
+                while self.text[self.pos] in _BARE_KEY_CHARS:
+                    self.pos += 1
+                if self.pos == start:
+                    raise ValueError(f"clé attendue à la position {start}")
+                keys.append(self.text[start : self.pos])
+            self._skip_spaces()
+            if self.text[self.pos] != ".":
+                return keys
+            self.pos += 1
+
+    def _value(self, path: TomlPath) -> None:
+        char = self.text[self.pos]
+        if self.text.startswith(('"""', "'''"), self.pos):
+            self._skip_multiline_string()
+        elif char == '"':
+            start = self.pos + 1
+            self._skip_basic_string()
+            self._record(path, start, self.pos - 1, literal=False)
+        elif char == "'":
+            start = self.pos + 1
+            self.pos = self.text.index("'", start) + 1
+            self._record(path, start, self.pos - 1, literal=True)
+        elif char == "[":
+            self._array(path)
+        elif char == "{":
+            self._inline_table(path)
+        else:
+            # Nombre, booléen, date : on passe jusqu'au prochain séparateur.
+            while self.pos < len(self.text) and self.text[self.pos] not in ",]}#\r\n":
+                self.pos += 1
+
+    def _array(self, path: TomlPath) -> None:
+        self.pos += 1
+        index = 0
+        while True:
+            self._skip_blank()
+            if self.text[self.pos] == "]":
+                self.pos += 1
+                return
+            self._value((*path, index))
+            index += 1
+            self._skip_blank()
+            if self.text[self.pos] == ",":
+                self.pos += 1
+
+    def _inline_table(self, path: TomlPath) -> None:
+        self.pos += 1
+        while True:
+            self._skip_blank()
+            if self.text[self.pos] == "}":
+                self.pos += 1
+                return
+            self._key_value(path)
+            self._skip_blank()
+            if self.text[self.pos] == ",":
+                self.pos += 1
+
+    def _skip_basic_string(self) -> None:
+        """Avance après une chaîne ``"…"`` ; ``pos`` est sur le guillemet ouvrant."""
+        index = self.pos + 1
+        while self.text[index] != '"':
+            index += 2 if self.text[index] == "\\" else 1
+        self.pos = index + 1
+
+    def _skip_multiline_string(self) -> None:
+        quote = self.text[self.pos : self.pos + 3]
+        index = self.pos + 3
+        while not self.text.startswith(quote, index):
+            index += 2 if quote == '"""' and self.text[index] == "\\" else 1
+        index += 3
+        # Jusqu'à deux guillemets de plus collés à la fin font partie du contenu.
+        extra = 0
+        while extra < 2 and index < len(self.text) and self.text[index] == quote[0]:
+            index += 1
+            extra += 1
+        self.pos = index
+
+    def _record(self, path: TomlPath, start: int, end: int, *, literal: bool) -> None:
+        line = bisect.bisect_right(self._line_starts, start)
+        self.spans[path] = StringSpan(
+            line=line,
+            column=start - self._line_starts[line - 1],
+            raw=self.text[start:end],
+            literal=literal,
+        )
+
+    def _skip_spaces(self) -> None:
+        while self.pos < len(self.text) and self.text[self.pos] in " \t":
+            self.pos += 1
+
+    def _skip_blank(self) -> None:
+        """Passe les espaces, les fins de ligne et les commentaires."""
+        while self.pos < len(self.text):
+            char = self.text[self.pos]
+            if char in " \t\r\n":
+                self.pos += 1
+            elif char == "#":
+                end = self.text.find("\n", self.pos)
+                self.pos = len(self.text) if end == -1 else end
+            else:
+                return

forceupdate/registries/__init__.py

@@ -0,0 +1,52 @@
+"""Les registres : ce que chacun dit d'un paquet (versions, dernière stable, dépréciation).
+
+Un client par registre, derrière l'interface de ``base.py``. Pour une session :
+
+    async with HttpClient() as http:
+        registry = for_ecosystem(Ecosystem.NPM, http, Cache.default())
+        info = await registry.package("lodash")  # PackageInfo
+        info.latest  # "4.17.21"
+
+PyPI et npm pour l'instant ; les autres registres arrivent avec leur étape (E21-E26).
+"""
+
+from forceupdate.models import Ecosystem
+from forceupdate.net.cache import Cache
+from forceupdate.net.http import HttpClient
+from forceupdate.registries.base import (
+    PackageInfo,
+    PackageNotFound,
+    PackageVersion,
+    Registry,
+    RegistryError,
+)
+from forceupdate.registries.npm import Npm
+from forceupdate.registries.pypi import PyPI
+
+__all__ = [
+    "PackageInfo",
+    "PackageNotFound",
+    "PackageVersion",
+    "Registry",
+    "RegistryError",
+    "for_ecosystem",
+]
+
+_REGISTRIES: dict[Ecosystem, type[Registry]] = {
+    Ecosystem.PYPI: PyPI,
+    Ecosystem.NPM: Npm,
+}
+
+
+def for_ecosystem(ecosystem: Ecosystem, http: HttpClient, cache: Cache) -> Registry:
+    """Un client du registre de ``ecosystem``, pour la session ; ``LookupError`` s'il n'est pas
+    encore géré.
+
+    Garder l'instance pour toute la session : c'est elle qui fait qu'un paquet n'est demandé
+    qu'une fois.
+    """
+    try:
+        registry = _REGISTRIES[ecosystem]
+    except KeyError:
+        raise LookupError(f"registre {ecosystem} pas encore géré par forceupdate.") from None
+    return registry(http, cache)

forceupdate/registries/base.py

@@ -0,0 +1,294 @@
+"""Ce que les registres disent d'un paquet : ses versions, la dernière stable, sa dépréciation.
+
+Un client par registre (PyPI et npm, puis ceux de la phase F), derrière une même
+interface. Pour un paquet, trois issues :
+
+- ``PackageInfo`` : le registre le connaît ;
+- ``PackageNotFound`` : il ne le connaît pas (paquet privé, faute de frappe). Le constat
+  est « non vérifiable », ce n'est pas une erreur fatale ;
+- ``RegistryError`` : pas de réponse exploitable (réseau, hors ligne sans cache, réponse
+  illisible). Le constat est « non concluant », jamais faux.
+
+Les versions restent des chaînes, telles que le registre les donne. Elles s'interprètent
+avec ``forceupdate.versions`` ; une version que ses règles ne savent pas lire (un vieux
+paquet PyPI hors PEP 440) est gardée, mais n'est jamais candidate.
+
+Une réponse est réduite à ce qui sert, puis rangée dans le cache disque (``CacheKind.
+VERSIONS``, 1 h), un « introuvable » aussi. Une erreur ne l'est pas.
+"""
+
+import asyncio
+import functools
+from abc import ABC, abstractmethod
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any, ClassVar
+
+from forceupdate import versions
+from forceupdate.models import Ecosystem
+from forceupdate.net.cache import Cache, CacheEntry, CacheKind
+from forceupdate.net.http import HttpClient, NetworkError, Response
+from forceupdate.versions import InvalidVersion
+
+_FORMAT = 1
+"""Version du format des entrées du cache : une autre est ignorée, et le registre réinterrogé."""
+
+
+class PackageNotFound(LookupError):
+    """Le registre ne connaît pas le paquet : paquet privé, ou faute de frappe.
+
+    Le message, en français, est fait pour être montré tel quel dans le rapport.
+    """
+
+
+class RegistryError(Exception):
+    """Le registre n'a pas donné de réponse exploitable : réseau, mode hors ligne sans
+    cache, statut inattendu, réponse illisible.
+
+    Le message, en français, est fait pour être montré tel quel dans le rapport.
+    """
+
+
+@dataclass(frozen=True, kw_only=True)
+class PackageVersion:
+    """Une version publiée d'un paquet."""
+
+    version: str
+    """Telle que le registre l'écrit."""
+    published: datetime | None = None
+    """Date de publication (UTC) ; ``None`` si le registre ne la donne pas."""
+    yanked: bool = False
+    """Retirée : on ne la propose plus, et l'utiliser est un constat. Sur PyPI, quand tous
+    ses fichiers sont « yanked ». npm n'a pas de retrait : une version dépubliée disparaît."""
+    yanked_reason: str | None = None
+    """La raison du retrait donnée par le registre, s'il y en a une."""
+    deprecated: str | None = None
+    """npm : le message de dépréciation de cette version ; ``None`` si elle ne l'est pas."""
+
+
+@dataclass(frozen=True, kw_only=True)
+class PackageInfo:
+    """Ce qu'un registre dit d'un paquet."""
+
+    ecosystem: Ecosystem
+    name: str
+    """Le nom tel que le registre le connaît (normalisé selon PEP 503 pour PyPI)."""
+    versions: tuple[PackageVersion, ...]
+    """Toutes les versions publiées, de la plus ancienne à la plus récente ; les versions
+    illisibles à la fin."""
+    latest: str | None
+    """La dernière stable, celle qu'on propose (voir chaque registre pour sa règle) ; ``None``
+    s'il n'y en a pas (que des pré-versions, ou des versions retirées)."""
+    deprecated: str | None = None
+    """Le paquet entier est déprécié, abandonné ou retiré : le message à montrer (celui du
+    registre quand il en donne un) ; ``None`` sinon."""
+    tags: Mapping[str, str] = field(default_factory=dict)
+    """npm : les étiquettes (``dist-tags``) et leur version, ``{"latest": "4.17.21", "next":
+    …}``. Une dépendance écrite avec une étiquette suit celle-ci. Vide pour PyPI."""
+    url: str | None = None
+    """La page du paquet, pour en savoir plus."""
+    fetched_at: datetime
+    """Quand le registre a répondu (UTC) : plus ancien si la réponse vient du cache."""
+
+    def get(self, version: str) -> PackageVersion | None:
+        """La version publiée ``version`` : même texte, sinon même version selon les règles de
+        l'écosystème (``1.8c1`` et ``1.8rc1`` sur PyPI). ``None`` si elle n'est pas publiée."""
+        found = self._by_text.get(version)
+        if found is not None:
+            return found
+        try:
+            return self._by_parsed.get(versions.for_ecosystem(self.ecosystem).parse(version))
+        except InvalidVersion:
+            return None
+
+    def available(self) -> list[str]:
+        """Les versions qu'on peut proposer, de la plus ancienne à la plus récente : toutes sauf
+        les retirées. C'est la liste à donner à ``versions`` (``latest``, ``max_satisfying``)."""
+        return [v.version for v in self.versions if not v.yanked]
+
+    @functools.cached_property
+    def _by_text(self) -> dict[str, PackageVersion]:
+        return {v.version: v for v in self.versions}
+
+    @functools.cached_property
+    def _by_parsed(self) -> dict[Any, PackageVersion]:
+        scheme = versions.for_ecosystem(self.ecosystem)
+        found = {}
+        for v in self.versions:
+            try:
+                found.setdefault(scheme.parse(v.version), v)
+            except InvalidVersion:
+                continue
+        return found
+
+
+class Registry(ABC):
+    """Le client d'un registre : ``await registry.package(nom)``.
+
+    Une instance par session, avec le client HTTP et le cache de la session : un paquet
+    n'y est demandé qu'une fois, même si plusieurs projets le demandent en même temps.
+    """
+
+    ecosystem: Ecosystem
+    label: str
+    """Le nom du registre dans les messages (``PyPI``, ``npm``)."""
+    base_url: str
+    """L'adresse du registre public, sans ``/`` final."""
+    headers: ClassVar[Mapping[str, str]] = {}
+    """En-têtes des requêtes (le format de réponse voulu)."""
+
+    def __init__(self, http: HttpClient, cache: Cache, *, base_url: str | None = None) -> None:
+        self._http = http
+        self._cache = cache
+        if base_url is not None:
+            self.base_url = base_url.rstrip("/")
+        self._lookups: dict[str, asyncio.Future[PackageInfo]] = {}
+
+    # -- à écrire pour chaque registre ------------------------------------------
+
+    @abstractmethod
+    def normalize(self, name: str) -> str:
+        """Le nom tel que le registre le connaît (``Flask`` → ``flask`` pour PyPI)."""
+
+    @abstractmethod
+    def url_for(self, name: str) -> str:
+        """L'URL à interroger pour le paquet ``name``, déjà normalisé."""
+
+    @abstractmethod
+    def page_url(self, name: str) -> str | None:
+        """La page web du paquet ; ``None`` si on ne la connaît pas (registre privé)."""
+
+    @abstractmethod
+    def parse(self, name: str, response: Response, fetched_at: datetime) -> PackageInfo:
+        """Lit la réponse (statut 200) ; lève ``ValueError`` si elle est illisible."""
+
+    # -- commun --------------------------------------------------------------
+
+    async def package(self, name: str) -> PackageInfo:
+        """Ce que le registre dit du paquet ``name``.
+
+        Lève ``PackageNotFound`` s'il ne le connaît pas, ``RegistryError`` sans réponse
+        exploitable. Une seule requête par paquet dans la session : les appels suivants, ou
+        simultanés, rendent la même réponse (ou la même erreur).
+        """
+        key = self.normalize(name)
+        lookup = self._lookups.get(key)
+        if lookup is None:
+            lookup = self._lookups[key] = asyncio.ensure_future(self._lookup(key))
+        # shield : un appelant annulé n'annule pas la requête que d'autres attendent.
+        return await asyncio.shield(lookup)
+
+    async def _lookup(self, name: str) -> PackageInfo:
+        url = self.url_for(name)
+        entry = self._cache.get(CacheKind.VERSIONS, url, stale_ok=self._http.offline)
+        if entry is not None:
+            cached = self._from_cache(name, entry)
+            if cached is not None:
+                return cached
+        if self._http.offline:
+            raise RegistryError(
+                f"{self.label} : mode hors ligne, et {name} n'est pas dans le cache."
+            )
+        try:
+            response = await self._http.get(url, headers=self.headers)
+        except NetworkError as error:
+            raise RegistryError(f"{self.label} : {error}") from error
+        if response.status_code == 404:
+            self._cache.set(CacheKind.VERSIONS, url, {"format": _FORMAT, "not_found": True})
+            raise PackageNotFound(self._not_found(name))
+        if response.status_code != 200:
+            raise RegistryError(
+                f"{self.label} : réponse inattendue pour {name} (HTTP {response.status_code})."
+            )
+        try:
+            info = self.parse(name, response, datetime.now(UTC))
+        except (ValueError, KeyError, TypeError) as error:
+            # Une réponse d'un format inconnu n'arrête pas l'analyse : elle est non concluante.
+            raise RegistryError(
+                f"{self.label} : réponse illisible pour {name} ({error})."
+            ) from error
+        self._cache.set(CacheKind.VERSIONS, url, _info_to_cache(info))
+        return info
+
+    def _not_found(self, name: str) -> str:
+        return f"{name} est introuvable sur {self.label} : paquet privé, ou nom mal écrit ?"
+
+    def _from_cache(self, name: str, entry: CacheEntry) -> PackageInfo | None:
+        """L'entrée du cache relue ; lève ``PackageNotFound`` pour un « introuvable » rangé,
+        ``None`` pour une entrée d'un autre format."""
+        value = entry.value
+        if not isinstance(value, dict) or value.get("format") != _FORMAT:
+            return None
+        if value.get("not_found"):
+            raise PackageNotFound(self._not_found(name))
+        try:
+            return _info_from_cache(self.ecosystem, value, entry.stored_at)
+        except (ValueError, KeyError, TypeError):
+            return None
+
+
+def sorted_versions(
+    ecosystem: Ecosystem, found: Iterable[PackageVersion]
+) -> tuple[PackageVersion, ...]:
+    """Les versions de la plus ancienne à la plus récente, les illisibles à la fin."""
+    key = versions.for_ecosystem(ecosystem).sort_key
+    return tuple(sorted(found, key=lambda v: key(v.version)))
+
+
+def parse_time(value: object) -> datetime | None:
+    """Une date ISO 8601 du registre (``2021-05-21T15:53:08.128824Z``), en UTC ; ``None`` si
+    elle manque ou est illisible."""
+    if not isinstance(value, str):
+        return None
+    try:
+        when = datetime.fromisoformat(value)
+    except ValueError:
+        return None
+    return when.replace(tzinfo=UTC) if when.tzinfo is None else when.astimezone(UTC)
+
+
+def _info_to_cache(info: PackageInfo) -> dict[str, Any]:
+    return {
+        "format": _FORMAT,
+        "name": info.name,
+        "versions": [
+            [
+                v.version,
+                None if v.published is None else v.published.isoformat(),
+                v.yanked,
+                v.yanked_reason,
+                v.deprecated,
+            ]
+            for v in info.versions
+        ],
+        "latest": info.latest,
+        "deprecated": info.deprecated,
+        "tags": dict(info.tags),
+        "url": info.url,
+    }
+
+
+def _info_from_cache(
+    ecosystem: Ecosystem, value: dict[str, Any], stored_at: datetime
+) -> PackageInfo:
+    found = tuple(
+        PackageVersion(
+            version=version,
+            published=parse_time(published),
+            yanked=yanked,
+            yanked_reason=reason,
+            deprecated=deprecated,
+        )
+        for version, published, yanked, reason, deprecated in value["versions"]
+    )
+    return PackageInfo(
+        ecosystem=ecosystem,
+        name=value["name"],
+        versions=found,
+        latest=value["latest"],
+        deprecated=value["deprecated"],
+        tags=dict(value["tags"]),
+        url=value["url"],
+        fetched_at=stored_at,
+    )