openepd 1.4.0__tar.gz → 1.6.0__tar.gz

{openepd-1.4.0 → openepd-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: openepd
-Version: 1.4.0
+Version: 1.6.0
 Summary: Python library to work with OpenEPD format
 Home-page: https://github.com/cchangelabs/openepd
 License: Apache-2.0

{openepd-1.4.0 → openepd-1.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "openepd"
-version = "1.4.0"
+version = "1.6.0"
 license = "Apache-2.0"
 description = "Python library to work with OpenEPD format"
 authors = ["C-Change Labs <support@c-change-labs.com>"]
@@ -58,7 +58,7 @@ api_client = ["requests"]
 
 
 [tool.commitizen]
-version = "1.4.0"
+version = "1.6.0"
 bump_version = "bump: version $current_version → $new_version"
 update_changelog_on_bump = true
 pre_bump_hooks = []

{openepd-1.4.0 → openepd-1.6.0}/src/openepd/__version__.py

@@ -17,4 +17,4 @@
 #  Charles Pankow Foundation, Microsoft Sustainability Fund, Interface, MKA Foundation, and others.
 #  Find out more at www.BuildingTransparency.org
 #
-VERSION = "1.4.0"
+VERSION = "1.6.0"

{openepd-1.4.0 → openepd-1.6.0}/src/openepd/model/base.py

@@ -18,32 +18,62 @@
 #  Find out more at www.BuildingTransparency.org
 #
 import abc
+from enum import StrEnum
 import json
-from typing import Any, Optional, Type, TypeVar
+from typing import Any, Callable, Generic, Optional, Type, TypeVar
 
-import pydantic
+import pydantic as pyd
 from pydantic.generics import GenericModel
 
-AnySerializable = int | str | bool | float | list | dict | pydantic.BaseModel | None
+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 | pyd.BaseModel | None
 TAnySerializable = TypeVar("TAnySerializable", bound=AnySerializable)
 
+OPENEPD_VERSION_FIELD = "openepd_version"
+"""Field name for the openEPD format version."""
+
+
+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
+    """
+    ext = schema_dict.get("properties", {}).get("ext")
+    # move to bottom
+    if ext is not None:
+        del schema_dict["properties"]["ext"]
+        schema_dict["properties"]["ext"] = ext
+    return schema_dict
 
-class BaseOpenEpdSchema(pydantic.BaseModel):
+
+class BaseOpenEpdSchema(pyd.BaseModel):
     """Base class for all OpenEPD models."""
 
-    ext: dict[str, AnySerializable] | None = pydantic.Field(alias="ext", default=None)
+    ext: dict[str, AnySerializable] | None = pyd.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 json.loads(self.json(*args, **kwargs))
 
@@ -83,7 +113,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
@@ -129,12 +159,6 @@ class BaseOpenEpdGenericSchema(GenericModel, BaseOpenEpdSchema):
     pass
 
 
-class BaseOpenEpdSpec(BaseOpenEpdSchema):
-    """Base class for all OpenEPD specs."""
-
-    pass
-
-
 class OpenEpdExtension(BaseOpenEpdSchema, metaclass=abc.ABCMeta):
     """Base class for OpenEPD extension models."""
 
@@ -148,3 +172,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-1.4.0 → openepd-1.6.0}/src/openepd/model/common.py

@@ -17,6 +17,7 @@
 #  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
@@ -137,3 +138,18 @@ 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"

{openepd-1.4.0 → openepd-1.6.0}/src/openepd/model/epd.py

@@ -22,18 +22,31 @@ from typing import Annotated
 
 import pydantic as pyd
 
-from openepd.model.base import BaseOpenEpdSchema
+from openepd.model.base import BaseDocumentFactory, RootDocument
 from openepd.model.common import Amount, Ingredient, WithAltIdsMixin, WithAttachmentsMixin
 from openepd.model.lcia import Impacts, OutputFlowSet, ResourceUseSet
 from openepd.model.org import Org, Plant
 from openepd.model.pcr import Pcr
 from openepd.model.specs import Specs
 from openepd.model.standard import Standard
+from openepd.model.versioning import OpenEpdVersions, Version
 
 
-class Epd(WithAttachmentsMixin, WithAltIdsMixin, BaseOpenEpdSchema):
+class BaseEpd(RootDocument):
+    """
+    Base class for EPD documents.
+
+    This class should not be used directly.  Use Epd or EpdVx instead.
+    """
+
+    pass
+
+
+class EpdV0(WithAttachmentsMixin, WithAltIdsMixin, BaseEpd):
     """Represent an EPD."""
 
+    _FORMAT_VERSION = OpenEpdVersions.Version0.as_str()
+
     # TODO: Add validator for open-xpd-uuid on this field
     id: str | None = pyd.Field(
         description="The unique ID for this EPD.  To ensure global uniqueness, should be registered at "
@@ -41,10 +54,6 @@ class Epd(WithAttachmentsMixin, WithAltIdsMixin, BaseOpenEpdSchema):
         example="1u7zsed8",
         default=None,
     )
-    doctype: str = pyd.Field(
-        description='Describes the type and schema of the document. Must always always read "openEPD".',
-        default="OpenEPD",
-    )
     product_name: str | None = pyd.Field(
         max_length=200, description="The name of the product described by this EPD", example="Mix 12345AC"
     )
@@ -53,7 +62,7 @@ class Epd(WithAttachmentsMixin, WithAltIdsMixin, BaseOpenEpdSchema):
     )
     product_description: str | None = pyd.Field(
         max_length=2000,
-        description="1-paragraph description of product. " "Supports plain text or github flavored markdown.",
+        description="1-paragraph description of product. Supports plain text or github flavored markdown.",
     )
     # TODO: add product_alt_names? E.g. ILCD has a list of synonymous names
     product_classes: dict[str, str | list[str]] = pyd.Field(
@@ -234,28 +243,28 @@ class Epd(WithAttachmentsMixin, WithAltIdsMixin, BaseOpenEpdSchema):
     )
     lca_discussion: str | None = pyd.Field(
         max_length=20000,
-        description="""A rich text description containing information for experts reviewing the EPD contents. 
-    Text descriptions required by ISO 14025, ISO 21930, EN 15804,, relevant PCRs, or program instructions and which do not 
-    have specific openEPD fields should be entered here.  This field may be large, and may contain multiple sections 
+        description="""A rich text description containing information for experts reviewing the EPD contents.
+    Text descriptions required by ISO 14025, ISO 21930, EN 15804,, relevant PCRs, or program instructions and which do not
+    have specific openEPD fields should be entered here.  This field may be large, and may contain multiple sections
     separated by github flavored markdown formatting.""",
         example="""# Packaging
 
-    Information on product-specific packaging: type, composition and possible reuse of packaging materials (paper, 
-    strapping, pallets, foils, drums, etc.) shall be included in this Section. The EPD shall describe specific packaging 
-    scenario assumptions, including disposition pathways for each packaging material by reuse, recycling, or landfill 
+    Information on product-specific packaging: type, composition and possible reuse of packaging materials (paper,
+    strapping, pallets, foils, drums, etc.) shall be included in this Section. The EPD shall describe specific packaging
+    scenario assumptions, including disposition pathways for each packaging material by reuse, recycling, or landfill
     disposal based on packaging type.*
 
     # Product Installation
 
-    A description of the type of processing, machinery, tools, dust extraction equipment, auxiliary materials, etc. 
-    to be used during installation shall be included. Information on industrial and environmental protection may be 
-    included in this section. Any waste treatment included within the system boundary of installation waste should be 
+    A description of the type of processing, machinery, tools, dust extraction equipment, auxiliary materials, etc.
+    to be used during installation shall be included. Information on industrial and environmental protection may be
+    included in this section. Any waste treatment included within the system boundary of installation waste should be
     specified.
 
     # Use Conditions
 
-    Use-stage environmental impacts of flooring products during building operations depend on product cleaning assumptions. 
-    Information on cleaning frequency and cleaning products shall be provided based on the manufacturer’s recommendations. 
+    Use-stage environmental impacts of flooring products during building operations depend on product cleaning assumptions.
+    Information on cleaning frequency and cleaning products shall be provided based on the manufacturer’s recommendations.
     In the absence of primary data, cleaning assumptions shall be documented.
     """,
     )
@@ -278,3 +287,13 @@ class Epd(WithAttachmentsMixin, WithAltIdsMixin, BaseOpenEpdSchema):
         if v is None:
             return []
         return v
+
+
+Epd = EpdV0
+
+
+class EpdFactory(BaseDocumentFactory[BaseEpd]):
+    """Factory for EPD objects."""
+
+    DOCTYPE_CONSTRAINT = "openEPD"
+    VERSION_MAP: dict[Version, type[BaseEpd]] = {OpenEpdVersions.Version0: EpdV0}

openepd-1.6.0/src/openepd/model/factory.py

@@ -0,0 +1,48 @@
+#
+#  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.model.base import BaseDocumentFactory, OpenEpdDoctypes, RootDocument
+from openepd.model.epd import EpdFactory
+
+
+class DocumentFactory:
+    """A factory for creating documents regardless of the type."""
+
+    DOCTYPE_TO_FACTORY: dict[str, type[BaseDocumentFactory]] = {
+        OpenEpdDoctypes.Epd: EpdFactory,
+    }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> RootDocument:
+        """
+        Create a document from the dictionary.
+
+        Type of the document will be recognized from the `doctype` field.
+        :raise ValueError: if the document type is not specified or not supported.
+        """
+        doctype = data.get("doctype")
+        if doctype is None:
+            raise ValueError("The document type is not specified.")
+        factory = cls.DOCTYPE_TO_FACTORY.get(doctype)
+        if factory is None:
+            raise ValueError(
+                f"The document of type `{doctype}` is not supported. Supported documents are: "
+                + ", ".join(cls.DOCTYPE_TO_FACTORY.keys())
+            )
+        return factory.from_dict(data)

{openepd-1.4.0 → openepd-1.6.0}/src/openepd/model/org.py

@@ -25,8 +25,8 @@ from openepd.model.base import BaseOpenEpdSchema
 from openepd.model.common import Location, WithAltIdsMixin, WithAttachmentsMixin
 
 
-class Org(WithAttachmentsMixin, WithAltIdsMixin, BaseOpenEpdSchema):
-    """Represent an organization."""
+class OrgRef(BaseOpenEpdSchema):
+    """Represents Organisation with minimal data."""
 
     web_domain: str | None = pyd.Field(
         description="A web domain owned by organization. Typically is the org's home website address", default=None
@@ -37,12 +37,18 @@ class Org(WithAttachmentsMixin, WithAltIdsMixin, BaseOpenEpdSchema):
         example="C Change Labs",
         default=None,
     )
+
+
+class Org(WithAttachmentsMixin, WithAltIdsMixin, OrgRef):
+    """Represent an organization."""
+
     alt_names: Annotated[list[str], pyd.conlist(pyd.constr(max_length=200), max_items=255)] | None = pyd.Field(
         description="List of other names for organization",
         example=["C-Change Labs", "C-Change Labs inc."],
         default=None,
     )
     # TODO: NEW field, not in the spec
+
     owner: Optional["Org"] = pyd.Field(description="Organization that controls this organization", default=None)
     subsidiaries: Annotated[list[str], pyd.conlist(pyd.constr(max_length=200), max_items=255)] | None = pyd.Field(
         description="Organizations controlled by this organization",

openepd-1.6.0/src/openepd/model/specs/README.md

@@ -0,0 +1,19 @@
+# Material Extensions
+
+This package contains openEPD material extensions. They are used to represent the material properties of the openEPD 
+materials, and are a more dynamic, frequently changing part of the standard. 
+
+## Versioning
+
+Extensions are versioned separately from the openEPD standard or openEPD API. 
+
+Each material extension is named after the corresponding EC3 product class, and is located in the relevant place 
+in the specs tree. For example, `RebarSteel` is nested under `Steel`. 
+
+Extensions are versioned as Major.Minor, for example "2.4". 
+
+Rules: 
+1. Minor versions for the same major version should be backwards compatible.
+2. Major versions are not compatible between themselves. 
+3. Pydantic models representing versions are named in a pattern SpecNameV1, where 1 is major version and SpecName is
+   the name of the material extension.

{openepd-1.4.0 → openepd-1.6.0}/src/openepd/model/specs/__init__.py

@@ -17,13 +17,19 @@
 #  Charles Pankow Foundation, Microsoft Sustainability Fund, Interface, MKA Foundation, and others.
 #  Find out more at www.BuildingTransparency.org
 #
+
 import pydantic as pyd
 
 from openepd.model.base import BaseOpenEpdSchema
-from openepd.model.specs.concrete import CmuSpec
+from openepd.model.specs import concrete, steel
 
 
 class Specs(BaseOpenEpdSchema):
     """Material specific specs."""
 
-    cmu: CmuSpec | None = pyd.Field(default=None, description="Concrete Masonry Unit-specific (CMU) specs")
+    cmu: concrete.CmuSpec | None = pyd.Field(default=None, description="Concrete Masonry Unit-specific (CMU) specs")
+    CMU: concrete.CmuSpec | None = pyd.Field(default=None, description="Concrete Masonry Unit-specific (CMU) specs")
+    Steel: steel.SteelV1 | None = pyd.Field(default=None, title="SteelV1", description="Steel-specific specs")
+    Concrete: concrete.ConcreteV1 | None = pyd.Field(
+        default=None, title="ConcreteV1", description="Concrete-specific specs"
+    )

openepd-1.6.0/src/openepd/model/specs/base.py

@@ -0,0 +1,60 @@
+#
+#  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 typing import Any
+
+import pydantic as pyd
+
+from openepd.model.base import BaseOpenEpdSchema, Version
+from openepd.model.validation.common import validate_version_compatibility, validate_version_format
+from openepd.model.validation.numbers import QuantityValidator
+from openepd.model.versioning import WithExtVersionMixin
+
+
+class BaseOpenEpdSpec(BaseOpenEpdSchema):
+    """Base class for all OpenEPD specs."""
+
+    class Config:
+        use_enum_values = False  # we need to store enums as strings and not values
+
+
+class BaseOpenEpdHierarchicalSpec(BaseOpenEpdSpec, WithExtVersionMixin):
+    """Base class for new specs (hierarchical, versioned)."""
+
+    _QUANTITY_VALIDATOR: QuantityValidator | None = None
+
+    def __init__(self, **data: Any) -> None:
+        # ensure that all the concrete spec objects fail on creations if they dont have _EXT_VERSION declared to
+        # something meaningful
+        if not hasattr(self, "_EXT_VERSION") or self._EXT_VERSION is None:
+            raise ValueError(f"Class {self.__class__} must declare an extension version")
+        Version.parse_version(self._EXT_VERSION)  # validate format correctness
+        super().__init__(**{"ext_version": self._EXT_VERSION, **data})
+
+    _version_format_validator = pyd.validator("ext_version", allow_reuse=True, check_fields=False)(
+        validate_version_format
+    )
+    _version_major_match_validator = pyd.validator("ext_version", allow_reuse=True, check_fields=False)(
+        validate_version_compatibility("_EXT_VERSION")
+    )
+
+
+def setup_external_validators(quantity_validator: QuantityValidator):
+    """Set the implementation unit validator for specs."""
+    BaseOpenEpdHierarchicalSpec._QUANTITY_VALIDATOR = quantity_validator