======== xkbgroup

.. image:: https://img.shields.io/badge/python-3.2+-blue.svg

.. image:: https://img.shields.io/pypi/v/xkbgroup.svg :target: https://pypi.python.org/pypi/xkbgroup

.. image:: https://img.shields.io/badge/license-MIT-blue.svg :target: https://github.com/hcpl/xkbgroup/blob/master/LICENSE

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

.. contents:: 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__ ++++++++++++++++++++++++++++

__ https://pypi.python.org/pypi/xkbgroup

.. code-block:: sh

pip install xkbgroup

Library usage

.. code-block:: sh

Assume we have the following configuration

$ setxkbmap -layout us,ru,ua,fr

Change layout once before calling python

$ python

.. code-block:: 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_.

__ https://wiki.archlinux.org/index.php/X_KeyBoard_extension#Keycode_translation

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.

Xkbgroup

Install / Use

README