Metadata-Version: 2.4
Name: cocoa-py
Version: 0.1.0a2
Summary: Native Apple platform modules for Python
Author: Yosorable
License-Expression: MIT
Project-URL: Source, https://github.com/Yosorable/cocoa-py
Project-URL: Issues, https://github.com/Yosorable/cocoa-py/issues
Keywords: apple,macos,coreml,native,inference
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: iOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Objective C
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.15,>=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: native/physics/box2d/LICENSE
Provides-Extra: coreml
Requires-Dist: numpy<3,>=2.3.3; extra == "coreml"
Dynamic: license-file

# cocoa-py

Native Apple platform modules for Python, maintained independently of their
original host, [Pythona](https://pythona.app).

One distribution provides independent top-level imports:

| Module | Capabilities |
| --- | --- |
| `audio` | File and PCM playback, streaming recording, effects, rate/pitch control, offline mixing and WAV/CAF/M4A export. |
| `scene` | Metal-rendered 2D scenes, shapes, sprites, text, animation, input and Box2D physics. |
| `coreml` | Core ML model compilation, inspection and NumPy-based inference. |
| `photos` | System media picker and saving images/videos to Photos. |
| `location` | Foreground location fixes, bounded update streams and address geocoding. |
| `motion` | Bounded iOS accelerometer, gyroscope, magnetometer and device-motion streams. |
| `clipboard` | Text and typed byte representations on the system clipboard. |
| `share` | System sharing UI for text, URLs and files. |
| `device` | OS, hardware, power, battery and storage information. |
| `notification` | Permission, scheduling and management of local notifications. |

There is no `cocoa.` import prefix. Importing one module does not import the
others or request permissions. `coreml` initializes its NumPy interface when
imported; the other modules do not require NumPy unless using an array helper.
Rubicon-ObjC is not a dependency.

## Status and installation

**0.1.0a2** is an alpha release of the module collection described above.
It provides Apple Silicon macOS and arm64 iPhoneOS wheels on
[PyPI](https://pypi.org/project/cocoa-py/0.1.0a2/), plus a source distribution.
The earlier **0.1.0a1** preview contained only Core ML.

The current source targets **macOS 14+**, **iOS 17+**, and standard **CPython 3.14
with the GIL**. macOS wheels are built with Apple's SDK; iOS hosts install a
matching iPhoneOS wheel before packaging their application. Native macOS motion sensors are not
available and are reported as unsupported.

On an Apple Silicon Mac, install the wheel in a CPython 3.14 environment:

```sh
python3.14 -m venv .venv
source .venv/bin/activate
python -m pip install 'cocoa-py[coreml]==0.1.0a2'
```

The `coreml` extra installs NumPy for inference. Use `cocoa-py==0.1.0a2` without
the extra if you do not need NumPy. Installing a matching wheel does not require
Xcode. Source builds require Apple's development tools and use NumPy headers in
an isolated build environment.

## Start using the modules

```python
import device
import audio

print(device.info())
with audio.Sound("sound.wav") as sound:
    channel = sound.play()
    channel.wait()
```

For permission-sensitive desktop scripts, use the supplied launcher:

```sh
cocoa-py my_script.py
cocoa-py -m my_package
```

The launcher keeps the current virtual environment and runs CPython in a small
macOS app with the required usage descriptions. It does not install a second
Python distribution. Ordinary `python` remains suitable for offline audio,
Core ML inference and scene windows. See [macOS execution](https://github.com/Yosorable/cocoa-py/blob/main/docs/macos.md) for
permissions, IDE use and event-loop requirements.

```python
import location

position = location.current(timeout=30)
print(position.latitude, position.longitude, position.horizontal_accuracy)

with location.watch(distance_filter=10) as updates:
    sample = updates.read(timeout=10)
    print(sample)
```

The host application's system permissions apply to scripts running inside it.
Applications embedding these modules must supply their own usage descriptions
and lifecycle integration; see [iOS embedding](https://github.com/Yosorable/cocoa-py/blob/main/docs/embedding.md).

## Documentation

- [Module API guide](https://github.com/Yosorable/cocoa-py/blob/main/docs/api.md)
- [macOS execution and permissions](https://github.com/Yosorable/cocoa-py/blob/main/docs/macos.md)
- [Embedding in an iOS application](https://github.com/Yosorable/cocoa-py/blob/main/docs/embedding.md)
- [Architecture and resource ownership](https://github.com/Yosorable/cocoa-py/blob/main/docs/architecture.md)
- [Third-party code](https://github.com/Yosorable/cocoa-py/blob/main/docs/third-party.md)
- [0.1.0a2 release](https://github.com/Yosorable/cocoa-py/blob/main/docs/releases/0.1.0a2.md)
- [Initial Core ML release](https://github.com/Yosorable/cocoa-py/blob/main/docs/releases/0.1.0a1.md)

The Python wrappers contain full signatures and docstrings, available through
`help(audio.Sound)`, `help(location.Watch)`, and equivalent Python introspection.

## Build and validate

```sh
git clone https://github.com/Yosorable/cocoa-py.git
cd cocoa-py
python -m pip install build
MACOSX_DEPLOYMENT_TARGET=14.0 python -m build
python -m unittest discover -s tests -v
COCOA_PY_UI_TESTS=1 python -m unittest discover -s tests -v
```

Tests exercise actual native audio rendering, Metal readback, Box2D and Core ML.
The UI option briefly opens desktop scene and sharing windows without selecting
or sharing personal data. `COCOA_PY_NETWORK_TESTS=1` additionally exercises Apple's
geocoder with a public address. Permission prompts, recording, phone sensors,
Photos selection and hardware routing are separate device checks.

To produce an iOS wheel with a CPython 3.14 framework for arm64 devices:

```sh
python3.14 tools/build_ios_wheel.py --python-framework /path/to/ios-arm64/Python.framework
COCOA_PY_IOS_WHEEL=dist/cocoa_py-0.1.0a2-cp314-cp314-ios_17_0_arm64_iphoneos.whl \
  python3.14 -m unittest discover -s tests -p test_ios_wheel.py -v
```

This compiles all seven extensions and the scene shader library. It does not
build or run a simulator. The iOS wheel excludes the macOS launcher. Published
versions correspond to Git tags such as `v0.1.0a2`; hosts should pin the release
version and record the downloaded wheel's SHA-256.

## License

MIT. Copyright (c) 2026 Yosorable. Box2D retains its upstream MIT license.
