Skip to content

Project facts

Generated from pyproject.toml and checked in CI, so this page cannot disagree with what is installed.

Fact Value
Distribution pydiggs
Requires Python >=3.11
Runtime dependencies lxml>=6.1.3, rich>=13.9.4

Optional extras

Extra Install Adds
frames pip install "pydiggs[frames]" pandas>=2.2.3
gis pip install "pydiggs[gis]" geopandas>=1.1.2, pandas>=2.2.3, pyarrow>=23.0.1, pyogrio>=0.10.0, pyproj>=3.7.0, shapely>=2.0.6
mcp pip install "pydiggs[mcp]" mcp>=2.3.0, python-multipart>=0.0.31
polars pip install "pydiggs[polars]" polars>=1.20.0
server pip install "pydiggs[server]" fastapi>=0.146.0, starlette>=1.6.0, pydantic>=2.12.0, python-multipart>=0.0.31, uvicorn>=0.54.0

Command-line scripts

pydiggs

usage: pydiggs [-h] [--schema_path SCHEMA_PATH]
               [--dictionary_path DICTIONARY_PATH]
               [--schematron_path SCHEMATRON_PATH]
               [--output_log | --no-output_log]
               {schema_check,schematron_check,dictionary_check,context_check}
               diggs_file

A Python package for Data Interchange for Geotechnical and Geoenvironmental
Specialists (DIGGS).

positional arguments:
  {schema_check,schematron_check,dictionary_check,context_check}
                        Available commands for execution
  diggs_file            Relative or full path of the DIGGS instance file

options:
  -h, --help            show this help message and exit
  --schema_path SCHEMA_PATH
                        Relative or full path of the DIGGS schema file
                        (default: auto-detect 2.5.a / 2.6 / 3.0.0 from
                        instance NS)
  --dictionary_path DICTIONARY_PATH
                        Primary DIGGS dictionary file (default: bundled
                        properties.xml)
  --schematron_path SCHEMATRON_PATH
                        Schematron schema file (default: bundled DIGGS lxml-
                        adapted rules)
  --output_log, --no-output_log
                        Write validation logs to the current working directory
                        (default: True)

Machine-readable findings (JSON, SARIF) for one or many files: pydiggs
validate --help. Validation for other programs (stdio sidecar, HTTP, MCP):
pydiggs serve --help. AGS4 files against the AGS4 rules: pydiggs ags4 check
--help. AGS4 to DIGGS and DIGGS to AGS4: pydiggs convert --help. What changed
between two DIGGS files: pydiggs diff --help. Installed version: pydiggs
--version.

pydiggs ags4

usage: pydiggs ags4 [-h] COMMAND ...

Work with AGS4 files. See: pydiggs ags4 check --help.

positional arguments:
  COMMAND
    check     check AGS4 files against the AGS4 rules (Rules 1 to 20)

options:
  -h, --help  show this help message and exit

pydiggs ags4 check

usage: pydiggs ags4 check [-h] [--dictionary FILE]
                          [--format {text,json,sarif}] [--output FILE]
                          [--fail-on {error,warning}] [--max-findings N]
                          [--max-bytes N] [--time-budget SECONDS]
                          [--absolute-paths]
                          FILE [FILE ...]

Check AGS4 files against the AGS4 rules (Rules 1 to 20 of the AGS4
specification, Edition 4.2) and report the findings as text, JSON (diggs-
findings 1.2) or SARIF 2.1.0. pyDIGGS bundles no AGS data dictionary: the
rules that need one (7, 9, 10a, 10b, 10c, 18, and parts of 11c, 13, 14 and
19b) run for the file's own DICT group, and for standard groups only with
--dictionary. Not an AGS-approved validator.

positional arguments:
  FILE                  AGS4 files to check

options:
  -h, --help            show this help message and exit
  --dictionary FILE     an AGS4 data dictionary (such as the AGS standard
                        dictionary of the version)
  --format {text,json,sarif}
  --output FILE         write the report here, not stdout
  --fail-on {error,warning}
  --max-findings N      keep at most N findings per file (default 10000; 0: no
                        limit)
  --max-bytes N         refuse files larger than N bytes (default 100 MiB)
  --time-budget SECONDS
                        stop checking a file after SECONDS; what was found so
                        far is reported
  --absolute-paths      report absolute paths in JSON and SARIF (default:
                        relative to here)

Exit status: 0 no finding at or above --fail-on; 1 some; 2 usage error, an
unreadable input, or an unusable dictionary.

pydiggs capabilities

usage: pydiggs capabilities [-h] [--json]

List what this pydiggs can do: each operation, how stable it is, what it reads
and gives, and whether the extras it needs are installed.

options:
  -h, --help  show this help message and exit
  --json      print a diggs-capabilities 1.0 document
              (pydiggs.capabilities().to_dict())

pydiggs convert

usage: pydiggs convert [-h] -o OUT [--to {diggs,ags4}]
                       [--diggs-version {3.0.0}] [--ags-version {4.2,4.1.1}]
                       [--residual FILE] [--report FILE]
                       [--format {text,json}] [--fail-on {error,loss}]
                       [--force] [--max-bytes N] [--time-budget SECONDS]
                       IN

Convert an AGS4 file to a DIGGS 3.0.0 document, or (--to ags4) a DIGGS
document to an AGS4 file, by the mapping table described at https://xinp-
hub.github.io/pydiggs/convert-mapping/. Every source value that does not reach
the output is reported as a loss; the output is validated (DIGGS) or checked
against the AGS4 rules (AGS4). pyDIGGS bundles no AGS data dictionary and is
not an AGS-approved tool.

positional arguments:
  IN                    the file to convert: AGS4, or DIGGS XML with --to ags4

options:
  -h, --help            show this help message and exit
  -o OUT, --output OUT  where to write the output (DIGGS XML, or the AGS4 file
                        with --to ags4)
  --to {diggs,ags4}     the format to convert to: diggs (the default; IN is
                        AGS4) or ags4 (IN is DIGGS)
  --diggs-version {3.0.0}
                        the DIGGS version to write (--to diggs; default:
                        3.0.0)
  --ags-version {4.2,4.1.1}
                        the AGS4 version to write (--to ags4; default: 4.2).
                        The BGS AGS validator and python-ags4 1.2.0 accept
                        AGS4 only up to 4.1.1 (November 2026)
  --residual FILE       also write the AGS4 file of what was not converted
                        here (--to diggs only; not written when everything was
                        converted)
  --report FILE         also write the findings report (diggs-findings 1.2
                        JSON) here
  --format {text,json}  the summary on stdout: text, or JSON (the result
                        without the output bytes)
  --fail-on {error,loss}
  --force               replace OUT (and --report) if they exist
  --max-bytes N         refuse inputs larger than N bytes (default 100 MiB)
  --time-budget SECONDS
                        stop converting after SECONDS; the output is then
                        partial and says so

Exit status: 0 no finding at or above --fail-on; 1 some; 2 usage error, an
input that cannot be read or is not of the expected format, or an output that
cannot be written.

pydiggs diff

usage: pydiggs diff [-h] [--format {text,json}] [-o FILE]
                    [--match {auto,gml-id,natural}] [--rel-tol R]
                    [--abs-tol A] [--max-changes N] [--time-budget SECONDS]
                    [--max-bytes N] [--verbose]
                    OLD NEW

Compare two DIGGS files by what they describe, not by how they are written:
element order, number formatting, line numbers and the gml:id of a record do
not count. Boreholes, samples, tests and the other records are matched by
gml:id, then by a natural key (a borehole's kind and name, a sample's
borehole, name and top), so records stay paired when their gml:ids change: two
exports of the same data with new ids are identical. The renamed ids are
counted, and listed with --verbose. Numbers compare within a tolerance; a
change of unit is always a change, and nothing is converted. The two files may
be different DIGGS versions.

positional arguments:
  OLD                   the earlier DIGGS file
  NEW                   the later DIGGS file

options:
  -h, --help            show this help message and exit
  --format {text,json}  the report: text (the default), or JSON (a diggs-diff
                        document)
  -o FILE, --output FILE
                        write the report here, not to stdout
  --match {auto,gml-id,natural}
                        how records are paired: auto (the default; by gml:id,
                        then by natural key), gml-id (ids only, also written
                        gml_id; a record whose gml:id changed is removed and
                        added) or natural (natural keys only)
  --rel-tol R           two numbers are equal when they differ by at most R
                        times the larger one; 0 or more and less than 1
                        (default 1e-09)
  --abs-tol A           or by at most A, in the value's own unit (default 0)
  --max-changes N       list at most N changes (default 10000); the counts
                        stay exact, and a cut list is an incomplete comparison
  --time-budget SECONDS
                        stop after SECONDS, reading included; the comparison
                        is then incomplete
  --max-bytes N         refuse files larger than N bytes (default 100 MiB)
  --verbose             also list what is not a change: values that are only
                        written differently (1.50 and 1.5, other separators
                        that read the same values, double and float) and
                        records whose gml:id changed; both are always counted

Exit status: 0 the files are identical and the comparison finished; 1 they
differ, or the comparison is incomplete; 2 usage error, an input that cannot
be read or is not DIGGS, or an output that cannot be written.

pydiggs serve

usage: pydiggs serve [-h] (--stdio | --http | --mcp) [--max-bytes N]
                     [--max-findings N] [--timeout SECONDS] [--workers N]
                     [--host H] [--port P] [--allow-path DIR]
                     [--log-level {debug,info,warning,error,critical}]
                     [--log-format {text,json}]

Serve DIGGS validation to other programs: a JSON-RPC sidecar on stdin/stdout
(--stdio), an HTTP API (--http, needs pydiggs[server]) or an MCP server on
stdin/stdout (--mcp, needs pydiggs[mcp]). Only the bundled schema,
dictionaries and Schematron rules are used.

options:
  -h, --help            show this help message and exit
  --stdio               JSON-RPC 2.0 over NDJSON on stdio
  --http                HTTP API (pydiggs[server])
  --mcp                 MCP server on stdio (pydiggs[mcp])
  --max-bytes N         largest document in bytes (default 26,214,400; --stdio
                        by path 104,857,600; --mcp 10,485,760)
  --max-findings N      findings kept per document (default 10,000; --mcp 200)
  --timeout SECONDS     per-request limit in seconds (default 60)
  --workers N           --http worker processes (default: CPUs-1, 1-4)
  --host H              --http bind address (default 127.0.0.1)
  --port P              --http port (default 8000)
  --allow-path DIR      --stdio: also accept files by absolute path under DIR
                        (repeatable)
  --log-level {debug,info,warning,error,critical}
  --log-format {text,json}

Exit status: 0 after a clean shutdown; 2 for bad arguments or a missing extra.
--timeout is a hard limit (process kill) for --http and --mcp, and the default
per-request time budget for --stdio, where the host owns hard limits.

pydiggs validate

usage: pydiggs validate [-h] [--format {text,json,sarif}] [--output FILE]
                        [--checks STEP[,STEP...]]
                        [--diggs-version {2.5.a,2.6,3.0.0,3.1-dev}]
                        [--schema-path P] [--dictionary-path P]
                        [--schematron-path P] [--fail-on {error,warning}]
                        [--max-findings N] [--snippets] [--absolute-paths]
                        [--max-bytes N] [--timeout SECONDS]
                        [--local-dictionaries {instance-dir,off}]
                        [--base-dir DIR] [--allow-network]
                        PATH [PATH ...]

Validate DIGGS instance files with every native check and report the findings
as text, JSON (diggs-findings 1.2) or SARIF 2.1.0.

positional arguments:
  PATH                  instance files, or directories searched recursively
                        for *.xml

options:
  -h, --help            show this help message and exit
  --format {text,json,sarif}
  --output FILE         write the report here, not stdout
  --checks STEP[,STEP...]
                        steps to run (default: all of structure,schema,diction
                        ary,schematron,geometry,deprecation,context)
  --diggs-version {2.5.a,2.6,3.0.0,3.1-dev}
  --schema-path P       XSD instead of the bundled one
  --dictionary-path P   primary property dictionary
  --schematron-path P   Schematron rules file
  --fail-on {error,warning}
  --max-findings N      keep at most N findings per file (default 10000; 0: no
                        limit)
  --snippets            include each finding's element XML (off by default: it
                        carries file data)
  --absolute-paths      report absolute paths (default: relative to here, else
                        the bare file name)
  --max-bytes N         refuse instances larger than N bytes (default 100 MiB)
  --timeout SECONDS     validate each file in its own process and stop it
                        after SECONDS (an error)
  --local-dictionaries {instance-dir,off}
                        read local dictionaries only from each instance's
                        folder (default), or never
  --base-dir DIR        report paths relative to DIR (default: here, unless
                        here is / or above home)
  --allow-network       fetch whitelisted remote code lists that are not
                        bundled

Exit status: 0 no finding at or above --fail-on; 1 some; 2 usage error, no
input files, or an unreadable input.