ceps-api 0.1.0__py3-none-any.whl

ceps_api/convert.py

@@ -0,0 +1,88 @@
+"""Functions for converting between the wrapper interface and the service interface, and for turning service responses into DataFrames."""
+from __future__ import annotations
+
+from collections.abc import Iterable
+from datetime import date, datetime
+from typing import cast
+
+import pandas as pd
+
+from .models import CepsResponseType
+from .parsing import PRAGUE, Fields, Parsed, Rows, TimeSeries
+
+# What the wrappers take as start and end.
+DateLike = date | datetime | str
+#----------------------------------------------------------------------------------------------------------------------------
+
+def to_ceps_time(x: DateLike) -> str:
+    """
+    Accepts a date, datetime or ISO string ('YYYY-MM-DD', with a time or
+    without), gives the timestamp ČEPS wants, which is Czech local time
+    with no zone on it. One with a timezone is converted to Czech time
+    first; a naive one is taken as Czech time already.
+
+    The zone has to come off because the service does not read it: it
+    answers '...T10:00:00Z' with the data of 10:00 Czech time.
+
+    Local time cannot tell apart the two runs of the hour repeated when the
+    clocks go back. The service takes such a time as the second run; a
+    period that starts before 02:00 covers both. A time in the hour skipped
+    in spring is moved an hour on.
+
+    Raises ValueError for a string that is not a date or time.
+    """
+    if isinstance(x, str):
+        try:
+            # fromisoformat does not know the Z of UTC before Python 3.11.
+            x = datetime.fromisoformat(x[:-1] + "+00:00" if x[-1:] in ("Z", "z") else x)
+        except ValueError:
+            raise ValueError(f"not a date or time: {x!r}, expected e.g. "
+                             "'2026-09-14' or '2026-09-14T10:00:00'") from None
+    if isinstance(x, datetime):
+        if x.tzinfo is not None:
+            x = x.astimezone(PRAGUE)
+        return x.strftime("%Y-%m-%dT%H:%M:%S")
+    return x.strftime("%Y-%m-%dT00:00:00")
+#----------------------------------------------------------------------------------------------------------------------------
+
+def _prague(values: Iterable[datetime]) -> pd.DatetimeIndex:
+    """
+    Datetimes with mixed +01:00/+02:00 offsets -> one Europe/Prague index.
+    Through UTC, so the repeated hour of the DST change stays two hours.
+    """
+    return pd.DatetimeIndex(pd.to_datetime(list(values), utc=True)).tz_convert(PRAGUE)
+#----------------------------------------------------------------------------------------------------------------------------
+
+def to_dataframe(response_type: CepsResponseType, data: Parsed) -> pd.DataFrame:
+    """
+    What the parser returns -> a DataFrame:
+
+      SERIES, ESTIMATED_PRICE  index "timestamp" (Europe/Prague), a column per series
+      TABLE                    a row per row, date columns in Europe/Prague
+      CODES                    index "code", column "description"
+      MESSAGE                  one row, a column per field
+    """
+    # The response type decides the shape of data, which the casts tell the type checker.
+    if response_type in (CepsResponseType.SERIES, CepsResponseType.ESTIMATED_PRICE):
+        series = cast(TimeSeries, data)
+        if not series:
+            return pd.DataFrame(index=pd.DatetimeIndex([], tz=PRAGUE, name="timestamp"))
+        df = pd.DataFrame(list(series.values()), index=_prague(series))
+        df.index.name = "timestamp"
+        return df.sort_index()
+    if response_type is CepsResponseType.TABLE:
+        df = pd.DataFrame(cast(Rows, data))
+        for col in df.columns:
+            # A column of dates only; one the parser left as text stays text.
+            values = df[col].dropna()
+            if len(values) and values.map(lambda v: isinstance(v, datetime)).all():
+                df[col] = pd.Series(_prague(df[col]), index=df.index)
+        if "date" in df.columns:
+            df = df.sort_values("date", kind="stable", ignore_index=True)
+        return df
+    fields = cast(Fields, data)
+    if response_type is CepsResponseType.CODES:
+        return pd.DataFrame({"description": pd.Series(fields, dtype=object)}).rename_axis("code")
+    # MESSAGE
+    return pd.DataFrame([fields]) if fields else pd.DataFrame()
+#----------------------------------------------------------------------------------------------------------------------------

ceps_api/models.py

@@ -0,0 +1,63 @@
+"""
+Types describing the methods of the ČEPS service used in catalog.py
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+#----------------------------------------------------------------------------------------------------------------------------
+class CepsResponseType(Enum):
+    """The shape of a method's response, which decides the parser the wrappers use."""
+
+    # A plain time series: rows with a date and one value per series.
+    SERIES = "series"
+    # A time series whose rows have no date attribute (OdhadovanaCenaOdchylky).
+    ESTIMATED_PRICE = "estimated_price"
+    # Rows that are not one per timestamp: several share a date or they have
+    # none at all (EmergencyExchange, OfferPrices).
+    TABLE = "table"
+    # A list of codes with their descriptions (DataVersion, DataAgregation).
+    CODES = "codes"
+    # A single message of text fields (EmergencyExchangeACER).
+    MESSAGE = "message"
+#----------------------------------------------------------------------------------------------------------------------------
+@dataclass(frozen=True)
+class CepsMethod:
+    """What is known about one method of the ČEPS service."""
+
+    # The method description is by personal understanding, check the ČEPS documentation
+    # to see full description (it is in Czech and too long to put here).
+    description: str
+
+    # Parameters the WSDL marks as compulsory.
+    # Most methods need the dates; a few require nothing.
+    required_params: tuple[str, ...] = ("dateFrom", "dateTo")
+
+    # Parameters the WSDL marks as optional.
+    optional_params: tuple[str, ...] = ()
+
+    # Needed parameters the service does not work without: it answers
+    # with a server error instead of data.
+    needed_params: tuple[str, ...] = ()
+
+    # The aggregations the method returns data for, from the ČEPS documentation and
+    # checked by trying. None means not known, so any aggregation is let through.
+    aggregations: tuple[str, ...] | None = None
+
+    # The data versions the method has, from the ČEPS documentation and
+    # checked by trying; any other comes back empty. None means not known,
+    # so any version is let through.
+    versions: tuple[str, ...] | None = None
+
+    # The values a filter parameter (param1, para1, param2) takes, from the
+    # ČEPS documentation and checked by trying. What they stand for is
+    # listed above CEPS_METHODS.
+    param_values: dict[str, tuple[str, ...]] = field(default_factory=dict)
+
+    # The shape of the response, which decides the parser the wrappers use.
+    # Found out by experiment (the service does not say).
+    response_type: CepsResponseType = CepsResponseType.SERIES
+#----------------------------------------------------------------------------------------------------------------------------

ceps_api/parsing.py

@@ -0,0 +1,251 @@
+"""Turns a ČEPS response document into plain Python."""
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from collections.abc import Callable
+from datetime import datetime, timezone
+from zoneinfo import ZoneInfo
+
+from .models import CepsResponseType
+from .soap import CepsError
+
+#----------------------------------------------------------------------------------------------------------------------------
+PRAGUE = ZoneInfo("Europe/Prague")
+
+# The attributes of a row that hold a date. The ČEPS schema
+# (StructuredData.xsd) types the columns by their id: value13, value14 and
+# value21 are dates, like the date of the row itself.
+_DATE_IDS = ("date", "value13", "value14", "value21")
+
+# One value of a row, as _value reads it.
+Value = datetime | float | str
+# What the parsers return: {timestamp: {series name: value}}, one dict per
+# row, and {name: text}.
+TimeSeries = dict[datetime, dict[str, Value]]
+Rows = list[dict[str, Value]]
+Fields = dict[str, str]
+Parsed = TimeSeries | Rows | Fields
+#----------------------------------------------------------------------------------------------------------------------------
+
+def _local(tag: str) -> str:
+    """The tag without the namespace prefix ElementTree puts on it."""
+    return tag.rsplit("}", 1)[-1]
+#----------------------------------------------------------------------------------------------------------------------------
+
+def _value(key: str, text: str) -> Value:
+    """
+    One attribute of a row: a datetime for a date column, else a float if
+    the text reads as a number, else the text itself.
+    """
+    if key in _DATE_IDS:
+        try:
+            return datetime.fromisoformat(text)
+        except ValueError:
+            return text
+    try:
+        return float(text)
+    except ValueError:
+        pass
+    # The schema warns that numbers in the text columns have a decimal comma.
+    try:
+        return float(text.replace(",", "."))
+    except ValueError:
+        return text
+#----------------------------------------------------------------------------------------------------------------------------
+
+def parse_rows(raw: bytes) -> Rows:
+    """
+    Parses a raw ČEPS SOAP response into one dict per row.
+
+    Every report other than the two code lists and the ACER message is the
+    same document. It describes its columns once and then lists the rows:
+
+        <serie id="value3" name="mFRR5 [MW]" />
+        <serie id="value15" name="Unit" />
+        <item date="2024-06-01T00:00:00+02:00" value3="2579" value15="LIMIT_PRICE_CZK" />
+
+    which becomes
+
+        [{"date": datetime(2024, 6, 1, 0, 0, tzinfo=+02:00),
+          "mFRR5 [MW]": 2579.0,
+          "Unit": "LIMIT_PRICE_CZK"}]
+
+    A row has "date" only if the report gives it one, and several rows may
+    share it, which is why this is a list. A report with one row per
+    timestamp is easier to read with parse_series.
+
+    Dates come back with the Czech UTC offset attached, so they are
+    timezone-aware and safe to compare across the DST change. The schema
+    lists the columns value1 to value21; the service goes beyond that, so
+    the ids are taken as they come.
+
+    Raises CepsError when two columns share a name, which would lose values.
+    """
+    root = ET.fromstring(raw)
+    # Column lookup: attribute name used in the rows -> readable series name.
+    names = {s.attrib["id"]: s.attrib["name"]
+             for s in root.iter() if _local(s.tag) == "serie" and s.get("id") and s.get("name")}
+    # date keeps its own name, so a series may not take it either.
+    taken = {"date"}
+    for name in names.values():
+        if name in taken:
+            raise CepsError(f"two columns are named {name!r}")
+        taken.add(name)
+    # Every attribute is one value; use the readable name, falling back to
+    # the raw attribute name (date has no series).
+    return [{names.get(key, key): _value(key, text) for key, text in item.attrib.items()}
+            for item in root.iter() if _local(item.tag) == "item"]
+#----------------------------------------------------------------------------------------------------------------------------
+
+def parse_series(raw: bytes) -> TimeSeries:
+    """
+    Parses a raw ČEPS SOAP response into {timestamp: {series name: value}}.
+
+    The response describes its columns once and then lists the rows:
+
+        <serie id="value1" name="aFRR [EUR/MWh]" />
+        <item date="2026-09-14T00:00:00+02:00" value1="196.1663" />
+
+    which becomes
+
+        {datetime(2026, 9, 14, 0, 0, tzinfo=+02:00): {"aFRR [EUR/MWh]": 196.1663}}
+
+    Values are floats; one that is not a number is kept as the original
+    string. A response with no rows gives an empty dict.
+
+    Timestamps come back with the Czech UTC offset attached, so they
+    are timezone-aware and safe to compare across the DST change.
+
+    Raises CepsError for a report that is not one row per timestamp, where
+    this shape would lose rows: a row without a date or two rows with the
+    same one. parse_rows reads those.
+    """
+    out: TimeSeries = {}
+    for row in parse_rows(raw):
+        when = row.pop("date", None)
+        if not isinstance(when, datetime):
+            raise CepsError("a row has no date, so this is not a time series")
+        if when in out:
+            raise CepsError(f"more than one row for {when.isoformat()}")
+        out[when] = row
+    return out
+
+#----------------------------------------------------------------------------------------------------------------------------
+def parse_estimated_price(raw: bytes) -> TimeSeries:
+    """
+    Parses an OdhadovanaCenaOdchylky response into
+    {timestamp: {"Estimated price [Kč/MWh]": price}}, the shape of
+    parse_series.
+
+    Its rows have no date attribute, which is why parse_series does not
+    read it. The time is split over two columns instead:
+
+        <serie id="value2" name="Estimated price [Kč/MWh]" />
+        <serie id="value13" name="Date" />
+        <serie id="value15" name="Interval" />
+        <item value2="3934.46" value13="2026-10-05T02:00:00+02:00"
+              value15="00:00-00:15" />
+
+    Only the day of Date is meaningful (it is UTC midnight shown in Czech
+    time) and Interval is Czech wall-clock time, so the timestamp is that
+    day plus the start of the interval, with the Czech UTC offset attached
+    like the timestamps of parse_series.
+
+    On the day the clocks go back the 02:00-03:00 intervals are listed
+    twice; the second run gets the winter offset.
+
+    Raises CepsError, like parse_series, where this shape would lose rows:
+    a row without its day, interval or price, or two rows for the same
+    time.
+    """
+    out: TimeSeries = {}
+    seen: set[datetime] = set()
+    for row in parse_rows(raw):
+        day, interval = row.pop("Date", None), row.pop("Interval", None)
+        # The price is the one remaining column.
+        if not isinstance(day, datetime) or not isinstance(interval, str) or not interval or not row:
+            raise CepsError("a row has no Date, Interval or price")
+        hour, minute = interval.split("-")[0].split(":")
+        local = datetime(day.year, day.month, day.day, int(hour), int(minute))
+        # A wall-clock time seen before is the repeated hour: fold=1 picks
+        # its second occurrence.
+        aware = local.replace(tzinfo=PRAGUE, fold=1 if local in seen else 0)
+        seen.add(local)
+        # Fixed offset rather than the zone itself, because two datetimes
+        # in the same zone compare equal regardless of fold and the
+        # repeated hour would overwrite itself as a dict key.
+        offset = aware.utcoffset()
+        assert offset is not None  # aware has a zone
+        when = local.replace(tzinfo=timezone(offset))
+        if when in out:
+            raise CepsError(f"more than one row for {when.isoformat()}")
+        out[when] = row
+    return out
+#----------------------------------------------------------------------------------------------------------------------------
+
+def parse_codes(raw: bytes) -> Fields:
+    """
+    Parses a DataVersion or DataAgregation response into {code: description}.
+
+    The response is a plain list:
+
+        <version name="RT " description="Reálná data" />
+
+    which becomes {"RT": "Reálná data"}. The service pads the codes with
+    spaces to three characters, so they are stripped.
+    """
+    root = ET.fromstring(raw)
+    return {e.attrib["name"].strip(): e.attrib["description"]
+            for e in root.iter() if e.get("name") and e.get("description")}
+#----------------------------------------------------------------------------------------------------------------------------
+
+def parse_message(raw: bytes) -> Fields:
+    """
+    Parses an EmergencyExchangeACER response into {field: text}.
+
+    The response is one message, however long the period asked for, with
+    one element per field:
+
+        <eventStatus>Active</eventStatus>
+        <eventStart>2025-02-09T00:00:00</eventStart>
+
+    which becomes {"eventStatus": "Active", "eventStart": "2025-02-09T00:00:00"}.
+    Everything stays text, as ČEPS sent it. The remarks field holds the
+    exchanges themselves, one "Direction-Type-MWh|" line each.
+    """
+    root = ET.fromstring(raw)
+    # The fields are the elements without children that carry text; the
+    # wrappers around them have children.
+    return {_local(e.tag): e.text.strip()
+            for e in root.iter() if len(e) == 0 and e.text and e.text.strip()}
+#----------------------------------------------------------------------------------------------------------------------------
+
+# The parser for each CepsMethod.response_type.
+_PARSERS: dict[CepsResponseType, Callable[[bytes], Parsed]] = {
+    CepsResponseType.SERIES: parse_series,
+    CepsResponseType.ESTIMATED_PRICE: parse_estimated_price,
+    CepsResponseType.TABLE: parse_rows,
+    CepsResponseType.CODES: parse_codes,
+    CepsResponseType.MESSAGE: parse_message,
+}
+#----------------------------------------------------------------------------------------------------------------------------
+
+def parse(response_type: CepsResponseType, raw: bytes) -> Parsed:
+    """
+    Parses a raw ČEPS SOAP response with the parser of its response type:
+
+      SERIES           parse_series
+      ESTIMATED_PRICE  parse_estimated_price
+      TABLE            parse_rows
+      CODES            parse_codes
+      MESSAGE          parse_message
+
+    Raises CepsError as the parser does, and for a response it cannot read:
+    one that is not XML (cut off, say) or has a value in a form it does not
+    know (an Interval that is not "HH:MM-HH:MM").
+    """
+    try:
+        return _PARSERS[response_type](raw)
+    except (ET.ParseError, ValueError) as e:
+        raise CepsError(f"unreadable response ({e})") from None
+#----------------------------------------------------------------------------------------------------------------------------

ceps_api/soap.py

@@ -0,0 +1,99 @@
+"""SOAP transport for the ČEPS service: envelope out, raw XML back."""
+from __future__ import annotations
+
+import http.client
+import urllib.error
+import urllib.request
+import xml.etree.ElementTree as ET
+from xml.sax.saxutils import escape
+
+# SOAP endpoint (ASMX web service) that every request is POSTed to
+CEPS_URL = "https://www.ceps.cz/_layouts/CepsData.asmx"
+# XML namespace of the service; identifies the method elements in the envelope and the SOAPAction prefix
+CEPS_NS = "https://www.ceps.cz/CepsData/"
+
+#----------------------------------------------------------------------------------------------------------------------------
+class CepsError(RuntimeError):
+    pass
+#----------------------------------------------------------------------------------------------------------------------------
+
+def call(method: str, params: dict[str, object], timeout: int = 30) -> bytes:
+    """
+    Posts one SOAP call and returns the response body for method in CEPS_METHODS.
+    Parameters that are None or empty are left out of the envelope.
+    timeout is in seconds.
+
+    Raises CepsError if the service answers with an error or with something
+    that is not XML (e.g. an HTML page during an outage), or cannot be
+    reached in time.
+    """
+    # Build the request; passing data makes urllib send it as a POST.
+    request = urllib.request.Request(
+        CEPS_URL,
+        # The XML envelope, converted from str to bytes.
+        data=_envelope(method, params).encode("utf-8"),
+        # SOAPAction tells the server which method is being called.
+        headers={"Content-Type": "text/xml; charset=utf-8",
+                 "SOAPAction"  : f'"{CEPS_NS}{method}"'})
+    try:
+        # Send it and return the raw XML response.
+        with urllib.request.urlopen(request, timeout=timeout) as r:
+            # The service answers in text/xml; anything else is not its answer,
+            # e.g. a maintenance page, which may even parse as XML.
+            content_type = r.headers.get("Content-Type", "")
+            if "xml" not in content_type:
+                raise CepsError(f"{method}: unexpected answer from ČEPS ({content_type or 'no Content-Type'})")
+            body: bytes = r.read()
+            return body
+    except urllib.error.HTTPError as e:
+        # The server answered with an error status: raise its SOAP fault
+        # message if it sent one, otherwise just the HTTP code.
+        # "from None" hides the original urllib traceback.
+        message = _fault(e.read()) or f"HTTP {e.code}"
+        raise CepsError(f"{method}: {message}") from None
+    except (urllib.error.URLError, http.client.HTTPException, TimeoutError, OSError) as e:
+        # No answer at all: DNS, connection refused, timeout, or an answer cut
+        # off (HTTPException). URLError wraps the real cause in .reason.
+        reason = getattr(e, "reason", None) or e
+        raise CepsError(f"{method}: could not reach ČEPS ({reason})") from None
+#----------------------------------------------------------------------------------------------------------------------------
+def _envelope(method: str, params: dict[str, object]) -> str:
+    """
+    Builds the SOAP request XML for one method call.
+    Each parameter becomes a <name>value</name> element inside the
+    method element; parameters that are None or empty are skipped.
+    Values are XML-escaped.
+    """
+    # One <name>value</name> line per parameter; None/empty ones are dropped
+    # and values are escaped so characters like & or < cannot break the XML.
+    inner = "".join(f"  <{k}>{escape(str(v))}</{k}>\n"
+                    for k, v in params.items() if v not in (None, ""))
+    return (
+    # XML declaration.
+    '<?xml version="1.0" encoding="utf-8"?>\n'
+    # SOAP 1.1 envelope; the soap prefix is bound to the standard namespace.
+    '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">'
+        '<soap:Body>'
+            # Method element in the ČEPS namespace, wrapping the parameters.
+            f'<{method} xmlns="{CEPS_NS}">\n{inner}'
+            f'</{method}>'
+        '</soap:Body>'
+    '</soap:Envelope>'
+    )
+#----------------------------------------------------------------------------------------------------------------------------
+def _fault(body: bytes) -> str:
+    """
+    Pulls the error message out of a SOAP fault response.
+    Returns "" if the body is not XML or holds no message.
+    """
+    try:
+        root = ET.fromstring(body)
+    except ET.ParseError:
+        # Not XML at all, e.g. an HTML error page.
+        return ""
+    # Walk every element; endswith ignores the namespace prefix on the tag.
+    for e in root.iter():
+        if e.tag.endswith("faultstring") and e.text:
+            return e.text
+    return ""
+#----------------------------------------------------------------------------------------------------------------------------

ceps_api/validation.py

@@ -0,0 +1,77 @@
+"""The parameters of a call checked against the catalog, before a request goes out."""
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from .catalog import CEPS_AGGREGATIONS, CEPS_DATA_VERSIONS, CEPS_FUNCTIONS, CEPS_METHODS
+
+# The argument names of the wrappers that the service spells differently.
+# param1 is para1 for the methods whose catalog entry says so.
+_SERVICE_NAMES = {"start": "dateFrom", "end": "dateTo", "aggregation": "agregation"}
+#----------------------------------------------------------------------------------------------------------------------------
+
+def service_name(method: str, name: str) -> str:
+    """The service's name for an argument of a wrapper (param1 -> para1 where the catalog says so)."""
+    if name == "param1" and "para1" in CEPS_METHODS[method].optional_params:
+        return "para1"
+    return _SERVICE_NAMES.get(name, name)
+#----------------------------------------------------------------------------------------------------------------------------
+
+def validate(method: str, params: dict[str, object], shown: dict[str, str] | None = None) -> None:
+    """
+    Raises ValueError for a method, parameter, aggregation, function,
+    version or filter value the service does not have and for a missing
+    parameter it needs, instead of letting a request go out that would
+    fail or come back empty.
+
+    shown maps the service's parameter names to the ones the messages
+    use instead; the wrappers pass their argument names, so an error
+    says param1 where the service calls it para1.
+    """
+    def names(params: Iterable[str]) -> str:
+        return ", ".join((shown or {}).get(p, p) for p in params)
+
+    if method not in CEPS_METHODS:
+        raise ValueError(f"Unknown ČEPS method {method!r}")
+    info = CEPS_METHODS[method]
+    # A parameter that is None or empty is left out of the request, so
+    # it is missing too.
+    missing = [p for p in info.required_params + info.needed_params
+               if params.get(p) in (None, "")]
+    if missing:
+        raise ValueError(f"{method} needs {names(missing)}")
+    allowed = info.required_params + info.optional_params
+    unknown = [p for p in params if p not in allowed]
+    if unknown:
+        raise ValueError(f"{method} does not take {names(unknown)}, "
+                         f"expected {names(allowed) or 'no parameters'}")
+    agregation = params.get("agregation")
+    if agregation is not None and agregation not in CEPS_AGGREGATIONS:
+        raise ValueError(f"unknown aggregation {agregation!r}, "
+                         f"expected one of {', '.join(CEPS_AGGREGATIONS)}")
+    supported = info.aggregations
+    if agregation is not None and supported is not None and agregation not in supported:
+        raise ValueError(f"{method} has no data for aggregation {agregation!r}, "
+                         f"expected one of {', '.join(supported)}")
+    function = params.get("function")
+    if function is not None and function not in CEPS_FUNCTIONS:
+        raise ValueError(f"unknown function {function!r}, "
+                         f"expected one of {', '.join(CEPS_FUNCTIONS)}")
+    # Without a function the service fails or returns rows with no values.
+    if agregation is not None and function is None:
+        raise ValueError(f"{method}: an aggregation needs a function, "
+                         f"one of {', '.join(CEPS_FUNCTIONS)}")
+    version = params.get("version")
+    if version is not None and version not in CEPS_DATA_VERSIONS:
+        raise ValueError(f"unknown version {version!r}, "
+                         f"expected one of {', '.join(CEPS_DATA_VERSIONS)}")
+    if version is not None and info.versions is not None and version not in info.versions:
+        raise ValueError(f"{method} has no data version {version!r}, "
+                         f"expected one of {', '.join(info.versions)}")
+    # The service does not report a filter value it does not know.
+    for name, values in info.param_values.items():
+        value = params.get(name)
+        if value is not None and value not in values:
+            raise ValueError(f"{method} has no {names([name])} {value!r}, "
+                             f"expected one of {', '.join(values)}")
+#----------------------------------------------------------------------------------------------------------------------------