Update Usage.md

[olilarkin]

What is the problem or limitation you are having?

It seems that maybe a recent switch to a different package layout with the xcframework has made the Usage.md instructions obsolete? I was able to use PythonKit without the module map but it is unclear to me now how i install dependencies since the xcframework contains the site packages folder.

Describe the solution you'd like

update about how it's meant to work

Describe alternatives you've considered

ditto

Additional context

thanks for this cool project!

[freakboy3742]

Support for PythonKit is provided on a "best effort" basis; we're happy to incorporate changes to documentation, but we're not actively monitoring for changes.

FWIW, the Briefcase iOS template gives the paths that are used by the new project layout:

NSString *resourcePath = [[NSBundle mainBundle] resourcePath];
NSString *python_home = [NSString stringWithFormat:@"%@/python", resourcePath, nil];
NSString *stdlib_path = [NSString stringWithFormat:@"%@/lib/python3.13", python_home, nil];
NSString *libdynload_path = [NSString stringWithFormat:@"%@/lib/python3.13/lib-dynload", python_home, nil];

I think that is all the detail you need to adapt the current usage guide; if you want to convert that into a PR updating USAGE.md, I'll happily merge those changes.

[kostrykin]

I'm following a guide on how to embed a Python interpreter into a Swift app for macOS, and it tells to copy the python-stdlib directory from a release of this repo into the project directory. The guide also tells to ensure that python-stdlib is contained in "Copy Bundle Resources" and all .so files from within python-stdlib are signed.

I downloaded a few releases from this repo, for example https://github.com/beeware/Python-Apple-support/releases/tag/3.11-b5, but there isn't such a directory. Do you maybe have a suggestion how to proceed?

---

Update: I have added the Python.xcframework from the release to the Xcode project but when I try import Python all I get is No such module 'Python'. What am I missing?

I was able to use PythonKit without the module map but it is unclear to me now how i install dependencies since the xcframework contains the site packages folder.

@olilarkin Can you maybe elaborate on which steps exactly you took to make it work?

[freakboy3742]

3.11-b4 (and other version releases at the same time) changed the structure of the support package to use the binary format and loading mechanism that was approved as part of PEP 730. This required some changes to the layout of the package.

Any errors associated with "No such module Python", or any difficulties loading the standard library can almost certainly be traced back to the initialisation of the module (and in particular paths) being correct.

As noted above, the usage guide for PythonKit is provided on a best-effort basis; if you want to see what is required to make the support package work, the project generated by Briefcase is the canonical reference implementation.

[kostrykin]

Thanks for the reply!

Any errors associated with "No such module Python", or any difficulties loading the standard library can almost certainly be traced back to the initialisation of the module (and in particular paths) being correct.

Maybe I'm misunderstanding something here, because from what I've read, I assumed that the initialization of the module happens after the import Python instruction (for example, see Step 3 in https://github.com/beeware/Python-Apple-support/blob/main/USAGE.md#pythonkit). Is there anything that I need to put before the import Python instruction?

As noted above, the usage guide for PythonKit is provided on a best-effort basis;

Yes I understand that. I appreciate this very much.

if you want to see what is required to make the support package work, the project generated by Briefcase is the canonical reference implementation.

Thanks for the pointer, I have tried setting up a briefcase project using the macOS Xcode template as described in the README file (pip install cookiecutter, btw the step pip install briefcase is missing, cookiecutter https://github.com/beeware/briefcase-macOS-Xcode-template, then I put the extracted 3.11-b4 release into the Support directory). This gives me an Xcode project to work with. However, when I create a Swift file inside this project and add the line import Python, I still get the No such module 'Python' error.

[freakboy3742]

Any errors associated with "No such module Python", or any difficulties loading the standard library can almost certainly be traced back to the initialisation of the module (and in particular paths) being correct.

Maybe I'm misunderstanding something here, because from what I've read, I assumed that the initialization of the module happens after the import Python instruction (for example, see Step 3 in https://github.com/beeware/Python-Apple-support/blob/main/USAGE.md#pythonkit). Is there anything that I need to put before the import Python instruction?

I know almost nothing about PythonKit, so I can't say for certain - but as far as I know there's nothing needed in code before you invoke import Python.

However, your Xcode project needs to include Python correctly, and ensure that it is copied into the project as a target. A failure to load a module likely indicates that the framework isn't being copied into the project correctly, or there's some other (swift-specific) module configuration that needs to be performed (such as configuring a loading/linking path).

[kostrykin]

It works basically out of the box using the old release layout (e.g., 3.11-b3) following the steps described here.

Following basically the same steps for releases with the new layout (e.g., 3.11-b4) however does not work and yields the No such module 'Python' error. I would be very grateful if @olilarkin could describe the steps they took to make it work with the new layout :)

[olilarkin]

I've made a template repo for a macOS based on the info here

https://github.com/olilarkin/SwiftPythonTemplate

I hope that helps

[frogcjn]

@kostrykin @freakboy3742 @olilarkin

Repo:
https://github.com/frogcjn/SwiftwithPython/tree/main

SwiftwithPython

How to embed Python Framework into Swift Projects (currently iOS)

1. Create an empty Swift iOS Project

2. Download Compiled Python.xcframework for iOS target
   https://github.com/beeware/Python-Apple-support/releases/tag/3.13-b3

• Python-3.13-iOS-support.b3.tar.gz
  • ./platform-site/sitecustomize.py : use this file to custom download packages on targeted platform
  • Python.xcframework: this is what we need

3-8. Follow up the detail instructions on Python official website: Using Python on iOS (except the step 1, 4, 5, 10 in this document)

(I also have a more detailed version published on my Notion Swift with Python Step by Step, including the necessary steps posted on Python official website)

9. Create two file copies called module.modulemap inside

• Python.xcframework/ios-arm64/Python.framework/Headers/ and

• Python.xcframework/ios-arm64_x86_64-simulator/Python.framework/Headers/

containing the same code below:

module Python {
    umbrella header "Python.h"
    export *
    link "Python"
}

Step 3-9 are necessary steps to import Python in Swift, Xcode will search the module headers in Python.framework

10. PythonKit is not a requirement to use Python on iOS, but if you want to use the code in testPythonKit() in next step to test, then you should add PythonKit on the Xcode project settings, there is a Swift Package Manager configuration.

11. Add init func to the iOS Project App swift file

import SwiftUI

@main
struct SwiftPythonApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
    
    init() {
        initPythonSimpleVersion()
        testPythonKit()
    }
}

12. Also add a new InitPython.swift file to the target:

import Foundation
import Python

// Python Init Part (Neccessary)
func initPythonSimpleVersion() {
    print("init Python")
    
    // let resourcePath = Bundle.main.resourcePath!
    guard let pythonHome = Bundle.main.path(forResource: "python", ofType: nil) else { return }
    guard let pythonPath = Bundle.main.path(forResource: "python/lib/python3.13", ofType: nil) else { return }
    guard let libDynLoad = Bundle.main.path(forResource: "python/lib/python3.13/lib-dynload", ofType: nil) else { return }
    let appPath = Bundle.main.path(forResource: "app", ofType: nil)
    
    setenv("PYTHONHOME", pythonHome, 1)
    
    /*
     The PYTHONPATH for the interpreter includes:
     the python/lib/python3.X subfolder of your app’s bundle,
     the python/lib/python3.X/lib-dynload subfolder of your app’s bundle, and
     the app subfolder of your app’s bundle
     */
    
    setenv("PYTHONPATH", [pythonPath, libDynLoad, appPath].compactMap { $0 }.joined(separator: ":"), 1)
    Py_Initialize()
    
    print("init Success")
}

// test PythonKit Part (Optional)
import PythonKit
var version: String? = nil
func testPythonKit() {
    print("test PythonKit")
    
    let sys = Python.import("sys")
    version = "\(sys.version)"
    print("Python Version: \(sys.version_info.major).\(sys.version_info.minor)")
    print("Python Encoding: \(sys.getdefaultencoding().upper())")
    print("Python Path: \(sys.path)")
    let platform = Python.import("platform")
    print(platform.system())
}

13. Edit ContentView.swift

import SwiftUI

struct ContentView: View {
    var body: some View {
        VStack {
            Text("🐍")
                .imageScale(.large)
                .foregroundStyle(.tint)
            Text("Hello, Python \(version ?? "Not Available")!")
        }
        .padding()
    }
}

#Preview {
    ContentView()
}

14. Final Result

[freakboy3742]

@frogcjn Thanks for those details. If the modulemap files are required for Swift integration, I can add them to the build produced by this project.

Regarding the remaining instructions - based on those details, you presumably also need to add PythonKit to your project? Can you provide details on what is required there? I'm happy to add those into the usage guide if I know what needs to be added.

[frogcjn]

Hi @freakboy3742 , you could just clone my GitHub, all thing is done in my project.

PythonKit is not a requirement to use Python on iOS, but if you want to use code in testPythonKit() to test, then you should add PythonKit on the Xcode project settings, there is a Swift Package Manager configuration.

[freakboy3742]

@frogcjn So... I don't know if you've noticed, but I'm the maintainer of this project.

You left your original comment on an open ticket on this repository (that I maintain). The ticket is asking for a documentation update. I'm trying to establish what needs to be in that documentation update.

Cloning your project won't solve any problem I have. It would give me a worked example of a project... but that doesn't tell me what you've done to the project (unless I dig through all the details myself).

[frogcjn]

@freakboy3742 , I have written detail steps.

I have a more detailed version published on my Notion, including the necessary steps posted on Python official website.
https://frogcjn.notion.site/Python-3-13-on-iOS-1984959764ca80999f25cf9897df83bc?pvs=4

[freakboy3742]

Thanks... although that seems like a very longwinded way to say "the only thing in the existing documentation that needs to be updated is the configuration of paths".

I've just made those changes (and included the module map in the generated frameworks) in #248.