README.rst
1The Python X Library
2====================
3
4|Build Status| |codecov.io| |Code Health|
5
6`Homepage`_ | `Releases`_ | `Changelog`_
7
8Copyright
9~~~~~~~~~
10
11The main part of the code is
12
13::
14
15 Copyright (C) 2000-2002 Peter Liljenberg
16
17Some contributed code is copyrighted by `the contributors <Contributors_>`_,
18in these cases that is indicated in the source files in question.
19
20The Python X Library is released under LGPL v2.1 or later (since 2016),
21see the file LICENSE for details. 0.15rc1 and before were released under
22GPL v2.
23
24Requirements
25~~~~~~~~~~~~
26
27The Python X Library requires Python 2.7 or newer. It has been tested to
28various extents with Python 2.7 and 3.3 through 3.6.
29
30Installation
31~~~~~~~~~~~~
32
33The Python Xlib uses the standard setuptools package, to install run
34this command:
35
36::
37
38 python setup.py install
39
40See the command help for details: ``python setup.py install -h``.
41
42Alternatively, you can run programs from the distribution directory, or
43change the module path in programs.
44
45There's a simple example program, implemented twice using both the
46high-level interface and the low-level protocol.
47
48Introduction
49~~~~~~~~~~~~
50
51The Python X Library is intended to be a fully functional X client
52library for Python programs. It is written entirely in Python, in
53contrast to earlier X libraries for Python (the ancient X extension and
54the newer plxlib) which were interfaces to the C Xlib.
55
56This is possible to do since X client programs communicate with the X
57server via the X protocol. The communication takes place over TCP/IP,
58Unix sockets, DECnet or any other streaming network protocol. The C Xlib
59is merely an interface to this protocol, providing functions suitable
60for a C environment.
61
62There are three advantages of implementing a pure Python library:
63
64- Integration: The library can make use of the wonderful object system
65 in Python, providing an easy-to-use class hierarchy.
66
67- Portability: The library will be usable on (almost) any computer
68 which have Python installed. A C interface could be problematic to
69 port to non-Unix systems, such as MS Windows or OpenVMS.
70
71- Maintainability: It is much easier to develop and debug native Python
72 modules than modules written in C.
73
74Documentation
75~~~~~~~~~~~~~
76
77The reference manual is not finished by far, but is probably still useful. It
78can be `browsed online <http://python-xlib.sourceforge.net/doc/html/index.html>`__.
79
80There are also some `example programs <Examples_>`_ and, of course,
81`the standard X11 documentation <http://tronche.com/gui/x/xlib/>`__ applies.
82
83
84Project status
85~~~~~~~~~~~~~~
86
87The low-level protocol is complete, implementing client-side X11R6. The
88high-level object oriented interface is also fully functional. It is
89possible to write client applications with the library. Currently, the
90only real application using Python Xlib is the window manager PLWM,
91starting with version 2.0.
92
93There is a resource database implementation, ICCCM support and a
94framework for adding X extension code. Several extensions have been
95implemented; (RECORD, SHAPE, Xinerama, Composite, RANDR, and XTEST)
96patches for additions are very welcome.
97
98There are most likely still bugs, but the library is at least stable
99enough to run PLWM. A continuously bigger part of the library is covered
100by regression tests, improving stability.
101
102The documentation is still quite rudimentary, but should be of some help
103for people programming with the Xlib. X beginners should first find some
104general texts on X. A very good starting point is
105http://www.rahul.net/kenton/xsites.html
106
107See the file TODO for a detailed list of what is missing, approximately
108ordered by importance.
109
110.. _Homepage: https://github.com/python-xlib/python-xlib
111.. _Releases: https://github.com/python-xlib/python-xlib/releases
112.. _Changelog: https://github.com/python-xlib/python-xlib/tree/master/CHANGELOG.md
113.. _Contributors: https://github.com/python-xlib/python-xlib/graphs/contributors
114.. _Examples: https://github.com/python-xlib/python-xlib/tree/master/examples
115
116.. |Build Status| image:: https://travis-ci.org/python-xlib/python-xlib.svg?branch=master
117 :target: https://travis-ci.org/python-xlib/python-xlib
118.. |codecov.io| image:: https://codecov.io/github/python-xlib/python-xlib/coverage.svg?branch=master
119 :target: https://codecov.io/github/python-xlib/python-xlib?branch=master
120.. |Code Health| image:: https://landscape.io/github/python-xlib/python-xlib/master/landscape.svg?style=flat
121 :target: https://landscape.io/github/python-xlib/python-xlib/master
122
