dv_schema_models 0.9.0__py3-none-any.whl

dv_schema_models/__init__.py

@@ -0,0 +1 @@
+"""dv_schema_models."""

dv_schema_models/dataset_instance.py

@@ -0,0 +1,305 @@
+"""Pydantic models for a Dataverse dataset export (`GET /api/datasets/:id` response).
+
+This is the companion to dataverse_schema.py: that file models the *schema*
+(what fields CAN exist and their rules), this file models actual *metadata
+values* attached to one dataset. The shapes are different — here each field
+is {typeName, multiple, typeClass, value}, and `value` itself is polymorphic
+depending on typeClass/multiple:
+
+  - primitive / controlledVocabulary, multiple=False -> a plain string
+  - primitive / controlledVocabulary, multiple=True   -> a list of strings
+  - compound, multiple=False                          -> a dict of nested fields
+  - compound, multiple=True                           -> a list of dicts of nested fields
+"""
+# ruff:file-ignore[mixed-case-variable-in-class-scope]
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field
+
+from dv_schema_models.file_instance import FileInstance
+
+
+class DatasetFieldValue(BaseModel):
+    """One metadata field value, as it appears inside metadataBlocks.<block>.fields."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    typeName: str
+    multiple: bool
+    typeClass: str  # 'primitive', 'compound', or 'controlledVocabulary'
+    value: str | list[str] | dict[str, DatasetFieldValue] | list[dict[str, DatasetFieldValue]]
+
+    def simple_value(self) -> Any:
+        """Recursively strip away the typeName/multiple/typeClass wrapper, returning plain Python values.
+
+        Compound fields become plain dicts (or lists of dicts); primitive and
+        controlledVocabulary fields are already plain strings or lists of strings.
+        """
+        if self.typeClass == "compound":
+            if isinstance(self.value, list):
+                return [{k: v.simple_value() for k, v in item.items()} for item in self.value]
+            if isinstance(self.value, dict):
+                return {k: v.simple_value() for k, v in self.value.items()}
+        return self.value
+
+    def get_fields(self) -> list[DatasetFieldValue]:
+        """Return a flat list of all DatasetFieldValue objects nested inside this one."""
+        return [self.typeName for f in self.value]
+
+
+# Needed because DatasetFieldValue references itself by forward-reference string.
+DatasetFieldValue.model_rebuild()
+
+
+class MetadataBlockInstance(BaseModel):
+    """One populated metadata block (e.g. citation) within a dataset version."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    displayName: str
+    name: str
+    fields: list[DatasetFieldValue]
+
+    def field_names(self) -> list[str]:
+        """Return the typeName of every field present in this block instance."""
+        return [f.typeName for f in self.fields]
+
+    def get_field(self, type_name: str) -> DatasetFieldValue | None:
+        """Find a field in this block by its typeName (e.g. 'title', 'author')."""
+        return next((f for f in self.fields if f.typeName == type_name), None)
+
+    def get_value(self, type_name: str) -> Any:
+        """Get the plain (unwrapped) value of a field in this block, or None if absent."""
+        field = self.get_field(type_name)
+        return field.simple_value() if field else None
+
+    def get_subfield_values(self, type_name: str, subfield: str) -> list[Any]:
+        """Collect one subfield from a compound field, e.g. get_subfield_values('author', 'authorName') -> ['Author1', 'Author2']."""
+        value = self.get_value(type_name)
+        items = value if isinstance(value, list) else [value] if value else []
+        return [item[subfield] for item in items if subfield in item]
+
+
+class DatasetVersion(BaseModel):
+    """One version of a dataset, holding the actual metadata block values and files."""
+
+    model_config = ConfigDict(extra="allow")
+
+    id: int
+    datasetId: int
+    versionState: str
+    datasetPersistentId: str
+    datasetType: (
+        str | None
+    )  # backward compatibility: some datasets /older Dataverse versions don't have this field
+    storageIdentifier: str
+    versionNumber: int | None = None
+    internalVersionNumber: int
+    versionMinorNumber: int | None = None
+    latestVersionPublishingState: str
+    deaccessionLink: str | None = Field(None)
+    UNF: str | None = Field(None)
+    lastUpdateTime: str
+    releaseTime: str | None = Field(None)
+    createTime: str
+    termsOfUse: str | None = Field(None)
+    termsOfAccess: str | None = Field(None)
+    dataAccessPlace: str | None = Field(None)
+    fileAccessRequest: bool
+
+    metadataBlocks: dict[str, MetadataBlockInstance]
+
+    files: list[FileInstance] | None = None
+
+    def get_value(self, block_name: str, type_name: str) -> Any:
+        """Get a field's plain value by block name (e.g. 'citation') and field typeName (e.g. 'title')."""
+        block = self.metadataBlocks.get(block_name)
+        return block.get_value(type_name) if block else None
+
+    def field_names(self, block_name: str) -> list[str]:
+        """Get the typeNames of every field present in the given block (e.g. 'citation').
+
+        Parameters
+        ----------
+        block_name
+            The name of the metadata block (e.g. 'citation', 'geospatial').
+
+        Returns
+        -------
+        list[str]
+            A list of typeNames for the fields present in the specified block.
+
+        """
+        block = self.metadataBlocks.get(block_name)
+        return block.field_names() if block else []
+
+    def get_raw(self, key: str) -> object | None:
+        """Get a raw top-level field not covered by the schema.
+
+        Parameters
+        ----------
+        key
+            The name of the top-level field to retrieve.
+
+        Returns
+        -------
+        object | None
+            The value of the specified field, or None if not found.
+
+
+        """
+        return self.model_extra.get(key) if self.model_extra else None
+
+
+class IsPartOf(BaseModel):
+    """The 'isPartOf' payload of a dataset export response.
+
+    See: https://github.com/IQSS/dataverse/blob/dd1859dde249df8b0612ca3899b5f00fcc6d082e/src/main/java/edu/harvard/iq/dataverse/util/json/JsonPrinter.java#L533-L562 (v6.11)
+
+    """  # ruff:ignore[doc-line-too-long]
+
+    model_config = ConfigDict(extra="allow")
+
+    type: str
+    identifier: str
+    isReleased: bool | None = None  # backward compatibility
+    persistentIdentifier: str | None = None
+    displayName: str
+    isPartOf: IsPartOf | None = None  # recursive
+
+    @staticmethod
+    def get_field_list(node: IsPartOf | None, field_name: str, *, from_root: bool = False) -> list:
+        """Return the values of a field from a node to the root.
+
+        Parameters
+        ----------
+        node
+            The node to start from. May be None, in which case an empty list is returned.
+
+        field_name
+            The name of the field to retrieve (e.g. 'identifier', 'displayName').
+
+        from_root
+            If True, return the values from the root to this node; if False, return from this node to the root.
+
+        Returns
+        -------
+        list
+            A list of the values of the specified field.
+
+        """  # ruff:ignore[doc-line-too-long]
+        values = []
+        current = node
+
+        while current is not None:
+            values.append(getattr(current, field_name))
+            current = current.isPartOf
+
+        if not from_root:
+            values.reverse()
+        return values
+
+
+class DatasetData(BaseModel):
+    """The 'data' payload of a dataset export response."""
+
+    model_config = ConfigDict(extra="allow")
+
+    id: int
+    identifier: str
+    persistentUrl: str
+    protocol: str
+    authority: str
+    separator: str
+    publisher: str
+    storageIdentifier: str
+    isPartOf: IsPartOf | None = None
+    datasetType: str | None = (
+        None  # backward compatibility: some datasets /older Dataverse versions don't have this field
+    )
+
+    latestVersion: DatasetVersion | None = Field(
+        None, validation_alias=AliasChoices("datasetVersion", "latestVersion")
+    )  # Deaccessioned dataset does not have this field.
+
+    @property
+    def datasetVersion(self) -> DatasetVersion | None:
+        """Supports both export and Native JSON endpoints.
+
+        Returns
+        -------
+        DatasetVersion | None
+            The latest version of the dataset, or None if not present.
+
+        """
+        return self.latestVersion
+
+    def get_raw(self, key: str) -> object | None:
+        """Get a raw top-level field not covered by the schema.
+
+        Parameters
+        ----------
+        key
+            The name of the top-level field to retrieve.
+
+        Returns
+        -------
+        object | None
+            The value of the specified field, or None if not found.
+
+        """
+        return self.model_extra.get(key) if self.model_extra else None
+
+
+class DatasetJson(BaseModel):
+    """Top-level wrapper matching the raw JSON returned by GET /api/datasets/:id."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    status: str
+    data: DatasetData
+
+    def get_value(
+        self, block_name: str, type_name: str
+    ) -> str | list[str] | dict[str, Any] | list[dict[str, Any]] | None:
+        """Get the value of a field by its block and type names.
+
+        Parameters
+        ----------
+            block_name: The name of the metadata block (e.g. 'citation', 'geospatial').
+            type_name: The typeName of the field within that block (e.g. 'title', 'author').
+
+        Returns
+        -------
+            str | list[str] | dict[str, Any] | list[dict[str, Any]] | None: The value of the specified field, or None if not found.
+
+        """  # ruff:ignore[doc-line-too-long]
+        return self.data.latestVersion.get_value(block_name, type_name)
+
+    def field_names(self, block_name: str) -> list[str]:
+        """Check what fields are present in a given block.
+
+        Parameters
+        ----------
+            block_name: The name of the metadata block (e.g. 'citation', 'geospatial').
+
+        Returns
+        -------
+            list[str]: A list of typeNames for the fields present in the specified block.
+
+        """
+        return self.data.latestVersion.field_names(block_name)
+
+
+def load_dataset(metadata: dict) -> DatasetJson:
+    """Parse a dataset export JSON payload (already loaded as a dict) into a DatasetExport.
+
+    Accepts either the full `{status, data: {...}}` export envelope, or a bare
+    `data`-shaped payload (no envelope), by trying each model in turn.
+    """
+    if "data" in metadata:
+        return DatasetJson.model_validate(metadata)
+    return DatasetJson(status="OK", data=DatasetData.model_validate(metadata))

dv_schema_models/dataverse_schema.py

@@ -0,0 +1,109 @@
+"""Pydantic models for the Dataverse '/api/metadatablocks' schema response.
+
+This models the *schema definition* JSON itself (block -> fields -> optional
+recursive childFields), not an individual dataset's metadata values. Use it to
+parse, validate, and query the schema (e.g. "what fields exist in the citation
+block?", "is authorAffiliation required?", "what controlled vocab values does
+subject accept?").
+"""
+
+# ruff: noqa: N815
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class MetadataField(BaseModel):
+    """A single metadata field definition.
+
+    For compound fields (typeClass == 'compound'), `childFields` holds the
+    nested sub-fields, keyed by field name, recursively using this same model.
+    Leaf fields (primitive or controlledVocabulary) have `childFields = None`.
+    """
+
+    model_config = ConfigDict(extra="ignore")  # tolerate any schema fields we did not model
+
+    name: str
+    displayName: str
+    displayOnCreate: bool
+    title: str
+    type: str  # e.g. 'TEXT', 'TEXTBOX', 'DATE', 'INT', 'FLOAT', 'URL', 'EMAIL', 'NONE'
+    typeClass: str  # 'primitive', 'compound', or 'controlledVocabulary'
+    watermark: str = ""
+    description: str = ""
+    multiple: bool
+    isControlledVocabulary: bool
+    isAdvancedSearchFieldType: bool
+    displayFormat: str = ""
+    displayOrder: int
+    isRequired: bool
+    controlledVocabularyValues: list[str] | None = None
+    childFields: dict[str, MetadataField] | None = None
+
+    def is_compound(self) -> bool:
+        """Return True if this field wraps nested childFields rather than holding a value directly."""
+        return self.childFields is not None
+
+    def iter_leaf_fields(self) -> list[MetadataField]:
+        """Recursively collect every leaf (non-compound) field reachable from this field."""
+        if self.childFields:
+            leaves: list[MetadataField] = []
+            for child in self.childFields.values():
+                leaves.extend(child.iter_leaf_fields())
+            return leaves
+        return [self]
+
+
+# Needed because MetadataField references itself by forward-reference string.
+MetadataField.model_rebuild()
+
+
+class MetadataBlock(BaseModel):
+    """A single metadata block (e.g. citation, geospatial, astrophysics)."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    id: int
+    name: str
+    displayName: str
+    displayOnCreate: bool
+    fields: dict[str, MetadataField]
+
+    def get_field(self, field_name: str) -> MetadataField | None:
+        """Look up a top-level field in this block by its key name."""
+        return self.fields.get(field_name)
+
+    def all_leaf_fields(self) -> dict[str, MetadataField]:
+        """Flatten every leaf field in this block (including nested ones) into a single dict."""
+        flat: dict[str, MetadataField] = {}
+        for field in self.fields.values():
+            for leaf in field.iter_leaf_fields():
+                flat[leaf.name] = leaf
+        return flat
+
+    def required_fields(self) -> list[str]:
+        """Return the names of all leaf fields marked isRequired = True."""
+        return [name for name, field in self.all_leaf_fields().items() if field.isRequired]
+
+
+class DataverseSchemaResponse(BaseModel):
+    """Top-level wrapper matching the raw JSON returned by /api/metadatablocks."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    status: str
+    data: list[MetadataBlock]
+
+    def get_block(self, block_name: str) -> MetadataBlock | None:
+        """Look up a metadata block by its short name (e.g. 'citation', 'geospatial')."""
+        return next((b for b in self.data if b.name == block_name), None)
+
+    def block_names(self) -> list[str]:
+        """List the short names of every block in the response."""
+        return [b.name for b in self.data]
+
+
+def load_schema(metadata: dict) -> DataverseSchemaResponse:
+    """Parse a metadatablocks JSON payload (already loaded as a dict) into a DataverseSchemaResponse."""
+    return DataverseSchemaResponse.model_validate(metadata)

dv_schema_models/file_instance.py

@@ -0,0 +1,124 @@
+"""File representation models."""
+# ruff: noqa: N815
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+logger = logging.getLogger(__name__)
+
+
+class DataFile(BaseModel):
+    """The 'dataFile' object nested inside a FileInstance."""
+
+    model_config = ConfigDict(extra="allow")
+
+    id: int | None = None
+    persistentId: str | None = None
+    filename: str | None = None
+    contentType: str | None = None
+    friendlyType: str | None = None
+    filesize: int | None = None
+    description: str | None = None
+    storageIdentifier: str | None = None
+    rootDataFileId: int | None = None
+    md5: str | None = None
+    checksum: CheckSum | None = None
+    tabularData: bool | None = None
+    creationDate: str | None = None
+    directoryLabel: str | None = None
+    lastUpdateTime: str | None = None
+    fileAccessRequest: bool | None = None
+
+    def get_raw(self, key: str) -> object | None:
+        """Get a raw top-level field not covered by the schema (requires extra='allow')."""
+        return self.model_extra.get(key) if self.model_extra else None
+
+
+class CheckSum(BaseModel):
+    """The 'checksum' object nested inside a DataFile."""
+
+    model_config = ConfigDict(extra="allow")
+
+    type: str
+    value: str
+
+    def get_raw(self, key: str) -> object | None:
+        """Get a raw top-level field not covered by the schema (requires extra='allow')."""
+        return self.model_extra.get(key) if self.model_extra else None
+
+
+class FileInstance(BaseModel):
+    """One file, as it appears inside a dataset version."""
+
+    model_config = ConfigDict(extra="allow")
+
+    label: str | None = None
+    restricted: bool | None = None
+    directoryLabel: str | None = None
+    version: int | None = None
+    datasetVersionId: int | None = None
+    dataFile: DataFile | None = None
+
+    def get_raw(self, key: str) -> object | None:
+        """Get a raw top-level field not covered by the schema (requires extra='allow')."""
+        return self.model_extra.get(key) if self.model_extra else None
+
+    @staticmethod
+    def sum_field(instances: list[FileInstance], field: str) -> float | None:
+        """Sum a DataFile field across FileInstances, skipping entries with no dataFile or None values.
+
+        Returns None (and logs a warning) if any present value isn't int/float.
+
+        Parameters
+        ----------
+        instances
+            A list of FileInstance objects to sum over.
+        field
+            The name of the field to sum, e.g. "dataFile.filesize".
+
+        Returns
+        -------
+        float | None
+            The sum of the field values, or None if any value is non-numeric.
+
+        """  # noqa: W505
+        values = [getattr(i.dataFile, field) for i in instances if i.dataFile is not None]
+        for v in values:
+            if v is not None and not isinstance(v, (int, float)):
+                logger.warning("sum_field: field %r has non-numeric value %r", field, v)
+                return None
+        return sum(v for v in values if v is not None)
+
+    @staticmethod
+    def list_field(instances: list[FileInstance], field: str) -> list[Any]:
+        """Get the values of a field across instances, e.g. field="dataFile.checksum.type".
+
+        Skips instances where the path is missing or resolves to None.
+
+        Parameters
+        ----------
+        instances
+            A list of FileInstance objects to extract values from.
+
+        field
+            The name of the field to extract, e.g. "dataFile.checksum.type".
+
+        Returns
+        -------
+        list[Any]
+            A list of values for the specified field across the instances.
+        """
+        result = []
+        for i in instances:
+            value: Any = i
+            for part in field.split("."):
+                value = getattr(value, part, None)
+                if value is None:
+                    break
+            if value is not None:
+                result.append(value)
+        return result

dv_schema_models/role_assignments.py

@@ -0,0 +1,89 @@
+"""Role assignments model.
+
+Corresponds to "List Role Assignments in a Dataset" endpoint: https://borealisdata.ca/guides/en/latest/api/native-api.html#list-role-assignments-in-a-dataset
+
+"""
+# ruff: noqa: N815
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class RoleAssignment(BaseModel):
+    """A single role assignment."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    id: int | None = None
+    assignee: str | None = None
+    roleId: int | None = None
+    roleName: str | None = None
+    roleAlias: str | None = Field(default=None, alias="_roleAlias")
+    definitionPointId: int | None = None
+
+    def get_raw(self, key: str) -> object | None:
+        """Get a raw top-level field not covered by the schema (requires extra='allow')."""
+        return self.model_extra.get(key) if self.model_extra else None
+
+
+class RoleAssignments(BaseModel):
+    """Role assignments model."""
+
+    model_config = ConfigDict(extra="allow")
+
+    status: str | None = None
+    data: list[RoleAssignment] | None = None
+
+    def count_field(self, field_name: str, value: str | int | None = None) -> int:
+        """Count the number of occurrences of a field with a specific value. If value is None, counts all occurrences of the field regardless of value.
+
+        Parameters
+        ----------
+        field_name
+            The name of the field to count.
+        value
+            The value to look for and count. If None, counts all occurrences of the field regardless of value.
+
+        Returns
+        -------
+        int
+            The number of occurrences of the field with the specified value.
+
+        """  # noqa: W505
+        if not self.data:
+            return 0
+
+        if value is None:
+            return sum(1 for ra in self.data if hasattr(ra, field_name))
+
+        return sum(
+            1 for ra in self.data if hasattr(ra, field_name) and getattr(ra, field_name) == value
+        )
+
+    def get_value(self, field_name: str) -> list[str | int | None]:
+        """Get a list of all values for the given field name. Returns None for role assignments that don't have the field.
+
+        Parameters
+        ----------
+        field_name
+            The name of the field to retrieve values for.
+
+        Returns
+        -------
+        list[str | int | None]
+            A list of values for the specified field, or None for role assignments that don't have the field.
+
+        """  # noqa: W505
+        if not self.data:
+            return []
+        return [getattr(ra, field_name) if hasattr(ra, field_name) else None for ra in self.data]
+
+
+def load_role_assignments(metadata: dict) -> RoleAssignments:
+    """Parse a role assignments JSON payload (already loaded as a dict) into a RoleAssignments.
+
+    Accepts the full `{status, data: [...]}` export envelope (including error
+    responses with no `data`), or a bare single role assignment dict (no envelope).
+    """
+    if "data" in metadata or "status" in metadata:
+        return RoleAssignments.model_validate(metadata)
+    return RoleAssignments(status="OK", data=[RoleAssignment.model_validate(metadata)])

dv_schema_models/schema_driven_records.py

@@ -0,0 +1,99 @@
+"""Build a Pydantic model FROM the Dataverse schema, then use it to validate real dataset values.
+
+Workflow:
+  1. Load the metadatablocks schema (dataverse_schema.py) -> know what fields exist, their
+     types, whether they're required/multiple, and what compound sub-fields they contain.
+  2. Dynamically build a Pydantic model that mirrors that schema exactly, using pydantic.create_model.
+  3. Load a dataset export (dataset_instance.py) and flatten it to {typeName: value}.
+  4. Validate that flat dict against the schema-derived model, so the actual metadata is checked
+     against the same field names, required-ness, and structure the schema defines -- instead of
+     a generic model that would accept any field.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pydantic import BaseModel, ConfigDict, Field, create_model
+
+from dv_schema_models.dataset_instance import MetadataBlockInstance
+from dv_schema_models.dataverse_schema import MetadataBlock, MetadataField
+
+# Maps a Dataverse field 'type' to a Python type. Anything not listed here (TEXT, TEXTBOX,
+# DATE, URL, EMAIL, and controlled-vocabulary text) is treated as a plain str.
+_PRIMITIVE_TYPE_MAP: dict[str, type] = {"INT": int, "FLOAT": float}
+
+
+def _python_type_for(field: MetadataField) -> type:
+    """Map a leaf schema field's declared 'type' to a Python type.
+
+    Parameters
+    ----------
+    field: The schema MetadataField to map.
+
+    Returns
+    -------
+    type: The Python type corresponding to the Dataverse field's 'type'.
+
+    """
+    return _PRIMITIVE_TYPE_MAP.get(field.type, str)
+
+
+def _safe_identifier(name: str) -> str:
+    """Turn a Dataverse field name that may contain dots (e.g. 'resolution.Spatial') into a valid Python identifier."""
+    return name.replace(".", "_")
+
+
+def build_record_model(
+    source: MetadataBlock | MetadataField, *, model_name: str | None = None
+) -> type[BaseModel]:
+    """Recursively build a Pydantic model matching a schema MetadataBlock (or a compound MetadataField).
+
+    The resulting model accepts exactly the fields the schema defines: correct nested structure
+    for compound fields, List[...] wrapping for multiple=True fields, and required vs Optional
+    matching isRequired.
+    """
+    if isinstance(source, MetadataBlock):
+        fields = source.fields
+        default_name = f"{source.name.capitalize()}Record"
+    else:
+        fields = source.childFields or {}
+        default_name = f"{source.name.capitalize()}Record"
+
+    field_definitions: dict[str, Any] = {}
+
+    for field_name, field in fields.items():
+        py_name = _safe_identifier(field_name)
+
+        if field.is_compound():
+            base_type: Any = build_record_model(
+                field, model_name=f"{field_name.capitalize()}Record"
+            )
+        else:
+            base_type = _python_type_for(field)
+
+        if field.multiple:
+            base_type = list[base_type]
+
+        if not field.isRequired:
+            base_type = Optional[base_type]
+            default = None
+        else:
+            default = ...
+
+        if py_name != field_name:
+            # Field name isn't a valid Python identifier as-is -- alias back to the original.
+            field_definitions[py_name] = (base_type, Field(default, alias=field_name))
+        else:
+            field_definitions[py_name] = (base_type, default)
+
+    return create_model(
+        model_name or default_name,
+        __config__=ConfigDict(populate_by_name=True, extra="forbid"),
+        **field_definitions,
+    )
+
+
+def flatten_instance(block_instance: MetadataBlockInstance) -> dict[str, Any]:
+    """Turn a dataset export's field list into a flat {typeName: value} dict, ready to validate."""
+    return {f.typeName: f.simple_value() for f in block_instance.fields}

dv_schema_models/schema_spreadsheet.py

@@ -0,0 +1,134 @@
+"""Turns the dataverse schema into a spreadsheet."""
+
+import random
+from pathlib import Path
+
+import xlsxwriter
+from xlsxwriter.format import Format
+
+from dv_schema_models.dataverse_schema import DataverseSchemaResponse, MetadataBlock, MetadataField
+
+# (title, definition, usage, repeatable, example, is_top_level, is_last_row_of_field)
+Row = tuple[str, str, str, str, str, bool, bool]
+
+COLUMN_WIDTHS = [30, 90, 10, 16, 60]
+
+
+class SchemaSpreadsheet:
+    """Turns the dataverse schema into a spreadsheet."""
+
+    def __init__(self, schema: DataverseSchemaResponse) -> None:
+        """Initialize the SchemaSpreadsheet with a DataverseSchemaResponse."""
+        self.schema = schema.data
+
+    @staticmethod
+    def _header_row() -> list[str]:
+        return ["Field", "Definition", "Usage", "Repeatable (Y/N)", "Example"]
+
+    def _title_fmt(self, workbook: xlsxwriter.Workbook):
+        return workbook.add_format({"bold": True})
+
+    def _block_fmt(self, workbook: xlsxwriter.Workbook):
+        return workbook.add_format({
+            "bold": True,
+            "align": "center",
+            "bg_color": f"#{random.randrange(0x1000000):06x}",
+        })
+
+    @staticmethod
+    def _field_rows(field: MetadataField) -> list[Row]:
+        """Turn one top-level field (and its children) into spreadsheet rows."""
+        # ponytail: usage is RQ/O from isRequired; the schema has no "recommended" flag
+        usage = lambda f: "RQ" if f.isRequired else "O"  # noqa: E731
+        repeatable = lambda f: "Y" if f.multiple else "N"  # noqa: E731
+
+        if not field.childFields:
+            return [
+                (
+                    field.title,
+                    field.description,
+                    usage(field),
+                    repeatable(field),
+                    field.watermark,
+                    True,
+                    True,
+                )
+            ]
+        # Compound field: parent row carries only the definition, children the rest.
+        rows: list[Row] = [(field.title, field.description, "", "", "", True, False)]
+        children = sorted(field.childFields.values(), key=lambda f: f.displayOrder)
+        rows.extend(
+            (
+                child.title,
+                child.description,
+                usage(child),
+                # A child of a repeatable compound is effectively repeatable.
+                "Y" if (child.multiple or field.multiple) else "N",
+                child.watermark,
+                False,
+                child is children[-1],
+            )
+            for child in children
+        )
+        return rows
+
+    def _write_sheet(
+        self,
+        workbook: xlsxwriter.Workbook,
+        sheet_name: str,
+        blocks: list[MetadataBlock],
+        cell_fmts: dict[tuple[bool, bool], Format],
+    ) -> None:
+        sheet = workbook.add_worksheet(sheet_name)
+        for col, width in enumerate(COLUMN_WIDTHS):
+            sheet.set_column(col, col, width)
+
+        sheet.write_row(0, 0, self._header_row(), self._title_fmt(workbook))
+
+        row_num = 1
+        for block in blocks:
+            sheet.merge_range(
+                row_num, 0, row_num, 4, f"{block.displayName} Block", self._block_fmt(workbook)
+            )
+            row_num += 1
+            for field in sorted(block.fields.values(), key=lambda f: f.displayOrder):
+                for title, *cells, bold, end in self._field_rows(field):
+                    sheet.write(row_num, 0, title, cell_fmts[bold, end])
+                    for col, value in enumerate(cells, start=1):
+                        sheet.write(row_num, col, value, cell_fmts[False, end])
+                    row_num += 1
+
+    def write(self, path: str | Path) -> Path:
+        """Write an 'All' worksheet plus one per metadata block to an .xlsx file at `path`.
+
+        Parameters
+        ----------
+        path
+            The path to the .xlsx file to write. If it exists, it will be overwritten
+
+        Returns
+        -------
+        Path
+            The path to the .xlsx file that was written.
+
+        """
+        path = Path(path)
+        workbook = xlsxwriter.Workbook(str(path))
+        cell_fmts = {
+            (bold, end): workbook.add_format({
+                "bold": bold,
+                "bottom": 1 if end else 0,
+                "text_wrap": True,
+                "valign": "top",
+            })
+            for bold in (True, False)
+            for end in (True, False)
+        }
+        blocks = sorted(self.schema, key=lambda b: b.id)
+        self._write_sheet(workbook, "All", blocks, cell_fmts)
+        for block in blocks:
+            self._write_sheet(
+                workbook, block.displayName.removesuffix(" Metadata")[:31], [block], cell_fmts
+            )
+        workbook.close()
+        return path

dv_schema_models-0.9.0.dist-info/METADATA

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: dv_schema_models
+Version: 0.9.0
+Summary: Turns Harvard Dataverse Project metadatablocks schema and dataset JSON into Pydantic models.
+Author: Ken Lui
+Author-email: Ken Lui <kenlh.lui@utoronto.ca>
+License-Expression: MIT
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Python: >=3.10, <4.0
+Project-URL: homepage, https://github.com/kenlhlui/dv_schema_models
+Project-URL: source, https://github.com/kenlhlui/dv_schema_models
+Project-URL: changelog, https://github.com/kenlhlui/dv_schema_models/blob/main/CHANGELOG.md
+Project-URL: releasenotes, https://github.com/kenlhlui/dv_schema_models/releases
+Project-URL: documentation, https://kenlhlui.github.io/dv_schema_models
+Project-URL: issues, https://github.com/kenlhlui/dv_schema_models/issues
+Description-Content-Type: text/markdown
+
+# dv_schema_models
+
+Pydantic models for Dataverse metadata — parse the schema, load dataset 
+exports, and validate field values against the schema.
+
+> [!CAUTION]
+> This library is under active development and the API is not yet stable. Breaking changes may occur between releases. Please pin to a specific version in your `pyproject.toml` or `requirements.txt` if you want to avoid surprises.
+
+## Pre-requisites
+1. Python 3.10+
+
+## Installation
+
+1. With `uv` (recommended):
+```bash
+uv add dv_schema_models
+```
+
+2. With `pip`:
+```bash
+pip install dv_schema_models
+```
+
+To export schemas to Excel (see [usage #5](#5-export-the-schema-to-a-spreadsheet)), install with the `spreadsheet` extra:
+```bash
+uv add "dv_schema_models[spreadsheet]"   # or: pip install "dv_schema_models[spreadsheet]"
+```
+
+## Concepts
+
+| Thing | What it is |
+|---|---|
+| **Schema** | `/api/metadatablocks` response — defines what fields *can* exist, their types, and rules |
+| **Dataset instance** | `GET /api/datasets/:id` response — the actual metadata values for one dataset |
+| **Record model** | A Pydantic model *generated from* the schema, used to validate instance values |
+
+## Usage
+
+### 1. Load and query the schema
+
+```python
+import json
+from dv_schema_models.dataverse_schema import load_schema
+
+schema = load_schema(json.load(open("dv_schema.json")))
+
+schema.block_names()                        # ['citation', 'geospatial', ...]
+block = schema.get_block("citation")
+block.fields.keys()                         # top-level field names
+block.required_fields()                     # leaf fields where isRequired=True
+block.all_leaf_fields()                     # flattened, including nested compound fields
+
+field = block.get_field("keyword")
+field.is_compound()                         # True — has childFields
+field.iter_leaf_fields()                    # [keywordValue, keywordVocabulary, ...]
+```
+
+### 2. Load a dataset and read values
+
+```python
+import json
+from dv_schema_models.dataset_instance import IsPartOf, load_dataset
+
+dataset = load_dataset(json.load(open("ds_metadata.json")))
+
+# Load the possible typeNames for a given block
+dataset.field_names("citation")  # ['title', 'author', 'keyword', ...] 
+dataset.data.latestVersion.metadataBlocks.get("citation").field_names() # same
+
+
+# Shortcut from the top level
+dataset.get_value("citation", "title")      # plain string
+
+# Or drill down
+block = dataset.data.latestVersion.metadataBlocks.get("citation")
+block.get_value("keyword")                  # unwrapped Python value (str / list / dict)
+block.get_field("author").simple_value()    # [{'authorName': 'Author1', 'authorAffiliation': 'Author1Aff'...} ... {'authorName': 'Author2', 'authorAffiliation': 'Author2Aff'...}]
+
+# Pull one subfield out of a compound field
+block.get_subfield_values("author", "authorName")  # ['Author1', 'Author2']
+
+# Walk the isPartOf chain (dataset -> collection -> parent collection -> ...), possibly None
+IsPartOf.get_field_list(dataset.data.isPartOf, "identifier")  # ['sub-collection', 'top-collection']
+```
+
+### 3. Work with files
+
+```python
+from dv_schema_models.dataset_instance import load_dataset
+from dv_schema_models.file_instance import FileInstance
+
+dataset = load_dataset(json.load(open("ds_metadata.json")))
+
+files = dataset.data.latestVersion.files or []
+FileInstance.sum_field(files, "filesize")   # sum a DataFile field across files, e.g. total filesize
+FileInstance.list_field(files, "dataFile.filename")   # list a field's values across files, dotted path for nested fields
+```
+
+`sum_field` skips files with no `dataFile` or a `None` value for the field. Returns `None` (and logs a warning) if any present value isn't numeric.
+
+`list_field` takes a dotted path (e.g. `"restricted"` for a top-level field, `"dataFile.checksum.type"` for a nested one) and skips entries where the path is missing or `None`.
+
+### 4. Work with role assignments
+
+```python
+import json
+from dv_schema_models.role_assignments import load_role_assignments
+
+role_assignments = load_role_assignments(json.load(open("ds_role_assignments.json")))
+
+role_assignments.count_field("assignee")            # number of assignments with an "assignee" field
+role_assignments.count_field("roleName", "Curator") # number of assignments where roleName == "Curator"
+role_assignments.get_value("assignee")              # ['@personA', '@personB', ...]
+
+# Fields not on the schema (e.g. the `_roleAlias` Dataverse sends) are still reachable
+role_assignments.data[0].get_raw("_roleAlias")      # 'curator'
+```
+
+`load_role_assignments` also accepts the error envelope Dataverse returns when the request isn't permitted (`{"status": "ERROR", "message": "..."}`) — `data` is `None`, and `message` is reachable via `role_assignments.model_extra`.
+
+### 5. Validate instance values against the schema
+
+```python
+import json
+from dv_schema_models.dataverse_schema import load_schema
+from dv_schema_models.dataset_instance import load_dataset
+from dv_schema_models.schema_driven_records import build_record_model, flatten_instance
+
+
+schema = load_schema(json.load(open("dv_schema.json")))
+dataset = load_dataset(json.load(open("ds_metadata.json")))
+
+citation_schema = schema.get_block("citation")
+CitationRecord = build_record_model(citation_schema)   # dynamic Pydantic model
+
+block = dataset.data.latestVersion.metadataBlocks.get("citation")
+raw = flatten_instance(block)              # {typeName: value, ...}
+record = CitationRecord.model_validate(raw)
+```
+
+The generated model enforces field names, required/optional status, list wrapping for `multiple=True` fields, and `int`/`float` types where declared by the schema.
+
+### 6. Discover available fields
+
+```python
+# Fields actually present in this dataset instance
+block = dataset.data.latestVersion.metadataBlocks.get("citation")
+block.field_names()                            # e.g. ['title', 'author', 'keyword', ...]
+
+# All fields the schema defines (including absent/optional ones)
+schema.get_block("citation").all_leaf_fields().keys()
+
+# After validation, access as typed attributes
+record = CitationRecord.model_validate(flatten_instance(block))
+record.title          # str
+record.author         # list[...] for multiple=True compound fields
+record.keyword        # None if not present in this dataset (optional fields default to None)
+# Note: field names with dots become underscores — e.g. 'resolution.Spatial' → record.resolution_Spatial
+```
+
+### 7. Export the schema to a spreadsheet
+
+Requires the `spreadsheet` extra (see [Installation](#installation)).
+
+```python
+import json
+from dv_schema_models.dataverse_schema import load_schema
+from dv_schema_models.schema_spreadsheet import SchemaSpreadsheet
+
+schema = load_schema(json.load(open("dv_schema.json")))
+SchemaSpreadsheet(schema).write("dv_schema.xlsx")
+```
+
+Writes an `.xlsx` workbook with one formatted worksheet per metadata block plus a combined **All** sheet. See [docs/schema_spreadsheet/README.md](docs/schema_spreadsheet/README.md) for the output layout, column mapping, and architecture.
+
+## Input file shapes
+
+**Schema** — output of Dataverse `/api/metadatablocks`:
+```json
+{"status": "OK", "data": [{"id": 10, "name": "citation", "fields": {...}}]}
+```
+
+**Dataset** — output of Dataverse `GET /api/datasets/:id`:
+```json
+{"status": "OK", "data": {"latestVersion": {"metadataBlocks": {"citation": {"fields": [...]}}}}}
+```
+
+**Role assignments** — output of Dataverse `GET /api/datasets/:id/assignments`:
+```json
+{"status": "OK", "data": [{"id": 1, "assignee": "@user", "roleId": 7, "roleName": "Curator", "definitionPointId": 34847}]}
+```
+Error responses (e.g. `{"status": "ERROR", "message": "..."}`, no `data` key) are also accepted — see [usage #4](#4-work-with-role-assignments).
+
+## Citation
+If you use this library in your work, please cite according to [CITATION](CITATION.cff)
+
+## License
+[MIT](LICENSE)

dv_schema_models-0.9.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+dv_schema_models/__init__.py,sha256=X3S5OpQrp39k1raDCGfNrvdAVInfNfuYmIb1GLjdYNc,24
+dv_schema_models/dataset_instance.py,sha256=xXiWPw4Zd-rq2KAeCN50gXqABTPoiZtxh__BsjRcEOI,10575
+dv_schema_models/dataverse_schema.py,sha256=KT9cHY0wHQUS5ig_v9wmwwXZBXT2GxmGObswCeDDRaM,4003
+dv_schema_models/file_instance.py,sha256=UGZ6_s2HAFSkKormXJMEAmAz_sIK_C-knNddq9VjcWg,3992
+dv_schema_models/role_assignments.py,sha256=-hYSLqIJkZl5EzonPDGCWKckgFwvUtFkQTZmT4rMdGI,3106
+dv_schema_models/schema_driven_records.py,sha256=TNejnWfk-Yob-1oTxlvHSkYoEhhmU4JpR2tq2oCp2e0,3783
+dv_schema_models/schema_spreadsheet.py,sha256=1pQ8Rjyoo09ux6hUn0Lf51FSgAfryqgTk4vYfo2cUPg,4756
+dv_schema_models-0.9.0.dist-info/WHEEL,sha256=r-Se0i_n47Mj8pdnVuq7W628oP9YAKMaTjp4l3lQcns,81
+dv_schema_models-0.9.0.dist-info/METADATA,sha256=yyohLs9IxJSNpRRAkAXzUAfBxSE5oXzgtPoEi1Gz-NQ,8699
+dv_schema_models-0.9.0.dist-info/RECORD,,

dv_schema_models-0.9.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.31
+Root-Is-Purelib: true
+Tag: py3-none-any