mdto.py

mdto.py is een Python library die helpt bij het aanmaken, aanpassen, en controleren van MDTO XML bestanden. Denk bijvoorbeeld aan het automatisch genereren van technische metagegevens, of wat in MDTO het objectsoort Bestand wordt genoemd:

<?xml version="1.0" encoding="UTF-8"?>
<MDTO xmlns="https://www.nationaalarchief.nl/mdto" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://www.nationaalarchief.nl/mdto https://www.nationaalarchief.nl/mdto/MDTO-XML1.0.1.xsd">
    <bestand>
        <identificatie>
            <identificatieKenmerk>Bestand-345c-4379</identificatieKenmerk>
            <identificatieBron>Corsa</identificatieBron>
        </identificatie>
        <naam>bouwtekening-003.jpg</naam>
        <omvang>1089910</omvang>
        <bestandsformaat>
            <begripLabel>JPEG File Interchange Format</begripLabel>
            <begripCode>fmt/43</begripCode>
            <begripBegrippenlijst>
                <verwijzingNaam>PRONOM-register</verwijzingNaam>
            </begripBegrippenlijst>
        </bestandsformaat>
        <checksum>
            <checksumAlgoritme>
                <begripLabel>SHA-256</begripLabel>
                <begripBegrippenlijst>
                    <verwijzingNaam>Begrippenlijst ChecksumAlgoritme MDTO</verwijzingNaam>
                </begripBegrippenlijst>
            </checksumAlgoritme>
            <checksumWaarde>857ee09fb53f647b16b1f96aba542ace454cd6fc52c9844d4ddb8218c5d61b6c</checksumWaarde>
            <checksumDatum>2024-02-15T16:15:33</checksumDatum>
        </checksum>
        <URLBestand>https://www.example.com/bouwtekening-003.jpg</URLBestand>
        <isRepresentatieVan>
            <verwijzingNaam>Bouwtekening Flipje's erf 27</verwijzingNaam>
            <verwijzingIdentificatie>
                <identificatieKenmerk>Informatieobject-4661a-5a3526</identificatieKenmerk>
                <identificatieBron>Corsa</identificatieBron>
            </verwijzingIdentificatie>
        </isRepresentatieVan>
    </bestand>
</MDTO>

Naast gebruiksvriendelijkheid, streeft mdto.py ook een 100% correcte implementatie van het MDTO XML-schema te zijn. Deze correctheid wordt geverifieerd door de output van mdto.py met de XSD en de MDTO voorbeeldbestanden te vergelijken (zie unit tests).

💿 Installatie

Afhankelijkheden

• Python 3.11 of nieuwer.
• De PRONOM detectie functionaliteit werkt alleen als het programma fido in je PATH staat. Als je de instructies hieronder volgt gebeurd dit automatisch.

Tip

mdto.py kan ook PRONOM-informatie genereren via sf (siegfried). sf is sneller en meer up-to-date dan fido, maar op dit moment lastiger te installeren. Als sf geïnstalleerd is, gebruikt mdto.py dit programma automatisch voor PRONOM-informatie.

Als beide programma's aanwezig zijn, kun je je voorkeur aangeven door de environment variable PRONOM_BACKEND aan te passen naar sf/fido.

Systeem-brede installatie

git clone https://github.com/Regionaal-Archief-Rivierenland/mdto.py
cd mdto.py
sudo pip install . # Windows gebruikers kunnen "sudo" hier weglaten

Installatie in een virtual environment

Windows

git clone https://github.com/Regionaal-Archief-Rivierenland/mdto.py
cd mdto.py
python -m venv mdto_env
mdto_env\Scripts\activate
pip install .

Linux/WSL/*nix

git clone https://github.com/Regionaal-Archief-Rivierenland/mdto.py
cd mdto.py/
python -m venv mdto_env
source mdto_env/bin/activate
pip install .

📖 mdto.py als Python library

XML bestanden bouwen

De primaire doelstellingen van mdto.py is het versimpelen van het bouwen van MDTO XMLs via Python. Om enkele voorbeelden te geven:

from mdto.gegevensgroepen import *  # importeer VerwijzingGegevens, BegripGegevens, BegripGegevens, etc.

# maak identificatiekenmerk element
informatieobject_id = IdentificatieGegevens("Informatieobject-4661a", "Proza (OCW-DMS)")

# maak waardering element
waardering = BegripGegevens(begripLabel="Tijdelijk te bewaren",
                            begripCode="V",
                            begripBegrippenlijst=VerwijzingGegevens("Begrippenlijst Waarderingen MDTO"))

# maak beperkingGebruik element
# beperkingGebruikType verwacht een begrip label (bijv. 'Auteurswet'), en een verwijzing naar een begrippenlijst
beperkingType = BegripGegevens("Auteurswet", VerwijzingGegevens("Gemeente Den Haag zaaksysteem begrippenlijst"))
beperkingGebruik = BeperkingGebruikGegevens(beperkingGebruikType=beperkingType)

# maak informatieobject op basis van deze gegevens
informatieobject = Informatieobject(identificatie = informatieobject_id,
                 naam = "Verlenen kapvergunning Hooigracht 21 Den Haag",
                 waardering = waardering,
                 archiefvormer = VerwijzingGegevens("'s-Gravenhage"),
                 beperkingGebruik = beperkingGebruik)

# schrijf informatieobject naar een XML bestand
informatieobject.save("informatieobject-4661a.mdto.xml")

mdto.py zorgt dat al deze informatie in de juiste volgorde in de XML terechtkomt — resulterende bestanden zijn altijd 100% valide MDTO.

In tegenstelling tot Python's ingebouwde XML library xml.etree kun je het bovenstaand informatieobject gemakkelijk inspecteren en veranderen, bijvoorbeeld via print():

>>> print(informatieobject)
Informatieobject(naam='Verlenen kapvergunning Hooigracht 21 Den Haag',  identificatie=IdentificatieGegevens(identificatieKenmerk='Informatieobject-4661a, identificatieBron='Proza (OCW-DMS)', ...)
>>> informatieobject.naam = informatieobject.naam.upper() # waardes zijn gemakkelijk aan te passen
>>> print(informatieobject.naam)
'VERLENEN KAPVERGUNNING HOOIGRACHT 21 DEN HAAG'

Tip

Je kan op een vergelijkbare manier Bestand objecten bouwen via de Bestand() class. Het is vaak echter simpeler om hiervoor de convience functie bestand_from_file() te gebruiken, omdat deze veel gegevens, zoals PRONOM informatie en checksums, automatisch voor je aanmaakt:

import mdto
from mdto.gegevensgroepen import *

# verwijzing naar bijbehorend informatieobject
obj_verwijzing = VerwijzingGegevens("Verlenen kapvergunning Hooigracht")

bestand = mdto.bestand_from_file(
        file="vergunning.pdf",  # bestand waarvoor technische metagegevens moeten worden aangemaakt
        identificatie=Identificatiegegevens("34c5-4379-9f1a-5c378", "Proza (DMS)"),
        isrepresentatievan=obj_verwijzing
     )

# Sla op als XML bestand
bestand.save("vergunning.bestand.mdto.xml")

Het resulterende XML bestand bevat vervolgens de correcte <omvang>, <bestandsformaat>, <checksum> , en <isRepresentatieVan> tags. <URLBestand> tags kunnen ook worden aangemaakt worden via de optionele url= parameter van bestand_from_file().

XML bestanden inlezen

mdto.py kan ook MDTO bestanden inlezen en naar Python MDTO objecten omzetten via de from_xml functie.

Stel bijvoorbeeld dat je alle checksums van Bestand XML bestanden wilt updaten:

import mdto
from pathlib import Path

# Aangenomen dat je mapstructuur er zo uitziet:
# mdto_collectie/
# ├── Kapvergunning/
# │   ├── 19880405KapvergunningHoogracht.bestand.mdto.xml
# │   ├── 19880405KapvergunningHoogracht.mdto.xml
# │   └── 19880405KapvergunningHoogracht.pdf
# └── Verslag/
#     ├── 19880409Verslag.bestand.mdto.xml
#     ├── 19880409Verslag.mdto.xml
#     └── 19880409Verslag.pdf


# itereer door alle Bestand XMLs:
for bestand_path in Path(".").rglob("*.bestand.mdto.xml"):
    bestand = mdto.from_xml(bestand_path)

    # vind naam + path van het te updaten bestand
    filename = bestand.naam  # in de regel bevat <naam> de bestandsnaam
    filepath = bestand_path.parent / filename

    # maak een nieuwe checksum
    bestand.checksum = mdto.create_checksum(filepath)

    # schrijf geüpdatet Bestand object terug naar de oorspronkelijke XML file
    bestand.save(bestand_path)

Autocompletion & documentatie in je teksteditor/IDE

mdto.py bevat docstrings, zodat teksteditors/IDEs je kunnen ondersteunen met documentatie popups en vensters. Handig als je even niet meer wat een MDTO element precies doet.

doc-popup.webm

Autocompletition werkt natuurlijk ook:

autocompletion-cast.webm