pywayland
=========

|ci| |coveralls| |docs|

PyWayland provides a wrapper to the ``libwayland`` library using the CFFI
library to provide access to the Wayland library calls and written in pure
Python.

Below is outlined some of the basics of PyWayland and how to get up and
running.  For more help, see the `full documentation`_.

.. _full documentation: http://pywayland.readthedocs.org/

Current Release
---------------

PyWayland is still in a developmental state.  An current version is available
on the `cheese shop`_.  Current development versions can be obtained from the
`git repository`_, feedback, as well as any bug reports or fixes are highly
appreciated.

.. _cheese shop: https://pypi.python.org/pypi/pywayland/
.. _git repository: https://github.com/flacjacket/pywayland/

Dependencies
------------

Installing PyWayland requires the Wayland library and the headers to be installed.

PyWayland requires the cffi_ package to be installed. See the `installation guide`_
for more information on installing required dependencies

.. _cffi: https://cffi.readthedocs.org/
.. _installation guide: http://pywayland.readthedocs.org/en/latest/install.html#installation

Installing
----------

Installation can be done through pip to pull the most recently tagged release.
To see instructions on running from source, see the relevant documentation on
`installing from source`_.

.. _installing from source: http://pywayland.readthedocs.org/en/latest/install.html#installing-from-source

Building Wayland protocols
--------------------------

In order to run from source, you will need to generate the interfaces to the
Wayland protocol objects as defined in the wayland.xml file.  By default, this
file will be located in ``/usr/share/wayland/wayland.xml``.  In this case, the
protocol files can be generated by the scanner module::

    $ python -m pywayland.scanner

If ``pywayland._ffi`` is not built yet, run the scanner as a top-level module
from the ``./pywayland`` directory instead::

    $ cd pywayland
    $ python -m scanner

See the help for this module to use non-default locations for the input and
output of the scanner.

The scanner is installed as a script ``pywayland-scanner`` when PyWayland is
installed.  See ``pywayland-scanner -h`` for more information.

Running Tests
-------------

PyWayland implements a (currently limited) test-suite in ``./tests``.  The
tests can be run through ``pytest``.  Be sure you build the protocol files (see
`Building Wayland protocols`_) before running the tests.

.. |ci| image:: https://github.com/flacjacket/pywayland/actions/workflows/ci.yml/badge.svg
    :target: https://github.com/flacjacket/pywayland/actions
    :alt: Build Status
.. |coveralls| image:: https://coveralls.io/repos/flacjacket/pywayland/badge.svg
    :target: https://coveralls.io/r/flacjacket/pywayland
    :alt: Build Coverage
.. |docs| image:: https://readthedocs.org/projects/pywayland/badge/?version=latest
    :target: https://pywayland.readthedocs.io/en/latest/
    :alt: Documentation Status
