openepd 2.0.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

openepd/compat/pydantic.py

@@ -0,0 +1,29 @@
+#
+#  Copyright 2024 by C Change Labs Inc. www.c-change-labs.com
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+#
+#  This software was developed with support from the Skanska USA,
+#  Charles Pankow Foundation, Microsoft Sustainability Fund, Interface, MKA Foundation, and others.
+#  Find out more at www.BuildingTransparency.org
+#
+try:
+    from pydantic import v1 as pyd  # type: ignore
+    from pydantic.v1 import generics as pyd_generics  # type: ignore
+except ImportError:
+    import pydantic as pyd  # type: ignore[no-redef]
+    from pydantic import generics as pyd_generics  # type: ignore[no-redef]
+
+pydantic = pyd
+
+__all__ = ["pyd", "pydantic", "pyd_generics"]

openepd/model/__init__.py

@@ -1,5 +1,5 @@
 #
-#  Copyright 2023 by C Change Labs Inc. www.c-change-labs.com
+#  Copyright 2024 by C Change Labs Inc. www.c-change-labs.com
 #
 #  Licensed under the Apache License, Version 2.0 (the "License");
 #  you may not use this file except in compliance with the License.

openepd/model/base.py

@@ -1,5 +1,5 @@
 #
-#  Copyright 2023 by C Change Labs Inc. www.c-change-labs.com
+#  Copyright 2024 by C Change Labs Inc. www.c-change-labs.com
 #
 #  Licensed under the Apache License, Version 2.0 (the "License");
 #  you may not use this file except in compliance with the License.
@@ -18,32 +18,71 @@
 #  Find out more at www.BuildingTransparency.org
 #
 import abc
-from typing import Any, Optional, Type, TypeVar
+from enum import StrEnum
+import json
+from typing import Any, Callable, Generic, Optional, Type, TypeAlias, TypeVar
 
-import pydantic
+from openepd.compat.pydantic import pyd, pyd_generics
+from openepd.model.validation.common import validate_version_compatibility, validate_version_format
+from openepd.model.versioning import OpenEpdVersions, Version
 
-AnySerializable = int | str | bool | float | list | dict | pydantic.BaseModel | None
+AnySerializable: TypeAlias = int | str | bool | float | list | dict | pyd.BaseModel | None
 TAnySerializable = TypeVar("TAnySerializable", bound=AnySerializable)
 
+OPENEPD_VERSION_FIELD = "openepd_version"
+"""Field name for the openEPD format version."""
 
-class BaseOpenEpdSchema(pydantic.BaseModel):
+OPENAPI_SCHEMA_SERVICE_PROPERTIES = ["ext_version", "ext"]
+"""OpenAPI properties which should be moved to the bottom of specification if present. """
+
+
+class OpenEpdDoctypes(StrEnum):
+    """Enum of supported openEPD document types."""
+
+    Epd = "openEPD"
+
+
+def modify_pydantic_schema(schema_dict: dict, cls: type) -> dict:
+    """
+    Modify the schema dictionary to add the required fields.
+
+    :param schema_dict: schema dictionary
+    :param cls: class for which the schema was generated
+    :return: modified schema dictionary
+    """
+    for prop_name in OPENAPI_SCHEMA_SERVICE_PROPERTIES:
+        prop = schema_dict.get("properties", {}).get(prop_name, None)
+        # move to bottom
+        if prop is not None:
+            del schema_dict["properties"][prop_name]
+            schema_dict["properties"][prop_name] = prop
+
+    return schema_dict
+
+
+class BaseOpenEpdSchema(pyd.BaseModel):
     """Base class for all OpenEPD models."""
 
-    model_config = pydantic.ConfigDict(validate_assignment=False, populate_by_name=True, use_enum_values=True)
+    ext: dict[str, AnySerializable] | None = pyd.Field(alias="ext", default=None)
 
-    ext: dict[str, AnySerializable] | None = pydantic.Field(alias="ext", default=None)
+    class Config:
+        allow_mutation = True
+        validate_assignment = False
+        allow_population_by_field_name = True
+        use_enum_values = True
+        schema_extra: Callable | dict = modify_pydantic_schema
 
     def to_serializable(self, *args, **kwargs) -> dict[str, Any]:
         """
         Return a serializable dict representation of the DTO.
 
-        It expects the same arguments as the pydantic.BaseModel.json() method.
+        It expects the same arguments as the pyd.BaseModel.json() method.
         """
-        return self.model_dump(mode="json", *args, **kwargs)
+        return json.loads(self.json(*args, **kwargs))
 
     def has_values(self) -> bool:
         """Return True if the model has any values."""
-        return len(self.model_dump(mode="python", exclude_unset=True, exclude_none=True)) > 0
+        return len(self.dict(exclude_unset=True, exclude_none=True)) > 0
 
     def set_ext(self, ext: "OpenEpdExtension") -> None:
         """Set the extension field."""
@@ -77,7 +116,7 @@ class BaseOpenEpdSchema(pydantic.BaseModel):
         value = self.get_ext_field(key, default)
         if value is None:
             return None  # type: ignore
-        if issubclass(target_type, pydantic.BaseModel) and isinstance(value, dict):
+        if issubclass(target_type, pyd.BaseModel) and isinstance(value, dict):
             return target_type.construct(**value)  # type: ignore
         elif isinstance(value, target_type):
             return value
@@ -98,10 +137,10 @@ class BaseOpenEpdSchema(pydantic.BaseModel):
 
         Both property name and aliases are checked.
         """
-        if field_name in cls.model_fields:
+        if field_name in cls.__fields__:
             return True
         else:
-            for x in cls.model_fields.values():
+            for x in cls.__fields__.values():
                 if x.alias == field_name:
                     return True
         return False
@@ -117,8 +156,8 @@ class BaseOpenEpdSchema(pydantic.BaseModel):
         return None
 
 
-class BaseOpenEpdSpec(BaseOpenEpdSchema):
-    """Base class for all OpenEPD specs."""
+class BaseOpenEpdGenericSchema(pyd_generics.GenericModel, BaseOpenEpdSchema):
+    """Base class for all OpenEPD generic models."""
 
     pass
 
@@ -136,3 +175,63 @@ class OpenEpdExtension(BaseOpenEpdSchema, metaclass=abc.ABCMeta):
 TOpenEpdExtension = TypeVar("TOpenEpdExtension", bound=OpenEpdExtension)
 TOpenEpdObject = TypeVar("TOpenEpdObject", bound=BaseOpenEpdSchema)
 TOpenEpdObjectClass = TypeVar("TOpenEpdObjectClass", bound=Type[BaseOpenEpdSchema])
+
+
+class RootDocument(abc.ABC, BaseOpenEpdSchema):
+    """Base class for all objects representing openEPD root element. E.g. Epd, IndustryEpd, GenericEstimate, etc."""
+
+    _FORMAT_VERSION: str
+    """Version of this document format. Must be defined in the concrete class."""
+
+    doctype: str = pyd.Field(
+        description='Describes the type and schema of the document. Must always always read "openEPD".',
+        default="OpenEPD",
+    )
+    openepd_version: str = pyd.Field(
+        description="Version of the document format, related to /doctype",
+        default=OpenEpdVersions.get_current().as_str(),
+    )
+
+    _version_format_validator = pyd.validator(OPENEPD_VERSION_FIELD, allow_reuse=True, check_fields=False)(
+        validate_version_format
+    )
+    _version_major_match_validator = pyd.validator(OPENEPD_VERSION_FIELD, allow_reuse=True, check_fields=False)(
+        validate_version_compatibility("_FORMAT_VERSION")
+    )
+
+
+TRootDocument = TypeVar("TRootDocument", bound=RootDocument)
+
+
+class BaseDocumentFactory(Generic[TRootDocument]):
+    """
+    Base class for document factories.
+
+    Extend it to create a factory for a specific document type e.g. for industry epd, epd, etc.
+    """
+
+    DOCTYPE_CONSTRAINT: str = ""
+    VERSION_MAP: dict[Version, type[TRootDocument]] = {}
+
+    @classmethod
+    def from_dict(cls, data: dict) -> TRootDocument:
+        """Create a document from a dictionary."""
+        doctype: str | None = data.get("doctype")
+        if doctype is None:
+            raise ValueError("Doctype not found in the data.")
+        if doctype.lower() != cls.DOCTYPE_CONSTRAINT.lower():
+            raise ValueError(
+                f"Document type {doctype} not supported. This factory supports {cls.DOCTYPE_CONSTRAINT} only."
+            )
+        version = Version.parse_version(data.get(OPENEPD_VERSION_FIELD, ""))
+        for x, doc_cls in cls.VERSION_MAP.items():
+            if x.major == version.major:
+                if version.minor <= x.minor:
+                    return doc_cls(**data)
+                else:
+                    raise ValueError(
+                        f"Unsupported version: {version}. "
+                        f"The highest supported version from branch {x.major}.x is {x}"
+                    )
+        supported_versions = ", ".join(f"{v.major}.x" for v in cls.VERSION_MAP.keys())
+        raise ValueError(f"Version {version} is not supported. Supported versions are: {supported_versions}")

openepd/model/category.py

@@ -0,0 +1,39 @@
+#
+#  Copyright 2024 by C Change Labs Inc. www.c-change-labs.com
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+#
+#  This software was developed with support from the Skanska USA,
+#  Charles Pankow Foundation, Microsoft Sustainability Fund, Interface, MKA Foundation, and others.
+#  Find out more at www.BuildingTransparency.org
+#
+from openepd.compat.pydantic import pyd
+from openepd.model.base import BaseOpenEpdSchema
+from openepd.model.common import Amount
+
+
+class Category(BaseOpenEpdSchema):
+    """DTO for Category model, recursive."""
+
+    id: str = pyd.Field(description="Category short ID (readable unique string)")
+    name: str = pyd.Field(description="Category display name (user-friendly)")
+    short_name: str = pyd.Field(description="Category short user-friendly name")
+    openepd_hierarchical_name: str = pyd.Field(
+        "Special form of hierarchical category ID where the >> is hierarchy separator"
+    )
+    masterformat: str | None = pyd.Field(description="Default category code in Masterformat")
+    description: str | None = pyd.Field(description="Category verbose description")
+    declared_unit: Amount | None = pyd.Field(description="Declared unit of category, for example 1 kg")
+    subcategories: list["Category"] = pyd.Field(
+        description="List of subcategories. This makes categories tree-like structure"
+    )

openepd/model/common.py

@@ -1,5 +1,5 @@
 #
-#  Copyright 2023 by C Change Labs Inc. www.c-change-labs.com
+#  Copyright 2024 by C Change Labs Inc. www.c-change-labs.com
 #
 #  Licensed under the Apache License, Version 2.0 (the "License");
 #  you may not use this file except in compliance with the License.
@@ -17,11 +17,10 @@
 #  Charles Pankow Foundation, Microsoft Sustainability Fund, Interface, MKA Foundation, and others.
 #  Find out more at www.BuildingTransparency.org
 #
+from enum import StrEnum
 from typing import Annotated, Any
 
-import pydantic as pyd
-from pydantic import BaseModel, model_validator
-
+from openepd.compat.pydantic import pyd
 from openepd.model.base import BaseOpenEpdSchema
 
 
@@ -29,13 +28,9 @@ class Amount(BaseOpenEpdSchema):
     """A value-and-unit pairing for amounts that do not have an uncertainty."""
 
     qty: float | None = pyd.Field(description="How much of this in the amount.", default=None)
-    unit: str | None = pyd.Field(
-        description="Which unit.  SI units are preferred.",
-        default=None,
-        json_schema_extra=dict(example="kg"),
-    )
+    unit: str | None = pyd.Field(description="Which unit.  SI units are preferred.", example="kg", default=None)
 
-    @model_validator(mode="before")
+    @pyd.root_validator
     def check_qty_or_unit(cls, values: dict[str, Any]):
         """Ensure that qty or unit is provided."""
         if values["qty"] is None and values["unit"] is None:
@@ -80,8 +75,8 @@ class Ingredient(BaseOpenEpdSchema):
 class LatLng(BaseOpenEpdSchema):
     """A latitude and longitude."""
 
-    lat: float = pyd.Field(description="Latitude", json_schema_extra=dict(example=47.6062))
-    lng: float = pyd.Field(description="Longitude", json_schema_extra=dict(example=-122.3321))
+    lat: float = pyd.Field(description="Latitude", example=47.6062)
+    lng: float = pyd.Field(description="Longitude", example=-122.3321)
 
 
 class Location(BaseOpenEpdSchema):
@@ -96,18 +91,16 @@ class Location(BaseOpenEpdSchema):
     )
 
 
-class WithAttachmentsMixin(BaseModel):
+class WithAttachmentsMixin(pyd.BaseModel):
     """Mixin for objects that can have attachments."""
 
     attachments: dict[Annotated[str, pyd.Field(max_length=200)], pyd.AnyUrl] | None = pyd.Field(
         description="Dict of URLs relevant to this entry",
-        default=None,
-        json_schema_extra={
-            "example": {
-                "Contact Us": "https://www.c-change-labs.com/en/contact-us/",
-                "LinkedIn": "https://www.linkedin.com/company/c-change-labs/",
-            }
+        example={
+            "Contact Us": "https://www.c-change-labs.com/en/contact-us/",
+            "LinkedIn": "https://www.linkedin.com/company/c-change-labs/",
         },
+        default=None,
     )
 
     def set_attachment(self, name: str, url: str):
@@ -122,17 +115,15 @@ class WithAttachmentsMixin(BaseModel):
             self.set_attachment(name, url)
 
 
-class WithAltIdsMixin(BaseModel):
+class WithAltIdsMixin(pyd.BaseModel):
     """Mixin for objects that can have alt_ids."""
 
     alt_ids: dict[Annotated[str, pyd.Field(max_length=200)], str] | None = pyd.Field(
         description="Dict identifiers for this entry.",
+        example={
+            "oekobau.dat": "bdda4364-451f-4df2-a68b-5912469ee4c9",
+        },
         default=None,
-        json_schema_extra=dict(
-            example={
-                "oekobau.dat": "bdda4364-451f-4df2-a68b-5912469ee4c9",
-            }
-        ),
     )
 
     def set_alt_id(self, domain_name: str, value: str):
@@ -145,3 +136,20 @@ class WithAltIdsMixin(BaseModel):
         """Set an alt_id if value is not None."""
         if value is not None:
             self.set_alt_id(domain_name, value)
+
+
+class OpenEPDUnit(StrEnum):
+    """OpenEPD allowed units."""
+
+    kg = "kg"
+    m2 = "m2"
+    m = "m"
+    M2_RSI = "m2 * RSI"
+    MJ = "MJ"
+    t_km = "t * km"
+    MPa = "MPa"
+    item = "item"
+    W = "W"
+    use = "use"
+    degree_c = "°C"
+    kg_co2 = "kgCO2e"