3.13 update (#292)

* Updates Python patch to 3.13.3
* Adds handling for .xcprivacy and .dSYM handling.

Author: freakboy3742

.github/workflows/ci.yaml

@@ -105,7 +105,7 @@ jobs:
     - uses: actions/[email protected]
 
     - name: Set up Python
-      uses: actions/setup-python@v5.4.0
+      uses: actions/setup-python@v5.6.0
       with:
         # Appending -dev ensures that we can always build the dev release.
         # It's a no-op for versions that have been published.
@@ -120,7 +120,7 @@ jobs:
         make ${{ matrix.target }} BUILD_NUMBER=${{ needs.config.outputs.BUILD_NUMBER }}
 
     - name: Upload build artefacts
-      uses: actions/[email protected].1
+      uses: actions/[email protected].2
       with:
         name: Python-${{ needs.config.outputs.PYTHON_VER }}-${{ matrix.target }}-support.${{ needs.config.outputs.BUILD_NUMBER }}.tar.gz
         path: dist/Python-${{ needs.config.outputs.PYTHON_VER }}-${{ matrix.target }}-support.${{ needs.config.outputs.BUILD_NUMBER }}.tar.gz

.github/workflows/publish.yaml

@@ -11,7 +11,7 @@ jobs:
     - uses: actions/checkout@v4
 
     - name: Set up Python environment
-      uses: actions/setup-python@v5.4.0
+      uses: actions/setup-python@v5.6.0
       with:
         python-version: "3.X"
 
@@ -48,3 +48,6 @@ jobs:
         # watchOS build
         curl -o watchOS-artefact.tar.gz -L https://github.com/beeware/Python-Apple-support/releases/download/${{ steps.build-vars.outputs.TAG }}/Python-${{ steps.build-vars.outputs.PYTHON_VER }}-watchOS-support.${{ steps.build-vars.outputs.BUILD_NUMBER }}.tar.gz
         aws s3 cp watchOS-artefact.tar.gz s3://briefcase-support/python/${{ steps.build-vars.outputs.PYTHON_VER }}/watchOS/Python-${{ steps.build-vars.outputs.PYTHON_VER }}-watchOS-support.${{ steps.build-vars.outputs.BUILD_NUMBER }}.tar.gz
+        # visionOS build
+        curl -o visionOS-artefact.tar.gz -L https://github.com/beeware/Python-Apple-support/releases/download/${{ steps.build-vars.outputs.TAG }}/Python-${{ steps.build-vars.outputs.PYTHON_VER }}-visionOS-support.${{ steps.build-vars.outputs.BUILD_NUMBER }}.tar.gz
+        aws s3 cp visionOS-artefact.tar.gz s3://briefcase-support/python/${{ steps.build-vars.outputs.PYTHON_VER }}/visionOS/Python-${{ steps.build-vars.outputs.PYTHON_VER }}-visionOS-support.${{ steps.build-vars.outputs.BUILD_NUMBER }}.tar.gz

.github/workflows/release.yaml

@@ -40,7 +40,7 @@ jobs:
     needs: [ config, ci ]
     steps:
     - name: Get build artifacts
-      uses: actions/download-artifact@v4.1.9
+      uses: actions/download-artifact@v4.3.0
       with:
         pattern: Python-*
         path: dist

CONTRIBUTING.md

@@ -2,7 +2,44 @@
 
 BeeWare <3's contributions!
 
-Please be aware, BeeWare operates under a Code of Conduct.
+Please be aware that BeeWare operates under a [Code of
+Conduct](https://beeware.org/community/behavior/code-of-conduct/).
 
-See [CONTRIBUTING to BeeWare](https://beeware.org/contributing) for details.
+See [CONTRIBUTING to BeeWare](https://beeware.org/contributing) for general
+project contribution guidelines.
 
+Unless a fix is version specific, PRs should genereally be made against the
+`main` branch of this repo, targeting the current development version of Python.
+Project maintainers will manage the process of backporting changes to older
+Python versions.
+
+## Changes to `Python.patch`
+
+Additional handling is required if you need to make modifications to the patch
+applied to Python sources (`patch/Python/Python.patch`).
+
+Any iOS or macOS-specific changes should be submitted to the [upstream CPython
+repository](https://github.com/python/cpython). macOS and iOS are both
+officially supported Python platforms, and the code distributed by this project
+for those platforms is unmodified from the official repository.
+
+Changes to to support other platforms can be included in a PR for this repo, but
+they must also be submitted as a pull request against the `MAJOR.MINOR-patched`
+branch on [the `freakboy3742` fork of the CPython
+repo](https://github.com/freakboy3742/cpython). This is required to ensure that
+any contributed changes can be easily reproduced in future patches as more
+changes are made.
+
+Note that the `MAJOR.MINOR-patched` branch of that fork is maintained in the format
+of a *patch tree*, which is a branch that consists of an entirely linear sequence of
+commits applied on top of another branch (in the case of the fork, `MAJOR.MINOR`),
+each of which adds a significant new feature. Therefore, a bug fix for an existing commit
+in the patch tree *will* be merged when appropriate, but its changes will get combined
+with that existing commit that adds the feature. A feature addition PR will be squashed
+into a single, new commit, and then put on top of the patch tree.
+
+This also means that if another contributor gets a pull request merged into
+`MAJOR.MINOR-patched`, you must *rebase* your changes on top of the updated
+`MAJOR.MINOR-patched` branch, as opposed to *merging* `MAJOR.MINOR-patched` into your
+branch, since the "history" of a patch tree is likely to change in a way that is
+incompatible with merge commits.

Makefile

@@ -33,24 +33,28 @@ OPENSSL_VERSION=3.0.16-2
 XZ_VERSION=5.6.4-2
 
 # Supported OS
-OS_LIST=macOS iOS tvOS watchOS
+OS_LIST=macOS iOS tvOS watchOS visionOS
 
 CURL_FLAGS=--disable --fail --location --create-dirs --progress-bar
 
 # macOS targets
 TARGETS-macOS=macosx.x86_64 macosx.arm64
+TRIPLE_OS-macOS=macos
 VERSION_MIN-macOS=11.0
 
 # iOS targets
 TARGETS-iOS=iphonesimulator.x86_64 iphonesimulator.arm64 iphoneos.arm64
+TRIPLE_OS-iOS=ios
 VERSION_MIN-iOS=13.0
 
 # tvOS targets
 TARGETS-tvOS=appletvsimulator.x86_64 appletvsimulator.arm64 appletvos.arm64
+TRIPLE_OS-tvOS=tvos
 VERSION_MIN-tvOS=12.0
 
 # watchOS targets
 TARGETS-watchOS=watchsimulator.x86_64 watchsimulator.arm64 watchos.arm64_32
+TRIPLE_OS-watchOS=watchos
 VERSION_MIN-watchOS=4.0
 
 # The architecture of the machine doing the build
@@ -128,10 +132,10 @@ ARCH-$(target)=$$(subst .,,$$(suffix $(target)))
 
 ifneq ($(os),macOS)
 	ifeq ($$(findstring simulator,$$(SDK-$(target))),)
-TARGET_TRIPLE-$(target)=$$(ARCH-$(target))-apple-$$(OS_LOWER-$(target))$$(VERSION_MIN-$(os))
+TARGET_TRIPLE-$(target)=$$(ARCH-$(target))-apple-$$(TRIPLE_OS-$(os))$$(VERSION_MIN-$(os))
 IS_SIMULATOR-$(target)=False
 	else
-TARGET_TRIPLE-$(target)=$$(ARCH-$(target))-apple-$$(OS_LOWER-$(target))$$(VERSION_MIN-$(os))-simulator
+TARGET_TRIPLE-$(target)=$$(ARCH-$(target))-apple-$$(TRIPLE_OS-$(os))$$(VERSION_MIN-$(os))-simulator
 IS_SIMULATOR-$(target)=True
 	endif
 endif
@@ -398,15 +402,13 @@ define build-sdk
 sdk=$1
 os=$2
 
-OS_LOWER-$(sdk)=$(shell echo $(os) | tr '[:upper:]' '[:lower:]')
-
 SDK_TARGETS-$(sdk)=$$(filter $(sdk).%,$$(TARGETS-$(os)))
 SDK_ARCHES-$(sdk)=$$(sort $$(subst .,,$$(suffix $$(SDK_TARGETS-$(sdk)))))
 
 ifeq ($$(findstring simulator,$(sdk)),)
-SDK_SLICE-$(sdk)=$$(OS_LOWER-$(sdk))-$$(shell echo $$(SDK_ARCHES-$(sdk)) | sed "s/ /_/g")
+SDK_SLICE-$(sdk)=$$(TRIPLE_OS-$(os))-$$(shell echo $$(SDK_ARCHES-$(sdk)) | sed "s/ /_/g")
 else
-SDK_SLICE-$(sdk)=$$(OS_LOWER-$(sdk))-$$(shell echo $$(SDK_ARCHES-$(sdk)) | sed "s/ /_/g")-simulator
+SDK_SLICE-$(sdk)=$$(TRIPLE_OS-$(os))-$$(shell echo $$(SDK_ARCHES-$(sdk)) | sed "s/ /_/g")-simulator
 endif
 
 # Expand the build-target macro for target on this OS
@@ -450,6 +452,7 @@ $$(PYTHON_LIB-$(sdk)): $$(foreach target,$$(SDK_TARGETS-$(sdk)),$$(PYTHON_LIB-$$
 	mkdir -p $$(dir $$(PYTHON_LIB-$(sdk)))
 	lipo -create -output $$@ $$^ \
 		2>&1 | tee -a install/$(os)/$(sdk)/python-$(PYTHON_VERSION).lipo.log
+	dsymutil $$@ -o $$(PYTHON_INSTALL-$(sdk))/Python.dSYM
 
 $$(PYTHON_FRAMEWORK-$(sdk))/Info.plist: $$(PYTHON_LIB-$(sdk))
 	@echo ">>> Install Info.plist for the $(sdk) SDK"
@@ -481,11 +484,15 @@ $$(PYTHON_INCLUDE-$(sdk))/pyconfig.h: $$(PYTHON_LIB-$(sdk))
 	mkdir -p $$(PYTHON_INSTALL-$(sdk))/include
 	ln -si ../Python.framework/Headers $$(PYTHON_INSTALL-$(sdk))/include/python$(PYTHON_VER)
 
+ifeq ($(os), visionOS)
+	echo "Skipping arch-specific header copying for visionOS"
+else
 	# Add the individual headers from each target in an arch-specific name
 	$$(foreach target,$$(SDK_TARGETS-$(sdk)),cp $$(PYTHON_INCLUDE-$$(target))/pyconfig.h $$(PYTHON_INCLUDE-$(sdk))/pyconfig-$$(ARCH-$$(target)).h; )
 
 	# Copy the cross-target header from the source folder of the first target in the $(sdk) SDK
 	cp $$(PYTHON_SRCDIR-$$(firstword $$(SDK_TARGETS-$(sdk))))/$(os)/Resources/pyconfig.h $$(PYTHON_INCLUDE-$(sdk))/pyconfig.h
+endif
 
 
 $$(PYTHON_STDLIB-$(sdk))/LICENSE.TXT: $$(PYTHON_LIB-$(sdk)) $$(PYTHON_FRAMEWORK-$(sdk))/Info.plist $$(PYTHON_INCLUDE-$(sdk))/pyconfig.h $$(foreach target,$$(SDK_TARGETS-$(sdk)),$$(PYTHON_PLATFORM_SITECUSTOMIZE-$$(target)))
@@ -510,6 +517,14 @@ $$(PYTHON_STDLIB-$(sdk))/LICENSE.TXT: $$(PYTHON_LIB-$(sdk)) $$(PYTHON_FRAMEWORK-
 	# Merge the binary modules from each target in the $(sdk) SDK into a single binary
 	$$(foreach module,$$(wildcard $$(PYTHON_STDLIB-$$(firstword $$(SDK_TARGETS-$(sdk))))/lib-dynload/*),lipo -create -output $$(PYTHON_STDLIB-$(sdk))/lib-dynload/$$(notdir $$(module)) $$(foreach target,$$(SDK_TARGETS-$(sdk)),$$(PYTHON_STDLIB-$$(target))/lib-dynload/$$(notdir $$(module))); )
 
+	# Create dSYM files for each module
+	$$(foreach module,$$(wildcard $$(PYTHON_STDLIB-$$(firstword $$(SDK_TARGETS-$(sdk))))/lib-dynload/*),dsymutil $$(PYTHON_STDLIB-$(sdk))/lib-dynload/$$(notdir $$(module)); )
+
+	# Copy in known-required xcprivacy files.
+	# Libraries linking OpenSSL must provide a privacy manifest. The one in this repository
+	# has been sourced from https://github.com/openssl/openssl/blob/openssl-3.0/os-dep/Apple/PrivacyInfo.xcprivacy
+	cp $(PROJECT_DIR)/patch/Python/OpenSSL.xcprivacy $$(PYTHON_STDLIB-$(sdk))/lib-dynload/_hashlib.xcprivacy
+	cp $(PROJECT_DIR)/patch/Python/OpenSSL.xcprivacy $$(PYTHON_STDLIB-$(sdk))/lib-dynload/_ssl.xcprivacy
 endif
 
 $(sdk): $$(PYTHON_STDLIB-$(sdk))/LICENSE.TXT
@@ -647,10 +662,11 @@ $$(PYTHON_XCFRAMEWORK-$(os))/Info.plist: \
 	$$(foreach sdk,$$(SDKS-$(os)),cp -r $$(PYTHON_INSTALL-$$(sdk))/bin $$(PYTHON_XCFRAMEWORK-$(os))/$$(SDK_SLICE-$$(sdk)); )
 	$$(foreach sdk,$$(SDKS-$(os)),cp -r $$(PYTHON_INSTALL-$$(sdk))/lib $$(PYTHON_XCFRAMEWORK-$(os))/$$(SDK_SLICE-$$(sdk)); )
 	$$(foreach sdk,$$(SDKS-$(os)),cp -r $$(PYTHON_INSTALL-$$(sdk))/platform-config $$(PYTHON_XCFRAMEWORK-$(os))/$$(SDK_SLICE-$$(sdk)); )
+	$$(foreach sdk,$$(SDKS-$(os)),cp -r $$(PYTHON_INSTALL-$$(sdk))/Python.dSYM $$(PYTHON_XCFRAMEWORK-$(os))/$$(SDK_SLICE-$$(sdk)); )
 
-ifeq ($(os),iOS)
+ifeq ($(filter $(os),iOS visionOS),$(os))
 	@echo ">>> Clone testbed project for $(os)"
-	$(HOST_PYTHON) $$(PYTHON_SRCDIR-$$(firstword $$(SDK_TARGETS-$$(firstword $$(SDKS-$(os))))))/iOS/testbed clone --framework $$(PYTHON_XCFRAMEWORK-$(os)) support/$(PYTHON_VER)/$(os)/testbed
+	$(HOST_PYTHON) $$(PYTHON_SRCDIR-$$(firstword $$(SDK_TARGETS-$$(firstword $$(SDKS-$(os))))))/$(os)/testbed clone --framework $$(PYTHON_XCFRAMEWORK-$(os)) support/$(PYTHON_VER)/$(os)/testbed
 endif
 
 	@echo ">>> Create VERSIONS file for $(os)"

README.rst

@@ -2,7 +2,7 @@ Python Apple Support
 ====================
 
 This is a meta-package for building a version of Python that can be embedded
-into a macOS, iOS, tvOS or watchOS project.
+into a macOS, iOS, tvOS, watchOS, or visionOS project.
 
 **This branch builds a packaged version of Python 3.13**.
 Other Python versions are available by cloning other branches of the main
@@ -16,21 +16,24 @@ repository:
 
 It works by downloading, patching, and building a fat binary of Python and
 selected pre-requisites, and packaging them as frameworks that can be
-incorporated into an XCode project. The binary modules in the Python standard
+incorporated into an Xcode project. The binary modules in the Python standard
 library are distributed as binaries that can be dynamically loaded at runtime.
 
 The macOS package is a re-bundling of the official macOS binary, modified so that
 it is relocatable, with the IDLE, Tkinter and turtle packages removed, and the
 App Store compliance patch applied.
 
-The iOS, tvOS and watchOS packages compiled by this project use the official
-`PEP 730 <https://peps.python.org/pep-0730/>`__ code that is part of Python 3.13
-to provide iOS support; the relevant patches have been backported to 3.9-3.12.
-Additional patches have been applied to add tvOS and watchOS support.
+The iOS, tvOS, watchOS, and visionOS packages compiled by this project use the
+official `PEP 730 <https://peps.python.org/pep-0730/>`__ code that is part of
+Python 3.13 to provide iOS support; the relevant patches have been backported
+to 3.9-3.12. Additional patches have been applied to add tvOS, watchOS, and
+visionOS support.
 
 The binaries support x86_64 and arm64 for macOS; arm64 for iOS and appleTV
-devices; and arm64_32 for watchOS devices. It also supports device simulators on
-both x86_64 and M1 hardware. This should enable the code to run on:
+devices; arm64_32 for watchOS devices; and arm64 for visionOS devices. It also
+supports device simulators on both x86_64 and M1 hardware, except for visionOS,
+for which x86_64 simulators are officially unsupported. This should enable the
+code to run on:
 
 * macOS 11 (Big Sur) or later, on:
     * MacBook (including MacBooks using Apple Silicon)
@@ -49,6 +52,8 @@ both x86_64 and M1 hardware. This should enable the code to run on:
     * Apple TV (4th gen or later)
 * watchOS 4.0 or later, on:
     * Apple Watch (4th gen or later)
+* visionOS 2.0 or later, on:
+    * Apple Vision Pro
 
 Quickstart
 ----------
@@ -69,23 +74,24 @@ repository, and then in the root directory, and run:
 * ``make iOS`` to build everything for iOS.
 * ``make tvOS`` to build everything for tvOS.
 * ``make watchOS`` to build everything for watchOS.
+* ``make visionOS`` to build everything for visionOS.
 
 This should:
 
 1. Download the original source packages
 2. Patch them as required for compatibility with the selected OS
 3. Build the packages as Xcode-compatible XCFrameworks.
 
-The resulting support packages will be packaged as a ``.tar.gz`` file
+The resulting support packages will be packaged as ``.tar.gz`` files
 in the ``dist`` folder.
 
 Each support package contains:
 
 * ``VERSIONS``, a text file describing the specific versions of code used to build the
   support package;
-* ``Python.xcframework``, a multi-architecture build of the Python runtime library
+* ``Python.xcframework``, a multi-architecture build of the Python runtime library.
 
-On iOS/tvOS/watchOS, the ``Python.xcframework`` contains a
+On iOS/tvOS/watchOS/visionOS, the ``Python.xcframework`` contains a
 slice for each supported ABI (device and simulator). The folder containing the
 slice can also be used as a ``PYTHONHOME``, as it contains a ``bin``, ``include``
 and ``lib`` directory.
@@ -131,8 +137,8 @@ Building binary wheels
 This project packages the Python standard library, but does not address building
 binary wheels. Binary wheels for macOS can be obtained from PyPI. `Mobile Forge
 <https://github.com/beeware/mobile-forge>`__ is a project that provides the
-tooling to build build binary wheels for iOS (and potentially for tvOS and
-watchOS, although that hasn't been tested).
+tooling to build build binary wheels for iOS (and potentially for tvOS, watchOS,
+and visionOS, although that hasn't been tested).
 
 Historical support
 ------------------

USAGE.md

@@ -2,10 +2,10 @@
 
 ## The easy way
 
-The easist way to use these packages is by creating a project with `Briefcase
-<https://github.com/beeware/briefcase>`__. Briefcase will download pre-compiled
-versions of these support packages, and add them to an Xcode project (or
-pre-build stub application, in the case of macOS).
+The easist way to use these packages is by creating a project with
+(Briefcase)[https://github.com/beeware/briefcase]. Briefcase will download
+pre-compiled versions of these support packages, and add them to an Xcode project
+(or pre-build stub application, in the case of macOS).
 
 ## The manual way
 
@@ -22,8 +22,72 @@ guides:
 * [macOS](https://docs.python.org/3/using/mac.html)
 * [iOS](https://docs.python.org/3/using/ios.html#adding-python-to-an-ios-project)
 
-For tvOS and watchOS, you should be able to broadly follow the instructions in
-the iOS guide.
+For tvOS, watchOS, and visionOS, you should be able to broadly follow the instructions
+in the iOS guide, changing some platform names in the first script. The testbed projects
+generated on iOS and visionOS may be used as rough references as well.
+
+### Using Objective C
+
+Once you've added the Python XCframework to your project, you'll need to
+initialize the Python runtime in your Objective C code (This is step 10 of the
+iOS guide linked above). This initialization should generally be done as early
+as possible in the application's lifecycle, but definitely needs to be done
+before you invoke Python code.
+
+As a *bare minimum*, you can do the following:
+
+1. Import the Python C API headers:
+   ```objc
+   #include <Python/Python.h>
+   ```
+
+2. Initialize the Python interpreter:
+   ```objc
+   NSString *resourcePath = [[NSBundle mainBundle] resourcePath];
+   NSString *pythonHome = [NSString stringWithFormat:@"%@/python", resourcePath, nil];
+   NSString *appPath = [NSString stringWithFormat:@"%@/app", resourcePath, nil];
+
+   setenv("PYTHONHOME", [pythonHome UTF8String], 1);
+   setenv("PYTHONPATH", [appPath UTF8String], 1);
+
+   Py_Initialize();
+
+   // we now have a Python interpreter ready to be used
+   ```
+
+Again - this is the *bare minimum* initialization. In practice, you will likely
+need to configure other aspects of the Python interpreter using the
+`PyPreConfig`  and `PyConfig` mechanisms. Consult the [Python documentation on
+interpreter configuration](https://docs.python.org/3/c-api/init_config.html) for
+more details on the configuration options that are available. You may find the
+[bootstrap mainline code used by
+Briefcase](https://github.com/beeware/briefcase-iOS-Xcode-template/blob/main/%7B%7B%20cookiecutter.format%20%7D%7D/%7B%7B%20cookiecutter.class_name%20%7D%7D/main.m)
+a helpful point of comparison.
+
+### Using Swift
+
+If you want to use Swift instead of Objective C, the bare minimum initialization
+code will look something like this:
+
+1. Import the Python framework:
+   ```swift
+   import Python
+   ```
+
+2. Initialize the Python interpreter:
+   ```swift
+   guard let pythonHome = Bundle.main.path(forResource: "python", ofType: nil) else { return }
+   let appPath = Bundle.main.path(forResource: "app", ofType: nil)
+
+   setenv("PYTHONHOME", pythonHome, 1)
+   setenv("PYTHONPATH", appPath, 1)
+   Py_Initialize()
+   // we now have a Python interpreter ready to be used
+   ```
+
+   Again, references to a specific Python version should reflect the version of
+   Python you are using; and you will likely need to use `PyPreConfig` and
+   `PreConfig` APIs.
 
 ### Using Objective C