pythonnative 0.40.0__cp313-cp313-win_amd64.whl

pythonnative/sdk/module_codegen.py

@@ -0,0 +1,184 @@
+"""Typed module facades and native dispatch adapters from Python protocols."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .schema import MODULES
+
+
+def _types(schema: dict[str, Any]) -> tuple[str, str, str]:
+    if "anyOf" in schema:
+        variants = [item for item in schema["anyOf"] if item.get("type") != "null"]
+        if len(variants) == 1:
+            python, swift, kotlin = _types(variants[0])
+            return python + " | None", swift + "?", kotlin + "?"
+    return {
+        "string": ("str", "String", "String"),
+        "integer": ("int", "Int", "Int"),
+        "number": ("float", "Double", "Double"),
+        "boolean": ("bool", "Bool", "Boolean"),
+        "null": ("None", "Void", "Unit"),
+    }.get(schema.get("type", ""), ("Any", "Any", "Any"))
+
+
+def generate_modules() -> dict[str, str]:
+    """Generate native interfaces, checked dispatch, and typed Python calls."""
+    python = [
+        '"""Generated native module facades."""',
+        "from typing import Any",
+        "from pythonnative.native_modules.registry import native_module",
+        "",
+    ]
+    swift = ["import Foundation", ""]
+    kotlin = [
+        "package com.pythonnative.generated",
+        "",
+        "import org.json.JSONObject",
+        "import com.pythonnative.runtime.modules.NativeModule",
+        "import com.pythonnative.runtime.modules.Promise",
+        "",
+    ]
+    for name, module in sorted(MODULES.items()):
+        if not name.isidentifier():
+            raise ValueError(f"Invalid module name: {name!r}")
+        python.append(f"class {name}:")
+        swift.extend([f"public protocol {name}Implementation {{", "    init()"])
+        kotlin.append(f"interface {name}Implementation {{")
+        method_info = []
+        for method, contract in module.methods.items():
+            if not method.isidentifier():
+                raise ValueError(f"Invalid method name: {method!r}")
+            result_py, result_swift, result_kotlin = _types(contract["result"])
+            params_py, params_swift, params_kotlin, args = [], [], [], []
+            for key, schema in contract["arguments"].items():
+                if not key.isidentifier():
+                    raise ValueError(f"Invalid argument name: {key!r}")
+                pt, st, kt = _types(schema)
+                params_py.append(f"{key}: {pt}")
+                params_swift.append(f"{key}: {st}")
+                params_kotlin.append(f"{key}: {kt}")
+                args.append(key)
+            asynchronous = contract["async"]
+            python.extend(
+                [
+                    "    @staticmethod",
+                    f"    {'async ' if asynchronous else ''}def {method}("
+                    + ", ".join(params_py)
+                    + f") -> {result_py}:",
+                    f'        return {"await " if asynchronous else ""}native_module("{name}").'
+                    f'{"call_async" if asynchronous else "call"}("{method}"'
+                    + "".join(f", {key}={key}" for key in args)
+                    + ")",
+                    "",
+                ]
+            )
+            if asynchronous:
+                swift.append(
+                    f"    func {method}("
+                    + ", ".join(params_swift + [f"completion: @escaping (Result<{result_swift}, Error>) -> Void"])
+                    + ")"
+                )
+                kotlin.append(
+                    f"    fun {method}("
+                    + ", ".join(params_kotlin + [f"completion: (Result<{result_kotlin}>) -> Unit"])
+                    + ")"
+                )
+            else:
+                swift.append(f"    func {method}(" + ", ".join(params_swift) + f") throws -> {result_swift}")
+                kotlin.append(f"    fun {method}(" + ", ".join(params_kotlin) + f"): {result_kotlin}")
+            method_info.append((method, contract, args))
+        if not method_info:
+            python.append("    pass")
+        python.append("")
+        swift.extend(
+            [
+                "}",
+                "",
+                f"public final class {name}Module<Implementation: {name}Implementation>: PNNativeModule {{",
+                f'    public static var name: String {{ "{name}" }}',
+                "    let implementation: Implementation",
+                "    public init() { implementation = Implementation() }",
+                "    public func call(_ method: String, args: [String: Any], promise: PNPromise) {",
+                "        do {",
+                "            switch method {",
+            ]
+        )
+        kotlin.extend(
+            [
+                "}",
+                "",
+                f"class {name}Module(private val implementation: {name}Implementation): NativeModule {{",
+                f'    override val name = "{name}"',
+                "    override fun call(method: String, args: JSONObject, promise: Promise) {",
+                "        try {",
+                "            when (method) {",
+            ]
+        )
+        for method, contract, args in method_info:
+            swift.append(f'            case "{method}":')
+            kotlin.append(f'                "{method}" -> {{')
+            for key in args:
+                _, st, kt = _types(contract["arguments"][key])
+                if st.endswith("?"):
+                    swift.append(f'                let {key} = args["{key}"] as? {st[:-1]}')
+                else:
+                    swift.append(
+                        f'                guard let {key} = args["{key}"] as? {st} else {{ '
+                        f'promise.reject("Invalid {key}"); return }}'
+                    )
+                accessor = {"String": "getString", "Int": "getInt", "Double": "getDouble", "Boolean": "getBoolean"}.get(
+                    kt.rstrip("?"), "get"
+                )
+                expression = f'args.{accessor}("{key}")'
+                if kt.endswith("?"):
+                    expression = f'if (args.isNull("{key}")) null else {expression}'
+                kotlin.append(f"                    val {key} = {expression}")
+            sc = f"implementation.{method}(" + ", ".join(f"{key}: {key}" for key in args)
+            kc = f"implementation.{method}(" + ", ".join(args)
+            void = contract["result"].get("type") == "null"
+            if contract["async"]:
+                swift.append(f"                {sc}) {{ result in")
+                swift.append(
+                    "                    switch result { case .success(let value): promise.resolve("
+                    + ("nil" if void else "value")
+                    + "); case .failure(let error): promise.reject(error) }"
+                )
+                swift.append("                }")
+                kotlin.append(
+                    f"                    {kc}) {{ result -> result.fold({{ value -> promise.resolve("
+                    + ("null" if void else "value")
+                    + ') }, { error -> promise.reject(error.message ?: "Native call failed") }) }'
+                )
+            elif void:
+                swift.append(f"                try {sc}); promise.resolve(nil)")
+                kotlin.append(f"                    {kc}); promise.resolve(null)")
+            else:
+                swift.append(f"                promise.resolve(try {sc}))")
+                kotlin.append(f"                    promise.resolve({kc}))")
+            kotlin.append("                }")
+        swift.extend(
+            [
+                '            default: promise.reject("Unknown method", code: "unknown_method")',
+                "            }",
+                "        } catch { promise.reject(error) }",
+                "    }",
+                "}",
+                "",
+            ]
+        )
+        kotlin.extend(
+            [
+                "                else -> promise.rejectUnknownMethod(method)",
+                "            }",
+                '        } catch (error: Exception) { promise.reject(error.message ?: "Native call failed") }',
+                "    }",
+                "}",
+                "",
+            ]
+        )
+    return {
+        "modules.py": "\n".join(python),
+        "NativeModules.swift": "\n".join(swift),
+        "NativeModules.kt": "\n".join(kotlin),
+    }

pythonnative/sdk/schema.py

@@ -0,0 +1,224 @@
+"""Python definitions for native props, events, commands, and modules."""
+
+from __future__ import annotations
+
+import collections.abc
+import dataclasses
+import enum
+import hashlib
+import inspect
+import json
+import types
+import typing
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True)
+class NativeField:
+    """Native behavior attached to an annotated dataclass field.
+
+    Use ``Annotated[T, NativeField(...)]`` for native-specific metadata.
+    """
+
+    invalidates_layout: bool = False
+    recreate: bool = False
+    animated: bool = False
+    platforms: tuple[str, ...] = ("ios", "android", "web")
+    description: str = ""
+
+
+def type_schema(annotation: Any) -> dict[str, Any]:
+    """Convert a Python annotation into a portable JSON type description."""
+    origin, args = typing.get_origin(annotation), typing.get_args(annotation)
+    if origin is typing.Annotated:
+        result = type_schema(args[0])
+        for metadata in args[1:]:
+            if isinstance(metadata, NativeField):
+                result["native"] = dataclasses.asdict(metadata)
+        return result
+    if origin in (typing.Union, types.UnionType):
+        return {"anyOf": [type_schema(arg) for arg in args]}
+    if origin is typing.Literal:
+        return {"enum": list(args)}
+    if annotation is type(None):
+        return {"type": "null"}
+    if annotation in (str, bool, int, float):
+        return {"type": {str: "string", bool: "boolean", int: "integer", float: "number"}[annotation]}
+    if origin in (list, tuple, set, collections.abc.Sequence):
+        return {"type": "array", "items": type_schema(args[0]) if args else {}}
+    if origin in (dict, collections.abc.Mapping) or annotation is dict:
+        return {"type": "object", "additionalProperties": type_schema(args[-1]) if args else {}}
+    if origin in (typing.Callable, collections.abc.Callable):
+        return {
+            "type": "event",
+            "arguments": [type_schema(arg) for arg in args[0]] if args and args[0] is not Ellipsis else [],
+        }
+    if inspect.isclass(annotation) and issubclass(annotation, enum.Enum):
+        return {"enum": [value.value for value in annotation]}
+    if dataclasses.is_dataclass(annotation):
+        hints = typing.get_type_hints(annotation, include_extras=True)
+        return {"type": "object", "properties": {name: type_schema(value) for name, value in hints.items()}}
+    return {}
+
+
+def validate(value: Any, schema: Mapping[str, Any], path: str = "value") -> None:
+    """Validate wire values without coercion or ambiguous boolean comparisons."""
+    if "anyOf" in schema:
+        for alternative in schema["anyOf"]:
+            try:
+                validate(value, alternative, path)
+                return
+            except TypeError:
+                pass
+        raise TypeError(f"{path} does not match its annotation")
+    if "enum" in schema:
+        candidate = value.value if isinstance(value, enum.Enum) else value
+        if candidate not in schema["enum"]:
+            raise TypeError(f"{path} must be one of {schema['enum']!r}")
+    kind = schema.get("type")
+    checks = {
+        "null": lambda: value is None,
+        "string": lambda: isinstance(value, str),
+        "boolean": lambda: type(value) is bool,
+        "integer": lambda: type(value) is int,
+        "number": lambda: type(value) in (int, float),
+        "array": lambda: isinstance(value, (list, tuple, set)),
+        "object": lambda: isinstance(value, Mapping) or dataclasses.is_dataclass(value),
+        "event": lambda: callable(value),
+    }
+    if kind in checks and not checks[kind]():
+        raise TypeError(f"{path} must be {kind}, received {type(value).__name__}")
+    if kind == "array":
+        for index, item in enumerate(value):
+            validate(item, schema.get("items", {}), f"{path}[{index}]")
+    if kind == "object":
+        values = dataclasses.asdict(value) if dataclasses.is_dataclass(value) and not isinstance(value, type) else value
+        for name, item in values.items():
+            validate(
+                item, schema.get("properties", {}).get(name, schema.get("additionalProperties", {})), f"{path}.{name}"
+            )
+
+
+@dataclass(frozen=True)
+class ComponentSchema:
+    """The portable contract shared by every renderer and the component SDK."""
+
+    name: str
+    props: dict[str, dict[str, Any]]
+    required: tuple[str, ...] = ()
+    defaults: dict[str, Any] = field(default_factory=dict)
+    measurement: str = "intrinsic"
+    commands: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dataclass(cls, name: str, props: type, *, measurement: str = "intrinsic") -> ComponentSchema:
+        """Describe a native widget with a frozen Python props dataclass."""
+        if not dataclasses.is_dataclass(props):
+            raise TypeError("Native props must be a dataclass")
+        hints = typing.get_type_hints(props, include_extras=True)
+        required, defaults = [], {}
+        for item in dataclasses.fields(props):
+            if item.default is not dataclasses.MISSING:
+                defaults[item.name] = item.default
+            elif item.default_factory is not dataclasses.MISSING:
+                defaults[item.name] = item.default_factory()
+            else:
+                required.append(item.name)
+        return cls(
+            name, {key: type_schema(value) for key, value in hints.items()}, tuple(required), defaults, measurement
+        )
+
+    def validate(self, props: Mapping[str, Any], *, partial: bool = False) -> None:
+        """Validate a construction or a partial update against this contract."""
+        if not partial:
+            missing = set(self.required) - props.keys()
+            if missing:
+                raise TypeError(f"{self.name} requires {', '.join(sorted(missing))}")
+        for key, value in props.items():
+            if key not in self.props:
+                raise TypeError(f"Unknown {self.name} prop {key!r}")
+            validate(value, self.props[key], f"{self.name}.{key}")
+
+
+@dataclass(frozen=True)
+class ModuleSchema:
+    """Typed native module methods, arguments, results, and async behavior."""
+
+    name: str
+    methods: dict[str, dict[str, Any]]
+
+    @classmethod
+    def from_protocol(cls, name: str, protocol: type) -> ModuleSchema:
+        """Read annotated methods from a Python protocol or interface class."""
+        methods = {}
+        for method_name, method in inspect.getmembers(protocol, inspect.isfunction):
+            if method_name.startswith("_"):
+                continue
+            hints = typing.get_type_hints(method, include_extras=True)
+            signature = inspect.signature(method)
+            methods[method_name] = {
+                "arguments": {key: type_schema(hints.get(key, Any)) for key in signature.parameters if key != "self"},
+                "result": type_schema(hints.get("return", Any)),
+                "async": inspect.iscoroutinefunction(method),
+            }
+        return cls(name, methods)
+
+
+COMPONENTS: dict[str, ComponentSchema] = {}
+MODULES: dict[str, ModuleSchema] = {}
+
+
+def register_schema(schema: ComponentSchema | ModuleSchema) -> None:
+    """Register the contract used to generate and validate a native extension."""
+    if isinstance(schema, ComponentSchema):
+        COMPONENTS[schema.name] = schema
+    else:
+        MODULES[schema.name] = schema
+
+
+def manifest() -> dict[str, Any]:
+    """Return deterministic native metadata for code generation and tooling."""
+    return {
+        "protocol": 2,
+        "yoga": "3.2.1",
+        "components": {name: dataclasses.asdict(value) for name, value in sorted(COMPONENTS.items())},
+        "modules": {name: dataclasses.asdict(value) for name, value in sorted(MODULES.items())},
+    }
+
+
+def fingerprint() -> str:
+    """Hash the native contract; incompatible dev clients require rebuilding."""
+    return hashlib.sha256(json.dumps(manifest(), sort_keys=True, default=str).encode()).hexdigest()
+
+
+def load_manifest(document: Mapping[str, Any]) -> None:
+    """Load declarative extension contracts without importing target binaries."""
+    if document.get("protocol") != 2 or document.get("yoga") != "3.2.1":
+        raise ValueError("Native contracts require protocol 2 and Yoga 3.2.1")
+    pending = []
+    for group, constructor, registered in (
+        ("components", ComponentSchema, COMPONENTS),
+        ("modules", ModuleSchema, MODULES),
+    ):
+        for name, value in document.get(group, {}).items():
+            if not name.isidentifier() or value.get("name") != name:
+                raise ValueError(f"Invalid native contract name: {name!r}")
+            schema = constructor(**value)
+            old = registered.get(name)
+            if old is not None and json.dumps(dataclasses.asdict(old), sort_keys=True, default=str) != json.dumps(
+                dataclasses.asdict(schema), sort_keys=True, default=str
+            ):
+                raise ValueError(f"Conflicting native contract: {name}")
+            pending.append(schema)
+    for schema in pending:
+        register_schema(schema)
+
+
+def load_bundled_contracts() -> None:
+    """Install the exact contracts compiled into this embedded application."""
+    from importlib.resources import files
+
+    path = files("pythonnative").joinpath("_native_contracts.json")
+    if path.is_file():
+        load_manifest(json.loads(path.read_text(encoding="utf-8")))

pythonnative/sdk/templates/contracts.kt

@@ -0,0 +1,46 @@
+package com.pythonnative.generated
+
+import org.json.JSONArray
+import org.json.JSONObject
+
+/** Generated contract metadata shared by built-ins and extension managers. */
+object PNContracts {
+    const val fingerprint = "{{fingerprint}}"
+    private val components = JSONObject(listOf({{specification}}).joinToString("")).getJSONObject("components")
+
+    fun validate(name: String, props: JSONObject, partial: Boolean = false): Boolean {
+        val schema = components.optJSONObject(name) ?: return true
+        val fields = schema.getJSONObject("props")
+        val required = schema.optJSONArray("required") ?: JSONArray()
+        if (!partial) for (i in 0 until required.length()) if (!props.has(required.getString(i))) return false
+        for (key in props.keys()) {
+            if (partial && props.isNull(key)) continue
+            val field = fields.optJSONObject(key) ?: continue
+            if (!matches(props.get(key), field)) return false
+        }
+        return true
+    }
+
+    fun invalidatesLayout(name: String, changed: JSONObject): Boolean {
+        val fields = components.optJSONObject(name)?.optJSONObject("props") ?: return true
+        return changed.keys().asSequence().any { fields.optJSONObject(it)?.optJSONObject("native")?.optBoolean("invalidates_layout", true) ?: true }
+    }
+
+    private fun matches(value: Any, schema: JSONObject): Boolean {
+        schema.optJSONArray("anyOf")?.let { alternatives ->
+            return (0 until alternatives.length()).any { matches(value, alternatives.getJSONObject(it)) }
+        }
+        schema.optJSONArray("enum")?.let { values -> return (0 until values.length()).any { values.get(it).toString() == value.toString() } }
+        return when (schema.optString("type")) {
+            "null" -> value == JSONObject.NULL
+            "string" -> value is String
+            "boolean" -> value is Boolean
+            "integer" -> value is Number && value.toDouble() == value.toLong().toDouble()
+            "number" -> value is Number && value.toDouble().isFinite()
+            "array" -> value is JSONArray && (0 until value.length()).all { matches(value.get(it), schema.optJSONObject("items") ?: JSONObject()) }
+            "object" -> value is JSONObject
+            "event" -> value is Boolean || value == JSONObject.NULL
+            else -> true
+        }
+    }
+}

pythonnative/sdk/templates/contracts.swift

@@ -0,0 +1,46 @@
+import Foundation
+import CoreFoundation
+
+/// Generated contract metadata; validation is shared by built-ins and plugins.
+public enum PNContracts {
+    public static let fingerprint = "{{fingerprint}}"
+    private static let specification = """
+{{specification}}
+"""
+    private static let components = (try! JSONSerialization.jsonObject(with: Data(specification.utf8)) as! [String: Any])["components"] as! [String: [String: Any]]
+
+    public static func validate(_ name: String, _ props: [String: Any], partial: Bool = false) -> Bool {
+        guard let schema = components[name], let fields = schema["props"] as? [String: [String: Any]] else { return true }
+        if !partial {
+            for key in schema["required"] as? [String] ?? [] where props[key] == nil { return false }
+        }
+        for (key, value) in props {
+            if value is NSNull && partial { continue }
+            if let field = fields[key], !matches(value, field) { return false }
+        }
+        return true
+    }
+
+    public static func invalidatesLayout(_ name: String, _ changed: [String: Any]) -> Bool {
+        guard let fields = components[name]?["props"] as? [String: [String: Any]] else { return true }
+        return changed.keys.contains { ((fields[$0]?["native"] as? [String: Any])?["invalidates_layout"] as? Bool) ?? true }
+    }
+
+    private static func matches(_ value: Any, _ schema: [String: Any]) -> Bool {
+        if let alternatives = schema["anyOf"] as? [[String: Any]] { return alternatives.contains { matches(value, $0) } }
+        if let values = schema["enum"] as? [Any] { return values.contains { String(describing: $0) == String(describing: value) } }
+        switch schema["type"] as? String {
+        case "null": return value is NSNull
+        case "string": return value is String
+        case "boolean": return (value as? NSNumber).map { CFGetTypeID($0) == CFBooleanGetTypeID() } ?? false
+        case "integer": return (value as? NSNumber).map { CFGetTypeID($0) != CFBooleanGetTypeID() && $0.doubleValue.rounded() == $0.doubleValue } ?? false
+        case "number": return (value as? NSNumber).map { CFGetTypeID($0) != CFBooleanGetTypeID() && $0.doubleValue.isFinite } ?? false
+        case "array":
+            guard let array = value as? [Any] else { return false }
+            return array.allSatisfy { matches($0, schema["items"] as? [String: Any] ?? [:]) }
+        case "object": return value is [String: Any]
+        case "event": return value is Bool || value is NSNull
+        default: return true
+        }
+    }
+}