nyirog

Reflect go to dbus

2021-02-05T19:42:00+01:00

The prop.go godbus example demonstrates how easy to register a dbus property from go and access the changed value at update. But what if we require all our config data at once when one of its property is changed?

We will look through how to register a native go struct to dbus as a map of dbus properties and access the whole struct when any of its field is updated.

We will need two transformations to achieve our goal:

Convert struct to a map[string]interface{}.
Set struct field by its name from the dbus change.

Struct to map

The godbus prop.Prop accepts any go value which has dbus equivalent type so we only have to convert our struct to a map where the keys will be set from the field names.

This is quite straightforward with reflecttion:

func CreateStructMap(config interface{}) map[string]interface{} {
    var struct_map = make(map[string]interface{})

    config_value := reflect.ValueOf(config).Elem()
    config_type := config_value.Type()

    for i := 0; i < config_type.NumField(); i++ {
        field_type := config_type.Field(i)
        if strings.Title(field_type.Name) != field_type.Name {
            continue
        }

        struct_map[field_type.Name] = config_value.Field(i).Interface()
    }

    return struct_map
}

The only trick what we did is to skip the fields which are not capitalized (private fields). The struct fields could have been exported to dbus by StructTag but our export-all-public-field strategy will be good enough for now.

Set struct field by its name

The update of the struct from the prop.Change is more straightforward:

func SetStructField(config interface{}, change *prop.Change) {
    config_value := reflect.ValueOf(config).Elem()
    config_value.FieldByName(change.Name).Set(reflect.ValueOf(change.Value))
}

Only two comments is required for the function above:

We have to call the Elem() method on the reflect.Value because our struct will be passed as reference.
The change.Value has to be wrapped into a reflect.Value so the general Set() method can be used.

Updatable interface

Our helper functions are quite easy to use but it is more general if we define an interface above them:

type Updatable interface {
    Update(*prop.Change) *dbus.Error

    CreatePropertyMap() map[string]interface{}
}

Let see how we can implement Updatable interface with a common struct:

type Config struct {
    SomeInt    int32
    SomeString string
}

func (config *Config) Update(change *prop.Change) *dbus.Error {
    SetStructField(config, change)

    return nil
}

func (config *Config) CreatePropertyMap() map[string]interface{} {
    return CreateStructMap(config)
}

Register to dbus

Only two helper functions are missing to finish our task. The first function creates a map[string]*prop.Prop from our map[string]interface:

func createProps(config Updatable) map[string]*prop.Prop {
    var props = make(map[string]*prop.Prop)

    for name, value := range config.CreatePropertyMap() {
        props[name] = &prop.Prop{
            value,
            true,
            prop.EmitTrue,
            config.Update,
        }
    }

    return props
}

And the second function exports our map[string]*prop.Prop to dbus:

func CreateNode(conn *dbus.Conn, path dbus.ObjectPath, iface string, config Updatable) {
    propsSpec := map[string]map[string]*prop.Prop{
        iface: createProps(config),
    }
    props := prop.New(conn, path, propsSpec)
    node := &introspect.Node{
        Name: string(path),
        Interfaces: []introspect.Interface{
            introspect.IntrospectData,
            prop.IntrospectData,
            {
                Name:       iface,
                Properties: props.Introspection(iface),
            },
        },
    }
    conn.Export(introspect.NewIntrospectable(node), path,
        "org.freedesktop.DBus.Introspectable")
}

This last function is a simple copy from the prop.go example of godbus (except createProps).

Final form

We can put the pieces together to have a simple dbus application:

package main

import (
    "fmt"
    "os"

    "github.com/nyirog/configd"

    "github.com/godbus/dbus/v5"
    "github.com/godbus/dbus/v5/prop"
)

type Config struct {
    SomeInt    int32
    SomeString string
}

func (config *Config) Update(change *prop.Change) *dbus.Error {
    configd.SetStructField(config, change)

    return nil
}

func (config *Config) CreatePropertyMap() map[string]interface{} {
    return configd.CreateStructMap(config)
}


func main() {
    config := Config{SomeInt: 42, SomeString: "egg"}

    conn, err := dbus.SessionBus()
    if err != nil {
        panic(err)
    }
    reply, err := conn.RequestName("org.configd",
        dbus.NameFlagDoNotQueue)
    if err != nil {
        panic(err)
    }
    if reply != dbus.RequestNameReplyPrimaryOwner {
        fmt.Fprintln(os.Stderr, "name already taken")
        os.Exit(1)
    }

    configd.CreateNode(conn, "/config", "org.configd.Config", &config)

    fmt.Println("Listening on org.configd /config ...")

    select {}
}

Note: Our helper function are imported from the configd package.

Validate our input

Since we have a standard go struct in our hands we can use the validator package to validate our user input:

package main

import (
    ...

    "gopkg.in/go-playground/validator.v9"
)

type Config struct {
    SomeInt    int32  `validate:"max=50"`
    SomeString string `validate:"len=3"`
}

func (config *Config) Update(change *prop.Change) *dbus.Error {
    configd.SetStructField(config, change)

    err := validate.Struct(config)
    if err != nil {
        return validationError(err.(validator.ValidationErrors))
    }

    fmt.Println("Update", change.Name, change.Value)
    return nil
}

func (config *Config) CreatePropertyMap() map[string]interface{} {
    return configd.CreateStructMap(config)
}

func validationError(err validator.ValidationErrors) *dbus.Error {
    body := make([]interface{}, len(err))
    for i, e := range err {
        body[i] = fmt.Sprintf(
            "%s[%s=%s] <> %v", e.Field(), e.Tag(), e.Param(), e.Value(),
        )
    }
    return dbus.NewError("org.freedesktop.DBus.Properties.Error.ValidationErrors", body)
}

var validate *validator.Validate

func main() {
    validate = validator.New()

    ...
}

You can find more example under the _example directory of the configd package.

Register dbus service

2021-01-10T19:12:00+01:00

The promise of dbus is to eliminate the need of an init system by starting the services on demand. In this guide we will walk through how to register a simple service on the system bus and manage it via systemd.

Remarks:

The guide assumes that git and go programs are already installed on your machine.
The well-known name of the dbus client will be referred as bus name.

Start a dbus service

We will use an example code from godbus as a dbus service.

$ git clone https://github.com/godbus/dbus

We will use the latest release (v5.0.3) to avoid inconsistency:

$ cd dbus
$ git checkout v5.0.3

go programs can be executed with the go run command:

$ go run _examples/server.go 
Listening on com.github.guelfey.Demo / /com/github/guelfey/Demo ...

Let see what /com/github/guelfey/Demo object can do:

$ dbus-send --session --dest=com.github.guelfey.Demo \
  --type=method_call --print-reply \
  /com/github/guelfey/Demo org.freedesktop.DBus.Introspectable.Introspect

   string "
<node>
    <interface name="com.github.guelfey.Demo">
        <method name="Foo">
            <arg direction="out" type="s"/>
        </method>
    </interface>
    <interface name="org.freedesktop.DBus.Introspectable">
        <method name="Introspect">
            <arg name="out" direction="out" type="s"/>
        </method>
    </interface>
</node> "

We have a Foo method in the com.github.guelfey.Demo interface. Let see what Foo method does:

$ dbus-send --session --dest=com.github.guelfey.Demo \
  --type=method_call --print-reply \
  /com/github/guelfey/Demo com.github.guelfey.Demo.Foo

   string "Bar!"

Nice, but we used session bus all along. How about the system bus?

System bus

Change our example program to connect to the system bus:

diff --git a/_examples/server.go b/_examples/server.go
index 0f4ee32..76d5151 100644
--- a/_examples/server.go
+++ b/_examples/server.go
@@ -24,7 +24,7 @@ func (f foo) Foo() (string, *dbus.Error) {
 }

 func main() {
-       conn, err := dbus.SessionBus()
+       conn, err := dbus.SystemBus()
        if err != nil {
                panic(err)
        }

Start our service again:

$ go run _examples/server.go
panic: Connection ":1.102" is not allowed to own the service "com.github.guelfey.Demo" due to security policies in the configuration file

goroutine 1 [running]:
main.main()
    /home/nyirogergo/workspace/dbus/_examples/server.go:40 +0x238
exit status 2

System bus policy

Arbitrary dbus client cannot acquire names on system bus. We have to create a policy file to register the name of our server. Lucky for us the Integrating system services section of the dbus-daemon documentation defines a minimal policy file:

<!-- /usr/share/dbus-1/system.d/com.github.guelfey.Demo.conf -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE busconfig PUBLIC
 "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
 "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
<busconfig>
  <policy user="${USER}">
    <allow own="com.github.guelfey.Demo"/>
  </policy>

  <policy context="default">
    <allow send_destination="com.github.guelfey.Demo"/>
  </policy>
</busconfig>

The policy should be saved as /usr/share/dbus-1/system.d/com.github.guelfey.Demo.conf so the com.github.guelfey.Demo name will be available for ${USER}. The ${USER} has to be replaced with a local username which can be yours too. More details about the bus policy can be read in the dbus-daemon and polkit documentations.

Remark: The /usr/share/dbus-1/system.d directory does not refer to systemd, this directory only contains the policies of the system bus configuration (/usr/share/dbus-1/system.conf).

We can start our example server again:

$ go run _examples/server.go
Listening on com.github.guelfey.Demo / /com/github/guelfey/Demo ...

The Foo method is available on the system bus:

$ dbus-send --system --dest=com.github.guelfey.Demo \
  --type=method_call --print-reply \
  /com/github/guelfey/Demo com.github.guelfey.Demo.Foo

   string "Bar!"

Dbus service

Until now we could not refer our example server as dbus service because we started it by hand. However it is quite straightforward to register our server into dbus.

At first we compile our example server so it can be referred more easily:

$ go build -o /tmp/dbus-demo-server _example/server.go

Register service

The dbus-daemon scan the /usr/share/dbus-1/system-services for system services. We should create a simple service file there. The service file has to be named after bus name of the service.

# /usr/share/dbus-1/system-services/com.github.guelfey.Demo.service

[D-BUS Service]
Name=com.github.guelfey.Demo
User=${USER}
Exec=/tmp/dbus-demo-server

Remark: ${USER} should be replaced with username which is used in the policy file.

List activate able services

We can check our service configuration by the ListActivatableNames method:

$ dbus-send --system --dest=org.freedesktop.DBus \
  --type=method_call --print-reply \
  /org/freedektop/DBus org.freedesktop.DBus.ListActivatableNames

   array [
      string "org.freedesktop.DBus"
      string "org.freedesktop.login1"
      ...
      string "com.github.guelfey.Demo"
   ]

It seems alright, let call our famous Foo method:

$ dbus-send --system --dest=com.github.guelfey.Demo \
  --type=method_call --print-reply \
  /com/github/guelfey/Demo com.github.guelfey.Demo.Foo

   string "Bar!"

Manage dbus services

It is quite easy, but how can I stop or restart our service?

Dbus services are regular processes so we only have to know their PIDs, which can be queried with the GetConnectionUnixProcessID method:

$ dbus-send --system --dest=org.freedesktop.DBus \
  --type=method_call --print-reply \
  /org/freedektop/DBus org.freedesktop.DBus.GetConnectionUnixProcessID \
  string:'com.github.guelfey.Demo'

   uint32 7909

We can stop our example service with a SIGINT signal:

$ kill -SIGINT 7909

We can ensure that our example service is stopped:

$ dbus-send --system --dest=org.freedesktop.DBus \
  --type=method_call --print-reply \
  /org/freedektop/DBus org.freedesktop.DBus.GetConnectionUnixProcessID \
  string:'com.github.guelfey.Demo'

Error org.freedesktop.DBus.Error.NameHasNoOwner: Could not get PID of name 'com.github.guelfey.Demo': no such name

Systemd service

The GetConnectionUnixProcessID exposes the process of the dbus service but it is not an administrator friendly way to manage services. Lucky for us dbus services can be managed with systemd so we don't have to query their PIDs.

Register service

Only a SystemdService option has to be set in the dbus service file to ask dbus-daemon to start our service with systemd:

# /usr/share/dbus-1/system-services/com.github.guelfey.Demo.service

[D-BUS Service]
Name=com.github.guelfey.Demo
Exec=/bin/false
SystemdService=dbus-demo

As you can see from the dbus service file above the User option is left to systemd and the Exec option is overwritten with /bin/false so the Exec would fail if there is no SystemdService.

The systemd service file of the referred dbus-demo service should look like this:

# /usr/lib/systemd/system/dbus-demo.service

[Unit]
Description=Simple dbus server example
[Service]
Type=dbus
BusName=com.github.guelfey.Demo
ExecStart=/tmp/dbus-demo-server
User=${USER}

This systemd service above will start /tmp/dbus-demo-server at the first dbus message as ${USER} (you have to replace it with a real username). Systemd use the BusName option in the status check of our example server. Systemd consider the service active if the started process acquires the com.github.guelfey.Demo BusName.

Finally a daemon-reload command has to be called to register our systemd service:

$ sudo systemctl daemon-reload

At this stage our systemd service is inactive:

$ systemctl status dbus-demo
● dbus-demo.service - Simple dbus server example
     Loaded: loaded (/usr/lib/systemd/system/dbus-demo.service; disabled; vendor preset: disabled)
     Active: inactive (dead)

It will be activated by the first dbus message:

$ dbus-send --system --dest=com.github.guelfey.Demo \
  --type=method_call --print-reply \
  /com/github/guelfey/Demo com.github.guelfey.Demo.Foo

   string "Bar!"

$ systemctl status dbus-demo
● dbus-demo.service - Simple dbus server example
     Loaded: loaded (/usr/lib/systemd/system/dbus-demo.service; disabled; vendor preset: disabled)
     Active: active (running) since Sun 2021-01-10 16:44:42 CET; 12s ago
   Main PID: 8500 (dbus-demo-serve)
      Tasks: 6 (limit: 38345)
     Memory: 1.2M
     CGroup: /system.slice/dbus-demo.service
             └─8500 /usr/bin/dbus-demo-server

We can check that systemd and dbus-daemon use the same process (PID=8500):

$ dbus-send --system --dest=org.freedesktop.DBus \
  --type=method_call --print-reply \
  /org/freedektop/DBus org.freedesktop.DBus.GetConnectionUnixProcessID \
  string:'com.github.guelfey.Demo'

   uint32 8500

Epilogue

You have to remember that neither dbus-daemon or systemd acquire bus name for your server. The bus name has to be acquired by your server.

We did not use any policy for our example server, but authorization is key point of dbus services. You should use polkit or a proper bus policy for your dbus services.

Discover dbus

2021-01-07T20:22:00+01:00

In this guide we will discover dbus services with the dbus-send command. dbus-send may not the most user friendly tool to introspect dbus services but we can learn more about the dbus protocol in this way.

List connections

As the first step we should list the connections on the session bus:

$ dbus-send --session --dest=org.freedesktop.DBus --type=method_call --print-reply \
  /org/freedesktop/DBus org.freedesktop.DBus.ListNames

   array [
      string "org.freedesktop.DBus"
      string ":1.403"
      string "org.freedesktop.Notifications"
      string ":1.405"
      string "org.freedesktop.portal.Desktop"
      string "org.freedesktop.systemd1"
      string ":1.408"
      string "org.pulseaudio.Server"
      ...
   ]

This command requires some explanation: dbus-send call the ListNames method of /org/freedesktop/DBus object at the org.freedesktop.DBus address. The ListNames method is defined in the org.freedesktop.DBus interface that's why we wrote org.freedesktop.DBus.ListNames at the end of the command.

The reply is the list of bus names on the session bus. You can see two kind of bus names there: unique name (:1.403) and well-known name (org.pulseaudio.Server). All the bus clients has a unique name but they can require well-known name, too. Services usually has well known name for easier access.

You may ask why we have to write org.freedesktop.DBus so many times. The answer lies in the components of dbus protocol: addresses, objects and interfaces.

Address

The well-known name of a dbus client is only used in message routing. Other features like match rule uses only the unique name of the client. So the well-known name has to be unique on the bus but it does not provide any further information about the client behavior.

Object

The name of the object can be used in match filters so it should be unique and they usually follow the same naming convention as the well-known bus name:

org.freedesktop.DBus -> /org/freedesktop/DBus

Interface

The interfaces describes the methods, signals and properties of the dbus objects they meant to be reusable so there are standard interfaces which are implemented by most of the dbus objects. Because interfaces can be shared their name are unique therefore the object specific interfaces starts with the well-known name of the service. Such an interface is the org.freedesktop.DBus which contains the ListNames method.

Introspect

Let see what other methods are implemented by /org/freedesktop/DBus:

$ dbus-send --session --dest=org.freedesktop.DBus --type=method_call --print-reply \
  /org/freedesktop/DBus org.freedesktop.DBus.Introspectable.Introspect

   string "<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
<node>
  <interface name="org.freedesktop.DBus">
    <method name="RequestName">
      <arg direction="in" type="s"/>
      <arg direction="in" type="u"/>
      <arg direction="out" type="u"/>
    </method>
    <method name="ListNames">
      <arg direction="out" type="as"/>
    </method>
    ...
    <property name="Features" type="as" access="read">
      <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const"/>
    </property>
    <property name="Interfaces" type="as" access="read">
      <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const"/>
    </property>
    ...
    <signal name="NameAcquired">
      <arg type="s"/>
    </signal>
  </interface>
  <interface name="org.freedesktop.DBus.Properties">
    <method name="Get">
      <arg direction="in" type="s"/>
      <arg direction="in" type="s"/>
      <arg direction="out" type="v"/>
    </method>
    <method name="GetAll">
      <arg direction="in" type="s"/>
      <arg direction="out" type="a{sv}"/>
    </method>
    <method name="Set">
      <arg direction="in" type="s"/>
      <arg direction="in" type="s"/>
      <arg direction="in" type="v"/>
    </method>
    <signal name="PropertiesChanged">
      <arg type="s" name="interface_name"/>
      <arg type="a{sv}" name="changed_properties"/>
      <arg type="as" name="invalidated_properties"/>
    </signal>
  </interface>
  <interface name="org.freedesktop.DBus.Introspectable">
    <method name="Introspect">
      <arg direction="out" type="s"/>
    </method>
  </interface>
  ...
</node>
"

The dbus objects can be introspected with the Introspect method of the org.freedesktop.DBus.Introspectable interface. The org.freedesktop.DBus.Introspectable is one of the standard interfaces which are implemented by all the dbus objects. The reply of the Introspect is an xml document which is defined in the introspect.dtd.

Method

The introspect xml document is quite readable alone without its specification. For example the RequestName method has two arguments (direction="in") a string (type="s") and a 32-bit unsigned integer (type="u") and returns (direction="out") a 32-bit unsigned integer. You can read more about the type notation in the dbus overview.

Let see how the RequestName method works:

$ dbus-send --session --dest=org.freedesktop.DBus --type=method_call --print-reply \
  /org/freedesktop/DBus org.freedesktop.DBus.RequestName string:'foo.bar.baz' uint32:4

  uint32:1

The first argument is the requested name and the second argument is a flag where 4 means DBUS_NAME_FLAG_DO_NOT_QUEUE. The other values of the flag are described in the bus messages section of the dbus specification.

Signal

Beside the return value the /org/freedesktop/DBus object will broadcast a org.freedesktop.DBus.NameAcquired signal if the RequestName call succeeded. This is a common pattern in dbus that some method call triggers a signal so an observer client can match to the signals and collect the changes about the other clients.

For development purposes the dbus messages can be monitored with dbus-monitor:

$ dbus-monitor --session

signal time=1609972071.551809 sender=org.freedesktop.DBus -> destination=:1.572 serial=2 path=/org/freedesktop/DBus; interface=org.freedesktop.DBus; member=NameAcquired
   string ":1.572"
method call time=1609972071.552236 sender=:1.572 -> destination=org.freedesktop.DBus serial=2 path=/org/freedesktop/DBus; interface=org.freedesktop.DBus; member=RequestName
   string "foo.bar.baz"
   uint32 4
signal time=1609972071.552288 sender=org.freedesktop.DBus -> destination=(null destination) serial=45 path=/org/freedesktop/DBus; interface=org.freedesktop.DBus; member=NameOwnerChanged
   string "foo.bar.baz"
   string ""
   string ":1.572"
signal time=1609972071.552354 sender=org.freedesktop.DBus -> destination=:1.572 serial=3 path=/org/freedesktop/DBus; interface=org.freedesktop.DBus; member=NameAcquired
   string "foo.bar.baz"
method return time=1609972071.552387 sender=org.freedesktop.DBus -> destination=:1.572 serial=4 reply_serial=2
   uint32 1
signal time=1609972071.553096 sender=org.freedesktop.DBus -> destination=:1.572 serial=9 path=/org/freedesktop/DBus; interface=org.freedesktop.DBus; member=NameLost
   string "foo.bar.baz"
signal time=1609972071.553164 sender=org.freedesktop.DBus -> destination=(null destination) serial=46 path=/org/freedesktop/DBus; interface=org.freedesktop.DBus; member=NameOwnerChanged
   string "foo.bar.baz"
   string ":1.572"
   string ""
signal time=1609972071.553227 sender=org.freedesktop.DBus -> destination=:1.572 serial=10 path=/org/freedesktop/DBus; interface=org.freedesktop.DBus; member=NameLost
   string ":1.572"

From these messages above you can read the story of our short lived connection:

Our client gets the :1.572 unique name.
Our client requests the "foo.bar.baz" well-known name without queuing (4).
NameOwnerChanged signal says that our client got the "foo.bar.baz" well-known name.
NameAcquired signal says that "foo.bar.baz" name is acquired.
Our client closes the connection so there will be 2 NameLost signal: one for our unique name and one for our requested well-known name.
Between the two NameLost signal a second NameOwnerChanged signal shows that the "foo.bar.baz" is free.

Property

The org.freedesktop.DBus interface holds some properties (Features, Interface) beside the methods and signals. The properties can be managed via the org.freedesktop.DBus.Properties interface. Let start with the Get method:

$ dbus-send --session --dest=org.freedesktop.DBus --type=method_call --print-reply \
  /org/freedesktop/DBus org.freedesktop.DBus.Properties.Get string:'org.freedesktop.DBus' string:'Features'

   variant       array [
         string "SystemdActivation"
      ]

The first argument of the Get method is the interface name (string:'org.freedesktop.DBus') and the second argument is the property name (string:'Features').

Remark: In some cases the interface name can be empty string if the object has only one interface with properties.

The GetAll method replies with all the properties in a dict:

$ dbus-send --session --dest=org.freedesktop.DBus --type=method_call --print-reply \
  /org/freedesktop/DBus org.freedesktop.DBus.Properties.GetAll string:'org.freedesktop.DBus'

   array [
      dict entry(
         string "Features"
         variant             array [
               string "SystemdActivation"
            ]
      )
      dict entry(
         string "Interfaces"
         variant             array [
               string "org.freedesktop.DBus.Monitoring"
               string "org.freedesktop.DBus.Debug.Stats"
            ]
      )
   ]

The properties of org.freedesktop.DBus are read only (access="read") so we cannot try the Set method.

Remark: A successful Set call would trigger a org.freedesktop.DBus.PropertiesChanged signal just like the RequestName method did with NameAcquired signal.

Object names

We can introspect a dbus object but how could we find its name?

Short answer we can introspect that, too. Let see the objects of org.pulseaudio.Server

$ dbus-send --session --dest=org.pulseaudio.Server --type=method_call --print-reply \
  / org.freedesktop.DBus.Introspectable.Introspect

   string "<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
<node>
  <node name="org"/>
</node>
"

So the / object only contains a sub node org. Let see the next level:

$ dbus-send --session --dest=org.pulseaudio.Server --type=method_call --print-reply \
  /org org.freedesktop.DBus.Introspectable.Introspect

   string "<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
<node>
  <node name="pulseaudio"/>
</node>
"

We can repeat this search until we find server_lookup1:

$ dbus-send --session --dest=org.pulseaudio.Server --type=method_call --print-reply \
  /org/pulseaudio/server_lookup1 org.freedesktop.DBus.Introspectable.Introspect

   string "<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
<node> <!-- If you are looking for documentation make sure to check out
      http://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/Developer/Clients/DBus/ -->
 <interface name="org.PulseAudio.ServerLookup1">
  <property name="Address" type="s" access="read"/>
 </interface>
 ...
</node>
"

Remark: The number in the object name (server_lookup1) is usually used for API versioning (you should not search for multiple servers).

Epilogue

This command can be applied to the system bus as well. Only the --system option has to be used instead of --session.

Now you can discover the system and session buses on your machine without any fancy GUI.

Argparse default trick

2021-01-03T12:00:00+01:00

At One Identity - Quest we have a repetitive job to create small helper scripts for our internal services. Most of them are simple xmlrpc client which expose only a couple of methods and the methods have zero or one parameter. This minimalist requirements can be implemented with standard python libraries.

argparse subparsers

The add_subparsers method of ArgumentParser can be used to select the xmlrpc method:

import argparse
import xmlrpc.client

parser = argparse.ArgumentParser()
sub_parsers = parser.add_subparsers(dest="command", required=True)

sub_parsers.add_parser("list")

get_parser = sub_parsers.add_parser("get")
get_parser.add_argument("id")

client = xmlrpc.client.ServerProxy("http://127.0.0.1:1234")
args = parser.parse_args()

if args.command == "list":
    client.list()
elif args.command == "get":
    client.get(args.id)

and argparse will generate the usual interactive help for our client:

usage: client.py [-h] {list,get} ...

positional arguments:
  {list,get}

optional arguments:
  -h, --help  show this help message and exit

usage: client.py get [-h] id

positional arguments:
  id

optional arguments:
  -h, --help  show this help message and exit

set_defaults

This is nice, but it would better if the function call and the argument definition would be closer. The set_defaults method can help to register our xmlrpc call into the parsed args:

import argparse
import xmlrpc.client

client = xmlrpc.client.ServerProxy("http://127.0.0.1:1234")

parser = argparse.ArgumentParser()
sub_parsers = parser.add_subparsers(dest="command", required=True)

list_parser = sub_parsers.add_parser("list")
list_parser.set_defaults(action=lambda _: client.list())

get_parser = sub_parsers.add_parser("get")
get_parser.add_argument("id")
get_parser.set_defaults(action=lambda args: client.get(args.id))

args = parser.parse_args()
args.action(args)

argparse_action

It's more compact but not so pythonic. The code would be more readable if the argument definition would be created from the function signature not the other way around. The inspect.signature can help us to create a helper module (argparse_action) for this:

import inspect

def add_action(sub_parsers, func):
    parser = sub_parsers.add_parser(func.__name__)
    sig = inspect.signature(func)

    for name in sig.parameters:
        parser.add_argument(name)

    def action(cli_args):
        func_args = [getattr(cli_args, name) for name in sig.parameters]
        return func(*func_args)

    parser.set_defaults(action=action)

import argparse
import xmlrpc.client

from argparse_action import add_action


def get(id):
    client = _connect()
    return client.get(id)

def list():
    client = _connect()
    return client.list()

def _connect():
    return xmlrpc.client.ServerProxy("http://127.0.0.1:1234")


parser = argparse.ArgumentParser()
sub_parsers = parser.add_subparsers(dest="command", required=True)
add_action(sub_parsers, list)
add_action(sub_parsers, get)

args = parser.parse_args()
args.action(args)

action.add decorator

It is more readable but we cannot see easily which function is exposed to CLI. A decoration could help:

import inspect


class Action:
    def __init__(self, pasrer):
        self._parsers = parser.add_subparsers(dest="command", required=True)

    def add(self, func):
        parser = self._parsers.add_parser(func.__name__)
        return add_action(parser, func)

def add_action(parser, func):
    sig = inspect.signature(func)

    for name in sig.parameters:
        parser.add_argument(name)

    def action(cli_args):
        func_args = [getattr(cli_args, name) for name in sig.parameters]
        return func(*func_args)

    parser.set_defaults(action=action)
    return action

import argparse
import xmlrpc.client

from argparse_action import add_action

parser = argparse.ArgumentParser()
action = Action(parser)


@action.add()
def get(id):
    client = _connect()
    return client.get(id)

@action.add()
def list():
    client = _connect()
    return client.list()

def _connect():
    return xmlrpc.client.ServerProxy("http://127.0.0.1:1234")

args = parser.parse_args()
args.action(args)

The argparse_action is published to pypi so you can try the its other features.