Skip to main content

Pasteboard - Python interface for reading from NSPasteboard (macOS clipboard)

Project description

Pasteboard

License: MPL 2.0 CI

Pasteboard exposes Python bindings for reading and writing macOS' 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:

pip install pasteboard

Usage

Getting the contents

>>> 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. See the pasteboard module members for other options such as HTML fragment, RTF, PDF, PNG, and TIFF. Not all formats of NSPasteboardType 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 for string types, and 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

>>> 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 or 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. See the pasteboard module members for other options such as HTML fragment, RTF, PDF, PNG, and TIFF. Not all formats of NSPasteboardType are implemented.

set_contents will return True if the pasteboard was successfully set; otherwise, False. It may also throw RuntimeError if data can't be converted to an AppKit type.

Getting file URLs

>>> import pasteboard
>>> pb = pasteboard.Pasteboard()
>>> pb.get_file_urls()
('/Users/<user>/Documents/foo.txt', '/Users/<user>/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 and hypothesis).

This project uses pre-commit 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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pasteboard-0.4.0.tar.gz (28.2 kB view details)

Uploaded Source

Built Distributions

pasteboard-0.4.0-cp312-cp312-macosx_11_0_universal2.whl (30.7 kB view details)

Uploaded CPython 3.12 macOS 11.0+ universal2 (ARM64, x86-64)

pasteboard-0.4.0-cp311-cp311-macosx_11_0_universal2.whl (30.6 kB view details)

Uploaded CPython 3.11 macOS 11.0+ universal2 (ARM64, x86-64)

pasteboard-0.4.0-cp310-cp310-macosx_11_0_x86_64.whl (24.5 kB view details)

Uploaded CPython 3.10 macOS 11.0+ x86-64

pasteboard-0.4.0-cp39-cp39-macosx_11_0_x86_64.whl (24.5 kB view details)

Uploaded CPython 3.9 macOS 11.0+ x86-64

pasteboard-0.4.0-cp38-cp38-macosx_11_0_x86_64.whl (24.5 kB view details)

Uploaded CPython 3.8 macOS 11.0+ x86-64

File details

Details for the file pasteboard-0.4.0.tar.gz.

File metadata

  • Download URL: pasteboard-0.4.0.tar.gz
  • Upload date:
  • Size: 28.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/4.0.2 CPython/3.11.7

File hashes

Hashes for pasteboard-0.4.0.tar.gz
Algorithm Hash digest
SHA256 dd332253c431ada32074dd5693a231261f2bbd78465de4da27a3469f30d0f84d
MD5 9cf16b008ac88d9a95bca63c2badb617
BLAKE2b-256 beedd21829c72b2d7de85a3ef8214639e60611e92676c5559a4e879c5711b3ac

See more details on using hashes here.

File details

Details for the file pasteboard-0.4.0-cp312-cp312-macosx_11_0_universal2.whl.

File metadata

File hashes

Hashes for pasteboard-0.4.0-cp312-cp312-macosx_11_0_universal2.whl
Algorithm Hash digest
SHA256 d7e749dafc1fe75fe7dde3464e81059b1735f3de67c0edc035e5fcef3410afb8
MD5 898d1a449df6360692455a1c8486bf0a
BLAKE2b-256 59c1f488fbf6e0ab046d208155bccfa8d0bda737c66ce531bc64015238e38f02

See more details on using hashes here.

File details

Details for the file pasteboard-0.4.0-cp311-cp311-macosx_11_0_universal2.whl.

File metadata

File hashes

Hashes for pasteboard-0.4.0-cp311-cp311-macosx_11_0_universal2.whl
Algorithm Hash digest
SHA256 da509dc8c038240779b08301d53049e3b0c37229080d8010114ac351c4281d5c
MD5 53ca1c04d65727e9250ca9e56e2c37cd
BLAKE2b-256 b71d65ceb23d0df4003a7357fdcbea5026285065ac964449109dcdcf75bcd6c0

See more details on using hashes here.

File details

Details for the file pasteboard-0.4.0-cp310-cp310-macosx_11_0_x86_64.whl.

File metadata

File hashes

Hashes for pasteboard-0.4.0-cp310-cp310-macosx_11_0_x86_64.whl
Algorithm Hash digest
SHA256 bdcbfbcbf16513cf14455e3cccdd390dadcb550f6296d35b542b1238d1ea0ece
MD5 afdbf74771e287b835525c7f87e75d77
BLAKE2b-256 fe523da2b9e9d08af1ceee29de831c306b43524217bb5e78058215e85c7a8c2b

See more details on using hashes here.

File details

Details for the file pasteboard-0.4.0-cp39-cp39-macosx_11_0_x86_64.whl.

File metadata

File hashes

Hashes for pasteboard-0.4.0-cp39-cp39-macosx_11_0_x86_64.whl
Algorithm Hash digest
SHA256 247ff0e087128299dc3d8b776a6f01b67f85f26a833a504b754b661521101851
MD5 3f2d2213a84287187e5e61133aaa8982
BLAKE2b-256 a9c14f0544483502bdab170b7bc67cc592dba4ebbd32687f9173a25b667f7d7e

See more details on using hashes here.

File details

Details for the file pasteboard-0.4.0-cp38-cp38-macosx_11_0_x86_64.whl.

File metadata

File hashes

Hashes for pasteboard-0.4.0-cp38-cp38-macosx_11_0_x86_64.whl
Algorithm Hash digest
SHA256 d375e5718a22cf87eceb465c1e9d40706acdb16e75d663b64b318a599c08b02d
MD5 3cf286c9eef6a4724e9dc3228335a6d7
BLAKE2b-256 b2b48de22275633ab823cd16ace03672b431f087af78486a7b2e12dbb14bc4ae

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page