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:
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.
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:
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:
__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.
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:
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.
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.
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 itself is a namespace. The kitchen sdist (tarball) provides certain useful subpackages.
See also
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’.
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.
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
Addon packages are very similar to subpackages integrated into the kitchen sdist. This section just lists some of the differences to watch out for.
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'],
# [...]
)
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
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.
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)