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.

Table of Contents

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 -------------------------------------+ xkb.group_name -------------------------------------+ xkb.group_symbol -------------------------------------+ xkb.group_variant -------------------------------------+ xkb.group_data -------------------------------------+ xkb.groups_count -------------------------------------+ xkb.groups_names -------------------------------------+ xkb.groups_symbols -------------------------------------+ xkb.groups_variants -------------------------------------+ xkb.groups_data	xkbgroup get num --------------------------------------+ xkbgroup get name --------------------------------------+ xkbgroup get symbol --------------------------------------+ xkbgroup get variant --------------------------------------+ xkbgroup get current_data --------------------------------------+ xkbgroup get count --------------------------------------+ xkbgroup get names --------------------------------------+ xkbgroup get symbols --------------------------------------+ xkbgroup get variants --------------------------------------+ xkbgroup get all_data
Set	xkb.group_num = 2 -------------------------------------+ xkb.group_name = 'English (US)' -------------------------------------+ xkb.group_symbol = 'fr'	xkbgroup set num 2 --------------------------------------+ xkbgroup set name 'English (US)' --------------------------------------+ 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.