xrdcore 0.4.0__tar.gz

xrdcore-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: CI
+
+# Every gate is one of xrd-devtools' reusable workflows (rob-c/xrd-devtools,
+# .github/workflows): the same steps in every repository of the chain, each
+# reading its configuration from this repository's pyproject.toml.
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      devtools-ref:
+        description: "rob-c/xrd-devtools ref whose gates and tools run"
+        default: main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  # ruff, mypy --strict, complexipy, the take-over scorecard and the
+  # configuration conformance check. ``fast`` too: google-crc32c ships its
+  # own types, and mypy checks the accelerated path against them.
+  static:
+    uses: rob-c/xrd-devtools/.github/workflows/static.yml@main
+    with:
+      devtools-ref: ${{ inputs.devtools-ref || 'main' }}
+      extras: dev,fast
+
+  # The CRC-32C accelerator is optional: the suite must pass, at the same
+  # 100 %, with and without it, on Linux and macOS, Python 3.11-3.14.
+  test:
+    uses: rob-c/xrd-devtools/.github/workflows/tests.yml@main
+    with:
+      devtools-ref: ${{ inputs.devtools-ref || 'main' }}
+      extras: '["dev", "dev,fast"]'
+
+  # The wheel holds only the package; installed into a clean environment it
+  # imports every public module, with nothing else installed (no
+  # dependencies), and the ``fast`` extra brings the accelerator.
+  package:
+    uses: rob-c/xrd-devtools/.github/workflows/package.yml@main
+    with:
+      package: xrdcore
+      devtools-ref: ${{ inputs.devtools-ref || 'main' }}
+      post-install: |
+        "$PY" -m pip install --only-binary=:all: "$(ls "$DIST"/*.whl)[fast]"
+        "$PY" -m pip check
+        "$PY" -I -c 'from xrdcore import crc32c; assert crc32c.IS_ACCELERATED and crc32c.crc32c(b"123456789") == 0xE3069283'
+
+  # No function duplicated across the chain; every repository's configuration
+  # is the standard. This commit stands in for xrdcore's main.
+  chain:
+    uses: rob-c/xrd-devtools/.github/workflows/chain.yml@main
+    with:
+      xrdcore-ref: ${{ github.sha }}
+      devtools-ref: ${{ inputs.devtools-ref || 'main' }}

xrdcore-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+# Builds the sdist and wheel on a version tag and uploads them to PyPI through
+# trusted publishing (no API token: PyPI trusts this workflow's OIDC identity,
+# registered under the project's "Publishing" settings, with the "pypi"
+# environment). xrdcore is the bottom of the chain and depends on nothing, so
+# it is published first; xrdsec's and xrdhttp's publish jobs then install
+# their wheels against this one from PyPI. The chain's runbook is xrdclient's
+# docs/releasing.md ("Releasing the 0.4.0 chain").
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  # Every step but the upload is xrd-devtools' shared publish action: build,
+  # `twine check --strict`, the artifact contents (check_dist), then a clean
+  # install that imports every public module, has no default dependency, and
+  # whose tag, runtime version and dated changelog section agree.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: rob-c/xrd-devtools/.github/actions/publish@main
+        with:
+          package: xrdcore
+          check-dist: true
+          no-dependencies: true
+
+  # Trusted publishing ties PyPI's trust to this job of this workflow, so the
+  # upload stays here, in a job that only downloads what the build staged.
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

xrdcore-0.4.0/.gitignore

@@ -0,0 +1,27 @@
+__pycache__/
+*.py[cod]
+
+# Build artefacts
+build/
+dist/
+*.egg-info/
+site/
+
+# Tooling caches and coverage data
+.coverage
+.coverage.*
+htmlcov/
+.hypothesis/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.tox/
+.venv/
+venv/
+
+# Generated datasets
+/datasets/
+
+# CI checkouts of sibling repositories (xrd-devtools, the library candidates)
+/.dependencies/
+.complexipy_cache/

xrdcore-0.4.0/CHANGELOG.md

@@ -0,0 +1,158 @@
+# Changelog
+
+Notable user-visible changes are recorded here. This project follows
+[Semantic Versioning](https://semver.org/).
+
+## [0.4.0] - 2026-10-19
+
+### Added
+
+- First release: the shared core extracted from xrdclient 0.4.0 so that
+  xrdclient, xgfalclient and xrdarc stop importing each other's private
+  modules.
+- `xrdcore.safexml` (was `xrdclient._xml`).
+- `xrdcore.checksum`, `xrdcore.crc32c`, `xrdcore.crc64` (were
+  `xrdclient.crypto.checksum`, `.crc32c`, `.crc64`). The pure-Python CRC-32C
+  is public as `crc32c_py`; `Digest` names either kind of digest. XRootD's
+  4 KiB page framing (`pack_pages`, `unpack_pages`, `page_span`) stays with
+  the XRootD client.
+- `xrdcore.checksum.ChecksumInfo`: the one `algorithm:value` type for a
+  reported checksum (was `xrdclient.types.ChecksumInfo` and a look-alike in
+  `xrdhttp.metalink`), so checksums from every protocol compare equal.
+- `xrdcore.log` (was `xrdclient._log`). `get_logger()` keeps the caller's
+  logger name instead of forcing an `xrdclient.` prefix; the filter is public
+  as `RedactingFilter`/`FILTER`.
+- `xrdcore.cancel` (was `xrdclient._cancel`); its context variable is now the
+  one every library looks at.
+- `xrdcore.pipeline` (was `xrdclient.copy._pipeline`).
+- `xrdcore.report` (was `xrdclient.cli._output`), with `dumps()` and
+  `register_text_type()` in place of its dependency on `XRootDURL`.
+- `xrdcore.retry` (was `xrdclient.retry`, née `_retry`): `ceiling`, `delay`,
+  `pause`, `use_rng` and `retry_after`.
+- `xrdcore.errors`: `XrdError`, `ProtocolError`, `MetalinkError`,
+  `ConnectionError`, `TransientError`, `TimeoutError`, `AuthenticationError`,
+  `CredentialError`, `TokenExpiredError`, `InsecureCredentialError`.
+- Release readiness: the suite gates coverage at 100 % line and branch
+  (`fail_under = 100`), with the CRC-32C accelerator probe, the safe-XML
+  guard (every encoding, both ElementTree parsers, hostile documents) and the
+  report (both formats, captured streams, exit-code policy) tested here
+  rather than in xrdclient; the wheel ships `py.typed` (PEP 561).
+- xrdclient 0.4.0 is built on this package: its old module names are aliases
+  of these modules, and its shared error names are these classes.
+- `xrdcore.fanout` (was `xrdclient._fanout`): `run_all()` and `Stopped`, the
+  thread fan-out behind xrdclient's bulk download, parallel copy and
+  multi-replica reader, xgfalclient's parallel ranged HTTP download (which
+  had its own pool) and xrdarc's `get` (likewise). One exception object
+  raised by several jobs is now reported once, not noted on itself.
+- `xrdcore.cli`: the exit statuses xrdarc, xrdwms and the storage clients'
+  tools share (`ExitCode`: 0, 1, 2, 70, 130, 141, from xrdarc's
+  `cli._common.ExitCode` and xrdwms's `cli.ExitCode`), `extends()` checking
+  a tool's own table keeps them, `run()` (Ctrl-C → 130, `BrokenPipeError` →
+  a quiet 141, everything else to the tool's handler) and `silence_stdout()`
+  (was xrdarc's `cli._common.silence_stdout` and xgfalclient's
+  `cli._base._silence_stdout`). `report.run_cli` takes its 130 from it.
+- `xrdcore.errors.rebuild`, the unpickler the clients' own exceptions reduce
+  through, is public (it was `_rebuild`, which xrdclient imported anyway).
+- `xrdcore.cli.Fatal`, the handler `run()` hands any other failure to (was
+  xrdarc's `cli._fatal` and xrdwms's `cli._fatal`, near copies): an `error`
+  record under `--json`/`--xml`, one redacted `prog: message` line on
+  stderr, the status from the tool's exception table (`exit_code()`, rows of
+  `ExitRule`: a class and a code, or a function of the exception), and a
+  bug's traceback logged at DEBUG instead of printed; `Fatal.interrupted`
+  says `prog: interrupted` for `run`'s Ctrl-C. xrdclient's `cli.fail` is one.
+- `xrdcore.log.configure()`, `verbosity_level()`, `VERBOSITY` and
+  `Configured`: a command-line tool's `-v` handler (was built separately by
+  xrdarc's `cli._common`, xrdclient's `cli.configure_logging` and
+  xgfalclient's `cli._base._Logging`; xrdwms had none). One handler on the
+  loggers named, on a given stream or whatever `sys.stderr` is at each
+  record, with `FILTER`'s redaction and muting on every record it writes
+  (third-party loggers included), replacing its own earlier handler rather
+  than adding a second; `Configured.close()` undoes it. Its first argument
+  is a level, not a `-v` count, because the tools count on different scales
+  (`verbosity_level(count, scale)`) and xrdarc's `-d LEVEL` names one.
+- `xrdcore.fanout.Pool`: the long-lived thread pool for work that is not a
+  fan-out (xrdclient's asyncio facade and pyxrootd callback dispatcher,
+  xrdwms's backend threads and dask executor). Made on first use, sized
+  then (the size may be a callable reading configuration), named, and made
+  again in a forked child, whose copy of the parent's executor has no
+  threads. With `run_all` it is where the chain makes its thread pools: the
+  clients' lint bans `ThreadPoolExecutor` and names these two.
+- `xrdcore.report.parse(text, output_format)`: the format's reader, giving
+  back a finished document of either format as the one JSON tree (XML
+  through `safexml`, encoded strings and keys decoded). It replaces the
+  `xml_value`/`decode` helpers that xrdcore's, xrdclient's and xgfalclient's
+  report tests each carried.
+- `xrdcore.sockets`: `recv_exact(sock, count)`, the exactly-N-bytes read
+  every framed stream protocol loops on, raising `ShortRead` (an
+  `xrdcore.errors.ConnectionError`, so an `OSError`) with how far it got.
+  It replaces the copies in xrdsec's KDC client and xgfalclient's dcap fake.
+
+### Packaging
+
+- CI (`.github/workflows/ci.yml`): ruff, `mypy --strict` and the family's
+  take-over scorecard (`tests/test_scorecard.py`, measured with
+  xrd-devtools' scorecard plugin; `complexipy` and `radon` joined the `dev`
+  extra); the suite at 100 % on Linux and macOS, Python 3.11-3.14, with and
+  without the `fast` extra; and a package job that builds the sdist and
+  wheel, checks their contents (xrd-devtools' `check_dist.py`: no caches,
+  coverage data or stray top-level files; `py.typed` present), installs the
+  wheel into a clean environment and imports every public module from it.
+- Publishing (`.github/workflows/publish.yml`): a `v<version>` tag builds,
+  checks that tag, runtime version, wheel metadata and a dated changelog entry
+  agree and that the wheel has no default dependency, and uploads to PyPI by
+  trusted publishing. xrdcore is the first package of the 0.4.0 chain to be
+  published; xrdclient's `docs/releasing.md` is the chain's runbook.
+- `CONTRIBUTING.md` and `SECURITY.md`.
+- The chain's tooling moved to the new
+  [xrd-devtools](https://github.com/rob-c/xrd-devtools) repository, used from
+  a checkout (it is not on PyPI and cannot be a dependency):
+  `tests/test_scorecard.py` is now a few lines loading its scorecard plugin
+  (found through pytest's `pythonpath`: `../xrd-devtools/src` or CI's
+  `.dependencies/xrd-devtools/src`; it skips, saying so, without one), in
+  place of the copy that located xrdclient's `tools/scorecard.py` through
+  `XRDCLIENT_CHECKOUT`/`SCORECARD_REQUIRED`. `.github/scripts/check_dist.py`,
+  identical in the three libraries, is xrd-devtools' `check_dist.py`; ruff,
+  mypy and complexipy no longer list `.github/scripts`.
+- CI (`.github/workflows/ci.yml`) calls xrd-devtools' reusable workflows -
+  `static.yml` (ruff, mypy, complexipy, the scorecard, made required, and
+  `xrddevtools conformance`), `tests.yml`, `package.yml` and `chain.yml` (the
+  duplicate and conformance gates over all seven repositories) - with the
+  candidates from its one candidates action; `publish.yml` checks
+  xrd-devtools out to run `check_dist.py`. CI therefore needs
+  `rob-c/xrd-devtools` to exist.
+
+### Code health
+
+- No grandfathered code: ruff's full rule set (`SIM` added) with nothing
+  ignored, `mypy --strict` over the tests and release scripts as well as
+  the package, complexipy at 15 with no snapshot, and every warning an
+  error under pytest. The suppressions are gone (6 `type: ignore`, 1 `noqa`)
+  and so is the untyped-import exemption for google-crc32c, which ships its
+  own types. `errors`' pickling helpers are typed; the private
+  `safexml._guard_expat` and `pipeline._abort` take any object, as they
+  always looked at it by attribute only.
+- Banned APIs (ruff `TID251`; CONTRIBUTING.md explains the list): xrdcore
+  imports no third-party package, no protocol module (`http.client`,
+  `ssl`) and nothing above it in the chain (xrdsec, xrdhttp, the clients).
+  It owns `ThreadPoolExecutor` (`fanout`) and the XML parsers (`safexml`),
+  which the other repositories ban in its favour.
+- Release metadata is xrd-devtools' release gate:
+  `tests/test_release_metadata.py` is `release_gate(__file__)` from
+  `xrddevtools.pytest_plugin` - one version source (`_version.py`, read by
+  hatch), a CHANGELOG led by exactly that version's well-formed section,
+  project metadata and README that name this repository, and a release
+  workflow built through the shared publish action.
+- The publish workflow's build job is xrd-devtools' shared `publish`
+  composite action (build, `twine check --strict`, the artifact or
+  pre-flight checks, a clean install whose tag, runtime version and dated
+  changelog section agree, the artifact upload); only the trusted-publishing
+  upload to PyPI stays in this workflow's own job.
+- The standard's settings in `pyproject.toml` (ruff rules, the banned-API
+  table, mypy's strictness and allowed overrides, complexipy, coverage,
+  pytest's warnings filter) and CONTRIBUTING's *The code standard*, *Banned
+  APIs* table and *xrd-devtools* sections are managed blocks, written by
+  `xrddevtools sync` from the standard kept once in xrd-devtools;
+  `xrddevtools conformance` fails a hand edit between the markers. The
+  repository's own keys and notes sit beside the blocks.
+- `[project.urls]` (Homepage, Documentation, Repository, Issues,
+  Changelog), as every other package of the chain has.

xrdcore-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,200 @@
+# Contributing to xrdcore
+
+xrdcore is the dependency-free bottom layer of the storage-client family:
+xrdsec, xrdhttp, xrdclient, xgfalclient and xrdarc all import it, and every
+one of their `--help` screens loads it. Changes are welcome when they keep the
+three properties it is built around: it needs nothing but the standard library
+to import (the `fast` extra only accelerates CRC-32C); it holds only what more
+than one package of the family needs and nothing protocol-specific; and it
+depends on no other package of the family, ever.
+
+## Development setup
+
+Python 3.11 through 3.14 are supported. xrdcore has no dependencies, so a
+checkout on its own is a complete development environment:
+
+```console
+$ python3 -m venv .venv
+$ .venv/bin/python -m pip install -U pip
+$ .venv/bin/python -m pip install -e '.[dev,fast]'
+$ .venv/bin/pytest -q -n auto
+```
+
+`pyproject.toml` puts `src` on the test path, so a suite run from the shared
+workspace virtual environment needs nothing installed. The suite is hermetic.
+Run it once without the `fast` extra as well: the CRC-32C tests then cover the
+pure-Python path, and CI runs both.
+`mypy` wants the `fast` extra installed: google-crc32c ships its own types,
+and the accelerated path is checked against them.
+
+## Definition of done
+
+A change is ready when all of these pass, as CI runs them:
+
+```console
+$ ruff check src tests
+$ ruff format --check src tests
+$ mypy
+$ complexipy
+$ pytest -q -p no:cacheprovider -n auto --cov --cov-report=term-missing:skip-covered
+$ python -m build && twine check --strict dist/*
+$ python ../xrd-devtools/src/xrddevtools/check_dist.py contents xrdcore dist
+$ xrddevtools conformance --repo .
+```
+
+- **Coverage is 100 % of lines and branches** (`fail_under = 100`). Reach it
+  with a test that makes the case happen - a hostile document, a cancelled
+  copy, a missing accelerator - not with an exclusion.
+- **The code standard** (below) holds for every line: nothing suppressed,
+  nothing ignored, no snapshot. Fix the code rather than silencing a finding.
+- **Types are `mypy --strict`.** The package ships `py.typed`; its annotations
+  are part of the API of every package above it.
+- **The take-over scorecard.** `tests/test_scorecard.py` loads the chain's
+  scorecard plugin (`xrddevtools.pytest_plugin`) from an
+  [xrd-devtools](https://github.com/rob-c/xrd-devtools) checkout and fails if
+  any of the twelve measurements of `src` is worse than the median of 39
+  widely used Python libraries. Do not lower the bar to land a change; split
+  the function, group its options, or explain the code.
+- **The chain's gates** pass: the scorecard above, the release-metadata gate
+  (`tests/test_release_metadata.py`: one version source, a CHANGELOG led by
+  that version, metadata that agrees), `xrddevtools conformance` (the
+  standard, and every managed block as `xrddevtools sync` writes it) and
+  `xrddevtools dupes` (no function copied into another repository) - all
+  from [xrd-devtools](#xrd-devtools).
+- **Documentation.** Every module, class and function has a docstring that
+  explains purpose, contract, failure modes and why - not a restatement of the
+  signature. The README's module table is the package's map; keep it current.
+- **Changelog.** Add user-visible changes to [CHANGELOG.md](CHANGELOG.md) in
+  the same pull request, and say which package a moved name came from.
+
+## The code standard
+
+<!-- >>> xrddevtools sync: code-standard (generated from xrd-devtools/src/xrddevtools/standard) >>> -->
+Every repository of the chain is held to one code standard, and every line
+of it is held to the standard: old code passes the same checks as new code.
+
+- **Ruff** selects `E`, `F`, `W`, `I`, `UP`, `B`, `C4`, `SIM`, `RUF`, the
+  high-confidence security checks `S102`, `S307`, `S506`, `S602`, `S608`,
+  `S609`, `S701` and the banned-API rule `TID251` (see *Banned APIs*), with
+  `ignore = []` and no per-file ignores, over `src`, `tests`; `ruff format`
+  formats it, 100 columns wide.
+- **mypy** is strict (Python 3.11) over `src`, `tests`. A test function may
+  leave its fixtures unannotated where `pyproject.toml` allows it, but its
+  body is still checked; only a named third-party module that ships no types
+  may be imported untyped, with the reason beside it.
+- **complexipy** allows no function above 15, over `src`, `tests`, with no
+  snapshot of old offenders.
+- **Coverage** is 100 % of lines and branches, reached by a test that makes
+  each case happen. The only exclusions are `if TYPE_CHECKING:`,
+  `@overload`, `raise NotImplementedError`, `\.\.\.$`, `if __name__ ==
+  .__main__.:`; there is no `omit`.
+- **Every warning is an error** (`filterwarnings = ["error"]`): ours are
+  fixed, not filtered.
+- **No suppression comment**: no `# noqa`, `# pragma: no cover`, `# fmt:
+  off`, `# complexipy: ignore` or `# nosec`. A `# type: ignore[code]` only
+  where it cannot be avoided (a test passing a wrongly typed value on
+  purpose), with its error code and the reason beside it or just above.
+- **No snapshot or baseline** of old findings, for any tool.
+
+The settings behind these rules are the managed blocks of `pyproject.toml`
+(between `# >>> xrddevtools sync` markers), and this section is one of the
+managed blocks of this file (between `<!-- >>> xrddevtools sync` markers).
+`xrddevtools sync` writes them all from the standard, kept once in
+xrd-devtools (`src/xrddevtools/standard`); `xrddevtools conformance`, which
+CI runs, fails if one is edited by hand. To change the standard, change it
+there and run `xrddevtools sync --workspace ..` over every repository.
+<!-- <<< xrddevtools sync: code-standard <<< -->
+
+## Banned APIs
+
+<!-- >>> xrddevtools sync: banned-apis (generated from xrd-devtools/src/xrddevtools/standard) >>> -->
+Ruff's `TID251` rule refuses the APIs whose job another part of the chain
+does, in every tree ruff checks (`src`, `tests`), with no per-file ignore
+and no `noqa`; the list is `[tool.ruff.lint.flake8-tidy-imports.banned-api]`
+in `pyproject.toml`, and each entry's message names what to use instead. A
+need for a banned API is met by the library that owns it growing an API,
+with its tests - never by an exception here.
+
+| Banned | Use instead | Why |
+|---|---|---|
+| `urllib3`, `requests`, `httpx` | the chain has no third-party HTTP stack: use xrdhttp.session.Session (pooling, redirects, retries; TLS from xrdsec.tls) | one HTTP stack for the whole chain, with its TLS, redirect and retry rules |
+| `urllib.request` | use xrdhttp.session.Session: urllib's opener has none of the chain's TLS, redirect or retry rules | urllib's opener knows none of the grid's TLS (CAs, CRLs, proxies) and follows redirects with credentials attached |
+| `gssapi` | Kerberos GSS-API is xrdsec.krb5.gss (the xrdsec[krb5] extra), one wrapper for every client | one GSS-API wrapper, behind the `xrdsec[krb5]` extra |
+| `krb5` | pykrb5 is not a dependency: credential caches are xrdsec.krb5.caches / xrdsec.krb5.ccache, GSS-API is xrdsec.krb5.gss | the pure-Python ccache, KCM and keyring readers replaced it |
+| `botocore`, `boto3` | S3 signing and the S3 codec are xrdhttp.s3 (the xrdhttp[s3] extra); only xrdhttp.s3 imports botocore | S3 signing and the S3 codec, behind the `xrdhttp[s3]` extra |
+| `http.client` | xrdcore speaks no protocol: HTTP is xrdhttp's (xrdhttp.session) | - |
+| `ssl` | xrdcore speaks no protocol: TLS contexts are xrdsec.tls's | - |
+| `cryptography` | xrdcore has no third-party dependency: cryptography belongs in xrdsec | - |
+| `asn1crypto` | xrdcore has no third-party dependency: ASN.1 belongs in xrdsec (xrdsec.der) | - |
+| `xrdsec`, `xrdhttp`, `xrdclient`, `xgfalclient`, `xrdarc`, `xrdwms` | - | they are built on this repository; the dependency direction never points up |
+<!-- <<< xrddevtools sync: banned-apis <<< -->
+
+What xrdcore owns, it does not ban: `concurrent.futures.ThreadPoolExecutor`
+(`fanout.run_all` and `fanout.Pool` are built on it) and the
+`xml.etree.ElementTree` parsers (`safexml` is built on them, and its tests
+compare against them). The other repositories ban both, naming these
+modules instead - so a new need there (another kind of pool, another kind
+of XML input) is met by an API here, with its tests, not by an exception
+there.
+
+## xrd-devtools
+
+<!-- >>> xrddevtools sync: devtools (generated from xrd-devtools/src/xrddevtools/standard) >>> -->
+The chain's gates and tools - the take-over scorecard and the
+release-metadata and maintainability gates, `xrddevtools conformance`,
+`dupes` and `sync`, the release pre-flight and the packaging tools - live in
+[xrd-devtools](https://github.com/rob-c/xrd-devtools). It is never uploaded
+to PyPI and cannot be a dependency (PyPI refuses direct-URL requirements),
+so it is used from a checkout:
+
+- **A developer** keeps it beside this repository (`../xrd-devtools`, the
+  workspace layout). pytest's `pythonpath` lists `../xrd-devtools/src`, so
+  the gate tests find it with nothing installed; `pip install -e
+  ../xrd-devtools` once gives the `xrddevtools` command.
+- **CI** checks it out under `.dependencies/xrd-devtools` (the shared
+  `candidates` action always does), which `pythonpath` lists too. It loads
+  the plugin with `pytest -p xrddevtools.pytest_plugin`, which fails at
+  start-up if it cannot be imported, and sets `XRD_DEVTOOLS_REQUIRED=1`, so
+  a missing radon or complexipy fails rather than skips. This repository's
+  workflows are xrd-devtools' reusable workflows and actions: CI runs only
+  once `rob-c/xrd-devtools` exists.
+- **Anywhere else** - a wheel-only test environment, a distribution build -
+  `pip install -e` a checkout or put its `src` on `PYTHONPATH`. Without one,
+  the gate tests (`tests/test_scorecard.py`,
+  `tests/test_release_metadata.py`) skip, saying why.
+<!-- <<< xrddevtools sync: devtools <<< -->
+
+## Layering and compatibility
+
+- **No dependencies.** `dependencies = []` in `pyproject.toml` is a contract:
+  the publish workflow refuses a wheel with a default requirement. An
+  accelerator goes behind an extra with a pure-Python fallback, as
+  `google-crc32c` does.
+- **Imports.** xrdcore never imports xrdsec, xrdhttp or a client, and
+  `import xrdcore` imports no submodule; `tests/test_package.py` pins both.
+- **Shared formats are API.** The `storage-client-report` document
+  (`xrdcore.report`) is read by scripts written against any of the family's
+  tools; a change that would make an existing consumer misread it bumps its
+  `VERSION`. Redaction patterns (`xrdcore.log`) only ever grow.
+- **Exceptions.** The clients join `xrdcore.errors` by identity or multiple
+  inheritance (`xrdclient.XRootDError is XrdError`), so a rename, a new base
+  class or a changed attribute is a change to their public API too. Add,
+  deprecate, then remove; never change what an existing keyword means.
+
+## Releasing
+
+xrdcore is released first: everything else in the family requires it. The
+whole chain's runbook is xrdclient's
+[docs/releasing.md](https://github.com/rob-c/xrdclient/blob/main/docs/releasing.md)
+("Releasing the 0.4.0 chain").
+
+1. Set `__version__` in `src/xrdcore/_version.py` (the build reads it from
+   there) and date the version's [CHANGELOG.md](CHANGELOG.md) entry.
+2. Wait for CI on the release commit, then push an annotated `v<version>` tag.
+   The publish workflow rebuilds the sdist and wheel, checks the artifact
+   contents, that the tag, the runtime version, the wheel metadata and a dated
+   changelog entry agree and that the wheel has no default dependency, and
+   uploads to PyPI through trusted publishing. Never upload a local build.
+3. Wait until `pip download --only-binary=:all: xrdcore==<version>` succeeds
+   from a clean environment before tagging xrdsec or xrdhttp: their publish
+   jobs install against this release from PyPI.