Add PyPi build and publish, fix --help

Author: Patrick J. McNerthney

.github/workflows/ci.yaml

@@ -14,7 +14,8 @@ on:
 
 env:
   # Common versions
-  PYTHON_VERSION: '3.12.11' # TODO: Used?
+  PYTHON_VERSION: '3.13.7' # TODO: Used?
+  HATCH_VERSION: '1.12.0'
   DOCKER_BUILDX_VERSION: 'v0.26.1'
 
   # These environment variables are important to the Crossplane CLI install.sh
@@ -32,6 +33,9 @@ env:
   # XPKG: xpkg.upbound.io/${{ github.repository}}
   CROSSPLANE_REGORG: ghcr.io/${{ github.repository}}
 
+  # The PyPi project version to push. The default is v0.0.0+gitdate-gitsha.
+  PYPI_VERSION: ${{ inputs.version }}
+
   # The package version to push. The default is 0.0.0-gitsha.
   XPKG_VERSION: ${{ inputs.version }}
 
@@ -86,11 +90,49 @@ jobs:
         #remove-link-from-badge: false
         #unique-id-for-comment: python3.8
 
+  build-pypi:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Setup Hatch
+        run: pipx install hatch==${{ env.HATCH_VERSION }}
+
+      # If a version wasn't explicitly passed as a workflow_dispatch input we
+      # default to version v0.0.0+<git-commit-date>-<git-short-sha>, for example
+      # v0.0.0+20231101115142-1091066df799. This is a simple implementation of
+      # Go's pseudo-versions: https://go.dev/ref/mod#pseudo-versions.
+      - name: Set Default PyPI Project Version
+        if: env.PYPI_VERSION == ''
+        run: echo "PYPI_VERSION=v0.0.0+$(date -d@$(git show -s --format=%ct) +%Y%m%d%H%M%S)-$(git rev-parse --short=12 HEAD)" >> $GITHUB_ENV
+
+      - name: Set PyPI Project Version
+        run: hatch version ${{ env.PYPI_VERSION }}
+
+      - name: Build Sdist and Wheel
+        run: hatch build
+
+      - name: Upload Sdist and Wheel to GitHub
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: "dist/*"
+          if-no-files-found: error
+          retention-days: 1
+
   # We want to build most packages for the amd64 and arm64 architectures. To
   # speed this up we build single-platform packages in parallel. We then upload
   # those packages to GitHub as a build artifact. The push job downloads those
   # artifacts and pushes them as a single multi-platform package. 
-  build:
+  build-xpkg:
+    needs:
+      - build-pypi
     runs-on: ubuntu-24.04
     strategy:
       fail-fast: true
@@ -113,6 +155,13 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Download Wheel from GitHub
+        uses: actions/download-artifact@v5
+        with:
+          name: dist
+          pattern: '*.whl'
+          path: dist
+
       # We ask Docker to use GitHub Action's native caching support to speed up
       # the build, per https://docs.docker.com/build/cache/backends/gha/.
       - name: Build Runtime
@@ -142,16 +191,38 @@ jobs:
           if-no-files-found: error
           retention-days: 1
 
+  publish-pypi:
+    # Don't publish unless we were run with an explicit version.
+    if: ${{ inputs.version != '' }}
+    needs:
+      - build-xpkg # only publish if xpkg builds succeeds
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Download Sdist and Wheel from GitHub
+        uses: actions/download-artifact@v5
+        with:
+          name: dist
+          path: dist
+
+      - name: Setup Hatch
+        run: pipx install hatch==${{ env.HATCH_VERSION }}
+
+      - name: Publish to PyPI
+        env:
+          HATCH_INDEX_USER: __token__
+          HATCH_INDEX_AUTH: ${{ secrets.PYPI_API_TOKEN }}
+        run: hatch publish --no-prompt
+
   # This job downloads the single-platform packages built by the build job, and
   # pushes them as a multi-platform package. We only push the package it the
   # XPKG_ACCESS_ID and XPKG_TOKEN secrets were provided.
-  push:
+  push-xpkg:
+    needs:
+      - build-xpkg
     runs-on: ubuntu-24.04
     permissions:
       contents: read
       packages: write
-    needs:
-      - build
     steps:
       - name: Checkout
         uses: actions/checkout@v4

.gitignore

@@ -211,4 +211,6 @@ marimo/_lsp/
 __marimo__/
 
 # function-pythonic
+crossplane/pythonic/__version__.py
+pocs/
 pythonic-packages/

Dockerfile

@@ -1,17 +1,11 @@
 FROM python:3.13-slim-trixie AS image
 
-WORKDIR /root/pythonic
-COPY pyproject.toml /root/pythonic
-COPY crossplane /root/pythonic/crossplane
+COPY dist/*.whl /root
 WORKDIR /
 RUN \
   set -eux && \
-  cd /root/pythonic && \
-  pip install --root-user-action ignore --no-build-isolation setuptools==80.9.0 && \
-  pip install --root-user-action ignore --no-build-isolation . && \
-  pip uninstall --root-user-action ignore --yes setuptools && \
-  cd .. && \
-  rm -rf .cache pythonic && \
+  pip install --root-user-action ignore --no-build-isolation /root/*.whl && \
+  rm -rf /root/*.whl /root/.cache && \
   groupadd --gid 2000 pythonic && \
   useradd --uid 2000 --gid pythonic --home-dir /opt/pythonic --create-home --shell /usr/sbin/nologin pythonic
 

README.md

@@ -59,7 +59,6 @@ metadata:
 spec:
   package: ghcr.io/fortra/function-pythonic:v0.0.7
 ```
-
 ## Composed Resource Dependencies
 
 function-pythonic automatically handles dependencies between composed resources.
@@ -253,34 +252,46 @@ selection. For now, use matchLabels and filter the results if required.
 RequiredResources acts like a Python list to provide access to the found required resources.
 Each resource in the list is the following RequiredResource class:
 
-| Field | Description |
-| ----- | ----------- |
-| RequiredResource.name | The required resource name |
-| RequiredResource.observed | Low level direct access to the observed required resource |
-| RequiredResource.apiVersion | The required resource apiVersion |
-| RequiredResource.kind | The required resource kind |
-| RequiredResource.metadata | The required resource metadata |
-| RequiredResource.spec | The required resource spec |
-| RequiredResource.data | The required resource data |
-| RequiredResource.status | The required resource status |
-| RequiredResource.conditions | The required resource conditions |
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| RequiredResource.name | String | The required resource name |
+| RequiredResource.observed | Map | Low level direct access to the observed required resource |
+| RequiredResource.apiVersion | String | The required resource apiVersion |
+| RequiredResource.kind | String | The required resource kind |
+| RequiredResource.metadata | Map | The required resource metadata |
+| RequiredResource.spec | Map | The required resource spec |
+| RequiredResource.data | Map | The required resource data |
+| RequiredResource.status | Map | The required resource status |
+| RequiredResource.conditions | Map | The required resource conditions |
 
 ### Conditions
 
-The `conditions` field is a map of the resource's status conditions array, with
-the map key being the condition type.
+The `BaseCompsite.conditions`, `Resource.conditions`, and `RequiredResource.conditions` fields
+are maps of that entity's status conditions array, with the map key being the condition type.
+The fields are read only for `Resource.conditions` and `RequiredResource.conditions`.
 
-| Field | Description |
-| ----- | ----------- |
-| Condition.type | The condtion type |
-| Condition.status | RequiredResource.observed | Low level direct access to the observed required resource |
-| RequiredResource.apiVersion | The required resource apiVersion |
-| RequiredResource.kind | The required resource kind |
-| RequiredResource.metadata | The required resource metadata |
-| RequiredResource.spec | The required resource spec |
-| RequiredResource.data | The required resource data |
-| RequiredResource.status | The required resource status |
-| RequiredResource.conditions | The required resource conditions |
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| Condition.type | String | The condtion type, or name |
+| Condition.status | Boolean | The condition status |
+| Condition.reason | String | PascalCase, machine-readable reason for this condition |
+| Condition.message | String | Human-readable details about the condition |
+| Condition.lastTransitionTime | Timestamp | Last transition time, read only |
+| Condition.claim | Boolean | Also apply the condition the claim |
+
+### Events
+
+The `BaseComposite.events` field is a list of events to apply to the Composite and
+optionally to the Claim.
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| Event.info | Boolean | Normal informational event |
+| Event.warning | Boolean | Warning level event |
+| Event.fatal | Boolean | Fatal events also terminate composing the Composite |
+| Event.reason | String | PascalCase, machine-readable reason for this event |
+| Event.message | String | Human-readable details about the event |
+| Event.claim | Boolean | Also apply the event to the claim |
 
 ## Single use Composites
 
@@ -301,6 +312,85 @@ spec:
         self.status.composite = 'Hello, World!'
 ```
 
+## Quick Start Development
+
+The following example demonstrates how to locally render function-python
+compositions. First, install the `crossplane-function-pythonic` python
+package into the python environment:
+```shell
+$ pip install crossplane-function-pythonic
+```
+Next, create the following files:
+#### xr.yaml
+```yaml
+apiVersion: pythonic.fortra.com/v1alpha1
+kind: Hello
+metadata:
+  name: world
+spec:
+  who: World
+```
+#### composition.yaml
+```yaml
+apiVersion: apiextensions.crossplane.io/v1
+kind: Composition
+metadata:
+  name: hellos.pythonic.fortra.com
+spec:
+  compositeTypeRef:
+    apiVersion: pythonic.fortra.com/v1alpha1
+    kind: Hello
+  mode: Pipeline
+  pipeline:
+  - step: pythonic
+    functionRef:
+      name: function-pythonic
+    input:
+      apiVersion: pythonic.fn.fortra.com/v1alpha1
+      kind: Composite
+      composite: |
+        class Composite(BaseComposite):
+          def compose(self):
+            self.status.greeting = f"Hello, {self.spec.who}!"
+```
+#### functions.yaml
+```yaml
+apiVersion: pkg.crossplane.io/v1beta1
+kind: Function
+metadata:
+  name: function-pythonic
+  annotations:
+    render.crossplane.io/runtime: Development
+spec:
+  package: ghcr.io/fortra/function-pythonic:v0.0.7
+```
+In one terminal session, run function-pythonic:
+```shell
+$ function-pythonic --insecure --debug
+[2025-08-21 15:32:37.966] grpc._cython.cygrpc  [DEBUG   ] Using AsyncIOEngine.POLLER as I/O engine
+```
+In another terminal session, render the Composite:
+```shell
+$ crossplane render xr.yaml composition.yaml functions.yaml
+---
+apiVersion: pythonic.fortra.com/v1alpha1
+kind: Hello
+metadata:
+  name: world
+status:
+  conditions:
+  - lastTransitionTime: "2024-01-01T00:00:00Z"
+    reason: Available
+    status: "True"
+    type: Ready
+  - lastTransitionTime: "2024-01-01T00:00:00Z"
+    message: All resources are composed
+    reason: AllComposed
+    status: "True"
+    type: ResourcesComposed
+  greeting: Hello, World!
+```
+
 ## ConfigMap Packages
 
 ConfigMap based python packages are enable using the `--packages` and

crossplane/pythonic/__init__.py

@@ -1,3 +1,4 @@
+
 import base64
 
 from .composite import BaseComposite

crossplane/pythonic/__version__.py

@@ -0,0 +1,2 @@
+# This is set at build time, using "hatch version"
+__version__ = "0.0.0"

crossplane/pythonic/function.py

@@ -220,30 +220,30 @@ async def run_function(self, request):
 
     def trimFullName(self, name):
         name = name.split('.')
-        ix = 0
         for values in (
-                ('request', 'response'),
-                ('observed', 'desired'),
-                ('resources', 'extra_resources'),
-                None,
-                ('resource', 'items'),
+                ('request', 'observed', 'resources', None, 'resource'),
+                ('request', 'extra_resources', None, 'items', 'resource'),
+                ('response', 'desired', 'resources', None, 'resource'),
         ):
-            if values:
-                if ix < len(name):
+            if len(values) <= len(name):
+                for ix, value in enumerate(values):
+                    if value and value != name[ix] and not name[ix].startswith(f"{value}["):
+                       break
+                else:
+                    ix = 0
                     for value in values:
-                        if name[ix] == value:
-                            del name[ix]
-                            break
-                        if name[ix].startswith(f"{value}["):
-                            if ix:
+                        if value:
+                            if value == name[ix]:
+                                del name[ix]
+                            elif ix:
                                 name[ix-1] += name[ix][len(value):]
                                 del name[ix]
                             else:
                                 name[ix] = name[ix][len(value):]
                                 ix += 1
-                            break
-            else:
-                ix += 1
+                        else:
+                            ix += 1
+                    break
         return '.'.join(name)