Skip to content

Commit

Permalink
docs: Added import statements to all examples
Browse files Browse the repository at this point in the history
  • Loading branch information
igo95862 committed Feb 4, 2021
1 parent d7de72c commit 37ea44c
Show file tree
Hide file tree
Showing 5 changed files with 96 additions and 19 deletions.
29 changes: 23 additions & 6 deletions docs/asyncio_api.rst
Original file line number Diff line number Diff line change
Expand Up @@ -153,7 +153,10 @@ Decorators
:param str method_name: Force specific dbus method name
instead of being based on Python function name.

Example::
Example: ::

from sdbus import DbusInterfaceCommonAsync, dbus_method_async


class ExampleInterface(DbusInterfaceCommonAsync,
interface_name='org.example.test'
Expand Down Expand Up @@ -223,7 +226,10 @@ Decorators
Set property value.


Example::
Example: ::

from sdbus import DbusInterfaceCommonAsync, dbus_property_async


class ExampleInterface(DbusInterfaceCommonAsync,
interface_name='org.example.test'
Expand Down Expand Up @@ -294,7 +300,10 @@ Decorators
Emit a new signal with *args* data.

Example::
Example: ::

from sdbus import DbusInterfaceCommonAsync, dbus_signal_async


class ExampleInterface(DbusInterfaceCommonAsync,
interface_name='org.example.signal'
Expand All @@ -315,7 +324,11 @@ Decorators

You **must** add round brackets to decorator.

Example::
Example: ::

from sdbus import (DbusInterfaceCommonAsync, dbus_method_async
dbus_method_async_override)


class ExampleInterface(DbusInterfaceCommonAsync,
interface_name='org.example.test'
Expand All @@ -340,7 +353,11 @@ Decorators

You **must** add round brackets to decorator.

Example::
Example: ::

from sdbus import (DbusInterfaceCommonAsync, dbus_property_async
dbus_property_async_override)


class ExampleInterface(DbusInterfaceCommonAsync,
interface_name='org.example.test'
Expand All @@ -350,7 +367,7 @@ Decorators
self.s = 'aaaaaaaaa'

# Original property
@dbus_property('s')
@dbus_property_async('s')
def str_prop(self) -> str:
return self.s
Expand Down
40 changes: 36 additions & 4 deletions docs/asyncio_quick.rst
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,10 @@ Interface classes for async IO should be derived from :py:class:`DbusInterfaceCo
The class constructor takes ``interface_name`` keyword to determine the dbus interface name for all
dbus elements declared in the class body.

Example::
Example: ::

from sdbus import DbusInterfaceCommonAsync


class ExampleInterface(DbusInterfaceCommonAsync,
interface_name='org.example.myinterface'
Expand All @@ -26,7 +29,11 @@ signals using decorators such as
:py:func:`dbus_signal_async`.


Example::
Example: ::

from sdbus import (DbusInterfaceCommonAsync, dbus_method_async,
dbus_property_async, dbus_signal_async)


class ExampleInterface(DbusInterfaceCommonAsync,
interface_name='org.example.myinterface'
Expand Down Expand Up @@ -57,6 +64,9 @@ Connecting

Recommended to create connection classes that a subclass of the interface: ::

from sdbus import DbusInterfaceCommonAsync


class ExampleInterface(...):
# Some interface class
...
Expand All @@ -74,7 +84,10 @@ Serving objects
will export the object to the dbus. After calling it the object
becomes visible on dbus for other processes to call.

Example using ExampleInterface from before ::
Example using ExampleInterface from before: ::

from sdbus import request_default_bus_name_async


loop = get_event_loop()

Expand Down Expand Up @@ -125,7 +138,10 @@ Regular exceptions will not propagate.

See :doc:`/exceptions`.

Example::
Example: ::

from sdbus import DbusInterfaceCommonAsync, dbus_method_async


class ExampleInterface(...):

Expand Down Expand Up @@ -159,6 +175,9 @@ To declare a read only property you need to decorate a regular function with

Example: ::

from sdbus import DbusInterfaceCommonAsync, dbus_property_async


class ExampleInterface(...):

...
Expand All @@ -174,6 +193,9 @@ the :py:obj:`setter` attribute of your getter function.

Example: ::

from sdbus import DbusInterfaceCommonAsync, dbus_property_async


class ExampleInterface(...):

...
Expand Down Expand Up @@ -221,6 +243,9 @@ to just put ``raise NotImplementedError`` in to the body of the function.

Example: ::

from sdbus import DbusInterfaceCommonAsync, dbus_signal_async


class ExampleInterface(...):

...
Expand Down Expand Up @@ -251,6 +276,10 @@ Overridden methods should take same number and type of arguments.

Example: ::

from sdbus import (dbus_method_async_override,
dbus_property_async_override)


# Some subclass
class SubclassInterface(...):

Expand Down Expand Up @@ -278,6 +307,9 @@ multiple inheritance on all interfaces the object has.

Example: ::

from sdbus import DbusInterfaceCommonAsync


class ExampleInterface(DbusInterfaceCommonAsync,
interface_name='org.example.myinterface'
):
Expand Down
12 changes: 9 additions & 3 deletions docs/common_api.rst
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,10 @@ Helper functions
:return: valid object path
:rtype: str

Example on how systemd encodes unit names on dbus ::
Example on how systemd encodes unit names on dbus: ::

from sdbus import encode_object_path


# System uses /org/freedesktop/systemd1/unit as prefix of all units
# dbus.service is a name of dbus unit but dot . is not a valid object path
Expand All @@ -78,9 +81,12 @@ Helper functions
:return: Arbitrary name
:rtype: str

Example decoding systemd unit name ::
Example decoding systemd unit name: ::

from sdbus import decode_object_path


s = encode_object_path(
s = decode_object_path(
'/org/freedesktop/systemd1/unit',
'/org/freedesktop/systemd1/unit/dbus_2eservice'
)
Expand Down
16 changes: 13 additions & 3 deletions docs/sync_api.rst
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,11 @@ Classes
:return: string with introspection XML
:rtype: str

Example::
Example: ::

from sdbus import (DbusInterfaceCommon,
dbus_method, dbus_property)


class ExampleInterface(DbusInterfaceCommon,
interface_name='org.example.my'
Expand Down Expand Up @@ -112,7 +116,10 @@ Decorators
Usually not required as remote method name will be constructed
based on original method name.

Defining methods example::
Defining methods example: ::

from sdbus import DbusInterfaceCommon, dbus_method


class ExampleInterface(DbusInterfaceCommon,
interface_name='org.example.my'
Expand Down Expand Up @@ -174,7 +181,10 @@ Decorators
Usually not required as remote property name will be constructed
based on original method name.

Defining properties example::
Defining properties example: ::

from sdbus import DbusInterfaceCommon, dbus_property


class ExampleInterface(DbusInterfaceCommon,
interface_name='org.example.myproperty'
Expand Down
18 changes: 15 additions & 3 deletions docs/sync_quick.rst
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,10 @@ Interface class body should contain the definitions of methods, properties and s

Example::

from sdbus import (DbusInterfaceCommon,
dbus_method, dbus_property)


class ExampleInterface(DbusInterfaceCommon,
interface_name='org.example.myinterface'
):
Expand Down Expand Up @@ -74,7 +78,10 @@ will be raised. See :doc:`/exceptions` for list of exceptions.

The wrapped function will not be called. Its recommended to set the function to ``raise NotImplementedError``.

Example::
Example: ::

from sdbus import DbusInterfaceCommon, dbus_method


class ExampleInterface(...):

Expand All @@ -90,7 +97,9 @@ Properties

DBus property is defined by wrapping a function with :py:func:`dbus_property` decorator.

Example::
Example: ::

from sdbus import DbusInterfaceCommon, dbus_property

class ExampleInterface(...):

Expand Down Expand Up @@ -126,7 +135,10 @@ A dbus object can have multiple interfaces with different methods and properties
To implement this define multiple interface classes and do a
multiple inheritance on all interfaces the object has.

Example::
Example: ::

from sdbus import DbusInterfaceCommon, dbus_method


class ExampleInterface(DbusInterfaceCommon,
interface_name='org.example.myinterface'
Expand Down

0 comments on commit 37ea44c

Please sign in to comment.