Skip to content

Capabilities

pydiggs.capabilities() says what the installed pyDIGGS can do: every operation, how stable it is, what it reads and gives, its options, the extras it needs, and whether they are installed. An app that bundles pyDIGGS builds its menus from this answer, so a new pyDIGGS release reaches the app without hand edits.

import pydiggs

caps = pydiggs.capabilities()
for op in caps.operations:
    print(op.id, op.stability, op.available)
caps.to_dict()  # a diggs-capabilities 1.0 document
$ pydiggs capabilities
pydiggs 1.8.0
  validate             stable        Check a DIGGS file against the schema, dictionaries and business rules
  read                 stable        Read what a DIGGS file holds: boreholes, samples, tests and results
  ...
  export.gpkg          stable        Save features as a GeoPackage (.gpkg)  (needs pydiggs[gis])
$ pydiggs capabilities --json

The document

{
  "$schema": "https://xinp-hub.github.io/pydiggs/schemas/diggs-capabilities-1.0.schema.json",
  "schema_version": "1.0",
  "pydiggs_version": "1.8.0",
  "operations": [
    {
      "id": "read",
      "label": "Read what a DIGGS file holds: boreholes, samples, tests and results",
      "stability": "stable",
      "inputs": ["diggs-2.5.a", "diggs-2.6", "diggs-3.0.0", "diggs-3.1-dev"],
      "outputs": ["diggs-model-1.0"],
      "options": {
        "results": {
          "type": "boolean",
          "label": "Keep the values of result tables (off: only their columns and size)",
          "default": true,
          "choices": null,
          "required": false
        }
      },
      "needs": [],
      "available": true
    }
  ]
}
field meaning
id a stable identifier: validate, read, ags4.check, export.gpkg …
label what the operation does, in plain language
stability stable (Semantic Versioning), preview (may change in a minor release) or experimental (may change or go at any time)
inputs, outputs a DIGGS version (diggs-2.6), an AGS4 version (ags4-4.1.1), a pyDIGGS document (diggs-findings-1.2, diggs-model-1.0), a media type (application/geo+json), or the Python type of an in-memory result (pandas.DataFrame)
options option name (the keyword argument, and the request parameter where a surface takes it) to its type (boolean, integer, number, string, string[] or file), label, default (null: not given), choices (null: any) and required
needs the pyDIGGS extras it needs (pip install 'pydiggs[gis]'); empty for the core
available whether everything it needs is installed in the interpreter that answered

available is worked out when you ask, by looking for each module an operation needs without importing it. The same wheel answers correctly under CPython with extras and in the browser (Pyodide), where only the core is installed and the data-frame and GIS exports report available: false. Over HTTP and MCP the answer is about the server's own interpreter.

Operations

The table is generated from pydiggs.capabilities() and checked in CI, so it lists exactly the operations the installed release offers. needs is the extra to install (for example pydiggs[gis]).

id stability needs what it does
validate stable Check a DIGGS file against the schema, dictionaries and business rules
read stable Read what a DIGGS file holds: boreholes, samples, tests and results
detect stable Tell which DIGGS version a file is written in
rules.list stable List every rule pyDIGGS can report
rules.explain stable Explain one rule a finding names
ags4.read preview Read an AGS4 file as tables
ags4.write preview Write tables as an AGS4 file
ags4.check preview Check an AGS4 file against the AGS4 rules
convert.ags4-to-diggs stable Convert an AGS4 file to DIGGS 3.0.0, listing everything not carried over and keeping it in a residual AGS4 file
convert.diggs-to-ags4 stable Convert a DIGGS file (or a read one) to an AGS4 file, listing everything not carried over
diff stable Compare two DIGGS files: what was added, removed or changed
export.pandas stable frames Tables of a read file as a pandas data frame
export.polars stable polars Tables of a read file as a polars data frame
gis.transform stable gis Add longitude and latitude to every location that has a known CRS
export.geodataframe stable gis Boreholes and other features as map points (a GeoDataFrame)
export.gpkg stable gis Save features as a GeoPackage (.gpkg)
export.geoparquet stable gis Save features as GeoParquet (.parquet)
export.geojson stable gis Save features as GeoJSON (.geojson)

Where each is in Python:

id Python
validate pydiggs.validate(), validate_bytes()
read pydiggs.read(), read_bytes()
detect pydiggs.detect_diggs_version()
rules.list pydiggs.rule_catalogue()
rules.explain pydiggs.explain_rule()
ags4.read pydiggs.ags4.read(), read_bytes()
ags4.write pydiggs.ags4.dumps(), write()
ags4.check pydiggs.ags4.check()
convert.ags4-to-diggs pydiggs.convert.ags4_to_diggs()
convert.diggs-to-ags4 pydiggs.convert.diggs_to_ags4(), model_to_ags4()
diff pydiggs.diff.compare()
export.pandas pydiggs.frames.to_pandas()
export.polars pydiggs.frames.to_polars()
gis.transform pydiggs.gis.transform()
export.geodataframe pydiggs.gis.to_geodataframe()
export.gpkg, export.geoparquet, export.geojson pydiggs.gis.write()

The AGS4 reading, writing and checking operations are a preview; conversion (pydiggs.convert) is stable from pyDIGGS 1.11, both ways. POST /v1/convert and the sidecar's convert are either conversion operation, chosen by their to parameter. diff (Comparing two files, from pyDIGGS 1.12, stable from 1.13) is offered in Python, as pydiggs diff, and from 1.13 as POST /v1/diff and the sidecar's diff (protocol 1.3); the MCP server does not offer it yet. The experimental DIGGS 3.1-dev profile is a choice of the diggs_version option (see Validation checks).

Versioning

diggs-capabilities follows the rules of the other pyDIGGS documents. Objects accept unknown fields, so a 1.0 consumer accepts any 1.x document. A new optional field, a new operation, or a new token in inputs, outputs or needs is a minor version; a new stability or option type, or any other change, is a new major. An operation's id does not change while it is listed; a stable one is removed only in a major release of pyDIGGS.