### Install Jeepney

Source: https://gitlab.com/takluyver/jeepney/-/blob/master/README.rst

Use pip to install the Jeepney library. This command installs the latest version of Jeepney.

```bash
pip install jeepney
```

--------------------------------

### Send Desktop Notification (Asyncio with Proxy)

Source: https://gitlab.com/takluyver/jeepney/-/blob/master/docs/integrate.md

This example shows how to send a desktop notification using asyncio with Jeepney's higher-level Proxy API, which wraps message generators.

```python
"""Send a desktop notification

See also aio_notify_noproxy.py, which does the same with lower-level APIs
"""
import asyncio

from jeepney import MessageGenerator, new_method_call
from jeepney.io.asyncio import open_dbus_router, Proxy

```

--------------------------------

### Typical Authentication Flow

Source: https://gitlab.com/takluyver/jeepney/-/blob/master/docs/api/auth.md

A step-by-step guide on how to perform authentication using Jeepney's authenticator.

```APIDOC
## Typical Authentication Flow

### Description
This outlines the typical sequence of operations for authenticating a D-Bus connection using Jeepney.

### Steps
1.  Send data obtained from `Authenticator.data_to_send()` (or iterate through `authenticator`).
2.  Receive data from the server and feed it into the `Authenticator` using `Authenticator.feed()`.
3.  Repeat steps 1 and 2 until `Authenticator.authenticated` is `True` or the iteration completes.
4.  Send the [`BEGIN`](#jeepney.auth.BEGIN) message.
5.  Commence sending and receiving D-Bus messages.
```

--------------------------------

### Sending a Notification

Source: https://gitlab.com/takluyver/jeepney/-/blob/master/docs/integrate.md

Example of how to send a notification using the Jeepney library.

```APIDOC
## POST /org/freedesktop/Notifications

### Description
Sends a desktop notification.

### Method
POST

### Endpoint
/org/freedesktop/Notifications

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
This method is called via `proxy.Notify` and does not have a direct request body in the typical HTTP sense. The parameters are passed directly to the method call.

### Request Example
```python
# Assuming 'proxy' is an instance of Notifications()
resp = await proxy.Notify(
    'jeepney_test',  # App name
    0,               # Not replacing any previous notification
    '',              # Icon
    'Hello, world!', # Summary
    'This is an example notification from Jeepney',
    [],              # Actions
    {{}},            # Hints
    -1               # expire_timeout (-1 = default)
)
```

### Response
#### Success Response (200)
- **notification_id** (int) - The ID of the newly created notification.
```

--------------------------------

### Example of Generated Jeepney MessageGenerator Class

Source: https://context7.com/takluyver/jeepney/llms.txt

This Python code demonstrates the structure of a `MessageGenerator` class automatically created by `jeepney.bindgen`. It defines methods corresponding to D-Bus interface methods, simplifying message creation.

```python
# Generated output looks like this:
from jeepney import MessageGenerator, new_method_call

class Notifications(MessageGenerator):
    interface = 'org.freedesktop.Notifications'

    def __init__(self, object_path='/org/freedesktop/Notifications',
                 bus_name='org.freedesktop.Notifications'):
        super().__init__(object_path=object_path, bus_name=bus_name)

    def Notify(self, app_name, replaces_id, app_icon, summary, body, actions, hints, expire_timeout):
        return new_method_call(self, 'Notify', 'susssasa{sv}i',
                               (app_name, replaces_id, app_icon, summary, body, actions, hints, expire_timeout))

    def CloseNotification(self, id):
        return new_method_call(self, 'CloseNotification', 'u', (id,))

    def GetCapabilities(self):
        return new_method_call(self, 'GetCapabilities')

    def GetServerInformation(self):
        return new_method_call(self, 'GetServerInformation')
```

--------------------------------

### Access D-Bus Object Properties with Properties Class

Source: https://context7.com/takluyver/jeepney/llms.txt

Use the `Properties` class to interact with D-Bus object properties via the `org.freedesktop.DBus.Properties` interface. This includes getting single properties, all properties, and setting properties. Note that property values are returned as a tuple of (signature, value).

```python
from jeepney import DBusAddress, Properties
from jeepney.io.blocking import open_dbus_connection

# Define the object with its specific interface
player = DBusAddress(
    '/org/mpris/MediaPlayer2',
    bus_name='org.mpris.MediaPlayer2.spotify',
    interface='org.mpris.MediaPlayer2.Player'
)

conn = open_dbus_connection(bus='SESSION')

# Get a single property
props = Properties(player)
get_msg = props.get('PlaybackStatus')
reply = conn.send_and_get_reply(get_msg)
status = reply.body[0][1]  # Variant returns (signature, value)
print(f"Playback status: {status}")

# Get all properties for the interface
get_all_msg = props.get_all()
reply = conn.send_and_get_reply(get_all_msg)
all_props = dict(reply.body[0])
for name, (sig, value) in all_props.items():
    print(f"{name}: {value}")

# Set a property (signature 'd' for double/float)
set_msg = props.set('Volume', 'd', 0.5)
conn.send_and_get_reply(set_msg)

conn.close()
```

--------------------------------

### Access D-Bus Object Properties

Source: https://context7.com/takluyver/jeepney/llms.txt

The `Properties` class provides methods to get and set properties on D-Bus objects using the standard `org.freedesktop.DBus.Properties` interface.

```APIDOC
## Properties - Access D-Bus Object Properties

### Description
The `Properties` class provides methods to get and set properties on D-Bus objects using the standard `org.freedesktop.DBus.Properties` interface.

### Class
`Properties`

### Methods
- **get(property_name)**: Retrieves a single property.
- **get_all()**: Retrieves all properties for the interface.
- **set(property_name, signature, value)**: Sets a property.

### Parameters
- **property_name** (string) - The name of the property.
- **signature** (string) - The D-Bus type signature of the property value (for `set`).
- **value** - The value of the property (for `set`).

### Request Example
```python
from jeepney import DBusAddress, Properties
from jeepney.io.blocking import open_dbus_connection

player = DBusAddress(
    '/org/mpris/MediaPlayer2',
    bus_name='org.mpris.MediaPlayer2.spotify',
    interface='org.mpris.MediaPlayer2.Player'
)

conn = open_dbus_connection(bus='SESSION')

props = Properties(player)

# Get a single property
get_msg = props.get('PlaybackStatus')
reply = conn.send_and_get_reply(get_msg)
status = reply.body[0][1]
print(f"Playback status: {status}")

# Get all properties
get_all_msg = props.get_all()
reply = conn.send_and_get_reply(get_all_msg)
all_props = dict(reply.body[0])
for name, (sig, value) in all_props.items():
    print(f"{name}: {value}")

# Set a property
set_msg = props.set('Volume', 'd', 0.5)
conn.send_and_get_reply(set_msg)

conn.close()
```
```

--------------------------------

### Define D-Bus Interface Wrappers with MessageGenerator

Source: https://context7.com/takluyver/jeepney/llms.txt

Subclass `MessageGenerator` to create typed wrappers for D-Bus interfaces. Define methods that return pre-constructed D-Bus messages for each interface method. The example shows how to create a `Notifications` wrapper.

```python
from jeepney import MessageGenerator, new_method_call

class Notifications(MessageGenerator):
    """Message generator for org.freedesktop.Notifications"""
    interface = 'org.freedesktop.Notifications'

    def __init__(
        self,
        object_path='/org/freedesktop/Notifications',
        bus_name='org.freedesktop.Notifications'
    ):
        super().__init__(object_path=object_path, bus_name=bus_name)

    def Notify(self, app_name, replaces_id, icon, summary, body, actions, hints, timeout):
        """Send a desktop notification"""
        return new_method_call(
            self, 'Notify', 'susssasa{sv}i',
            (app_name, replaces_id, icon, summary, body, actions, hints, timeout)
        )

    def CloseNotification(self, notification_id):
        """Close a notification by ID"""
        return new_method_call(self, 'CloseNotification', 'u', (notification_id,))

    def GetCapabilities(self):
        """Get server capabilities"""
        return new_method_call(self, 'GetCapabilities')

    def GetServerInformation(self):
        """Get notification server info"""
        return new_method_call(self, 'GetServerInformation')

# Usage: create a message
gen = Notifications()
msg = gen.Notify('MyApp', 0, '', 'Hello', 'World', [], {}, -1)
```

--------------------------------

### Trio Integration - Async Context Manager

Source: https://context7.com/takluyver/jeepney/llms.txt

Utilize Trio's async primitives for D-Bus operations with the Trio integration of open_dbus_router. Requires importing trio, jeepney, and jeepney.io.trio.

```python
import trio
from jeepney import MessageGenerator, new_method_call
from jeepney.io.trio import open_dbus_router, Proxy

class Notifications(MessageGenerator):
    interface = 'org.freedesktop.Notifications'

    def __init__(self):
        super().__init__('/org/freedesktop/Notifications', 'org.freedesktop.Notifications')

    def Notify(self, app, replaces, icon, summary, body, actions, hints, timeout):
        return new_method_call(self, 'Notify', 'susssasa{sv}i',
                              (app, replaces, icon, summary, body, actions, hints, timeout))

async def main():
    async with open_dbus_router(bus='SESSION') as router:
        proxy = Proxy(Notifications(), router)

        result = await proxy.Notify(
            'trio_example', 0, '', 'Hello Trio',
            'Notification from Trio', [], {}, -1
        )
        print(f"Notification ID: {result[0]}")

trio.run(main)
```

--------------------------------

### jeepney.auth.BEGIN Message

Source: https://gitlab.com/takluyver/jeepney/-/blob/master/docs/api/auth.md

The `jeepney.auth.BEGIN` message is sent just before switching to the D-Bus protocol after successful authentication.

```APIDOC
## jeepney.auth.BEGIN

### Description
Send the `jeepney.auth.BEGIN` message just before switching to the D-Bus protocol. This signifies the completion of the authentication handshake.

### Method
N/A (Message identifier)

### Endpoint
N/A (Message identifier)

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Generate D-Bus wrappers via command line

Source: https://gitlab.com/takluyver/jeepney/-/blob/master/docs/bindgen.md

Use the bindgen module to introspect a specific D-Bus service and object path to generate Python wrapper classes.

```bash
python3 -m jeepney.bindgen --name org.freedesktop.Notifications \
        --path /org/freedesktop/Notifications
```

--------------------------------

### Send Desktop Notification (Asyncio)

Source: https://gitlab.com/takluyver/jeepney/-/blob/master/docs/integrate.md

This snippet demonstrates sending a desktop notification asynchronously using Jeepney with asyncio. It utilizes `open_dbus_router` for managing the connection and message sending.

```python
"""Send a desktop notification

See also aio_notify.py, which does the same with the higher-level Proxy API.
"""
import asyncio

from jeepney import DBusAddress, new_method_call
from jeepney.io.asyncio import open_dbus_router

notifications = DBusAddress('/org/freedesktop/Notifications',
                            bus_name='org.freedesktop.Notifications',
                            interface='org.freedesktop.Notifications')

async def send_notification():
    msg = new_method_call(notifications, 'Notify', 'susssasa{sv}i',
                            ('jeepney_test',  # App name
                             0,     # Not replacing any previous notification
                             '',    # Icon
                             'Hello, world!',  # Summary
                             'This is an example notification from Jeepney',
                             [], {},  # Actions, hints
                             -1,      # expire_timeout (-1 = default)
                            ))
    # Send the message and await the reply
    async with open_dbus_router() as router:
        reply = await router.send_and_get_reply(msg)
        print('Notification ID:', reply.body[0])

loop = asyncio.get_event_loop()
loop.run_until_complete(send_notification())
```

--------------------------------

### Sending & Receiving File Descriptors

Source: https://gitlab.com/takluyver/jeepney/-/blob/master/docs/integrate.md

Demonstrates how to send and receive file descriptors over D-Bus using Jeepney.

```APIDOC
## Sending & Receiving File Descriptors

### Description
D-Bus allows sending file descriptors (references to open files, sockets, etc.). This requires enabling FD support when connecting to D-Bus.

### Sending File Descriptors
Pass an object with a `.fileno()` method (e.g., an open file, socket, or integer) to the method call. The file descriptor must not be closed before sending.

#### Request Example (Sending)
```python
# Assuming 'server' and 'router' are properly initialized
from tempfile import TemporaryFile

with TemporaryFile() as tf:
    msg = new_method_call(server, 'write_data', 'h', (tf,))
    await router.send_and_get_reply(msg)
```

### Receiving File Descriptors
Received file descriptors are returned as `FileDescriptor` objects to prevent leaks. These can be converted to file objects, sockets, or raw integers.

#### Response Example (Receiving)
```python
# Assuming 'conn' is a D-Bus connection
msg = await conn.receive()
fd, = msg.body  # fd is a FileDescriptor object

# Use as a writable file
with fd.to_file('w') as f:
    f.write(f'Timestamp: {datetime.now()}')

# Or as a raw integer
raw_fd = fd.to_raw_fd()

# Or as a socket (if applicable)
socket_obj = fd.to_socket()
```

### Versionadded
Added in version 0.7.
```

--------------------------------

### Generate D-Bus Interface Wrappers with jeepney.bindgen

Source: https://context7.com/takluyver/jeepney/llms.txt

Use the `jeepney.bindgen` command-line tool to automatically generate Python classes for D-Bus interfaces from introspection data. This simplifies creating message generators for specific services.

```bash
python3 -m jeepney.bindgen \
    --name org.freedesktop.Notifications \
    --path /org/freedesktop/Notifications \
    --output notifications.py

# Specify which bus to use (SESSION is default)
python3 -m jeepney.bindgen \
    --name org.freedesktop.UPower \
    --path /org/freedesktop/UPower \
    --bus SYSTEM \
    --output upower.py

# Generate from an XML file instead of live introspection
python3 -m jeepney.bindgen \
    --file introspection.xml \
    --output generated_bindings.py
```

--------------------------------

### CLI: jeepney.bindgen

Source: https://gitlab.com/takluyver/jeepney/-/blob/master/docs/bindgen.md

Command-line interface for generating D-Bus wrapper classes from a live service or an XML introspection file.

```APIDOC
## CLI: jeepney.bindgen

### Description
Generates Python classes defining messages to send to D-Bus services based on introspection data.

### Method
CLI Command

### Parameters
#### Options
- **-n, --name** (string) - Required (unless --file is used) - The D-Bus service name to introspect.
- **-p, --path** (string) - Required (unless --file is used) - The object path to introspect.
- **--bus** (string) - Optional - The bus to connect to (SESSION or SYSTEM). Defaults to SESSION.
- **-f, --file** (string) - Optional - Path to an XML file to use as input instead of live introspection.
- **-o, --output** (string) - Optional - Path to write the generated Python code.
```

--------------------------------

### Asyncio D-Bus Integration

Source: https://context7.com/takluyver/jeepney/llms.txt

Use open_dbus_router to handle D-Bus communication asynchronously within an event loop.

```python
import asyncio
from jeepney import DBusAddress, new_method_call
from jeepney.io.asyncio import open_dbus_router

async def send_notification():
    notifications = DBusAddress(
        '/org/freedesktop/Notifications',
        bus_name='org.freedesktop.Notifications',
        interface='org.freedesktop.Notifications'
    )

    msg = new_method_call(
        notifications,
        'Notify',
        'susssasa{sv}i',
        ('asyncio_example', 0, '', 'Hello Async', 'Asyncio example', [], {}, -1)
    )

    # open_dbus_router handles connection and cleanup
    async with open_dbus_router(bus='SESSION') as router:
        print(f"Connected as: {router.unique_name}")

        # Send message and await reply
        reply = await router.send_and_get_reply(msg)
        print(f"Notification ID: {reply.body[0]}")

asyncio.run(send_notification())
```

--------------------------------

### Send a Desktop Notification

Source: https://gitlab.com/takluyver/jeepney/-/blob/master/docs/integrate.md

This asynchronous Python function demonstrates sending a desktop notification using the generated Notifications interface and Jeepney. It requires an active D-Bus connection and establishes a router. The notification includes an app name, ID, icon, summary, and body.

```python
async def send_notification():
    async with open_dbus_router() as router:
        proxy = Proxy(Notifications(), router)

        resp = await proxy.Notify('jeepney_test',  # App name
                              0,      # Not replacing any previous notification
                              '',     # Icon
                              'Hello, world!',  # Summary
                              'This is an example notification from Jeepney',
                              [], {},  # Actions, hints
                              -1,      # expire_timeout (-1 = default)
                             )
        print('Notification ID:', resp[0])

if __name__ == '__main__':
    asyncio.run(send_notification())
```

--------------------------------

### Receive and Use a File Descriptor

Source: https://gitlab.com/takluyver/jeepney/-/blob/master/docs/integrate.md

This Python snippet demonstrates receiving a file descriptor from D-Bus using Jeepney and using it as a writable file object. Received file descriptors are returned as `FileDescriptor` objects to prevent leaks and can be converted to file objects, sockets, or raw integers.

```python
# Receive a file descriptor, use it as a writable file
msg = await conn.receive()
fd, = msg.body
with fd.to_file('w') as f:
    f.write(f'Timestamp: {datetime.now()}')
```

--------------------------------

### Handle Unix File Descriptors with Jeepney

Source: https://context7.com/takluyver/jeepney/llms.txt

Enable file descriptor (FD) support when opening a D-Bus connection using `enable_fds=True`. Use the `FileDescriptor` class for safe management of received FDs, with methods to convert them to Python file objects, sockets, or raw file descriptors.

```python
from tempfile import TemporaryFile
from jeepney import DBusAddress, new_method_call
from jeepney.io.blocking import open_dbus_connection
from jeepney.fds import FileDescriptor

# Enable FD support when connecting
conn = open_dbus_connection(bus='SESSION', enable_fds=True)

# Example: Sending a file descriptor
# The 'h' signature type represents a file descriptor
with TemporaryFile() as tf:
    tf.write(b'Hello from sender!')
    tf.seek(0)

    server = DBusAddress('/com/example/Server',
                         bus_name='com.example.Server',
                         interface='com.example.FileTransfer')

    # Send the file object (uses its fileno())
    msg = new_method_call(server, 'ReceiveFile', 'h', (tf,))
    # reply = conn.send_and_get_reply(msg)

# Example: Receiving a file descriptor
# When you receive a message containing FDs:
# received_msg = conn.receive()
# fd_wrapper = received_msg.body[0]  # FileDescriptor object

# Convert FileDescriptor to different types:
# fd_wrapper = FileDescriptor(some_fd)  # Simulating received FD

# To a Python file object
# with fd_wrapper.to_file('r') as f:
#     content = f.read()
#     print(f"Read: {content}")

# To a socket
# sock = fd_wrapper.to_socket()
# sock.sendall(b'Hello')
# sock.close()

# To raw integer (caller must close)
# raw_fd = fd_wrapper.to_raw_fd()
# os.write(raw_fd, b'data')
# os.close(raw_fd)

# Close without converting
# fd_wrapper.close()

conn.close()
```

--------------------------------

### Construct D-Bus Method Return Messages

Source: https://context7.com/takluyver/jeepney/llms.txt

Use new_method_return to create a D-Bus reply message for a method call. An empty reply can be created if no return value is expected.

```python
from jeepney import new_method_call, new_method_return, DBusAddress

# Simulate receiving a method call
address = DBusAddress('/com/example/Object', bus_name='com.example.Service', interface='com.example.Interface')
incoming_call = new_method_call(address, 'GetValue', '', ()) # Assuming no arguments
incoming_call.header.serial = 42

# Create a reply with return value
reply = new_method_return(
    incoming_call,
    'i',
    (123,)
)

# Reply without return value
empty_reply = new_method_return(incoming_call)
```

--------------------------------

### Construct D-Bus Match Rules with Jeepney

Source: https://context7.com/takluyver/jeepney/llms.txt

Use MatchRule to define filters for D-Bus signals. Supports basic filtering by type, interface, member, and path, as well as advanced filtering by sender and argument conditions. Ensure to register and remove rules with the bus proxy.

```python
from jeepney.bus_messages import MatchRule, message_bus
from jeepney.io.blocking import open_dbus_connection, Proxy

conn = open_dbus_connection()
bus_proxy = Proxy(message_bus, conn)

# Basic match rule for a signal
rule = MatchRule(
    type='signal',
    interface='org.freedesktop.Notifications',
    member='NotificationClosed',
    path='/org/freedesktop/Notifications'
)

# Match rule with sender filter
rule_with_sender = MatchRule(
    type='signal',
    sender='org.freedesktop.DBus',
    interface='org.freedesktop.DBus',
    member='NameOwnerChanged'
)

# Match rule with argument conditions
rule_with_args = MatchRule(
    type='signal',
    interface='org.freedesktop.DBus',
    member='NameOwnerChanged'
)
# Only match when first argument equals this value
rule_with_args.add_arg_condition(0, 'org.freedesktop.Notifications')

# Path namespace matching (matches path and all children)
rule_namespace = MatchRule(
    type='signal',
    interface='org.freedesktop.Secret.Collection',
    path_namespace='/org/freedesktop/secrets/collection'
)

# Register match rules with the bus
bus_proxy.AddMatch(rule)
print(f"Registered: {rule.serialise()}")

# Remove match rule when done
bus_proxy.RemoveMatch(rule)

conn.close()
```

--------------------------------

### Asyncio Proxy - Async Method Calls

Source: https://context7.com/takluyver/jeepney/llms.txt

Use the asyncio Proxy for asynchronous method calls that return awaitable coroutines. Requires importing asyncio, jeepney, and jeepney.io.asyncio.

```python
import asyncio
from jeepney import MessageGenerator, new_method_call
from jeepney.io.asyncio import open_dbus_router, Proxy

class Notifications(MessageGenerator):
    interface = 'org.freedesktop.Notifications'

    def __init__(self):
        super().__init__('/org/freedesktop/Notifications', 'org.freedesktop.Notifications')

    def Notify(self, app, replaces, icon, summary, body, actions, hints, timeout):
        return new_method_call(self, 'Notify', 'susssasa{sv}i',
                              (app, replaces, icon, summary, body, actions, hints, timeout))

    def GetCapabilities(self):
        return new_method_call(self, 'GetCapabilities')

async def main():
    async with open_dbus_router() as router:
        proxy = Proxy(Notifications(), router)

        # Await proxy method calls
        caps = await proxy.GetCapabilities()
        print(f"Server capabilities: {caps[0]}")

        notification_id = await proxy.Notify(
            'AsyncProxy', 0, '', 'Async Proxy', 'Using async proxy', [], {}, -1
        )
        print(f"Notification ID: {notification_id[0]}")

asyncio.run(main())
```

--------------------------------

### Connect with Blocking I/O

Source: https://context7.com/takluyver/jeepney/llms.txt

The blocking I/O integration is ideal for simple scripts, providing synchronous methods to send messages and wait for replies in a single thread.

```APIDOC
## Blocking I/O Integration - open_dbus_connection

### Description
The blocking I/O integration is ideal for simple scripts. It provides synchronous methods to send messages and wait for replies in a single thread.

### Function
`open_dbus_connection`

### Parameters
- **bus** (string) - Required - The D-Bus bus to connect to ('SESSION' or 'SYSTEM').

### Request Example
```python
from jeepney import DBusAddress, new_method_call
from jeepney.io.blocking import open_dbus_connection

conn = open_dbus_connection(bus='SESSION')
print(f"Connected as: {conn.unique_name}")

notifications = DBusAddress(
    '/org/freedesktop/Notifications',
    bus_name='org.freedesktop.Notifications',
    interface='org.freedesktop.Notifications'
)

# Example method call (assuming Notify method exists)
# msg = new_method_call(notifications, 'Notify', 'susssasa{sv}i', ('MyApp', 0, '', 'Hello', 'World', [], {}, -1))
# reply = conn.send_and_get_reply(msg)

conn.close()
```
```

--------------------------------

### Use DBusConnection as a Context Manager (Blocking I/O)

Source: https://gitlab.com/takluyver/jeepney/-/blob/master/docs/release-notes.md

The blocking DBusConnection integration class now supports being used as a context manager for cleaner connection handling.

```python
from jeepney.integrate.blocking import connect_and_authenticate
with connect_and_authenticate() as connection:
    ...
```

--------------------------------

### new_method_return

Source: https://context7.com/takluyver/jeepney/llms.txt

Constructs a reply message for a method call.

```APIDOC
## new_method_return

### Description
Creates a reply message in response to a method call, used when implementing D-Bus servers.

### Parameters
- **incoming_call** (Message) - Required - The original method call message.
- **signature** (string) - Optional - Signature of the return value.
- **args** (tuple) - Optional - The return values.
```

--------------------------------

### Connect to D-Bus with Blocking I/O

Source: https://context7.com/takluyver/jeepney/llms.txt

Use `open_dbus_connection` for simple scripts requiring synchronous D-Bus communication. This method provides straightforward ways to send messages and wait for replies within a single thread. Specify 'SESSION' or 'SYSTEM' for the desired bus.

```python
from jeepney import DBusAddress, new_method_call
from jeepney.io.blocking import open_dbus_connection

# Connect to the session bus (use 'SYSTEM' for system bus)
conn = open_dbus_connection(bus='SESSION')
print(f"Connected as: {conn.unique_name}")

# Define target address
notifications = DBusAddress(
    '/org/freedesktop/Notifications',
    bus_name='org.freedesktop.Notifications',
    interface='org.freedesktop.Notifications'
)


```

--------------------------------

### Asyncio Router - Async Signal Subscription

Source: https://context7.com/takluyver/jeepney/llms.txt

Subscribe to D-Bus signals asynchronously using the asyncio router's filter method, which returns an asyncio.Queue. Requires importing asyncio, jeepney, and jeepney.io.asyncio.

```python
import asyncio
from jeepney.io.asyncio import open_dbus_router, Proxy
from jeepney.bus_messages import message_bus, MatchRule

async def watch_name_changes():
    # Match rule for bus name ownership changes
    match_rule = MatchRule(
        type='signal',
        sender=message_bus.bus_name,
        interface=message_bus.interface,
        member='NameOwnerChanged',
        path=message_bus.object_path
    )

    async with open_dbus_router() as router:
        # Register match with the bus
        await Proxy(message_bus, router).AddMatch(match_rule)

        # Filter returns an async queue
        with router.filter(match_rule, bufsize=10) as queue:
            print("Watching for name changes (Ctrl+C to stop)...")
            while True:
                try:
                    msg = await asyncio.wait_for(queue.get(), timeout=10.0)
                    name, old_owner, new_owner = msg.body
                    if new_owner:
                        print(f"'{name}' acquired by {new_owner}")
                    else:
                        print(f"'{name}' released by {old_owner}")
                except asyncio.TimeoutError:
                    print("No changes in last 10 seconds...")

asyncio.run(watch_name_changes())
```

--------------------------------

### new_method_call

Source: https://context7.com/takluyver/jeepney/llms.txt

Constructs a D-Bus method call message.

```APIDOC
## new_method_call

### Description
Creates a D-Bus method call message with the specified address, method name, signature, and arguments.

### Parameters
- **address** (DBusAddress) - Required - The target address.
- **method_name** (string) - Required - The name of the method to call.
- **signature** (string) - Required - D-Bus type signature string.
- **args** (tuple) - Required - Arguments matching the signature.
```

--------------------------------

### Send Desktop Notification (Blocking I/O)

Source: https://gitlab.com/takluyver/jeepney/-/blob/master/docs/integrate.md

Use this snippet to send a desktop notification using Jeepney with blocking I/O. Ensure you have the necessary DBus services running.

```python
from jeepney import DBusAddress, new_method_call
from jeepney.io.blocking import open_dbus_connection

notifications = DBusAddress('/org/freedesktop/Notifications',
                            bus_name='org.freedesktop.Notifications',
                            interface='org.freedesktop.Notifications')

connection = open_dbus_connection(bus='SESSION')

# Construct a new D-Bus message. new_method_call takes the address, the
# method name, the signature string, and a tuple of arguments.
msg = new_method_call(notifications, 'Notify', 'susssasa{sv}i',
                      ('jeepney_test',  # App name
                       0,   # Not replacing any previous notification
                       '',  # Icon
                       'Hello, world!',  # Summary
                       'This is an example notification from Jeepney',
                       [], {},  # Actions, hints
                       -1,      # expire_timeout (-1 = default)
                      ))

# Send the message and wait for the reply
reply = connection.send_and_get_reply(msg)
print('Notification ID:', reply.body[0])

connection.close()
```

--------------------------------

### Send a File Descriptor

Source: https://gitlab.com/takluyver/jeepney/-/blob/master/docs/integrate.md

This Python snippet shows how to send a file descriptor over D-Bus using Jeepney. It requires enabling file descriptor support when connecting to D-Bus. The file descriptor is passed as an object with a `.fileno()` method, such as a temporary file.

```python
# Send a file descriptor for a temp file (normally not visible in any folder)
with TemporaryFile() as tf:
    msg = new_method_call(server, 'write_data', 'h', (tf,))
    await router.send_and_get_reply(msg)
```

--------------------------------

### Send D-Bus Messages

Source: https://context7.com/takluyver/jeepney/llms.txt

Construct and send a method call using the low-level API, either directly or via a context manager.

```python
msg = new_method_call(
    notifications,
    'Notify',
    'susssasa{sv}i',
    ('blocking_example', 0, '', 'Hello', 'Blocking I/O example', [], {}, -1)
)

# Send and wait for reply (blocks until reply received)
reply = conn.send_and_get_reply(msg)
notification_id = reply.body[0]
print(f"Notification ID: {notification_id}")

# Always close the connection when done
conn.close()

# Or use as context manager
with open_dbus_connection() as conn:
    reply = conn.send_and_get_reply(msg)
    print(f"Notification ID: {reply.body[0]}")
```

--------------------------------

### Use Blocking Proxy

Source: https://context7.com/takluyver/jeepney/llms.txt

Wrap a MessageGenerator in a Proxy to enable a more Pythonic method-call interface.

```python
from jeepney import MessageGenerator, new_method_call
from jeepney.io.blocking import open_dbus_connection, Proxy

class Notifications(MessageGenerator):
    interface = 'org.freedesktop.Notifications'

    def __init__(self):
        super().__init__(
            '/org/freedesktop/Notifications',
            'org.freedesktop.Notifications'
        )

    def Notify(self, app, replaces, icon, summary, body, actions, hints, timeout):
        return new_method_call(self, 'Notify', 'susssasa{sv}i',
                              (app, replaces, icon, summary, body, actions, hints, timeout))

    def GetServerInformation(self):
        return new_method_call(self, 'GetServerInformation')

# Use proxy for cleaner code
with open_dbus_connection() as conn:
    proxy = Proxy(Notifications(), conn)

    # Methods return the body tuple directly
    info = proxy.GetServerInformation()
    print(f"Server: {info[0]} {info[1]}")

    # Send notification with timeout
    result = proxy.Notify(
        'ProxyExample', 0, '', 'Hello', 'Using Proxy', [], {}, -1,
        _timeout=5.0  # Optional timeout in seconds
    )
    print(f"Notification ID: {result[0]}")
```

--------------------------------

### Generate Notifications Interface

Source: https://gitlab.com/takluyver/jeepney/-/blob/master/docs/integrate.md

This code defines a Python class for the D-Bus Notifications interface using Jeepney's bindgen. It includes methods for sending notifications, closing them, and retrieving capabilities or server information. Use this as a base for interacting with the system's notification service.

```python
# ---- Message generator, created by jeepney.bindgen ----
class Notifications(MessageGenerator):
    interface = 'org.freedesktop.Notifications'

    def __init__(self, object_path='/org/freedesktop/Notifications',
                 bus_name='org.freedesktop.Notifications'):
        super().__init__(object_path=object_path, bus_name=bus_name)

    def Notify(self, arg_0, arg_1, arg_2, arg_3, arg_4, arg_5, arg_6, arg_7):
        return new_method_call(self, 'Notify', 'susssasa{sv}i',
                               (arg_0, arg_1, arg_2, arg_3, arg_4, arg_5, arg_6, arg_7))

    def CloseNotification(self, arg_0):
        return new_method_call(self, 'CloseNotification', 'u',
                               (arg_0,))

    def GetCapabilities(self):
        return new_method_call(self, 'GetCapabilities')

    def GetServerInformation(self):
        return new_method_call(self, 'GetServerInformation')
# ---- End auto generated code ----
```

--------------------------------

### Define D-Bus Object Locations with DBusAddress

Source: https://context7.com/takluyver/jeepney/llms.txt

Use DBusAddress to specify the target object, bus name, and interface for D-Bus messages. Create new addresses with different interfaces using the with_interface method.

```python
from jeepney import DBusAddress

# Create an address for the desktop notifications service
notifications = DBusAddress(
    '/org/freedesktop/Notifications',           # Object path
    bus_name='org.freedesktop.Notifications',   # Bus name (destination)
    interface='org.freedesktop.Notifications'   # Interface name
)

# Create an address for the secrets service
secrets = DBusAddress(
    '/org/freedesktop/secrets',
    bus_name='org.freedesktop.secrets',
    interface='org.freedesktop.Secret.Service'
)

# Create a new address with a different interface
item_address = secrets.with_interface('org.freedesktop.Secret.Item')
```

--------------------------------

### Define D-Bus Interface Wrappers

Source: https://context7.com/takluyver/jeepney/llms.txt

The `MessageGenerator` class serves as a base for creating typed wrappers around D-Bus interfaces. Subclasses define methods that return pre-constructed messages for D-Bus methods.

```APIDOC
## MessageGenerator - Define D-Bus Interface Wrappers

### Description
The `MessageGenerator` class is the base for creating typed wrappers around D-Bus interfaces. Subclasses define methods that return pre-constructed messages for each D-Bus method.

### Class
`MessageGenerator`

### Subclass Example: Notifications
```python
from jeepney import MessageGenerator, new_method_call

class Notifications(MessageGenerator):
    interface = 'org.freedesktop.Notifications'

    def __init__((
        self,
        object_path='/org/freedesktop/Notifications',
        bus_name='org.freedesktop.Notifications'
    )):
        super().__init__(object_path=object_path, bus_name=bus_name)

    def Notify(self, app_name, replaces_id, icon, summary, body, actions, hints, timeout):
        """Send a desktop notification"""
        return new_method_call(
            self, 'Notify', 'susssasa{sv}i',
            (app_name, replaces_id, icon, summary, body, actions, hints, timeout)
        )

    def CloseNotification(self, notification_id):
        """Close a notification by ID"""
        return new_method_call(self, 'CloseNotification', 'u', (notification_id,))

    def GetCapabilities(self):
        """Get server capabilities"""
        return new_method_call(self, 'GetCapabilities')

    def GetServerInformation(self):
        """Get notification server info"""
        return new_method_call(self, 'GetServerInformation')

# Usage:
gen = Notifications()
msg = gen.Notify('MyApp', 0, '', 'Hello', 'World', [], {}, -1)
```
```

--------------------------------

### Construct D-Bus Signal Messages

Source: https://context7.com/takluyver/jeepney/llms.txt

Use `new_signal` to create broadcast signal messages for event notifications. Signals are one-way and do not expect replies. Ensure the emitter's DBusAddress includes the required interface for signals.

```python
from jeepney import DBusAddress, new_signal

# Define the emitter (sender) of the signal
emitter = DBusAddress(
    '/org/example/StatusMonitor',
    bus_name='org.example.StatusMonitor',
    interface='org.example.Status'  # Required for signals
)

# Create a signal message
signal = new_signal(
    emitter,
    'StatusChanged',           # Signal name
    'si',                      # Signature: string and int32
    ('connected', 1)           # Signal arguments
)

# Signal without arguments
simple_signal = new_signal(
    emitter,
    'Ping'
)
```

--------------------------------

### Construct D-Bus Method Call Messages

Source: https://context7.com/takluyver/jeepney/llms.txt

Use new_method_call to create a D-Bus method call message. The signature parameter uses D-Bus type codes to define the expected argument types.

```python
from jeepney import DBusAddress, new_method_call

notifications = DBusAddress(
    '/org/freedesktop/Notifications',
    bus_name='org.freedesktop.Notifications',
    interface='org.freedesktop.Notifications'
)

# Create a notification message
# Signature: s=string, u=uint32, a=array, {sv}=dict of string->variant, i=int32
msg = new_method_call(
    notifications,
    'Notify',
    'susssasa{sv}i',
    (
        'MyApp',
        0,
        'dialog-information',
        'Hello World',
        'This is the body text',
        ['action1', 'Action 1'],
        {'urgency': ('y', 1)},
        5000
    )
)

# The message can be serialized to bytes
raw_bytes = msg.serialise(serial=1)
```

--------------------------------

### Subscribe to D-Bus Signals

Source: https://context7.com/takluyver/jeepney/llms.txt

Filter incoming messages to wait for specific signals using MatchRule and connection filtering.

```python
from collections import deque
from jeepney import DBusAddress
from jeepney.bus_messages import MatchRule, message_bus
from jeepney.io.blocking import open_dbus_connection, Proxy

# Define the signal source
notifications = DBusAddress(
    '/org/freedesktop/Notifications',
    bus_name='org.freedesktop.Notifications',
    interface='org.freedesktop.Notifications'
)

conn = open_dbus_connection(bus='SESSION')

# Create a match rule for the signal
match_rule = MatchRule(
    type='signal',
    interface=notifications.interface,
    member='NotificationClosed',
    path=notifications.object_path
)

# Register the match with the message bus
bus_proxy = Proxy(message_bus, conn)
bus_proxy.AddMatch(match_rule)

# Set up filter and wait for matching signal
with conn.filter(match_rule, bufsize=10) as queue:
    print("Waiting for notification close signal...")
    # Blocks until a matching signal arrives
    signal_msg = conn.recv_until_filtered(queue, timeout=30.0)

    notification_id, reason = signal_msg.body
    reasons = {1: 'expired', 2: 'dismissed', 3: 'closed by app'}
    print(f"Notification {notification_id} closed: {reasons.get(reason, 'unknown')}")

conn.close()
```

--------------------------------

### Notifications Interface

Source: https://gitlab.com/takluyver/jeepney/-/blob/master/docs/integrate.md

Defines the methods available for the D-Bus Notifications interface.

```APIDOC
## Notifications Interface

This class provides methods to interact with the `org.freedesktop.Notifications` D-Bus interface.

### Methods

#### Notify

Sends a desktop notification.

- **app_name** (str) - The name of the application sending the notification.
- **id** (int) - The ID of the notification to replace (0 for a new notification).
- **icon** (str) - Path or name of the icon to display.
- **summary** (str) - The title of the notification.
- **body** (str) - The main text content of the notification.
- **actions** (list) - A list of actions that can be performed on the notification.
- **hints** (dict) - A dictionary of hints for customizing the notification display.
- **expire_timeout** (int) - The time in milliseconds before the notification expires (-1 for default).

#### CloseNotification

Closes a previously displayed notification.

- **id** (int) - The ID of the notification to close.

#### GetCapabilities

Retrieves the capabilities of the notification server.

#### GetServerInformation

Retrieves information about the notification server.
```

--------------------------------

### DBusAddress Class

Source: https://context7.com/takluyver/jeepney/llms.txt

Defines the target object and interface for D-Bus messages.

```APIDOC
## DBusAddress

### Description
Identifies the target object and interface for D-Bus messages by combining the object path, bus name, and interface name.

### Parameters
- **object_path** (string) - Required - The path to the D-Bus object.
- **bus_name** (string) - Required - The destination bus name.
- **interface** (string) - Required - The interface name.
```

--------------------------------

### SASL Authentication for D-Bus

Source: https://gitlab.com/takluyver/jeepney/-/blob/master/docs/api/auth.md

When setting up a socket for D-Bus, SASL authentication is required before sending D-Bus messages. This protocol is distinct from D-Bus itself. Jeepney implements a subset of SASL, sufficient for its integration layer.

```APIDOC
## SASL Authentication for D-Bus

### Description
This section details the SASL authentication process required for D-Bus socket connections using Jeepney. It is a text-based protocol separate from D-Bus.

### Method
N/A (Protocol description)

### Endpoint
N/A (Protocol description)

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### new_error

Source: https://context7.com/takluyver/jeepney/llms.txt

Constructs an error response message.

```APIDOC
## new_error

### Description
Creates an error message in response to a failed method call.

### Parameters
- **incoming_call** (Message) - Required - The original method call message.
- **error_name** (string) - Required - The D-Bus error name.
- **signature** (string) - Optional - Signature of error details.
- **args** (tuple) - Optional - Error details.
```

--------------------------------

### Parse Incoming D-Bus Data

Source: https://context7.com/takluyver/jeepney/llms.txt

Use the Parser class to process raw bytes from a socket into D-Bus messages. The parser buffers incomplete data and supports tracking required bytes for file descriptor handling.

```python
from jeepney import Parser, Message, HeaderFields

# Create a parser instance
parser = Parser()

# Feed raw data as it arrives (e.g., from a socket)
# The parser buffers incomplete messages
raw_data = b'...'  # Data from socket.recv()
parser.add_data(raw_data)

# Try to get complete messages
while True:
    msg = parser.get_next_message()
    if msg is None:
        break  # Need more data

    # Process the message
    print(f"Message type: {msg.header.message_type}")
    print(f"Serial: {msg.header.serial}")

    # Access header fields
    if HeaderFields.sender in msg.header.fields:
        print(f"Sender: {msg.header.fields[HeaderFields.sender]}")
    if HeaderFields.member in msg.header.fields:
        print(f"Method/Signal: {msg.header.fields[HeaderFields.member]}")

    # Access body data
    print(f"Body: {msg.body}")

# Alternative: feed() returns a list of completed messages
messages = parser.feed(more_data)
for msg in messages:
    print(msg.body)

# For FD-aware parsing, track how much data to read
bytes_needed = parser.bytes_desired()  # Read exactly this much for FD handling
```

--------------------------------

### Construct Signal Messages

Source: https://context7.com/takluyver/jeepney/llms.txt

The `new_signal` function creates broadcast signal messages for event notifications. Signals are one-way and do not expect replies.

```APIDOC
## new_signal - Construct Signal Messages

### Description
The `new_signal` function creates a broadcast signal message. Signals are one-way messages with no reply, used for event notifications.

### Method
`new_signal`

### Parameters
- **emitter** (DBusAddress) - Required - The sender of the signal.
- **signal_name** (string) - Required - The name of the signal.
- **signature** (string) - Optional - The D-Bus type signature of the arguments.
- **args** (tuple) - Optional - The arguments for the signal.

### Request Example
```python
from jeepney import DBusAddress, new_signal

emitter = DBusAddress(
    '/org/example/StatusMonitor',
    bus_name='org.example.StatusMonitor',
    interface='org.example.Status'
)

signal = new_signal(
    emitter,
    'StatusChanged',
    'si',
    ('connected', 1)
)

simple_signal = new_signal(emitter, 'Ping')
```
```

--------------------------------

### Query D-Bus Object Interfaces

Source: https://context7.com/takluyver/jeepney/llms.txt

The `Introspectable` class provides access to D-Bus introspection, which returns XML describing an object's interfaces, methods, signals, and properties.

```APIDOC
## Introspectable - Query D-Bus Object Interfaces

### Description
The `Introspectable` class provides access to D-Bus introspection, which returns XML describing an object's interfaces, methods, signals, and properties.

### Class
`Introspectable`

### Method
- **Introspect()**: Returns the introspection XML for the object.

### Request Example
```python
from jeepney import Introspectable
from jeepney.io.blocking import open_dbus_connection

conn = open_dbus_connection(bus='SESSION')

intro = Introspectable(
    object_path='/org/freedesktop/Notifications',
    bus_name='org.freedesktop.Notifications'
)

reply = conn.send_and_get_reply(intro.Introspect())
xml_data = reply.body[0]
print(xml_data)

conn.close()
```
```