weaverstack 0.1.1__py3-none-any.whl

weaver/spark/catalogue.py

@@ -0,0 +1,245 @@
+"""Spark catalogue operations, against a *named* destination.
+
+Everything Weaver does to a Lakehouse through Spark goes through here, and the
+one thing this type refuses to do is assume the session is pointed at the right
+place. The session is attached to the Weaver Lakehouse — the fixed control plane
+— so a destination is never the current catalogue, and an operation that did not
+name one would land in the control plane instead. That is the failure this
+exists to make impossible, not merely unlikely.
+
+A build has at least two of these open at once: one for the Lakehouse being
+built, one for the Weaver Lakehouse the catalogue is written to. They differ only
+in their :class:`~weaver.spark.destination.SparkDestination`, which is the claim
+being made — that once a name is right, the operation is the same one.
+
+**Enumerating a destination's schemas is not here, and that is deliberate.** On
+Fabric it cannot be: a schema is a three-level name under ``spark_catalog``, and
+``SHOW SCHEMAS IN `workspace`.`lakehouse``` is refused — a bare ``SHOW SCHEMAS``
+lists the *attached* Lakehouse and nothing else. Schema discovery therefore reads
+the destination's ``Tables/`` area through the store, which works across
+Lakehouses on both workspaces and is what prune already does. Offering a
+``list_schemas`` here that silently answered for the wrong Lakehouse would be the
+ambient-context mistake wearing an abstraction (how-does-build-work §4).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..errors import InstallError
+from . import tokens
+from .destination import SparkDestination
+
+
+class SparkCatalogue:
+    """Catalogue operations against one logical Spark destination."""
+
+    def __init__(self, spark: Any, destination: SparkDestination) -> None:
+        if spark is None:
+            raise InstallError(
+                f"a Spark session is needed to reach {destination.item!r}, "
+                "and none was provided"
+            )
+        self.spark = spark
+        self.destination = destination
+        if destination.case_sensitive_analysis:
+            # Local's folded schema is lower-case and every declared object keeps
+            # its exact Weaver spelling. Unlike Fabric's catalogue, Spark's local
+            # session catalogue cannot look that object up again after reverting
+            # to case-insensitive analysis, so this is the emulator's session
+            # policy rather than a one-statement override.
+            spark.conf.set("spark.sql.caseSensitive", "true")
+
+    # --- naming -----------------------------------------------------------
+
+    def qualify(self, schema: str, name: str) -> str:
+        return self.destination.qualify(schema, name)
+
+    def qualified_schema(self, schema: str) -> str:
+        return self.destination.qualified_schema(schema)
+
+    def expand(self, statement: str) -> str:
+        """One payload's object tokens, resolved to this destination."""
+
+        return tokens.expand(statement, self.destination)
+
+    # --- execution ---------------------------------------------------------
+
+    def sql(self, statement: str) -> Any:
+        """Run one statement here, with its object tokens resolved first."""
+
+        return self.spark.sql(self.expand(statement))
+
+    # --- structure ---------------------------------------------------------
+
+    def create_schema(self, schema: str, *, if_not_exists: bool = True) -> str:
+        """Create a schema in this destination, and return the statement run.
+
+        The ``LOCATION`` clause is the destination's business, not the planner's:
+        local Spark needs one so a managed table lands under the Lakehouse's
+        ``Tables`` area, and a schema-enabled Fabric Lakehouse pins it natively and
+        must not be given one. It is also a resolved path, so it could not have
+        been frozen into a payload without tying the bundle to the machine that
+        generated it (how-does-build-work §15).
+        """
+
+        qualifier = " IF NOT EXISTS" if if_not_exists else ""
+        statement = f"CREATE SCHEMA{qualifier} {self.qualified_schema(schema)}"
+        location = self.destination.schema_location(schema)
+        if location is not None:
+            statement += f" LOCATION '{_escaped(location)}'"
+        self.spark.sql(statement)
+        return statement
+
+    def register_external_table(self, schema: str, name: str, location: str) -> str:
+        """Name a table in this destination whose storage it does not own.
+
+        This exists for one thing: an alias in the local emulator. Fabric
+        discovers a OneLake shortcut placed under a Lakehouse's ``Tables`` area by
+        itself, and the table simply appears in the catalogue; local Spark
+        discovers nothing, so the emulator has to say out loud what Fabric infers.
+
+        Unregistered first rather than created strictly, because an alias is a
+        pointer and re-pointing one is not a destructive transition. Dropping an
+        *external* table removes the registration and never the storage, which is
+        exactly the distinction that makes this safe: the data belongs to the item
+        that produced it.
+        """
+
+        qualified = self.qualify(schema, name)
+        self.spark.sql(f"DROP TABLE IF EXISTS {qualified}")
+        statement = (
+            f"CREATE TABLE {qualified} USING DELTA LOCATION '{_escaped(location)}'"
+        )
+        self.spark.sql(statement)
+        return statement
+
+    # --- discovery ---------------------------------------------------------
+
+    def schema_exists(self, schema: str) -> bool:
+        return bool(self.spark.catalog.databaseExists(self.qualified_schema(schema)))
+
+    def views(self, schema: str) -> tuple[str, ...]:
+        """Persistent view names in one schema of this destination.
+
+        Views are catalogue-only — there is no directory to find them in — so this
+        is the one part of an inventory that has to be asked of Spark.
+        """
+
+        rows = self._rows(f"SHOW VIEWS IN {self.qualified_schema(schema)}")
+        names = []
+        for row in rows:
+            data = row.asDict()
+            if data.get("isTemporary"):
+                continue
+            name = data.get("viewName") or data.get("name")
+            if name:
+                names.append(name)
+        return tuple(names)
+
+    def tables(self, schema: str) -> tuple[str, ...]:
+        """Table names in one schema of this destination.
+
+        ``SHOW TABLES`` returns views as well, so the views are taken back out.
+        Prune does not use this — a Delta table is a directory, and reading the
+        storage is what keeps reconciliation scoped to the one Lakehouse — but a
+        test asserting what a build actually created needs to ask the catalogue,
+        not the filesystem.
+        """
+
+        views = {name.lower() for name in self.views(schema)}
+        rows = self._rows(f"SHOW TABLES IN {self.qualified_schema(schema)}")
+        names = []
+        for row in rows:
+            data = row.asDict()
+            if data.get("isTemporary"):
+                continue
+            name = data.get("tableName") or data.get("name")
+            if name and name.lower() not in views:
+                names.append(name)
+        return tuple(names)
+
+    def exists(self, schema: str, name: str) -> bool:
+        """Whether one object exists in this destination, table or view."""
+
+        return bool(self.spark.catalog.tableExists(self.qualify(schema, name)))
+
+    def _rows(self, statement: str) -> list:
+        """Run a listing, reading an absent schema as an empty one.
+
+        A schema that is not there holds nothing, which is the answer an inventory
+        wants — and both workspaces raise for it rather than returning no rows. So the
+        absence is tolerated and everything else propagates, narrowly, for the same
+        reason :mod:`weaver.catalogue.reader` does it that way: a real failure read
+        as "nothing here" tells the next build that nothing is managed.
+        """
+
+        try:
+            return self.spark.sql(statement).collect()
+        except Exception as exception:
+            if _is_missing_schema(exception):
+                return []
+            raise
+
+
+#: Spark's error class for a namespace that does not exist. A missing Lakehouse
+#: reports the same one, which is what we want: an inventory of somewhere that is
+#: not there is empty either way.
+_ABSENT = frozenset({"SCHEMA_NOT_FOUND"})
+
+
+def _is_missing_schema(exception: Exception) -> bool:
+    """Whether this means "not created yet" rather than "went wrong".
+
+    Keyed on Spark's error class, not on message text, so a reworded message
+    cannot quietly turn an infrastructure failure into an empty inventory. The
+    class name is consulted only when no error class is available — a stub session
+    in a test, or a connector that raises a plain error.
+    """
+
+    error_class = getattr(exception, "getErrorClass", None)
+    if callable(error_class):
+        try:
+            found = error_class()
+        except Exception:  # pragma: no cover - a broken accessor is not absence
+            found = None
+        if found:
+            return found in _ABSENT
+    return any(name in str(exception) for name in _ABSENT) or (
+        "NoSuchNamespaceException" in type(exception).__name__
+        or "NoSuchDatabaseException" in type(exception).__name__
+    )
+
+
+def _escaped(value: str) -> str:
+    return value.replace("\\", "\\\\").replace("'", "\\'")
+
+
+def drop_local_destination_catalogue(
+    spark: Any, destination: SparkDestination
+) -> tuple[str, ...]:
+    """Forget every namespace folded beneath one emulated Lakehouse.
+
+    Local CLI sessions use a persistent metastore so a later process can see
+    what ``initialise`` and ``build`` registered. A local wipe must therefore
+    clear catalogue registrations as well as the Fabric-shaped filesystem tree;
+    Fabric performs that bookkeeping itself when its Lakehouse storage is
+    emptied and never calls this emulator-only primitive.
+    """
+
+    if destination.namespace or not destination.schema_prefix:
+        raise InstallError("local catalogue cleanup needs a folded local destination")
+    rows = spark.sql("SHOW DATABASES").collect()
+    prefix = destination.schema_prefix.casefold()
+    schemas = []
+    for row in rows:
+        data = row.asDict() if hasattr(row, "asDict") else {}
+        name = data.get("namespace") or data.get("databaseName") or data.get("schemaName")
+        if name and str(name).casefold().startswith(prefix):
+            schemas.append(str(name))
+    statements = []
+    for schema in sorted(schemas, key=str.casefold):
+        statement = f"DROP SCHEMA IF EXISTS {destination.qualified_schema(schema[len(destination.schema_prefix):])} CASCADE"
+        spark.sql(statement)
+        statements.append(statement)
+    return tuple(statements)

weaver/spark/destination.py

@@ -0,0 +1,195 @@
+"""How one logical Lakehouse is *named* in a Spark session.
+
+:class:`~weaver.locations.LakehouseSparkLocation` answers where a destination's
+bytes live. This answers the other half: what a statement has to write to reach
+that destination's catalogue, given that the session is attached somewhere else.
+
+The two workspaces disagree, and the disagreement is **data**, not behaviour — which
+is why there is one class here and two constructors rather than two classes.
+
+**Fabric** has a native namespace for exactly this. Under ``spark_catalog`` a
+schema is a three-level name, so an object is four parts::
+
+    `Weaver`.`Play_Lakehouse_1`.`Sales`.`Customer`
+     ^workspace ^lakehouse       ^schema ^object
+
+One session can create, read and drop through that name in any Lakehouse in the
+workspace, and can build a view in one over a table in another. Nothing has to be
+attached, and nothing has to be switched.
+
+**Local Spark** has no such namespace, and cannot be given one: a Delta catalogue
+can only be the *session* catalogue (``DeltaCatalog`` extends
+``DelegatingCatalogExtension``, and registered as an ordinary named catalogue its
+delegate is null), so ``spark.sql.catalog.<lakehouse>`` is not available. Its one
+namespace level is the database. The proxy therefore folds the Lakehouse into
+that level::
+
+    `sales_lh__sales`.`Customer`
+
+which is not Fabric syntax and is not meant to be. What it reproduces is the
+*property* Fabric's namespace provides and a bare ``Sales.Customer`` does not:
+two destinations that declare a schema of the same name stay apart. Storage is
+untouched by the folding — the database still carries an explicit ``LOCATION`` of
+``<lakehouse>/Tables/<schema>``, so a managed table lands exactly where the
+Fabric layout puts it and the emulator keeps mirroring OneLake. The folded
+database identifier is lower-case because the local session catalogue registers
+it that way; declared object identifiers remain exact-case under the emulator's
+case-sensitive analysis policy.
+
+A destination is never carried in a build bundle. It is derived at install time
+from the item the bundle names, because a Fabric namespace is workspace-specific
+and a local one is rooted in a temporary directory — see
+:class:`~weaver.locations.LakehouseSparkLocation` for why a bundle that moved
+with either would stop being comparable between environments
+(how-does-build-work §15).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from ..errors import IdentityError
+
+#: Local Spark accepts word characters in a database name and nothing else, so a
+#: folded name is only legal if the Lakehouse's own name is.
+_LEGAL_LOCAL_NAME = re.compile(r"\A\w+\Z")
+
+#: What separates the Lakehouse from the schema in the folded local name. Two
+#: characters, so a single underscore in either half cannot be mistaken for it.
+LOCAL_SEPARATOR = "__"
+
+
+def identifier(name: str) -> str:
+    """A back-tick quoted Spark identifier, safe for spaces and keywords."""
+
+    return "`" + name.replace("`", "``") + "`"
+
+
+@dataclass(frozen=True)
+class SparkDestination:
+    """One logical Lakehouse, as a Spark session addresses it.
+
+    ``item`` is the logical name, and is what appears in a message. ``namespace``
+    is whatever sits above the schema — the workspace and Lakehouse on Fabric,
+    nothing locally. ``schema_prefix`` is the local fold, empty on Fabric.
+
+    ``tables_root`` is present only for the platform that needs it: local Spark
+    drops a managed table into its own warehouse directory unless the database
+    says otherwise, so the proxy supplies a ``LOCATION``. A schema-enabled Fabric
+    Lakehouse pins its own, and answers None.
+    """
+
+    item: str
+    namespace: tuple[str, ...] = ()
+    schema_prefix: str = ""
+    tables_root: str | None = None
+    preserve_table_identifier_case: bool = False
+    lowercase_schema_identifier: bool = False
+    case_sensitive_analysis: bool = False
+
+    def schema_identifier(self, schema: str) -> str:
+        """The schema's name at its own namespace level, unquoted."""
+
+        name = f"{self.schema_prefix}{_checked(schema, what='schema')}"
+        return name.lower() if self.lowercase_schema_identifier else name
+
+    def qualified_schema(self, schema: str) -> str:
+        """The schema, fully qualified — what ``CREATE SCHEMA`` is given."""
+
+        return ".".join(
+            identifier(part)
+            for part in (*self.namespace, self.schema_identifier(schema))
+        )
+
+    def qualify(self, schema: str, name: str) -> str:
+        """One object, fully qualified — what every statement names it by."""
+
+        return (
+            f"{self.qualified_schema(schema)}"
+            f".{identifier(_checked(name, what='object name'))}"
+        )
+
+    def schema_location(self, schema: str) -> str | None:
+        """Where this destination's managed tables for a schema must be pinned.
+
+        None when the platform pins them itself, which is the Fabric answer and
+        the reason no path reaches a Fabric ``CREATE SCHEMA``.
+        """
+
+        if self.tables_root is None:
+            return None
+        return f"{self.tables_root.rstrip('/')}/{_checked(schema, what='schema')}"
+
+    def __str__(self) -> str:
+        return self.item if not self.namespace else ".".join(self.namespace)
+
+
+def fabric_destination(*, workspace: str, lakehouse: str) -> SparkDestination:
+    """A Fabric Lakehouse, addressed by its native four-part name.
+
+    Both names are display names, deliberately: this is what Fabric's Spark
+    namespace is spelled with, and it is what a reviewer reading a statement can
+    recognise. The workspace and item *ids* stay where they belong — in
+    resolution, and in the bundle's target block.
+    """
+
+    return SparkDestination(
+        item=lakehouse,
+        namespace=(
+            _checked(workspace, what="workspace"),
+            _checked(lakehouse, what="lakehouse"),
+        ),
+        # Fabric otherwise folds a quoted table identifier to lower-case at
+        # creation.
+        preserve_table_identifier_case=True,
+    )
+
+
+def local_destination(*, item: str, tables_root: str) -> SparkDestination:
+    """A local Lakehouse, folded into the one namespace level Spark offers.
+
+    The Lakehouse name becomes part of every database name, so it has to be a
+    legal one. Refused rather than sanitised: a silently altered name would make
+    two destinations collide again, which is the single thing this exists to
+    prevent.
+    """
+
+    name = _checked(item, what="lakehouse")
+    if not _LEGAL_LOCAL_NAME.match(name):
+        raise IdentityError(
+            f"local Spark folds the Lakehouse name into its database names, and "
+            f"only accepts letters, digits and underscores there — {item!r} cannot "
+            "be addressed locally"
+        )
+    return SparkDestination(
+        item=name,
+        schema_prefix=f"{name}{LOCAL_SEPARATOR}",
+        tables_root=tables_root,
+        # The emulator mirrors Fabric's case-preserving table directories. Its
+        # folded schema itself was registered under Spark's case-insensitive
+        # policy, so every statement addresses it by its canonical lower case.
+        preserve_table_identifier_case=True,
+        lowercase_schema_identifier=True,
+        # Unlike Fabric's catalogue, Spark's local session catalogue cannot find
+        # a PascalCase table again after analysis returns to case-insensitive
+        # mode. The emulator therefore uses one exact-case policy for its life.
+        case_sensitive_analysis=True,
+    )
+
+
+def _checked(value: object, *, what: str) -> str:
+    """One name part, checked rather than trusted.
+
+    These strings are concatenated into identifiers and into paths, so a part
+    carrying a delimiter would name something other than what it says.
+    """
+
+    if not isinstance(value, str):
+        raise IdentityError(f"{what} must be a string, got {type(value).__name__}")
+    name = value.strip()
+    if not name:
+        raise IdentityError(f"{what} must not be empty")
+    if "." in name or "/" in name or "\\" in name:
+        raise IdentityError(f"{what} must not contain a separator: {value!r}")
+    return name

weaver/spark/session.py

@@ -0,0 +1,84 @@
+"""A leak-free local Delta session for CLI execution."""
+
+from __future__ import annotations
+
+import os
+import sys
+from importlib import import_module
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Iterator
+
+from ..diagnostics import SUPPORTED_JAVA, find_java_home
+from ..errors import CommandError
+
+
+@contextmanager
+def local_delta_session(workspace=None) -> Iterator[object]:
+    """Create one local Delta session and always stop it before returning.
+
+    CLI invocations are separate JVMs. When a local Workspace is supplied its
+    Spark metastore therefore lives beneath that emulator root, so namespaces
+    and table registrations created by ``initialise`` remain visible to the next
+    ``build`` command just as Fabric's catalogue remains visible between
+    sessions. Tests that supply no Workspace keep Spark's process-local default.
+    """
+
+    try:
+        configure_spark_with_delta_pip = import_module(
+            "delta"
+        ).configure_spark_with_delta_pip
+        SparkSession = import_module("pyspark.sql").SparkSession
+    except ImportError as exc:
+        raise CommandError(
+            "local build needs the Spark extra; install weaverstack[spark]"
+        ) from exc
+
+    java_home = find_java_home()
+    if java_home is None:
+        raise CommandError(
+            f"local build needs Java {' or '.join(SUPPORTED_JAVA)}; run weaver doctor"
+        )
+    previous = {
+        name: os.environ.get(name)
+        for name in ("JAVA_HOME", "PYSPARK_PYTHON", "PYSPARK_DRIVER_PYTHON")
+    }
+    os.environ["JAVA_HOME"] = java_home
+    os.environ["PYSPARK_PYTHON"] = sys.executable
+    os.environ["PYSPARK_DRIVER_PYTHON"] = sys.executable
+    builder = (
+        SparkSession.builder.appName("weaverstack-cli")
+        .master("local[*]")
+        .config("spark.sql.extensions", "io.delta.sql.DeltaSparkSessionExtension")
+        .config(
+            "spark.sql.catalog.spark_catalog",
+            "org.apache.spark.sql.delta.catalog.DeltaCatalog",
+        )
+        .config("spark.ui.enabled", "false")
+        .config("spark.sql.shuffle.partitions", "1")
+        .config("spark.databricks.delta.snapshotPartitions", "1")
+    )
+    if workspace is not None:
+        root_value = getattr(workspace, "workspace", workspace)
+        root = Path(root_value).expanduser().resolve() / ".weaver" / "spark"
+        builder = (
+            builder.config("spark.sql.catalogImplementation", "hive")
+            .config("spark.sql.warehouse.dir", str(root / "warehouse"))
+            .config(
+                "javax.jdo.option.ConnectionURL",
+                f"jdbc:derby:;databaseName={root / 'metastore'};create=true",
+            )
+        )
+    session = None
+    try:
+        session = configure_spark_with_delta_pip(builder).getOrCreate()
+        session.sparkContext.setLogLevel("ERROR")
+        yield session
+    finally:
+        if session is not None:
+            session.stop()
+        for name, value in previous.items():
+            if value is None:
+                os.environ.pop(name, None)
+            else:
+                os.environ[name] = value

weaver/spark/tokens.py

@@ -0,0 +1,138 @@
+"""How a frozen payload names an object without naming a destination.
+
+A generated statement has to say *which* object it acts on. It must not say
+which Lakehouse, in which workspace, at which path: that is bound by the batch's
+target, resolved at install time, and different in every environment. Writing it
+into the SQL would make two bundles of the same repository differ in every
+payload merely for having been generated somewhere else, which is exactly the
+comparison how-does-build-work §15 exists to protect.
+
+So a payload names an object logically, and the executor asks the batch's
+destination what that is called there::
+
+    CREATE VIEW {{object:Sales.ActiveCustomer}} AS
+    SELECT * FROM {{object:Sales.Customer}} WHERE IsActive
+
+    Fabric   ->  `Weaver`.`Play_Lakehouse_1`.`Sales`.`ActiveCustomer`
+    local    ->  `sales_lh__sales`.`ActiveCustomer`
+
+This is substitution of a transport-level value, not a template (§16). Nothing
+semantic is left for the installer to decide: the object, its schema, the
+statement and the destination are all fixed before the bundle is written — the
+only thing supplied late is how that already-chosen destination spells a name.
+A reviewer reading the payload sees the object; the manifest's target block says
+where it goes. A bare two-part name said neither, and resolved through whatever
+the session happened to be attached to.
+
+The tokens are deliberately unmistakable. ``{{`` and ``}}`` are not Spark SQL, so
+an unexpanded one is a syntax error at the point of use rather than a name that
+quietly resolves somewhere else.
+"""
+
+from __future__ import annotations
+
+import re
+
+from ..errors import InstallError
+from .destination import SparkDestination
+
+#: ``{{object:Schema.Name}}`` — one managed object.
+OBJECT = re.compile(r"\{\{object:([^.{}]+)\.([^.{}]+)\}\}")
+
+#: ``{{schema:Name}}`` — one managed schema.
+SCHEMA = re.compile(r"\{\{schema:([^.{}]+)\}\}")
+
+#: ``{{epoch}}`` — the instant this installation published its Registry.
+#:
+#: The one token that is not about a destination, which is why :func:`expand`
+#: does not resolve it: it is scoped to the *installation*, and every statement
+#: in a build must receive the same value however many destinations they name.
+#: :func:`substitute_epoch` puts it in, and it has to run first — ``expand``
+#: rejects any token it does not recognise, so an epoch that reached it would be
+#: an error rather than silently surviving into the engine.
+#:
+#: It is a token rather than a literal frozen at generation time for the reason
+#: this whole module exists: a rendered clock would make the same repository
+#: produce different payload bytes on every run, and a bundle's identity is its
+#: bytes.
+EPOCH = re.compile(r"\{\{epoch\}\}")
+
+#: The payload spelling of the publication epoch.
+EPOCH_TOKEN = "{{epoch}}"
+
+#: Anything else in token shape. Matched only so an unknown one is reported
+#: rather than passed through to the engine as mystery syntax.
+ANY = re.compile(r"\{\{[^{}]*\}\}")
+
+
+def object_token(schema: str, name: str) -> str:
+    """The payload spelling of one object."""
+
+    return f"{{{{object:{_part(schema, 'schema')}.{_part(name, 'object name')}}}}}"
+
+
+def schema_token(schema: str) -> str:
+    """The payload spelling of one schema."""
+
+    return f"{{{{schema:{_part(schema, 'schema')}}}}}"
+
+
+def expand(text: str, destination: SparkDestination) -> str:
+    """Every token in ``text``, resolved against one destination.
+
+    An unrecognised token is an error. Leaving it in place would hand Spark
+    something it cannot parse — better — or, if the shape ever became valid
+    syntax, something that means the wrong thing — far worse.
+    """
+
+    text = OBJECT.sub(
+        lambda match: destination.qualify(match.group(1), match.group(2)), text
+    )
+    text = SCHEMA.sub(
+        lambda match: destination.qualified_schema(match.group(1)), text
+    )
+    leftover = ANY.search(text)
+    if leftover:
+        raise InstallError(
+            f"{leftover.group(0)} is not a name this installer knows how to "
+            f"resolve against {destination.item!r}"
+        )
+    return text
+
+
+def substitute_epoch(text: str, epoch: str | None) -> str:
+    """Resolve ``{{epoch}}`` to one installation's publication instant.
+
+    Separate from :func:`expand` because the value is not a destination's
+    business: one install writes Registry rows for several items against several
+    targets, and they all have to carry the same instant or two rows published
+    by one build would order against each other.
+
+    A statement carrying the token when no epoch was supplied is a fault worth
+    naming here — the alternative is ``expand`` reporting it as an unresolvable
+    name, which says nothing about the missing value.
+    """
+
+    if not EPOCH.search(text):
+        return text
+    if epoch is None:
+        raise InstallError(
+            "a statement names {{epoch}} but this installation supplied none, so "
+            "the row it writes could not be dated"
+        )
+    return EPOCH.sub(epoch.replace("\\", "\\\\"), text)
+
+
+def _part(value: str, what: str) -> str:
+    """One name part, checked against the delimiters the token is built from."""
+
+    name = (value or "").strip()
+    if not name:
+        raise ValueError(f"{what} must not be empty")
+    for character in (".", "{", "}"):
+        if character in name:
+            raise ValueError(
+                f"{what} must not contain {character!r}, which delimits an "
+                f"object token: {value!r}"
+            )
+    return name