openepd 7.5.0__py3-none-any.whl → 7.7.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 = "7.5.0"
+VERSION = "7.7.0"

openepd/m49/const.py

@@ -695,6 +695,8 @@ REGION_VERBOSE_NAME_TO_M49 = {
     "Polynesia": "061",
 }
 
+REGION_VERBOSE_NAME_TO_M49_LOWER = {k.lower(): v for k, v in REGION_VERBOSE_NAME_TO_M49.items()}
+
 M49_TO_REGION_VERBOSE_NAME = {
     M49_CODE_WORLD: "World",
     M49_CODE_AFRICA: "Africa",
@@ -769,7 +771,7 @@ COUNTRY_VERBOSE_NAME_TO_M49 = {
     "Colombia": "170",
     "Comoros": "174",
     "Congo": "178",
-    "Congo (Democratic Republic of the)": "180",
+    "Congo (Democratic Republic of the Congo)": "180",
     "Costa Rica": "188",
     "Croatia": "191",
     "Cuba": "192",
@@ -905,6 +907,7 @@ COUNTRY_VERBOSE_NAME_TO_M49 = {
     "Trinidad and Tobago": "780",
     "Tunisia": "788",
     "Türkiye": "792",
+    "Turkey": "792",
     "Turkmenistan": "795",
     "Tuvalu": "798",
     "Uganda": "800",
@@ -913,6 +916,8 @@ COUNTRY_VERBOSE_NAME_TO_M49 = {
     "United Kingdom of Great Britain and Northern Ireland": "826",
     "United Republic of Tanzania": "834",
     "United States of America": "840",
+    "United States": "840",
+    "USA": "840",
     "Uruguay": "858",
     "Uzbekistan": "860",
     "Vanuatu": "548",
@@ -923,6 +928,8 @@ COUNTRY_VERBOSE_NAME_TO_M49 = {
     "Zimbabwe": "716",
 }
 
+COUNTRY_VERBOSE_NAME_TO_M49_LOWER = {k.lower(): v for k, v in COUNTRY_VERBOSE_NAME_TO_M49.items()}
+
 M49_TO_COUNTRY_VERBOSE_NAME = {
     "004": "Afghanistan",
     "008": "Albania",

openepd/m49/utils.py

@@ -14,6 +14,7 @@
 #  limitations under the License.
 #
 __all__ = [
+    "is_iso_code",
     "is_m49_code",
     "iso_to_m49",
     "m49_to_iso",
@@ -25,14 +26,14 @@ __all__ = [
 from collections.abc import Collection
 
 from openepd.m49.const import (
-    COUNTRY_VERBOSE_NAME_TO_M49,
+    COUNTRY_VERBOSE_NAME_TO_M49_LOWER,
     ISO3166_ALPHA2_TO_M49,
     M49_AREAS,
     M49_TO_COUNTRY_VERBOSE_NAME,
     M49_TO_ISO3166_ALPHA2,
     M49_TO_REGION_VERBOSE_NAME,
     OPENEPD_SPECIAL_REGIONS,
-    REGION_VERBOSE_NAME_TO_M49,
+    REGION_VERBOSE_NAME_TO_M49_LOWER,
 )
 
 
@@ -99,7 +100,9 @@ def region_and_country_names_to_m49(regions: Collection[str]) -> set[str]:
 
     result = set()
     for name in regions:
-        m49_code = REGION_VERBOSE_NAME_TO_M49.get(name.title()) or COUNTRY_VERBOSE_NAME_TO_M49.get(name.title())
+        m49_code = REGION_VERBOSE_NAME_TO_M49_LOWER.get(name.lower()) or COUNTRY_VERBOSE_NAME_TO_M49_LOWER.get(
+            name.lower()
+        )
         if not m49_code:
             msg = f"Region or country name '{name}' not found in M49 region codes."
             raise ValueError(msg)
@@ -162,7 +165,7 @@ def openepd_to_m49(regions: Collection[str]) -> set[str]:
     return result
 
 
-def m49_to_openepd(regions: list[str]) -> set[str]:
+def m49_to_openepd(regions: Collection[str]) -> set[str]:
     """
     Convert M49 region codes to OpenEPD geography definitions.
 
@@ -203,4 +206,22 @@ def is_m49_code(to_check: str) -> bool:
     :param to_check: any string
     :return: `True` if passed string is M49 code, `False` otherwise
     """
+    if not to_check:
+        return False
+    if len(to_check) != 3 or not to_check.isdigit():
+        return False
     return to_check in M49_AREAS or to_check in M49_TO_ISO3166_ALPHA2
+
+
+def is_iso_code(to_check: str) -> bool:
+    """
+    Check if passed string is ISO3166 alpha2 code.
+
+    :param to_check: any string
+    :return: `True` if passed string is ISO3166 alpha2 code, `False` otherwise
+    """
+    if not to_check:
+        return False
+    if len(to_check) != 2:
+        return False
+    return to_check.upper() in ISO3166_ALPHA2_TO_M49

openepd/model/base.py

@@ -16,8 +16,7 @@
 import abc
 from collections.abc import Callable
 from enum import StrEnum
-import json
-from typing import Any, ClassVar, Generic, Optional, TypeAlias, TypeVar
+from typing import Any, ClassVar, Generic, Literal, NotRequired, Optional, Self, TypeAlias, TypedDict, TypeVar, Unpack
 
 from cqd import open_xpd_uuid  # type:ignore[import-untyped]
 import pydantic
@@ -63,6 +62,17 @@ def modify_pydantic_schema(schema_dict: dict, cls: type) -> dict:
     return schema_dict
 
 
+class SerializingArgs(TypedDict):
+    include: NotRequired[set[int] | set[str] | dict[int, Any] | dict[str, Any] | None]
+    exclude: NotRequired[set[int] | set[str] | dict[int, Any] | dict[str, Any] | None]
+    by_alias: NotRequired[bool]
+    exclude_unset: NotRequired[bool]
+    exclude_defaults: NotRequired[bool]
+    exclude_none: NotRequired[bool]
+    round_trip: NotRequired[bool]
+    warnings: NotRequired[bool]
+
+
 class BaseOpenEpdSchema(pydantic.BaseModel):
     """Base class for all OpenEPD models."""
 
@@ -73,17 +83,56 @@ class BaseOpenEpdSchema(pydantic.BaseModel):
         use_enum_values=True,
     )
 
-    def to_serializable(self, *args, **kwargs) -> dict[str, Any]:
+    def to_serializable(
+        self, mode: Literal["json", "python"] | str = "json", **kwargs: Unpack[SerializingArgs]
+    ) -> dict[str, Any]:
         """
         Return a serializable dict representation of the DTO.
 
         It expects the same arguments as the pydantic.BaseModel.model_dump_json() method.
         """
-        return json.loads(self.model_dump_json(*args, **kwargs))
+        kwargs.setdefault("exclude_none", True)
+        kwargs.setdefault("exclude_unset", True)
+        kwargs.setdefault("by_alias", True)
+        return self.model_dump(mode=mode, **kwargs)
+
+    def to_json(self, indent: int = 0, **kwargs: Unpack[SerializingArgs]):
+        """
+        Return a JSON string representation of the DTO.
+
+        It expects the same arguments as the pydantic.BaseModel.model_dump_json() method.
+        """
+        kwargs.setdefault("exclude_none", True)
+        kwargs.setdefault("exclude_unset", True)
+        kwargs.setdefault("by_alias", True)
+        return self.model_dump_json(indent=indent, **kwargs)
+
+    def to_dict(self, **kwargs: Unpack[SerializingArgs]) -> dict[str, Any]:
+        """
+        Return a dictionary representation of the DTO.
+
+        The main difference with `to_serializable` is that it doesn't convert all native python types
+        (e.g. datetime won't be converted into string) into JSON-compatible types.
 
-    def has_values(self) -> bool:
+        Method expects the same kwargs as the pydantic.BaseModel.model_dump() method.
+        """
+        return self.to_serializable(mode="python", **kwargs)
+
+    def has_values(self, exclude_fields: set[str] | None = None) -> bool:
         """Return True if the model has any values."""
-        return len(self.model_dump(exclude_unset=True, exclude_none=True)) > 0
+        if isinstance(self, RootDocument) and exclude_fields is None:
+            exclude_fields = {"doctype", "openepd_version"}
+        return len(self.model_dump(exclude_unset=True, exclude_none=True, exclude=exclude_fields)) > 0
+
+    def revalidate(self, strict: bool | None = None) -> Self:
+        """
+        Re-run validation against current model and return a new validated instance.
+
+        Note: This method returns a validated _COPY_ of the object.
+
+        :param strict: If True, will raise an error if any field is missing or has an invalid value.
+        """
+        return self.model_validate(self.to_dict(), strict=strict)
 
     def set_ext(self, ext: "OpenEpdExtension") -> None:
         """Set the extension field."""
@@ -197,6 +246,15 @@ class RootDocument(abc.ABC, BaseOpenEpdSchema):
         default=OpenEpdVersions.get_current().as_str(),
     )
 
+    def __init__(self, **data: Any) -> None:
+        super().__init__(**data)
+        if not hasattr(self, "_FORMAT_VERSION"):
+            msg = f"RootDocument subclass {self.__class__.__name__} must define _FORMAT_VERSION class variable."
+            raise ValueError(msg)
+        if "openepd_version" not in self.model_fields_set:
+            self.openepd_version = self._FORMAT_VERSION
+        self.doctype = self.__class__.model_fields["doctype"].default  # type: ignore[assignment]
+
     @pydantic.field_validator(OPENEPD_VERSION_FIELD)
     def version_format_validator(cls, value: str) -> str:
         """Validate the correctness of version format."""

openepd/model/lcia.py

@@ -13,11 +13,14 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 #
+from collections.abc import Generator
 from enum import StrEnum
-from typing import Any, ClassVar, Self
+from typing import Any, ClassVar, Self, cast
 
 import pydantic
-from pydantic import ConfigDict
+from pydantic.annotated_handlers import GetJsonSchemaHandler
+from pydantic.json_schema import GenerateJsonSchema
+from pydantic_core import CoreSchema
 
 from openepd.model.base import BaseOpenEpdSchema
 from openepd.model.common import Measurement
@@ -206,7 +209,7 @@ class ScopeSet(BaseOpenEpdSchema):
     def _unit_validator(self) -> Self:
         all_units = set()
 
-        for k in self.model_fields:
+        for k in self.__class__.model_fields:
             v = getattr(self, k, None)
             if isinstance(v, Measurement):
                 all_units.add(v.unit)
@@ -246,22 +249,91 @@ class ScopeSet(BaseOpenEpdSchema):
 class ScopesetByNameBase(BaseOpenEpdSchema, extra="allow"):
     """Base class for the data structures presented as typed name:scopeset mapping ."""
 
-    def get_scopeset_names(self) -> list[str]:
+    def get_scopeset_names(self, exclude_none: bool = False, only_standard: bool = False) -> list[str]:
         """
         Get the names of scopesets which have been set by model (not defaults).
 
+        :param exclude_none: If True, exclude scopesets with None values.
+        :param only_standard: If True, include only standard scopesets (those defined in model_fields_set).
         :return: set of names, for example ['gwp', 'odp']
         """
         result = []
         for f in self.model_fields_set:
             if f in ("ext",):
                 continue
-            field = self.model_fields.get(f)
+            field = self.__class__.model_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)
 
+        # add extra fields
+        if not only_standard and self.model_extra:
+            for name in self.model_extra.keys():
+                if name not in result:
+                    result.append(name)
+
+        if exclude_none:
+            # filter out names with None values
+            result = [name for name in result if self.get_scopeset_by_name(name) is not None]
+
+        return result
+
+    def set_scopeset_by_name(self, name: str, scopeset: ScopeSet | None) -> None:
+        """
+        Set scopeset by name.
+
+        :param name: The name of the scopeset.
+        :param scopeset: The scopeset to set.
+        """
+        # check known impacts first
+        for f_name, f in self.__class__.model_fields.items():
+            if f.alias == name:
+                setattr(self, f_name, scopeset)
+                return
+            if f_name == name:
+                setattr(self, f_name, scopeset)
+                return
+        # probably unknown impact, coming from 'extra' fields
+        setattr(self, name, scopeset)
+
+    def __getitem__(self, scopeset_name: str) -> ScopeSet:
+        """Get scopeset by name or raise KeyError."""
+        if not isinstance(scopeset_name, str):
+            raise TypeError(f"Key must be a string, got {type(scopeset_name)}")
+        result = self.get_scopeset_by_name(scopeset_name)
+        if result is None:
+            raise KeyError(f"Scopeset '{scopeset_name}' not found")
         return result
 
+    def __setitem__(self, key: str, value: ScopeSet | None) -> None:
+        """Set scopeset by name."""
+        if not isinstance(key, str):
+            raise TypeError(f"Key must be a string, got {type(key)}")
+        if value is not None and not isinstance(value, ScopeSet):
+            raise TypeError(f"Value must be a ScopeSet, got {type(value)}")
+        self.set_scopeset_by_name(key, value)
+
+    def __contains__(self, item: str) -> bool:
+        """Check if scopeset with the given name exists (was set and is not None)."""
+        if not isinstance(item, str):
+            return False
+        return item in self.get_scopeset_names(exclude_none=True)
+
+    def __iter__(self) -> Generator[tuple[str, ScopeSet], None, None]:
+        """Iterate over existing (set and not None) scopesets and yield tuples of scopeset name and scopeset."""
+        for name in self.get_scopeset_names(exclude_none=True):
+            yield name, cast(ScopeSet, self.get_scopeset_by_name(name))
+
+    def __len__(self) -> int:
+        """Get the number of existing (set and not None) scopesets."""
+        return len(self.get_scopeset_names(exclude_none=True))
+
+    def items(self) -> list[tuple[str, ScopeSet]]:
+        """Get all scopeset names and their values."""
+        return [
+            (name, cast(ScopeSet, self.get_scopeset_by_name(name)))
+            for name in self.get_scopeset_names(exclude_none=True)
+        ]
+
     def get_scopeset_by_name(self, name: str) -> ScopeSet | None:
         """
         Get scopeset by name.
@@ -270,7 +342,7 @@ class ScopesetByNameBase(BaseOpenEpdSchema, extra="allow"):
         :return: A scopeset if found, None otherwise
         """
         # check known impacts first
-        for f_name, f in self.model_fields.items():
+        for f_name, f in self.__class__.model_fields.items():
             if f.alias == name:
                 return getattr(self, f_name)
             if f_name == name:
@@ -557,25 +629,6 @@ class LCIAMethod(StrEnum):
 class Impacts(pydantic.RootModel[dict[LCIAMethod, ImpactSet]]):
     """List of environmental impacts, compiled per one of the standard Impact Assessment methods."""
 
-    @staticmethod
-    def _update_schema_extra(schema, model):
-        schema.update(
-            {
-                "properties": {
-                    str(lm): {
-                        "description": str(lm),
-                        # This is an internal representation of the reference which exists in Pydantic during
-                        # generation process
-                        "allOf": [{"$ref": "#/components/schemas/openepd__model__lcia__ImpactSet-Input__1"}],
-                    }
-                    for lm in LCIAMethod
-                },
-                "additionalProperties": None,
-            }
-        )
-
-    model_config: ClassVar[ConfigDict] = ConfigDict(json_schema_extra=_update_schema_extra)
-
     def set_unknown_lcia(self, impact_set: ImpactSet):
         """Set the impact set as an unknown LCIA method."""
         self.root[LCIAMethod.UNKNOWN] = impact_set
@@ -623,6 +676,61 @@ class Impacts(pydantic.RootModel[dict[LCIAMethod, ImpactSet]]):
         """Return the impacts as a dictionary."""
         return self.root
 
+    @classmethod
+    def __get_pydantic_json_schema__(cls, core_schema: CoreSchema, handler: GetJsonSchemaHandler, *, mode="validation"):
+        # Get the base schema from the handler
+        json_schema: dict[str, Any] = handler(core_schema)
+        # Resolve the reference to get the actual ImpactSet schema
+        json_schema = handler.resolve_ref_schema(json_schema)
+        json_schema_generator: GenerateJsonSchema | None = None
+        if hasattr(handler, "generate_json_schema") and handler.generate_json_schema:
+            json_schema_generator = handler.generate_json_schema
+
+        ref_template = ""
+        if json_schema_generator and json_schema_generator.ref_template:
+            ref_template = json_schema_generator.ref_template
+        elif json_schema.get("propertyNames", {}).get("$ref") is not None:
+            template_path, _ = json_schema.get("propertyNames", {}).get("$ref", "").rsplit("/", maxsplit=2)
+            if template_path:
+                ref_template = f"{template_path}/{{model}}"
+        if not ref_template:
+            ref_template = "#/components/schemas/{model}"
+
+        # Get the ImpactSet reference dynamically
+        impact_set_ref = None
+        if (
+            json_schema_generator
+            and hasattr(json_schema_generator, "definitions")
+            and json_schema_generator.definitions
+        ):
+            # Look for ImpactSet in the definitions
+            for def_name, _ in json_schema_generator.definitions.items():
+                if "ImpactSet" in def_name:
+                    # Use the correct OpenAPI reference format
+                    impact_set_ref = ref_template.format(model=def_name)
+                    break
+
+        # Fallback: use a generic reference if we can't find the specific one (
+        if not impact_set_ref:
+            impact_set_ref = ref_template.format(model="ImpactSet")
+
+        # Update the schema with explicit properties for each LCIA method
+        json_schema.update(
+            {
+                "type": "object",
+                "properties": {
+                    str(lm): {
+                        "description": str(lm),
+                        "allOf": [{"$ref": impact_set_ref}],
+                    }
+                    for lm in LCIAMethod
+                },
+            }
+        )
+        json_schema.pop("additionalProperties")
+
+        return json_schema
+
 
 class ResourceUseSet(ScopesetByNameBase):
     """A set of resource use indicators, such as RPRec, RPRm, etc."""

openepd/model/org.py

@@ -150,26 +150,35 @@ class Plant(PlantRef, WithAttachmentsMixin, WithAltIdsMixin):
 
     pluscode: str | None = pydantic.Field(
         default=None,
-        description="(deprecated) Plus code (aka Open Location Code) of plant's location",
+        description="(DEPRECATED) Plus code (aka Open Location Code) of plant's location. "
+        "This field is deprecated. If users need a pluscode they can obtain it from `id`.",
         json_schema_extra={
-            "deprecated": "Pluscode field is deprecated. If users need a pluscode they can obtain it from "
-            "`id` like this: `id.spit('.', maxsplit=1)[0]`",
+            "deprecated": True,
         },
     )
     latitude: float | None = pydantic.Field(
         default=None,
-        description="(deprecated) Latitude of the plant location. Use 'location' fields instead.",
+        description="(DEPRECATED) Latitude of the plant location. Use 'location' fields instead.",
+        json_schema_extra={
+            "deprecated": True,
+        },
     )
     longitude: float | None = pydantic.Field(
         default=None,
-        description="(deprecated) Longitude of the plant location. Use 'location' fields instead.",
+        description="(DEPRECATED) Longitude of the plant location. Use 'location' fields instead.",
+        json_schema_extra={
+            "deprecated": True,
+        },
     )
     owner: Org | None = pydantic.Field(description="Organization that owns the plant", default=None)
     address: str | None = pydantic.Field(
         max_length=200,
         default=None,
-        description="(deprecated) Text address, preferably geocoded. Use 'location' fields instead",
+        description="(DEPRECATED) Text address, preferably geocoded. Use 'location' fields instead",
         examples=["1503 Orchard Hill Rd, LaGrange, GA 30240, United States"],
+        json_schema_extra={
+            "deprecated": True,
+        },
     )
     contact_email: pydantic.EmailStr | None = pydantic.Field(
         description="Email contact", examples=["info@interface.com"], default=None

openepd/model/versioning.py

@@ -30,7 +30,7 @@ class WithExtVersionMixin(ABC, pydantic.BaseModel):
         """Set the default value for the ext_version field from _EXT_VERSION class var."""
         super().__init_subclass__()
         if hasattr(cls, "_EXT_VERSION"):
-            cls.model_fields["ext_version"].default = cls._EXT_VERSION
+            cls.model_fields["ext_version"].default_factory = lambda: cls._EXT_VERSION
 
     # Note: default is set programmatically in __init_subclass__
     ext_version: str | None = pydantic.Field(description="Extension version", examples=["3.22"], default=None)

openepd/utils/__init__.py

@@ -0,0 +1,15 @@
+#
+#  Copyright 2025 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.
+#

openepd/utils/mapping/__init__.py

@@ -0,0 +1,15 @@
+#
+#  Copyright 2025 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.
+#

openepd/utils/mapping/common.py

@@ -0,0 +1,217 @@
+#
+#  Copyright 2025 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.
+#
+__all__ = (
+    "BaseDataMapper",
+    "KeyValueMapper",
+    "ReferenceMapper",
+    "RegexMapper",
+    "SimpleDataMapper",
+)
+
+import abc
+from collections.abc import Mapping
+import re
+from typing import Generic, TypeAlias, TypeVar, assert_never, cast
+
+T = TypeVar("T")
+K = TypeVar("K")
+
+
+class BaseDataMapper(Generic[T, K], abc.ABC):
+    """
+    Base class for all data mappers.
+
+    Data mappers are objects used to map some input values to output values of different types.
+
+    Typical use case is mapping between different aliases of impact names with OpenEpd naming conventions.
+    """
+
+    @abc.abstractmethod
+    def map(self, input_value: T, default_value: K | None, *, raise_if_missing: bool = False) -> K | None:
+        """
+        Map the input value to the output value.
+
+        :param input_value: The input value to map.
+        :param default_value: The default value to return if there is no mapping for the input value.
+        :param raise_if_missing: Whether to raise an exception if there is no mapping for the input value.
+
+        :raise ValueError: If there is no mapping for the input value and raise_if_missing is True.
+        """
+        pass
+
+    def map_or_keep(self, input_value: T) -> K:
+        """
+        Map the input value to the output value or keep the input value if there is no mapping.
+
+        This is a convenience method equivalent to calling `map` with `default_value=input_value`
+        and `raise_if_missing=False`.
+
+        :param input_value: The input value to map.
+        :return: The mapped value or the input value if there is no mapping.
+        """
+        return cast(K, self.map(input_value, default_value=cast(K, input_value), raise_if_missing=False))
+
+    def map_or_raise(self, input_value: T) -> K:
+        """
+        Map the input value to the output value or raise an exception if there is no mapping.
+
+        This is a convenience method equivalent to calling `map` with `default_value=None`
+        and `raise_if_missing=True`.
+
+        :param input_value: The input value to map.
+        :return: The mapped value.
+        :raise ValueError: If there is no mapping for the input value.
+        """
+        return cast(K, self.map(input_value, default_value=None, raise_if_missing=True))
+
+
+class SimpleDataMapper(BaseDataMapper[T, T], Generic[T]):
+    """A data mapper that does not change the type of the input value."""
+
+    DATABASE: Mapping[T, T] = {}
+
+    def map(self, input_value: T, default_value: T | None, *, raise_if_missing: bool = False) -> T | None:
+        """
+        Map the input value to the output value.
+
+        :param input_value: The input value to map.
+        :param default_value: The default value to return if there is no mapping for the input value.
+        :param raise_if_missing: Whether to raise an exception if there is no mapping for the input value.
+
+        :raise ValueError: If there is no mapping for the input value and raise_if_missing is True.
+        """
+        if raise_if_missing and input_value not in self.DATABASE:
+            msg = f"No mapping for input value: {input_value}"
+            raise ValueError(msg)
+
+        return self.DATABASE.get(input_value, default_value)
+
+
+class KeyValueMapper(BaseDataMapper[str, T], Generic[T]):
+    """
+    A data mapper that maps input values to output values using keywords.
+
+    List of values is expected to be a list string object or a list of objects easily castable to string.
+    """
+
+    KV: Mapping[str, list[T]] = {}
+
+    def map(self, input_value: str, default_value: T | None, *, raise_if_missing: bool = False) -> T | None:
+        """
+        Map the input value to the output value using keywords.
+
+        :param input_value: The input value to map.
+        :param default_value: The default value to return if there is no mapping for input value.
+        :param raise_if_missing: Whether to raise an exception if there is no mapping for the input value.
+
+        :raise ValueError: If there is no mapping for the input value and raise_if_missing is True.
+        """
+        for impact_name, keywords in self.KV.items():
+            for keyword in keywords:
+                if str(keyword).strip().lower() in input_value.strip().lower():
+                    return cast(T, impact_name)
+
+        if raise_if_missing:
+            msg = f"No mapping for input value: {input_value}"
+            raise ValueError(msg)
+
+        return default_value
+
+
+class RegexMapper(BaseDataMapper[str, T], Generic[T]):
+    """A data mapper that maps input values to output values using regex."""
+
+    PATTERNS: dict[str, str] = {}
+    _compiled_patterns: dict[str, re.Pattern]
+
+    def __init__(self) -> None:
+        self._compiled_patterns: dict[str, re.Pattern] = {
+            key: re.compile(pattern, re.IGNORECASE) for key, pattern in self.PATTERNS.items()
+        }
+
+    def map(self, input_value: str, default_value: T | None, *, raise_if_missing: bool = False) -> T | None:
+        """
+        Map the input value to the output value using regex.
+
+        :param input_value: The input value to map.
+        :param default_value: The default value to return if there is no mapping for an input value.
+
+        :param raise_if_missing: Whether to raise an exception if there is no mapping for the input value.
+
+        :raise ValueError: If there is no mapping for the input value and raise_if_missing is True.
+        """
+        for impact_name, pattern in self._compiled_patterns.items():
+            if pattern.search(input_value.strip().lower()):
+                return cast(T, impact_name)
+
+        if raise_if_missing:
+            msg = f"No mapping for input value: {input_value}"
+            raise ValueError(msg)
+
+        return default_value
+
+
+_TRmRules: TypeAlias = str | re.Pattern | list[str | re.Pattern]
+
+
+class ReferenceMapper(BaseDataMapper[str, _TRmRules]):
+    """
+    A mapper that maps input values of any form to the expected value format.
+
+    Expected values may be a value or a list of values. Values are expected to be a string object, regular expressions,
+    or objects easily castable to string.
+    """
+
+    def map(self, input_value: str, default_value: str | None, *, raise_if_missing: bool = False) -> str | None:  # type: ignore[override]
+        """
+        Return specified key as a value if any of the values in the list matches the input value.
+
+        :param input_value: value to be checked against the list of specified rules
+        :param default_value: default value to return if no match is found
+        :param raise_if_missing: whether to raise an exception if no match is found
+
+        :return: mapped value if find any match, else default value
+
+        :raise ValueError: if no match is found and raise_if_missing is True
+        """
+        for key, value in self.MAPPING.items():
+            if not self._is_applied(input_value, value):
+                continue
+            return key
+
+        if raise_if_missing:
+            msg = f"No mapping for input value: {input_value}"
+            raise ValueError(msg)
+
+        return default_value
+
+    def _is_applied(self, input_value: str, rules: _TRmRules) -> bool:
+        if isinstance(rules, str | re.Pattern):
+            return self._is_applied_to_item(input_value, rules)
+        elif isinstance(rules, list):
+            return any(self._is_applied_to_item(input_value, rule) for rule in rules)
+        else:
+            assert_never(rules)
+
+    def _is_applied_to_item(self, input_value: str, rule: str | re.Pattern) -> bool:
+        if isinstance(rule, str):
+            return input_value.strip().lower() == rule.strip().lower()
+        elif isinstance(rule, re.Pattern):
+            return bool(rule.search(input_value.strip().lower()))
+        else:
+            assert_never(rule)
+
+    MAPPING: Mapping[str, _TRmRules] = {}

openepd/utils/mapping/geography.py

@@ -0,0 +1,58 @@
+#
+#  Copyright 2025 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.
+#
+
+__all__ = (
+    "OPENEPD_GEOGRAPHY_MAPPER",
+    "GeographyToOpenEpdMapper",
+)
+
+from openepd.m49 import const as m49_const
+from openepd.m49 import utils as m49_utils
+from openepd.utils.mapping.common import BaseDataMapper
+
+
+class GeographyToOpenEpdMapper(BaseDataMapper[str, set[str]]):
+    """Mapper that converts various geography inputs (e.g. country name, ISO code, M49) into openEPD compliant geography."""
+
+    def map(
+        self, input_value: str, default_value: str | set[str] | None, *, raise_if_missing: bool = False
+    ) -> set[str] | None:
+        """Map input geography value to openEpd geography codes."""
+        result: set[str] = set()
+        try:
+            if input_value:
+                input_value = input_value.strip()
+            if m49_utils.is_m49_code(input_value):
+                result = m49_utils.m49_to_openepd([input_value])
+            elif m49_utils.is_iso_code(input_value):
+                result = m49_utils.m49_to_openepd(m49_utils.iso_to_m49([input_value]))
+            elif input_value.upper() in m49_const.OPENEPD_SPECIAL_REGIONS:  # Special regions like "NAFTA" or "EU"
+                result = {input_value.upper()}
+            else:  # this might be a verbose region or country name
+                mapped_m49 = m49_utils.region_and_country_names_to_m49([input_value])
+                result = m49_utils.m49_to_openepd(mapped_m49)
+        except ValueError:
+            result = set()
+        if result:
+            return result
+        if raise_if_missing:
+            raise ValueError(f"Input '{input_value}' could not be mapped to OpenEpd geography codes.")
+        if isinstance(default_value, str):
+            return {default_value}
+        return default_value
+
+
+OPENEPD_GEOGRAPHY_MAPPER = GeographyToOpenEpdMapper()

openepd/utils/markdown.py

@@ -0,0 +1,52 @@
+#
+#  Copyright 2025 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 dataclasses
+from typing import Self
+
+
+class MarkdownSectionBuilder:
+    """
+    A builder for Markdown sections.
+
+    Allows to build a Markdown string from a list of sections (title + content).
+    """
+
+    @dataclasses.dataclass(kw_only=True)
+    class _MdSection:
+        title: str
+        level: int = 1
+        content: str | None = None
+
+    def __init__(self) -> None:
+        self._sections: list[MarkdownSectionBuilder._MdSection] = []
+
+    def add_section(self, title: str, content: str | None = None, level: int = 1) -> Self:
+        """Add a new section to the builder."""
+        self._sections.append(MarkdownSectionBuilder._MdSection(title=title, content=content, level=level))
+        return self
+
+    @property
+    def has_content(self) -> bool:
+        """Return True if there are any sections added to the builder."""
+        return len(self._sections) > 0
+
+    @staticmethod
+    def _build_section(section: _MdSection) -> str:
+        return f"{'#' * section.level} {section.title}\n\n{section.content or ''}"
+
+    def build(self) -> str:
+        """Build the Markdown string."""
+        return "\n\n".join([self._build_section(x) for x in self._sections if x.content is not None])

{openepd-7.5.0.dist-info → openepd-7.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: openepd
-Version: 7.5.0
+Version: 7.7.0
 Summary: Python library to work with OpenEPD format
 License: Apache-2.0
 Author: C-Change Labs

{openepd-7.5.0.dist-info → openepd-7.7.0.dist-info}/RECORD

@@ -1,5 +1,5 @@
 openepd/__init__.py,sha256=9THJcV3LT7JDBOMz1px-QFf_sdJ0LOqJ5dmA9Dvvtd4,620
-openepd/__version__.py,sha256=wROB4Az8lHLZ19vzPzFg6vUHTTs6IDmcRyEAEx07WWs,638
+openepd/__version__.py,sha256=yl4wQF-1qgdO4jZxe2wV3xfKlACh5SDmznbBqByduEM,638
 openepd/api/__init__.py,sha256=9THJcV3LT7JDBOMz1px-QFf_sdJ0LOqJ5dmA9Dvvtd4,620
 openepd/api/average_dataset/__init__.py,sha256=9THJcV3LT7JDBOMz1px-QFf_sdJ0LOqJ5dmA9Dvvtd4,620
 openepd/api/average_dataset/generic_estimate_sync_api.py,sha256=mjTT8eGtfj6Fgp-wcs0cCWA7DJo1KL_iQ75rgKkaY3c,8037
@@ -36,10 +36,10 @@ openepd/bundle/model.py,sha256=4pmOCgK-kdBu7_PLm5QhlrVZRmab_18o0EGvcUjI8FQ,2722
 openepd/bundle/reader.py,sha256=H1mfuFxV2G0q9ld0dJ6SRucTwcTSEi-sFoKJLsBk4IQ,7767
 openepd/bundle/writer.py,sha256=cyFikYTtZCcX0rhdpbuvOaOBG4CS1nE8JjHUdB7Wghs,8708
 openepd/m49/__init__.py,sha256=AApOMp9PJPMXZbPB4piedqKtgHE01mlj_MyF3kf519U,718
-openepd/m49/const.py,sha256=bkYu6J7dQNVb2-nNkjy97uMpt64vICX5o-PHr0lk_90,31833
-openepd/m49/utils.py,sha256=vQl0wMXtYS2b7NeLIWilDNUopq3MATmLnhEFcMYTeZA,7256
+openepd/m49/const.py,sha256=lxp2bzwD4d95VHo5ULKFN8ryzjjfKTwpe9_MdUFIoXw,32104
+openepd/m49/utils.py,sha256=0UvdtC9gtvRA5WT_hJDIuQR0RSrnx-S34wwwBRM_tsM,7807
 openepd/model/__init__.py,sha256=9THJcV3LT7JDBOMz1px-QFf_sdJ0LOqJ5dmA9Dvvtd4,620
-openepd/model/base.py,sha256=CLE6iMS0hE5AiQo0rUWsatp2bt78DG2dRAWNw78t5T8,10928
+openepd/model/base.py,sha256=4D8BaSoNeY8RZfjkmJOSyfg0B34dKzM76lZbQT9AIXg,13622
 openepd/model/category.py,sha256=iyzzAsiVwW4zJ61oYsm9Sy-sEBA71-aMFXcJP1Y-dPI,1734
 openepd/model/common.py,sha256=D-FmaKk_ay6Of3HdUiloagc2nUiOLp97781BDRZMp8U,14662
 openepd/model/declaration.py,sha256=v-X2JBOK-7ZYWziEUP7GOSrQFK4pI9EMZvp3Z7-mwwM,14669
@@ -48,8 +48,8 @@ openepd/model/factory.py,sha256=UWSGpfCr3GiMTP4rzBkwqxzbXB6GKZ_5Okb1Dqa_4aA,2701
 openepd/model/generic_estimate.py,sha256=_R18Uz-hvxtSBl53D0_OkwVCWvoa2nIDjBdec6vEPDE,4304
 openepd/model/geography.py,sha256=Jx7NIDdk_sIvwyh-7YxnIjAwIHW2HCQK7UtFGM2xKtw,42095
 openepd/model/industry_epd.py,sha256=Cqn01IUNSZqRkyU05TwtOLXDKlg0YnGzqvKL8A__zbI,4061
-openepd/model/lcia.py,sha256=Sx6SAwRTlkxqjKq-QEkPEUihgIS04jUndhOi4oHP5vw,27824
-openepd/model/org.py,sha256=1O3MM2y4nEEQ8V2WsJCK4cvQumcadZ6sgwSM1sRbGkY,8012
+openepd/model/lcia.py,sha256=IfSLZER6kI1tb0tKZW1FeHxFqeumznurELNLtYR6TC8,32756
+openepd/model/org.py,sha256=zYZXTwU5Xah-MAiG0dP8SNRACpb79TmTWF6mUoROk8M,8181
 openepd/model/pcr.py,sha256=cu3EakCAjBCkcb_AaLXB-xEjY0mlG-wJe74zGc5tdS0,5637
 openepd/model/specs/README.md,sha256=UGhSiFJ9hOxT1mZl-5ZrhkOrPKf1W_gcu5CI9hzV7LU,2430
 openepd/model/specs/__init__.py,sha256=RMLxvwD-_N5qaU0U2o5LxMKmP_W0_yssl72uTTC2tJg,3904
@@ -144,9 +144,14 @@ openepd/model/validation/common.py,sha256=SsYgCOoO2sJYm4VzI2tBmukXMrzwvbncEdkLlJ
 openepd/model/validation/enum.py,sha256=0nRnjwmObw8ERQYWRWbovZjm90CMHi1Sc-UeNxCFnsc,1846
 openepd/model/validation/numbers.py,sha256=9THJcV3LT7JDBOMz1px-QFf_sdJ0LOqJ5dmA9Dvvtd4,620
 openepd/model/validation/quantity.py,sha256=M9dz3byTK6Lrys43I0Gq7n2b0aE8WYys-idxi6bKCII,21755
-openepd/model/versioning.py,sha256=LldrNjPjVBsVTWyJrBe6VoI19B0d47QXbHk_6omXPxc,4561
+openepd/model/versioning.py,sha256=QzPeWiRCNvSUmlXANg4Vl4WqsPtlrCr8gSwDNUhZGvM,4577
 openepd/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-openepd-7.5.0.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-openepd-7.5.0.dist-info/METADATA,sha256=LWKh9QYyF-8Zw1fsNsaQwZZmUYTTkAEf9JPdKwVy9Rk,9810
-openepd-7.5.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-openepd-7.5.0.dist-info/RECORD,,
+openepd/utils/__init__.py,sha256=9THJcV3LT7JDBOMz1px-QFf_sdJ0LOqJ5dmA9Dvvtd4,620
+openepd/utils/mapping/__init__.py,sha256=9THJcV3LT7JDBOMz1px-QFf_sdJ0LOqJ5dmA9Dvvtd4,620
+openepd/utils/mapping/common.py,sha256=hxfN-WW2WLwE_agQzf_mhvz6OHq5WWlr24uZ1S81k4Y,8426
+openepd/utils/mapping/geography.py,sha256=1_-dvLk11Hqn-K58yUI5pQ5X5gsnJPFlFT7JK2Rdoeg,2396
+openepd/utils/markdown.py,sha256=RQmudPhb4QU1I4-S-VV2WFbzzq2Po09kbpjjKbwkA9E,1830
+openepd-7.7.0.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+openepd-7.7.0.dist-info/METADATA,sha256=pyqC4h1XAG1lwB2uZQ82w2XAmgelS-7sqwGCVnsxYgg,9810
+openepd-7.7.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+openepd-7.7.0.dist-info/RECORD,,