Skip to main content

kivy-garden-pyle

日本語版

project logo

pyle is an experimental library aimed at reducing the boilerplate needed to create Kivy bindings without using the Kv language.

For example, suppose you want a function that adds a solid-color background to a specific Widget instance as well as the way to revert it. Your code might look like this:

from contextlib import ExitStack

from kivy.graphics import Color, Rectangle
from kivy.clock import Clock


def add_solid_background(widget, *, color=(1., 1. , 1., .3)):
	'''
	Adds a solid-color background to widget and returns a function that reverts it.
	'''
	with ExitStack() as stack:
		defer = stack.callback

		before = widget.canvas.before
		with before:
			defer(before.remove, Color(*color))
			defer(before.remove, rect := Rectangle(pos=widget.pos, size=widget.size))

		def sync_graphics(dt, rect=rect, w=widget):
			rect.pos = w.pos
			rect.size = w.size
		t = Clock.create_trigger(sync_graphics, -1)
		defer(t.cancel)
		widget.bind(pos=t, size=t)
		defer(widget.unbind, pos=t, size=t)

		return stack.pop_all().close


revert = add_solid_background(widget)
...
revert()

Now, here is what an equivalent implementation looks like with pyle:

from contextlib import ExitStack

from kivy.graphics import Color, Rectangle

from kivy_garden import pyle


def add_solid_background(widget, *, color=(1., 1. , 1., .3)):
	with ExitStack() as stack:
		defer = stack.callback

		before = widget.canvas.before
		with before:
			defer(before.remove, Color(*color))
			defer(before.remove, rect := Rectangle(pos=widget.pos, size=widget.size))

		@pyle.throttle_rule
		def sync_graphics(dt, rect=rect, w=widget):
			rect.pos = w.pos
			rect.size = w.size
		stack.enter_context(sync_graphics)

		return stack.pop_all().close

As you can see, the binding code becomes cleaner. And of course, if you are using an async library, you may want to implement the feature as a context manager:

from contextlib import ExitStack, contextmanager

from kivy.graphics import Color, Rectangle

from kivy_garden import pyle


@contextmanager
def add_solid_background(widget, *, color=(1., 1. , 1., .3)):
	with ExitStack() as stack:
		# omitted for brevity

		@pyle.throttle_rule
		def sync_graphics(dt, rect=rect, w=widget):
			rect.pos = w.pos
			rect.size = w.size
		stack.enter_context(sync_graphics)

		yield

In the examples above, the @pyle.throttle_rule decorator turns sync_graphics into a context manager. At this point, bindings are not yet enabled; they are enabled only while the context manager is active.

The context manager is not reentrant, but it is reusable:

# error
with sync_graphics:
    with sync_graphics:
        ...

# fine
with sync_graphics:
    ...
with sync_graphics:
    ...

Installation

Pin the minor version.

pip install "kivy-garden-pyle>=0.2,<0.3"

How does it know which Kivy properties should be observed?

It analyzes the signature and bytecode of the given function. When the function has a pre-filled argument that is an instance of EventDispatcher, any of its Kivy properties accessed via LOAD_ATTR will be observed.

Only the following types of "pre-filled" arguments are subjected to observation:

  • default values like in the sync_graphics example (w=widget)
  • values bound with functools.partial
  • self arguments bound via obj.instance_method

Any other way of filling arguments will not create bindings. For more details, please see test_detect_dependencies.py.

Tested on

  • CPython 3.11 + Kivy 2.3.1
  • CPython 3.12 + Kivy 2.3.1
  • CPython 3.13 + Kivy 2.3.1
  • CPython 3.14 + Kivy be90b9f

Metadata

Release files for kivy-garden-pyle 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kivy-garden-pyle 0.2.0
File Size Uploaded Provenance Actions
kivy_garden_pyle-0.2.0.tar.gz 4.1 kB With provenance Details for kivy_garden_pyle-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for kivy-garden-pyle 0.2.0
File Interpreter ABI Platform Actions
kivy_garden_pyle-0.2.0-py3-none-any.whl Python 3 none any Details for kivy_garden_pyle-0.2.0-py3-none-any.whl

Total release size: 8.9 kB

Release files / kivy_garden_pyle-0.2.0.tar.gz

Download URL kivy_garden_pyle-0.2.0.tar.gz
Size 4.1 kB
Tags Source
SHA-256 checksum
How to use checksums
c2ce176cd006203634b647e095774755ae7b6672cf744e6c3e7cbc50d0304b24
BLAKE2b-256 checksum
How to use checksums
fddb03eff3825accabf806020069ee01a3b24492338206886c606c9365c0a481
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.

Transparency log

Release files / kivy_garden_pyle-0.2.0-py3-none-any.whl

Download URL kivy_garden_pyle-0.2.0-py3-none-any.whl
Size 4.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b295d637a0a861271dd08bc586c7a7c27481b18ffc5278d9793b56ec4b593227
BLAKE2b-256 checksum
How to use checksums
ebcfe6606d03f69e44f8e0a2b9c6c937d826311c3c9b86f6660947389ffad6d6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.

Transparency log

Security for kivy-garden-pyle 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for kivy_garden_pyle-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page