openepd 4.13.0__tar.gz → 5.0.0__tar.gz

{openepd-4.13.0 → openepd-5.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: openepd
-Version: 4.13.0
+Version: 5.0.0
 Summary: Python library to work with OpenEPD format
 Home-page: https://github.com/cchangelabs/openepd
 License: Apache-2.0
@@ -19,6 +19,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Provides-Extra: api-client
 Requires-Dist: email-validator (>=1.3.1)
 Requires-Dist: idna (>=3.7)
+Requires-Dist: open-xpd-uuid (>=0.2.1,<0.3.0)
 Requires-Dist: pydantic (>=1.10,<3.0)
 Requires-Dist: requests (>=2.0) ; extra == "api-client"
 Project-URL: Repository, https://github.com/cchangelabs/openepd

{openepd-4.13.0 → openepd-5.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "openepd"
-version = "4.13.0"
+version = "5.0.0"
 license = "Apache-2.0"
 description = "Python library to work with OpenEPD format"
 authors = ["C-Change Labs <support@c-change-labs.com>"]
@@ -25,6 +25,7 @@ pydantic = ">=1.10,<3.0"
 email-validator = ">=1.3.1"
 requests = { version = ">=2.0", optional = true }
 idna = ">=3.7"
+open-xpd-uuid = "~=0.2.1"
 
 # Optional dependencies
 # lxml = { version = "~=4.9.2", optional = true }
@@ -37,7 +38,6 @@ pytest-subtests = "~=0.4"
 pytest-cov = "~=4.0"
 teamcity-messages = ">=1.31"
 wheel = "~=0.40.0"
-open-xpd-uuid = "~=0.2.1"
 
 # Dev tools
 black = "~=24.3"

openepd-5.0.0/src/openepd/__version__.py

@@ -0,0 +1,16 @@
+#
+#  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.
+#
+VERSION = "5.0.0"

{openepd-4.13.0 → openepd-5.0.0}/src/openepd/model/common.py

@@ -42,7 +42,7 @@ class Measurement(BaseOpenEpdSchema):
     """A scientific value with units and uncertainty."""
 
     mean: float = pyd.Field(description="Mean (expected) value of the measurement")
-    unit: str = pyd.Field(description="Measurement unit")
+    unit: str | None = pyd.Field(description="Measurement unit")
     rsd: pyd.PositiveFloat | None = pyd.Field(
         description="Relative standard deviation, i.e. standard_deviation/mean", default=None
     )

{openepd-4.13.0 → openepd-5.0.0}/src/openepd/model/declaration.py

@@ -24,7 +24,7 @@ from openepd.model.org import Org
 from openepd.model.pcr import Pcr
 from openepd.model.standard import Standard
 from openepd.model.validation.common import ReferenceStr
-from openepd.model.validation.quantity import AmountMass
+from openepd.model.validation.quantity import AmountGWP, AmountMass
 
 DEVELOPER_DESCRIPTION = "The organization responsible for the underlying LCA (and subsequent summarization as EPD)."
 PROGRAM_OPERATOR_DESCRIPTION = "JSON object for program operator Org"
@@ -136,19 +136,19 @@ class BaseDeclaration(RootDocument, abc.ABC):
         description="Link to data object on original registrar's site",
         example="https://epd-online.com/EmbeddedEpdList/Download/6029",
     )
-    kg_C_per_declared_unit: AmountMass | None = pyd.Field(
+    kg_C_per_declared_unit: AmountGWP | None = pyd.Field(
         default=None,
         description="Mass of elemental carbon, per declared unit, contained in the product itself at the manufacturing "
         "facility gate.  Used (among other things) to check a carbon balance or calculate incineration "
         "emissions.  The source of carbon (e.g. biogenic) is not relevant in this field.",
-        example=Amount(qty=8.76, unit="kg"),
+        example=Amount(qty=8.76, unit="kgCO2e"),
     )
-    kg_C_biogenic_per_declared_unit: AmountMass | None = pyd.Field(
+    kg_C_biogenic_per_declared_unit: AmountGWP | None = pyd.Field(
         default=None,
         description="Mass of elemental carbon from biogenic sources, per declared unit, contained in the product "
         "itself at the manufacturing facility gate.  It may be presumed that any biogenic carbon content "
         "has been accounted for as -44/12 kgCO2e per kg C in stages A1-A3, per EN15804 and ISO 21930.",
-        example=Amount(qty=8.76, unit="kg"),
+        example=Amount(qty=8.76, unit="kgCO2e"),
     )
     product_service_life_years: float | None = pyd.Field(
         gt=0.0009,

{openepd-4.13.0 → openepd-5.0.0}/src/openepd/model/lcia.py

@@ -14,10 +14,12 @@
 #  limitations under the License.
 #
 from enum import StrEnum
+from typing import Any, ClassVar
 
 from openepd.compat.pydantic import pyd
 from openepd.model.base import BaseOpenEpdSchema
 from openepd.model.common import Measurement
+from openepd.model.validation.quantity import ExternalValidationConfig
 
 
 class EolScenario(BaseOpenEpdSchema):
@@ -70,6 +72,8 @@ class ScopeSet(BaseOpenEpdSchema):
     The 'unit' field must be consistent across all scopes in a single scopeset.
     """
 
+    allowed_units: ClassVar[str | tuple[str, ...] | None] = None
+
     A1A2A3: Measurement | None = pyd.Field(
         description="Sum of A1..A3",
         default=None,
@@ -194,17 +198,56 @@ class ScopeSet(BaseOpenEpdSchema):
         description="Potential net benefits from reuse, recycling, and/or energy recovery beyond the system boundary.",
     )
 
+    @pyd.root_validator
+    def _unit_validator(cls, values: dict[str, Any]) -> dict[str, Any]:
+        all_units = set()
+
+        for k, v in values.items():
+            if isinstance(v, Measurement):
+                all_units.add(v.unit)
+
+        # units should be the same across all measurements (textually)
+        if len(all_units) > 1:
+            raise ValueError("All scopes and measurements should be expressed in the same unit.")
+
+        # can correctly validate unit
+        if cls.allowed_units is not None and len(all_units) == 1 and ExternalValidationConfig.QUANTITY_VALIDATOR:
+            unit = next(iter(all_units))
+            allowed_units = cls.allowed_units if isinstance(cls.allowed_units, tuple) else (cls.allowed_units,)
 
-class ScopesetByNameBase(BaseOpenEpdSchema):
+            matched_unit = False
+            for allowed_unit in allowed_units:
+                try:
+                    ExternalValidationConfig.QUANTITY_VALIDATOR.validate_same_dimensionality(unit, allowed_unit)
+                    matched_unit = True
+                except ValueError:
+                    ...
+            if not matched_unit:
+                raise ValueError(
+                    f"'{', '.join(allowed_units)}' is only allowed unit for this scopeset. Provided '{unit}'"
+                )
+
+        return values
+
+
+class ScopesetByNameBase(BaseOpenEpdSchema, extra="allow"):
     """Base class for the data structures presented as typed name:scopeset mapping ."""
 
     def get_scopeset_names(self) -> list[str]:
         """
         Get the names of scopesets which have been set by model (not defaults).
 
-        :return: set of names, for example ['gwp', 'odp]
+        :return: set of names, for example ['gwp', 'odp']
         """
-        return [self.__fields__[f].alias or f for f in self.__fields_set__ if f not in ("ext",)]
+        result = []
+        for f in self.__fields_set__:
+            if f in ("ext",):
+                continue
+            field = self.__fields__.get(f)
+            # field can be explicitly specified, or can be an unknown impact covered by extra='allow'
+            result.append(field.alias if field and field.alias else f)
+
+        return result
 
     def get_scopeset_by_name(self, name: str) -> ScopeSet | None:
         """
@@ -213,39 +256,133 @@ class ScopesetByNameBase(BaseOpenEpdSchema):
         :param name: The name of the scopeset.
         :return: A scopeset if found, None otherwise
         """
+        # check known impacts first
         for f_name, f in self.__fields__.items():
             if f.alias == name:
                 return getattr(self, f_name)
             if f_name == name:
                 return getattr(self, f_name)
+        # probably unknown impact, coming from 'extra' fields
+        return getattr(self, name, None)
+
+    @pyd.root_validator(skip_on_failure=True)
+    def _extra_scopeset_validator(cls, values: dict[str, Any]) -> dict[str, Any]:
+        for f in values:
+            # only interested in validating the extra fields
+            if f in cls.__fields__:
+                continue
+
+            # extra impact of an unknown type - engage validation of ScopeSet
+            extra_scopeset = values.get(f)
+            match extra_scopeset:
+                case ScopeSet():
+                    continue
+                case dict():
+                    values[f] = ScopeSet(**extra_scopeset)
+                case _:
+                    raise ValueError(f"{f} must be a ScopeSet schema")
+
+        return values
+
+
+class ScopeSetGwp(ScopeSet):
+    """ScopeSet measured in kgCO2e."""
+
+    allowed_units = "kgCO2e"
+
+
+class ScopeSetOdp(ScopeSet):
+    """ScopeSet measured in kgCFC11e."""
+
+    allowed_units = "kgCFC11e"
+
+
+class ScopeSetAp(ScopeSet):
+    """ScopeSet measured in kgSO2e."""
+
+    allowed_units = ("kgSO2e", "molHe")
+
+
+class ScopeSetEpNe(ScopeSet):
+    """ScopeSet measured in kgNe."""
+
+    allowed_units = "kgNe"
+
+
+class ScopeSetPocp(ScopeSet):
+    """ScopeSet measured in kgO3e."""
+
+    allowed_units = ("kgO3e", "kgNMVOCe")
+
+
+class ScopeSetEpFresh(ScopeSet):
+    """ScopeSet measured in kgPO4e."""
+
+    allowed_units = "kgPO4e"
+
+
+class ScopeSetEpTerr(ScopeSet):
+    """ScopeSet measured in molNe."""
 
-        return None
+    allowed_units = "molNe"
+
+
+class ScopeSetIrp(ScopeSet):
+    """ScopeSet measured in kilo Becquerel equivalent of u235."""
+
+    allowed_units = "kBqU235e"
+
+
+class ScopeSetCTUh(ScopeSet):
+    """ScopeSet measured in CTUh."""
+
+    allowed_units = "CTUh"
+
+
+class ScopeSetM3Aware(ScopeSet):
+    """ScopeSet measured in m3AWARE Water consumption by AWARE method."""
+
+    allowed_units = "m3AWARE"
+
+
+class ScopeSetCTUe(ScopeSet):
+    """ScopeSet measured in CTUe."""
+
+    allowed_units = "CTUe"
+
+
+class ScopeSetDiseaseIncidence(ScopeSet):
+    """ScopeSet measuring disease incidence measured in AnnualPerCapita (cases)."""
+
+    allowed_units = "AnnualPerCapita"
 
 
 class ImpactSet(ScopesetByNameBase):
     """A set of impacts, such as GWP, ODP, AP, EP, POCP, EP-marine, EP-terrestrial, EP-freshwater, etc."""
 
-    gwp: ScopeSet | None = pyd.Field(
+    gwp: ScopeSetGwp | None = pyd.Field(
         default=None,
         description="GWP100, calculated per IPCC guidelines.  If any CO2 removals are "
         "part of this figure, the gwp-fossil, gwp-bioganic, gwp-luluc, an "
         "gwp-nonCO2 fields are required, as is "
         "kg_C_biogenic_per_declared_unit.",
     )
-    odp: ScopeSet | None = pyd.Field(default=None, description="Ozone Depletion Potential")
-    ap: ScopeSet | None = pyd.Field(default=None, description="Acidification Potential")
-    ep: ScopeSet | None = pyd.Field(
+    odp: ScopeSetOdp | None = pyd.Field(default=None, description="Ozone Depletion Potential")
+    ap: ScopeSetAp | None = pyd.Field(default=None, description="Acidification Potential")
+    ep: ScopeSetEpNe | None = pyd.Field(
         default=None, description="Eutrophication Potential in Marine Ecosystems. Has the same meaning as ep-marine."
     )
-    pocp: ScopeSet | None = pyd.Field(default=None, description="Photochemical Smog (Ozone) creation potential")
-    ep_marine: ScopeSet | None = pyd.Field(alias="ep-marine", default=None, description="Has the same meaning as 'ep'")
-    ep_fresh: ScopeSet | None = pyd.Field(
+    pocp: ScopeSetPocp | None = pyd.Field(default=None, description="Photochemical Smog (Ozone) creation potential")
+    ep_marine: ScopeSetEpNe | None = pyd.Field(
+        alias="ep-marine", default=None, description="Has the same meaning as 'ep'"
+    )
+    ep_fresh: ScopeSetEpFresh | None = pyd.Field(
         alias="ep-fresh", default=None, description="Eutrophication Potential in Freshwater Ecosystems"
     )
-    ep_terr: ScopeSet | None = pyd.Field(
+    ep_terr: ScopeSetEpTerr | None = pyd.Field(
         alias="ep-terr", default=None, description="Eutrophication Potential in Terrestrial Ecosystems"
     )
-    gwp_biogenic: ScopeSet | None = pyd.Field(
+    gwp_biogenic: ScopeSetGwp | None = pyd.Field(
         alias="gwp-biogenic",
         default=None,
         description="Net GWP from removals of atmospheric CO2 into biomass and  emissions of CO2 from biomass sources. "
@@ -254,7 +391,7 @@ class ImpactSet(ScopesetByNameBase):
         "space (similar biome).  They must not have been sold, committed, or credited to any other "
         "product.  Harvesting from native forests is handled under GWP_luluc for EN15804.",
     )
-    gwp_luluc: ScopeSet | None = pyd.Field(
+    gwp_luluc: ScopeSetGwp | None = pyd.Field(
         alias="gwp-luluc",
         default=None,
         description="Climate change effects related to land use and land use change, for example biogenic carbon "
@@ -262,17 +399,49 @@ class ImpactSet(ScopesetByNameBase):
         "emissions). All related emissions for native forests are included under this category. "
         "Uptake for native forests is set to 0 kgCO2 for EN15804.",
     )
-    gwp_nonCO2: ScopeSet | None = pyd.Field(
+    gwp_nonCO2: ScopeSetGwp | None = pyd.Field(
         alias="gwp-nonCO2",
         default=None,
         description="GWP from non-CO2, non-fossil sources, such as livestock-sourced CH4 and agricultural N2O.",
     )
-    gwp_fossil: ScopeSet | None = pyd.Field(
+    gwp_fossil: ScopeSetGwp | None = pyd.Field(
         alias="gwp-fossil",
         default=None,
         description="Climate change effects due to greenhouse gas emissions originating from the oxidation or "
         "reduction of fossil fuels or materials containing fossil carbon. [Source: EN15804]",
     )
+    WDP: ScopeSetM3Aware | None = pyd.Field(
+        default=None,
+        description="Deprivation-weighted water consumption, calculated by the AWARE method "
+        "(https://wulca-waterlca.org/aware/what-is-aware)",
+    )
+    PM: ScopeSetDiseaseIncidence | None = pyd.Field(
+        default=None,
+        description="Potential incidence of disease due to particulate matter emissions.",
+    )
+    IRP: ScopeSetIrp | None = pyd.Field(
+        default=None,
+        description="Potential ionizing radiation effect on human health, relative to U235.",
+    )
+    ETP_fw: ScopeSetCTUe | None = pyd.Field(
+        alias="ETP-fw",
+        default=None,
+        description="Ecotoxicity in freshwater, in potential Comparative Toxic Unit for ecosystems.",
+    )
+    HTP_c: ScopeSetCTUh | None = pyd.Field(
+        alias="HTP-c",
+        default=None,
+        description="Human toxicity, cancer effects in potential Comparative Toxic Units for humans.",
+    )
+    HTP_nc: ScopeSetCTUh | None = pyd.Field(
+        alias="HTP-nc",
+        default=None,
+        description="Human toxicity, noncancer effects in potential Comparative Toxic Units for humans.",
+    )
+    SQP: ScopeSet | None = pyd.Field(
+        default=None,
+        description="Land use related impacts / Soil quality, in potential soil quality parameters.",
+    )
 
 
 class LCIAMethod(StrEnum):

{openepd-4.13.0 → openepd-5.0.0}/src/openepd/model/specs/base.py

@@ -18,7 +18,7 @@ from typing import Any
 from openepd.compat.pydantic import pyd
 from openepd.model.base import BaseOpenEpdSchema, Version
 from openepd.model.validation.common import validate_version_compatibility, validate_version_format
-from openepd.model.validation.quantity import QuantityValidator
+from openepd.model.validation.quantity import ExternalValidationConfig, QuantityValidator
 from openepd.model.versioning import WithExtVersionMixin
 
 
@@ -32,9 +32,6 @@ class BaseOpenEpdSpec(BaseOpenEpdSchema):
 class BaseOpenEpdHierarchicalSpec(BaseOpenEpdSpec, WithExtVersionMixin):
     """Base class for new specs (hierarchical, versioned)."""
 
-    # external validator for quantities (e.g. length, mass, etc.) which should be setup by the user of the library.
-    _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
@@ -53,4 +50,4 @@ class BaseOpenEpdHierarchicalSpec(BaseOpenEpdSpec, WithExtVersionMixin):
 
 def setup_external_validators(quantity_validator: QuantityValidator):
     """Set the implementation unit validator for specs."""
-    BaseOpenEpdHierarchicalSpec._QUANTITY_VALIDATOR = quantity_validator
+    ExternalValidationConfig.QUANTITY_VALIDATOR = quantity_validator

{openepd-4.13.0 → openepd-5.0.0}/src/openepd/model/validation/quantity.py

@@ -33,6 +33,19 @@ class QuantityValidator(ABC):
     and set it with `set_unit_validator` function.
     """
 
+    @abstractmethod
+    def validate_same_dimensionality(self, unit: str | None, dimensionality_unit: str) -> None:
+        """
+        Validate that a given unit ('kg') has the same dimesnionality as provided dimensionality_unit ('g').
+
+        :param unit: unit to validate, not quantity
+        :param dimensionality_unit: unit to check against
+        :raise:
+            ValueError if dimensionality is different
+        :return: None
+        """
+        pass
+
     @abstractmethod
     def validate_unit_correctness(self, value: str, dimensionality: str) -> None:
         """
@@ -79,12 +92,23 @@ class QuantityValidator(ABC):
         pass
 
 
+class ExternalValidationConfig:
+    """
+    Configuration holder for external validator.
+
+    Since openEPD library does not provide any facility for working with quantities/units, users should do this
+    by implementing the protocol for this validator and setting it with setup_external_validators function.
+    """
+
+    QUANTITY_VALIDATOR: ClassVar[QuantityValidator | None] = None
+
+
 def validate_unit_factory(dimensionality: OpenEPDUnit | str) -> "QuantityValidatorType":
     """Create validator for quantity field to check unit matching."""
 
     def validator(cls: "type[BaseOpenEpdHierarchicalSpec]", value: str) -> str:
-        if hasattr(cls, "_QUANTITY_VALIDATOR") and cls._QUANTITY_VALIDATOR is not None:
-            cls._QUANTITY_VALIDATOR.validate_unit_correctness(value, dimensionality)
+        if ExternalValidationConfig.QUANTITY_VALIDATOR is not None:
+            ExternalValidationConfig.QUANTITY_VALIDATOR.validate_unit_correctness(value, dimensionality)
         return value
 
     return validator
@@ -94,8 +118,8 @@ def validate_quantity_ge_factory(min_value: str) -> "QuantityValidatorType":
     """Create validator to check that quantity is greater than or equal to min_value."""
 
     def validator(cls: "type[BaseOpenEpdHierarchicalSpec]", value: str) -> str:
-        if hasattr(cls, "_QUANTITY_VALIDATOR") and cls._QUANTITY_VALIDATOR is not None:
-            cls._QUANTITY_VALIDATOR.validate_quantity_greater_or_equal(value, min_value)
+        if ExternalValidationConfig.QUANTITY_VALIDATOR is not None:
+            ExternalValidationConfig.QUANTITY_VALIDATOR.validate_quantity_greater_or_equal(value, min_value)
         return value
 
     return validator
@@ -105,8 +129,8 @@ def validate_quantity_le_factory(max_value: str) -> "QuantityValidatorType":
     """Create validator to check that quantity is less than or equal to max_value."""
 
     def validator(cls: "type[BaseOpenEpdHierarchicalSpec]", value: str) -> str:
-        if hasattr(cls, "_QUANTITY_VALIDATOR") and cls._QUANTITY_VALIDATOR is not None:
-            cls._QUANTITY_VALIDATOR.validate_quantity_less_or_equal(value, max_value)
+        if ExternalValidationConfig.QUANTITY_VALIDATOR is not None:
+            ExternalValidationConfig.QUANTITY_VALIDATOR.validate_quantity_less_or_equal(value, max_value)
         return value
 
     return validator
@@ -116,9 +140,8 @@ def validate_quantity_for_new_validator(max_value: str) -> Callable:
     """Create validator to check that quantity is less than or equal to max_value."""
 
     def validator(value: str) -> str:
-        cls = BaseOpenEpdHierarchicalSpec
-        if hasattr(cls, "_QUANTITY_VALIDATOR") and cls._QUANTITY_VALIDATOR is not None:
-            cls._QUANTITY_VALIDATOR.validate_quantity_less_or_equal(value, max_value)
+        if ExternalValidationConfig.QUANTITY_VALIDATOR is not None:
+            ExternalValidationConfig.QUANTITY_VALIDATOR.validate_quantity_less_or_equal(value, max_value)
         return value
 
     return validator
@@ -154,6 +177,12 @@ class AmountMass(AmountWithDimensionality):
     dimensionality_unit = OpenEPDUnit.kg
 
 
+class AmountGWP(AmountWithDimensionality):
+    """Amount of Global Warming Potential, measured in kgCO2e."""
+
+    dimensionality_unit = OpenEPDUnit.kg_co2
+
+
 class QuantityStr(str):
     """
     Quantity string type.

openepd-4.13.0/src/openepd/__version__.py

@@ -1,16 +0,0 @@
-#
-#  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.
-#
-VERSION = "4.13.0"