Metadata-Version: 2.5
Name: pymacos
Version: 1.1.0
Summary: Control your Mac from Python: notifications, clipboard, apps, Keychain, speech and more.
Project-URL: Homepage, https://github.com/JeanExtreme002/pymacos
Project-URL: Documentation, https://macos.readthedocs.io
Project-URL: Repository, https://github.com/JeanExtreme002/pymacos
Project-URL: Issues, https://github.com/JeanExtreme002/pymacos/issues
Project-URL: Changelog, https://github.com/JeanExtreme002/pymacos/releases
Project-URL: Funding, https://github.com/sponsors/JeanExtreme002
Author-email: Jean Loui Bernard Silva de Jesus <contact@jeanloui.dev>
Maintainer-email: Jean Loui Bernard Silva de Jesus <contact@jeanloui.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: appkit,automation,battery,caffeinate,clipboard,cocoa,ctypes,dark-mode,finder,keychain,mac,macos,notifications,osx,screenshot,shortcuts,text-to-speech
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Desktop Environment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: flake8; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# pymacos

**A Pythonic interface to macOS.** Notifications, clipboard, dark mode, apps, Keychain, speech, screenshots, battery, Shortcuts and Finder, all from one import with zero dependencies.

<table>
    <tr>
        <th>docs</th>
        <td>
            <a href="https://macos.readthedocs.io/?badge=latest"><img
                alt="Documentation Status"
                src="https://readthedocs.org/projects/macos/badge/?version=latest"></a>
        </td>
    </tr>
    <tr>
        <th>tests</th>
        <td>
            <a href="https://github.com/JeanExtreme002/pymacos/actions/workflows/python-package.yml"><img
                alt="GitHub Actions build status (lint, tests on macOS and Linux, docs)"
                src="https://github.com/JeanExtreme002/pymacos/actions/workflows/python-package.yml/badge.svg"></a>
            <a href="https://app.codecov.io/gh/JeanExtreme002/pymacos"><img
                alt="Code coverage"
                src="https://codecov.io/gh/JeanExtreme002/pymacos/branch/main/graph/badge.svg"></a>
        </td>
    </tr>
    <tr>
        <th>package</th>
        <td>
            <a href="https://pypi.org/project/pymacos/"><img
                alt="Newest PyPI version"
                src="https://img.shields.io/pypi/v/pymacos.svg"></a>
            <a href="https://pypi.org/project/pymacos/"><img
                alt="Supported Python versions"
                src="https://img.shields.io/pypi/pyversions/pymacos.svg?color=8A2BE2"></a>
            <a href="https://pypi.org/project/pymacos/"><img
                alt="Platform"
                src="https://img.shields.io/badge/platform-macOS-lightgrey.svg"></a>
            <a href="https://pypi.org/project/pymacos/"><img
                alt="Typed"
                src="https://img.shields.io/pypi/types/pymacos.svg"></a>
            <a href="https://github.com/JeanExtreme002/pymacos/blob/main/LICENSE"><img
                alt="License"
                src="https://img.shields.io/pypi/l/pymacos.svg"></a>
        </td>
    </tr>
</table>

```python
import macos

macos.notify("Build finished", title="CI")
macos.say("Done!")

macos.clipboard.copy("hello")
macos.appearance.is_dark()                      # True
macos.screenshot("screen.png")

macos.apps.open("Safari")                       # App(name='Safari', ...)
macos.keychain.get("my-app", "alice")           # 's3cret'

macos.power.battery()                           # Battery(percent=87, charging=True, ...)
macos.shortcuts.run("Translate", input="Olá")   # 'Hello'
macos.finder.trash("old.log")                   # moved to the Trash
```

## Install

```bash
pip install pymacos
```

The package is installed as `pymacos` and imported as `macos`.

Requires macOS and Python 3.9+.

## Why

A notification from plain Python means AppleScript inside a string, which breaks as soon as the message contains a quote:

```python
subprocess.run(["osascript", "-e", 'display notification "Build finished" with title "CI"'])
```

With pymacos:

```python
macos.notify("Build finished", title="CI")
```

Across the whole package:

- No dependencies: no PyObjC, nothing to compile.
- Plain, typed functions that return Python objects.
- Any text is safe: nothing is pasted into shell or AppleScript source.
- Clear errors when macOS is missing a permission, instead of silent failures.

See [Why pymacos?](https://macos.readthedocs.io/en/latest/why.html) for a longer comparison.

## Documentation

The full guide and API reference are at **[macos.readthedocs.io](https://macos.readthedocs.io)**.

## License

Released under the [MIT License](https://github.com/JeanExtreme002/pymacos/blob/main/LICENSE) — free for personal and commercial use.

<sub>Not affiliated with or endorsed by Apple Inc. macOS is a trademark of Apple Inc.</sub>
