Metadata-Version: 2.1
Name: xkit
Version: 0.5.1
Summary: Library for the manipulation of the xorg.conf
Home-page: https://launchpad.net/x-kit
Author: Alberto Milone
Author-email: albertomilone@alice.it
Maintainer: Plamen Kolev
Maintainer-email: multyrealm@gmail.com
License: GPL v2 or later
Keywords: xorg xorg.conf xorg.conf.d
Platform: UNKNOWN
Classifier: Development Status :: 7 - Inactive
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6

X-Kit - xorg.conf manipulator, parser and validator
===================================================

X-Kit is a set of libraries to manipulate the xorg.conf. It was written with the
following aims in mind:

* Simple API.
* Easy to extend.
* Dependent only on Python (no external libraries)

X-Kit was designed to be distribution agnostic so as to provide a standard way
to manipulate the content of the xorg.conf from different applications.

Structure
---------

The Parser class in xorgparser.py is the core of the project since it includes
all the main methods for the manipulation and validation of the xorg.conf. The
XUtils subclass in xutils.py contains some not fundamental but still quite
useful methods mainly focussed on dealing with the several relationships between
the different sections of the xorg.conf.

The most important attribute of the Parser class is globaldict i.e. a dictionary
which contains a structured representation of the content of the xorg.conf. The
section types are its keys (see self.sections).  "SubSection" is treated as
a special section type.

As regards normal sections, the value assigned to each key of globaldict is
another dictionary which has the position of each section as a key.

.. code:: python

    self.globaldict = {
                       'Device': {
                                  0: [option1, option2, etc.],
                                  1: [...], etc.
                                 },
                       'Screen': {
                                  0: [option1, option2, etc.],
                                  1: [...], etc.},
                       etc.
                      }

For example ``self.globaldict['Device'][0]`` corresponds to a list of the
options available in the 1st "Device" section of the xorg.conf.

SubSections are treated differently from sections:

.. code:: python

    self.globaldict = {
                       'Device': {
                                  0: [option1, option2, etc.],
                                  1: [...], etc.
                                 },
                       'Screen': {
                                  0: [option1, option2, etc.],
                                  1: [...], etc.
                                 },

                       'SubSection': {
                                      0: {
                                          'section': 'Screen',
                                          'identifier': 'Display',
                                          'position': 0,
                                          'options': [option1, option2, etc.]
                                         },
                                      1: {...}, etc.
                                     },
                      }

In this case they keys of ``self.globaldict['Device']`` (i.e. 0, 1, etc.)
represent the position of the "Display" SubSection inside the "Screen" section.
The following are the keys of ``self.globaldict['Device'][0]``, ``[1]``, etc.:

- section    = the section in which the SubSection is located (e.g. "Screen")
- position   = the position of the section (e.g. "Screen") in the xorg.conf e.g.
               position would be 0 if the SubSection was located in the 1st
               "Screen" section of the xorg.conf (whose options are stored in
               ``self.globaldict['Screen'][0]``)
- identifier = the name of the SubSection (e.g. "Display")
- options    = a list with the options available in the SubSection

Another important concept to consider is that each line in each section is
considered as an option. No more than one instance of the same option should be
found in the same section (e.g. Driver "nv" and Driver "vesa" cannot cohexist in
the same Device section). References (e.g. Screen "Default Screen" in the Device
section), however, are treated as a special kind of option and more than one
reference of the same kind can be found in the same section (e.g. Screen "Screen
1" and Screen "Screen 2" in the same ServerLayout section)

IMPORTANT NOTE ON CASE SENSITIVE SECTION NAMES: the parser will accept sections
in either lowercase and uppercase when reading a configuration file. The same is
not true when the methods are called and the name of the section is passed as
a parameter, as in such case the names of the sections must be exactly as in
``self.sections`` i.e. the 1st letter of each word which is part of the name
must be in uppercase.  E.g.:

- invalid: "screen", "serverlayout", "Serverlayout"
- valid:   "Screen", "ServerLayout"

If you don't respect this rule, a KeyError will be raised.

For further information you can have a look at the documentation by typing:

.. code:: python

    import XKit.xutils
    help(XKit.xutils)


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

All that X-Kit needs is just a working Python installation. No external modules
are required.

How to install X-Kit
--------------------

If you use Ubuntu you should be able to find the source package on Launchpad
(see the "Development" section of this file) and in the Ubuntu repository
(starting from Ubuntu 8.10).

The easiest way to install it is by typing the following command as root:

.. code:: sh

    ./setup.py install

Test suite
----------

Every new feature and bug fix should first get a test case, to maintain nearly
100% code coverage. You can either run the following test files separately:

    tests/0-test.py = unit test for xorgparser.py

    tests/1-test.py = unit test for xutils.py

or simply run them all with the following file:

    tests/run

The following file contains the path to the source xorg.conf which will be used
for testing ("inputFile") and the directory ("outputDir") in which the results
of the tests will be stored ("xkittest-0.txt" and "xkittest-1.txt" for 0-test.py
and 1-test.py respectively).

By default inputFile is set to the xorg.conf file in tests/ and outputDir is set
to tests/.

It is possible to change the default values of inputFile and outputDir by
passing parameters to the "tests/run" file:

The only accepted (optional) parameters are:

      -o, --output=<dirname>    the directory where the results
                                of the tests are saved.
      -i, --input=<filename>    the xorg.conf used for the tests.
      -h, --help                help page.

Launching "tests/run" without parameters will make it use the
default values for inputFile and outputDir.

Development
-----------

Development of trunk and the Ubuntu implementation takes place in the following
"x-kit" Launchpad project:

    https://launchpad.net/x-kit

This is the place to report bugs, do translations, host your own branches (if
you wish to do so), and download upstream releases.

Alberto Milone (tseliot) <albertomilone@alice.it>


