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

openepd/patch_pydantic.py

@@ -0,0 +1,101 @@
+#
+#  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.
+#
+from typing import Any
+
+from pydantic import utils as pydantic_utils
+
+from openepd.compat.pydantic import pyd
+
+
+def patch_pydantic_metaclass():
+    """
+    Patch pydantic's ModelMetaclass to restore class attribute lookup for fields.
+
+    In pydantic, while the model fields are defined in the model as class-level attributes, in runtime they disappear
+    due to ModelMetaclass logic. ModelMetaclass takes the defined attributes, removes them from class dict and puts
+    into a special __fields__ attribute to avoid naming conflict.
+
+    We would like to be able to access the attributes via dot notation in the runtimes, since it makes refactoring
+    easier.
+
+    This class exposes the original fields when accessed via class name. For example, one can call `Pcr.name` and get
+    `ModelField`, in addition to calling `pcr.__fields__` on an instance.
+    """
+
+    def model_metaclass__getattr__(cls, name: str) -> Any:
+        if name in cls.__fields__:
+            return cls.__fields__[name]
+        return getattr(super, name)
+
+    pyd.main.ModelMetaclass.__getattr__ = model_metaclass__getattr__
+
+
+def patch_pydantic_metaclass_validator():
+    """
+    Patch the internal validator function used during model construction to support modified metaclass.
+
+    Pydantic has a special guard which stops execution if a model defines field which shadows a basemodel interface.
+    For example, if someone would define a field named `__fields__` this would break code.
+
+    With the modified metaclass functionality, we are exposing the original fields as class attributes, and this
+    breaks this check.
+
+    This patcher method modifies the pydantic internals so that the check is retained, but it is not causing exception
+    when doing the normal field inheritance.
+    """
+    model_field_classes = list()
+
+    try:
+        from pydantic.v1.fields import ModelField as ModelFieldV1
+
+        model_field_classes.append(ModelFieldV1)
+    except ImportError:
+        pass
+
+    try:
+        from pydantic_core.core_schema import ModelField as ModelFieldV2
+
+        model_field_classes.append(ModelFieldV2)
+    except ImportError:
+        pass
+    model_field_classes_tuple = tuple(model_field_classes)
+
+    def pydantic_utils__validate_field_name(bases: list[type[pyd.BaseModel]], field_name: str) -> None:
+        for base in bases:
+            if attr := getattr(base, field_name, None):
+                if isinstance(attr, model_field_classes_tuple):
+                    continue
+
+                raise NameError(
+                    f'Field name "{field_name}" shadows a BaseModel attribute; '
+                    f"use a different field name with \"alias='{field_name}'\"."
+                )
+
+    pyd.main.validate_field_name = pydantic_utils__validate_field_name
+    pydantic_utils.validate_field_name = pydantic_utils__validate_field_name
+
+
+def patch_pydantic():
+    """
+    Modify Pydantic to support field attribute access via class.
+
+    Example: Field the_field in the model TheModel(BaseModel). Before this patch, one can do
+     `TheModel().__fields__["the_field"]' to get field descriptor. After the fix, one can do TheModel.the_field.
+
+     To disable, set env variable `OPENEPD_DISABLE_PYDANTIC_PATCH` to "1", "yes" or "true".
+    """
+    patch_pydantic_metaclass()
+    patch_pydantic_metaclass_validator()

{openepd-4.4.0.dist-info → openepd-4.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: openepd
-Version: 4.4.0
+Version: 4.5.0
 Summary: Python library to work with OpenEPD format
 Home-page: https://github.com/cchangelabs/openepd
 License: Apache-2.0
@@ -60,9 +60,7 @@ documenting supply-chain specific data.
 
 ## Usage
 
-## Usage
-
-**❗ ATTENTION**: Pick the right version. The cornerstone of this library models package representing openEPD models. 
+**❗ ATTENTION**: Pick the right version. The cornerstone of this library models package representing openEPD models.
 Models are defined with Pydantic library which is a dependency for openepd package. If you use Pydantic in your project
 carefully pick the version:
 
@@ -76,9 +74,11 @@ module. For mode details on the usage please refer to Pydantic documentation.
 
 ### API Client
 
-The library provides the API client to work with the OpenEPD API. The client is available in the `openepd.client` module.
+The library provides the API client to work with the OpenEPD API. The client is available in the `openepd.client`
+module.
 Currently, the only available implementation is based on synchronous [requests]() library. Client provides the following
 features:
+
 * Error handling - depending on HTTP status code the client raises different exceptions allowing to handle errors
   in a more granular way.
 * Throttling - the client is able to throttle the requests to the API to avoid hitting the rate limits.
@@ -144,12 +144,25 @@ with DefaultBundleWriter("my-bundle.epb") as writer, open("test-pcr.pdf", "rb")
     writer.write_blob_asset(pcr_pdf_file, "application/pdf", pcr_asset, RelType.Pdf)
 ```
 
-### Mypy
+### Model attribute access
+
+OpenEPD extends its pydantic models with extra functionality: field descriptors can be accessed via dot notation from
+class name:
+
+* Usual pydantic way: TheModel().__field__["the_field"]
+* In openEPD: TheModel.the_field
+
+Instances hold data as usual.
+
+This behaviour is enabled by default. To disable, run the code with `OPENEPD_DISABLE_PYDANTIC_PATCH` set to `true`.
+
+See src/openepd/patch_pydantic.py for details.
+
+### Generated enums
 
-OpenEPD uses a small modification to standard pydantic models (see PydanticClassAttributeExposeModelMetaclass). Mypy,
-in order to work correctly, requires a modified pydantic plugin. To enable it, add an 
-`openepd.mypy.custom_pydantic_plugin` to list of mypy plugins in your `pyproject.toml` or other mypy-related config
-file. See [Mypy configuration](https://mypy.readthedocs.io/en/stable/extending_mypy.html)
+The geography and country enums are generated from several sources, including pycountry list of 2-character country
+codes, UN m49 codification, and special regions. To update the enums, first update any of these sources, then use
+`make codegen`. See 'tools/openepd/codegen' for details.
 
 # Credits
 

{openepd-4.4.0.dist-info → openepd-4.5.0.dist-info}/RECORD

@@ -1,5 +1,5 @@
-openepd/__init__.py,sha256=UGmZGEyMnASrYwEBPHuXmVzHiuCUskUsJEPoHTIo-lg,620
-openepd/__version__.py,sha256=8oxCZtughIDK-iiG2jwUL1oA4HclG-SZymHOYT1nbtE,638
+openepd/__init__.py,sha256=Shkfh0Kun0YRhmRDw7LkUj2eQL3X-HnP55u2THOEALw,794
+openepd/__version__.py,sha256=Hcw_oQZEZ9hzNn_8In_JiWYNOFLzNVvUkS7-nl2hWyg,638
 openepd/api/__init__.py,sha256=UGmZGEyMnASrYwEBPHuXmVzHiuCUskUsJEPoHTIo-lg,620
 openepd/api/base_sync_client.py,sha256=jviqtQgsOVdRq5x7_Yh_Tg8zIdWtVTIUqNCgebf6YDg,20925
 openepd/api/category/__init__.py,sha256=UGmZGEyMnASrYwEBPHuXmVzHiuCUskUsJEPoHTIo-lg,620
@@ -30,11 +30,13 @@ openepd/compat/__init__.py,sha256=UGmZGEyMnASrYwEBPHuXmVzHiuCUskUsJEPoHTIo-lg,62
 openepd/compat/compat_functional_validators.py,sha256=yz6DfWeg7knBHEN_enpCGGTLRknEsecXfpzD1FDlywY,834
 openepd/compat/pydantic.py,sha256=DOjSixsylLqMtFAIARu50sGcT4VPXN_c473q_2JwZQ0,1146
 openepd/model/__init__.py,sha256=UGmZGEyMnASrYwEBPHuXmVzHiuCUskUsJEPoHTIo-lg,620
-openepd/model/base.py,sha256=XGuXCWr0PTAeewQj8u75OcRWFumFP2wiSdJsrsL_ZGI,9959
+openepd/model/base.py,sha256=uVEGndgLm8JFwffsCXdusfRE01DQSKJUJLxsd-GXba0,8988
 openepd/model/category.py,sha256=IQXNGQFQmFZ_H9PRONloX_UOSf1sTMDq1rM1yz8JR0Y,1639
 openepd/model/common.py,sha256=aa_bfotPybPoYyzHtwj5E5X1T-fCEyznMfVUWvpUhiM,5460
-openepd/model/epd.py,sha256=_PyVM3cKrOBS2vgLLPBZzKkNfiBEtp2rECP0imp49bc,14082
-openepd/model/factory.py,sha256=i45ZXG5RIMKrXvVH1li0ZlUwcBpSl5gEctcLc1MBM7M,1701
+openepd/model/epd.py,sha256=2mdXxXZFoPOoXI_zSC1VzdBf0Q2sUNKg7vrtXZ8c8EE,14137
+openepd/model/factory.py,sha256=StQUH7GNmRqskMnnRYkr_PLCl5X5sSLEPiYZOIQI9eo,2541
+openepd/model/generic_estimate.py,sha256=txr2bCbrZPIaCNJZypkna0vzz7e0AizOp6MMhEU018A,3324
+openepd/model/geography.py,sha256=amL_-0ojKhsiy_pVDbkM9Rm3yzBZC0KGpHQ_rZAYbM4,37417
 openepd/model/lcia.py,sha256=-5bMz5ZyoZJnggp66v9upTT0yhcyIZYlwfFh83-4ZvY,16968
 openepd/model/org.py,sha256=FHcYh2WOOQrCMyzm0Ow-iP79jMTBPcneidjH6NXIklA,3760
 openepd/model/pcr.py,sha256=SwqLWMj9k_jqIzxz5mh6ttqvtLCspKSpywF5YTBOMsA,5397
@@ -86,10 +88,9 @@ openepd/model/validation/common.py,sha256=FLYqK8gYFagx08LCkS0jy3qo4-Zq9VAv5i8ZwF
 openepd/model/validation/numbers.py,sha256=tgirqrDGgrSo6APGlW1ozNuVV8mJz_4HCAXS2OUENq0,888
 openepd/model/validation/quantity.py,sha256=kzug0MZ3Ao0zeVzN-aleyxUg5hA_7D5tNOOerverfRQ,7415
 openepd/model/versioning.py,sha256=R_zm6rCrgF3vlJQYbpyWhirdS_Oek16cv_mvZmpuE8I,4473
-openepd/mypy/__init__.py,sha256=UGmZGEyMnASrYwEBPHuXmVzHiuCUskUsJEPoHTIo-lg,620
-openepd/mypy/custom_pydantic_plugin.py,sha256=JpfQHAmqS95lKm68tTlQ12RFO_O2tvd4ZM_DFBNUa8s,4034
+openepd/patch_pydantic.py,sha256=W4n5nmCeurGfJNxiUiiDs73YqbG4JpMdTc2vPv5_6Ag,3946
 openepd/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-openepd-4.4.0.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-openepd-4.4.0.dist-info/METADATA,sha256=monlkvm4yIu0TbpTtV0iMUdxBGohmD-zBk5PSdPNc8o,8212
-openepd-4.4.0.dist-info/WHEEL,sha256=Zb28QaM1gQi8f4VCBhsUklF61CTlNYfs9YAZn-TOGFk,88
-openepd-4.4.0.dist-info/RECORD,,
+openepd-4.5.0.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+openepd-4.5.0.dist-info/METADATA,sha256=6RbVFGrMX0amNJi-F-by7jBBeUnVFaVB27guVslSiZ4,8534
+openepd-4.5.0.dist-info/WHEEL,sha256=Zb28QaM1gQi8f4VCBhsUklF61CTlNYfs9YAZn-TOGFk,88
+openepd-4.5.0.dist-info/RECORD,,

openepd/mypy/__init__.py

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

openepd/mypy/custom_pydantic_plugin.py

@@ -1,91 +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.
-#
-
-from collections.abc import Callable
-
-from mypy.nodes import AssignmentStmt, CallExpr, MemberExpr, TypeInfo
-from mypy.plugin import ClassDefContext
-import pydantic.mypy
-from pydantic.mypy import (
-    MODEL_METACLASS_FULLNAME,
-    ModelConfigData,
-    PydanticModelClassVar,
-    PydanticModelField,
-    PydanticModelTransformer,
-    PydanticPlugin,
-)
-
-# Using this plugin fixes the issue.
-
-CUSTOM_OPENEPD_MODEL_METACLASS_FULLNAME = "openepd.model.base.PydanticClassAttributeExposeModelMetaclass"
-MODEL_METACLASSES_FULL_NAMES = (MODEL_METACLASS_FULLNAME, CUSTOM_OPENEPD_MODEL_METACLASS_FULLNAME)
-
-DECORATOR_FULLNAMES = pydantic.mypy.DECORATOR_FULLNAMES | {
-    "pydantic.v1.class_validators.validator",
-}
-
-
-class CustomPydanticModelTransformer(PydanticModelTransformer):
-    """Extension of the mypy/pydantic model transformer which also understands validator definitions via v1 compat."""
-
-    def collect_field_or_class_var_from_stmt(
-        self, stmt: AssignmentStmt, model_config: ModelConfigData, class_vars: dict[str, PydanticModelClassVar]
-    ) -> PydanticModelField | PydanticModelClassVar | None:
-        """Extend implementation of the original Pydantic method with one more case for validator."""
-        if not stmt.new_syntax and (
-            isinstance(stmt.rvalue, CallExpr)
-            and isinstance(stmt.rvalue.callee, CallExpr)
-            and isinstance(stmt.rvalue.callee.callee, MemberExpr)
-            and stmt.rvalue.callee.callee.fullname in DECORATOR_FULLNAMES
-        ):
-            # Required to detect compat-imported v1 validators and not treat them as fields.
-            return None
-        return super().collect_field_or_class_var_from_stmt(stmt, model_config, class_vars)
-
-
-class CustomMetaclassPydanticPlugin(PydanticPlugin):
-    """
-    Custom metaclass pydantic plugin.
-
-    Extends a standard pydantic mypy plugin, and adds certain behaviours required for us:
-    1. Support for a non-standard metaclass for pydantic models. We use it allow for access via Class.field notation
-    2. Support for our modified compat import of pydantic v1 when using this metaclass.
-    """
-
-    def get_metaclass_hook(self, fullname: str) -> Callable[[ClassDefContext], None] | None:
-        """Update Pydantic `ModelMetaclass` definition."""
-        if fullname in MODEL_METACLASSES_FULL_NAMES:
-            return self._pydantic_model_metaclass_marker_callback
-        return None
-
-    def get_base_class_hook(self, fullname: str) -> Callable[[ClassDefContext], bool] | None:  # type: ignore
-        """Update Pydantic model class."""
-        sym = self.lookup_fully_qualified(fullname)
-        if sym and isinstance(sym.node, TypeInfo):  # pragma: no branch
-            # No branching may occur if the mypy cache has not been cleared
-            if any(base.fullname in ["pydantic.main.BaseModel", "pydantic.v1.main.BaseModel"] for base in sym.node.mro):
-                return self._pydantic_model_class_maker_callback
-        return None
-
-    def _pydantic_model_class_maker_callback(self, ctx: ClassDefContext) -> bool:
-        # extended to replace the mypy-pydantic transformer with our custom transformer - see validator note.
-        transformer = CustomPydanticModelTransformer(ctx.cls, ctx.reason, ctx.api, self.plugin_config)
-        return transformer.transform()
-
-
-def plugin(version: str):
-    """Entry point to the mypy plugin."""
-    return CustomMetaclassPydanticPlugin