Skip to content

code_generator.rst

Latest commit

 

History

History
111 lines (78 loc) · 3.71 KB

code_generator.rst

File metadata and controls

111 lines (78 loc) · 3.71 KB

Interface code generator

Python-sdbus is able to generate the interfaces code from the D-Bus introspection XML. (either from a file or live object on D-Bus) Currently async interfaces code is generated by default. Blocking interfaces can be generated by passing --block option.

Running code generator requires Jinja to be installed.

Warning

Do NOT send the generator result to exec() function. Interface code MUST be inspected before running.

The generated interfaces code will be syntactically correct but NOT stylistically. It is recommended running a code formatter on the generated code. (for example black)

Generating from XML files

To run generator on files (such as found under /usr/share/dbus-1/interfaces/ folder) execute the sdbus module with gen-from-file first argument and file paths to introspection XML files:

python -m sdbus gen-from-file /usr/share/dbus-1/interfaces/org.gnome.Shell.Screenshot.xml

The generated interface code will be printed in to stdout. You can use shell redirection > to save it in to file.

Multiple interface files can be passed which generates a file containing multiple interfaces.

Generating from run-time introspection

To run generator on some service on the D-Bus execute the sdbus module with gen-from-connection first argument, the service connection name as second and one or more object paths:

python -m sdbus gen-from-connection org.freedesktop.systemd1 /org/freedesktop/systemd1

The generated interface code will be printed in to stdout. You can use shell redirection > to save it in to file.

Multiple object paths can be passed which generates a file containing all interfaces encountered in the objects.

Pass --system option to use system bus instead of session bus.

Renaming interfaces and members

New in version 0.13.0.

Some interface and member names might conflict with Python keywords when converted from D-Bus introspection to Python code by gerator. The CLI interface allow to override the particular interface and member names using the --select-* and --set-name options. The selector options move the cursor to a particular interface and member

Available override options:

  • --set-name
    Sets the name of currently selected element as it would be in generated Python code. Can be used if either interface or member is selected.
  • --select-interface
    Selects the interface using its D-Bus name.
  • --select-method
    Selects the method using its D-Bus name. An interface must be selected first.
  • --select-property
    Selects the property using its D-Bus name. An interface must be selected first.
  • --select-signal
    Selects the signal using its D-Bus name. An interface must be selected first.

For example, an org.example.Interface interface has a property called Class. When automatically converted the name will become class which is a reserved Python keyword.

Using these CLI options it is possible to override the name of the property and class:

python -m sdbus gen-from-file \
    org.example.interface.xml \
        --select-interface org.example.Interface \
            --set-name Example \
            --select-property Class \
                --set-name example_class

This will generate following Python code:

class Example:
    @dbus_property_async(
        property_signature="s",
    )
    def example_class(self) -> str:
        raise NotImplementedError