Swift Packages

This section covers how to create and use Swift packages in your Kivy apps for iOS, so you can reuse Swift code and libraries across projects.

Creating a Swift Package

To create a Swift package, you will need to follow these steps:

Project Structure

We will assume you followed the Creating a Kivy iOS Project guide and have a Kivy project set up. At this point, your project structure should look like this:

hello-world-project
├── hello-world
│   ├── pyproject.toml
│   ├── README.md
│   ├── src
│   │   └── hello_world
│   │       ├── __init__.py
│   │       ├── main.py
│   └── uv.lock
└── hello-world-xcode
    ├── app
    ├── HelloWorld.xcodeproj
    ├── IphoneOS
    ├── requirements.txt
    ├── site_packages.iphoneos
    ├── site_packages.iphonesimulator
    └── Support

Creating the Swift Package

Let's create a folder to host Swift packages and then use psproject to create a package template. Run this command from the working directory (hello-world-project):

// Create Swift packages directory and enter it
$ mkdir swift_packages
$ cd swift_packages

// Initialize a new Swift package called "HelloWorldPackage"
$ psproject template package HelloWorldPackage

This will create a folder called HelloWorldPackage inside the swift_packages directory, containing the necessary files for a Swift package.

hello-world-project
├── hello-world
├── hello-world-xcode
└── swift_packages
    └── HelloWorldPackage

Adding the Swift Package to Xcode

Now you should Drag and Drop the HelloWorldPackage folder into the Frameworks section of your Xcode project. A popup will appear, just confirm the addition. This will allow you to use the Swift package in your Kivy app.

Enabling Type Annotations

Now, to add type annotation stubs for your IDE, add the HelloWorldPackage to Frameworks, Libraries, and Embedded Content in the General tab of your target in Xcode. Follow the steps in the image below:

Enable Type Annotations for Swift Package

1. Click on your project in the Project Navigator. (HelloWorld)
2. Select your target. (HelloWorld-iphoneos)
3. Go to the General tab.
4. Scroll down to the Frameworks, Libraries, and Embedded Content section, and click the + button.
5. Select HelloWorldPackage from the list and click Add.

This will enable type annotations for the Swift package in your Kivy app.

Adding Swift Code

To add Swift code to your package, click on HelloWorldPackage.swift in the Project Navigator.

Then, let's add the same code as we concluded the previous section with:

import Foundation
import PySwiftKit
import PySerializing
import PySwiftObject
import PySwiftWrapper


@PyClass
class User {
    @PyProperty
    var name: String = "Test"

    @PyInit
    init(name: String) {
        self.name = name
    }

    @PyMethod
    func greet() {
        print("Hello, \(self.name)!")
    }
}


@PyModule
struct Auth: PyModuleProtocol {
    static var py_classes: [any (PyClassProtocol & AnyObject).Type] = [
        User.self
    ]
}

Many errors will appear. Press Ctrl+B to build the project and generate the necessary Swift bindings and allow Xcode to recognize the new classes.

Generating Type Annotation Stubs

Finally, generate the actual stubs. Inside Xcode:

1. Right-click on HelloWorldPackage in the Frameworks folder.
2. Click on PyFileGenerator.
3. This will create the type annotation stub for your IDE.

Example stub file:

from typing import Callable, Protocol

class User():
    name: str

    def __init__(self, *args, **kwargs): ...

    def greet(self): ...

Adding the Swift Package in Editable Mode

For Python to see the Swift package sources, add it in editable mode with uv. Open the hello-world folder in the terminal:

hello-world-project
├── hello-world
├── hello-world-xcode
└── swift_packages

// Run this from hello-world folder
$ uv add ../swift_packages/HelloWorldPackage --editable

Using the Swift Package

Now you can use the Swift package in your Kivy app. Import the necessary modules and use the classes as needed. For example:

import auth
from kivy.app import App
from kivy.lang import Builder

kv = """
Button:
    text: "Greet User"
    on_release: app.greet_user()
"""


class MainApp(App):
    def build(self):
        return Builder.load_string(kv)

    def greet_user(self):
        user = auth.User("Kivy School")
        user.greet()  # Prints: Hello, Kivy School!


app = MainApp()
app.run()

Conclusion

At this point, your Swift package is fully integrated with your Kivy iOS project.
You have:

1. Created the Swift package.
2. Added it to Xcode for iOS builds.
3. Enabled type annotations in Xcode.
4. Written Swift code and built the project.
5. Generated Python type stubs with PyFileGenerator.
6. Linked the package in editable mode with uv so Python can access it directly.
7. Used the Swift package in your Kivy app.

With this setup, you can extend your Kivy apps with Swift code while retaining IDE support, autocompletion, and type checking across both Swift and Python.