### Install development and documentation dependencies

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/intro.rst

Commands to clone the repository and install optional components for running tests or building documentation.

```shell
git clone https://github.com/eclipse-cyclonedds/cyclonedds-python
cd cyclonedds-python

# Testsuite:
pip install .[dev]
pytest

# Documentation
pip install .[docs]
cd docs
sphinx-build ./source ./build
python -m http.server --directory build
```

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

### Install Documentation Dependencies

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/how-to-build.md

Install the necessary Python packages for building the documentation using pip and the requirements.txt file.

```bash
pip install -r requirements.txt
```

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

### Install Cyclone DDS Python from source

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/intro.rst

Installation command using a specific CYCLONEDDS_HOME path and a GitHub repository URL.

```shell
CYCLONEDDS_HOME="/path/to/cyclonedds" pip install git+https://github.com/eclipse-cyclonedds/cyclonedds-python
```

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

### ResourceLimits Policy Example

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.qos.rst

Demonstrates how to instantiate a ResourceLimits policy with specific constraints.

```pycon
>>> Policy.ResourceLimits(
>>>     max_samples=10,
>>>     max_instances=10,
>>>     max_samples_per_instance=2
>>> )
```

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

### Install CycloneDDS Python with Pre-built Binaries

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/README.md

Use this command for the simplest installation when DDS Security and shared memory via Iceoryx are not required.

```bash
    $ pip install cyclonedds
```

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

### Build and Install CycloneDDS Python from Git

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/README.md

This method clones the CycloneDDS repository, builds and installs it, sets the CYCLONEDDS_HOME environment variable, and then installs the Python package directly from a git repository.

```bash
$ git clone https://github.com/eclipse-cyclonedds/cyclonedds
$ cd cyclonedds && mkdir build install && cd build
$ cmake .. -DCMAKE_INSTALL_PREFIX=../install
$ cmake --build . --config RelWithDebInfo --target install
$ cd ..
$ export CYCLONEDDS_HOME="$(pwd)/install"
$ pip3 install git+https://github.com/eclipse-cyclonedds/cyclonedds-python
```

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

### Watch mode output example

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/tools.ddsls.rst

Example output showing new and disposed participant events in watch mode.

```text
-- New PARTICIPANT --
key: 713b1001-bb82-49db-9f2a-46f4000001c1
qos: Qos()


-- Disposed PARTICIPANT --
key: 713b1001-68a5-e15c-2709-d195000001c1
qos: Qos()
```

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

### Create a DomainParticipant in Python

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/tools.ddsls.rst

Example script to initialize a DomainParticipant on a specific domain ID.

```python
from cyclonedds.domain import DomainParticipant

dp = DomainParticipant(1)
```

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

### CMake Minimum Requirements and Project Setup

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/tests/support_modules/fuzz_tools/rand_idl/c_app/CMakeLists.txt

Sets the minimum CMake version and defines the project name and language. Ensure CycloneDDS is installed and findable.

```cmake
cmake_minimum_required(VERSION 3.16)
project(xtypes_sub LANGUAGES C)
find_package(CycloneDDS REQUIRED)
```

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

### Configure QoS policies

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/tools.pubsub.rst

Examples of applying single or multiple QoS policies to the pubsub tool via command-line arguments.

```console
$ pubsub --topic hello --qos Reliability.BestEffort
```

```console
$ pubsub --topic hello --qos Reliability.BestEffort History.KeepLast 10
```

```console
$ pubsub --topic hello --qos DurabilityService 1000, History.KeepLast 10, 100, 10, 10
```

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

### Reliability Policy Examples

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.qos.rst

Demonstrates how to access BestEffort and Reliable reliability policies.

```pycon
>>> Policy.Reliability.BestEffort
>>> Policy.Reliability.Reliable(max_blocking_time=duration(seconds=1))
```

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

### Verbose mode output example

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/tools.ddsls.rst

Example output when running ddsls in verbose mode, including full entity QoS details.

```console
Qos changed on topic 'MessageTopic' publication:
 key = e4921001-4edb-926f-14be-adb500000102
 Policy.OwnershipStrength(strength=10) -> Policy.OwnershipStrength(strength=20)
 Policy.Userdata(data=b'Old') -> Policy.Userdata(data=b'New')

-- New PUBLICATION --
key: e4921001-4edb-926f-14be-adb500000102
participant_key: e4921001-4edb-926f-14be-adb5000001c1
participant_instance_handle: 2236347693610277994
topic_name: MessageTopic
type_name: testtopics::message::Message
qos: Qos(Policy.Deadline(deadline=9223372036854775807), Policy.DestinationOrder.ByReceptionTimestamp, Policy.Durability.Volatile, Policy.DurabilityService(cleanup_delay=0, history=Policy.History.KeepLast(depth=1), max_samples=-1, max_instances=-1, max_samples_per_instance=-1), Policy.History.KeepLast(depth=1), Policy.IgnoreLocal.Nothing, Policy.LatencyBudget(budget=0), Policy.Lifespan(lifespan=9223372036854775807), Policy.Liveliness.Automatic(lease_duration=9223372036854775807), Policy.Ownership.Shared, Policy.OwnershipStrength(strength=20), Policy.PresentationAccessScope.Instance(coherent_access=False, ordered_access=False), Policy.Reliability.Reliable(max_blocking_time=100000000), Policy.ResourceLimits(max_samples=-1, max_instances=-1, max_samples_per_instance=-1), Policy.TransportPriority(priority=0), Policy.Userdata(data=b'New'), Policy.WriterDataLifecycle(autodispose=True))
```

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

### Build and Install CycloneDDS Python from Source via PyPI

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/README.md

This process involves cloning the CycloneDDS repository, building it, setting the CYCLONEDDS_HOME environment variable, and then installing the Python package from PyPI without using pre-built binaries.

```bash
$ git clone https://github.com/eclipse-cyclonedds/cyclonedds
$ cd cyclonedds && mkdir build install && cd build
$ cmake .. -DCMAKE_INSTALL_PREFIX=../install
$ cmake --build . --config RelWithDebInfo --target install
$ cd ..
$ export CYCLONEDDS_HOME="$(pwd)/install"
$ pip3 install cyclonedds --no-binary cyclonedds
```

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

### Install CycloneDDS with Development Dependencies

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/README.md

Install the CycloneDDS package from a GitHub repository, including development dependencies using pip.

```bash
pip3 install --user "cyclonedds[dev] @ git+https://github.com/eclipse-cyclonedds/cyclonedds-python"
```

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

### Install CycloneDDS with Development Dependencies (Local Clone)

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/README.md

Install the CycloneDDS package from a local git clone, including development dependencies using pip.

```bash
cd /path/to/git/clone
# for development:
pip3 install --user ".[dev]"
# for documentation generation
pip3 install --user ".[docs]"
# or for both
pip3 install --user ".[dev,docs]"
```

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

### PresentationAccessScope Policy Examples

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.qos.rst

Demonstrates how to configure access scope policies for Instances, Topics, or Groups.

```pycon
>>> Policy.PresentationAccessScope.Instance(coherent_access=True, ordered_access=False)
>>> Policy.PresentationAccessScope.Topic(coherent_access=True, ordered_access=False)
>>> Policy.PresentationAccessScope.Group(coherent_access=True, ordered_access=False)
```

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

### Read and write data examples

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/tools.pubsub.rst

Demonstrates terminal input and the corresponding subscribed output for various supported data types.

```console
420
Subscribed: Integer(seq=0, keyval=420)
test
Subscribed: String(seq=1, keyval='test')
[1, 8, 3]
Subscribed: IntArray(seq=2, keyval=[1, 8, 3])
['h','e','l','l','o']
Subscribed: StrArray(seq=3, keyval=['h', 'e', 'l', 'l', 'o'])
[20]
Subscribed: IntSequence(seq=4, keyval=[20])
['test']
Subscribed: StrSequence(seq=5, keyval=['test'])
```

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

### Durability Policy Examples

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.qos.rst

Demonstrates the available Durability policy settings.

```pycon
>>> Policy.Durability.Volatile
>>> Policy.Durability.TransientLocal
>>> Policy.Durability.Transient
>>> Policy.Durability.Persistent
```

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

### History Policy Examples

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.qos.rst

Demonstrates how to configure History policies for KeepAll or KeepLast settings.

```pycon
>>> Policy.History.KeepAll
>>> Policy.History.KeepLast(depth=10)
```

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

### Display QoS change output

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/tools.ddsls.rst

Example output showing specific QoS policy changes for a data writer.

```console
Qos changed on topic 'MessageTopic' publication:
 key = 1d681001-c040-7b68-2e4d-5fb900000102
 Policy.OwnershipStrength(strength=10) -> Policy.OwnershipStrength(strength=20)
 Policy.Userdata(data=b'Old') -> Policy.Userdata(data=b'New')
```

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

### Start pubsub with a specific topic

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/tools.pubsub.rst

Use the --topic option to define the target topic for read/write operations.

```console
$ pubsub --topic HelloWorld
```

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

### Rebuild Documentation (after activating venv)

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/how-to-build.md

When rebuilding docs in a new shell, first activate the virtual environment, then run the sphinx-build command. Dependency installation is skipped.

```bash
source .venv/bin/activate
sphinx-build ./manual ./output
```

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

### Install Cyclone DDS Python via pip

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/intro.rst

Standard installation command for the Cyclone DDS Python package from PyPi.

```shell
pip install cyclonedds
```

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

### Install CycloneDDS Python Nightly Build

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/README.md

Install the nightly build for the latest features, which may be less stable and could include API breaks.

```bash
    $ pip install cyclonedds-nightly
```

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

### Example ddsls output

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/tools.ddsls.rst

Sample output showing the structure of discovered participants, publications, and subscriptions.

```text
-- New PARTICIPANT --
key: 9ce21001-ad00-8ac9-4428-52f1000001c1
qos: Qos()

key: 350c1001-c5e3-ca6b-712a-ee09000001c1
qos: Qos()


-- New PUBLICATION --
key: 9ce21001-ad00-8ac9-4428-52f100000102
participant_key: 9ce21001-ad00-8ac9-4428-52f1000001c1
participant_instance_handle: 11822753457071331301
topic_name: Vehicle
type_name: vehicles::Vehicle
qos: Qos(Policy.Deadline(deadline=10000), Policy.DestinationOrder.ByReceptionTimestamp, Policy.Durability.Transient, Policy.DurabilityService(cleanup_delay=0, history=Policy.History.KeepLast(depth=1), max_samples=-1, max_instances=-1, max_samples_per_instance=-1), Policy.History.KeepLast(depth=10), Policy.IgnoreLocal.Nothing, Policy.LatencyBudget(budget=0), Policy.Lifespan(lifespan=9223372036854775807), Policy.Liveliness.Automatic(lease_duration=9223372036854775807), Policy.Ownership.Shared, Policy.OwnershipStrength(strength=0), Policy.PresentationAccessScope.Instance(coherent_access=False, ordered_access=False), Policy.Reliability.BestEffort, Policy.ResourceLimits(max_samples=-1, max_instances=-1, max_samples_per_instance=-1), Policy.TransportPriority(priority=0), Policy.WriterDataLifecycle(autodispose=True))


-- New SUBSCRIPTION --
key: 350c1001-c5e3-ca6b-712a-ee0900000107
participant_key: 350c1001-c5e3-ca6b-712a-ee09000001c1
participant_instance_handle: 5513147631977453825
topic_name: Vehicle
type_name: vehicles::Vehicle
qos: Qos(Policy.Deadline(deadline=10000), Policy.DestinationOrder.ByReceptionTimestamp, Policy.Durability.Transient, Policy.History.KeepLast(depth=10), Policy.IgnoreLocal.Nothing, Policy.LatencyBudget(budget=0), Policy.Liveliness.Automatic(lease_duration=9223372036854775807), Policy.Ownership.Shared, Policy.PresentationAccessScope.Instance(coherent_access=False, ordered_access=False), Policy.ReaderDataLifecycle(autopurge_nowriter_samples_delay=9223372036854775807, autopurge_disposed_samples_delay=9223372036854775807), Policy.Reliability.BestEffort, Policy.ResourceLimits(max_samples=-1, max_instances=-1, max_samples_per_instance=-1), Policy.TimeBasedFilter(filter_time=0), Policy.TransportPriority(priority=0))
```

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

### Example JSON output format

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/tools.ddsls.rst

The structure of the generated JSON file containing participant discovery information.

```JSON
{
    "PARTICIPANT": {
        "New": {
            "da531001-77b3-aef6-0cb8-647f000001c1": {
                "key": "da531001-77b3-aef6-0cb8-647f000001c1"
            }
        },
        "Disposed": {
            "8e281001-e010-0c8d-305c-20a3000001c1": {
                "key": "8e281001-e010-0c8d-305c-20a3000001c1"
            }
        }
    }
}
```

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

### JSON output format

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/tools.ddsls.rst

Example of the JSON structure returned when using the --json flag.

```JSON
[
{
    "type": "PARTICIPANT",
    "event": "new",
    "value": [
        {
            "key": "5dc81001-75dc-1fe3-5468-48b3000001c1"
        },
        {
            "key": "764e1001-d9da-53dd-ca0b-ab06000001c1"
        }
    ]
}]
```

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

### Build Self-Contained CycloneDDS CLI Binary

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/README.md

Build a self-contained binary of the `cyclonedds` CLI tool using PyOxidizer. Ensure PyOxidizer is installed first.

```bash
cd /path/to/git/clone
pip3 install --user pyoxidizer
pyoxidizer build
```

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

### Serve Documentation Locally

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/how-to-build.md

Host the built documentation using Python's http.server to view it in a browser. Specify the directory containing the built files.

```bash
python -m http.server --directory output
```

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

### Create and Activate Virtual Environment

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/how-to-build.md

Use a virtual environment to isolate documentation building dependencies. Activate it using the 'source' command.

```bash
python -m venv .venv
source .venv/bin/activate
```

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

### Build and Serve Documentation Locally

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/README.md

Commands to build Sphinx documentation and serve it locally for preview. Navigate to the 'docs' directory and use Python's HTTP server.

```bash
cd docs
python -m sphinx source/ _build/
# Serve the HTML files to view at localhost:8000
python -m http.server -d _build
```

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

### Pubsub Help Output

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/tools.pubsub.rst

The full help message detailing arguments, options, and QoS configuration syntax.

```text
usage: pubsub [-h] [-T TOPIC] [-f FILENAME] [-eqos {all,topic,publisher,subscriber,datawriter,datareader}] [-q QOS [QOS ...]] [-r RUNTIME] [--qoshelp]

optional arguments:
-h, --help              show this help message and exit
-T TOPIC, --topic TOPIC
                        The name of the topic to publish/subscribe to
-f FILENAME, --filename FILENAME
                        Write results to file in JSON format
-eqos {all,topic,publisher,subscriber,datawriter,datareader}, --entityqos {all,topic,publisher,subscriber,datawriter,datareader}
                        Select the entites to set the qos.
                        Choose between all entities, topic, publisher, subscriber, datawriter and datareader. (default: all).
                        Inapplicable qos will be ignored.
-q QOS [QOS ...], --qos QOS [QOS ...]
                        Set QoS for entities, check '--qoshelp' for available QoS and usage
-r RUNTIME, --runtime RUNTIME
                        Limit the runtime of the tool, in seconds.
--qoshelp               e.g.:
                            --qos Durability.TransientLocal
                            --qos History.KeepLast 10
                            --qos ReaderDataLifecycle 10, 20
                            --qos Partition [a, b, 123]
                            --qos PresentationAccessScope.Instance False, True
                            --qos DurabilityService 1000, History.KeepLast 10, 100, 10, 10
                            --qos Durability.TransientLocal History.KeepLast 10

                        Available QoS and usage are:
                        --qos Reliability.BestEffort
                        --qos Reliability.Reliable [max_blocking_time<integer>]
                        --qos Durability.Volatile
                        --qos Durability.TransientLocal
                        --qos Durability.Transient
                        --qos Durability.Persistent
                        --qos History.KeepAll
                        --qos History.KeepLast [depth<integer>]
                        --qos ResourceLimits [max_samples<integer>], [max_instances<integer>], [max_samples_per_instance<integer>]
                        --qos PresentationAccessScope.Instance [coherent_access<boolean>], [ordered_access<boolean>]
                        --qos PresentationAccessScope.Topic [coherent_access<boolean>], [ordered_access<boolean>]
                        --qos PresentationAccessScope.Group [coherent_access<boolean>], [ordered_access<boolean>]
                        --qos Lifespan [lifespan<integer>]
                        --qos Deadline [deadline<integer>]
                        --qos LatencyBudget [budget<integer>]
                        --qos Ownership.Shared
                        --qos Ownership.Exclusive
                        --qos OwnershipStrength [strength<integer>]
                        --qos Liveliness.Automatic [lease_duration<integer>]
                        --qos Liveliness.ManualByParticipant [lease_duration<integer>]
                        --qos Liveliness.ManualByTopic [lease_duration<integer>]
                        --qos TimeBasedFilter [filter_time<integer>]
                        --qos Partition [partitions<Sequence[str]>]
                        --qos TransportPriority [priority<integer>]
                        --qos DestinationOrder.ByReceptionTimestamp
                        --qos DestinationOrder.BySourceTimestamp
                        --qos WriterDataLifecycle [autodispose<boolean>]
                        --qos ReaderDataLifecycle [autopurge_nowriter_samples_delay<integer>], [autopurge_disposed_samples_delay<integer>]
                        --qos DurabilityService [cleanup_delay<integer>], [History.KeepAll / History.KeepLast [depth<integer>]], [max_samples<integer>], [max_instances<integer>], [max_samples_per_instance<integer>]
                        --qos IgnoreLocal.Nothing
                        --qos IgnoreLocal.Participant
                        --qos IgnoreLocal.Process
                        --qos Userdata [data<bytes>]
                        --qos Groupdata [data<bytes>]
                        --qos Topicdata [data<bytes>]
```

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

### Build Documentation with Sphinx

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/how-to-build.md

Build the documentation using the sphinx-build command, specifying the source and output directories.

```bash
sphinx-build ./manual ./output
```

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

### get_matched_publication_data(handle)

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.sub.rst

Get a description of a writer matched with the provided reader.

```APIDOC
## get_matched_publication_data(handle)

### Parameters
- **handle** (Int) - Required - The instance handle of a writer.

### Returns
- **DcpsEndpoint** - The sample of the DcpsEndpoint built-in topic.
```

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

### get_matched_publications()

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.sub.rst

Get instance handles of the data writers matching a reader.

```APIDOC
## get_matched_publications()

### Returns
- **List[int]** - A list of instance handles of the matching data writers.

### Errors
- **DDSException** - Raised when the number of matching writers is less than 0.
```

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

### View Pubsub Help

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/tools.pubsub.rst

Command to display available options and usage information for the pubsub tool.

```console
$ pubsub --help
```

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

### Handle Inapplicable QoS

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/tools.pubsub.rst

Demonstrates an invalid QoS configuration and the resulting warning message.

```console
$ pubsub --topic hello --qos Topicdata test --entityqos datareader
```

```console
InapplicableQosWarning: The Policy.Topicdata(data=b'test') is not applicable for datareader, will be ignored.
```

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

### Basic Pubsub Execution

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/tools.pubsub.rst

General syntax for invoking the pubsub tool.

```console
$ pubsub [Options]
```

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

### ddsls help output

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/tools.ddsls.rst

The full help message detailing all available command-line arguments and flags.

```text
usage: ddsls [-h] [-i ID] [-f FILENAME] [-j] [-w] [-v] [-r RUNTIME] (-a | -t {dcpsparticipant,dcpssubscription,dcpspublication})

optional arguments:
-h, --help            show this help message and exit
-i ID, --id ID        Define the domain participant id
-f FILENAME, --filename FILENAME
                      Write results to file in JSON format
-j, --json            Print output in JSON format
-w, --watch           Watch for data reader & writer & qoses changes
-v, --verbose         View the sample when Qos changes
-r RUNTIME, --runtime RUNTIME
                      Limit the runtime of the tool, in seconds.
-a, --all             for all topics
-t {dcpsparticipant,dcpssubscription,dcpspublication}, --topic {dcpsparticipant,dcpssubscription,dcpspublication}
                      for one specific topic
```

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

### Handle Incompatible QoS

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/tools.pubsub.rst

Shows a scenario where requested and offered QoS are incompatible, resulting in a warning.

```console
$ pubsub --topic hello --qos Durability.TransientLocal --entityqos datareader
```

```console
IncompatibleQosWarning: The Qos requested for subscription is incompatible with the Qos offered by publication.PubSub may not be available.
```

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

### Run ddsls with all topics

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/tools.ddsls.rst

Executes the ddsls tool to list all available DDS entities in the default domain.

```console
$ ddsls --all
```

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

### Executable Creation and Linking

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/tests/support_modules/fuzz_tools/rand_idl/c_app/CMakeLists.txt

Builds an executable from C source files and links it against the generated IDL library and the CycloneDDS DDS library. Ensure xtypes_sub.c and xtypes_dynamic_index.c are present.

```cmake
add_executable(xtypes_sub xtypes_sub.c xtypes_dynamic_index.c)
target_link_libraries(xtypes_sub xtypes_sub_lib CycloneDDS::ddsc)
```

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

### Initialize Property Policy

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.qos.rst

Creates a Property policy instance with string key-value pairs and propagation flag.

```pycon
>>> Policy.Property(key="host", value="central", propagate=True)
```

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

### Display ddsls help

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/tools.ddsls.rst

Command to view available options and usage information for ddsls.

```console
$ ddsls --help
```

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

### Initialize BinaryProperty Policy

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.qos.rst

Creates a BinaryProperty policy instance with string key, byte-encoded value, and propagation flag.

```pycon
>>> Policy.BinaryProperty(key="host", value=b"central", propagate=True)
```

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

### Configure Partition QoS Policy

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.qos.rst

Defines a list of partitions for the entity.

```pycon
>>> Policy.Partition(partitions=["partition_a", "partition_b", "partition_c"])
>>> Policy.Partition(partitions=[f"partition_{i}" for i in range(100)])
```

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

### Run ddsls tool

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/tools.ddsls.rst

Basic command to execute the ddsls tool.

```console
$ ddsls [Options]
```

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

### take_aiter(condition=None, timeout=None)

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.sub.rst

Shortcut method to async iterate taking samples.

```APIDOC
## take_aiter(condition=None, timeout=None)

### Description
Asynchronously iterates over taking samples. Iteration stops once the provided timeout expires, with the timeout resetting upon each received sample.

### Parameters
- **condition** (optional) - Condition to filter samples.
- **timeout** (int) - Optional - Timeout duration.

### Returns
- **AsyncGenerator[_T, None]** - An async generator yielding samples.

### Errors
- **DDSException** - Raised if the underlying DDS API returns an error.
```

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

### Configure Deadline QoS Policy

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.qos.rst

Defines the deadline for a sample in nanoseconds.

```pycon
>>> Policy.Deadline(deadline=duration(seconds=2))
```

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

### Topic(domain_participant, topic_name, data_type, qos=None, listener=None)

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.topic.rst

Constructor for creating a new Topic instance.

```APIDOC
## Topic Constructor

### Description
Initializes a new Topic instance within a given domain participant.

### Parameters
- **domain_participant** (DomainParticipant) - Required - The participant to associate with the topic.
- **topic_name** (AnyStr) - Required - The name of the topic.
- **data_type** (Type) - Required - The data type associated with the topic.
- **qos** (Qos) - Optional - Quality of Service settings.
- **listener** (Listener) - Optional - Listener for topic events.
```

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

### Run Local CI Script

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/README.md

Execute the `local-ci.py` script to run the test suite and linting for the project.

```bash
python local-ci.py
```

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

### Initialize Userdata Policy

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.qos.rst

Creates a Userdata policy instance with byte-encoded data.

```pycon
>>> Policy.Userdata(data=b"Hello, World!")
```

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

### Publish a Message to DDS

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/intro.rst

Initialize a DomainParticipant, define a Topic, and use a DataWriter to send the message.

```python
from cyclonedds.domain import DomainParticipant
from cyclonedds.topic import Topic
from cyclonedds.pub import DataWriter

participant = DomainParticipant()
topic = Topic(participant, "Announcements", Message)
writer = DataWriter(participant, topic)

writer.write(message)
```

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

### Initialize Topicdata Policy

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.qos.rst

Creates a Topicdata policy instance with byte-encoded data.

```pycon
>>> Policy.Topicdata(data=b"Hello, World!")
```

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

### Configure TimeBasedFilter QoS Policy

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.qos.rst

Sets the minimum time between samples in nanoseconds.

```pycon
>>> Policy.TimeBasedFilter(filter_fn=duration(seconds=2))
```

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

### on_offered_incompatible_qos / set_on_offered_incompatible_qos

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.core.rst

Handles the event when an offered QoS is incompatible and sets the callback.

```APIDOC
## on_offered_incompatible_qos(writer, status)

### Description
Callback triggered when an offered QoS is found to be incompatible.

### Parameters
- **writer** (cyclonedds.pub.DataWriter) - The DataWriter instance.
- **status** (offered_incompatible_qos_status) - The status information.

## set_on_offered_incompatible_qos(callable)

### Description
Sets the callback function for offered incompatible QoS events.

### Parameters
- **callable** (Callable[[cyclonedds.pub.DataWriter, offered_incompatible_qos_status], None]) - The callback function.
```

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

### Configure Ownership QoS Policy

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.qos.rst

Specifies whether ownership is shared or exclusive.

```pycon
>>> Policy.Ownership.Shared
>>> Policy.Ownership.Exclusive
```

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

### read_aiter(condition=None, timeout=None)

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.sub.rst

Shortcut method to async iterate reading samples.

```APIDOC
## read_aiter(condition=None, timeout=None)

### Description
Asynchronously iterates over reading samples. Iteration stops once the provided timeout expires, with the timeout resetting upon each received sample.

### Parameters
- **condition** (optional) - Condition to filter samples.
- **timeout** (int) - Optional - Timeout duration.

### Returns
- **AsyncGenerator[_T, None]** - An async generator yielding samples.

### Errors
- **DDSException** - Raised if the underlying DDS API returns an error.
```

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

### Entity Core Methods

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.core.rst

Methods for managing entity state, status, QoS, and listeners.

```APIDOC
## instance_handle

### Description
Retrieve the integer instance handle associated with this entity for use in writer or reader operations.

### Returns
- **int** - The instance handle.

### Raises
- **DDSException**

## get_guid()

### Description
Retrieve the globally unique identifier (GUID) for this entity.

### Returns
- **uuid.UUID** - The entity's unique identifier.

### Raises
- **DDSException**

## read_status(mask=None)

### Description
Read the status bits currently set on the entity.

### Parameters
- **mask** (int) - Optional. The DDSStatus mask to read. If not provided, uses the mask set via set_status_mask.

### Returns
- **int** - The set status bits.

## take_status(mask=None)

### Description
Read and clear the status bits set on the entity.

### Parameters
- **mask** (int) - Optional. The DDSStatus mask to take.

### Returns
- **int** - The status bits that were set before clearing.

## get_status_changes()

### Description
Retrieve all status changes that occurred since the last read or take operation.

### Returns
- **int** - The status bits that were set.

## get_status_mask()

### Description
Get the currently enabled status mask for the entity.

### Returns
- **int** - The enabled status bits.

## set_status_mask(mask)

### Description
Set the status mask to track specific status changes on this entity.

### Parameters
- **mask** (int) - The status bits to track.

## get_qos()

### Description
Retrieve the current Quality of Service (QoS) policies associated with the entity.

### Returns
- **Qos** - The QoS object.

## set_qos(qos)

### Description
Apply new QoS policies to the entity. Note that only specific policies can be updated after creation.

### Parameters
- **qos** (Qos) - The QoS policies to apply.

## get_listener()

### Description
Retrieve the current listener object associated with the entity.

### Returns
- **Listener** - The listener instance.

## set_listener(listener)

### Description
Update or remove the listener for this entity.

### Parameters
- **listener** (Listener | None) - The listener object to assign, or None to remove the existing listener.
```

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

### Configure DestinationOrder QoS Policy

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.qos.rst

Sets the destination order policy based on reception or source timestamp.

```pycon
>>> Policy.DestinationOrder.ByReceptionTimestamp
>>> Policy.DestinationOrder.BySourceTimestamp
```

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

### Enable watch mode for monitoring

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/tools.ddsls.rst

Command to monitor dcpsparticipant entities continuously.

```console
$ ddsls --topic dcpsparticipant --watch
```

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

### Configure Liveliness QoS Policy

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.qos.rst

Sets the liveliness policy with a specified lease duration.

```pycon
>>> Policy.Liveliness.Automatic(lease_duration=duration(seconds=10))
>>> Policy.Liveliness.ManualByParticipant(lease_duration=duration(seconds=10))
>>> Policy.Liveliness.ManualByTopic(lease_duration=duration(seconds=10))
```

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

### Configure Latency Budget QoS Policy

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.qos.rst

Sets the latency budget in nanoseconds.

```pycon
>>> Policy.LatencyBudget(duration(seconds=2))
```

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

### take_one(condition=None, timeout=None)

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.sub.rst

Shortcut method to block and take exactly one sample or raise a timeout.

```APIDOC
## take_one(condition=None, timeout=None)

### Description
Blocks and takes exactly one sample from the reader or raises a timeout if no sample is available.

### Parameters
- **condition** (optional) - Condition to filter samples.
- **timeout** (int) - Optional - Time to wait for a sample.

### Returns
- **_T** - The retrieved sample.
```

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

### cyclonedds.core.InstanceState

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.core.rst

Static constants for building condition masks based on the state of an instance.

```APIDOC
## class cyclonedds.core.InstanceState

### Constants
- **Alive**: Only samples from alive instances.
- **NotAliveDisposed**: Only samples from instances disposed by a writer.
- **NotAliveNoWriters**: Only samples from instances with no active writers.
- **Any**: Ignore liveliness status.
```

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

### Built-in Topic Instances

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.builtin.rst

Predefined instances of BuiltinTopic for monitoring network participants, topics, publications, and subscriptions.

```APIDOC
## Built-in Topic Instances

- **BuiltinTopicDcpsParticipant**: Published to when a new participant appears on the network.
- **BuiltinTopicDcpsTopic**: Published to when a new topic appears on the network. Requires -DENABLE_TOPIC_DISCOVERY=ON and specific configuration settings.
- **BuiltinTopicDcpsPublication**: Published to when a publication occurs.
- **BuiltinTopicDcpsSubscription**: Published to when a subscription occurs.
```

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

### Initialize Groupdata Policy

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.qos.rst

Creates a Groupdata policy instance with byte-encoded data.

```pycon
>>> Policy.Groupdata(data=b"Hello, World!")
```

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

### Dynamically Publish to a DDS Topic

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/README.md

Use `cyclonedds publish` to create an interactive REPL for building datatypes and a writer for a topic, displaying data as it arrives. Type discovery is similar to `typeof`.

```bash
cyclonedds publish
```

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

### on_requested_incompatible_qos / set_on_requested_incompatible_qos

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.core.rst

Handles the event when a requested QoS is incompatible and sets the callback.

```APIDOC
## on_requested_incompatible_qos(reader, status)

### Description
Callback triggered when a requested QoS is found to be incompatible.

### Parameters
- **reader** (cyclonedds.sub.DataReader) - The DataReader instance.
- **status** (requested_incompatible_qos_status) - The status information.

## set_on_requested_incompatible_qos(callable)

### Description
Sets the callback function for requested incompatible QoS events.

### Parameters
- **callable** (Callable[[cyclonedds.sub.DataReader, requested_incompatible_qos_status], None]) - The callback function.
```

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

### Configure Ownership Strength QoS Policy

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.qos.rst

Sets the ownership strength as an integer.

```pycon
>>> Policy.OwnershipStrength(strength=2)
```

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

### on_sample_rejected / set_on_sample_rejected

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.core.rst

Handles the event when a sample is rejected and sets the callback.

```APIDOC
## on_sample_rejected(reader, status)

### Description
Callback triggered when a sample is rejected.

### Parameters
- **reader** (cyclonedds.sub.DataReader) - The DataReader instance.
- **status** (sample_rejected_status) - The status information.

## set_on_sample_rejected(callable)

### Description
Sets the callback function for sample rejected events.

### Parameters
- **callable** (Callable[[cyclonedds.sub.DataReader, sample_rejected_status], None]) - The callback function.
```

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

### cyclonedds.core.SampleState

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.core.rst

Static constants for building condition masks based on the read state of a sample.

```APIDOC
## class cyclonedds.core.SampleState

### Constants
- **Read**: Only samples that have been read.
- **NotRead**: Only unread samples.
- **Any**: Ignore read/unread state.
```

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

### cyclonedds.util.timestamp.now()

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.util.rst

Returns the current system time in nanoseconds since the Unix Epoch.

```APIDOC
## cyclonedds.util.timestamp.now()

### Description
Returns the current time in nanoseconds since the Unix Epoch (dds_time_t).

### Returns
- **int** - Number of nanoseconds since the Unix Epoch.
```

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

### Configure ddsls runtime duration

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/tools.ddsls.rst

Use the --runtime option to specify the duration in seconds for the tool to run before automatically shutting down.

```console
$ ddsls --all --runtime 10
```

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

### Generate Typesupport with idlc

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/cyclonedds/idl/_typesupport/howto.md

Use the `idlc` compiler to generate Python typesupport files. Specify the output language as Python (`-l py`) and the root prefix for generated modules (`-p py-root-prefix`).

```bash
idlc -l py -p py-root-prefix=cyclonedds.idl._typesupport ddsi_xt_type_object.idl
```

```bash
idlc -l py -p py-root-prefix=cyclonedds.idl._typesupport ddsi_xt_typemap.idl
```

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

### Configure DurabilityService QoS Policy

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.qos.rst

Configures the durability service parameters including history and sample limits.

```pycon
>>> Policy.DurabilityService(
>>>     cleanup_delay=duration(minutes=2.5),
>>>     history=Policy.History.KeepLast(20),
>>>     max_samples=2000,
>>>     max_instances=200,
>>>     max_samples_per_instance=25
>>> )
```

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

### Configure ReaderDataLifecycle QoS Policy

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.qos.rst

Sets the delay for purging samples in the reader.

```pycon
>>> Policy.ReaderDataLifecycle(
>>>     autopurge_nowriter_samples_delay=duration(minutes=2),
>>>     autopurge_disposed_samples_delay=duration(minutes=5)
>>> )
```

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

### Enable verbose mode

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/tools.ddsls.rst

Command to run ddsls with verbose mode enabled to view full entity information.

```console
$ ddsls --all --watch --verbose
```

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

### List DDS System Applications

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/README.md

Use `cyclonedds ps` to view active DDS applications. This command relies on Participant Properties (QoS) merged into CycloneDDS from version 0.10.0.

```bash
cyclonedds ps
```

```bash
cyclonedds ps --suppress-progress-bar --force-color-mode
```

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

### cyclonedds.core.ViewState

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.core.rst

Static constants for building condition masks based on the view state of an instance.

```APIDOC
## class cyclonedds.core.ViewState

### Constants
- **New**: Only newly created instances.
- **Old**: Only previously created instances.
- **Any**: Ignore instance creation status.
```

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

### cyclonedds.idl.annotations.keylist

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.idl.rst

Defines a list of keys for the structure.

```APIDOC
## cyclonedds.idl.annotations.keylist(list_of_keys)

### Description
Specifies a list of member names that act as keys.

### Parameters
- **list_of_keys** (List[str]) - Required - A list of member names.
```

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

### get_offered_incompatible_qos_status()

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.pub.rst

Retrieves the current OFFERED_INCOMPATIBLE_QOS status for the publication.

```APIDOC
## get_offered_incompatible_qos_status()

### Description
Get OFFERED INCOMPATIBLE QOS status.

### Returns
- **offered_incompatible_qos_status** - The class 'offered_incompatible_qos_status' value.

### Errors
- **DDSException** - Raised if the status cannot be retrieved.
```

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

### Initialize and Refresh Statistics

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.core.rst

Create a statistics object for a datawriter and update it with current values.

```pycon
>>> Statistics(datawriter)
>>> Statistics(datawriter).refresh()
```

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

### Configure WriterDataLifecycle QoS Policy

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.qos.rst

Sets the autodispose behavior for the writer.

```pycon
>>> Policy.WriterDataLifecycle(autodispose=False)
```

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

### on_sample_lost / set_on_sample_lost

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.core.rst

Handles the event when a sample is lost and sets the callback.

```APIDOC
## on_sample_lost(writer, status)

### Description
Callback triggered when a sample is lost.

### Parameters
- **writer** (cyclonedds.pub.DataWriter) - The DataWriter instance.
- **status** (sample_lost_status) - The status information.

## set_on_sample_lost(callable)

### Description
Sets the callback function for sample lost events.

### Parameters
- **callable** (Callable[[cyclonedds.pub.DataWriter, sample_lost_status], None]) - The callback function.
```

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

### Write Subscribed Data to File

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/tools.pubsub.rst

Configures the tool to save subscribed data to a JSON file and shows the expected file structure.

```default
$ pubsub --topic hello --filename pubsub_data.json
```

```JSON
{
    "sequence 0": {
        "type": "integer",
        "keyval": 420
    },
    "sequence 1": {
        "type": "integer",
        "keyval": 33
    },
    "sequence 2": {
        "type": "string",
        "keyval": "hello"
    },
    "sequence 3": {
        "type": "int_array",
        "keyval": [
            2,
            3,
            3
        ]
    }
}
```

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

### QoS Policy Classes

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.qos.rst

The CycloneDDS Python SDK provides various classes under the Policy namespace to configure QoS settings. These classes are instantiated to define specific behaviors for data readers and writers.

```APIDOC
## Policy.Lifespan(lifespan)

### Description
Defines the expiration time relative to the source timestamp of a sample in nanoseconds.

### Parameters
- **lifespan** (int) - Required - Expiration time in nanoseconds.

## Policy.Deadline(deadline)

### Description
Defines the deadline of a sample in nanoseconds.

### Parameters
- **deadline** (int) - Required - Deadline in nanoseconds.

## Policy.LatencyBudget(budget)

### Description
Defines the latency budget in nanoseconds.

### Parameters
- **budget** (int) - Required - Latency budget in nanoseconds.

## Policy.OwnershipStrength(strength)

### Description
Defines the ownership strength for the Ownership QoS policy.

### Parameters
- **strength** (int) - Required - Ownership strength as an integer.

## Policy.TimeBasedFilter(filter_time)

### Description
Defines the minimum time between samples in nanoseconds.

### Parameters
- **filter_time** (int) - Required - Minimum time between samples in nanoseconds.

## Policy.Partition(partitions)

### Description
Defines the partitions for the Partition QoS policy.

### Parameters
- **partitions** (Sequence[str]) - Required - A sequence of partition names.

## Policy.WriterDataLifecycle(autodispose)

### Description
Defines the WriterDataLifecycle QoS policy.

### Parameters
- **autodispose** (bool) - Required - Whether to automatically dispose data.

## Policy.ReaderDataLifecycle(autopurge_nowriter_samples_delay, autopurge_disposed_samples_delay)

### Description
Defines the ReaderDataLifecycle QoS policy.

### Parameters
- **autopurge_nowriter_samples_delay** (int) - Required - Delay for purging samples without writers.
- **autopurge_disposed_samples_delay** (int) - Required - Delay for purging disposed samples.
```

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

### BuiltinDataReader.take

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.builtin.rst

Takes a maximum of N samples from the builtin topic in a non-blocking manner, removing them from the reader's cache.

```APIDOC
## take(N=1, condition=None)

### Description
Takes up to N samples from the builtin topic. Optionally filters samples using a read or query condition.

### Parameters
- **N** (int) - Optional - Maximum number of samples to take (default: 1).
- **condition** (ReadCondition | QueryCondition) - Optional - Condition to filter samples.

### Exceptions
- **DDSException** - Raised if the underlying DDS API returns an error.
```

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

### Statistics(datawriter)

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.core.rst

Initializes a new Statistics object for a given datawriter.

```APIDOC
## Statistics(datawriter)

### Description
Initializes a statistics structure for the specified datawriter.

### Parameters
- **datawriter** (object) - Required - The datawriter instance to track.
```

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

### Run ddsls in JSON mode

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/tools.ddsls.rst

Command to execute ddsls and output results in JSON format.

```console
$ ddsls --topic participant --json
```

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

### Configure TransportPriority QoS Policy

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.qos.rst

Sets the transport priority level.

```pycon
>>> Policy.TransportPriority(priority=10)
```

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

### Apply IDL Annotations

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/idl.rst

Use decorators or field-level annotations to apply IDL metadata like keys to structures.

```python
from dataclasses import dataclass
from cyclonedds.idl import IdlStruct
from cyclonedds.idl.annotations import key, keylist

@dataclass
class Type1(IdlStruct):
   id: int
   key("id")
   value: str

@dataclass
@keylist(["id"])
class Type2(IdlStruct):
   id: int
   value: str
```

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

### Set Entity QoS

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/tools.pubsub.rst

Configures the Durability QoS to TransientLocal specifically for the data writer entity.

```console
$ pubsub --topic hello --qos Durability.TransientLocal --entityqos datawriter
```

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

### QoS Policy Classes

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.qos.rst

Classes for defining Quality of Service policies in CycloneDDS.

```APIDOC
## Policy.Userdata(data)

### Description
The Userdata Qos Policy.

### Parameters
- **data** (bytes) - Required - The user data payload.

## Policy.Topicdata(data)

### Description
The Topicdata Qos Policy.

### Parameters
- **data** (bytes) - Required - The topic data payload.

## Policy.Groupdata(data)

### Description
The Groupdata Qos Policy.

### Parameters
- **data** (bytes) - Required - The group data payload.

## Policy.Property(key, value, propagate=False)

### Description
The Property Qos Policy.

### Parameters
- **key** (str) - Required - The property key.
- **value** (str) - Required - The property value.
- **propagate** (bool) - Optional - Whether to propagate the property.

## Policy.BinaryProperty(key, value, propagate=False)

### Description
The BinaryProperty Qos Policy.

### Parameters
- **key** (str) - Required - The property key.
- **value** (bytes) - Required - The binary property value.
- **propagate** (bool) - Optional - Whether to propagate the property.

## Policy.TypeConsistency

### Description
The TypeConsistency Qos Policy. Available constants: DisallowTypeCoercion, AllowTypeCoercion.

## Policy.DataRepresentation(use_cdrv0_representation=False, use_xcdrv2_representation=False)

### Description
The DataRepresentation Qos Policy.

### Parameters
- **use_cdrv0_representation** (bool) - Optional - Use CDRv0 representation.
- **use_xcdrv2_representation** (bool) - Optional - Use xCDRv2 representation.

## Policy.EntityName(name)

### Description
The EntityName Qos Policy.

### Parameters
- **name** (str) - Required - The name of the entity.
```

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

### Generate Python code with a package root prefix

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/idl.rst

Specify a package root prefix to nest generated modules within an existing Python package structure.

```shell
idlc -l py -p py-root-prefix=wubble.fruzzy your_file.idl
```

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

### Configure Lifespan QoS Policy

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.qos.rst

Sets the expiration time for samples relative to the source timestamp.

```pycon
>>> Policy.Lifespan(duration(seconds=2))
```

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

### cyclonedds.idl.annotations.must_understand

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/cyclonedds.idl.rst

Marks an element as 'must understand'.

```APIDOC
## cyclonedds.idl.annotations.must_understand(str)

### Description
Sets the must_understand flag for the element.

### Parameters
- **str** (Any) - Required - The element to annotate.
```

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

### Generate Python code from an IDL file

Source: https://github.com/eclipse-cyclonedds/cyclonedds-python/blob/master/docs/manual/idl.rst

Use the idlc command with the -l py flag to generate Python code from a specified IDL file.

```shell
idlc -l py your_file.idl
```