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

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

@@ -38,10 +38,10 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Setup Python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@v7
         with:
           python-version: ${{ env.PYTHON_VERSION }}
 
@@ -55,10 +55,10 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Setup Python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@v7
         with:
           python-version: ${{ env.PYTHON_VERSION }}
 
@@ -73,10 +73,10 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Setup Python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@v7
         with:
           python-version: ${{ env.PYTHON_VERSION }}
 
@@ -120,7 +120,7 @@ jobs:
           path: "dist"
 
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@v1.14.0
+        uses: pypa/gh-action-pypi-publish@v1.14.2
         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
@@ -136,10 +136,10 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Setup Python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@v7
         with:
           python-version: ${{ env.PYTHON_VERSION }}
 

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: crossplane-function-sdk-python
-Version: 0.13.0
+Version: 0.15.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
@@ -13,9 +13,10 @@ Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
+Requires-Dist: click==8.*
 Requires-Dist: grpcio-reflection==1.*
-Requires-Dist: grpcio==1.81.0
-Requires-Dist: protobuf==7.35.0
+Requires-Dist: grpcio==1.84.0
+Requires-Dist: protobuf==7.36.1
 Requires-Dist: pydantic==2.*
 Requires-Dist: structlog==26.*
 Description-Content-Type: text/markdown

crossplane_function_sdk_python-0.15.0/crossplane/function/__init__.py

@@ -0,0 +1,65 @@
+# Copyright 2025 The Crossplane Authors.
+#
+# 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.
+
+"""Python SDK for writing Crossplane composition functions.
+
+This SDK provides the building blocks for implementing [Crossplane composition
+functions](https://docs.crossplane.io/latest/concepts/composition-functions) in
+Python. Composition functions are serverless components that extend Crossplane's
+composition capability, allowing you to programmatically control how infrastructure
+is composed and managed.
+
+## Quick Start
+
+Install the SDK:
+
+```shell
+pip install crossplane-function-sdk-python
+```
+
+Create a composition function by subclassing `Runtime`:
+
+```python
+from crossplane.function.runtime import Runtime
+from crossplane.function.request import RunFunctionRequest
+from crossplane.function.response import RunFunctionResponse
+
+
+class MyFunction(Runtime):
+    def Run(self, request: RunFunctionRequest) -> RunFunctionResponse:
+        # Your composition logic here
+        return response.to(request)
+```
+
+## Modules
+
+- **runtime** — Base class for implementing the function runtime and gRPC server.
+- **request** — Types and utilities for parsing `RunFunctionRequest` messages.
+- **response** — Types and utilities for building `RunFunctionResponse` messages.
+- **resource** — Kubernetes resource types used in function pipelines.
+- **logging** — Structured logging utilities for function output.
+
+## Protobuf Types
+
+The `RunFunctionRequest` and `RunFunctionResponse` types are generated from
+proto3 schema definitions. See the proto modules for API reference:
+
+- [`proto.v1.run_function_pb2`][crossplane.function.proto.v1.run_function_pb2]
+  — Current API
+- [`proto.v1beta1.run_function_pb2`][crossplane.function.proto.v1beta1.run_function_pb2]
+  — Legacy API
+
+Proto-generated fields behave like standard Python types but follow
+[protobuf Python conventions](https://protobuf.dev/reference/python/python-generated/).
+"""

{crossplane_function_sdk_python-0.13.0 → crossplane_function_sdk_python-0.15.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.13.0"
+__version__ = "0.15.0"

crossplane_function_sdk_python-0.15.0/crossplane/function/cli.py

@@ -0,0 +1,127 @@
+# Copyright 2026 The Crossplane Authors.
+#
+# 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.
+
+"""Standard CLI options for Python composition functions.
+
+Provides reusable options and a run helper so that every composition
+function shares a standard set of flags, environment variables, and defaults.
+
+Usage in a function's main.py::
+
+    import click
+    from crossplane.function import cli as sdkcli
+    from function import fn
+
+    @click.command()
+    @sdkcli.standard_options
+    def cli(**kwargs):
+        sdkcli.run(fn.FunctionRunner(), **kwargs)
+
+To add custom options, stack them with the decorator::
+
+    @click.command()
+    @sdkcli.standard_options
+    @click.option("--cache-size", default=100, envvar="CACHE_SIZE")
+    def cli(cache_size, **kwargs):
+        runner = fn.FunctionRunner(cache_size=cache_size)
+        sdkcli.run(runner, **kwargs)
+"""
+
+import functools
+from collections.abc import Callable
+from typing import TypeVar
+
+import click
+
+from crossplane.function import logging, runtime
+from crossplane.function.proto.v1 import run_function_pb2_grpc as grpcv1
+
+F = TypeVar("F", bound=Callable)
+
+DEFAULT_ADDRESS = "0.0.0.0:9443"
+DEFAULT_MAX_RECV_MESSAGE_SIZE = 4  # MB
+
+
+def standard_options(func: F) -> F:
+    """Apply the standard Composition Function CLI options to a Click command."""
+
+    @click.option(
+        "--max-recv-message-size",
+        type=int,
+        default=DEFAULT_MAX_RECV_MESSAGE_SIZE,
+        show_default=True,
+        envvar="MAX_RECV_MESSAGE_SIZE",
+        help="Maximum size of received gRPC messages in MB.",
+    )
+    @click.option(
+        "--insecure",
+        is_flag=True,
+        envvar="INSECURE",
+        help="Run without mTLS credentials. "
+        "If you supply this flag --tls-server-certs-dir will be ignored.",
+    )
+    @click.option(
+        "--tls-server-certs-dir",
+        "--tls-certs-dir",
+        "tls_certs_dir",
+        envvar="TLS_SERVER_CERTS_DIR",
+        help="Serve using mTLS certificates.",
+    )
+    @click.option(
+        "--address",
+        default=DEFAULT_ADDRESS,
+        show_default=True,
+        envvar="ADDRESS",
+        help="Address at which to listen for gRPC connections.",
+    )
+    @click.option(
+        "--debug",
+        "-d",
+        is_flag=True,
+        envvar="DEBUG",
+        help="Emit debug logs.",
+    )
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        return func(*args, **kwargs)
+
+    return wrapper
+
+
+def run(  # noqa: PLR0913
+    function_runner: grpcv1.FunctionRunnerServiceServicer,
+    *,
+    debug: bool,
+    address: str,
+    tls_certs_dir: str | None,
+    insecure: bool,
+    max_recv_message_size: int,
+) -> None:
+    """Start a composition function gRPC server with standard options."""
+    level = logging.Level.DEBUG if debug else logging.Level.INFO
+    logging.configure(level=level)
+
+    size_bytes = max_recv_message_size * 1024 * 1024
+    options = [
+        ("grpc.max_receive_message_length", size_bytes),
+        ("grpc.max_send_message_length", size_bytes),
+    ]
+
+    runtime.serve(
+        function_runner,
+        address,
+        creds=runtime.load_credentials(tls_certs_dir),
+        insecure=insecure,
+        options=options,
+    )

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

@@ -163,13 +163,16 @@ def require_resources(  # noqa: PLR0913
         namespace: The namespace to search in (optional).
 
     Raises:
-        ValueError: If both match_name and match_labels are provided, or neither.
+        ValueError: If both match_name and match_labels are provided.
 
     This tells Crossplane to fetch the specified resources and include them
     in the next call to the function in req.required_resources[name].
+
+    If neither match_name nor match_labels is provided, all resources of the
+    given api_version and kind are matched.
     """
-    if (match_name is None) == (match_labels is None):
-        msg = "Exactly one of match_name or match_labels must be provided"
+    if match_name is not None and match_labels is not None:
+        msg = "match_name and match_labels are mutually exclusive"
         raise ValueError(msg)
 
     selector = fnv1.ResourceSelector(

{crossplane_function_sdk_python-0.13.0 → crossplane_function_sdk_python-0.15.0}/crossplane/function/runtime.py

@@ -70,7 +70,7 @@ def load_credentials(tls_certs_dir: str) -> grpc.ServerCredentials:
 
 
 def serve(
-    function: grpcv1.FunctionRunnerService,
+    function: grpcv1.FunctionRunnerServiceServicer,
     address: str,
     *,
     creds: grpc.ServerCredentials,
@@ -95,7 +95,10 @@ def serve(
     are supplied.
     """
     # Define the loop before the server so everything uses the same loop.
-    loop = asyncio.get_event_loop()
+    try:
+        loop = asyncio.get_event_loop()
+    except RuntimeError:
+        loop = asyncio.new_event_loop()
 
     server = grpc.aio.server(options=options)
 
@@ -134,20 +137,20 @@ def serve(
         loop.close()
 
 
-class BetaFunctionRunner(grpcv1beta1.FunctionRunnerService):
+class BetaFunctionRunner(grpcv1beta1.FunctionRunnerServiceServicer):
     """A BetaFunctionRunner handles beta gRPC RunFunctionRequests.
 
-    It handles requests by passing them to a wrapped v1.FunctionRunnerService.
+    It handles requests by passing them to a wrapped v1.FunctionRunnerServiceServicer.
     Incoming v1beta1 requests are converted to v1 by round-tripping them through
     serialization. Outgoing requests are converted from v1 to v1beta1 the same
     way.
     """
 
-    def __init__(self, wrapped: grpcv1.FunctionRunnerService):
+    def __init__(self, wrapped: grpcv1.FunctionRunnerServiceServicer):
         """Create a new BetaFunctionRunner."""
         self.wrapped = wrapped
 
-    async def RunFunction(  # noqa: N802  # gRPC requires this name.
+    async def RunFunction(  # noqa: N802  # gRPC requires this name. # pyright: ignore[reportIncompatibleMethodOverride]
         self, req: fnv1beta1.RunFunctionRequest, context: grpc.aio.ServicerContext
     ) -> fnv1beta1.RunFunctionResponse:
         """Run the underlying function."""

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

@@ -18,9 +18,10 @@ classifiers = [
 ]
 
 dependencies = [
-  "grpcio==1.81.0",
+  "click==8.*",
+  "grpcio==1.84.0",
   "grpcio-reflection==1.*",
-  "protobuf==7.35.0", # Must be compatible with grpcio-tools.
+  "protobuf==7.36.1", # Must be compatible with grpcio-tools.
   "pydantic==2.*",
   "structlog==26.*",
 ]

{crossplane_function_sdk_python-0.13.0 → crossplane_function_sdk_python-0.15.0}/tests/test_response.py

@@ -233,6 +233,21 @@ class TestResponse(unittest.TestCase):
                     match_name="worker-1",
                 ),
             ),
+            TestCase(
+                reason="Should match all resources of a kind with no match field.",
+                rsp=fnv1.RunFunctionResponse(),
+                name="all-pods",
+                api_version="v1",
+                kind="Pod",
+                match_name=None,
+                match_labels=None,
+                namespace="default",
+                want_selector=fnv1.ResourceSelector(
+                    api_version="v1",
+                    kind="Pod",
+                    namespace="default",
+                ),
+            ),
         ]
 
         for case in cases:
@@ -270,17 +285,6 @@ class TestResponse(unittest.TestCase):
                 match_labels={"app": "test"},
             )
 
-        # Should raise ValueError if neither match_name nor match_labels are provided
-        with self.assertRaises(ValueError):
-            response.require_resources(
-                rsp,
-                "test",
-                "v1",
-                "Pod",
-                match_name=None,
-                match_labels=None,
-            )
-
     def test_require_schema(self) -> None:
         @dataclasses.dataclass
         class TestCase: