openepd 4.5.0__py3-none-any.whl → 4.6.0__py3-none-any.whl

openepd/__version__.py

@@ -13,4 +13,4 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 #
-VERSION = "4.5.0"
+VERSION = "4.6.0"

openepd/model/declaration.py

@@ -0,0 +1,113 @@
+#
+#  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.
+#
+import abc
+import datetime
+
+from openepd.compat.pydantic import pyd
+from openepd.model.base import RootDocument
+from openepd.model.common import Amount
+from openepd.model.pcr import Pcr
+from openepd.model.standard import Standard
+
+
+class BaseDeclaration(RootDocument, abc.ABC):
+    """Base class for declaration-related documents (EPDs, Industry-wide EPDs, Generic Estimates)."""
+
+    # TODO: Add validator for open-xpd-uuid on this field
+    id: str | None = pyd.Field(
+        description="The unique ID for this document.  To ensure global uniqueness, should be registered at "
+        "open-xpd-uuid.cqd.io/register or a coordinating registry.",
+        example="1u7zsed8",
+        default=None,
+    )
+    date_of_issue: datetime.datetime | None = pyd.Field(
+        example=datetime.datetime(day=11, month=9, year=2019, tzinfo=datetime.timezone.utc),
+        description="Date the document was issued. This should be the first day on which the document is valid.",
+    )
+    valid_until: datetime.datetime | None = pyd.Field(
+        example=datetime.datetime(day=11, month=9, year=2028, tzinfo=datetime.timezone.utc),
+        description="Last date the document is valid on, including any extensions.",
+    )
+
+    declared_unit: Amount | None = pyd.Field(
+        description="SI declared unit for this document.  If a functional unit is "
+        "utilized, the declared unit shall refer to the amount of "
+        "product associated with the A1-A3 life cycle stage."
+    )
+    kg_per_declared_unit: Amount | None = pyd.Field(
+        default=None,
+        description="Mass of the product, in kilograms, per declared unit",
+        example=Amount(qty=12.5, unit="kg"),
+    )
+    compliance: list[Standard] = pyd.Field(
+        description="Standard(s) to which this document is compliant.", default_factory=list
+    )
+
+    # TODO: add product_alt_names? E.g. ILCD has a list of synonymous names
+    product_classes: dict[str, str | list[str]] = pyd.Field(
+        description="List of classifications, including Masterformat and UNSPC", default_factory=dict
+    )
+
+    language: str | None = pyd.Field(
+        min_length=2,
+        max_length=2,
+        strip_whitespace=True,
+        description="Language this document is captured in, as an ISO 639-1 code",
+        example="en",
+    )
+    private: bool = pyd.Field(
+        default=False,
+        description="This document's author does not wish the contents published. "
+        "Useful for draft, partial, or confidential declarations.  "
+        "How (or whether) privacy is implemented is up to the receiving system.  "
+        "Null is treated as false (public).  Private (draft) entries have a reduced "
+        "number of required fields, to allow for multiple systems to coordinate "
+        "incomplete EPDs.",
+    )
+
+    pcr: Pcr | None = pyd.Field(
+        description="JSON object for product category rules. Should point to the "
+        "most-specific PCR that applies; the PCR entry should point to any "
+        "parent PCR.",
+        default=None,
+    )
+    lca_discussion: str | None = pyd.Field(
+        max_length=20000,
+        description="""A rich text description containing information for experts reviewing the document 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
+    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
+    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.
+    In the absence of primary data, cleaning assumptions shall be documented.
+    """,
+    )

openepd/model/epd.py

@@ -13,129 +13,33 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 #
-import datetime
 from typing import Annotated
 
 from openepd.compat.pydantic import pyd
-from openepd.model.base import BaseDocumentFactory, OpenEpdDoctypes, RootDocument
+from openepd.model.base import BaseDocumentFactory, OpenEpdDoctypes
 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.declaration import BaseDeclaration
+from openepd.model.lcia import WithLciaMixin
+from openepd.model.org import Org, OrgRef, Plant
 from openepd.model.specs import Specs
-from openepd.model.standard import Standard
 from openepd.model.versioning import OpenEpdVersions, Version
 
+MANUFACTURER_DESCRIPTION = (
+    'JSON object for declaring Org. Sometimes called the "Declaration Holder" or "Declaration Owner".'
+)
+DEVELOPER_DESCRIPTION = "The organization responsible for the underlying LCA (and subsequent summarization as EPD)."
+PROGRAM_OPERATOR_DESCRIPTION = "JSON object for program operator Org"
+THIRD_PARTY_VERIFIER_DESCRIPTION = "JSON object for Org that performed a critical review of the EPD data"
 
-class BaseDeclaration(RootDocument):
-    """
-    Base class for EPD documents.
 
-    This class should not be used directly.  Use Epd or EpdVx instead.
+class EpdPreviewV0(WithAttachmentsMixin, WithAltIdsMixin, BaseDeclaration, title="EPD (Preview)"):
     """
+    EPD preview, used in API list responses and where there is no need for a full object.
 
-    id: str | None = pyd.Field(
-        description="The unique ID for this EPD.  To ensure global uniqueness, should be registered at "
-        "open-xpd-uuid.cqd.io/register or a coordinating registry.",
-        example="1u7zsed8",
-        default=None,
-    )
-    date_of_issue: datetime.datetime | None = pyd.Field(
-        example=datetime.datetime(day=11, month=9, year=2019, tzinfo=datetime.timezone.utc),
-        description="Date the EPD was issued. This should be the first day on which the EPD is valid.",
-    )
-    valid_until: datetime.datetime | None = pyd.Field(
-        example=datetime.datetime(day=11, month=9, year=2028, tzinfo=datetime.timezone.utc),
-        description="Last date the EPD is valid on, including any extensions.",
-    )
-
-    declared_unit: Amount | None = pyd.Field(
-        description="SI declared unit for this EPD.  If a functional unit is "
-        "utilized, the declared unit shall refer to the amount of "
-        "product associated with the A1-A3 life cycle stage."
-    )
-    kg_per_declared_unit: Amount | None = pyd.Field(
-        default=None,
-        description="Mass of the product, in kilograms, per declared unit",
-        example=Amount(qty=12.5, unit="kg"),
-    )
-    compliance: list[Standard] = pyd.Field(
-        description="Standard(s) to which this declaration is compliant.", default_factory=list
-    )
-
-    # TODO: add product_alt_names? E.g. ILCD has a list of synonymous names
-    product_classes: dict[str, str | list[str]] = pyd.Field(
-        description="List of classifications, including Masterformat and UNSPC", default_factory=dict
-    )
-
-    language: str | None = pyd.Field(
-        min_length=2,
-        max_length=2,
-        strip_whitespace=True,
-        description="Language this EPD is captured in, as an ISO 639-1 code",
-        example="en",
-    )
-    private: bool = pyd.Field(
-        default=False,
-        description="This document's author does not wish the contents published. "
-        "Useful for draft, partial, or confidential declarations.  "
-        "How (or whether) privacy is implemented is up to the receiving system.  "
-        "Null is treated as false (public).  Private (draft) entries have a reduced "
-        "number of required fields, to allow for multiple systems to coordinate "
-        "incomplete EPDs.",
-    )
-    impacts: Impacts | None = pyd.Field(
-        description="List of environmental impacts, compiled per one of the standard Impact Assessment methods"
-    )
-    resource_uses: ResourceUseSet | None = pyd.Field(
-        description="Set of Resource Use Indicators, over various LCA scopes"
-    )
-    output_flows: OutputFlowSet | None = pyd.Field(
-        description="Set of Waste and Output Flow indicators which describe the waste categories "
-        "and other material output flows derived from the LCI."
-    )
-
-    pcr: Pcr | None = pyd.Field(
-        description="JSON object for product category rules. Should point to the "
-        "most-specific PCR that applies; the PCR entry should point to any "
-        "parent PCR.",
-        default=None,
-    )
-    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
-    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
-    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
-    specified.
-
-    # Use Conditions
+    Excludes LCIA data.
 
-    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.
-    """,
-    )
-
-
-class EpdV0(WithAttachmentsMixin, WithAltIdsMixin, BaseDeclaration):
-    """Represent an EPD."""
-
-    _FORMAT_VERSION = OpenEpdVersions.Version0.as_str()
+    """
 
-    # TODO: Add validator for open-xpd-uuid on this field
     product_name: str | None = pyd.Field(
         max_length=200, description="The name of the product described by this EPD", example="Mix 12345AC", default=None
     )
@@ -162,12 +66,9 @@ class EpdV0(WithAttachmentsMixin, WithAltIdsMixin, BaseDeclaration):
         description="Link to data object on original registrar's site",
         example="https://epd-online.com/EmbeddedEpdList/Download/6029",
     )
-    manufacturer: Org | None = pyd.Field(
-        description="JSON object for declaring Org. Sometimes called the "
-        '"Declaration Holder" or "Declaration Owner".'
-    )
-    epd_developer: Org | None = pyd.Field(
-        description="The organization responsible for the underlying LCA (and subsequent summarization as EPD).",
+    manufacturer: OrgRef | None = pyd.Field(description=MANUFACTURER_DESCRIPTION)
+    epd_developer: OrgRef | None = pyd.Field(
+        description=DEVELOPER_DESCRIPTION,
         default=None,
     )
     epd_developer_email: pyd.EmailStr | None = pyd.Field(
@@ -181,16 +82,14 @@ class EpdV0(WithAttachmentsMixin, WithAltIdsMixin, BaseDeclaration):
         description="List of object(s) for one or more plant(s) that this declaration applies to.",
         default_factory=list,
     )
-    program_operator: Org | None = pyd.Field(description="JSON object for program operator Org")
+    program_operator: OrgRef | None = pyd.Field(description=PROGRAM_OPERATOR_DESCRIPTION)
     program_operator_doc_id: str | None = pyd.Field(
         max_length=200, description="Document identifier from Program Operator.", example="123-456.789/b"
     )
     program_operator_version: str | None = pyd.Field(
         max_length=200, description="Document version number from Program Operator.", example="4.3.0"
     )
-    third_party_verifier: Org | None = pyd.Field(
-        description="JSON object for Org that performed a critical review of the EPD data"
-    )
+    third_party_verifier: OrgRef | None = pyd.Field(description=THIRD_PARTY_VERIFIER_DESCRIPTION)
     third_party_verification_url: pyd.AnyUrl | None = pyd.Field(
         description="Optional link to a verification statement.",
         example="https://we-verify-epds.com/en/letters/123-456.789b.pdf",
@@ -268,6 +167,15 @@ class EpdV0(WithAttachmentsMixin, WithAltIdsMixin, BaseDeclaration):
         default_factory=list,
     )
 
+
+EpdPreview = EpdPreviewV0
+
+
+class EpdV0(WithLciaMixin, EpdPreviewV0, title="EPD (Full)"):
+    """Represent an EPD."""
+
+    _FORMAT_VERSION = OpenEpdVersions.Version0.as_str()
+
     @classmethod
     def get_asset_type(cls) -> str | None:
         """Return the asset type of this class (see BaseOpenEpdSchema.get_asset_type for details)."""
@@ -291,6 +199,22 @@ class EpdV0(WithAttachmentsMixin, WithAltIdsMixin, BaseDeclaration):
 Epd = EpdV0
 
 
+class EpdWithDepsV0(EpdV0, title="EPD (with Dependencies)"):
+    """
+    Expanded version of the EPD.
+
+    Contains related entities - orgs - with full fields, to support object matching in implementations.
+    """
+
+    manufacturer: Org | None = pyd.Field(description=MANUFACTURER_DESCRIPTION)
+    epd_developer: Org | None = pyd.Field(description=DEVELOPER_DESCRIPTION, default=None)
+    program_operator: Org | None = pyd.Field(description=PROGRAM_OPERATOR_DESCRIPTION)
+    third_party_verifier: Org | None = pyd.Field(description=THIRD_PARTY_VERIFIER_DESCRIPTION)
+
+
+EpdWithDeps = EpdWithDepsV0
+
+
 class EpdFactory(BaseDocumentFactory[BaseDeclaration]):
     """Factory for EPD objects."""
 

openepd/model/generic_estimate.py

@@ -18,9 +18,10 @@ from enum import StrEnum
 from openepd.compat.pydantic import pyd
 from openepd.model.base import BaseDocumentFactory, OpenEpdDoctypes
 from openepd.model.common import WithAltIdsMixin, WithAttachmentsMixin
-from openepd.model.epd import BaseDeclaration
+from openepd.model.declaration import BaseDeclaration
 from openepd.model.geography import Geography
-from openepd.model.org import Org
+from openepd.model.lcia import WithLciaMixin
+from openepd.model.org import Org, OrgRef
 from openepd.model.versioning import OpenEpdVersions, Version
 
 
@@ -45,27 +46,30 @@ class LicenseTerms(StrEnum):
     """
 
 
-class GenericEstimateV0(WithAttachmentsMixin, WithAltIdsMixin, BaseDeclaration):
-    """Represent a Generic Estimate."""
+class GenericEstimatePreviewV0(WithAttachmentsMixin, BaseDeclaration, title="Generic Estimate (preview)"):
+    """
+    Generic Estimate preview, used in API list responses and where there is no need for a full object.
 
-    _FORMAT_VERSION = OpenEpdVersions.Version0.as_str()
+    Excludes LCIA data.
+    """
 
     doctype: str = pyd.Field(
         description='Describes the type and schema of the document. Must always be "openGenericEstimate"',
         default="openGenericEstimate",
     )
 
-    name: str | None = pyd.Field(max_length=200, description="", default=None)
+    name: str | None = pyd.Field(max_length=200, description="Name of the generic estimate", default=None)
+
     description: str | None = pyd.Field(
         max_length=2000,
         description="1-paragraph description of the Generic Estimate. Supports plain text or github flavored markdown.",
     )
 
-    publisher: Org | None = pyd.Field(description="Organization that published the LCA results.")
+    publisher: OrgRef | None = pyd.Field(description="Organization that published the LCA results.")
     reviewer_email: pyd.EmailStr | None = pyd.Field(
         description="Email address of the third party verifier", example="john.doe@example.com", default=None
     )
-    reviewer: Org | None = pyd.Field(description="Org that performed a critical review of the LCA.")
+    reviewer: OrgRef | None = pyd.Field(description="Org that performed a critical review of the LCA.")
     license_terms: LicenseTerms | None = pyd.Field(description="The license terms for use of the data.")
     geography: list[Geography] | None = pyd.Field(
         "Jurisdiction(s) in which the LCA result is applicable.  An empty array, or absent properties, implies global applicability."
@@ -75,9 +79,38 @@ class GenericEstimateV0(WithAttachmentsMixin, WithAltIdsMixin, BaseDeclaration):
     )
 
 
+GenericEstimatePreview = GenericEstimatePreviewV0
+
+
+class GenericEstimateV0(GenericEstimatePreviewV0, WithLciaMixin, WithAltIdsMixin, title="Generic Estimate (Full)"):
+    """
+    Represent a full Generic Estimate object.
+
+    This is considered the most complete valid openEPD object for GenericEstimate. In addition to it, several related
+    models are defined, either with fewer fields (to be used in APIs for list requests) or with more relaxed structure
+    to support related entities matching.
+    """
+
+    _FORMAT_VERSION = OpenEpdVersions.Version0.as_str()
+
+
 GenericEstimate = GenericEstimateV0
 
 
+class GenericEstimateWithDepsV0(GenericEstimateV0, title="Generic Estimate (with Dependencies)"):
+    """
+    Expanded version of the GenericEstimate.
+
+    Contains related entities - orgs - with full fields, to support object matching in implementations.
+    """
+
+    publisher: Org | None = pyd.Field(description="Organization that published the LCA results.")
+    reviewer: Org | None = pyd.Field(description="Org that performed a critical review of the LCA.")
+
+
+GenericEstimateWithDeps = GenericEstimateWithDepsV0
+
+
 class GenericEstimateFactory(BaseDocumentFactory[GenericEstimate]):
     """Factory for EPD objects."""