Conventions for contributing to kitchen

Style

• Strive to be PEP 8 compliant
• Run :command:`pylint ` over the code and try to resolve most of its nitpicking

Python 2.3 compatibility

At the moment, we’re supporting python-2.3 and above. Understand that there’s a lot of python features that we cannot use because of this.

Sometimes modules in the python standard library can be added to kitchen so that they’re available. When we do that we need to be careful of several things:

1. Keep the module in sync with the version in the python-2.x trunk. Use maintainers/sync-copied-files.py for this.
2. Sync the unittests as well as the module.
3. Be aware that not all modules are written to remain compatible with Python-2.3 and might use python language features that were not present then (generator expressions, relative imports, decorators, with, try: with both except: and finally:, etc) These are not good candidates for importing into kitchen as they require more work to keep synced.

Unittests

• At least smoketest your code (make sure a function will return expected values for one set of inputs).

• Note that even 100% coverage is not a guarantee of working code! Good tests will realize that you need to also give multiple inputs that test the code paths of called functions that are outside of your code. Example:

  def to_unicode(msg, encoding='utf8', errors='replace'):
      return unicode(msg, encoding, errors)
  
  # Smoketest only.  This will give 100% coverage for your code (it
  # tests all of the code inside of to_unicode) but it leaves a lot of
  # room for errors as it doesn't test all combinations of arguments
  # that are then passed to the unicode() function.
  
  tools.ok_(to_unicode('abc') == u'abc')
  
  # Better -- tests now cover non-ascii characters and that error conditions
  # occur properly.  There's a lot of other permutations that can be
  # added along these same lines.
  tools.ok_(to_unicode(u'café', 'utf8', 'replace'))
  tools.assert_raises(UnicodeError, to_unicode, [u'cafè ñunru'.encode('latin1')])
  

• We’re using nose for unittesting. Rather than depend on unittest2 functionality, use the functions that nose provides.

• Remember to maintain python-2.3 compatibility even in unittests.

Docstrings and documentation

We use sphinx to build our documentation. We use the sphinx autodoc extension to pull docstrings out of the modules for API documentation. This means that docstrings for subpackages and modules should follow a certain pattern. The general structure is:

• Introductory material about a module in the module’s top level docstring.
  • Introductory material should begin with a level two title: an overbar and underbar of ‘-‘.
• docstrings for every function.
  • The first line is a short summary of what the function does
  • This is followed by a blank line
  • The next lines are a field list <http://sphinx.pocoo.org/markup/desc.html#info-field-lists>_ giving information about the function’s signature. We use the keywords: arg, kwarg, raises, returns, and sometimes rtype. Use these to describe all arguments, key word arguments, exceptions raised, and return values using these.
    • Parameters that are kwarg should specify what their default behaviour is.

Kitchen versioning

Currently the kitchen library is in early stages of development. While we’re in this state, the main kitchen library uses the following pattern for version information:

• Versions look like this::

  __version_info__ = ((0, 1, 2),) __version__ = ‘0.1.2’

• The Major version number remains at 0 until we decide to make the first 1.0 release of kitchen. At that point, we’re declaring that we have some confidence that we won’t need to break backwards compatibility for a while.

• The Minor version increments for any backwards incompatible API changes. When this is updated, we reset micro to zero.

• The Micro version increments for any other changes (backwards compatible API changes, pure bugfixes, etc).

Note

Versioning is only updated for releases that generate sdists and new uploads to the download directory. Usually we update the version information for the library just before release. By contrast, we update kitchen Versioning when an API change is made. When in doubt, look at the version information in the last release.

I18N

All strings that are used as feedback for users need to be translated. kitchen sets up several functions for this. _() is used for marking things that are shown to users via print, GUIs, or other “standard” methods. Strings for exceptions are marked with b_(). This function returns a byte str which is needed for use with exceptions:

from kitchen import _, b_

def print_message(msg, username):
    print _('%(user)s, your message of the day is:  %(message)s') % {
            'message': msg, 'user': username}

    raise Exception b_('Test message')

This serves several purposes:

• It marks the strings to be extracted by an xgettext-like program.
• _() is a function that will substitute available translations at runtime.

Note

By using the %()s with dict style of string formatting, we make this string friendly to translators that may need to reorder the variables when they’re translating the string.

paver <http://www.blueskyonmars.com/projects/paver/>_ and babel <http://babel.edgewall.org/>_ are used to extract the strings.

API updates

Kitchen strives to have a long deprecation cycle so that people have time to switch away from any APIs that we decide to discard. Discarded APIs should raise a DeprecationWarning and clearly state in the warning message and the docstring how to convert old code to use the new interface. An example of deprecating a function:

import warnings

from kitchen import _
from  kitchen.text.converters import to_bytes, to_unicode
from kitchen.text.new_module import new_function

def old_function(param):
    '''**Deprecated**

    This function is deprecated.  Use
    :func:`kitchen.text.new_module.new_function` instead. If you want
    unicode strngs as output, switch to::

        >>> from kitchen.text.new_module import new_function
        >>> output = new_function(param)

    If you want byte strings, use::

        >>> from kitchen.text.new_module import new_function
        >>> from kitchen.text.converters import to_bytes
        >>> output = to_bytes(new_function(param))
    '''
    warnings.warn(_('kitchen.text.old_function is deprecated.  Use'
        ' kitchen.text.new_module.new_function instead'),
        DeprecationWarning, stacklevel=2)

    as_unicode = isinstance(param, unicode)
    message = new_function(to_unicode(param))
    if not as_unicode:
        message = to_bytes(message)
    return message

If a particular API change is very intrusive, it may be better to create a new version of the subpackage and ship both the old version and the new version.

NEWS file

Update the NEWS file when you make a change that will be visible to the users. This is not a ChangeLog file so we don’t need to list absolutely everything but it should give the user an idea of how this version differs from prior versions. API changes should be listed here explicitly. bugfixes can be more general:

-----
0.2.0
-----
* Relicense to LGPLv2+
* Add kitchen.text.format module with the following functions:
  textual_width, textual_width_chop.
* Rename the kitchen.text.utils module to kitchen.text.misc.  use of the
  old names is deprecated but still available.
* bugfixes applied to kitchen.pycompat24.defaultdict that fixes some
  tracebacks

Kitchen subpackages

Kitchen itself is a namespace. The kitchen sdist (tarball) provides certain useful subpackages.

See also

Kitchen addon packages

For information about subpackages not distributed in the kitchen sdist that install into the kitchen namespace.

Versioning

Each subpackage should have its own version information which is independent of the other kitchen subpackages and the main kitchen library version. This is used so that code that depends on kitchen APIs can check the version information. The standard way to do this is to put something like this in the subpackage’s __init__.py:

from kitchen.versioning import version_tuple_to_string

__version_info__ = ((1, 0, 0),)
__version__ = version_tuple_to_string(__version_info__)

__version_info__ is documented in kitchen.versioning. The values of the first tuple should describe API changes to the module. There are at least three numbers present in the tuple: (Major, minor, micro). The major version number is for backwards incompatible changes (For instance, removing a function, or adding a new mandatory argument to a function). Whenever one of these occurs, you should increment the major number and reset minor and micro to zero. The second number is the minor version. Anytime new but backwards compatible changes are introduced this number should be incremented and the micro version number reset to zero. The micro version should be incremented when a change is made that does not change the API at all. This is a common case for bugfixes, for instance.

Version information beyond the first three parts of the first tuple may be useful for versioning but semantically have similar meaning to the micro version.

Note

We update the __version_info__ tuple when the API is updated. This way there’s less chance of forgetting to update the API version when a new release is made. However, we try to only increment the version numbers a single step for any release. So if kitchen-0.1.0 has kitchen.text.__version__ == ‘1.0.1’, kitchen-0.1.1 should have kitchen.text.__version__ == ‘1.0.2’ or ‘1.1.0’ or ‘2.0.0’.

Criteria for subpackages in kitchen

Supackages within kitchen should meet these criteria:

• Generally useful or needed for other pieces of kitchen.

• No mandatory requirements outside of the python standard library.

  • Optional requirements from outside the python standard library are allowed. Things with mandatory requirements are better placed in kitchen addon packages

• Somewhat API stable – this is not a hard requirement. We can change the kitchen api. However, it is better not to as people may come to depend on it.

  See also

  API Updates

Kitchen addon packages

Addon packages are very similar to subpackages integrated into the kitchen sdist. This section just lists some of the differences to watch out for.

setup.py

Your setup.py should contain entries like this:

# It's suggested to use a dotted name like this so the package is easily
# findable on pypi:
setup(name='kitchen.config',
    # Include kitchen in the keywords, again, for searching on pypi
    keywords=['kitchen', 'configuration'],
    # This package lives in the directory kitchen/config
    packages=['kitchen.config'],
    # [...]
)

Package directory layout

Create a kitchen directory in the toplevel. Place the addon subpackage in there. For example:

./                     <== toplevel with README, setup.py, NEWS, etc
kitchen/
kitchen/__init__.py
kitchen/config/        <== subpackage directory
kitchen/config/__init__.py

Fake kitchen module

The :file::__init__.py in the kitchen directory is special. It won’t be installed. It just needs to pull in the kitchen from the system so that you are able to test your module. You should be able to use this boilerplate:

# Fake module.  This is not installed,  It's just made to import the real
# kitchen modules for testing this module
import pkgutil

# Extend the __path__ with everything in the real kitchen module
__path__ = pkgutil.extend_path(__path__, __name__)

Note

kitchen needs to be findable by python for this to work. Installed in the site-packages directory or adding it to the PYTHONPATH will work.

Your unittests should now be able to find both your submodule and the main kitchen module.

Versioning

It is recommended that addon packages version similarly to Versioning. The __version_info__ and __version__ strings can be changed independently of the version exposed by setup.py so that you have both an API version (__version_info__) and release version that’s easier for people to parse. However, you aren’t required to do this and you could follow a different methodology if you want (for instance, Kitchen versioning)