===================
Kitchen.core Module
===================

:Author: Toshio Kuratomi
:Date: 9 May 2010
:Version: 0.1.x

The Kitchen module provides a python API for all sorts of little useful
snippets of code that everybody ends up writing for their projects but never
seem big enough to build an independent release.  Use kitchen and stop cutting
and pasting that code over and over.

.. contents::

-------
License
-------

This python module is distributed under the terms of the GNU General
Public License Version 2 or later.

.. note:: Currently working on relicensing some of this code to the LGPLv2+.
    Once that is done, the library will be licensed in whole as the GNU
    Lesser General Public License Version 2 or later.  New contributions to the
    library should be contributed under the LGPLv2+

    The files with GPLv2+ code are:

    * kitchen/text/utf8.py
    * i18n/__init__.py

.. note:: Some parts of this module are licensed under terms less restrictive
    than the GPL.  If you separate these files from the work as a whole you are
    allowed to use them under the less restrictive licenses.  The following is
    a list of the files that are known:

    :subprocess.py: licensed under the Python 2 license by the PSF
        http://www.python.org/download/releases/2.4/license/
    :test_subprocess.py: Python Software Foundation License Version 2
        http://www.python.org/download/releases/2.7/license/
    :tests/* other than test_subprocess.py: LGPLv2+
    :files directly contained in kitchen/: LGPLv2+
    :kitchen/pycompat24/*: LGPLv2+
    :kitchen/versioning/*: LGPLv2+
    :kitchen/text/* except for utf8.py: LGPLv2+

------------
Requirements
------------

kitchen.core requires

:python: 2.3.1 or later

Soft Requirements
=================

If found, these libraries will be used to make the implementation of soemthing
better in some way.  If they are not present, the API that they enable will
still exist but may function in a different manner.

:chardet_: Used in kitchen.text.xml.guess_encoding__to_xml() to help guess encoding of
    byte strings being converted.  If not present, unknown encodings will be
    converted as if they were latin1.

.. _chardet:: http://chardet.feedparser.org/

---------------------------
Other Recommended Libraries
---------------------------

These libraries implement commonly used functionality that everyone seems to
invent.  Rather than reinvent their wheel, I simply list the things that they
do well for now.  Perhaps if people can't find them normally, I'll add them as
requirements in setup.py or link them into kitchen's namespace.  For now, I
just mention them here:

:bunch_: Bunch is a dictionary that you can use attribute lookup as well as
    bracket notation to access.  Setting it apart from most homebrewed
    implementations is the bunchify() function which will descend nested
    structures of lists nad dicts, transforming the dicts to Bunch's.

.. _bunch:: http://pypi.python.org/pypi/bunch/

---------------------
Building, and testing
---------------------

Testing
=======

You can run the unittests with this command::
    nosetests --with-coverage --cover-package kitchen
