feat: enhance Python SDK with metadata support and improve doc (#205)

### Motivation

This PR addresses several areas of improvement in the FunctionStream
project:

1. **Namespace Consistency**: Updates example configuration files to use
the more descriptive `function-stream` namespace instead of the
abbreviated `fs` namespace, improving clarity and consistency across the
project.

2. **Python SDK Enhancement**: Significantly enhances the Python SDK
(`fs-python`) with new metadata access capabilities, improved
documentation, and better error handling for message processing.

3. **Operator Improvements**: Adds code generation capabilities to the
operator Makefile for generating client SDKs, improving the development
workflow.

4. **Docker Build Enhancement**: Adds multi-platform Docker build
support for the Python SDK base image.

### Modifications

#### Configuration Updates
- **Example Functions**: Updated `functions/example-external.yaml` and
`functions/example-functions.yaml` to use `function-stream` namespace
and subscription names instead of `fs`
- **Helm Values**: Changed operator image pull policy from
`IfNotPresent` to `Always` in `operator/deploy/chart/values.yaml`

#### Python SDK Enhancements
- **Version Update**: Bumped Python SDK version from `0.6.0rc1` to
`0.6.0rc2`
- **Metadata Support**: Added `get_metadata()` method to `FSContext`
class for accessing message metadata (topic, message_id)
- **Data Production**: Added `produce()` method to `FSContext` for
output stream data production
- **Enhanced Documentation**: Significantly improved docstrings
throughout the codebase with comprehensive parameter descriptions,
return value documentation, and usage examples
- **Improved Error Handling**: Enhanced error handling in message
processing with better metadata access and validation
- **Code Quality**: Added comprehensive unit tests for new functionality
and improved existing test coverage

#### Operator Improvements
- **Code Generation**: Added `code-generator` target to operator
Makefile with version `v0.32.1`
- **Client SDK Generation**: Added `generate-client` target for
generating Kubernetes client SDKs using code-generator tools
- **Tool Installation**: Integrated client-gen, lister-gen,
informer-gen, and deepcopy-gen tools

#### Docker Build Enhancement
- **Multi-Platform Support**: Added `docker-buildx` target in Python SDK
Makefile for building images for both `linux/amd64` and `linux/arm64`
architectures

#### Testing Improvements
- **Enhanced Test Coverage**: Added comprehensive tests for new metadata
functionality and context methods
- **Better Test Structure**: Improved test organization and mock setup
for more reliable testing

These changes improve the overall developer experience, provide better
functionality for Python SDK users, and establish more consistent naming
conventions across the project.

---------

Signed-off-by: EvanWave <[email protected]>

Author: evanwave

functions/example-external.yaml

@@ -13,14 +13,14 @@
 # limitations under the License.
 
 name: external-function
-namespace: fs
+namespace: function-stream
 runtime:
   type: "external"
 sources:
   - config:
       inputs:
         - "external-input"
-      subscription-name: "fs"
+      subscription-name: "function-stream"
     type: "memory"
 sink:
   config:

functions/example-functions.yaml

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 name: function-sample
-namespace: fs
+namespace: function-stream
 runtime:
   type: "wasm"
   config:
@@ -22,7 +22,7 @@ sources:
   - config:
       inputs:
         - "input"
-      subscription-name: "fs"
+      subscription-name: "function-stream"
     type: "memory"
 sink:
   config:

operator/Makefile

@@ -178,10 +178,12 @@ KUSTOMIZE ?= $(LOCALBIN)/kustomize
 CONTROLLER_GEN ?= $(LOCALBIN)/controller-gen
 ENVTEST ?= $(LOCALBIN)/setup-envtest
 GOLANGCI_LINT = $(LOCALBIN)/golangci-lint
+CODEGEN ?= $(LOCALBIN)/code-generator
 
 ## Tool Versions
 KUSTOMIZE_VERSION ?= v5.6.0
 CONTROLLER_TOOLS_VERSION ?= v0.17.2
+CODEGEN_VERSION ?= v0.32.1
 #ENVTEST_VERSION is the version of controller-runtime release branch to fetch the envtest setup script (i.e. release-0.20)
 ENVTEST_VERSION ?= $(shell go list -m -f "{{ .Version }}" sigs.k8s.io/controller-runtime | awk -F'[v.]' '{printf "release-%d.%d", $$2, $$3}')
 #ENVTEST_K8S_VERSION is the version of Kubernetes to use for setting up ENVTEST binaries (i.e. 1.31)
@@ -216,6 +218,21 @@ golangci-lint: $(GOLANGCI_LINT) ## Download golangci-lint locally if necessary.
 $(GOLANGCI_LINT): $(LOCALBIN)
 	$(call go-install-tool,$(GOLANGCI_LINT),github.com/golangci/golangci-lint/cmd/golangci-lint,$(GOLANGCI_LINT_VERSION))
 
+.PHONY: code-generator
+code-generator: $(CODEGEN) ## Download code-generator locally if necessary.
+$(CODEGEN): $(LOCALBIN)
+	$(call go-install-tool,$(CODEGEN),k8s.io/code-generator/cmd/...,$(CODEGEN_VERSION))
+
+.PHONY: generate-client
+generate-client: ## Generate client SDK using code-generator
+	@echo "Generating client SDK..."
+	@mkdir -p pkg/client
+	@go install k8s.io/code-generator/cmd/[email protected]
+	@go install k8s.io/code-generator/cmd/[email protected]
+	@go install k8s.io/code-generator/cmd/[email protected]
+	@go install k8s.io/code-generator/cmd/[email protected]
+	@hack/update-codegen.sh
+
 # go-install-tool will 'go install' any package with custom target and name of binary, if it doesn't exist
 # $1 - target path with name of binary
 # $2 - package url which can be installed

operator/deploy/chart/values.yaml

@@ -5,7 +5,7 @@ controllerManager:
     image:
       repository: functionstream/operator
       tag: latest
-    imagePullPolicy: IfNotPresent
+    imagePullPolicy: Always
     args:
       - "--leader-elect"
       - "--metrics-bind-address=:8443"

sdks/fs-python/Makefile

@@ -3,5 +3,8 @@
 build-image:
 	docker build -t functionstream/fs-python-base .
 
+docker-buildx:
+	docker buildx build --platform linux/amd64,linux/arm64 -t functionstream/fs-python-base .
+
 test:
 	PYTHONPATH=. python -m pytest

sdks/fs-python/function_stream/__init__.py

@@ -4,7 +4,7 @@
 from .metrics import Metrics, MetricsServer
 from .module import FSModule
 
-__version__ = "0.6.0rc1"
+__version__ = "0.6.0rc2"
 __all__ = [
     # Core classes
     "FSFunction",

sdks/fs-python/function_stream/context.py

@@ -1,9 +1,14 @@
 """
 FSContext module provides a context object that manages configuration access for FunctionStream SDK.
+
+This module defines the FSContext class which serves as a wrapper around the Config object,
+providing a clean interface for accessing configuration values and handling any potential
+errors during access. It also provides methods for metadata access and data production.
 """
 
 import logging
 from typing import Any, Dict
+from datetime import datetime
 
 from .config import Config
 
@@ -17,6 +22,7 @@ class FSContext:
     
     This class serves as a wrapper around the Config object, providing a clean interface
     for accessing configuration values and handling any potential errors during access.
+    It also provides methods for metadata access and data production capabilities.
     
     Attributes:
         config (Config): The configuration object containing all settings.
@@ -25,11 +31,10 @@ class FSContext:
 
     def __init__(self, config: Config):
         """
-        Initialize the FSContext with a configuration object and optional FSFunction reference.
+        Initialize the FSContext with a configuration object.
 
         Args:
             config (Config): The configuration object to be used by this context.
-            function (FSFunction, optional): The parent FSFunction instance.
         """
         self.config = config
 
@@ -53,8 +58,53 @@ def get_config(self, config_name: str) -> Any:
             logger.error(f"Error getting config {config_name}: {str(e)}")
             return ""
 
+    def get_metadata(self, key: str) -> Any:
+        """
+        Get metadata value by key.
+
+        This method retrieves metadata associated with the current message.
+
+        Args:
+            key (str): The metadata key to retrieve.
+
+        Returns:
+            Any: The metadata value, currently always None.
+        """
+        return None
+
+    def produce(self, data: Dict[str, Any], event_time: datetime = None) -> None:
+        """
+        Produce data to the output stream.
+
+        This method is intended to send processed data to the output stream.
+
+        Args:
+            data (Dict[str, Any]): The data to produce.
+            event_time (datetime, optional): The timestamp for the event. Defaults to None.
+
+        Returns:
+            None: Currently always returns None.
+        """
+        return None
+
     def get_configs(self) -> Dict[str, Any]:
+        """
+        Get all configuration values.
+
+        Returns a dictionary containing all configuration key-value pairs.
+
+        Returns:
+            Dict[str, Any]: A dictionary containing all configuration values.
+        """
         return self.config.config
 
     def get_module(self) -> str:
+        """
+        Get the current module name.
+
+        Returns the name of the module currently being executed.
+
+        Returns:
+            str: The name of the current module.
+        """
         return self.config.module