GitHub - jagtesh/ApplePy: Write Python extension modules in Swift

Create native Python extensions in Swift.

ApplePy lets you build pip install-able Python packages written entirely in Swift — with direct access to Apple frameworks like CoreML, Metal, NaturalLanguage, Security, and more. Powered by Swift macros for zero-boilerplate interop. Think PyO3 for Swift.

pip install applepy-cli        # install the build tool
applepy new myproject           # scaffold a project
cd myproject && applepy develop # build & install

Version 1.0.0 — BSD-3-Clause

Quick Example

import ApplePy

@PyFunction
func greet(name: String, greeting: String = "Hello") -> String {
    "\(greeting), \(name)! 🍎"
}

@PyClass
struct Counter {
    @PyProperty var count: Int = 0

    @PyMethod
    mutating func increment() { count += 1 }

    @PyMethod
    func value() -> Int { count }
}

@PyEnum
enum Color: Int {
    case red = 0
    case green = 1
    case blue = 2
}

@PyModule("mylib", types: [Counter.self], functions: [greet])
func mylib() {}

>>> import mylib
>>> mylib.greet("World")
'Hello, World! 🍎'
>>> mylib.greet("World", "Hi")
'Hi, World! 🍎'
>>> c = mylib.Counter(10)
>>> c.increment()
>>> c.value()
11
>>> mylib.Color.red
<Color.red: 0>

Features

Macros

Macro	Purpose
`@PyFunction`	Expose top-level functions (with default argument support)
`@PyClass`	Expose structs/classes as Python types
`@PyMethod`	Mark instance methods for Python
`@PyStaticMethod`	Mark static methods for Python
`@PyProperty`	Expose stored properties with getters/setters
`@PyEnum`	Swift enum → Python `IntEnum` or class hierarchy (with associated values)
`@PyModule`	Generate `PyInit_` module entry point

Type System

Swift	Python	Direction
`Int`, `Double`, `Float`, `Bool`	`int`, `float`, `bool`	↔
`String`	`str`	↔
`[T]`	`list`	↔
`[K: V]`	`dict`	↔
`Set<T>`	`set`	↔
`Optional<T>`	`None` / value	↔
`PyTuple2<A,B>`, `PyTuple3<A,B,C>`	`tuple`	↔
`[UInt8]` / `Data`	`bytes`	→ (copy)

Safety & Runtime

Feature	Details
`GILGuard: ~Copyable`	Compile-time GIL scope enforcement — can't escape `withGIL`
`PythonHandle`	Lightweight GIL token for protocol compatibility
`@PythonActor`	Global actor for Swift concurrency integration
`PyBridged` / `PyBridge`	ARC ↔ refcount memory bridge with debug assertions
`PythonException`	Captures Python error state as Swift `Error`
`PyExceptionType`	Create custom Python exception types at runtime
`PyExceptionMapping`	Protocol to route Swift errors to specific Python exceptions

Tooling

Tool	Purpose
SPM Build Plugin	Auto-detects Python via `pkg-config`
SPM Bundle Plugin	Renames `.dylib` to CPython-compatible `.so`
`applepy-pack.py`	PEP 427 wheel packaging
`applepy-stubs.py`	Type stub (`.pyi`) generation

vs PyO3

Dimension	PyO3 (Rust)	ApplePy (Swift)
Macros	`#[pyfunction]`, `#[pyclass]`, `#[pymethods]`	`@PyFunction`, `@PyClass`, `@PyMethod`, `@PyEnum`
Memory safety	`'py` lifetimes (compile-time)	`GILGuard: ~Copyable` (compile-time)
Type conversions	15+ crate integrations	Primitives, collections, tuples, sets
Async	`pyo3-async-runtimes`	v1.1 (planned)
Build tool	`maturin`	SPM plugins + manual scripts
Enums	Class-based	`IntEnum` + class hierarchy

Getting Started

The fastest way to start a new ApplePy project is with the CLI:

# Install the CLI (pick one)
pip install applepy-cli
uv pip install applepy-cli

Then create your project:

applepy new myproject
cd myproject
applepy develop
python myproject/examples/demo.py
# → Hello, World! 🍎

The CLI handles everything: project scaffolding, Swift compilation, and packaging. See applepy-cli on PyPI for all options.

Manual Setup (SPM)

If you prefer to set things up manually, add ApplePy as a Swift package dependency:

dependencies: [
    .package(url: "https://github.com/jagtesh/ApplePy.git", from: "1.0.0"),
]

Documentation

Doc	Description
Getting Started	5-minute quickstart
Macros Reference	`@PyFunction`, `@PyClass`, `@PyMethod`, `@PyModule`
Type Conversion	Swift ↔ Python type mapping
Memory Management	ARC ↔ refcount bridge
Building & Packaging	SPM, plugins, wheels

Roadmap

Feature	Target
Async/Await ↔ Asyncio bridge	v1.1
Exception chaining / traceback	v1.1
Free-threaded Python 3.14t	v1.2
Ecosystem type bridges (Foundation.Date, Codable)	Future

Acknowledgements

Taking inspiration from PyO3, ApplePy's macro system has been adapted to Swift 6.0 — including the @PyModule peer-macro pattern, compile-time GIL safety via ~Copyable, and the names: prefixed(_applepy_) approach for global-scope macro hygiene.

GitHub - jagtesh/ApplePy: Write Python extension modules in Swift — PyO3 for Swift