==============================================================
 python-uinput - Simple Python API to the Linux uinput-system
==============================================================

.. contents::

Description
===========

Uinput allows attaching user-space device drivers into the Linux kernel.
Python-uinput provides a simple and easy to use API to the Linux uinput-system.

General information
===================

- **Author**: `Tuomas Räsänen <http://tuos.codegrove.org/>`_ <tuos@codegrove.org>
- **Homepage**: http://codegrove.org/python-uinput/
- **License**: LGPLv3+ (see COPYING for details)
- **Version**: 0.3

Requirements
============

- Python 2.6. and development files for it:

  - On Ubuntu::

      sudo apt-get install python2.6-dev

Example usage
=============

Create and use a new uinput device with key-capabilities::

  import uinput

  device = uinput.Device()

  keys = uinput.KeyCapabilities(device)
  keys.add(uinput.KEY_A)
  keys.add(uinput.KEY_B)

  keys.click(uinput.KEY_A)
  keys.click(uinput.KEY_B)
  keys.click(uinput.KEY_B)
  keys.press(uinput.KEY_A)
  keys.release(uinput.KEY_A)

Use built-in mouse-device::

  import uinput.devices

  mouse = uinput.devices.Mouse()

  mouse.move(100, 100)

Use built-in keyboard-device::

  import uinput.devices

  keyboard = uinput.devices.Keyboard()

  keyboard.click(uinput.KEY_H)
  keyboard.click(uinput.KEY_E)
  keyboard.click(uinput.KEY_L)
  keyboard.click(uinput.KEY_L)
  keyboard.click(uinput.KEY_O)

Create and use a new device with key and absolute-axis capability::

  import uinput

  device = uinput.Device()

  abs_axes = uinput.AbsoluteAxisCapabilities(device)
  abs_axes.add(uinput.ABS_X, abs_min=-50, abs_max=50)

  keys = uinput.KeyCapabilities(device)
  keys.add(uinput.BTN_GAMEPAD)

  abs_axes.move_to(uinput.ABS_X, 15)
  keys.click(uinput.BTN_GAMEPAD)

All the above things can also be done through the "lower-level API"::

  import uinput

  device = uinput.Device()

  device.add_capability(uinput.EV_KEY, uinput.KEY_A)
  device.add_capability(uinput.EV_KEY, uinput.KEY_B)

  device.send(uinput.EV_KEY, uinput.KEY_A, 1) # press
  device.send(uinput.EV_KEY, uinput.KEY_A, 0) # release
  device.send(uinput.EV_KEY, uinput.KEY_B, 1) # press
  device.send(uinput.EV_KEY, uinput.KEY_B, 0) # release
  device.send(uinput.EV_KEY, uinput.KEY_B, 1) # press
  device.send(uinput.EV_KEY, uinput.KEY_B, 0) # release
  device.send(uinput.EV_KEY, uinput.KEY_A, 1) # press
  device.send(uinput.EV_KEY, uinput.KEY_A, 0) # release

In other words, uinput.Capabilities descendants provide just higher level API
for the uinput.Device.

Downloading
===========

- Tarball is available at: http://codegrove.org/python-uinput/0.3/python-uinput-0.3.tar.gz
- Latest sources from public git-repository: http://github.com/tuos/python-uinput/ ::

    git clone git://github.com/tuos/python-uinput.git

Installing
==========

The install-procedure adheres the "standard"::

  python setup build && sudo python setup install

Bug reporting
=============

Report bugs by sending email to tuos@codegrove.org or by opening an issue
at http://github.com/tuos/python-uinput/issues .