crossplane-function-sdk-python 0.11.0__tar.gz → 0.13.0__tar.gz

{crossplane_function_sdk_python-0.11.0 → crossplane_function_sdk_python-0.13.0}/.github/workflows/ci.yml

@@ -28,7 +28,7 @@ concurrency:
 env:
   # Common versions
   PYTHON_VERSION: '3.11'
-  HATCH_VERSION: '1.12.0'
+  HATCH_VERSION: '1.16.5'
 
   # The PyPi project version to push. The default is v0.0.0+gitdate-gitsha.
   PYPI_VERSION: ${{ inputs.version }}
@@ -98,7 +98,7 @@ jobs:
         run: hatch build
 
       - name: Upload Sdist and Wheel to GitHub
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: dist
           path: "dist/*"
@@ -114,13 +114,13 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Download Sdist and Wheel from GitHub
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
         with:
           name: dist
           path: "dist"
 
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@v1.13.0
+        uses: pypa/gh-action-pypi-publish@v1.14.0
         with:
           # Note that this is currently being pushed to the 'crossplane' PyPI
           # user (not org). See @negz if you need access - PyPI requires 2FA to
@@ -150,13 +150,13 @@ jobs:
         run: hatch run docs:pdoc -d google crossplane/function -o docs
 
       - name: Setup Pages
-        uses: actions/configure-pages@v5
+        uses: actions/configure-pages@v6
 
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v4
+        uses: actions/upload-pages-artifact@v5
         with:
           path: docs
 
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

{crossplane_function_sdk_python-0.11.0 → crossplane_function_sdk_python-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crossplane-function-sdk-python
-Version: 0.11.0
+Version: 0.13.0
 Summary: The Python SDK for Crossplane composition functions
 Project-URL: Documentation, https://github.com/crossplane/function-sdk-python#readme
 Project-URL: Issues, https://github.com/crossplane/function-sdk-python/issues
@@ -14,10 +14,10 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: grpcio-reflection==1.*
-Requires-Dist: grpcio==1.76.0
-Requires-Dist: protobuf==6.33.5
+Requires-Dist: grpcio==1.81.0
+Requires-Dist: protobuf==7.35.0
 Requires-Dist: pydantic==2.*
-Requires-Dist: structlog==25.*
+Requires-Dist: structlog==26.*
 Description-Content-Type: text/markdown
 
 # function-sdk-python

{crossplane_function_sdk_python-0.11.0 → crossplane_function_sdk_python-0.13.0}/crossplane/function/__version__.py

@@ -15,4 +15,4 @@
 """The version of function-sdk-python."""
 
 # This is set at build time, using "hatch version"
-__version__ = "0.11.0"
+__version__ = "0.13.0"

{crossplane_function_sdk_python-0.11.0 → crossplane_function_sdk_python-0.13.0}/crossplane/function/resource.py

@@ -16,6 +16,7 @@
 
 import dataclasses
 import datetime
+import hashlib
 
 import pydantic
 from google.protobuf import json_format
@@ -39,12 +40,21 @@ def update(r: fnv1.Resource, source: dict | structpb.Struct | pydantic.BaseModel
     """
     match source:
         case pydantic.BaseModel():
-            data = source.model_dump(exclude_defaults=True, warnings=False)
-            # In Pydantic, exclude_defaults=True in model_dump excludes fields
-            # that have their value equal to the default. If a field like
-            # apiVersion is set to its default value 's3.aws.upbound.io/v1beta2'
-            # (and not explicitly provided during initialization), it will be
-            # excluded from the serialized output.
+            # exclude_unset emits only the fields the caller explicitly set.
+            # Crossplane treats desired resources as server-side apply intent,
+            # so a function should own exactly the fields it has an opinion
+            # about and leave the rest to the API server.
+            #
+            # by_alias emits each field under its alias, which is its real
+            # wire name. datamodel-code-generator aliases fields whose KRM
+            # name collides with a Python keyword or builtin (e.g. it emits a
+            # bool_ attribute aliased to bool, continue_ aliased to continue).
+            # Without by_alias those fields serialize under the Python name and
+            # don't match the resource's schema. It's a no-op for ordinary
+            # fields, which have no alias.
+            data = source.model_dump(exclude_unset=True, by_alias=True, warnings=False)
+            # apiVersion and kind identify the resource but are rarely passed
+            # as kwargs, so they're usually unset. Add them back explicitly.
             data["apiVersion"] = source.apiVersion
             data["kind"] = source.kind
             r.resource.update(data)
@@ -59,6 +69,26 @@ def update(r: fnv1.Resource, source: dict | structpb.Struct | pydantic.BaseModel
             raise TypeError(msg)
 
 
+def update_status(
+    r: fnv1.Resource,
+    status: dict | pydantic.BaseModel,
+) -> None:
+    """Update a resource's status.
+
+    Args:
+        r: A composite or composed resource to update.
+        status: The status to set, as a dictionary or Pydantic model.
+
+    Sets ``r.resource.status`` from the supplied status. When the status
+    is a Pydantic model, fields the caller didn't explicitly set are
+    excluded and aliased fields are emitted under their wire names,
+    matching the behavior of :func:`update`.
+    """
+    if isinstance(status, pydantic.BaseModel):
+        status = status.model_dump(exclude_unset=True, by_alias=True, warnings=False)
+    update(r, {"status": status})
+
+
 def dict_to_struct(d: dict) -> structpb.Struct:
     """Create a Struct well-known type from the supplied dict.
 
@@ -99,11 +129,17 @@ class Condition:
     last_transition_time: datetime.time | None = None
 
 
-def get_condition(resource: structpb.Struct, typ: str) -> Condition:
+def get_condition(
+    resource: structpb.Struct | fnv1.Resource | None,
+    typ: str,
+) -> Condition:
     """Get the supplied status condition of the supplied resource.
 
     Args:
-        resource: A Crossplane resource.
+        resource: A Crossplane resource. Can be a protobuf Struct (the raw
+            resource), an fnv1.Resource wrapper, or None. When an
+            fnv1.Resource is supplied, the Struct is extracted automatically.
+            When None is supplied, an unknown condition is returned.
         typ: The type of status condition to get (e.g. Ready).
 
     Returns:
@@ -111,9 +147,23 @@ def get_condition(resource: structpb.Struct, typ: str) -> Condition:
 
     A status condition is always returned. If the status condition isn't present
     in the supplied resource, a condition with status "Unknown" is returned.
+
+    Accepting fnv1.Resource and None makes it safe to pass the result of a
+    protobuf map ``.get()`` call directly. This avoids auto-vivification, which
+    silently inserts a default entry when using bracket access on a missing
+    key::
+
+        # Safe — .get() returns None without mutating the map.
+        c = get_condition(req.observed.resources.get("bucket"), "Ready")
+
+        # Unsafe — bracket access auto-vivifies an empty Resource.
+        c = get_condition(req.observed.resources["bucket"].resource, "Ready")
     """
     unknown = Condition(typ=typ, status="Unknown")
 
+    if isinstance(resource, fnv1.Resource):
+        resource = resource.resource
+
     if not resource or "status" not in resource:
         return unknown
 
@@ -140,3 +190,37 @@ def get_condition(resource: structpb.Struct, typ: str) -> Condition:
         return condition
 
     return unknown
+
+
+_DNS_LABEL_MAX = 63
+_HASH_LEN = 5
+
+
+def child_name(*parts: str, sep: str = "-") -> str:
+    """Build a deterministic, DNS-label-safe name for a child resource.
+
+    Args:
+        *parts: Name components to join (e.g. parent name, suffix).
+        sep: Separator between parts. Defaults to "-".
+
+    Returns:
+        A name that is at most 63 characters long.
+
+    Composition functions often derive child resource names from a parent
+    name and a discriminator. The resulting name must be a valid DNS label
+    (at most 63 characters). This function joins the parts, appends a
+    deterministic 5-character hash suffix for uniqueness, and truncates
+    the prefix to fit within the limit.
+
+    The hash suffix is always appended, even for short names, so that
+    names are visually consistent regardless of length::
+
+        child_name("my-xr", "bucket")       # "my-xr-bucket-a1b2c"
+        child_name("my-very-long-xr-name",
+                   "with-a-very-long-suffix") # truncated to 63 chars
+    """
+    full = sep.join(parts)
+    h = hashlib.sha256(full.encode()).hexdigest()[:_HASH_LEN]
+    max_prefix = _DNS_LABEL_MAX - _HASH_LEN - 1
+    prefix = full[:max_prefix].rstrip(sep)
+    return f"{prefix}{sep}{h}"

{crossplane_function_sdk_python-0.11.0 → crossplane_function_sdk_python-0.13.0}/crossplane/function/response.py

@@ -81,6 +81,44 @@ def fatal(rsp: fnv1.RunFunctionResponse, message: str) -> None:
     )
 
 
+_STATUS_MAP = {
+    "True": fnv1.STATUS_CONDITION_TRUE,
+    "False": fnv1.STATUS_CONDITION_FALSE,
+    "Unknown": fnv1.STATUS_CONDITION_UNKNOWN,
+}
+
+
+def set_conditions(
+    rsp: fnv1.RunFunctionResponse,
+    *conditions: resource.Condition,
+) -> None:
+    """Set one or more conditions on the composite resource (XR).
+
+    Args:
+        rsp: The RunFunctionResponse to update.
+        *conditions: The conditions to set.
+
+    Each condition is appended to ``rsp.conditions``. Crossplane uses the
+    conditions returned by a function to set custom status conditions on
+    the composite resource.
+
+    The ``last_transition_time`` field of each condition is ignored.
+    Crossplane sets the transition time itself.
+
+    Do not set the ``Ready`` condition type. Crossplane manages it based
+    on resource readiness.
+    """
+    for condition in conditions:
+        c = fnv1.Condition(
+            type=condition.typ,
+            status=_STATUS_MAP.get(condition.status, fnv1.STATUS_CONDITION_UNKNOWN),
+            reason=condition.reason or "",
+        )
+        if condition.message:
+            c.message = condition.message
+        rsp.conditions.append(c)
+
+
 def set_output(rsp: fnv1.RunFunctionResponse, output: dict | structpb.Struct) -> None:
     """Set the output field in a RunFunctionResponse for operation functions.
 

{crossplane_function_sdk_python-0.11.0 → crossplane_function_sdk_python-0.13.0}/pyproject.toml

@@ -18,11 +18,11 @@ classifiers = [
 ]
 
 dependencies = [
-  "grpcio==1.76.0",
+  "grpcio==1.81.0",
   "grpcio-reflection==1.*",
-  "protobuf==6.33.5", # Must be compatible with grpcio-tools.
+  "protobuf==7.35.0", # Must be compatible with grpcio-tools.
   "pydantic==2.*",
-  "structlog==25.*",
+  "structlog==26.*",
 ]
 
 dynamic = ["version"]