geometamaker 0.1.2__py3-none-any.whl → 0.2.0__py3-none-any.whl

geometamaker/models.py

@@ -1,25 +1,47 @@
 from __future__ import annotations
+import collections
 import logging
+import numbers
 import os
 import warnings
-from typing import List, Union
+from typing import Union
 
 import fsspec
 import yaml
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
 from pydantic.dataclasses import dataclass
 
 import geometamaker
 from . import utils
 
 
-LOGGER = logging.getLogger(__name__)
+LOGGER = logging.getLogger('geometamaker')
+
+
+def _deep_update_dict(self_dict, other_dict):
+    """Update values in self_dict.
+
+    Only keys that exist in ``self_dict`` will exist in the
+    returned dict. Only values that are not empty in ``other_dict``
+    will be used to replace values in ``self_dict``.
+
+    """
+    for k, v in other_dict.items():
+        if k in self_dict:
+            if isinstance(v, collections.abc.Mapping):
+                self_dict[k] = _deep_update_dict(self_dict[k], v)
+            else:
+                if v is not None and (v or isinstance(v, numbers.Number)):
+                    self_dict[k] = v
+    return self_dict
 
 
 class Parent(BaseModel):
     """Parent class on which to configure validation."""
 
-    model_config = ConfigDict(validate_assignment=True, extra='forbid')
+    model_config = ConfigDict(validate_assignment=True,
+                              extra='forbid',
+                              use_attribute_docstrings=True)
 
 
 # dataclass allows positional args, BaseModel does not.
@@ -39,12 +61,15 @@ class SpatialSchema(Parent):
     """Class for keeping track of spatial info."""
 
     bounding_box: BoundingBox
+    """Spatial extent [xmin, ymin, xmax, ymax]."""
     crs: str
+    """Coordinate Reference System."""
     crs_units: str
+    """Units of measure for coordinates in the CRS."""
 
 
 class ContactSchema(Parent):
-    """Class for keeping track of contact info."""
+    """Class for storing contact information of data author."""
 
     email: str = ''
     organization: str = ''
@@ -53,15 +78,13 @@ class ContactSchema(Parent):
 
 
 class LicenseSchema(Parent):
-    """Class for storing license info."""
+    """Class for storing data license information."""
 
-    # https://datapackage.org/profiles/2.0/dataresource.json
-    # This profile also includes `name`, described as:
-    # "MUST be an Open Definition license identifier",
-    # see http://licenses.opendefinition.org/"
-    # I don't think that's useful to us yet.
+    # Loosely follows https://datapackage.org/profiles/2.0/dataresource.json
     path: str = ''
+    """URL that describes the license."""
     title: str = ''
+    """Name of a license, such as one from http://licenses.opendefinition.org/"""
 
 
 class FieldSchema(Parent):
@@ -69,40 +92,127 @@ class FieldSchema(Parent):
 
     # https://datapackage.org/standard/table-schema/
     name: str
+    """The name used to uniquely identify the field."""
     type: str
+    """Datatype of the content of the field."""
     description: str = ''
+    """A description of the field."""
     title: str = ''
+    """A human-readable title for the field."""
     units: str = ''
+    """Unit of measurement for values in the field."""
 
 
 class TableSchema(Parent):
     """Class for metadata for tables."""
 
     # https://datapackage.org/standard/table-schema/
-    fields: List[FieldSchema]
+    fields: list[FieldSchema]
+    """A list of ``FieldSchema`` objects."""
     missingValues: list = Field(default_factory=list)
-    primaryKey: list = Field(default_factory=list)
-    foreignKeys: list = Field(default_factory=list)
+    """A list of values that represent missing data."""
+    primaryKey: list[str] = Field(default_factory=list)
+    """A field or list of fields that uniquely identifies each row in the table."""
+    foreignKeys: list[str] = Field(default_factory=list)
+    """A field or list of fields that can be used to join another table.
+
+    See https://datapackage.org/standard/table-schema/#foreignKeys
+    """
+
+    def _get_field(self, name):
+        """Get an attribute by its name property.
+
+        Args:
+            name (string): to match the value of the 'name' key in a dict
+
+        Returns:
+            tuple of (list index of the matching attribute, the attribute
+                dict)
+
+        Raises:
+            KeyError if no attributes exist in the resource or if the named
+                attribute does not exist.
+
+        """
+        if len(self.fields) == 0:
+            raise KeyError(
+                f'{self} has no fields')
+        for idx, field in enumerate(self.fields):
+            if field.name == name:
+                return idx, field
+        raise KeyError(
+            f'{self} has no field named {name}')
+
+    def set_field_description(self, name, title=None, description=None,
+                              units=None, type=None):
+        """Define metadata for a tabular field.
+
+        Args:
+            name (str): name and unique identifier of the field
+            title (str): title for the field
+            description (str): description of the field
+            units (str): unit of measurement for the field's values
+            type (str): datatype of values in the field
+
+        """
+        idx, field = self._get_field(name)
+
+        if title is not None:
+            field.title = title
+        if description is not None:
+            field.description = description
+        if units is not None:
+            field.units = units
+        if type is not None:
+            field.type = type
+
+        self.fields[idx] = field
+
+    def get_field_description(self, name):
+        """Get the attribute metadata for a field.
+
+        Args:
+            name (str): name and unique identifier of the field
+
+        Returns:
+            FieldSchema
+        """
+        idx, field = self._get_field(name)
+        return field
 
 
 class BandSchema(Parent):
     """Class for metadata for a raster band."""
 
     index: int
+    """The index of the band of a GDAL raster, starting at 1."""
     gdal_type: str
+    """The GDAL data type of the band."""
     numpy_type: str
+    """The numpy data type of the band."""
     nodata: Union[int, float, None]
+    """The pixel value that represents no data in the band."""
     description: str = ''
+    """A description of the band."""
     title: str = ''
+    """A human-readable title for the band."""
     units: str = ''
+    """Unit of measurement for the pixel values."""
+    gdal_metadata: dict = {}
+    """Metadata key:value pairs stored in the GDAL band object."""
 
 
 class RasterSchema(Parent):
     """Class for metadata for raster bands."""
 
-    bands: List[BandSchema]
-    pixel_size: list
+    bands: list[BandSchema]
+    """A list of ``BandSchema`` objects."""
+    pixel_size: tuple[Union[int, float], Union[int, float]]
+    """The width and height of a pixel measured in ``SpatialSchema.crs_units``."""
     raster_size: Union[dict, list]
+    """The width and height of the raster measured in number of pixels."""
+    gdal_metadata: dict = {}
+    """Metadata key:value pairs stored in the GDAL raster object."""
 
     def model_post_init(self, __context):
         # Migrate from previous model where we stored this as a list
@@ -111,13 +221,37 @@ class RasterSchema(Parent):
                                 'height': self.raster_size[1]}
 
 
+class LayerSchema(Parent):
+    """Class for metadata for a GDAL vector's layer."""
+
+    name: str
+    """The layer name."""
+    table: TableSchema = Field(default_factory=TableSchema)
+    """A ``models.TableSchema`` object for describing fields in a layer's table."""
+    gdal_metadata: dict = {}
+    """Metadata key:value pairs stored in the GDAL layer object."""
+    n_features: int
+    """Number of features in the layer."""
+
+
+class VectorSchema(Parent):
+
+    layers: list[LayerSchema]
+    """A list of layers in the vector.
+
+    Geometamaker currently only supports vectors with one layer.
+    """
+    gdal_metadata: dict = {}
+    """Metadata key:value pairs stored in the GDAL vector object."""
+
+
 class BaseMetadata(Parent):
     """A class for the things shared by Resource and Profile."""
 
-    # These default to None in order to facilitate the logic
-    # in ``replace`` where we only replace values that are not None.
-    contact: Union[ContactSchema, None] = Field(default_factory=ContactSchema)
-    license: Union[LicenseSchema, None] = Field(default_factory=LicenseSchema)
+    contact: ContactSchema = Field(default_factory=ContactSchema)
+    """Contact information for the data author."""
+    license: LicenseSchema = Field(default_factory=LicenseSchema)
+    """Data license information."""
 
     def set_contact(self, organization=None, individual_name=None,
                     position_name=None, email=None):
@@ -186,8 +320,8 @@ class BaseMetadata(Parent):
         """Replace attribute values with those from another instance.
 
         Only attributes that exist in ``self`` will exist in the
-        returned instance. Only attribute values that are not None will be used
-        to replace existing attribute values in ``self``.
+        returned instance. Only attribute values that are not empty
+        in ``other`` will be used to replace values in ``self``.
 
         Args:
             other (BaseMetadata)
@@ -200,9 +334,13 @@ class BaseMetadata(Parent):
 
         """
         if isinstance(other, BaseMetadata):
-            updated_dict = self.model_dump() | {
-                k: v for k, v in other.__dict__.items() if v is not None}
-            return self.__class__(**updated_dict)
+            updated_dict = _deep_update_dict(
+                self.model_dump(), other.model_dump())
+            obj = self.__class__(**updated_dict)
+            # Private attributes are not pydantic fields.
+            # They were excluded in model_dump so set them again
+            obj._would_overwrite = self._would_overwrite
+            return obj
         raise TypeError(f'{type(other)} is not an instance of BaseMetadata')
 
 
@@ -214,11 +352,6 @@ class Profile(BaseMetadata):
 
     """
 
-    # For a Profile, default these to None so that they do not replace
-    # values in a Resource
-    contact: Union[ContactSchema, None] = None
-    license: Union[LicenseSchema, None] = None
-
     @classmethod
     def load(cls, filepath):
         """Load metadata document from a yaml file.
@@ -246,7 +379,7 @@ class Profile(BaseMetadata):
             file.write(utils.yaml_dump(self.model_dump()))
 
 
-class Resource(BaseMetadata):
+class BaseResource(BaseMetadata):
     """Base class for metadata for a resource.
 
     https://datapackage.org/standard/data-resource/
@@ -259,43 +392,49 @@ class Resource(BaseMetadata):
     with which to complete later.
 
     """
-
-    # A version string we can use to identify geometamaker compliant documents
-    geometamaker_version: str = ''
+    _would_overwrite: bool = False
     metadata_path: str = ''
+    geometamaker_version: str = ''
+    """The version of geometamaker used to create this metadata resource."""
 
-    # These are populated geometamaker.describe()
+    # These are populated by geometamaker.describe()
     bytes: int = 0
-    encoding: str = ''
+    """File size of the resource in bytes."""
     format: str = ''
+    """File format of the resource."""
     uid: str = ''
+    """Unique identifier for the resource."""
     path: str = ''
+    """Path to the resource being described."""
     scheme: str = ''
+    """File protocol for opening the resource."""
     type: str = ''
+    """The type of resource being described."""
     last_modified: str = ''
-    # DataPackage includes `sources` as a list of source files
-    # with some amount of metadata for each item. For our
-    # use-case, I think a list of filenames is good enough.
-    sources: list = Field(default_factory=list)
+    """Last modified time of the file at ``path``."""
 
     # These are not populated by geometamaker.describe(),
     # and should have setters & getters
     citation: str = ''
+    """A citation for the resource."""
     description: str = ''
+    """A text description of the resource."""
     doi: str = ''
+    """A digital object identifier for the resource."""
     edition: str = ''
-    keywords: list = Field(default_factory=list)
+    """A string representing the edition, or version, of the resource."""
+    keywords: list[str] = Field(default_factory=list)
+    """A list of keywords that describe the subject-matter of the resource."""
     lineage: str = ''
-    placenames: list = Field(default_factory=list)
+    """A text description of how the resource was created."""
+    placenames: list[str] = Field(default_factory=list)
+    """A list of geographic places associated with the resource."""
     purpose: str = ''
+    """The author's stated purpose for the resource."""
     title: str = ''
+    """The title of the resource."""
     url: str = ''
-
-    def model_post_init(self, __context):
-        self.metadata_path = f'{self.path}.yml'
-        self.geometamaker_version: str = geometamaker.__version__
-        self.path = self.path.replace('\\', '/')
-        self.sources = [x.replace('\\', '/') for x in self.sources]
+    """A URL where the resource is available."""
 
     @classmethod
     def load(cls, filepath):
@@ -322,27 +461,29 @@ class Resource(BaseMetadata):
                        f'geometamaker.')
             raise ValueError(message)
 
-        deprecated_attrs = ['metadata_version', 'mediatype', 'name']
-        for attr in deprecated_attrs:
-            if attr in yaml_dict:
-                warnings.warn(
-                    f'"{attr}" exists in {filepath} but is no longer part of '
-                    f'the geometamaker specification. "{attr}" will be '
-                    f'removed from this document. In the future, presence '
-                    f' of "{attr}" will raise a ValidationError',
-                    category=FutureWarning)
-                del yaml_dict[attr]
-
-        # migrate from 'schema' to 'data_model', if needed.
-        if 'schema' in yaml_dict:
-            warnings.warn(
-                "'schema' has been replaced with 'data_model' as an attribute "
-                "name. In the future, the presence of a 'schema' attribute "
-                "will raise a ValidationError",
-                category=FutureWarning)
-            yaml_dict['data_model'] = yaml_dict['schema']
-            del yaml_dict['schema']
-        return cls(**yaml_dict)
+        try:
+            return cls(**yaml_dict)
+        except ValidationError as validation_error:
+            for e in validation_error.errors():
+                # Migrate vector metadata that pre-dates 'layers'
+                if e['type'] == 'missing' and e['loc'] == ('data_model', 'layers'):
+                    warnings.warn(
+                        "A vector 'data_model' must include 'layers'. "
+                        "In the future, the absence of a 'layers' attribute "
+                        "will raise a ValidationError",
+                        category=FutureWarning)
+                    # In the context of `describe`, these layer attributes will
+                    # be updated on the resource after this document is loaded.
+                    layer = {
+                        'name': '',
+                        'table': yaml_dict['data_model'],
+                        'n_features': yaml_dict['n_features']
+                    }
+                    del yaml_dict['data_model']
+                    del yaml_dict['n_features']
+                    yaml_dict['data_model'] = {'layers': [layer]}
+                    return cls(**yaml_dict)
+            raise validation_error
 
     def set_title(self, title):
         """Add a title for the dataset.
@@ -500,7 +641,7 @@ class Resource(BaseMetadata):
         """Get the url for the dataset."""
         return self.url
 
-    def write(self, workspace=None):
+    def write(self, workspace=None, backup=True):
         """Write datapackage yaml to disk.
 
         This creates sidecar files with '.yml'
@@ -515,6 +656,9 @@ class Resource(BaseMetadata):
                 to write files. They will still be named to match the source
                 filename. Use this option if the source data is not on the local
                 filesystem.
+            backup (bool): whether to write a backup of a pre-existing metadata
+                file before ovewriting it in cases where that file is not a valid
+                geometamaker document.
 
         """
         if workspace is None:
@@ -523,42 +667,63 @@ class Resource(BaseMetadata):
             target_path = os.path.join(
                 workspace, os.path.basename(self.metadata_path))
 
+        if self._would_overwrite and backup and os.path.exists(target_path):
+            backup_path = f'{target_path}.bak'
+            LOGGER.info(
+                f'Backing up existing metadata file to {backup_path}')
+            os.rename(target_path, backup_path)
+
         with open(target_path, 'w', encoding='utf-8') as file:
-            file.write(utils.yaml_dump(
-                self.model_dump(exclude=['metadata_path'])))
+            file.write(utils.yaml_dump(self._dump_for_write()))
+
+    def _dump_for_write(self):
+        return self.model_dump(exclude={'metadata_path'})
+
 
-    def to_string(self):
-        pass
+class Resource(BaseResource):
+    """
+    Metadata class for general-purpose resources.
+
+    This class extends `BaseResource` and provides metadata for a single file
+    or dataset, including encoding and source file references. It serves as a
+    base for more specific resource types (e.g., table, raster, vector,
+    archive) and is typically initialized by `describe()`.
+    """
+
+    encoding: str = ''
+    """File encoding of the resource."""
+    sources: list[str] = Field(default_factory=list)
+    """A list of files which comprise the dataset or resource."""
+
+    def model_post_init(self, __context):
+        self.metadata_path = self._default_metadata_path()
+        self.geometamaker_version: str = geometamaker.__version__
+        self.path = self.path.replace('\\', '/')
+        self.sources = [x.replace('\\', '/') for x in self.sources]
+
+    def _default_metadata_path(self):
+        return f'{self.path}.yml'
 
 
 class TableResource(Resource):
     """Class for metadata for a table resource."""
 
     data_model: TableSchema = Field(default_factory=TableSchema)
+    """A ``models.TableSchema`` object for describing fields."""
 
-    def _get_field(self, name):
-        """Get an attribute by its name property.
+    def _get_fields(self):
+        return self.data_model.fields
+
+    def get_field_description(self, name):
+        """Get the attribute metadata for a field.
 
         Args:
-            name (string): to match the value of the 'name' key in a dict
+            name (str): name and unique identifier of the field
 
         Returns:
-            tuple of (list index of the matching attribute, the attribute
-                dict)
-
-        Raises:
-            KeyError if no attributes exist in the resource or if the named
-                attribute does not exist.
-
+            FieldSchema
         """
-        if len(self.data_model.fields) == 0:
-            raise KeyError(
-                f'{self.data_model} has no fields')
-        for idx, field in enumerate(self.data_model.fields):
-            if field.name == name:
-                return idx, field
-        raise KeyError(
-            f'{self.data_model} has no field named {name}')
+        return self.data_model.get_field_description(name)
 
     def set_field_description(self, name, title=None, description=None,
                               units=None, type=None):
@@ -572,18 +737,53 @@ class TableResource(Resource):
             type (str): datatype of values in the field
 
         """
-        idx, field = self._get_field(name)
+        self.data_model.set_field_description(
+            name, title, description, units, type)
 
-        if title is not None:
-            field.title = title
-        if description is not None:
-            field.description = description
-        if units is not None:
-            field.units = units
-        if type is not None:
-            field.type = type
 
-        self.data_model.fields[idx] = field
+class ArchiveResource(Resource):
+    """Class for metadata for an archive resource."""
+
+    compression: str = ''
+    """The compression method used to create the archive."""
+
+
+class CollectionItemSchema(Parent):
+    """Class for metadata for collection items."""
+    path: str = ''
+    """Path to the resource being described."""
+    description: str = ''
+    """A text description of the resource."""
+    metadata: str = ''
+    """Path to metadata document describing resource"""
+
+
+class CollectionResource(BaseResource):
+    """Class for metadata for a collection resource."""
+
+    items: list[CollectionItemSchema] = Field(default_factory=list)
+    """Files in collection."""
+
+    def model_post_init(self, __context):
+        self.metadata_path = self._default_metadata_path()
+        self.geometamaker_version: str = geometamaker.__version__
+        self.path = self.path.replace('\\', '/')
+
+    def _default_metadata_path(self):
+        """Add -metadata tag"""
+        return f'{self.path}-metadata.yml'
+
+
+class VectorResource(Resource):
+    """Class for metadata for a vector resource."""
+
+    data_model: VectorSchema
+    """An object for describing vector properties and layers."""
+    spatial: SpatialSchema
+    """An object for describing spatial properties of a GDAL dataset."""
+
+    def _get_fields(self):
+        return self.data_model.layers[0].table.fields
 
     def get_field_description(self, name):
         """Get the attribute metadata for a field.
@@ -594,28 +794,31 @@ class TableResource(Resource):
         Returns:
             FieldSchema
         """
-        idx, field = self._get_field(name)
-        return field
-
-
-class ArchiveResource(Resource):
-    """Class for metadata for an archive resource."""
-
-    compression: str
+        return self.data_model.layers[0].table.get_field_description(name)
 
+    def set_field_description(self, name, title=None, description=None,
+                              units=None, type=None):
+        """Define metadata for a tabular field.
 
-class VectorResource(TableResource):
-    """Class for metadata for a vector resource."""
+        Args:
+            name (str): name and unique identifier of the field
+            title (str): title for the field
+            description (str): description of the field
+            units (str): unit of measurement for the field's values
+            type (str): datatype of values in the field
 
-    n_features: int
-    spatial: SpatialSchema
+        """
+        self.data_model.layers[0].table.set_field_description(
+            name, title, description, units, type)
 
 
 class RasterResource(Resource):
     """Class for metadata for a raster resource."""
 
     data_model: RasterSchema
+    """An object for describing raster properties and bands."""
     spatial: SpatialSchema
+    """An object for describing spatial properties of a GDAL dataset."""
 
     def set_band_description(self, band_number, title=None,
                              description=None, units=None):