Skip to content

Python API reference

Everything below is importable from pydiggs and follows Semantic Versioning: names are only removed or changed in a major release, after a deprecation warning.

Where to start

Most programs need only validate() for files or validate_bytes() for data already in memory. Both return a Report; see Findings for its JSON form.

Validate

validate

validate(
    path: str | PathLike[str],
    *,
    diggs_version: str | None = None,
    checks: Iterable[str | Step] | None = None,
    schema_path: str | PathLike[str] | None = None,
    dictionary_path: str | PathLike[str] | None = None,
    schematron_path: str | PathLike[str] | None = None,
    allow_network: bool = False,
    include_snippets: bool = False,
    max_findings: int | None = DEFAULT_MAX_FINDINGS,
    max_bytes: int = DEFAULT_MAX_BYTES,
    base_dir: str | PathLike[str] | None = None,
    local_dictionaries: LocalDictionaries = "instance-dir",
    time_budget: float | None = None,
) -> Report

Validate one DIGGS instance with every native check and return the findings.

Nothing is printed and no file is written. Problems in the instance, including XML that is not well-formed, are findings in the report; only an unreadable instance, a broken trusted input, or a bad argument raises.

Safe to call from several threads at once: compiled validators are kept per thread, so a new thread pays one cold compile (see :func:warm_up). To validate bytes you received (an upload), use :func:validate_bytes instead.

Parameters:

Name Type Description Default
path str | PathLike[str]

The instance file.

required
diggs_version str | None

"2.5.a", "2.6" or "3.0.0"; detected from the root namespace when omitted (3.0.0 when unknown). "3.1-dev" (the unreleased DIGGS 3.1 draft, experimental) is used only when passed here, and adds a schema.unreleased-profile warning when the schema step runs against it.

None
checks Iterable[str | Step] | None

Step names to run, from structure, schema, dictionary, schematron, geometry, deprecation, context. Default: all of them. Every selected step runs even when an earlier one fails.

None
schema_path str | PathLike[str] | None

XSD to use instead of the bundled one (trusted input).

None
dictionary_path str | PathLike[str] | None

Primary property dictionary instead of the bundled one.

None
schematron_path str | PathLike[str] | None

Schematron rules instead of the bundled ones (trusted input: Schematron compiles to XSLT, which can read local files).

None
allow_network bool

Fetch whitelisted remote code lists that are not bundled.

False
include_snippets bool

Attach each finding's element XML (up to 1 KiB). Off by default because snippets carry the file's data.

False
max_findings int | None

Keep at most this many findings (default 10,000; None for no limit). When it is reached, one structure.findings-truncated finding, as severe as the worst one left out, says how many were dropped, and the steps that lost findings are incomplete.

DEFAULT_MAX_FINDINGS
max_bytes int

Largest instance accepted, in bytes (default :data:DEFAULT_MAX_BYTES, 100 MiB). The legacy validator keeps 1 GiB.

DEFAULT_MAX_BYTES
local_dictionaries LocalDictionaries

"instance-dir" (default): a relative or file: codeSpace is read only if it names a file inside the instance's folder (no working-directory fallback, no escape through .. or symlinks); anything else is reported as not accessible (dictionary.3). "off": no local dictionary is read. The legacy dictionary_check() keeps its 1.1 behaviour.

'instance-dir'
base_dir str | PathLike[str] | None

Report the path relative to this folder (the bare file name when the file is outside it). Default: the working directory, unless that is / or an ancestor of the home directory, when the bare name is used.

None
time_budget float | None

Cooperative time budget in seconds, counted from the call and checked between steps (default None: no budget). When it runs out, the steps not yet run are incomplete and the report gets one structure.timeout error (fail closed), as pydiggs validate --timeout reports. It does not interrupt a running libxml2/libxslt call, so a step can overrun it; for a hard limit, use process isolation (the CLI's --timeout, which stops the process).

None

Returns:

Name Type Description
A Report

class:~pydiggs.Report; report.ok is True when no finding is an error.

Raises:

Type Description
InstanceReadError

The instance cannot be read (also an OSError).

ResourceError

A schema, dictionary or Schematron file, or bundled data, is missing or broken.

ValueError

diggs_version or checks names something unknown, or a limit or the time budget is not positive.

Examples:

>>> from pydiggs import validate
>>> report = validate("tests/test_files/2.6/Schema_Error_1-2_6.xml")
>>> report.ok, report.diggs_version, report.steps["schema"]
(False, '2.6', 'failed')
>>> first = report.findings[0]
>>> first.rule_id, first.line
('schema.cvc-complex-type.2.4', 12)
>>> first.xpath.rsplit("/", 1)[-1]
'businessAssociate[1]'

validate_bytes

validate_bytes(
    data: bytes | bytearray | memoryview | BinaryIO,
    *,
    name: str | None = None,
    diggs_version: str | None = None,
    checks: Iterable[str | Step] | None = None,
    allow_network: bool = False,
    include_snippets: bool = False,
    max_findings: int | None = DEFAULT_MAX_FINDINGS,
    max_bytes: int = DEFAULT_MAX_BYTES,
    time_budget: float | None = None,
) -> Report

Validate a DIGGS document held in memory, such as an upload.

Applies every safety limit :func:validate applies and returns the same report, but never touches the filesystem for the instance: there is no path to resolve, local dictionaries are always off (a relative codeSpace is dictionary.3), and only the bundled schema, dictionaries and Schematron rules are used. Safe to call from several threads at once (see :func:warm_up).

allow_network and include_snippets exist for library callers. Never set them from request data: one makes pydiggs fetch URLs the document names, the other copies document content into the report.

Parameters:

Name Type Description Default
data bytes | bytearray | memoryview | BinaryIO

The document: bytes, a bytearray or contiguous memoryview (copied first), or a binary stream, read until EOF or one byte past max_bytes and left open.

required
name str | None

The file name to report (Report.path). Only its last component is kept, splitting on / and \; control characters are escaped and it is cut to 255 characters. Missing, empty, . or ..: "input.xml".

None
diggs_version str | None

As for :func:validate.

None
checks Iterable[str | Step] | None

As for :func:validate.

None
allow_network bool

Fetch whitelisted remote code lists that are not bundled.

False
include_snippets bool

Attach each finding's element XML (up to 1 KiB).

False
max_findings int | None

As for :func:validate.

DEFAULT_MAX_FINDINGS
max_bytes int

Largest document accepted, in bytes (default 100 MiB).

DEFAULT_MAX_BYTES
time_budget float | None

Cooperative time budget in seconds, as for :func:validate; running out gives a structure.timeout report, never an exception. It cannot interrupt a running libxml2/libxslt call; for a hard limit (timeout), run validation in a separate process and stop it.

None

Returns:

Name Type Description
A Report

class:~pydiggs.Report whose absolute_path is None.

Raises:

Type Description
InstanceReadError

data is larger than max_bytes (EFBIG), gzip-compressed (EINVAL), or the stream could not be read. The message names only Report.path.

ResourceError

pydiggs's bundled data is missing or broken.

ValueError

diggs_version or checks names something unknown, or a limit or the time budget is not positive.

TypeError

data is str, a text stream, a non-contiguous memoryview or another unsupported type, or name is not a string.

Examples:

>>> from pydiggs import validate_bytes
>>> upload = b'<Diggs xmlns="http://diggsml.org/schemas/2.6"><oops/></Diggs>'
>>> report = validate_bytes(upload, name="C:\\uploads\\BH-01.xml")
>>> report.path, report.absolute_path, report.ok
('BH-01.xml', None, False)
>>> report.steps["schema"]
'failed'
>>> validate_bytes(b"<Diggs", checks=["structure"]).findings[0].rule_id
'structure.well-formed'

detect_diggs_version

detect_diggs_version(
    source: str | Path | _ElementTree | _Element,
    *,
    default: str = DEFAULT_PROFILE,
) -> str

Detect a DIGGS profile key from an instance path or parsed document.

Unknown or missing namespaces fall back to default (3.0.0 per HG1/HG2). An experimental profile (:data:EXPERIMENTAL_PROFILES) is never returned unless it is passed as default.

warm_up

warm_up(diggs_version: str | None = None) -> None

Compile the bundled validators for the calling thread, ahead of the first file.

Compiled schemas, Schematron rules and dictionary data are kept per thread, so the first :func:validate or :func:validate_bytes call on a new thread pays for compiling them. Call this from a thread pool's initialiser (or once at start) so no request does. Repeated calls cost almost nothing.

Parameters:

Name Type Description Default
diggs_version str | None

Warm only this DIGGS version's schema; None (default) warms every released bundled version (about a second in all on a cold start), not the experimental 3.1-dev.

None

Raises:

Type Description
ValueError

diggs_version is not a bundled DIGGS version.

ResourceError

pydiggs's bundled data is missing or broken.

Examples:

>>> from concurrent.futures import ThreadPoolExecutor
>>> from pydiggs import validate_bytes, warm_up
>>> with ThreadPoolExecutor(2, initializer=warm_up, initargs=("2.6",)) as pool:
...     report = pool.submit(validate_bytes, b"<Diggs/>").result()
>>> report.verdict
'not-valid'

Read

Stable from 1.7.0; see Reading files. The node and value classes are in pydiggs.model.

read

read(
    path: str | PathLike[str],
    *,
    diggs_version: str | None = None,
    results: bool = True,
    provenance: Literal["object", "field"] = "object",
    max_bytes: int = DEFAULT_MAX_BYTES,
    time_budget: float | None = None,
) -> Model

Read a DIGGS file into a :class:~pydiggs.model.Model.

Reading is lenient: a schema-invalid file still reads, and nothing about the model says whether the file is valid (use :func:pydiggs.validate for that). What reading had to work around is in model.notes. Nothing is fetched from the network.

Parameters:

Name Type Description Default
path str | PathLike[str]

The file. It must be a regular file of at most max_bytes bytes and not gzip-compressed.

required
diggs_version str | None

Read as this DIGGS version instead of the detected one (the experimental 3.1-dev is used only when named here).

None
results bool

False keeps every result table's columns and row_count but no values: an inventory of a large file.

True
provenance Literal['object', 'field']

"object" (the default) gives every node its xpath and line; "field" also records, in provenance.fields, where each value the node read came from (larger JSON).

'object'
max_bytes int

Largest file accepted (default 100 MiB, as for validate).

DEFAULT_MAX_BYTES
time_budget float | None

Seconds to spend; when they run out the members read so far are returned with complete=False and a structure.timeout note. Reading also stops, the same way with a structure.read-limit note, at a work limit: more objects, or more elements the model has no typed field for, than 100,000 plus one per 200 bytes of the file, or such elements nested more than 64 deep (real files have a few thousand, about 10 deep).

None

Raises:

Type Description
InstanceReadError

The file is missing, unreadable, too large, compressed or not a regular file.

DocumentError

The file is not a readable DIGGS document (kind: malformed, not-diggs, unsafe-entity or namespace-too-long).

ValueError

An argument is out of range.

Examples:

>>> from pydiggs import read
>>> m = read("tests/fixtures/official/3.0/Borehole-CPT_Example_Annotated.xml")
>>> m.source.diggs_version, len(m.features) > 0
('3.0.0', True)

read_bytes

read_bytes(
    data: bytes | bytearray | memoryview | BinaryIO,
    *,
    name: str | None = None,
    diggs_version: str | None = None,
    results: bool = True,
    provenance: Literal["object", "field"] = "object",
    max_bytes: int = DEFAULT_MAX_BYTES,
    time_budget: float | None = None,
) -> Model

Read a DIGGS document held in memory, such as an upload.

The same as :func:read, with the input rules of :func:pydiggs.validate_bytes: a bytearray or memoryview is copied first, a binary stream is read to its end and left open, and name is reduced to its last path component.

Raises:

Type Description
InstanceReadError

The input is too large, compressed or an unreadable stream.

DocumentError

The bytes are not a readable DIGGS document.

TypeError

data is text, a text stream or a non-contiguous memoryview.

ValueError

An argument is out of range.

Model dataclass

Model(
    *,
    schema_version: str,
    tool: Mapping[str, str],
    source: SourceInfo,
    complete: bool,
    limits_hit: tuple[str, ...] = (),
    document: DocumentInfo | None = None,
    projects: tuple[Project, ...] = (),
    associates: tuple[Associate, ...] = (),
    features: tuple[Feature, ...] = (),
    sampling_activities: tuple[SamplingActivity, ...] = (),
    samples: tuple[Sample, ...] = (),
    observations: tuple[Observation, ...] = (),
    measurements: tuple[Measurement, ...] = (),
    others: tuple[Other, ...] = (),
    crs: Mapping[str, CrsRef] = (
        lambda: MappingProxyType({})
    )(),
    links: tuple[Link, ...] = (),
    notes: tuple[Finding, ...] = (),
)

Everything one DIGGS file describes, as a graph of nodes and links.

Read one with :func:pydiggs.read. Nodes are grouped by what they are (features, samples, measurements, …), each tuple in document order; links holds every reference between them and notes what reading had to work around (findings, not a validity verdict).

nodes

nodes() -> Iterator[Node]

Every node, each once.

The document, each collection in order, lithology layers, then every nested :class:Component (depth first, in document order).

get

get(key: str) -> Node | None

The node with this key, or None.

related

related(
    node: Node | str,
    *,
    relation: str | None = None,
    direction: Direction = "out",
) -> tuple[Node, ...]

Nodes linked to node, in link order, each once.

direction picks those it refers to (out), those that refer to it (in), or both; relation keeps only links of that relation.

owner_of

owner_of(finding: Finding) -> Node | None

The deepest node that contains the element a finding points at, or None.

to_dict

to_dict() -> dict[str, Any]

The model as a diggs-model document (plain dicts and lists).

to_json

to_json(indent: int | None = None) -> str

The model as diggs-model JSON; the same model always gives the same text.

write_json

write_json(fp: IO[str], indent: int | None = None) -> None

Write :meth:to_json to a text stream.

from_dict classmethod

from_dict(data: Mapping[str, Any]) -> Model

Build a model from a diggs-model document; unknown fields are ignored.

Raises:

Type Description
ValueError

the document does not have the model's shape, a node key repeats, a link names a node that is not there, or its schema_version has another major version.

from_json classmethod

from_json(text: str | bytes) -> Model

Build a model from diggs-model JSON (see :meth:from_dict).

model_schema

model_schema() -> dict[str, Any]

The packaged diggs-model JSON Schema, as a fresh dict.

Component dataclass

Component(
    *,
    key: str,
    gml_id: str | None,
    element: str,
    kind: str,
    name: str | None,
    names: tuple[str, ...],
    description: str | None,
    remarks: tuple[str, ...],
    params: Mapping[str, Param] = (
        lambda: MappingProxyType({})
    )(),
    provenance: Provenance,
    extra: tuple[ExtraNode, ...],
    role: str = "",
    interval: Interval | None = None,
    location: Position | None = None,
    time: TimeSpan | None = None,
    components: tuple[Component, ...] = (),
)

Bases: Node

A record nested inside another node, kept as a node of its own.

A casing, a backfill, a water strike, a well opening, an SPT drive set, the cone of a CPT, a constituent of a lithology. role is the DIGGS property that holds it (casing, waterStrike, driveSet …); interval, location and time are where and when it applies, when it says; components are the records nested in it (a water strike's readings, a backfill's layers).

Procedure dataclass

Procedure(
    *,
    type: str,
    params: Mapping[str, Param] = (
        lambda: MappingProxyType({})
    )(),
    components: tuple[Component, ...] = (),
    extra: tuple[ExtraNode, ...] = (),
)

How a measurement was made: the procedure element and its parameters.

params holds the procedure's simple parameters by DIGGS element name (totalPenetration, tipArea …); components its nested records (each SPT drive set, the cone, a sieve analysis).

DocumentError

DocumentError(
    kind: str, message: str, finding: Finding | None = None
)

Bases: PydiggsError, ValueError

The bytes are not a readable document of the expected format (read APIs only).

kind says why. From :func:pydiggs.read: malformed (not well-formed XML), not-diggs (the root is not a DIGGS Diggs element), unsafe-entity (the internal DTD declares an entity whose value contains markup) or namespace-too-long (a namespace URI of more than 1,024 characters). From :func:pydiggs.ags4.read: not-ags4 (no AGS4 structure was found, or the content is binary) or unsupported-version (an AGS 3 or older file). The set may grow in a minor release. finding is the matching finding: for DIGGS the structure.* finding :func:pydiggs.validate reports for that file, for AGS4 an ags4.* finding. It is also a :class:ValueError.

Examples:

>>> from pydiggs import DocumentError, ags4
>>> try:
...     ags4.read_bytes(b"not an AGS4 file")
... except DocumentError as exc:
...     print(exc.kind, exc.finding.rule_id)
not-ags4 ags4.rule-2

Record kind and the matching finding.

Coordinate reference systems

parse

parse(
    srs_name: str,
    *,
    local_ids: frozenset[str] | None = None,
) -> CrsRef

What srs_name refers to, from the name and the EPSG subset alone.

form is epsg (one EPSG code or a compound of two), diggs (a DIGGS CRS registry entry), ogc (CRS84, CRS83 or CRS27: longitude first), local (the gml:id of an element in the file) or unknown. known says whether every part was found: the EPSG codes in the subset, or, given local_ids, the id in the file. A compound EPSG code is split into its horizontal and vertical parts.

epsg

epsg(code: int) -> CrsComponent | None

Facts about one EPSG CRS, or None when it is not in pyDIGGS's subset.

type is geographic_2d, geographic_3d, geocentric, projected, vertical or compound; unit is the axes' unit when they share one; axis_order names the axes in order (lat,lon for most geographic CRSs, east,north for most projected ones, up for heights).

Raises:

Type Description
ResourceError

the packaged subset cannot be read (a broken install).

epsg_source

epsg_source() -> Mapping[str, Any]

Where the EPSG facts come from.

The dataset, its version and date, the tool that extracted them, the owner and the terms of use.

Raises:

Type Description
ResourceError

the packaged subset cannot be read (a broken install).

SUPPORTED_SRS_FORMS module-attribute

SUPPORTED_SRS_FORMS: Final[tuple[str, ...]] = (
    "epsg",
    "diggs",
    "ogc",
    "local",
)

Data frames and GIS

The frames, polars and gis extras; see Reading files.

to_pandas

to_pandas(
    model: Model,
    view: str = "results",
    *,
    feature: str | None = None,
    kind: str | None = None,
    procedure: str | None = None,
    measurement: str | None = None,
    si: bool = False,
) -> Any

A view of model as a pandas.DataFrame (needs the frames extra).

Parameters:

Name Type Description Default
model Model

From :func:pydiggs.read.

required
view str

features, samples, layers, measurements or results (see the module documentation for their columns).

'results'
feature str | None

Only rows of the feature with this key.

None
kind str | None

Only features or measurements of this kind.

None
procedure str | None

Only measurements, or results, of this procedure type.

None
measurement str | None

Only results of the measurement with this key.

None
si bool

For results: values in SI units where the unit converts.

False

Raises:

Type Description
ImportError

pandas is not installed.

ValueError

view is unknown, or it does not take one of the filters given.

Examples:

>>> import pydiggs
>>> from pydiggs.frames import to_pandas
>>> m = pydiggs.read("tests/fixtures/official/2.6/CPT_and_PorePressureDissipation.xml")
>>> frame = to_pandas(m, "results", procedure="StaticConePenetrationTest")
>>> list(frame.columns[:5])
['measurement', 'feature', 'procedure', 'table', 'row']

to_polars

to_polars(
    model: Model,
    view: str = "results",
    *,
    feature: str | None = None,
    kind: str | None = None,
    procedure: str | None = None,
    measurement: str | None = None,
    si: bool = False,
) -> Any

A view of model as a polars.DataFrame (needs the polars extra).

The same views, filters and columns as :func:to_pandas.

Raises:

Type Description
ImportError

polars is not installed.

ValueError

view is unknown, or it does not take one of the filters given.

transform

transform(model: Model, to: str = 'EPSG:4326') -> Model

A copy of model with longitude and latitude in the CRS to, where possible.

Every position whose srsName names an EPSG or OGC CRS gets geographic (lon, lat, and h when the source is three-dimensional) in to, and transformed_by says so. coordinates and crs are never changed. A position already in to, or in a CRS that cannot be resolved, is left as it is. The height h of a geographic position is copied as written, not shifted to the new datum.

Transforming a model that was transformed before is safe: each position is computed again from its coordinates as written, so transform(transform(m)) equals transform(m), and a later to replaces an earlier one.

Parameters:

Name Type Description Default
model Model

From :func:pydiggs.read.

required
to str

A geographic CRS pyproj understands, such as "EPSG:4326" (WGS 84) or "EPSG:4269" (NAD83).

'EPSG:4326'

Returns:

Type Description
Model

A new model; model is not changed.

Raises:

Type Description
ImportError

pyproj is not installed (pip install 'pydiggs[gis]').

ValueError

to is not a geographic CRS.

Examples:

>>> import pydiggs
>>> from pydiggs import gis
>>> m = pydiggs.read("tests/fixtures/official/2.6/CPT_and_PorePressureDissipation.xml")
>>> moved = gis.transform(m)
>>> moved.features[0].location.coordinates == m.features[0].location.coordinates
True

to_geodataframe

to_geodataframe(
    model: Model,
    *,
    to: str = "EPSG:4326",
    kind: str | None = None,
) -> Any

The features of model as a geopandas.GeoDataFrame of points in to.

The columns are those of the features view of :mod:pydiggs.frames, plus geometry. A feature whose position cannot be brought to to (no location, or a local or unknown CRS) has an empty geometry and still has its row.

Parameters:

Name Type Description Default
model Model

From :func:pydiggs.read.

required
to str

The geographic CRS of the points (see :func:transform).

'EPSG:4326'
kind str | None

Only features of this kind, such as "borehole".

None

Raises:

Type Description
ImportError

the gis extra is not installed.

ValueError

to is not a geographic CRS.

write

write(
    model: Model,
    path: str | PathLike[str],
    *,
    driver: str | None = None,
    to: str = "EPSG:4326",
    kind: str | None = None,
) -> Path

Save the features of model as GeoPackage, GeoParquet or GeoJSON.

The format follows the file suffix (.gpkg, .parquet, .geojson) unless driver names it ("GPKG", "Parquet" or "GeoJSON"). An existing file is replaced. The rows and columns are those of :func:to_geodataframe; a GeoPackage's layer is named features.

Parameters:

Name Type Description Default
model Model

From :func:pydiggs.read.

required
path str | PathLike[str]

The file to write.

required
driver str | None

The format, when the suffix does not say.

None
to str

The geographic CRS of the points (see :func:transform).

'EPSG:4326'
kind str | None

Only features of this kind.

None

Returns:

Type Description
Path

path as a :class:~pathlib.Path.

Raises:

Type Description
ImportError

the gis extra is not installed.

ValueError

the format is not one of the three, or to is not geographic.

Results

Report dataclass

Report(
    *,
    path: str,
    sha256: str,
    diggs_version: str | None,
    steps: Mapping[Step, StepStatus],
    findings: tuple[Finding, ...] = (),
    tool_version: str,
    reference_data: Mapping[str, str] = dict(),
    absolute_path: str | None = None,
    status: FileStatus = "checked",
    format: FileFormat = "diggs",
)

Everything :func:pydiggs.validate found in one file.

path is the path as reported: relative to the working directory when the file is under it, else the bare file name. absolute_path is only written out when asked for (absolute_paths=True). steps says what happened to each native step, in pipeline order; findings are sorted deterministically. format is "diggs" unless the report is about an AGS4 file ("ags4", diggs-findings 1.1), which has no diggs_version.

Examples:

>>> r = Report(
...     path="site/BH-01.xml",
...     sha256="0" * 64,
...     diggs_version="3.0.0",
...     steps={Step.SCHEMA: "failed"},
...     findings=(
...         Finding(
...             step="schema",
...             rule_id="schema.cvc-elt.1",
...             severity="error",
...             message="No matching global declaration.",
...             line=2,
...         ),
...     ),
...     tool_version="1.2.0",
... )
>>> r.ok, r.counts
(False, {'error': 1, 'warning': 0, 'info': 0})
>>> r.to_dict()["findings"][0]["location"]
{'line': 2, 'column': None, 'xpath': None, 'gml_id': None}

ok property

ok: bool

True when there is no error-severity finding.

verdict property

verdict: Verdict

One word for the result, derived only from status, steps and findings.

In order: not-diggs (the root is not Diggs); not-valid (any error); partly-checked (no error, but a step is partial or incomplete: a step stopped by a safety limit has an error, so it is not-valid, while one whose warnings were cut by max_findings may have none); valid-with-warnings; valid.

counts property

counts: dict[str, int]

Number of findings per severity, always with all three keys.

__reduce__

__reduce__() -> tuple[Any, tuple[dict[str, Any]]]

Pickle support (steps and reference_data are read-only mappings).

Built from :func:dataclasses.fields, so a new field cannot be forgotten.

to_dict

to_dict(*, absolute_paths: bool = False) -> dict[str, Any]

This file's entry of the diggs-findings JSON document (files[] item).

Only the entry: for the whole one-file document ($schema, tool, files), use :meth:to_document.

to_document

to_document(
    *, absolute_paths: bool = False
) -> dict[str, Any]

Return this report as a whole one-file diggs-findings 1.2 document.

The dict form of :meth:to_json: dumping it with :func:pydiggs.findings_json's settings gives the same bytes. :meth:to_dict is just its files[0] entry. tool names the version that produced the report; for several reports in one document, use :func:pydiggs.findings_document.

Parameters:

Name Type Description Default
absolute_paths bool

Write absolute_path (when known) instead of path.

False

Returns:

Type Description
dict[str, Any]

A JSON-serialisable dict that validates against :func:pydiggs.findings_schema.

Examples:

>>> from pydiggs import validate_bytes
>>> doc = validate_bytes(b"<Diggs/>", name="a.xml").to_document()
>>> doc["format"], doc["schema_version"], doc["files"][0]["path"]
('diggs-findings', '1.2', 'a.xml')

to_json

to_json(
    indent: int | None = 2, *, absolute_paths: bool = False
) -> str

A complete diggs-findings 1.2 JSON document for this one file.

The text form of :meth:to_document.

to_sarif

to_sarif(*, absolute_paths: bool = False) -> dict[str, Any]

A SARIF 2.1.0 log (as a JSON-serialisable dict) for this one file.

Finding dataclass

Finding(
    *,
    layer: Layer = "native",
    step: Step,
    rule_id: str,
    severity: Severity,
    message: str,
    line: int | None = None,
    column: int | None = None,
    xpath: str | None = None,
    gml_id: str | None = None,
    source_snippet: str | None = None,
    path: str | None = None,
)

One problem found in one file.

line and column are 1-based; column is known only for XML syntax errors. xpath is the official diggs:get-path form (/diggs:Diggs[1]/diggs:samplingFeature[2]). gml_id is the gml:id of the nearest element at or above the problem. source_snippet is the offending element's XML, only when snippets were asked for. path is the place in a source that is not XML (diggs-findings 1.1): for AGS4, GROUP, GROUP/row or GROUP/row/HEADING, with DATA rows counted from 1.

Examples:

>>> f = Finding(
...     step=Step.DICTIONARY,
...     rule_id="dictionary.5",
...     severity=Severity.ERROR,
...     message='Code "x" is not found.',
...     line=12,
...     xpath="/diggs:Diggs[1]/diggs:Borehole[1]",
... )
>>> f.conformance_key()
('dictionary', 'error', 'xpath:/Diggs[1]/Borehole[1]', 'dictionary.5')
>>> Finding(step="schema", rule_id="dictionary.5", severity="error", message="")
Traceback (most recent call last):
...
ValueError: rule_id 'dictionary.5' is not a valid rule id for step 'schema'
>>> note = Finding(
...     step="ags4",
...     rule_id="ags4.rule-4",
...     severity="error",
...     message="A DATA row has fewer fields than the HEADING row.",
...     line=12,
...     path="GEOL/3",
... )
>>> note.path
'GEOL/3'

conformance_key

conformance_key() -> ConformanceKey

(step, severity, location, rule_id) used to match findings across layers.

The location is "xpath:" plus the normalised xpath when there is one. A finding with no xpath but a path (a source that is not XML) has "path:<path>", followed by ";line:<n>" when the line is known. Otherwise it is "line:<n>", else "file". The message is deliberately left out.

sort_key

sort_key() -> tuple[object, ...]

Deterministic order within a file: step, line, column, severity, rule, xpath, text.

Findings without a line come first; at the same place, errors come first. The remaining fields break any tie, so the order is total.

Severity

Bases: StrEnum

How serious a finding is: the official validator's ERROR, WARNING and INFO.

Examples:

>>> Severity("warning").rank > Severity.INFO.rank
True
>>> max(Severity, key=lambda s: s.rank)
<Severity.ERROR: 'error'>

rank property

rank: int

2 for error, 1 for warning, 0 for info; higher is more serious.

Step

Bases: StrEnum

The validation step a finding belongs to, in the official pipeline's order.

The names follow DIGGSml/validation's steps (DIGGS Structure, Schema Location, CodeType Validation ...), plus context for pydiggs's cross-reference checks. ags4 (reading and checking an AGS4 file) and convert (what a conversion lost) and diff (what :func:pydiggs.diff.compare could not settle) are not validation steps: :func:pydiggs.validate never runs them. New steps may be added in a minor release.

Examples:

>>> [s.value for s in Step][:4]
['structure', 'schema', 'codeType', 'dictionary']
>>> Step.SCHEMA.order < Step.DICTIONARY.order
True

order property

order: int

Position in the pipeline; findings sort by it.

Findings documents

findings_document

findings_document(
    reports: Iterable[Report],
    *,
    absolute_paths: bool = False,
) -> dict[str, Any]

Build one diggs-findings 1.2 document from several reports, sorted by path.

tool.version and tool.reference_data describe the running pydiggs. No reports gives a valid document with an empty files list.

Parameters:

Name Type Description Default
reports Iterable[Report]

Reports from :func:pydiggs.validate or :func:pydiggs.validate_bytes.

required
absolute_paths bool

Write each absolute_path (when known) instead of path.

False

Returns:

Type Description
dict[str, Any]

A JSON-serialisable dict that validates against :func:findings_schema. For one

dict[str, Any]

report made by this pydiggs it equals report.to_document().

Examples:

>>> from pydiggs import findings_document, validate_bytes
>>> b = validate_bytes(b"<Diggs/>", name="b.xml")
>>> a = validate_bytes(b"<x/>", name="a.xml")
>>> [f["path"] for f in findings_document([b, a])["files"]]
['a.xml', 'b.xml']
>>> findings_document([])["files"]
[]

findings_json

findings_json(
    reports: Iterable[Report],
    *,
    indent: int | None = 2,
    absolute_paths: bool = False,
) -> str

Serialise :func:findings_document deterministically.

Keys keep their documented order, non-ASCII text is written as is (ensure_ascii=False) and NaN is refused, so the same reports always give the same text. indent=None gives one line with no newline in it, safe for NDJSON.

Parameters:

Name Type Description Default
reports Iterable[Report]

As for :func:findings_document.

required
indent int | None

Spaces per level (default 2, as the CLI writes); None for one line.

2
absolute_paths bool

As for :func:findings_document.

False

Returns:

Type Description
str

The JSON text, without a trailing newline.

Examples:

>>> from pydiggs import findings_json, validate_bytes
>>> text = findings_json([validate_bytes(b"<Diggs/>")], indent=None)
>>> "\n" in text, text.startswith('{"$schema": "https://')
(False, True)

findings_schema

findings_schema() -> dict[str, Any]

Return the packaged diggs-findings JSON Schema (draft 2020-12), parsed.

The same file is published at :data:FINDINGS_SCHEMA_URL; reading it here needs no network. Each call returns a fresh copy, so changing it changes nothing else.

Returns:

Type Description
dict[str, Any]

The schema as a dict.

Raises:

Type Description
ResourceError

The packaged schema is missing or broken.

Examples:

>>> from pydiggs import FINDINGS_SCHEMA_URL, findings_schema
>>> schema = findings_schema()
>>> schema["$id"] == FINDINGS_SCHEMA_URL
True

FINDINGS_SCHEMA_VERSION module-attribute

FINDINGS_SCHEMA_VERSION: Final = _json.SCHEMA_VERSION

FINDINGS_SCHEMA_URL module-attribute

FINDINGS_SCHEMA_URL: Final = _json.SCHEMA_URL

Rules and versions

explain_rule

explain_rule(rule_id: str) -> RuleInfo

Describe one rule id, such as a finding's rule_id.

A well-formed id that pydiggs never emits ("crs.unknown") is not an error: it gets known=False, no severities, a generic description and no guidance. A known id gets plain-language guidance: its own when it has some, else its family's (so schema.cvc-complex-type.2.4 is explained more specifically than the schema.cvc-<rule> family as a whole).

Parameters:

Name Type Description Default
rule_id str

<step>.<name>, at most 256 characters.

required

Returns:

Name Type Description
The RuleInfo

class:RuleInfo for exactly this id.

Raises:

Type Description
ValueError

rule_id does not follow the rule-id grammar, names no step, or is longer than 256 characters.

TypeError

rule_id is not a string.

Examples:

>>> from pydiggs import explain_rule
>>> explain_rule("schematron.Borehole.totalMeasuredDepth").description
'Schematron rule Borehole.totalMeasuredDepth'
>>> explain_rule("schema.cvc-elt.1").pattern
'^schema\\.cvc-[A-Za-z0-9][A-Za-z0-9._-]*$'
>>> explain_rule("schema.cvc-complex-type.2.4").guidance.title
'Missing or misplaced entry'
>>> explain_rule("schema.cvc-length-valid").guidance.title
'Breaks the DIGGS format'
>>> explain_rule("crs.unknown").known
False
>>> explain_rule("not a rule")
Traceback (most recent call last):
...
ValueError: 'not a rule' is not a valid rule id (<step>.<name>)

rule_catalogue

rule_catalogue() -> tuple[RuleInfo, ...]

Every rule id pydiggs can emit: fixed ids, then open families as patterns.

Fixed ids come in pipeline (step) order, then alphabetically; the open families (schema.cvc-*, schema.libxml2.*, <step>.incomplete, schematron.user-* and user Schematron @id rules) follow, each with a pattern. The <step>.incomplete family is listed under structure but covers every step. A new entry may be added in a minor release. Every entry carries plain-language guidance.

Returns:

Type Description
tuple[RuleInfo, ...]

The catalogue, the same tuple on every call.

Examples:

>>> from pydiggs import rule_catalogue
>>> rules = rule_catalogue()
>>> rules[0].id
'structure.diggs-root'
>>> [r.id for r in rules if r.pattern][:2]
['schema.cvc-<rule>', 'schema.libxml2.<TYPE>']

RuleInfo dataclass

RuleInfo(
    *,
    id: str,
    pattern: str | None,
    step: Step,
    description: str,
    severities: tuple[Severity, ...],
    help_uri: str,
    known: bool,
    guidance: Guidance | None = None,
)

What one rule id (or one open family of them) means.

id is the rule id. For an open family in :func:rule_catalogue it is the family's template ("schema.cvc-<rule>") and pattern is the regular expression its ids match in full; for a fixed id pattern is None. :func:explain_rule returns the id asked about, with its family's pattern when it belongs to one. severities lists what a finding with this id can be, most serious first; known is False for a well-formed id pydiggs never emits. guidance is the plain-language :class:~pydiggs.Guidance for engineers who are not DIGGS specialists (title, meaning, fix); it is None only for an unknown id.

Examples:

>>> from pydiggs import explain_rule
>>> info = explain_rule("dictionary.5")
>>> info.step, info.severities, info.known
(<Step.DICTIONARY: 'dictionary'>, (<Severity.ERROR: 'error'>,), True)
>>> info.to_dict()["description"]
'Code is not found in the code list dictionary'
>>> info.guidance.title
'Unknown code'

to_dict

to_dict() -> dict[str, Any]

A JSON-serialisable dict (enums as their string values), in field order.

Guidance dataclass

Guidance(
    *, title: str, meaning: str, fix: str, locale: str
)

What a rule means for your data, in plain words, and what to do about it.

Attributes:

Name Type Description
title str

A few words that name the problem ("Unknown code").

meaning str

What is wrong with the data, and why it matters.

fix str

What to do, in your software or with your data supplier.

locale str

The language of the text, as a BCP 47 tag ("en").

Examples:

>>> from pydiggs import explain_rule
>>> guidance = explain_rule("dictionary.5").guidance
>>> guidance.title, guidance.locale
('Unknown code', 'en')
>>> sorted(guidance.to_dict())
['fix', 'locale', 'meaning', 'title']

to_dict

to_dict() -> dict[str, str]

A JSON-serialisable dict, in field order.

version_info

version_info() -> VersionInfo

Describe the running pydiggs: its version, findings schema and bundled data.

Returns:

Name Type Description
A VersionInfo

class:VersionInfo; version_info().to_dict() is JSON-ready.

Raises:

Type Description
ResourceError

The bundled PROVENANCE.toml is missing or broken.

Examples:

>>> import pydiggs
>>> info = pydiggs.version_info()
>>> info.pydiggs_version == pydiggs.__version__, info.diggs_versions
(True, ('2.5.a', '2.6', '3.0.0', '3.1-dev'))
>>> info.findings_schema_version
'1.2'

VersionInfo dataclass

VersionInfo(
    *,
    pydiggs_version: str,
    findings_schema_version: str,
    findings_schema_url: str,
    diggs_versions: tuple[str, ...],
    reference_data: Mapping[str, str] = dict(),
)

The versions a pydiggs install reports, for an /versions endpoint or a log line.

diggs_versions are the DIGGS versions with a bundled schema, oldest first. reference_data maps each vendored reference-data source (schemas, dictionaries, Schematron) to the upstream commit it was taken from.

Examples:

>>> from pydiggs import VersionInfo
>>> info = VersionInfo(
...     pydiggs_version="1.3.0",
...     findings_schema_version="1.0",
...     findings_schema_url="https://example.org/s.json",
...     diggs_versions=("2.6",),
...     reference_data={"schemas": "abc1234"},
... )
>>> info.to_dict()["diggs_versions"]
['2.6']

__reduce__

__reduce__() -> tuple[Any, ...]

Pickle and deep-copy through a plain dict; a mappingproxy cannot be pickled.

to_dict

to_dict() -> dict[str, Any]

A JSON-serialisable dict, in field order.

Capabilities

What this pyDIGGS can do; see Capabilities.

capabilities

capabilities() -> Capabilities

Describe what this pydiggs can do: every operation, its options and stability.

available is worked out now, in this interpreter: an operation whose extra is not installed (pip install 'pydiggs[gis]', say) is listed with available=False, so a host such as Pyodide, where only the core is installed, reports what it can really do. Nothing optional is imported to find out.

Returns:

Name Type Description
A Capabilities

class:Capabilities; capabilities().to_dict() is a diggs-capabilities

Capabilities

1.0 document (see :func:capabilities_schema).

Examples:

>>> import pydiggs
>>> caps = pydiggs.capabilities()
>>> [op.id for op in caps.operations][:5]
['validate', 'read', 'detect', 'rules.list', 'rules.explain']
>>> validate = caps.operations[0]
>>> validate.stability, validate.outputs, validate.needs, validate.available
('stable', ('diggs-findings-1.2',), (), True)
>>> validate.options["diggs_version"].choices
('2.5.a', '2.6', '3.0.0', '3.1-dev')

Capabilities dataclass

Capabilities(
    *,
    pydiggs_version: str,
    schema_version: str,
    operations: tuple[Operation, ...],
)

What a pydiggs install offers: its version and its :class:Operation entries.

Examples:

>>> import pydiggs
>>> caps = pydiggs.capabilities()
>>> caps.schema_version, caps.pydiggs_version == pydiggs.__version__
('1.0', True)
>>> caps.to_dict()["$schema"] == pydiggs.CAPABILITIES_SCHEMA_URL
True

to_dict

to_dict() -> dict[str, Any]

A diggs-capabilities document: JSON-serialisable, $schema first.

Operation dataclass

Operation(
    *,
    id: str,
    label: str,
    stability: str,
    inputs: tuple[str, ...] = (),
    outputs: tuple[str, ...] = (),
    options: Mapping[str, OptionSpec] = dict(),
    needs: tuple[str, ...] = (),
    available: bool = True,
)

One thing this pydiggs can do, such as validate, read or export.gpkg.

inputs and outputs name what the operation reads and gives: a DIGGS version (diggs-2.6), an AGS4 version (ags4-4.1.1), a pyDIGGS document contract (diggs-findings-1.2, diggs-model-1.0), a media type (application/geo+json) or, for an in-memory result, the Python type (pandas.DataFrame). needs lists the pyDIGGS extras the operation needs (empty for the core), and available says whether everything it needs is installed in this interpreter.

Examples:

>>> from pydiggs import Operation
>>> op = Operation(
...     id="read",
...     label="Read a DIGGS file",
...     stability="stable",
...     inputs=("diggs-3.0.0",),
...     outputs=("diggs-model-1.0",),
... )
>>> op.to_dict()["outputs"], op.available
(['diggs-model-1.0'], True)

__reduce__

__reduce__() -> tuple[Any, ...]

Pickle and deep-copy through a plain dict; a mappingproxy cannot be pickled.

to_dict

to_dict() -> dict[str, Any]

A JSON-serialisable dict, in field order.

OptionSpec dataclass

OptionSpec(
    *,
    type: str,
    label: str,
    default: OptionDefault = None,
    choices: tuple[str, ...] | None = None,
    required: bool = False,
)

One option of an :class:Operation: its type, default, choices and a label.

The option's name is its key in Operation.options; it is the keyword argument of the Python function and the parameter of the HTTP, MCP and sidecar requests that take it. default None means "not given" (the function then decides, as its documentation says); choices None means any value of type.

Examples:

>>> from pydiggs import OptionSpec
>>> spec = OptionSpec(type="boolean", label="Keep result values", default=True)
>>> spec.to_dict()["default"], spec.to_dict()["choices"]
(True, None)
>>> OptionSpec(type="date", label="x")
Traceback (most recent call last):
...
ValueError: OptionSpec.type must be one of boolean, ...; got 'date'

to_dict

to_dict() -> dict[str, Any]

A JSON-serialisable dict, in field order.

capabilities_schema

capabilities_schema() -> dict[str, Any]

The packaged diggs-capabilities JSON Schema, as a fresh dict.

The same file is published at :data:CAPABILITIES_SCHEMA_URL.

Raises:

Type Description
ResourceError

The packaged schema is missing or not valid JSON.

Examples:

>>> from pydiggs import CAPABILITIES_SCHEMA_URL, capabilities_schema
>>> schema = capabilities_schema()
>>> schema["$id"] == CAPABILITIES_SCHEMA_URL, schema["title"]
(True, 'diggs-capabilities 1.0')

CAPABILITIES_SCHEMA_VERSION module-attribute

CAPABILITIES_SCHEMA_VERSION: Final = '1.0'

CAPABILITIES_SCHEMA_URL module-attribute

CAPABILITIES_SCHEMA_URL: Final = "https://xinp-hub.github.io/pydiggs/schemas/diggs-capabilities-1.0.schema.json"

AGS4 and DIGGS conversion

Stable from pyDIGGS 1.11; see AGS4 and DIGGS conversion.

ags4_to_diggs

ags4_to_diggs(
    source: Source,
    *,
    diggs_version: str = "3.0.0",
    validate: bool = True,
    name: str | None = None,
    encoding: str | None = None,
    max_bytes: int = DEFAULT_MAX_BYTES,
    time_budget: float | None = None,
) -> Conversion

Convert an AGS4 file to a DIGGS 3.0.0 document, listing everything that was lost.

The bundled mapping table (version :data:MAPPING_VERSION, see :func:mapping_info) covers PROJ, TRAN, the ABBR/UNIT/TYPE/DICT lookups, LOCA, GEOL, SAMP, ISPT, LLPL, GRAG with GRAT, LNMC, and HORN, HDIA, CDIA, BKFL, WSTG with WSTD, LDEN, and static cone tests (SCPG with SCPT, and CPTG with CPTT); any other group is reported and not converted, and its rows are in residual.

Every non-null value of the source is either carried into DIGGS or named by a convert finding in report; nothing is dropped silently. Values are carried as reported: units are renamed only through the unit table, and nothing is converted numerically. Nothing the file names is opened, nothing is fetched, and the same file always gives the same bytes.

Parameters:

Name Type Description Default
source Source

A path, the bytes of a file (or a binary stream), or an :class:~pydiggs.ags4.File already read.

required
diggs_version str

The DIGGS version to write; only "3.0.0".

'3.0.0'
validate bool

Validate the output with :func:pydiggs.validate_bytes.

True
name str | None

A file name to report for bytes, a stream or a File.

None
encoding str | None

As for :func:pydiggs.ags4.read.

None
max_bytes int

As for :func:pydiggs.ags4.read.

DEFAULT_MAX_BYTES
time_budget float | None

Seconds for the whole call, measured from its start: reading, converting, validating and reading back are each given what is left. When it runs out while reading or converting, xml holds what was converted and convert.incomplete (or an ags4 note) says what was not; while validating, validation has a structure.timeout error, as :func:pydiggs.validate_bytes gives; while reading back, model holds the members read so far (model.complete is False, with a structure.timeout note) while xml stays whole. complete is False in every case but a validation timeout (check validation for that). Writing the XML is not stopped part way (it runs to its end), and none of the steps can interrupt a running libxml2 call, so the call can overrun the budget by up to one write and one such call.

None

Returns:

Name Type Description
The Conversion

class:Conversion.

Raises:

Type Description
InstanceReadError

As :func:pydiggs.ags4.read.

DocumentError

As :func:pydiggs.ags4.read (not AGS4, or AGS 3).

ValueError

diggs_version is not supported, or an argument is out of range.

ResourceError

A bundled mapping table, dictionary or layout is broken.

Examples:

>>> from pydiggs import convert
>>> c = convert.ags4_to_diggs("tests/fixtures/ags4/convert_tier_a.ags")
>>> c.validation.ok, c.model.source.diggs_version
(True, '3.0.0')
>>> c.trace["BH01"]
Origin(group='LOCA', row=1, line=60)
>>> sorted({f.rule_id for f in c.losses})[:2]
['convert.assumed', 'convert.unmapped-code']
>>> list(c.residual.groups)[:3]
['PROJ', 'TRAN', 'LOCA']

diggs_to_ags4

diggs_to_ags4(
    source: DiggsSource,
    *,
    ags_version: str = _DEFAULT_AGS_VERSION,
    check: bool = True,
    formula_guard: Literal["prefix"] | None = None,
    name: str | None = None,
    max_bytes: int = DEFAULT_MAX_BYTES,
    time_budget: float | None = None,
) -> Conversion

Convert a DIGGS document to an AGS4 file, listing everything that was lost.

The document is read with :func:pydiggs.read (any DIGGS version it reads) and the model converted as :func:model_to_ags4 does. Nothing is fetched and nothing the document names is opened.

Parameters:

Name Type Description Default
source DiggsSource

A path, or the bytes of a document (or a binary stream).

required
ags_version str

As for :func:model_to_ags4: "4.2" (the default) or "4.1.1". The BGS AGS validator (agsapi.bgs.ac.uk) and python-ags4 1.2.0 accept AGS4 only up to 4.1.1 (November 2026): pass ags_version="4.1.1" for files meant for them.

_DEFAULT_AGS_VERSION
check bool

As for :func:model_to_ags4.

True
formula_guard Literal['prefix'] | None

As for :func:model_to_ags4.

None
name str | None

A file name to report for bytes or a stream.

None
max_bytes int

As for :func:pydiggs.read.

DEFAULT_MAX_BYTES
time_budget float | None

Seconds for reading, as for :func:pydiggs.read; when they run out the model holds the members read so far and complete is False.

None

Returns:

Name Type Description
The Conversion

class:Conversion, with ags4 set.

Raises:

Type Description
InstanceReadError

As :func:pydiggs.read.

DocumentError

As :func:pydiggs.read.

ValueError

ags_version or formula_guard is not supported.

ResourceError

A bundled mapping table is broken.

Examples:

>>> from pydiggs import convert
>>> xml = convert.ags4_to_diggs("tests/fixtures/ags4/convert_tier_a.ags").xml
>>> c = convert.diggs_to_ags4(xml, name="site.xml")
>>> c.validation.ok, c.report.path, list(c.ags4.groups)[:4]
(True, 'site.xml', ['PROJ', 'TRAN', 'ABBR', 'TYPE'])

model_to_ags4

model_to_ags4(
    model: Model,
    *,
    ags_version: str = _DEFAULT_AGS_VERSION,
    check: bool = True,
    formula_guard: Literal["prefix"] | None = None,
) -> Conversion

Convert a DIGGS model to an AGS4 file, listing everything that was lost.

The model is mapped by the same bundled table as :func:ags4_to_diggs, read the other way. Every value of the model (each name and remark, params entry, typed field, extra node, link that is not structure, and result-table cell) is either written into a cell or named by a convert finding; a value with no AGS4 target is a convert.unmapped-element warning. Values are written as reported: a quantity's text as it was written, a result-table number in its shortest form, a unit renamed only through the unit table. pyDIGGS bundles no AGS4 data dictionary, so each heading's TYPE is the one its values have.

Text a spreadsheet would read as a formula (starting with =, +, @, or a - that is not a number) is written unchanged and reported as ags4.formula-text. With formula_guard="prefix", such text under a text (X) heading that is not a key is written with an apostrophe in front instead, and each heading is reported: that changes the value, so use it only for files meant for a spreadsheet.

Parameters:

Name Type Description Default
model Model

The model, as :func:pydiggs.read gives it.

required
ags_version str

The AGS4 version to write: "4.2" (the default) or "4.1.1". It is written in TRAN_AGS (as 4.2, the value python-ags4 recognises, not the 4.2.0 of the AGS example), and selects the groups that differ between the two: static cone tests are CPTG/CPTT in 4.2 and SCPG/SCPT in 4.1.1, and 4.2 also gives the CRS as an EPSG code (LOCA_NSRI, LOCA_LLSI). As of November 2026 the BGS AGS validator (agsapi.bgs.ac.uk) and python-ags4 1.2.0 accept AGS4 only up to 4.1.1: pass ags_version="4.1.1" for files meant for them.

_DEFAULT_AGS_VERSION
check bool

Check the output with :func:pydiggs.ags4.check (into validation).

True
formula_guard Literal['prefix'] | None

None (the default) or "prefix" (see above).

None

Returns:

Name Type Description
The Conversion

class:Conversion, with ags4 set.

Raises:

Type Description
ValueError

ags_version or formula_guard is not supported.

TypeError

model is not a :class:pydiggs.Model.

ResourceError

A bundled mapping table is broken.

Examples:

>>> import pydiggs
>>> from pydiggs import ags4, convert
>>> c = convert.ags4_to_diggs("tests/fixtures/ags4/site_tier_b_4_1_1.ags")
>>> back = convert.model_to_ags4(c.model)
>>> back.validation.ok, back.ags4.version, "CPTT" in back.ags4.groups
(True, '4.2', True)
>>> back.ags4.groups["HDIA"].records()[0]["HDIA_DIAM"]
'200'
>>> "SCPT" in convert.model_to_ags4(c.model, ags_version="4.1.1").ags4.groups
True

Conversion dataclass

Conversion(
    *,
    model: Model,
    report: Report,
    validation: Report | None,
    xml: bytes | None = None,
    ags4: File | None = None,
    residual: File | None = None,
    trace: Mapping[str, Origin] = (
        lambda: MappingProxyType({})
    )(),
    mapping_version: str = MAPPING_VERSION,
    complete: bool = True,
)

The result of a conversion, either way: the output, what it means, and what was lost.

AGS4 to DIGGS (:func:ags4_to_diggs): xml is the DIGGS document and model that document read back with :func:pydiggs.read_bytes, so it is always the model of a real DIGGS file; ags4 is None; residual is an AGS4 file of what was not converted (every value a convert finding names, with its row's key fields), so that the DIGGS output and the residual file together hold everything the source did; validation is :func:pydiggs.validate_bytes on xml; trace maps a node's key in model to the AGS4 row it came from.

DIGGS to AGS4 (:func:diggs_to_ags4, :func:model_to_ags4): ags4 is the AGS4 file (ags4.dumps(c.ags4) gives its bytes) and model the model it was made from; xml and residual are None and trace is empty; validation is :func:pydiggs.ags4.check on the output.

report is about the source: what reading it worked around and the conversion's findings (step convert; also ags4.formula-text for AGS4 output). losses are the convert findings of severity warning or error, each naming what did not reach the output or what was written by default; lossless is True when there are none. complete is False when a size or time limit stopped the conversion.

losses property

losses: tuple[Finding, ...]

The convert findings of severity warning or error, in report order.

lossless property

lossless: bool

True when nothing was lost or assumed (losses is empty).

save

save(path: str | PathLike[str]) -> None

Write the output to path (the DIGGS XML, or the AGS4 file), replacing a file.

Raises:

Type Description
ValueError

The conversion has no output (neither xml nor ags4).

OSError

The path cannot be written.

Origin dataclass

Origin(*, group: str, row: int, line: int | None = None)

Where a DIGGS node came from: an AGS4 group, a DATA row (from 1) and its line.

line is the line of that DATA row in the source file, or None for a file built in code.

mapping_info

mapping_info() -> dict[str, Any]

What the bundled mapping table covers: its version, groups and headings.

Returns:

Type Description
dict[str, Any]

A JSON-serialisable dict: mapping_version, ags_versions,

dict[str, Any]

diggs_versions, rules (each convert rule id and its severity) and

dict[str, Any]

groups, each with its name, pattern, status (draft or

dict[str, Any]

reviewed), keys, parent, to_ags4_versions (the AGS4 versions

dict[str, Any]

DIGGS to AGS4 writes it for; None for every one) and headings (name,

dict[str, Any]

to, target, property, reason, quantity for a measure, and

dict[str, Any]

direction: both, to-diggs or to-ags4).

Examples:

>>> from pydiggs import convert
>>> info = convert.mapping_info()
>>> info["mapping_version"], info["diggs_versions"]
('1.2', ['3.0.0'])
>>> [g["name"] for g in info["groups"]][:3]
['PROJ', 'TRAN', 'ABBR']
>>> sorted({g["status"] for g in info["groups"]}), "ags4" in str(info["rules"])
(['reviewed'], False)
>>> "convert.unmapped-element" in info["rules"]
True

MAPPING_VERSION module-attribute

MAPPING_VERSION: Final = '1.2'

Comparing files

Stable from pyDIGGS 1.13 (a preview in 1.12); see Comparing two files. import pydiggs does not load pydiggs.diff: use from pydiggs import diff.

compare

compare(
    old: Source,
    new: Source,
    *,
    match: str = "auto",
    rel_tol: float = 1e-09,
    abs_tol: float = 0.0,
    max_changes: int = 10000,
    time_budget: float | None = None,
    max_bytes: int = DEFAULT_MAX_BYTES,
    show_reformatted: bool = False,
    show_renamed: bool = False,
) -> Diff

Compare two DIGGS files at model level.

Stable from pyDIGGS 1.13; the result is a diggs-diff 1.0 document (:meth:Diff.to_json).

Give it the two files (paths or bytes) for the full comparison: what a model holds, and what each file holds of a record that its model does not keep. Given two :class:~pydiggs.model.Model, it compares the two models and can only see what a model holds, so an identical result then says that the models are equal. A file and a model are compared as two models.

Parameters:

Name Type Description Default
old Source

The earlier file: a path, the bytes of a file, or a :class:~pydiggs.model.Model. A reference to an element the model does not keep (a borehole's centre line) is compared by what it points to only when both are paths or bytes. With a model on either side it is compared by the record that holds the element and the text of the id, which cannot show that two such elements of one record exchanged their ids: only the files can. A model read with results=False has no cells to compare: when one of its tables has columns, the result is complete=False (limit old_results_not_read or new_results_not_read) with a diff.limit note, and so never identical.

required
new Source

The later file, in the same forms. The two may be different DIGGS versions; both are recorded in the result.

required
match str

How nodes are paired. "auto": by gml:id and element, then by natural key; "gml-id" (or "gml_id", as the report spells matched_by): the first pass only, so a node whose id changed is removed and added; "natural": the second pass only. A natural key that several nodes share is never matched. The report gives options.match as "gml-id".

'auto'
rel_tol float

Two numbers are equal when |a - b| <= max(abs_tol, rel_tol * max(|a|, |b|)). The default is exact up to float noise. From 0 to less than 1: at 1 every number would equal 0.

1e-09
abs_tol float

The absolute part of that bound (default 0).

0.0
max_changes int

Most entries listed (changed nodes plus their value changes). The counts in the summary stay exact; when the list is cut the result is complete=False with a diff.limit note.

10000
time_budget float | None

Seconds for the whole call, reading both files included. When it runs out the result is complete=False with a diff.timeout note.

None
max_bytes int

Largest file read (default 100 MiB, as for :func:pydiggs.read).

DEFAULT_MAX_BYTES
show_reformatted bool

List the values written differently but equal (1.50 and 1.5; other separators in a result set whose values read the same; double declared as float); they are always counted.

False
show_renamed bool

List the nodes matched by natural key whose own gml:id differs, each with the value gml_id (old and new id); they are always counted. A changed id is not a difference: such a node is unchanged unless one of its values differs.

False

Returns:

Name Type Description
A Diff

class:Diff. A problem with the data is a finding in Diff.notes.

Diff

Each side's source.sha256 is copied into the report as it is: a

Diff

class:~pydiggs.model.Model you build yourself must give the 64-digit hex

Diff

digest the diggs-model schema requires, or :meth:Diff.to_json is not a valid

Diff

diggs-diff 1.0 document.

Raises:

Type Description
InstanceReadError

A file is missing, unreadable, too large or compressed.

DocumentError

A file is not a readable DIGGS document.

TypeError

old or new is not a path, bytes or a model.

ValueError

An option is out of range.

Examples:

>>> from pydiggs import diff
>>> a = "tests/fixtures/official/3.0/MWDExample.xml"
>>> b = "tests/fixtures/official/3.0/TrenchWallExample.xml"
>>> diff.compare(a, a).identical
True
>>> result = diff.compare(a, b)
>>> result.identical, result.summary["features"]["removed"] > 0
(False, True)

Diff dataclass

Diff(
    *,
    tool: Mapping[str, str],
    identical: bool,
    complete: bool,
    limits_hit: tuple[str, ...],
    old: Mapping[str, Any],
    new: Mapping[str, Any],
    options: Mapping[str, Any],
    summary: Mapping[str, Mapping[str, int]],
    value_changes: int,
    reformatted: int,
    renamed: int,
    changes: tuple[Change, ...],
    notes: tuple[Finding, ...],
)

The difference between two DIGGS files, at model level.

identical is True only when nothing differs and the comparison finished (complete). A number written differently and a record's own gml:id are not differences, so two exports of the same data with new ids are identical. limits_hit names what stopped it or what it could not look at (max_changes, time_budget, old_read_incomplete, new_read_incomplete, old_results_not_read, new_results_not_read); it is empty exactly when complete is True. summary counts nodes per collection (added, removed, changed, unchanged) and stays exact when max_changes stops the list, but is partial after a time_budget stop. value_changes counts every differing value, reformatted every value written differently and renamed every node matched by its natural key whose gml:id differs; the last two are counted whether listed or not. changes is ordered by collection, then key, then path; notes are findings of step diff.

to_dict

to_dict() -> dict[str, Any]

The diff as a diggs-diff document (plain dicts and lists).

to_json

to_json(indent: int | None = None) -> str

The diff as diggs-diff JSON: keys sorted, no NaN, the same bytes every time.

to_text

to_text() -> str

A human-readable report, safe to print through rich (file text is escaped).

It lists what the diff holds: reformatted values appear only if the diff was made with show_reformatted=True, and renamed ids only with show_renamed=True. Both are always counted.

from_dict classmethod

from_dict(data: Mapping[str, Any]) -> Diff

Build a diff from a diggs-diff document.

Raises:

Type Description
ValueError

data is not a diggs-diff 1.x document.

Change dataclass

Change(
    *,
    op: str,
    collection: str,
    element: str,
    name: str | None,
    old_key: str | None,
    new_key: str | None,
    matched_by: str | None = None,
    values: tuple[ValueChange, ...] = (),
    truncated: bool = False,
)

One node that was added, removed or changed.

collection is where the node lives (features, samples, measurements, layers, components …). old_key and new_key are its keys in the two files (None on the side that has no such node); matched_by says how a changed node was paired (gml_id, or natural for the natural key). values lists what differs, sorted by path. Two values of op are for a node that did not change and is listed only on request: renamed for one whose gml:id differs (listed with show_renamed=True; its numbers written differently are listed with it when show_reformatted=True too), and reformatted for one that only has numbers written differently (listed with show_reformatted=True). A changed node whose id also differs is changed. truncated is True when a key or name was cut to 200 characters.

ValueChange dataclass

ValueChange(
    *,
    op: str,
    path: str,
    old: Any,
    new: Any,
    at: str | None = None,
    truncated: bool = False,
)

One value that differs between two matched nodes.

path says which value (name, params.totalPenetration, interval.top, results[0].columns[tip_resistance].cells[@1.5]). old and new are what each file holds, as JSON values: text, a number, "1.50 ft" for a quantity, a list for a tuple, None when that side has no such value (op is then added or removed). op is reformatted when the same number is written differently, and renamed for the record's own gml:id (path gml_id, with the old and the new id; None on a side that gives the record no id). Neither is a change. at is the XPath of the node in the new file: a value change belongs to a node both files hold (a node that was added or removed is listed without values). truncated is True when old or new was cut to fit 200 characters (or 200 list items). path and at are at most 1,000 characters: a longer one keeps its start and its end, around a digest of the whole.

diff_schema

diff_schema() -> dict[str, Any]

The packaged diggs-diff JSON Schema, as a fresh dict.

Examples:

>>> from pydiggs import diff
>>> diff.diff_schema()["$id"] == diff.DIFF_SCHEMA_URL
True

DIFF_SCHEMA_VERSION module-attribute

DIFF_SCHEMA_VERSION: Final = '1.0'

DIFF_SCHEMA_URL module-attribute

DIFF_SCHEMA_URL: Final = "https://xinp-hub.github.io/pydiggs/schemas/diggs-diff-1.0.schema.json"

Errors

PydiggsError

Bases: Exception

Base class for every exception pydiggs raises on purpose.

Examples:

>>> issubclass(InstanceReadError, PydiggsError)
True

InstanceReadError

Bases: PydiggsError, OSError

The instance file could not be read (missing, unreadable, too large, compressed).

It is also an :class:OSError, so except OSError keeps working.

Examples:

>>> from pydiggs import validate
>>> try:
...     validate("no-such-file.xml")
... except InstanceReadError as exc:
...     print(type(exc).__name__, isinstance(exc, OSError))
InstanceReadError True

ResourceError

Bases: PydiggsError

A trusted input (a schema, dictionary or Schematron file) is missing or broken.

Raised for files given by path and for pydiggs's own bundled reference data.

Examples:

>>> from pydiggs import validate
>>> try:
...     validate("tests/test_files/2.6/No_Error_2_6.xml", schema_path="missing.xsd")
... except ResourceError as exc:
...     print("schema" in str(exc))
True

Legacy checks

The validator class runs one check at a time and prints or logs its results. New code should prefer validate(); validator stays for existing scripts. See Validation checks for examples.

validator

validator(
    instance_path=None,
    schema_path=None,
    dictionary_path=None,
    schematron_path=None,
    output_log=True,
    diggs_version=None,
)

A Python Class for validating DIGGS instance files.

Initialize the arguments within the validator class.

Parameters:

Name Type Description Default
instance_path string

Relative or full path of the DIGGS instance file.

None
schema_path string

Relative or full path of the DIGGS schema file. Trusted input: schema files are not sandboxed. If omitted, the bundled XSD for diggs_version (or auto-detected NS) is used.

None
dictionary_path string

Relative or full path of the DIGGS dictionary file.

None
schematron_path string

Relative or full path of DIGGS schematron schema file. Trusted input: Schematron compiles to XSLT, which can read local files. If omitted, the bundled DIGGS lxml-adapted rules are used for schematron_check().

None
output_log boolean

Whether to write log files to the CWD. Defaults to True.

True
diggs_version string

Profile 2.5.a, 2.6, or 3.0.0. If omitted, detected from the instance namespace (defaults to 3.0.0 when unknown).

None

schema_check

schema_check() -> bool

Validate the instance against an XSD schema. Returns True on success.

dictionary_check

dictionary_check() -> bool

Run DIGGSml-compatible semantic dictionary validation. Returns True if no ERRORs.

schematron_check

schematron_check() -> bool

Validate against Schematron rules. Returns True on success.

context_check

context_check() -> bool

Run structure / geometry SRS / href / dataBlock semantic checks.