https://github.com/tobywf/pasteboard
UNSUPPORTED Pasteboard - Python interface for NSPasteboard (macOS clipboard)
https://github.com/tobywf/pasteboard
appkit clipboard macos nspasteboard pasteboard python3
Last synced: 10 months ago
JSON representation
UNSUPPORTED Pasteboard - Python interface for NSPasteboard (macOS clipboard)
- Host: GitHub
- URL: https://github.com/tobywf/pasteboard
- Owner: tobywf
- License: mpl-2.0
- Created: 2017-12-10T20:09:06.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2024-09-03T23:20:25.000Z (over 1 year ago)
- Last Synced: 2025-05-22T02:49:57.419Z (12 months ago)
- Topics: appkit, clipboard, macos, nspasteboard, pasteboard, python3
- Language: Objective-C
- Homepage: https://pypi.org/project/pasteboard/
- Size: 67.4 KB
- Stars: 35
- Watchers: 3
- Forks: 7
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Pasteboard
[](https://opensource.org/licenses/MPL-2.0) [](https://github.com/tobywf/pasteboard/actions)
[Pasteboard](https://pypi.org/project/pasteboard/) exposes Python bindings for reading and writing macOS' AppKit [NSPasteboard](https://developer.apple.com/documentation/appkit/nspasteboard). This allows retrieving different formats (HTML/RTF fragments, PDF/PNG/TIFF) and efficient polling of the pasteboard.
Now with type hints!
## Installation
Python 3.8+ is required. Obviously, this module will only compile on **macOS**:
```bash
pip install pasteboard
```
## Usage
### Getting the contents
```pycon
>>> import pasteboard
>>> pb = pasteboard.Pasteboard()
>>> pb.get_contents()
'pasteboard'
>>> pb.get_contents(diff=True)
>>>
```
Unsurprisingly, `get_contents` gets the contents of the pasteboard. This method
takes two optional arguments:
**type** - The format to get. Defaults to `pasteboard.String`, which corresponds
to [NSPasteboardTypeString](https://developer.apple.com/documentation/appkit/nspasteboardtypestring?language=objc). See the `pasteboard` module members for other
options such as HTML fragment, RTF, PDF, PNG, and TIFF. Not all formats of [NSPasteboardType](https://developer.apple.com/documentation/appkit/nspasteboardtype?language=objc) are implemented.
**diff** - Defaults to `False`. When `True`, only get and return the contents if it has changed since the last call. Otherwise, `None` is returned. This can be used to efficiently monitor the pasteboard for changes, which must be done by polling (there is no option to subscribe to changes).
`get_contents` will return the appropriate type, so [str](https://docs.python.org/3/library/stdtypes.html#str) for string types,
and [bytes](https://docs.python.org/3/library/stdtypes.html#bytes) for binary types. `None` is returned when:
* There is no data of the requested type (e.g. an image was copied but a string was requested)
* **diff** is `True`, and the contents has not changed since the last call
* An error occurred
### Setting the contents
```pycon
>>> import pasteboard
>>> pb = pasteboard.Pasteboard()
>>> pb.set_contents('pasteboard')
True
>>>
```
Analogously, `set_contents` sets the contents of the pasteboard. This method
takes two arguments:
**data** - [str](https://docs.python.org/3/library/stdtypes.html#str) or [bytes-like object](https://docs.python.org/3/glossary.html#term-bytes-like-object), required. There is no type checking. So if `type` indicates a string type and `data` is bytes-like but not UTF-8 encoded, the behaviour is undefined.
**type** - The format to set. Defaults to `pasteboard.String`, which corresponds to [NSPasteboardTypeString](https://developer.apple.com/documentation/appkit/nspasteboardtypestring?language=objc). See the `pasteboard` module members for other options such as HTML fragment, RTF, PDF, PNG, and TIFF. Not all formats of [NSPasteboardType](https://developer.apple.com/documentation/appkit/nspasteboardtype?language=objc) are implemented.
`set_contents` will return `True` if the pasteboard was successfully set; otherwise, `False`. It may also throw [RuntimeError](https://docs.python.org/3/library/exceptions.html#RuntimeError) if `data` can't be converted to an AppKit type.
### Getting file URLs
```pycon
>>> import pasteboard
>>> pb = pasteboard.Pasteboard()
>>> pb.get_file_urls()
('/Users//Documents/foo.txt', '/Users//Documents/bar.txt')
```
**Warning** This API is new, and may change in future.
Returns a `Tuple` of strings, or `None`. Also supports the **diff** parameter analogue to `get_contents`.
## Development
You don't need to know this if you're not changing `pasteboard.m` code. There are some integration tests in `tests.py` to check the module works as designed (using [pytest](https://docs.pytest.org/en/latest/) and [hypothesis](https://hypothesis.readthedocs.io/en/latest/)).
This project uses [pre-commit](https://pre-commit.com/) to run some linting hooks when committing. When you first clone the repo, please run:
```
pre-commit install
```
You may also run the hooks at any time:
```
pre-commit run --all-files
```
To install development dependencies, use:
```
python3 -m venv env
source env/bin/activate
pip install .[dev]
```
This will also install development dependencies (`pytest`). To run the tests:
```
pytest tests.py --verbose
```
## License
From version 0.3.0 and forwards, this library is licensed under the Mozilla Public License Version 2.0. For more information, see `LICENSE`.