Metadata-Version: 1.1
Name: xkbgroup
Version: 0.2.0
Summary: Query and change XKB layout state
Home-page: https://github.com/hcpl/xkbgroup
Author: Nguyen Duc My
Author-email: hcpl.prog@gmail.com
License: MIT
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.
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: X11 Applications
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Desktop Environment :: Window Managers
Classifier: Topic :: Software Development :: Libraries
