dbt-metricflow-sql 0.1.1__tar.gz

dbt_metricflow_sql-0.1.1/.gitignore

@@ -0,0 +1,218 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

dbt_metricflow_sql-0.1.1/LICENSE

@@ -0,0 +1,29 @@
+Copyright (c) 2026 Fivetran, Inc.
+
+By accessing or using this software, you agree to the following terms:
+
+PERMITTED USE
+This software is made available for internal use and evaluation purposes
+only. You may install and use the software solely to access and interact
+with Fivetran's services.
+
+RESTRICTIONS
+You may not use this software to:
+- Build competing products or services
+- Redistribute, sublicense, or transfer the software
+
+INTELLECTUAL PROPERTY
+All rights, title, and interest in the software remain exclusively with
+Fivetran, Inc. No license to any intellectual property is granted
+except as expressly stated herein.
+
+NO WARRANTIES
+THE SOFTWARE IS PROVIDED "AS IS". FIVETRAN, INC. MAKES NO WARRANTIES,
+EXPRESS OR IMPLIED, AND HEREBY DISCLAIMS ALL IMPLIED WARRANTIES,
+INCLUDING ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
+PURPOSE.
+
+LIMITATION OF LIABILITY
+FIVETRAN, INC. SHALL NOT BE LIABLE FOR ANY DAMAGES OF ANY KIND ARISING
+FROM USE OF THIS SOFTWARE, INCLUDING DIRECT, INDIRECT, INCIDENTAL,
+PUNITIVE, AND CONSEQUENTIAL DAMAGES.

dbt_metricflow_sql-0.1.1/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.5
+Name: dbt-metricflow-sql
+Version: 0.1.1
+Summary: dbt v1 plugin for MetricFlow
+Project-URL: Documentation, https://congenial-bassoon-7zkjv8w.pages.github.io/
+License-Expression: LicenseRef-Fivetran
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: dbt-core>=1.9
+Requires-Dist: jsonschema>=4.19
+Provides-Extra: sidecar
+Requires-Dist: metricflow-sql-sidecar; extra == 'sidecar'
+Description-Content-Type: text/markdown
+
+# dbt-metricflow-sql
+
+Something is cooking...
+
+[Documentation](https://congenial-bassoon-7zkjv8w.pages.github.io/), for design partners with access.

dbt_metricflow_sql-0.1.1/PYPI.md

@@ -0,0 +1,5 @@
+# dbt-metricflow-sql
+
+Something is cooking...
+
+[Documentation](https://congenial-bassoon-7zkjv8w.pages.github.io/), for design partners with access.

dbt_metricflow_sql-0.1.1/README.md

@@ -0,0 +1,162 @@
+# dbt-metricflow-sql
+
+A dbt-core plugin that builds a project's semantics into MetricFlow, and models written in
+MetricFlow semantic SQL. Install it next to dbt and dbt loads it automatically.
+
+It compiles MetricFlow models with a MetricFlow server: metricflow-sql's `metricflow-serve`, as
+[metricflow-sql-sidecar](../metricflow-sql-sidecar/README.md) packages it, an executable with a
+Python of its own, so it runs whatever dbt's Python is. A project with MetricFlow models needs
+it, so install the plugin with its `sidecar` extra:
+
+```sh
+pip install 'dbt-metricflow-sql[sidecar]'
+```
+
+For another command, set the `metricflow_server` var, as a list of arguments or a string:
+
+```yaml
+# dbt_project.yml
+vars:
+  metricflow_server: /opt/metricflow/bin/metricflow-serve
+```
+
+The plugin runs the server for each dbt command that compiles MetricFlow models, and stops it
+once the command completes; its log is in `target/metricflow-server.log`. The command is run
+from the project's directory, with `--bundle <directory> --catalog <project name>` appended: the
+project's semantics, and the semantic catalog's name. Once it listens, it must print a JSON line
+with its `port`, e.g. `{"host": "127.0.0.1", "port": 54321}`, to stdout, and it should exit when
+its stdin closes.
+
+## Semantics
+
+Declare semantics in schema files: `datasets`, `entities`, `constellations` and `pages` at the
+root, and dataset fields on models, seeds, snapshots and source tables. They're the objects of a
+[v1 fragment](../metricflow-sql/src/metricflow_sql/schemas/v1/fragment.py), whose named
+collections are dbt-style lists of objects with a `name`:
+
+```yaml
+models:
+  - name: orders          # a dataset of the model's relation and columns
+    columns:
+      - name: amount
+        data_type: numeric
+    calculations:
+      - name: revenue
+        expr: SUM(amount)
+
+  - name: customers
+    dataset: true         # a dataset of nothing but its columns
+
+datasets:
+  - name: refunds
+    source: ref('refunds')   # or source('<source>', '<table>')
+
+constellations:
+  - name: sales
+    roles:
+      - name: customer
+        datatype: REF(customer)
+    metrics:
+      - name: revenue
+        expr: AGG(orders.revenue)
+    assignments:
+      - dataset: orders
+        roles:
+          - name: customer
+            expr: customer
+```
+
+A node is a dataset, named after it, if it sets `calculations`, `relationships`, `parameters` or
+`key`, or `dataset: true`. Expressions are in the warehouse's dialect.
+
+dbt validates schema files on some adapters (BigQuery, Databricks, Redshift, Snowflake), and
+warns of keys it doesn't know as custom ones; the plugin declares these to it.
+
+## Lifecycle
+
+- **Parse** builds the semantics into a bundle in `target/metricflow/`, one fragment per
+  schema file, and validates it against the fragment JSON Schema. The root `fragment.json` holds
+  the bundle's `generation_meta`: the target and invocation that built it.
+- **Compile**: the first time a `metricflow=true` model compiles, the plugin starts the server
+  over the bundle. Each such model's rendered SQL compiles there to warehouse SQL, which dbt
+  builds with any materialization:
+
+  ```sql
+  {{ config(materialized='table', metricflow=true) }}
+  SELECT AGG(revenue) AS revenue FROM sales
+  ```
+
+  The semantic catalog is the project's, so name tables without it: `sales`, `finance.revenue`.
+
+  dbt can't see what semantic SQL reads, so as dbt builds its graph, each such model compiles
+  first: the models, seeds, snapshots and sources that build the tables its warehouse SQL
+  reads become its dependencies. It builds after them, and `+model` selects them. So every
+  command that builds the graph, e.g. `dbt ls`, runs the server when the project has
+  MetricFlow models.
+- **Publish**: if the `metricflow_publish_url` var is set, `dbt run` and `dbt build` end by
+  sending the project's bundle to the MetricFlow server at that URL, e.g. production's, as the
+  next version of the bundle named for the project. It isn't the server the plugin runs to
+  compile models.
+
+  It happens after dbt's own `on-run-end` hooks, whether or not the run's models succeeded:
+  the semantics don't wait for every model to build, which in a large project may never
+  happen. dbt records it in `run_results.json` as an operation, `metricflow-publish`, so a
+  publish that fails fails the run. Publishing content the server already has changes nothing,
+  so a rerun is safe, and so is a build that changed no semantics.
+
+  dbt tells production from development only by the target a run uses, e.g.
+  `dbt build --target prod`, so the var is what decides where a run publishes. It's rendered like
+  any var, so it can read the environment and the target, and it publishes nothing if it renders
+  empty. Either of these keeps development builds from publishing:
+
+  ```yaml
+  # dbt_project.yml
+  vars:
+    # The job that should publish sets METRICFLOW_URL...
+    metricflow_publish_url: "{{ env_var('METRICFLOW_URL', '') }}"
+    # ...or only production does, wherever it runs:
+    # metricflow_publish_url: "{{ env_var('METRICFLOW_URL') if target.name == 'prod' else '' }}"
+  ```
+
+  Other commands don't publish, and nor does a project without the var. For a one-off,
+  `--vars '{"metricflow_publish_url": "http://localhost:8080"}'` works too.
+
+  A server that authenticates a publish, e.g. dbt Cloud's, takes a token and a dbt Cloud project:
+
+  - The token is the `DBT_CLOUD_TOKEN` environment variable, the one dbt-core and Fusion read,
+    sent as `Authorization: Bearer`. It's an environment variable only, never a var: vars reach
+    dbt's artifacts, e.g. `manifest.json`. It may be a service token, a personal access token
+    (PAT) or a dbt OAuth access token. Use a service token for CI: a PAT stops working when its
+    user leaves the account or the token expires, and an OAuth access token is short-lived. A
+    user token publishes exactly as a service token does, but a query made with one runs on that
+    user's development credentials, not the Semantic Layer credential, so BI clients and CI
+    should query with a Semantic Layer service token.
+  - The project's id is `DBT_CLOUD_PROJECT_ID`, which dbt Cloud's job runs set, else
+    `project-id` in `dbt_project.yml`'s `dbt-cloud:` block, as Fusion reads it. It's sent as
+    `X-Dbt-Project-Id`. The server publishes to the environment of the project's Semantic Layer
+    configuration, so there's no environment to name, and answers with the catalog to query it
+    as, which the run's output shows.
+
+  Both go only with the plugin's requests to the server, never with the upload to the server's
+  storage, and both are optional: a server without authentication, e.g. a local one, needs
+  neither. The upload goes straight to the server's storage, e.g. S3, so that host must be
+  reachable from where dbt runs.
+
+  ```yaml
+  # dbt_project.yml; the job's environment sets DBT_CLOUD_TOKEN and METRICFLOW_URL.
+  dbt-cloud:
+    project-id: 160
+  vars:
+    metricflow_publish_url: "{{ env_var('METRICFLOW_URL', '') if target.name == 'prod' else '' }}"
+  ```
+
+  Publish from a target that builds the tables the Semantic Layer environment reads, on the same
+  warehouse: the server refuses a bundle in another warehouse's dialect, but checks nothing else.
+
+  `DBT_CLOUD_TOKEN` is often set in CI for other dbt tools, so the plugin sends it only to an
+  `https://` URL, or an `http://` one whose host is `localhost` or a loopback IP, e.g.
+  `http://127.0.0.1:8080`; it never resolves a name to check. With the token set, any other URL
+  fails the publish, sending nothing. The plugin also follows no redirect, since following the
+  server's would send the token to the host it names. A redirected request fails the publish,
+  naming the redirect's host. That includes the upload's, e.g. S3's for a bucket in another
+  region.

dbt_metricflow_sql-0.1.1/pyproject.toml

@@ -0,0 +1,67 @@
+[project]
+name = "dbt-metricflow-sql"
+# A placeholder: a release sets its tag's version, with scripts/set_version.py.
+version = "0.1.1"
+description = "dbt v1 plugin for MetricFlow"
+# Its PyPI page: README.md is for this repository.
+readme = "PYPI.md"
+# Fivetran's own, in LICENSE, which no SPDX identifier names.
+license = "LicenseRef-Fivetran"
+requires-python = ">=3.9"
+classifiers = [
+    "Programming Language :: Python :: 3",
+]
+dependencies = [
+    "dbt-core>=1.9",
+    # Validates the fragments it builds; dbt-core requires it too.
+    "jsonschema>=4.19",
+]
+
+[project.optional-dependencies]
+# The MetricFlow server it runs by default, which needs no Python of its own: only projects with
+# MetricFlow models run one.
+sidecar = ["metricflow-sql-sidecar"]
+
+[project.urls]
+Documentation = "https://congenial-bassoon-7zkjv8w.pages.github.io/"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dbt_metricflow_sql"]
+
+# The workspace's `tests/dbt_metricflow_sql` run in this environment, against a real
+# metricflow-sql server, which needs a newer Python than the plugin, and metricflow-service, which
+# they publish to.
+[dependency-groups]
+dev = [
+    "dbt-duckdb>=1.9",
+    "duckdb>=1.5.6",
+    "metricflow-db[s3]",
+    "metricflow-service",
+    "metricflow-sql[server]",
+    "metricflow-sql-sidecar",
+    "mypy>=1.11",
+    "pytest>=8.0",
+    "ruamel-yaml>=0.18",
+    "trino>=0.334",
+    "types-jsonschema>=4.19",
+]
+
+[tool.uv.dependency-groups]
+dev = { requires-python = ">=3.12" }
+
+[tool.uv.sources]
+metricflow-db = { path = "../metricflow-db", editable = true }
+metricflow-service = { path = "../metricflow-service", editable = true }
+metricflow-sql = { path = "../metricflow-sql", editable = true }
+metricflow-sql-sidecar = { path = "../metricflow-sql-sidecar" }
+
+[tool.mypy]
+python_version = "3.12"
+files = ["src"]
+# Read the service packages from source, as the workspace does.
+mypy_path = "../metricflow-sql/src:../metricflow-service/src:../metricflow-sql-sidecar/src"
+strict = true

dbt_metricflow_sql-0.1.1/src/dbt_metricflow_sql/__init__.py

@@ -0,0 +1,11 @@
+"""A dbt plugin: dbt discovers it by its `dbt_` module prefix and `plugins` list."""
+
+from __future__ import annotations
+
+import logging
+
+from dbt_metricflow_sql.plugin import MetricFlowPlugin
+
+logger = logging.getLogger(__name__)
+
+plugins = [MetricFlowPlugin]

dbt_metricflow_sql-0.1.1/src/dbt_metricflow_sql/client.py

@@ -0,0 +1,173 @@
+"""Metricflow HTTP client"""
+
+from __future__ import annotations
+
+import json
+import logging
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Mapping
+from dataclasses import dataclass
+from email.message import Message
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+_TIMEOUT_SECONDS = 10
+# Bundles can be large, and the server reads one as it syncs it.
+_PUBLISH_TIMEOUT_SECONDS = 300
+# The header of a publish's response naming the catalog to query the bundle as, e.g. `env_220`.
+CATALOG_HEADER = "X-Dbt-Catalog"
+
+
+class MetricFlowError(Exception):
+    """A request to a MetricFlow server failed: it's unreachable, or it rejected the request."""
+
+
+class _NoRedirectHandler(urllib.request.HTTPRedirectHandler):
+    """
+    Follows no redirect, so a 3xx raises `HTTPError`: urllib would otherwise send the redirect's
+    host the request's headers, e.g. `Authorization`.
+    """
+
+    def redirect_request(self, *args: Any, **kwargs: Any) -> None:
+        return None
+
+
+# For the server's requests and the upload alike.
+_OPENER = urllib.request.build_opener(_NoRedirectHandler)
+
+
+@dataclass(frozen=True)
+class Compiled:
+    """Warehouse SQL compiled from semantic SQL."""
+
+    sql: str
+    # The physical tables `sql` reads, by their parts, e.g. `("analytics", "main", "orders")`.
+    tables: tuple[tuple[str, ...], ...]
+
+
+def compile_sql(url: str, sql: str, dialect: str) -> Compiled:
+    """Metricflow SQL, in the warehouse's `dialect`, to warehouse SQL."""
+    response = _request(
+        url,
+        "POST",
+        "/v1/compile",
+        {"sql": sql, "input_dialect": dialect, "output_dialect": dialect},
+    ).body
+    return Compiled(
+        sql=str(response["sql"]),
+        tables=tuple(tuple(str(part) for part in table) for table in response.get("tables", [])),
+    )
+
+
+@dataclass(frozen=True)
+class Published:
+    """A bundle published to a MetricFlow server."""
+
+    name: str
+    version: int
+    # False if the server already had this bundle, as its current version.
+    changed: bool
+    # The catalog to query it as, if the server names one, e.g. `env_220`.
+    catalog: str | None = None
+
+
+def publish_bundle(
+    url: str, name: str, archive: bytes, headers: Mapping[str, str] | None = None
+) -> Published:
+    """
+    Publishes the zip `archive` of a bundle to the server at `url`, as the next version of
+    the bundle `name`: uploads it through the URL the server gives, then asks the server to
+    publish it. `headers`, e.g. credentials, go with each request to the server, and never
+    with the upload.
+    """
+    timeout = _PUBLISH_TIMEOUT_SECONDS
+    upload = _request(
+        url, "POST", "/api/v1/bundles/uploads", {"size": len(archive)}, timeout, headers
+    ).body
+    upload_url = str(upload["url"])
+    # Only the headers the server gives: the URL is the store's, e.g. S3's, which mustn't see
+    # the server's credentials.
+    put = urllib.request.Request(
+        upload_url, data=archive, headers=dict(upload["headers"]), method=str(upload["method"])
+    )
+    # Named by its host: the URL itself carries a signature.
+    parts = urllib.parse.urlsplit(upload_url)
+    _send(put, f"{parts.scheme}://{parts.netloc}", timeout)
+    path = f"/api/v1/bundles/{urllib.parse.quote(name, safe='')}"
+    response = _request(url, "PUT", path, {"ref": upload["ref"]}, timeout, headers)
+    result = response.body
+    return Published(
+        name=str(result["name"]),
+        version=int(result["version"]),
+        changed=bool(result["changed"]),
+        catalog=response.headers.get(CATALOG_HEADER) or None,
+    )
+
+
+@dataclass(frozen=True)
+class _Response:
+    """A JSON response from the server."""
+
+    body: dict[str, Any]
+    headers: Message
+
+
+def _request(
+    url: str,
+    method: str,
+    path: str,
+    body: Mapping[str, Any],
+    timeout: float = _TIMEOUT_SECONDS,
+    headers: Mapping[str, str] | None = None,
+) -> _Response:
+    parts = urllib.parse.urlsplit(url)
+    if parts.scheme not in ("http", "https") or not parts.netloc:
+        raise MetricFlowError(f"invalid URL `{url}`: it must be like http://localhost:8080")
+    request = urllib.request.Request(
+        f"{url.rstrip('/')}{path}",
+        data=json.dumps(body).encode(),
+        headers={**(headers or {}), "Content-Type": "application/json"},
+        method=method,
+    )
+    content, response_headers = _send(request, url, timeout)
+    return _Response(body=json.loads(content), headers=response_headers)
+
+
+def _send(request: urllib.request.Request, url: str, timeout: float) -> tuple[bytes, Message]:
+    """
+    Sends `request`, returning the response's body and headers. A redirect is an error, naming its
+    host.
+    """
+    try:
+        with _OPENER.open(request, timeout=timeout) as response:
+            content: bytes = response.read()
+            return content, response.headers
+    except urllib.error.HTTPError as e:
+        location = e.headers.get("Location")
+        if 300 <= e.code < 400 and location:
+            # Named by its host, as the upload's URL is: a `Location` can carry a signature. A
+            # relative one, e.g. `/other`, is on the request's host.
+            parts = urllib.parse.urlsplit(urllib.parse.urljoin(request.full_url, location))
+            raise MetricFlowError(
+                f"redirected ({e.code}) to {parts.scheme}://{parts.netloc}, not followed"
+            ) from e
+        raise MetricFlowError(_error_message(e.read())) from e
+    # `URLError` (refused, DNS) and timeouts, which a read can raise unwrapped, are both `OSError`s.
+    except OSError as e:
+        raise MetricFlowError(f"unreachable at {url}: {e}") from e
+
+
+def _error_message(content: bytes) -> str:
+    """The message of an error response, e.g. `{"message": "..."}`, else its raw body."""
+    text = content.decode(errors="replace")
+    try:
+        body = json.loads(text)
+    except ValueError:
+        return text
+    message: Any | None = None
+    if type(body) is dict:
+        message = body.get("message", body.get("error"))
+    return text if message is None else str(message)