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
|
|
None
|
checks
|
Iterable[str | Step] | None
|
Step names to run, from |
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 |
DEFAULT_MAX_FINDINGS
|
max_bytes
|
int
|
Largest instance accepted, in bytes (default
:data: |
DEFAULT_MAX_BYTES
|
local_dictionaries
|
LocalDictionaries
|
|
'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
|
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 |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
A |
Report
|
class: |
Raises:
| Type | Description |
|---|---|
InstanceReadError
|
The instance cannot be read (also an |
ResourceError
|
A schema, dictionary or Schematron file, or bundled data, is missing or broken. |
ValueError
|
|
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: |
required |
name
|
str | None
|
The file name to report ( |
None
|
diggs_version
|
str | None
|
As for :func: |
None
|
checks
|
Iterable[str | Step] | None
|
As for :func: |
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: |
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: |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
A |
Report
|
class: |
Raises:
| Type | Description |
|---|---|
InstanceReadError
|
|
ResourceError
|
pydiggs's bundled data is missing or broken. |
ValueError
|
|
TypeError
|
|
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
¶
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 |
None
|
Raises:
| Type | Description |
|---|---|
ValueError
|
|
ResourceError
|
pydiggs's bundled data is missing or broken. |
Examples:
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 |
required |
diggs_version
|
str | None
|
Read as this DIGGS version instead of the detected one (the
experimental |
None
|
results
|
bool
|
False keeps every result table's columns and |
True
|
provenance
|
Literal['object', 'field']
|
|
'object'
|
max_bytes
|
int
|
Largest file accepted (default 100 MiB, as for |
DEFAULT_MAX_BYTES
|
time_budget
|
float | None
|
Seconds to spend; when they run out the members read so far are
returned with |
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 ( |
ValueError
|
An argument is out of range. |
Examples:
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
|
|
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
¶
Every node, each once.
The document, each collection in order, lithology layers, then every nested
:class:Component (depth first, in document order).
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_json
¶
The model as diggs-model JSON; the same model always gives the same text.
write_json
¶
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
|
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
¶
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
¶
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
¶
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
¶
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: |
required |
view
|
str
|
|
'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 |
False
|
Raises:
| Type | Description |
|---|---|
ImportError
|
pandas is not installed. |
ValueError
|
|
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
|
|
transform
¶
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: |
required |
to
|
str
|
A geographic CRS pyproj understands, such as |
'EPSG:4326'
|
Returns:
| Type | Description |
|---|---|
Model
|
A new model; |
Raises:
| Type | Description |
|---|---|
ImportError
|
pyproj is not installed ( |
ValueError
|
|
Examples:
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: |
required |
to
|
str
|
The geographic CRS of the points (see :func: |
'EPSG:4326'
|
kind
|
str | None
|
Only features of this kind, such as |
None
|
Raises:
| Type | Description |
|---|---|
ImportError
|
the |
ValueError
|
|
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: |
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: |
'EPSG:4326'
|
kind
|
str | None
|
Only features of this kind. |
None
|
Returns:
| Type | Description |
|---|---|
Path
|
|
Raises:
| Type | Description |
|---|---|
ImportError
|
the |
ValueError
|
the format is not one of the three, or |
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}
verdict
property
¶
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 |
False
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A JSON-serialisable dict that validates against :func: |
Examples:
to_json
¶
A complete diggs-findings 1.2 JSON document for this one file.
The text form of :meth:to_document.
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
¶
(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
¶
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
¶
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
Findings documents¶
findings_document
¶
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: |
required |
absolute_paths
|
bool
|
Write each |
False
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A JSON-serialisable dict that validates against :func: |
dict[str, Any]
|
report made by this pydiggs it equals |
Examples:
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: |
required |
indent
|
int | None
|
Spaces per level (default 2, as the CLI writes); None for one line. |
2
|
absolute_paths
|
bool
|
As for :func: |
False
|
Returns:
| Type | Description |
|---|---|
str
|
The JSON text, without a trailing newline. |
Examples:
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:
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
|
|
required |
Returns:
| Name | Type | Description |
|---|---|---|
The |
RuleInfo
|
class: |
Raises:
| Type | Description |
|---|---|
ValueError
|
|
TypeError
|
|
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:
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'
Guidance
dataclass
¶
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 ( |
Examples:
version_info
¶
version_info() -> VersionInfo
Describe the running pydiggs: its version, findings schema and bundled data.
Returns:
| Name | Type | Description |
|---|---|---|
A |
VersionInfo
|
class: |
Raises:
| Type | Description |
|---|---|
ResourceError
|
The bundled |
Examples:
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']
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
|
1.0 document (see :func: |
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, ...],
)
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:
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'
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:
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: |
required |
diggs_version
|
str
|
The DIGGS version to write; only |
'3.0.0'
|
validate
|
bool
|
Validate the output with :func: |
True
|
name
|
str | None
|
A file name to report for bytes, a stream or a |
None
|
encoding
|
str | None
|
As for :func: |
None
|
max_bytes
|
int
|
As for :func: |
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, |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
The |
Conversion
|
class: |
Raises:
| Type | Description |
|---|---|
InstanceReadError
|
As :func: |
DocumentError
|
As :func: |
ValueError
|
|
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: |
_DEFAULT_AGS_VERSION
|
check
|
bool
|
As for :func: |
True
|
formula_guard
|
Literal['prefix'] | None
|
As for :func: |
None
|
name
|
str | None
|
A file name to report for bytes or a stream. |
None
|
max_bytes
|
int
|
As for :func: |
DEFAULT_MAX_BYTES
|
time_budget
|
float | None
|
Seconds for reading, as for :func: |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
The |
Conversion
|
class: |
Raises:
| Type | Description |
|---|---|
InstanceReadError
|
As :func: |
DocumentError
|
As :func: |
ValueError
|
|
ResourceError
|
A bundled mapping table is broken. |
Examples:
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: |
required |
ags_version
|
str
|
The AGS4 version to write: |
_DEFAULT_AGS_VERSION
|
check
|
bool
|
Check the output with :func: |
True
|
formula_guard
|
Literal['prefix'] | None
|
None (the default) or |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
The |
Conversion
|
class: |
Raises:
| Type | Description |
|---|---|
ValueError
|
|
TypeError
|
|
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.
save
¶
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 |
OSError
|
The path cannot be written. |
Origin
dataclass
¶
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: |
dict[str, Any]
|
|
dict[str, Any]
|
|
dict[str, Any]
|
|
dict[str, Any]
|
DIGGS to AGS4 writes it for; None for every one) and |
dict[str, Any]
|
|
dict[str, Any]
|
|
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
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: |
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'
|
rel_tol
|
float
|
Two numbers are equal when |
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
|
10000
|
time_budget
|
float | None
|
Seconds for the whole call, reading both files included. When it runs
out the result is |
None
|
max_bytes
|
int
|
Largest file read (default 100 MiB, as for :func: |
DEFAULT_MAX_BYTES
|
show_reformatted
|
bool
|
List the values written differently but equal ( |
False
|
show_renamed
|
bool
|
List the nodes matched by natural key whose own |
False
|
Returns:
| Name | Type | Description |
|---|---|---|
A |
Diff
|
class: |
Diff
|
Each side's |
|
Diff
|
class: |
|
Diff
|
digest the diggs-model schema requires, or :meth: |
|
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
|
|
ValueError
|
An option is out of range. |
Examples:
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_json
¶
The diff as diggs-diff JSON: keys sorted, no NaN, the same bytes every time.
to_text
¶
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.
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_URL
module-attribute
¶
Errors¶
PydiggsError
¶
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:
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:
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 |
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 |
None
|
schema_check
¶
Validate the instance against an XSD schema. Returns True on success.
dictionary_check
¶
Run DIGGSml-compatible semantic dictionary validation. Returns True if no ERRORs.
schematron_check
¶
Validate against Schematron rules. Returns True on success.
context_check
¶
Run structure / geometry SRS / href / dataBlock semantic checks.