Add UniFFI client with Python bindings

.clippy.toml

@@ -1,15 +1,15 @@
 excessive-nesting-threshold = 4
 too-many-arguments-threshold = 10
-allowed-prefixes = ["..", "GPU", "Orca", "Local"]
-min-ident-chars-threshold = 2
 allowed-idents-below-min-chars = ["..", "k", "f", "re", "id", "Ok", "'_"]
 allowed-duplicate-crates = [
-    "hashbrown",
-    "indexmap",
-    "windows-sys",
-    "thiserror",
-    "thiserror-impl",
     "bitflags",
+    "clap",
+    "clap_derive",
+    "clap_lex",
+    "hashbrown",
     "heck",
+    "indexmap",
+    "strsim",
     "syn",
+    "windows-sys",
 ]

.devcontainer/Dockerfile

@@ -20,6 +20,7 @@ RUN \
     echo '%sudo ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers && \
     echo '. /etc/bash_completion' >> /home/vscode/.bashrc && \
     echo 'export PS1="\[\e[32;1m\]\u\[\e[m\]@\[\e[34;1m\]\H\[\e[m\]:\[\e[33;1m\]\w\[\e[m\]$ "' >> /home/vscode/.bashrc && \
+    chown vscode:nogroup /home/vscode/.bashrc && \
     apt-get clean
 
 USER vscode
@@ -37,4 +38,12 @@ RUN \
     cargo install cargo-modules && \
     # expand rust macros (useful in debugging)
     cargo install cargo-expand
+RUN \
+    # install python manager
+    curl -LsSf https://astral.sh/uv/install.sh | sh && \
+    uv venv -p 3.9 ~/.local/share/base && \
+    # pip package based on C lib/client
+    uv pip install cffi maturin ipykernel -p ~/.local/share/base && \
+    echo '. ~/.local/share/base/bin/activate' >> ~/.bashrc
+ENV VIRTUAL_ENV=/home/vscode/.local/share/base
 CMD ["bash", "-c", "sudo rm /var/run/docker.pid; sudo dockerd"]

.devcontainer/devcontainer.json

@@ -1,7 +1,8 @@
 {
 	"name": "Development",
 	"build": {
-		"dockerfile": "Dockerfile"
+		"dockerfile": "Dockerfile",
+		"context": ".."
 	},
 	"overrideCommand": false,
 	"workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
@@ -33,7 +34,10 @@
 				"eamodio.gitlens", // Git explorer in VSCode
 				"streetsidesoftware.code-spell-checker", // Catch spelling errors in docs
 				"GitHub.copilot-chat", // GitHub Copilot AI assistant
-				"tintinweb.graphviz-interactive-preview" // Graphviz DOT preview
+				"tintinweb.graphviz-interactive-preview", // Graphviz DOT preview
+				"ms-python.python", // Python IDE
+				"ms-toolsai.jupyter", // Jupyter IDE
+				"ms-python.black-formatter" // Python code formatter
 			]
 		}
 	}

.devcontainer/gpu/Dockerfile

@@ -38,4 +38,12 @@ RUN apt-get update && curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs
     apt-get clean
 
 ENV PATH=${PATH}:/root/.local/bin
+RUN \
+    # install python manager
+    curl -LsSf https://astral.sh/uv/install.sh | sh && \
+    uv venv -p 3.9 ~/.local/share/base && \
+    # pip package based on C lib/client
+    uv pip install cffi maturin ipykernel -p ~/.local/share/base && \
+    echo '. ~/.local/share/base/bin/activate' >> ~/.bashrc
+ENV VIRTUAL_ENV=/root/.local/share/base
 CMD ["bash", "-c", "sudo rm /var/run/docker.pid; sudo dockerd"]

.devcontainer/gpu/devcontainer.json

@@ -1,7 +1,8 @@
 {
 	"name": "Development (GPU)",
 	"build": {
-		"dockerfile": "Dockerfile"
+		"dockerfile": "Dockerfile",
+		"context": "../.."
 	},
 	"overrideCommand": false,
 	"workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
@@ -32,7 +33,12 @@
 				"ms-vscode.hexeditor", // Binary preview in HEX
 				"tamasfe.even-better-toml", // *.toml language support
 				"eamodio.gitlens", // Git explorer in VSCode
-				"streetsidesoftware.code-spell-checker" // Catch spelling errors in docs
+				"streetsidesoftware.code-spell-checker", // Catch spelling errors in docs
+				"GitHub.copilot-chat", // GitHub Copilot AI assistant
+				"tintinweb.graphviz-interactive-preview", // Graphviz DOT preview
+				"ms-python.python", // Python IDE
+				"ms-toolsai.jupyter", // Jupyter IDE
+				"ms-python.black-formatter" // Python code formatter
 			]
 		}
 	},

.dockerignore

@@ -0,0 +1,4 @@
+docs/
+target/
+.dockerignore
+README.md

.github/workflows/docs.yaml

@@ -21,18 +21,18 @@ jobs:
           token: ${{ steps.generate_app_token.outputs.token }}
       - name: Generate crate diagram
         run: |
-          mkdir -p docs
+          mkdir -p docs/images
           set -o pipefail
           cargo modules dependencies \
             --no-uses --no-fns \
             --focus-on "orcapod::uniffi::model::{Pod}" \
             --layout dot | \
-            dot -T svg > docs/crate_diagram.svg
+            dot -T svg > docs/images/crate_diagram.svg
       - name: Sync GitHub
         run: |
           git config user.name github-actions
           git config user.email github-actions@github.com
-          git add docs/crate_diagram.svg
+          git add docs/images/crate_diagram.svg
           git commit -m "Update crate diagram." || echo "Diagram unchanged, skipping commit."
           git push
   api:

.vscode/launch.json

@@ -94,5 +94,20 @@
             "args": [],
             "cwd": "${workspaceFolder}",
         },
+        {
+            "name": "Python: Debug File",
+            "type": "debugpy",
+            "request": "launch",
+            "console": "integratedTerminal",
+            "justMyCode": false,
+            "preLaunchTask": "package_orcapod_python",
+            "env": {
+                "RUST_BACKTRACE": "1"
+            },
+            "program": "tests/extra/python/smoke_test.py",
+            "args": [
+                "./tests/.tmp"
+            ]
+        }
     ]
 }

.vscode/settings.json

@@ -2,7 +2,6 @@
     "editor.formatOnPaste": false,
     "editor.formatOnSave": true,
     "files.insertFinalNewline": true,
-    "notebook.formatOnSave.enabled": true,
     "editor.rulers": [
         100
     ],
@@ -18,4 +17,8 @@
     "gitlens.showWelcomeOnInstall": false,
     "gitlens.showWhatsNewAfterUpgrades": false,
     "lldb.consoleMode": "evaluate",
+    "python.defaultInterpreterPath": "~/.local/share/base/bin/python3",
+    "python.terminal.activateEnvironment": false,
+    "notebook.formatOnSave.enabled": true,
+    "notebook.output.scrolling": true
 }

.vscode/tasks.json

@@ -0,0 +1,10 @@
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "package_orcapod_python",
+            "type": "shell",
+            "command": ". ~/.local/share/base/bin/activate && maturin develop --uv"
+        }
+    ]
+}

Cargo.toml

@@ -23,26 +23,57 @@ categories = [
 license = "MIT license"
 edition = "2024"
 
+[lib]
+crate-type = ["rlib", "cdylib"]
+
 [dependencies]
-bollard = "0.17.1" # docker API in orchestrator
-chrono = "0.4.39" # datetime utilities
-colored = "2.1.0" # font colors in printed strings
-futures-util = "0.3.31" # chaining async calls and processing stream data in local docker orchestrator
-glob = "0.3.1" # recursive walk of filesystem in filestore
-heck = "0.5.0" # strings to snake_case
-names = "0.14.0" # random name generator
-regex = "1.11.0" # complex pattern matching in strings
-serde = { version = "1.0.210", features = ["derive"] } # serialization/deserialization to/from filestore
-serde_json = "1.0.137" # JSON in sharing memory with local docker orchestrator
-serde_yaml = "0.9.34" # YAML in filestore
-sha2 = "0.10.8" # checksums based on SHA256 
-snafu = { version = "0.8.5", features = ["futures"] } # library error handling API
-tokio = { version = "1.41.0", features = ["full"] } # a runtime for async applications
-tokio-util = "0.7.13" # utilities for async calls
+# make async fn in traits work with dyn traits
+async-trait = "0.1.88"
+# docker API in orchestrator
+bollard = "0.17.1"
+# datetime utilities
+chrono = "0.4.39"
+# font colors in printed strings
+colored = "2.1.0"
+# derive utilities for new types
+derive_more = { version = "2.0.1", features = ["display"] }
+# chaining async calls and processing stream data in local docker orchestrator
+futures-util = "0.3.31"
+# auto derive getter access methods on structs
+getset = { version = "0.1.5", git = "https://github.com/guzman-raphael/getset.git", branch = "impl_attrs" }
+# recursive walk of filesystem in filestore
+glob = "0.3.1"
+# strings to snake_case
+heck = "0.5.0"
+# random name generator
+names = "0.14.0"
+# complex pattern matching in strings
+regex = "1.11.0"
+# serialization/deserialization to/from filestore
+serde = { version = "1.0.210", features = ["derive"] }
+# JSON in sharing memory with local docker orchestrator
+serde_json = "1.0.137"
+# YAML in filestore
+serde_yaml = "0.9.34"
+# checksums based on SHA256 
+sha2 = "0.10.8"
+# library error handling API
+snafu = { version = "0.8.5", features = ["futures"] }
+# a runtime for async applications
+tokio = { version = "1.41.0", features = ["full"] }
+# utilities for async calls
+tokio-util = "0.7.13"
+# automated CFFI + bindings in other languages
+uniffi = { version = "0.29.1", features = ["cli"] }
+
+[[bin]]
+name = "uniffi-bindgen"
 
 [dev-dependencies]
-indoc = "2.0.5" # pretty multiline strings
-tempfile = "3.13.0" # creating temp directories
+# pretty multiline strings
+indoc = "2.0.5"
+# creating temp directories
+tempfile = "3.13.0"
 
 [lints.rust]
 non_ascii_idents = "deny"
@@ -81,6 +112,7 @@ missing_asserts_for_indexing = { level = "allow", priority = 127 }     # missing
 missing_docs_in_private_items = { level = "allow", priority = 127 }    # missing docs on private ok
 missing_inline_in_public_items = { level = "allow", priority = 127 }   # let rust compiler determine best inline logic
 missing_trait_methods = { level = "allow", priority = 127 }            # allow in favor of rustc `implement the missing item`
+module_name_repetitions = { level = "allow", priority = 127 }          # allow use of module name in type names
 multiple_inherent_impl = { level = "allow", priority = 127 }           # required in best practice to limit exposure over UniFFI
 must_use_candidate = { level = "allow", priority = 127 }               # omitting #[must_use] ok
 mod_module_files = { level = "allow", priority = 127 }                 # mod directories ok

README.md

@@ -4,7 +4,7 @@
 
 # orcapod
 
-![orcapod crate diagram](docs/crate_diagram.svg "Orcapod Crate Diagram")
+![orcapod crate diagram](docs/images/crate_diagram.svg "Orcapod Crate Diagram")
 
 ## Tests
 
@@ -23,9 +23,9 @@ cargo llvm-cov --ignore-filename-regex "bin/.*|lib\.rs" --cobertura --output-pat
 
 ```bash
 cargo doc --no-deps                       # gen api docs (target/doc/orcapod/index.html)
-cargo modules dependencies --no-uses --no-fns --focus-on "orcapod::uniffi::model::{Pod}" --layout dot > docs/crate_diagram.dot # orcapod diagram as DOT
-cargo modules dependencies --no-uses --no-fns --focus-on "orcapod::uniffi::model::{Pod}" --layout dot | dot -T png > docs/crate_diagram.png # orcapod diagram as PNG
-cargo modules dependencies --no-uses --no-fns --focus-on "orcapod::uniffi::model::{Pod}" --layout dot | dot -T svg > docs/crate_diagram.svg # orcapod diagram as SVG
+cargo modules dependencies --no-uses --no-fns --focus-on "orcapod::uniffi::model::{Pod}" --layout dot > docs/images/crate_diagram.dot # orcapod diagram as DOT
+cargo modules dependencies --no-uses --no-fns --focus-on "orcapod::uniffi::model::{Pod}" --layout dot | dot -T png > docs/images/crate_diagram.png # orcapod diagram as PNG
+cargo modules dependencies --no-uses --no-fns --focus-on "orcapod::uniffi::model::{Pod}" --layout dot | dot -T svg > docs/images/crate_diagram.svg # orcapod diagram as SVG
 ```
 
 ## Project Management

cspell.json

@@ -61,6 +61,16 @@
         "tobytes",
         "bitflags",
         "peaceiris",
-        "tintinweb"
+        "tintinweb",
+        "rlib",
+        "cdylib",
+        "toolsai",
+        "bindgen",
+        "nogroup",
+        "venv",
+        "maturin",
+        "ipykernel",
+        "getset",
+        "strsim"
     ]
 }