pythonnative 0.40.0__cp313-cp313-win_amd64.whl

pythonnative/templates/ios_template/ios_template/BridgingHeader.h

@@ -0,0 +1,14 @@
+//
+//  BridgingHeader.h
+//  ios_template
+//
+//  Exposes the embedded CPython C API to Swift. The header resolves
+//  through the linked Python.xcframework's framework search path.
+//
+
+#ifndef ios_template_BridgingHeader_h
+#define ios_template_BridgingHeader_h
+
+#include <Python/Python.h>
+
+#endif /* ios_template_BridgingHeader_h */

pythonnative/templates/ios_template/ios_template/Info.plist

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<!-- PythonNative's StatusBar element is applied through PNViewController's
+	     preferredStatusBarStyle / prefersStatusBarHidden overrides, so the
+	     modern view-controller-based appearance must stay enabled. -->
+	<key>UIViewControllerBasedStatusBarAppearance</key>
+	<true/>
+	<key>UIApplicationSceneManifest</key>
+	<dict>
+		<key>UIApplicationSupportsMultipleScenes</key>
+		<false/>
+		<key>UISceneConfigurations</key>
+		<dict>
+			<key>UIWindowSceneSessionRoleApplication</key>
+			<array>
+				<dict>
+					<key>UISceneConfigurationName</key>
+					<string>Default Configuration</string>
+					<key>UISceneDelegateClassName</key>
+					<string>$(PRODUCT_MODULE_NAME).SceneDelegate</string>
+				</dict>
+			</array>
+		</dict>
+	</dict>
+</dict>
+</plist>

pythonnative/templates/ios_template/ios_template/PythonRuntime.swift

@@ -0,0 +1,390 @@
+//
+//  PythonRuntime.swift
+//  ios_template
+//
+//  Embeds CPython directly through the C API (no PythonKit). The
+//  Python.xcframework is linked at build time, so a missing runtime is
+//  a build error, never a silent runtime fallback.
+//
+//  After the interpreter starts, `pythonnative.bootstrap.start()` binds
+//  the PythonNativeKit C exports, registers the Python callback, and
+//  verifies the protocol version. Everything else (screens, modules,
+//  deep links) flows over that bridge; nothing else here calls Python
+//  functions by name.
+//
+
+import Foundation
+import PythonNativeKit
+
+enum PythonRuntimeError: Error, CustomStringConvertible {
+    case startup(String)
+    case call(String)
+
+    var description: String {
+        switch self {
+        case .startup(let message): return message
+        case .call(let message): return message
+        }
+    }
+}
+
+/// An owned reference to a Python object. Reference counting is handled
+/// automatically; the wrapped pointer is released on deinit.
+final class PyRef {
+    fileprivate let pointer: UnsafeMutablePointer<PyObject>
+
+    fileprivate init(owned pointer: UnsafeMutablePointer<PyObject>) {
+        self.pointer = pointer
+    }
+
+    deinit {
+        let gil = PyGILState_Ensure()
+        Py_DecRef(pointer)
+        PyGILState_Release(gil)
+    }
+
+    /// Call a method on this object with string/number/bool arguments.
+    @discardableResult
+    func call(_ method: String, _ args: Any...) throws -> PyRef {
+        let gil = PyGILState_Ensure()
+        defer { PyGILState_Release(gil) }
+        guard let bound = PyObject_GetAttrString(pointer, method) else {
+            throw PythonRuntimeError.call("Python object has no method '\(method)': \(PythonRuntime.consumeError())")
+        }
+        defer { Py_DecRef(bound) }
+        return try PythonRuntime.invoke(bound, args: args, context: method)
+    }
+
+    /// Truthiness of the wrapped object (`PyObject_IsTrue`).
+    var isTruthy: Bool {
+        let gil = PyGILState_Ensure()
+        defer { PyGILState_Release(gil) }
+        return PyObject_IsTrue(pointer) == 1
+    }
+}
+
+/// Owns the embedded CPython interpreter for the whole process.
+final class PythonRuntime {
+    static let shared = PythonRuntime()
+
+    private(set) var started = false
+    private(set) var startupError: String? = nil
+
+    private init() {}
+
+    // MARK: - Startup
+
+    /// Initialize the embedded interpreter once and complete the bridge
+    /// handshake. Throws with a full description when the bundle is not
+    /// packaged correctly or the protocol versions disagree; there is
+    /// deliberately no fallback mode.
+    func ensureStarted() throws {
+        if let error = startupError { throw PythonRuntimeError.startup(error) }
+        if started { return }
+        do {
+            try start()
+            // The interpreter is live from here on; a failed handshake is
+            // recorded as a startup error but Python is never re-initialized.
+            started = true
+            try connectBridge()
+        } catch let error as PythonRuntimeError {
+            startupError = error.description
+            throw error
+        }
+    }
+
+    /// Run `pythonnative.bootstrap.start(dev, strict=True)`: it binds the
+    /// `pn_bridge_*` symbols, registers the native -> Python callback,
+    /// verifies the protocol version against `pn_bridge_protocol_version()`,
+    /// routes `print()` to the console, and warms the asyncio runtime.
+    private func connectBridge() throws {
+        #if DEBUG
+        let dev = true
+        #else
+        let dev = false
+        #endif
+        do {
+            try callList(module: "pythonnative.bootstrap", function: "start", [dev, true])
+        } catch let error as PythonRuntimeError {
+            throw PythonRuntimeError.startup(
+                "Bridge bootstrap failed (native protocol v\(pn_bridge_protocol_version())):\n\(error.description)"
+            )
+        }
+        guard PNBridge.shared.hasCallback else {
+            throw PythonRuntimeError.startup(
+                "pythonnative.bridge.handshake() returned without registering the native callback."
+            )
+        }
+    }
+
+    private func start() throws {
+        guard let resourcePath = Bundle.main.resourcePath else {
+            throw PythonRuntimeError.startup("The app bundle has no resource path; the build is corrupt.")
+        }
+        let pythonHome = "\(resourcePath)/python"
+        let appPath = "\(resourcePath)/app"
+        let packagesPath = "\(resourcePath)/app_packages"
+        for (path, hint) in [
+            (pythonHome, "the embedded Python runtime"),
+            (appPath, "the app's Python sources"),
+            (packagesPath, "the bundled Python packages"),
+        ] where !FileManager.default.fileExists(atPath: path) {
+            throw PythonRuntimeError.startup(
+                "Missing \(hint) at \(path). Build the app with 'pn run ios' or 'pn build ios' "
+                    + "so the PythonNative CLI stages the Python runtime; the raw Xcode template "
+                    + "cannot run on its own."
+            )
+        }
+
+        // The embedded CPython (3.13+) reports sys.platform == "ios" on its
+        // own; this explicit override is belt-and-braces for
+        // pythonnative.utils.IS_IOS and costs nothing.
+        setenv("PN_PLATFORM", "ios", 1)
+
+        var preconfig = PyPreConfig()
+        PyPreConfig_InitIsolatedConfig(&preconfig)
+        preconfig.utf8_mode = 1
+        var status = Py_PreInitialize(&preconfig)
+        if PyStatus_Exception(status) != 0 {
+            throw PythonRuntimeError.startup("Unable to pre-initialize Python: \(Self.statusMessage(status))")
+        }
+
+        var config = PyConfig()
+        PyConfig_InitIsolatedConfig(&config)
+        defer { PyConfig_Clear(&config) }
+        // Unbuffered stdio so print() reaches the device log immediately.
+        config.buffered_stdio = 0
+        // The signed bundle is immutable; never try to write bytecode.
+        config.write_bytecode = 0
+
+        guard let homeW = Py_DecodeLocale(pythonHome, nil) else {
+            throw PythonRuntimeError.startup("Could not decode the Python home path.")
+        }
+        status = withUnsafeMutablePointer(to: &config) { cfg in
+            PyConfig_SetString(cfg, &cfg.pointee.home, homeW)
+        }
+        PyMem_RawFree(homeW)
+        if PyStatus_Exception(status) != 0 {
+            throw PythonRuntimeError.startup("Unable to set the Python home: \(Self.statusMessage(status))")
+        }
+
+        status = PyConfig_Read(&config)
+        if PyStatus_Exception(status) != 0 {
+            throw PythonRuntimeError.startup("Unable to read the Python config: \(Self.statusMessage(status))")
+        }
+
+        status = Py_InitializeFromConfig(&config)
+        if PyStatus_Exception(status) != 0 {
+            throw PythonRuntimeError.startup("Unable to initialize Python: \(Self.statusMessage(status))")
+        }
+
+        // The interpreter is live and this thread holds the GIL. Finish
+        // path setup, then release the GIL; every later entry point
+        // re-acquires it via PyGILState_Ensure.
+        do {
+            try bootstrapPaths(appPath: appPath, packagesPath: packagesPath)
+        } catch {
+            PyEval_SaveThread()
+            throw error
+        }
+        PyEval_SaveThread()
+        NSLog("[PN] Embedded Python initialized (home: \(pythonHome))")
+    }
+
+    private func bootstrapPaths(appPath: String, packagesPath: String) throws {
+        // site.addsitedir(app_packages): adds to sys.path and honors .pth files.
+        guard let site = PyImport_ImportModule("site"),
+              let addsitedir = PyObject_GetAttrString(site, "addsitedir")
+        else {
+            throw PythonRuntimeError.startup("Could not import the site module: \(Self.consumeError())")
+        }
+        defer { Py_DecRef(site) }
+        defer { Py_DecRef(addsitedir) }
+        guard let packagesObj = PyUnicode_FromString(packagesPath),
+              let argsTuple = PyTuple_New(1)
+        else {
+            throw PythonRuntimeError.startup("Could not build site.addsitedir arguments.")
+        }
+        PyTuple_SetItem(argsTuple, 0, packagesObj)  // steals packagesObj
+        defer { Py_DecRef(argsTuple) }
+        guard let addResult = PyObject_CallObject(addsitedir, argsTuple) else {
+            throw PythonRuntimeError.startup("site.addsitedir failed: \(Self.consumeError())")
+        }
+        Py_DecRef(addResult)
+
+        // sys.path.insert(0, app) so `import app.main` resolves.
+        guard let sys = PyImport_ImportModule("sys"),
+              let sysPath = PyObject_GetAttrString(sys, "path"),
+              let appObj = PyUnicode_FromString(appPath)
+        else {
+            throw PythonRuntimeError.startup("Could not access sys.path: \(Self.consumeError())")
+        }
+        defer { Py_DecRef(sys) }
+        defer { Py_DecRef(sysPath) }
+        defer { Py_DecRef(appObj) }
+        // The bundle root itself is also importable ("app" package form).
+        if let resourceObj = PyUnicode_FromString(Bundle.main.resourcePath ?? appPath) {
+            PyList_Insert(sysPath, 0, resourceObj)
+            Py_DecRef(resourceObj)
+        }
+        if PyList_Insert(sysPath, 0, appObj) != 0 {
+            throw PythonRuntimeError.startup("Could not add the app directory to sys.path.")
+        }
+
+        #if DEBUG
+        // Dev-only: prioritize the writable hot-reload overlay. Release
+        // builds never look outside the signed bundle.
+        let documents = NSHomeDirectory() + "/Documents"
+        guard let hotReload = PyImport_ImportModule("pythonnative.hot_reload"),
+              let configure = PyObject_GetAttrString(hotReload, "configure_dev_environment"),
+              let docsObj = PyUnicode_FromString(documents),
+              let devArgs = PyTuple_New(1)
+        else {
+            throw PythonRuntimeError.startup(
+                "Could not import pythonnative: \(Self.consumeError())\n"
+                    + "The pythonnative package must be staged into app_packages by the pn CLI."
+            )
+        }
+        defer { Py_DecRef(hotReload) }
+        defer { Py_DecRef(configure) }
+        PyTuple_SetItem(devArgs, 0, docsObj)  // steals docsObj
+        defer { Py_DecRef(devArgs) }
+        if let devResult = PyObject_CallObject(configure, devArgs) {
+            Py_DecRef(devResult)
+        } else {
+            throw PythonRuntimeError.startup("Hot-reload setup failed: \(Self.consumeError())")
+        }
+        #endif
+    }
+
+    // MARK: - Calling into Python
+
+    /// Import `module` and call its `function` with the given arguments.
+    /// Supported argument types: String, Int, UInt, Bool, Double.
+    @discardableResult
+    func call(module: String, function: String, _ args: Any...) throws -> PyRef {
+        try callList(module: module, function: function, args)
+    }
+
+    @discardableResult
+    func callList(module: String, function: String, _ args: [Any]) throws -> PyRef {
+        guard started else {
+            throw PythonRuntimeError.call("Python is not running (startup failed or never happened).")
+        }
+        let gil = PyGILState_Ensure()
+        defer { PyGILState_Release(gil) }
+        guard let moduleObj = PyImport_ImportModule(module) else {
+            throw PythonRuntimeError.call("Could not import \(module): \(Self.consumeError())")
+        }
+        defer { Py_DecRef(moduleObj) }
+        guard let fnObj = PyObject_GetAttrString(moduleObj, function) else {
+            throw PythonRuntimeError.call("\(module) has no attribute '\(function)': \(Self.consumeError())")
+        }
+        defer { Py_DecRef(fnObj) }
+        return try Self.invoke(fnObj, args: args, context: "\(module).\(function)")
+    }
+
+    /// Shared invocation helper. The caller must hold the GIL.
+    fileprivate static func invoke(
+        _ callable: UnsafeMutablePointer<PyObject>,
+        args: [Any],
+        context: String
+    ) throws -> PyRef {
+        guard let tuple = PyTuple_New(args.count) else {
+            throw PythonRuntimeError.call("Could not allocate arguments for \(context).")
+        }
+        for (index, arg) in args.enumerated() {
+            guard let converted = convert(arg) else {
+                Py_DecRef(tuple)
+                throw PythonRuntimeError.call("Unsupported argument type \(type(of: arg)) for \(context).")
+            }
+            PyTuple_SetItem(tuple, index, converted)  // steals converted
+        }
+        defer { Py_DecRef(tuple) }
+        guard let result = PyObject_CallObject(callable, tuple) else {
+            throw PythonRuntimeError.call("\(context) raised: \(consumeError())")
+        }
+        return PyRef(owned: result)
+    }
+
+    private static func convert(_ value: Any) -> UnsafeMutablePointer<PyObject>? {
+        switch value {
+        case let string as String:
+            return PyUnicode_FromString(string)
+        case let flag as Bool:
+            return PyBool_FromLong(flag ? 1 : 0)
+        case let unsigned as UInt:
+            return PyLong_FromUnsignedLongLong(UInt64(unsigned))
+        case let integer as Int:
+            return PyLong_FromLongLong(Int64(integer))
+        case let double as Double:
+            return PyFloat_FromDouble(double)
+        default:
+            return nil
+        }
+    }
+
+    // MARK: - Error formatting
+
+    /// Format and clear the pending Python exception (caller holds the GIL).
+    fileprivate static func consumeError() -> String {
+        var ptype: UnsafeMutablePointer<PyObject>? = nil
+        var pvalue: UnsafeMutablePointer<PyObject>? = nil
+        var ptrace: UnsafeMutablePointer<PyObject>? = nil
+        PyErr_Fetch(&ptype, &pvalue, &ptrace)
+        PyErr_NormalizeException(&ptype, &pvalue, &ptrace)
+        defer {
+            Py_DecRef(ptype)
+            Py_DecRef(pvalue)
+            Py_DecRef(ptrace)
+        }
+        guard ptype != nil else { return "unknown Python error" }
+
+        if let traceback = PyImport_ImportModule("traceback") {
+            defer { Py_DecRef(traceback) }
+            let fnName = ptrace != nil ? "format_exception" : "format_exception_only"
+            if let formatFn = PyObject_GetAttrString(traceback, fnName) {
+                defer { Py_DecRef(formatFn) }
+                let count = ptrace != nil ? 3 : 2
+                if let tuple = PyTuple_New(count) {
+                    Py_IncRef(ptype)
+                    PyTuple_SetItem(tuple, 0, ptype)
+                    Py_IncRef(pvalue)
+                    PyTuple_SetItem(tuple, 1, pvalue)
+                    if count == 3 {
+                        Py_IncRef(ptrace)
+                        PyTuple_SetItem(tuple, 2, ptrace)
+                    }
+                    defer { Py_DecRef(tuple) }
+                    if let lines = PyObject_CallObject(formatFn, tuple) {
+                        defer { Py_DecRef(lines) }
+                        if let empty = PyUnicode_FromString(""),
+                           let joined = PyUnicode_Join(empty, lines)
+                        {
+                            Py_DecRef(empty)
+                            defer { Py_DecRef(joined) }
+                            if let utf8 = PyUnicode_AsUTF8(joined) {
+                                return String(cString: utf8)
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        // Fallback: str(value).
+        if let value = pvalue, let str = PyObject_Str(value) {
+            defer { Py_DecRef(str) }
+            if let utf8 = PyUnicode_AsUTF8(str) {
+                return String(cString: utf8)
+            }
+        }
+        return "unknown Python error"
+    }
+
+    private static func statusMessage(_ status: PyStatus) -> String {
+        if let errMsg = status.err_msg {
+            return String(cString: errMsg)
+        }
+        return "unknown error"
+    }
+}

pythonnative/templates/ios_template/ios_template/SceneDelegate.swift

@@ -0,0 +1,61 @@
+//
+//  SceneDelegate.swift
+//  ios_template
+//
+//  Creates the window programmatically and forwards scene-level events
+//  (deep links, foreground/background transitions) to the Swift native
+//  modules, which relay them to Python over the bridge.
+//
+
+import PythonNativeKit
+import UIKit
+
+class SceneDelegate: UIResponder, UIWindowSceneDelegate {
+    var window: UIWindow?
+
+    func scene(
+        _ scene: UIScene,
+        willConnectTo session: UISceneSession,
+        options connectionOptions: UIScene.ConnectionOptions
+    ) {
+        guard let windowScene = (scene as? UIWindowScene) else { return }
+        // A cold start from a deep link delivers the URL here, before
+        // Python is running; LinkingModule buffers it until the bridge
+        // callback is registered so Linking.get_initial_url() sees it.
+        for context in connectionOptions.urlContexts {
+            LinkingModule.deliver(url: context.url.absoluteString)
+        }
+        let window = UIWindow(windowScene: windowScene)
+        let root = ViewController()
+        let nav = UINavigationController(rootViewController: root)
+        window.rootViewController = nav
+        self.window = window
+        window.makeKeyAndVisible()
+    }
+
+    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
+        for context in URLContexts {
+            LinkingModule.deliver(url: context.url.absoluteString)
+        }
+    }
+
+    // MARK: - AppState forwarding
+
+    func sceneDidBecomeActive(_ scene: UIScene) {
+        AppStateModule.dispatch("active")
+    }
+
+    func sceneWillResignActive(_ scene: UIScene) {
+        AppStateModule.dispatch("inactive")
+    }
+
+    func sceneWillEnterForeground(_ scene: UIScene) {
+        AppStateModule.dispatch("inactive")
+    }
+
+    func sceneDidEnterBackground(_ scene: UIScene) {
+        AppStateModule.dispatch("background")
+    }
+
+    func sceneDidDisconnect(_ scene: UIScene) {}
+}

pythonnative/templates/ios_template/ios_template/ViewController.swift

@@ -0,0 +1,23 @@
+//
+//  ViewController.swift
+//  ios_template
+//
+//  Hosts one PythonNative screen. All screen plumbing lives in
+//  PythonNativeKit's PNViewController; this subclass only starts the
+//  embedded interpreter (showing a bootstrap error on failure).
+//
+
+import PythonNativeKit
+import UIKit
+
+final class ViewController: PNViewController {
+    override func prepareRuntime() -> Bool {
+        do {
+            try PythonRuntime.shared.ensureStarted()
+        } catch {
+            showBootstrapError("Python failed to start.\n\n\(error)")
+            return false
+        }
+        return true
+    }
+}