Skip to main content

Query and change XKB layout state

Project description

========
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.


Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
xkbgroup-0.2.0-py3-none-any.whl (80.9 kB) Copy SHA256 hash SHA256 Wheel py3
xkbgroup-0.2.0.tar.gz (79.4 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page