Skip to main content
Help us improve PyPI by participating in user testing. All experience levels needed!

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


Release history Release notifications

This version
History Node

0.2.0

History Node

0.1.4.3

History Node

0.1.4.2

History Node

0.1.4.1

History Node

0.1.3

History Node

0.1.2

History Node

0.1.1

History Node

0.1

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 Oct 6, 2017
xkbgroup-0.2.0.tar.gz (79.4 kB) Copy SHA256 hash SHA256 Source None Oct 6, 2017

Supported by

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