xkbgroup

Query and change XKB layout state


License
MIT
Install
pip install xkbgroup==0.2.0

Documentation

xkbgroup

Use this library to change the keyboard layout through XKB extension (subsystem) of the X server system. Both library and command line script included.

Dependencies

  • Python 3.2+
  • libX11.so.6 shared library which you must have by default if you use X server

Installation

From PyPI package xkbgroup

pip install xkbgroup

Library usage

# Assume we have the following configuration
$ setxkbmap -layout us,ru,ua,fr
# Change layout once before calling python
$ python
>>> from xkbgroup import XKeyboard
>>> xkb = XKeyboard()
>>> xkb.groups_count
4
>>> xkb.group_num
1
>>> xkb.group_num = 2
>>> xkb.group_num
2
>>> xkb.group_num -= 2
>>> xkb.group_num
0
>>> xkb.groups_names
['English (US)', 'Russian', 'Ukrainian', 'French']
>>> xkb.group_name
'English (US)'
>>> xkb.group_name = 'Ukrainian'
>>> xkb.group_name
'Ukrainian'
>>> xkb.group_num
2
>>> xkb.groups_symbols
['us', 'ru', 'ua', 'fr']
>>> xkb.group_symbol
'ua'
>>> xkb.group_symbol = 'fr'
>>> xkb.group_symbol
'fr'
>>> xkb.groups_variants
['', '', '', '']
>>> xkb.group_variant
''
>>> xkb.group_num -= 3
>>> xkb.group_variant
''
>>> xkb.group_num
0
>>> xkb.group_data
GroupData(num=0, name='English (US)', symbol='us', variant='')
>>> xkb.groups_data
[GroupData(num=0, name='English (US)', symbol='us', variant=''), GroupData(num=1, name=
'Russian', symbol='ru', variant=''), GroupData(num=2, name='Ukrainian', symbol='ua', va
riant=''), GroupData(num=3, name='French', symbol='fr', variant='')]
>>> xkb.format('{num} => {symbol}')
'0 => us'
>>> xkb.group_num = 1
>>> xkb.format('{num} => {symbol}')
'1 => ru'
>>> xkb.group_num = 3
>>> xkb.format('{num}: {symbol} - {name} "{variant}"')
'3: fr - French ""'
>>> xkb.format('{count}')
'4'
>>> xkb.format('{names}')
"['English (US)', 'Russian', 'Ukrainian', 'French']"
>>> xkb.format('{names::}')
'English (US)RussianUkrainianFrench'
>>> xkb.format('{names:: - }')
'English (US) - Russian - Ukrainian - French'
>>> xkb.format('{symbols:: - }')
'us - ru - ua - fr'
>>> xkb.format('{symbols:s: - }')
'us - ru - ua - fr'
>>> xkb.format('{all_data}')
"[GroupData(num=0, name='English (US)', symbol='us', variant=''), GroupData(num=1, name
='Russian', symbol='ru', variant=''), GroupData(num=2, name='Ukrainian', symbol='ua', v
ariant=''), GroupData(num=3, name='French', symbol='fr', variant='')]"
>>> xkb.format('{all_data:{{num}}}')
"['0', '1', '2', '3']"
>>> xkb.format('{all_data:/* {{name}} */}')
"['/* English (US) */', '/* Russian */', '/* Ukrainian */', '/* French */']"
>>> xkb.format('{all_data:{{symbol}}:\n}')
'us\nru\nua\nfr'
>>> print(xkb.format('{all_data:{{symbol}}:\n}'))
us
ru
ua
fr
>>> print(xkb.format('{all_data:{{num}}\\: {{symbol}} - {{name}} - "{{variant}}":\n}'))
0: us - English (US) - ""
1: ru - Russian - ""
2: ua - Ukrainian - ""
3: fr - French - ""
>>>

Command line features mapping

Category Library Command line
Get xkb.group_num xkbgroup get num
xkb.group_name xkbgroup get name
xkb.group_symbol xkbgroup get symbol
xkb.group_variant xkbgroup get variant
xkb.group_data xkbgroup get current_data
xkb.groups_count xkbgroup get count
xkb.groups_names xkbgroup get names
xkb.groups_symbols xkbgroup get symbols
xkb.groups_variants xkbgroup get variants
xkb.groups_data xkbgroup get all_data
Set xkb.group_num = 2 xkbgroup set num 2
xkb.group_name = 'English (US)' xkbgroup set name 'English (US)'
xkb.group_symbol = 'fr' xkbgroup set symbol fr
Format xkb.format('{format_str}') xkbgroup format '{format_str}'

Naming convention

Throughout the whole XKB subsystem the so-called groups represent actual keyboard layouts. This library follows the same convention and names of the API methods start with group_ or groups_.

Classes

These all reside in xkbgroup/core.py:

  • XKeyboard — the main class:
    • __init__(self, auto_open=True, non_symbols=None):
      • auto_open — if True then automatically call open_display() on initialization.
      • non_symbols — either iterable of string non-symbol names or None to use the default set of non-symbol names.
    • open_display() — establishes connection with X server and prepares objects necessary to retrieve and send data.
    • close_display() — closes connection with X server and cleans up objects created on open_display().
    • group_* — properties for accessing current group data:
      • group_num — get/set current group number (e.g. 0, 2, 3).
      • group_name — get/set current group full name (e.g. English (US), Russian, French).
      • group_symbol — get/set current group symbol (e.g. us, ru, fr).
      • group_variant — get (only) current group variant (e.g. , dos, latin9).
      • group_data — get (only) all data about the current group. In fact, assembles all previous group_* values.
    • groups_* — properties for querying info about all groups set by setxkbmap:
      • groups_count — get number of all groups.
      • groups_names — get names of all groups.
      • groups_symbols — get symbols of all groups.
      • groups_variants — get variants of all groups.
      • groups_data — get all data about all groups by assembling all previous groups_* values.
    • format() — obtain a formatted output, see docs/formatting.rst for details.
  • X11Error — an exception class, raised for errors on X server issues.

Helper files

There are also complementary files:

  • generate_bindings.sh — a shell script which generates Python bindings to X server structures, functions and #define definitions by:
    • converting X11 C headers using h2xml and xml2py;
    • creating ctypes references to functions from libX11.so.6 using xml2py.
  • xkbgroup/xkb.py — the output of the above script, usable for Xlib development under Python.