openepd 7.1.0__tar.gz → 7.3.0__tar.gz

{openepd-7.1.0 → openepd-7.3.0}/PKG-INFO

@@ -1,15 +1,14 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: openepd
-Version: 7.1.0
+Version: 7.3.0
 Summary: Python library to work with OpenEPD format
-Home-page: https://github.com/cchangelabs/openepd
 License: Apache-2.0
 Author: C-Change Labs
 Author-email: support@c-change-labs.com
 Maintainer: C-Change Labs
 Maintainer-email: open-source@c-change-labs.com
 Requires-Python: >=3.11,<4.0
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
@@ -21,7 +20,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: open-xpd-uuid (>=0.2.1,<2)
 Requires-Dist: openlocationcode (>=1.0.1)
 Requires-Dist: pydantic (>=2.0,<3)
 Requires-Dist: requests (>=2.0) ; extra == "api-client"
@@ -45,6 +44,24 @@ Description-Content-Type: text/markdown
 
 This library is a Python library to work with OpenEPD format.
 
+> ⚠️ **Version Warning**
+>
+> This application is currently developed in **two major versions** in parallel:
+>
+> - **v6.x (>=6.0.0)** — Stable and production-ready. Maintains support for Pydantic v1 and v2 through a compatibility layer.
+> - **v7.x (>=7.0.0)** — Public beta. Fully functional, with native support for Pydantic v2. Still experimental and may introduce breaking changes in **internal and integration interfaces**.
+>
+> ⚠️ No breaking changes are expected in the **public standard or data model**, only in internal APIs and integration points.
+> 
+> Both versions currently offer the same set of features.  
+> We recommend using **v6** for most production use cases as the more mature and stable option.  
+> **v7** is suitable for production environments that can tolerate some level of interface instability and want to adopt the latest internals.
+>
+> 💡 Only the **latest version of v7** is guaranteed to contain all the features and updates from v6. Earlier v7 releases may lack some recent improvements.
+>
+> Once **v7 is promoted to stable**, all earlier **pre-stable (beta) v7 releases** will be **marked as yanked** to prevent accidental usage in production.
+>
+
 ## About OpenEPD
 
 [openEPD](https://www.buildingtransparency.org/programs/openepd/) is an open data format for passing digital
@@ -60,17 +77,10 @@ including uniqueness of organizations/plants, precise PCR references, and dated
 The openEPD format is **extensible**. Standard extensions exist for concrete products, and for
 documenting supply-chain specific data.
 
-[Read More about OpenEPD format here](https://www.buildingtransparency.org/programs/openepd/).
+[Read More about OpenEPD format here](https://www.open-epd-forum.org).
 
 ## Usage
 
-**❗ 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:
-
-* Use version **below** `2.0.0` if your project uses Pydantic version below `2.0.0`
-* Use version `2.x.x` or higher if your project uses Pydantic version `2.0.0` or above
-
 ### Models
 
 The library provides the Pydantic models for all the OpenEPD entities. The models are available in the `openepd.models`

{openepd-7.1.0 → openepd-7.3.0}/README.md

@@ -15,6 +15,24 @@
 
 This library is a Python library to work with OpenEPD format.
 
+> ⚠️ **Version Warning**
+>
+> This application is currently developed in **two major versions** in parallel:
+>
+> - **v6.x (>=6.0.0)** — Stable and production-ready. Maintains support for Pydantic v1 and v2 through a compatibility layer.
+> - **v7.x (>=7.0.0)** — Public beta. Fully functional, with native support for Pydantic v2. Still experimental and may introduce breaking changes in **internal and integration interfaces**.
+>
+> ⚠️ No breaking changes are expected in the **public standard or data model**, only in internal APIs and integration points.
+> 
+> Both versions currently offer the same set of features.  
+> We recommend using **v6** for most production use cases as the more mature and stable option.  
+> **v7** is suitable for production environments that can tolerate some level of interface instability and want to adopt the latest internals.
+>
+> 💡 Only the **latest version of v7** is guaranteed to contain all the features and updates from v6. Earlier v7 releases may lack some recent improvements.
+>
+> Once **v7 is promoted to stable**, all earlier **pre-stable (beta) v7 releases** will be **marked as yanked** to prevent accidental usage in production.
+>
+
 ## About OpenEPD
 
 [openEPD](https://www.buildingtransparency.org/programs/openepd/) is an open data format for passing digital
@@ -30,17 +48,10 @@ including uniqueness of organizations/plants, precise PCR references, and dated
 The openEPD format is **extensible**. Standard extensions exist for concrete products, and for
 documenting supply-chain specific data.
 
-[Read More about OpenEPD format here](https://www.buildingtransparency.org/programs/openepd/).
+[Read More about OpenEPD format here](https://www.open-epd-forum.org).
 
 ## Usage
 
-**❗ 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:
-
-* Use version **below** `2.0.0` if your project uses Pydantic version below `2.0.0`
-* Use version `2.x.x` or higher if your project uses Pydantic version `2.0.0` or above
-
 ### Models
 
 The library provides the Pydantic models for all the OpenEPD entities. The models are available in the `openepd.models`

{openepd-7.1.0 → openepd-7.3.0}/pyproject.toml

@@ -1,11 +1,6 @@
-[tool.ruff]
-line-length = 120
-target-version = "py311"
-exclude = [".*pyi"]
-
 [tool.poetry]
 name = "openepd"
-version = "7.1.0"
+version = "7.3.0"
 license = "Apache-2.0"
 description = "Python library to work with OpenEPD format"
 authors = ["C-Change Labs <support@c-change-labs.com>"]
@@ -13,7 +8,7 @@ maintainers = ["C-Change Labs <open-source@c-change-labs.com>"]
 repository = "https://github.com/cchangelabs/openepd"
 keywords = []
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: Apache Software License",
     "Operating System :: OS Independent",
@@ -23,6 +18,7 @@ classifiers = [
 readme = "README.md"
 packages = [{ include = "openepd", from = "src" }]
 exclude = ["**/test_*.py", "**/tests/**"]
+requires-poetry = ">=2.0.0"
 
 [tool.poetry.dependencies]
 python = "^3.11"
@@ -30,13 +26,13 @@ pydantic = ">=2.0,<3"
 email-validator = ">=1.3.1"
 requests = { version = ">=2.0", optional = true }
 idna = ">=3.7"
-open-xpd-uuid = "~=0.2.1"
+open-xpd-uuid = ">=0.2.1,<2"
 openlocationcode = ">=1.0.1"
 
 # Optional dependencies
 # lxml = { version = "~=4.9.2", optional = true }
 
-[tool.poetry.dev-dependencies]
+[tool.poetry.group.dev.dependencies]
 # Unit tests
 coverage = { version = "=6.5", extras = ["toml"] }
 pytest = "~=7.2"
@@ -47,12 +43,8 @@ wheel = "~=0.40.0"
 click = "~=8.1.7"
 
 # Dev tools
-black = "~=24.3"
+ruff = ">=0.11.8"
 licenseheaders = "~=0.8"
-flake8 = "~=4.0"
-flake8-import-graph = "~=0.1.3"
-flake8-docstrings = "~=1.7.0"
-isort = "~=5.11"
 mypy = ">=1.0.1"
 pre-commit = "~=2.19"
 commitizen = "~=3.16.0"
@@ -71,7 +63,6 @@ jinja2 = ">=3.1.4"
 [tool.poetry.extras]
 api_client = ["requests"]
 
-
 [tool.commitizen]
 version_provider = "poetry"
 bump_version = "bump: version $current_version → $new_version"
@@ -151,3 +142,33 @@ follow_imports = "skip"
 [[tool.mypy.overrides]]
 module = "openlocationcode.*"
 ignore_missing_imports = true
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+exclude = [".*pyi", "tools/**.py"]
+
+[tool.ruff.lint.isort]
+force-sort-within-sections = true
+
+[tool.ruff.lint]
+extend-ignore = [
+    "S101", # Use of assert statement. We have a lot of asserts for mypy type checking.
+    "W291", # W291 trailing whitespace
+    "W391", # W391 blank line at end of file
+    "E501", # E501: line too long
+    "E203", # E704: Multiple statements on one line (def)
+    "F403", #F403 'from module import *' used; unable to detect undefined names (F403)
+    ##### DOCSTRINGS #####
+    "D100", # Missing docstring in public module
+    "D101", # Missing docstring in public class
+    "D102", # Docstring of prublic method
+    "D107", # Missing docstring in __init__
+    "D105", # Missing docstring in magic method
+    "D104", # Missing docstring in public package
+    "D106", # Missing docstring in public nested class
+    "D202", # D202 No blank lines allowed after function docstring
+    "D203", # We want to have blank line before class
+    "D212", # We want to require second line for multiline docstrings
+]
+extend-select = ["S", "E", "B", "A", "EM", "UP", "LOG", "G", "I", "D"]

{openepd-7.1.0 → openepd-7.3.0}/src/openepd/__version__.py

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

{openepd-7.1.0 → openepd-7.3.0}/src/openepd/api/average_dataset/generic_estimate_sync_api.py

@@ -135,7 +135,8 @@ class GenericEstimateApi(BaseApiMethodGroup):
         """
         ge_id = ge.id
         if not ge_id:
-            raise ValueError("The ID must be set to edit a GenericEstimate.")
+            msg = "The ID must be set to edit a GenericEstimate."
+            raise ValueError(msg)
 
         response = self._client.do_request(
             "put",

{openepd-7.1.0 → openepd-7.3.0}/src/openepd/api/average_dataset/industry_epd_sync_api.py

@@ -90,7 +90,8 @@ class IndustryEpdApi(BaseApiMethodGroup):
         """
         iepd_id = iepd.id
         if not iepd_id:
-            raise ValueError("The ID must be set to edit a IndustryEpd.")
+            msg = "The ID must be set to edit a IndustryEpd."
+            raise ValueError(msg)
 
         response = self._client.do_request(
             "put",

{openepd-7.1.0 → openepd-7.3.0}/src/openepd/api/base_sync_client.py

@@ -14,14 +14,15 @@
 #  limitations under the License.
 #
 __all__ = (
-    "HttpStreamReader",
-    "SyncHttpClient",
+    "USER_AGENT_DEFAULT",
+    "BaseApiMethodGroup",
     "DoRequest",
+    "HttpStreamReader",
     "RetryHandler",
-    "BaseApiMethodGroup",
-    "USER_AGENT_DEFAULT",
+    "SyncHttpClient",
 )
 
+from collections.abc import Callable
 import datetime
 from functools import partial, wraps
 from io import IOBase
@@ -29,7 +30,7 @@ import logging
 import random
 import shutil
 import time
-from typing import IO, Any, BinaryIO, Callable, Final, NamedTuple
+from typing import IO, Any, BinaryIO, Final, NamedTuple
 
 import requests
 from requests import PreparedRequest, Response, Session, Timeout
@@ -180,7 +181,7 @@ class SyncHttpClient:
         self._throttler = Throttler(rate_per_sec=requests_per_sec)
         self._throttle_retry_timeout: float = (
             float(throttle_retry_timeout)
-            if isinstance(throttle_retry_timeout, (float, int))
+            if isinstance(throttle_retry_timeout, float | int)
             else throttle_retry_timeout.total_seconds()
         )
         self.user_agent = user_agent
@@ -412,7 +413,8 @@ class SyncHttpClient:
 
         response.raise_for_status()
         # This can't be handled by static checker because of the dynamic nature of the raise_for_status method
-        raise RuntimeError("This line should never be reached")
+        msg = "This line should never be reached"
+        raise RuntimeError(msg)
 
     def _get_url_for_request(self, path_or_url: str) -> str:
         """
@@ -471,7 +473,7 @@ class SyncHttpClient:
                     exception = e
 
                 if exception or response.status_code == requests_codes.service_unavailable:
-                    secs = random.randint(60, 60 * 5)
+                    secs = random.randint(60, 60 * 5)  # noqa: S311
                     logger.warning(
                         "%s %s is unavailable. Attempts left: %s. Waiting %s seconds...",
                         method,

{openepd-7.1.0 → openepd-7.3.0}/src/openepd/api/common.py

@@ -13,12 +13,12 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 #
-from collections.abc import Iterable
+from collections.abc import Callable, Iterable, Iterator
 from contextlib import contextmanager
 from datetime import datetime, timedelta
 import threading
 from time import sleep
-from typing import Callable, Generic, Iterator, cast
+from typing import Generic, cast
 
 from requests import Response
 
@@ -126,20 +126,26 @@ class StreamingListResponse(Iterable[TOpenEpdObject], Generic[TOpenEpdObject]):
         :return: list of items on the page
         """
         if page_num <= 0:
-            raise ValueError("Page number must be positive")
+            msg = "Page number must be positive"
+            raise ValueError(msg)
         if self.__current_page != page_num or force_reload:
             self.__recent_response = self.__fetch_handler(page_num, self.__page_size)
             self.__current_page = page_num
         if self.__recent_response is None:
-            raise RuntimeError("Response is empty, this should not happen, check if fetch_handler is compatible")
+            msg = "Response is empty, this should not happen, check if fetch_handler is compatible"
+            raise RuntimeError(msg)
         if self.__recent_response.payload is None:
-            raise ValueError("Response does not contain payload")
+            msg = "Response does not contain payload"
+            raise ValueError(msg)
         if not isinstance(self.__recent_response.payload, list):
-            raise ValueError("Response does not contain a list")
+            msg = "Response does not contain a list"
+            raise ValueError(msg)
         if self.__recent_response.meta is None:
-            raise ValueError("Response does not contain meta")
+            msg = "Response does not contain meta"
+            raise ValueError(msg)
         if not isinstance(self.__recent_response.meta, PagingMetaMixin):
-            raise ValueError("Response does not contain paging meta")
+            msg = "Response does not contain paging meta"
+            raise ValueError(msg)
         return self.__recent_response.payload
 
     def get_paging_meta(self) -> PagingMeta:
@@ -152,7 +158,8 @@ class StreamingListResponse(Iterable[TOpenEpdObject], Generic[TOpenEpdObject]):
         """
         paging_meta = cast(PagingMetaMixin, self.get_meta()).paging
         if paging_meta is None:
-            raise ValueError("Response does not contain paging meta")
+            msg = "Response does not contain paging meta"
+            raise ValueError(msg)
         return paging_meta
 
     def get_meta(self) -> MetaCollectionDto:
@@ -206,8 +213,7 @@ class StreamingListResponse(Iterable[TOpenEpdObject], Generic[TOpenEpdObject]):
         self.goto_page(start_from_page)
         while True:
             items = self.goto_page(self.current_page)
-            for x in items:
-                yield x
+            yield from items
             if not self.has_next_page():
                 return  # no more pages
             else:

{openepd-7.1.0 → openepd-7.3.0}/src/openepd/api/dto/common.py

@@ -63,7 +63,7 @@ TMetaExtension = TypeVar("TMetaExtension", bound=MetaExtensionBase)
 
 class MetaCollectionDto(BaseOpenEpdApiModel, Generic[TMetaExtension]):
     """
-    This class is intended to be used as a container for different meta objects.
+    Use this class as a container for different meta objects.
 
     From a specific controller, you should return a specific subclass of MetaCollectionDto and appropriate mixins. This
     would allow to retain type information to generate schema for meta section of response.

{openepd-7.1.0 → openepd-7.3.0}/src/openepd/api/epd/sync_api.py

@@ -173,7 +173,8 @@ class EpdApi(BaseApiMethodGroup):
         """
         epd_id = epd.id
         if not epd_id:
-            raise ValueError("The EPD ID must be set to edit an EPD.")
+            msg = "The EPD ID must be set to edit an EPD."
+            raise ValueError(msg)
         response = self._client.do_request(
             "put",
             f"/epds/{encode_path_param(epd_id)}",

openepd-7.3.0/src/openepd/api/org/sync_api.py

@@ -0,0 +1,79 @@
+#
+#  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.
+#
+from typing import Literal, overload
+
+from requests import Response
+
+from openepd.api.base_sync_client import BaseApiMethodGroup
+from openepd.api.utils import encode_path_param
+from openepd.model.org import Org, OrgRef
+
+
+class OrgApi(BaseApiMethodGroup):
+    """API methods for Orgs."""
+
+    @overload
+    def create(self, to_create: Org, with_response: Literal[True]) -> tuple[OrgRef, Response]: ...
+
+    @overload
+    def create(self, to_create: Org, with_response: Literal[False] = False) -> OrgRef: ...
+
+    def create(self, to_create: Org, with_response: bool = False) -> OrgRef | tuple[OrgRef, Response]:
+        """
+        Create a new organization.
+
+        :param to_create: Organization to create
+        :param with_response: if True, return a tuple of (OrgRef, Response), otherwise return only OrgRef
+        :return: Organization reference or Organization reference with HTTP Response object depending on parameter
+        :raise ValidationError: if given object Org is invalid
+        """
+        response = self._client.do_request("post", "/orgs", json=to_create.to_serializable())
+        content = response.json()
+        ref = OrgRef.model_validate(content)
+        if with_response:
+            return ref, response
+        return ref
+
+    @overload
+    def edit(self, to_edit: Org, with_response: Literal[True]) -> tuple[OrgRef, Response]: ...
+
+    @overload
+    def edit(self, to_edit: Org, with_response: Literal[False] = False) -> OrgRef: ...
+
+    def edit(self, to_edit: Org, with_response: bool = False) -> OrgRef | tuple[OrgRef, Response]:
+        """
+        Edit an organization.
+
+        :param to_edit: Organization to edit
+        :param with_response: if True, return a tuple of (OrgRef, Response), otherwise return only Org
+        :return: Organization reference or Organization reference with HTTP Response object depending on parameter
+        :raise ValueError: if the organization web_domain is not set
+        """
+        entity_id = to_edit.web_domain
+        if not entity_id:
+            msg = "The organization web_domain must be set to edit an organization."
+            raise ValueError(msg)
+        response = self._client.do_request(
+            "put",
+            f"/orgs/{encode_path_param(entity_id)}",
+            json=to_edit.to_serializable(exclude_unset=True, exclude_defaults=True, by_alias=True),
+        )
+        response.raise_for_status()
+        content = response.json()
+        ref = OrgRef.model_validate(content)
+        if with_response:
+            return ref, response
+        return ref

{openepd-7.1.0 → openepd-7.3.0}/src/openepd/api/pcr/sync_api.py

@@ -13,7 +13,12 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 #
+from typing import Literal, overload
+
+from requests import Response
+
 from openepd.api.base_sync_client import BaseApiMethodGroup
+from openepd.api.utils import encode_path_param
 from openepd.model.pcr import Pcr, PcrRef
 
 
@@ -42,3 +47,33 @@ class PcrApi(BaseApiMethodGroup):
         """
         pcr_ref_obj = self._client.do_request("post", "/pcrs", json=pcr.to_serializable()).json()
         return PcrRef.model_validate(pcr_ref_obj)
+
+    @overload
+    def edit(self, to_edit: Pcr, with_response: Literal[True]) -> tuple[PcrRef, Response]: ...
+
+    @overload
+    def edit(self, to_edit: Pcr, with_response: Literal[False] = False) -> PcrRef: ...
+
+    def edit(self, to_edit: Pcr, with_response: bool = False) -> PcrRef | tuple[PcrRef, Response]:
+        """
+        Edit a pcr.
+
+        :param to_edit: Pcr to edit
+        :param with_response: if True, return a tuple of (PcrRef, Response), otherwise return only PcrRef
+        :return: Pcr reference or Pcr reference with HTTP Response object depending on parameter
+        :raise ValueError: if the pcr ID is not set
+        """
+        entity_id = to_edit.id
+        if not entity_id:
+            msg = "The pcr ID must be set to edit a pcr."
+            raise ValueError(msg)
+        response = self._client.do_request(
+            "put",
+            f"/pcrs/{encode_path_param(entity_id)}",
+            json=to_edit.to_serializable(exclude_unset=True, exclude_defaults=True, by_alias=True),
+        )
+        content = response.json()
+        ref = PcrRef.model_validate(content)
+        if with_response:
+            return ref, response
+        return ref

openepd-7.3.0/src/openepd/api/plant/sync_api.py

@@ -0,0 +1,79 @@
+#
+#  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.
+#
+from typing import Literal, overload
+
+from requests import Response
+
+from openepd.api.base_sync_client import BaseApiMethodGroup
+from openepd.api.utils import encode_path_param
+from openepd.model.org import Plant, PlantRef
+
+
+class PlantApi(BaseApiMethodGroup):
+    """API methods for Plants."""
+
+    @overload
+    def create(self, to_create: Plant, with_response: Literal[True]) -> tuple[PlantRef, Response]: ...
+
+    @overload
+    def create(self, to_create: Plant, with_response: Literal[False] = False) -> PlantRef: ...
+
+    def create(self, to_create: Plant, with_response: bool = False) -> PlantRef | tuple[PlantRef, Response]:
+        """
+        Create a new plant.
+
+        :param to_create: Plant to create
+        :param with_response: if True, return a tuple of (PlantRef, Response), otherwise return only PlantRef
+        :return: Plant reference or Plant reference with HTTP Response object depending on parameter
+        :raise ValidationError: if given object Plant is invalid
+        """
+        response = self._client.do_request("post", "/plants", json=to_create.to_serializable())
+        content = response.json()
+        ref = PlantRef.model_validate(content)
+        if with_response:
+            return ref, response
+        return ref
+
+    @overload
+    def edit(self, to_edit: Plant, with_response: Literal[True]) -> tuple[PlantRef, Response]: ...
+
+    @overload
+    def edit(self, to_edit: Plant, with_response: Literal[False] = False) -> PlantRef: ...
+
+    def edit(self, to_edit: Plant, with_response: bool = False) -> PlantRef | tuple[PlantRef, Response]:
+        """
+        Edit a plant.
+
+        :param to_edit: Plant to edit
+        :param with_response: if True, return a tuple of (PlantRef, Response), otherwise return only PlantRef
+        :return: Plant reference or Plant reference with HTTP Response object depending on parameter
+        :raise ValueError: if the plant ID is not set
+        """
+        entity_id = to_edit.id
+        if not entity_id:
+            msg = "The plant ID must be set to edit a plant."
+            raise ValueError(msg)
+        response = self._client.do_request(
+            "put",
+            f"/plants/{encode_path_param(entity_id)}",
+            json=to_edit.to_serializable(exclude_unset=True, exclude_defaults=True, by_alias=True),
+        )
+        response.raise_for_status()
+        content = response.json()
+        ref = PlantRef.model_validate(content)
+        if with_response:
+            return ref, response
+        return ref