Adaptors

class Dpowers.Adaptor(main_info=None, *, group='default', _primary_name=False, **method_infos)

Abstract baseclass for all of Dpower’s Adaption classes.

__init__(main_info=None, *, group='default', _primary_name=False, **method_infos)

Usually, you do not need to create Adaptor instances yourself as a default instance is already available for each subclass (see below).

Parameters:

main_info (str) – Name of the backend to be used, passed on to adapt().
group (str) – Name of the instance group to which the new instance will belong.
_primary_name – Used only for internal documentation purposes. It allows specifiying the primary/default instance for each instance group.
method_infos – Passed on to adapt().

If the main_info and/or method_infos parameter is given, the new instance is immediately adapted using its adapt() method.

If neither main_info nor method_infos is specified (default), and Adpator.autoadapt_active is True, choose the default backend according to the instance group and Dpowers.default_backends.py.

Otherwise an unadapted instance is created.

adapt(main_info=None, *, raise_error=True, require_backend=True, **method_infos)

Choose the backend for this Adaptor instance. If neither main_info nor method_infos is specified, the default backend for this instance group is selected, as defined in the module Dpowers.default_backends.py.

Parameters:

main_info (str) – Name of the backend to be used.
raise_error (bool) – If set to False, exceptions caused during backend import are suppressed. A warning is printed instead.
require_backend (bool) – If set to True (default), a ValueError will be raised if no default backend could be found.
method_infos – Explanation to be added .

Returns:

The module object of the backend’s adapt_*.py file.
False if an exception occurs but is suppressed (see parameters raise_error and require_backend).

Raises:

Dpowers.AdaptionError if there is an exception during importing the backend.
ValueError if used without arguments and no default backend could be found (you can disable this via require_backend=False).

keyb (KeyboardAdaptor)

Dpowers.keyb

Default instance of KeyboardAdaptor class.

How to import:

from Dpowers import keyb

# choose the default backend for your system:
keyb.adapt()

# alternatively, choose one of the following backends:
keyb.adapt('evdev')
keyb.adapt('pynput')
keyb.adapt('xdotool_bash')

How to install dependencies for available backends:

>>> print(keyb.install_instructions())
pip install -U pynput
sudo apt install xdotool

class Dpowers.KeyboardAdaptor(main_info=None, *, group='default', _primary_name=False, **method_infos)

Send key events to the system via the chosen backend.

See Dpowers.events.keybutton_names.py for a list of allowed key names and key groups. Most of the defined keys can be called by more than one name equivalently. Simply pass one of the key’s names as a string to the methods defined below.

For some backends (such as evdev) it might be neccessary to manually specify the layout of the keyboard currently used via the set_layout() method.

Subclass of Dpowers.Adaptor.

adapt(main_info=None, *, raise_error=True, require_backend=True, **method_infos): Choose the backend for this instance. See Adaptor.adapt().

default_delay = 0: Class attribute. Default time (in milliseconds) to wait between sending several keys in a row. You can set a custom value to this attribute for the whole class or for a single instance.

default_duration = 1: Class attribute. Default time (in milliseconds) to wait between sending press and release event of the same key. You can set a custom value to this attribute for the whole class or for a single instance.

send(string, auto_rls=True, delay=None)

Convenience method to send several kind of key patterns in one command. It integrates the functionality of tap(), comb() and text().

Parameters:

string (str) – Content to be sent, format see below.
auto_rls (bool) – If True, send press and release events for all keys specified inside < >. If False, normal key names are interpreted as press events and you must attach _rls to a key name to send the corresponding release event.
delay (int) – Time (in milliseconds) to wait between tapping keys. Defaults to default_delay.

The string parameter will be parsed from left to right according to the following rules:

There are two special characters: < and >. All content between them will be interpreted as key names (as if called by the tap() method):
```
keyb.send("<return>") # is equivalent to
keyb.tap("return")
```

Everything outside of a < > block will be sent literally using the text() method:

keyb.send("normal text input..") # is equivalent to
keyb.text("normal text input..")

Use <key1+key2> to send key combinations:

keyb.send("<ctrl+s>") # is equivalent to
keyb.comb("ctrl","s") # is equivalent to
keyb.send("<ctrl s s_rls ctrl_rls>", auto_rls=False)

Chain keys and texts as in the following examples:

keyb.send("<home>hello world<return end>") # equivalent to
keyb.tap("home","h","e","l","l","o"," ","w","o","r","l","d",
"return", "end")

keyb.send("<key1 key2 key3>") # equivalent to
keyb.send("<key1><key2><key3>")

keyb.send("<shift+home backspace>this line was deleted")
# is equivalent to
keyb.comb("shift","home")
keyb.tap("backspace")
keyb.text("this line was deleted")

If not paired, < and > are interpreted literally.
Use <><something> to send literal <something> as text output.

tap(key, *keys, delay=None, duration=None, repeat=1)

Simulate a key tap (i.e. send a press event followed by a release event of the same key), or multiple key taps in a row.

Parameters:

key (str) – Name of the (first) key to be sent.
keys (str) – Further names of keys to be sent in sequence.
delay (int) – Time (in milliseconds) to wait after tapping a key. Defaults to default_delay.
duration (int) – Time (in milliseconds) to wait between each press and release event. Defaults to default_duration.
repeat – Number of times this sequence should be repeated.

Examples:

keyb.tap("a")
keyb.tap(1)
keyb.tap("esc")
keyb.tap("f9")

press(key, *keys, delay=None, translate_names=True)

Send key press event(s) to the system. You need to manually send the corresponding release event(s) afterwards.

Parameters:: See tap().

rls(key, *keys, delay=None)

Send key release event(s) to the system.

Parameters:: See tap().

comb(key1, key2, *keys, delay=None, duration=None)

Simulates a key combination, such as Control+S or Shift+Alt+F5. Sends all the press events first and then the release events in reverse order.

Parameters:

key1 (str) – The is the name of the first key to be pressed (and hence the last to be released.)
key2 (str) – The name of the second key in the combination.
keys (str) – Further key names.
delay (int) – Time (in milliseconds) to wait between pressing/releasing the sequence of keys. Defaults to default_delay.
duration (int) – Time (in milliseconds) to wait between sending the press and release event of the final key. Defaults to default_duration.

Examples:

keyb.comb("ctrl","s")
keyb.comb("shift","alt","f5")

custom_text_method = True: Default value for parameter custom of method text().

text(text, delay=None, custom=None, **kwargs)

Send a plain text string to the system as if the user would type it.

Parameters:

text (str) – Any text you want to send. Depending on the backend, not all symbols might be supported.
delay (int) – Time (in milliseconds) to wait between sending single characters. Defaults to default_delay.
custom (bool) – If set to True, prefer the backend’s special text method if implemented. Otherwise use tap() for sending single characters via the backend’s press/rls methods.
kwargs – Custom keyword arguments to pass to the backend’s text method.

property layout: Return the currently used keyboard layout for this instance. Use set_layout() to change it manually.

set_layout(name, make_default=False, backend_layout=None, use_shifted=None)

Manually set the effective keyboard layout and translate the key codes from the backend accordingly. This is e.g. necessary for the evdev backend to make sure that the correct keys are sent to the system.

Parameters:

name (str) – Name of the keyboard layout you use. This is usually a two character abbreviation, such as ‘de’ or ‘us’. A list of available layouts can be found in the folder Dhelpers.KeyboardLayouts.layouts_imported_from_xkb.
make_default (bool) – If set to True, all other instances of KeyboardAdaptor with the same backend as this instance will use this layout by default. Raises an exception if the backend for this instance has not been chosen yet.
backend_layout (str) – Manually set the assumed backend layout. Normally this is set by the backend, so don’t use this parameter unless you know what you are doing.
use_shifted (bool) – Whether to use manualy key shifting when sending keys. Normally this is set by the backend, so don’t use this parameter unless you know what you are doing.

Example for a German keyboard:

>>> from Dpowers import keyb
>>> keyb.adapt("evdev")
<module 'Dpowers.events.sending.keybpower.adapt_evdev'>
>>> keyb.layout # returns default layout for evdev backend
us
>>> keyb.tap("[") # sents the wrong key on a German keyboard:
>>> ü
>>> # change to German layout & set as default for evdev backend:
>>> keyb.set_layout("de", make_default=True)
>>> keyb.tap("[") # now the correct key is sent:
>>> [

property key

This object allows accessing Dpowers’ internal key objects and key groups as defined in the module Dpowers.events.keybutton_names.py. Find a key object by calling it’s name:

>>> keyb.key("a")
<Dpowers.events.keybutton_classes.NamedKey object at 0x73fc54c095e0 with standard name 'a'>
>>> keyb.key("ctrl")
<Dpowers.events.keybutton_classes.NamedKey object at 0x73fc54c0dfd0 with standard name 'CtrlL'>
>>> keyb.key(1)
<Dpowers.events.keybutton_classes.NamedKey object at 0x73fc54c0a780 with standard name '1'>
>>> # check if two names belong to the same key object:
>>> keyb.key("ctrl") is keyb.key("leftcontrol")
True

You can find key groups via the .group attribute and check if a key belongs to it:

>>> keyb.key.group.arrow_keys
[<Dpowers.events.keybutton_classes.NamedKey object at 0x73fc54c0e9c0 with standard name 'up'>, <Dpowers.events.keybutton_classes.NamedKey object at 0x73fc54c0e990 with standard name 'down'>, <Dpowers.events.keybutton_classes.NamedKey object at 0x73fc54c0eab0 with standard name 'left'>, <Dpowers.events.keybutton_classes.NamedKey object at 0x73fc54c0eb70 with standard name 'right'>]
>>> "up" in keyb.key.group.arrow_keys
True
>>> 0 in keyb.key.group.arrow_keys
False
>>> 0 in keyb.key.group.digits
True

class Dpowers.KeyboardAdaptor.AdaptiveClass: A baseclass to create your own AdaptiveClasses. See Dpowers.AdaptiveClass.

mouse (MouseAdaptor)

Dpowers.mouse

Default instance of MouseAdaptor class.

How to import:

from Dpowers import mouse

# choose the default backend for your system:
mouse.adapt()

# alternatively, choose one of the following backends:
mouse.adapt('evdev')
mouse.adapt('pynput')

How to install dependencies for available backends:

>>> print(mouse.install_instructions())
pip install -U pynput

class Dpowers.MouseAdaptor(main_info=None, *, group='default', _primary_name=False, **method_infos)

Subclass of Dpowers.Adaptor.

adapt(main_info=None, *, raise_error=True, require_backend=True, **method_infos): Choose the backend for this instance. See Adaptor.adapt().

default_delay = 0: Class attribute. Default time (in milliseconds) to wait between sending several buttons in a row. You can set a custom value to this attribute for the whole class or for a single instance.

default_duration = 1: Class attribute. Default time (in milliseconds) to wait between sending press and release event of the same button. You can set a custom value to this attribute for the whole class or for a single instance.

class Dpowers.MouseAdaptor.AdaptiveClass: A baseclass to create your own AdaptiveClasses. See Dpowers.AdaptiveClass.

clip (ClipboardAdaptor)

Dpowers.clip

Default instance of ClipboardAdaptor class.

How to import:

from Dpowers import clip

# choose the default backend for your system:
clip.adapt()

# alternatively, choose one of the following backends:
clip.adapt('termux')
clip.adapt('xclip_bash')
clip.adapt('xsel_bash')

How to install dependencies for available backends:

>>> print(clip.install_instructions())
sudo apt install xclip xsel

class Dpowers.ClipboardAdaptor(main_info=None, *, group='default', _primary_name=False, **method_infos)

Subclass of Dpowers.Adaptor.

adapt(main_info=None, *, raise_error=True, require_backend=True, **method_infos): Choose the backend for this instance. See Adaptor.adapt().

get(selection=0) → str

Retrieves the content

Parameters:: selection – The selection to be retrieved. Defaults to 0, i.e. the standard clipboard.
Returns str:: retrieved content

class Dpowers.ClipboardAdaptor.AdaptiveClass: A baseclass to create your own AdaptiveClasses. See Dpowers.AdaptiveClass.

ntfy (NotificationAdaptor)

Dpowers.ntfy

Default instance of NotificationAdaptor class.

How to import:

from Dpowers import ntfy

# choose the default backend for your system:
ntfy.adapt()

# alternatively, choose one of the following backends:
ntfy.adapt('notify_send_bash')
ntfy.adapt('termux')

class Dpowers.NotificationAdaptor(main_info=None, *, group='default', _primary_name=False, **method_infos)

Subclass of Dpowers.Adaptor.

adapt(main_info=None, *, raise_error=True, require_backend=True, **method_infos): Choose the backend for this instance. See Adaptor.adapt().

class Dpowers.NotificationAdaptor.AdaptiveClass: A baseclass to create your own AdaptiveClasses. See Dpowers.AdaptiveClass.

dlg (DialogAdaptor)

Dpowers.dlg

Default instance of DialogAdaptor class.

How to import:

from Dpowers import dlg

# choose the default backend for your system:
dlg.adapt()

# alternatively, choose one of the following backends:
dlg.adapt('termux')
dlg.adapt('tkinter')
dlg.adapt('zenity_bash')

How to install dependencies for available backends:

>>> print(dlg.install_instructions())
sudo apt install python3-tk zenity

class Dpowers.DialogAdaptor(main_info=None, *, group='default', _primary_name=False, **method_infos)

Subclass of Dpowers.Adaptor.

adapt(main_info=None, *, raise_error=True, require_backend=True, **method_infos): Choose the backend for this instance. See Adaptor.adapt().

date(selected=None, **kwargs): selected_date must be of form (dd,mm,yyyy). returns the same format.

class Dpowers.DialogAdaptor.AdaptiveClass: A baseclass to create your own AdaptiveClasses. See Dpowers.AdaptiveClass.

hook (HookAdaptor)

Dpowers.hook

Default instance of HookAdaptor class.

How to import:

from Dpowers import hook

# choose the default backend for your system:
hook.adapt()

# alternatively, choose one of the following backends:
hook.adapt('evdev')
hook.adapt('pynput')

How to install dependencies for available backends:

>>> print(hook.install_instructions())
pip install -U pynput

class Dpowers.HookAdaptor(main_info=None, *, group='default', _primary_name=False, **method_infos)

Subclass of Dpowers.Adaptor.

adapt(main_info=None, *, raise_error=True, require_backend=True, **method_infos): Choose the backend for this instance. See Adaptor.adapt().

class Dpowers.HookAdaptor.AdaptiveClass: A baseclass to create your own AdaptiveClasses. See Dpowers.AdaptiveClass.