xkbgroup 0.2.0

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