Video tutorials¶
Short narrated videos of pyDIGGS at work, one per feature. Every video has English captions, chapters and a full transcript, and plays from this site: no third-party player and no cookies.
The videos are made from scripts in
docs/tutorials/ each
time the documentation is published. The commands you see really ran against the
documented version, and a video whose output no longer matches its script stops the
build, so the videos cannot fall behind the software. The example files are written for
the purpose; none holds project data.
Follow along. Under each video, Try it yourself offers the files the video starts from, exactly as it used them (one by one, or as a zip with its SHA-256), and the commands it runs, ready to copy. Every build checks that those files alone are enough: the commands are run from the unpacked zip and must print what the video shows.
Command line¶
Transcript
Validate a file. This terminal holds a DIGGS 3.0 file called site dot X M L. We type pydiggs validate and the file name. pyDIGGS runs every check: structure, schema, dictionary, Schematron rules, geometry and context. The last line reads valid, with no errors and no warnings.
Read the findings. Now we validate broken dot X M L, where a borehole depth was typed as a word. The verdict is not valid, with two errors. Each finding gives the line number, the rule that failed, and what is wrong: the schema expects a number, and the Schematron rule says the depth must be positive.
Write a report for CI. For continuous integration, ask for SARIF and write it to a file. The command exits with a non-zero status when the file is not valid, so a pipeline stops. Listing the report shows results dot sarriff on its own line, ready for GitHub code scanning or any SARIF viewer.
Try it yourself
The files this video starts from, exactly as it used them: validate-files.zip (6.5 KB, SHA-256 189983aa689bcec5a325ea20b033fae7e33ebf164bdae510da126286340503a5), or one by one: site.xml, broken.xml. They are synthetic examples, Apache-2.0.
Set up a folder with uv and the version the video shows, put the files in it, and run each command there (on Windows, activate with .venv\Scripts\activate):
Transcript
AGS4 to DIGGS. We start from an AGS4 file, site dot A G S. pydiggs convert, with dash o for the output, writes a DIGGS 3.0 document. The first line sums it up: the mapping table version, the number of losses, and that the output is valid.
Every loss is reported. Nothing is dropped in silence. Here we count the losses by kind. Unmapped headings have no DIGGS target, unmapped codes and units could not be carried, and assumed means the converter had to fill something in. Each loss in the full report names the line of the source file it came from.
DIGGS back to AGS4. To go the other way, add dash dash to A G S 4. The DIGGS file becomes an AGS4 file, which is checked against the AGS4 rules as it is written. Here one value needed an assumption, and it is reported the same way.
Try it yourself
The files this video starts from, exactly as it used them: convert-files.zip (2.2 KB, SHA-256 7ba94ac82c59eac188f719c0afdb1a21932f1147e31774121453863adb50ebfb), or one by one: site.ags. They are synthetic examples, Apache-2.0.
Set up a folder with uv and the version the video shows, put the files in it, and run each command there (on Windows, activate with .venv\Scripts\activate):
Transcript
Compare two revisions. We have two revisions of the same site file. pydiggs diff takes the older file first, then the newer one. It compares what the files describe, not how they are written, so element order and number formatting do not count.
Read the change. The report counts records by kind: added, removed, changed and unchanged. One feature changed. At the bottom, borehole B H 0 2 is matched by its identifier, and its total depth went from ten metres to twelve and a half metres.
Try it yourself
The files this video starts from, exactly as it used them: diff-files.zip (6.5 KB, SHA-256 eeac8cb7a8e55beaf269df1eef4bab33caf60fed32baa64f80dbaa4f3c5283e3), or one by one: site.xml, site-rev2.xml. They are synthetic examples, Apache-2.0.
Set up a folder with uv and the version the video shows, put the files in it, and run each command there (on Windows, activate with .venv\Scripts\activate):
Transcript
Check a received file. pyDIGGS also checks AGS4 files. We run pydiggs A G S 4 check on a file we received. The verdict is not valid, with one error. The finding names rule 13 and the group, PROJ: the project group may hold only one data row, and this file has two.
A clean file. Checking a clean file prints valid with no errors. The information line says that no AGS data dictionary was given, so the dictionary rules were checked against the groups the file defines itself. Pass dash dash dictionary to check the standard groups too.
Try it yourself
The files this video starts from, exactly as it used them: ags4-check-files.zip (2.2 KB, SHA-256 533d2dad3faa19422a65e8ea042970f22d09b6f36c045d0048103ec74034f557), or one by one: received.ags, site.ags. They are synthetic examples, Apache-2.0.
Set up a folder with uv and the version the video shows, put the files in it, and run each command there (on Windows, activate with .venv\Scripts\activate):
Python¶
Transcript
The script. Here is a short Python script. It imports pydiggs, validates site dot X M L, and prints the verdict and the counts. Then it reads the same file into a model and prints the kind, name and total depth of each sampling feature.
Run it. Running the script prints valid, with zero errors and zero warnings. Below that are the three sampling features in the file: two boreholes and a trial pit, each with its depth exactly as the file writes it, and its unit.
Try it yourself
The files this video starts from, exactly as it used them: python-api-files.zip (3.7 KB, SHA-256 182aeba596fa2f2d1bed5c2c32af45c953bf6b1d4a177aec80db6eb9f3298758), or one by one: site.xml, check_site.py. They are synthetic examples, Apache-2.0.
Set up a folder with uv and the version the video shows, put the files in it, and run each command there (on Windows, activate with .venv\Scripts\activate):
Browser¶
Transcript
Load the page. This is the browser example that ships with pyDIGGS. The page loads Pyodide, Python compiled to WebAssembly, and installs pyDIGGS inside the tab. When the status line says Ready, with the versions it loaded, the file picker is enabled.
Validate a file. We pick site dot X M L. The file is read in the page and validated in a background worker, so it is never uploaded anywhere. The report shows the verdict, valid, for DIGGS 3.0.0, with no errors and no warnings.
Read the findings. Now we pick broken dot X M L, where a borehole depth was typed as a word. The verdict changes to not valid, with two errors, and each finding below it gives the rule and the line, just as on the command line.
Try it yourself
The files this video starts from, exactly as it used them: browser-files.zip (6.4 KB, SHA-256 b6dd3805dd411a358e03412e08f981946eacbb92c92417fd2bd0f02530d1c805), or one by one: site.xml, broken.xml. They are synthetic examples, Apache-2.0.
Run the browser example as described below, then pick these files.