Commits

Andriy Kornatskyy committed 265394e

Working on documentation

Comments (0)

Files changed (13)

 Install
 -------
 
-`wheezy.core`_ requires `python`_ version 2.4 to 2.7 or 3.2.  It
-is independent of operating system. You can install it using
-`setuptools`_::
+:ref:`wheezy.core` requires `python`_ version 2.4 to 2.7 or 3.2.
+It is independent of operating system. You can install it from `pypi`_ 
+site using `setuptools`_::
 
-    easy_install wheezy.core
+    $ easy_install wheezy.core
+    
+If you are using `virtualenv`_::
 
+    $ virtualenv env
+    $ env/bin/easy_install wheezy.core
 
 Develop
 -------
 
-Get the `source code`_ using `mercurial`_::
+You can get the `source code`_ using `mercurial`_::
 
-    hg clone https://bitbucket.org/akorn/wheezy.core
-    cd wheezy.core
+    $ hg clone http://bitbucket.org/akorn/wheezy.core
+    $ cd wheezy.core
 
-Prepare virtualenv environment in *env* directory and run all
-tests for python2.6 (default)::
+Prepare `virtualenv`_ environment in *env* directory ::
 
-    make env test VERSION=2.6
+    $ make env
 
-doctests can be run with python3.2::
+... and run all tests::
 
-    make env doctest-cover VERSION=3.2
+    $ make test
+
+You can read how to compile from source code different versions of 
+`python`_ in the `article`_ published on `mind reference`_ blog.
+
+You can run certain make targets with specific python version. Here
+we are going to run `doctest`_ with python3.2::
+
+    $ make env doctest-cover VERSION=3.2
+    
+Generate documentation with `sphinx`_::
+
+	$ make doc
 
 If you run into any issue or have comments, go ahead and add on
 `bitbucket`_.
 
-User Guide and Examples
------------------------
-
-Please see the `user guide`_ and `examples`_ for more
-information.
-
-.. _`wheezy.core`: http://pypi.python.org/pypi/wheezy.core
+.. _`pypi`: http://pypi.python.org/pypi/wheezy.core
 .. _`python`: http://www.python.org
 .. _`setuptools`: http://pypi.python.org/pypi/setuptools
-.. _`documented`: http://packages.python.org/wheezy.core
-.. _`examples`: https://bitbucket.org/akorn/wheezy.core/src/tip/demos/
-.. _`bitbucket`: https://bitbucket.org/akorn/wheezy.core
-.. _`source code`: https://bitbucket.org/akorn/wheezy.core/src
+.. _`bitbucket`: http://bitbucket.org/akorn/wheezy.core/issues
+.. _`source code`: http://bitbucket.org/akorn/wheezy.core/src
 .. _`mercurial`: http://mercurial.selenic.com/
-.. _`user guide`: http://packages.python.org/wheezy.core/userguide.html
+.. _`virtualenv`: http://pypi.python.org/pypi/virtualenv
+.. _`article`: http://mindref.blogspot.com/2011/09/compile-python-from-source.html
+.. _`mind reference`: http://mindref.blogspot.com/
+.. _`doctest`: http://docs.python.org/library/doctest.html
+.. _`sphinx`: http://sphinx.pocoo.org/
+# -*- coding: utf-8 -*-
+#
+# wheezy.core documentation build configuration file, created by
+# sphinx-quickstart on Fri Sep  9 20:36:50 2011.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+sys.path.extend([
+	os.path.abspath(os.path.join('..', 'src'))
+])
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = [
+    'sphinx.ext.autodoc', 'sphinx.ext.doctest',
+    'sphinx.ext.coverage', 'sphinx.ext.viewcode'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'wheezy.core'
+copyright = u'2011, Andriy Kornatskyy'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.1'
+# The full version, including alpha/beta/rc tags.
+release = '0.1'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'colorful'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# The style sheet to use for HTML pages.
+html_style = 'style.css'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+html_theme_options = {
+    'footerbgcolor': '#FFF',
+    'footertextcolor': '#000',
+    'sidebarbgcolor': '#FFF',
+    'sidebartextcolor': '#4d8cbf',
+    'sidebarlinkcolor': '#216093',
+    'relbarbgcolor': '#FFF',
+    'relbartextcolor': '#000',
+    'relbarlinkcolor': '#216093',
+    'bgcolor': '#FFF',
+    'textcolor': '#000',
+    'linkcolor': '#216093',
+    'visitedlinkcolor': '#216093',
+    'headbgcolor': '#FFF',
+    'headtextcolor': '#4d8cbf',
+    'codebgcolor': '#FFF',
+    'codetextcolor': '#060',
+    'bodyfont': 'Georgia, serif',
+    'headfont': 'Calibri, sans-serif',
+	'stickysidebar': True,
+	'externalrefs': True
+}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# '<project> v<release> documentation'.
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named 'default.css' will overwrite the builtin 'default.css'.
+html_static_path = ['static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, 'Created using Sphinx' is shown in the HTML footer. Default is True.
+html_show_sphinx = False
+
+# If true, '(C) Copyright ...' is shown in the HTML footer. Default is True.
+html_show_copyright = False
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. '.xhtml').
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'wheezy.coredoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'wheezy.core.tex', u'wheezy.core Documentation',
+   u'Andriy Kornatskyy', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For 'manual' documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'wheezy.core', u'wheezy.core Documentation',
+     [u'Andriy Kornatskyy'], 1)
+]
+
+Examples
+========
+
+We start with a simple example. Before we proceed 
+let setup `virtualenv`_ environment::
+
+    $ virtualenv env
+    $ env/bin/easy_install wheezy.core
+
+
+.. _`virtualenv`: http://pypi.python.org/pypi/virtualenv

doc/gettingstarted.rst

+
+Getting Started
+===============
+
+Install
+-------
+
+:ref:`wheezy.core` requires `python`_ version 2.4 to 2.7 or 3.2.
+It is independent of operating system. You can install it from `pypi`_ 
+site using `setuptools`_::
+
+    $ easy_install wheezy.core
+    
+If you are using `virtualenv`_::
+
+    $ virtualenv env
+    $ env/bin/easy_install wheezy.core
+
+Develop
+-------
+
+You can get the `source code`_ using `mercurial`_::
+
+    $ hg clone http://bitbucket.org/akorn/wheezy.core
+    $ cd wheezy.core
+
+Prepare `virtualenv`_ environment in *env* directory ::
+
+    $ make env
+
+... and run all tests::
+
+    $ make test
+
+You can read how to compile from source code different versions of 
+`python`_ in the `article`_ published on `mind reference`_ blog.
+
+You can run certain make targets with specific python version. Here
+we are going to run `doctest`_ with python3.2::
+
+    $ make env doctest-cover VERSION=3.2
+    
+Generate documentation with `sphinx`_::
+
+	$ make doc
+
+If you run into any issue or have comments, go ahead and add on
+`bitbucket`_.
+
+.. _`pypi`: http://pypi.python.org/pypi/wheezy.core
+.. _`python`: http://www.python.org
+.. _`setuptools`: http://pypi.python.org/pypi/setuptools
+.. _`bitbucket`: http://bitbucket.org/akorn/wheezy.core/issues
+.. _`source code`: http://bitbucket.org/akorn/wheezy.core/src
+.. _`mercurial`: http://mercurial.selenic.com/
+.. _`virtualenv`: http://pypi.python.org/pypi/virtualenv
+.. _`article`: http://mindref.blogspot.com/2011/09/compile-python-from-source.html
+.. _`mind reference`: http://mindref.blogspot.com/
+.. _`doctest`: http://docs.python.org/library/doctest.html
+.. _`sphinx`: http://sphinx.pocoo.org/
+.. _`wheezy.core`:
+
+Wheezy Core
+===========
+
+Introduction
+------------
+
+:ref:`wheezy.core` is a `python`_ package written in pure Python code. 
+It is a lightweight core library.
+
+It is optimized for performance, well tested and documented.
+
+Resources:
+
+* `source code`_, `examples`_ and `issues`_ tracker are available
+  on `bitbucket`_
+* `documentation`_
+* `eggs`_ on `pypi`_
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 2
+
+   gettingstarted
+   examples
+   userguide
+   modules
+
+.. _`python`: http://www.python.org
+.. _`source code`: http://bitbucket.org/akorn/wheezy.core/src
+.. _`bitbucket`: http://bitbucket.org/akorn/wheezy.core
+.. _`issues`: http://bitbucket.org/akorn/wheezy.core/issues
+.. _`documentation`: http://packages.python.org/wheezy.core
+.. _`examples`: http://bitbucket.org/akorn/wheezy.core/src/tip/demos
+.. _`pypi`: http://pypi.python.org
+.. _`eggs`: http://pypi.python.org/pypi/wheezy.core
+Modules
+=======
+
+wheezy.core
+-----------
+
+.. automodule:: wheezy.core
+   :members:
+
+wheezy.core.collections
+-----------------------
+
+.. automodule:: wheezy.core.collections
+   :members:
+
+wheezy.core.config
+------------------
+
+.. automodule:: wheezy.core.config
+   :members:
+
+wheezy.core.datetime
+--------------------
+
+.. automodule:: wheezy.core.datetime
+   :members:
+
+wheezy.core.descriptors
+-----------------------
+
+.. automodule:: wheezy.core.descriptors
+   :members:
+
+wheezy.core.i18n
+----------------
+
+.. automodule:: wheezy.core.i18n
+   :members:
+
+wheezy.core.introspection
+-------------------------
+
+.. automodule:: wheezy.core.introspection
+   :members:
+
+wheezy.core.url
+---------------
+
+.. automodule:: wheezy.core.url
+   :members:
+
+wheezy.core.uuid
+----------------
+
+.. automodule:: wheezy.core.uuid
+   :members:

doc/static/style.css

+@import url("default.css");
+
+div.body h1,
+div.body h2,
+div.body h3,
+div.body h4,
+div.body h5,
+div.body h6,
+div.sphinxsidebar h3,
+div.sphinxsidebar h4 {
+    font-weight: bold;
+    border-bottom: none;
+}
+
+pre {
+    line-height: 14pt;
+    margin: 17pt;
+    padding-left: 1em;
+    border: none;
+    border-left: 3px solid #EE9816;
+    font-family: 'Consolas','Deja Vu Sans Mono','Bitstream Vera Sans Mono',monospace;
+    font-size: 0.9em;
+}
+
+div.body p, div.body dd, div.body li {
+    text-align: left;
+}
+
+.highlight {
+    background: #FFF !important;
+}
+
+th.field-name {
+    background: #FFF;
+}
+
+div.related {
+    position: fixed;
+}
+
+div.body {
+    top: 30px;
+    bottom: 0;
+    right: 0;
+    left: 230px;
+    margin: 0;
+    position: fixed;
+    overflow: auto;
+    height: auto;
+}
+
+div.related, div.sphinxsidebar {
+    font-family: Calibri, sans-serif;
+}

doc/userguide.rst

+
+User Guide
+==========
+
+:ref:`wheezy.core` comes with extensions to the following features:
+
+* collections
+* config
+* datetime
+* descriptors
+* i18n
+* introspection
+* url
+* uuid
+
+collections
+-----------
+
+The :py:mod:`~wheezy.core.collections` module contains types and functions 
+that define various collections, iterators and algorithms.
+
+Classes:
+
+* :py:class:`~wheezy.core.collections.ItemAdapter` - adapts 
+  ``defaultdict(list)``.__getitem__ accessor to return item at ``index`` 
+  from the list. If ``key`` is not found return None.
+* :py:class:`~wheezy.core.collections.attrdict` - a dictionary with 
+  attribute-style access. Maps attribute access to dictionary.
+* :py:class:`~wheezy.core.collections.defaultattrdict` - a dictionary with 
+  attribute-style access. Maps attribute access to dictionary. Extends 
+  ``defaultdict``.
+  
+Functions:
+
+* :py:meth:`~wheezy.core.collections.first_item_adapter` - adapts 
+  ``defaultdict(list)``.__getitem__  accessor to return the first item from 
+  the list. 
+* :py:meth:`~wheezy.core.collections.last_item_adapter` - adapts 
+  ``defaultdict(list)``.__getitem__  accessor to return the last item from 
+  the list.
+* :py:meth:`~wheezy.core.collections.distinct` - returns generator for unique 
+  items in ``seq`` with preserved order.
+* :py:meth:`~wheezy.core.collections.gzip_iterator` - iterates over ``items`` 
+  and returns generator of gzipped items. Argument ``compress_level`` sets
+  compression level.
+
+config
+------
+
+:py:class:`~wheezy.core.config.Config` -  promotes ``options`` dict to 
+attributes. If an option can not be found in ``options``, tries to get it 
+from ``master``. ``master`` must have a requested option otherwise raises 
+error::
+
+    m = {'DEBUG': False}
+    c = Config(options={'DEBUG': True}, master=m)
+    assert True == c.DEBUG
+
+``master`` - object with dictionary or attribute style of access.
+
+datetime
+--------
+
+Represents an instant in time, typically expressed as a date and time of day.
+
+Classes:
+
+* :py:class:`~wheezy.core.datetime.utc` - defines UTC timezone. There are
+  two instances of the class: GMT and UTC.
+
+Functions:
+
+* :py:meth:`~wheezy.core.datetime.format_http_datetime` - formats datetime 
+  to a string following rfc1123 pattern::
+  
+    >>> from wheezy.core.datetime import UTC
+    >>> now = datetime(2011, 9, 19, 10, 45, 30, 0, UTC)
+    >>> format_http_datetime(now)
+    'Mon, 19 Sep 2011 10:45:30 GMT'
+
+* :py:meth:`~wheezy.core.datetime.parse_http_datetime` - parses a string 
+  in rfc1123 format to ``datetime``::
+  
+    >>> parse_http_datetime('Mon, 19 Sep 2011 10:45:30 GMT')
+    datetime.datetime(2011, 9, 19, 10, 45, 30)
+
+* :py:meth:`~wheezy.core.datetime.total_seconds` - returns a total number 
+  of seconds for the given time delta (``datetime.timedelta`` or ``int``)::
+  
+    >>> total_seconds(timedelta(hours=2))
+    7200
+
+i18n
+----
+
+Internationalisation is a process of adapting application to different 
+languages, regional differences and technical requirements.
+Internationalization is the process of designing a software application so 
+that it can be adapted to various languages and regions without engineering 
+changes.
+
+``gettext`` is an internationalization and localization (i18n) system commonly
+used for writing multilingual programs on Unix-like operating systems.
+
+:py:class:`~wheezy.core.i18n.TranslationsManager` - manages several languages 
+and translation domains. You can use method 
+:py:meth:`~wheezy.core.i18n.TranslationsManager.load` to load all available 
+languages and domains from the given directory (typically it is ``i18n``
+directory within our application root directory).
+
+Translations directory structure must follow ``gettext`` requirements (this
+this how it looks below ``i18n`` directory)::
+
+    {localedir}/{lang}/LC_MESSAGES/{domain}.mo
+    
+In order to generate .mo file from .po file::
+
+    $ msgfmt domain.po
+
+:py:class:`~wheezy.core.i18n.TranslationsManager` supports the following
+arguments in initialization:
+
+* ``directories`` - a list of directories that holds translations.
+* ``default_lang`` - a default language in translations. Defaults to ``en``.
+
+:py:class:`~wheezy.core.i18n.TranslationsManager` supports fallback mechanism.
+You can use :py:meth:`~wheezy.core.i18n.TranslationsManager.add_fallback`
+to adds fallback languages.
+
+    >>> from wheezy.core.i18n import TranslationsManager
+    >>> tm = TranslationsManager(['i18n'], default_lang='en')
+    >>> tm.add_fallback(('uk', 'ru'))
+    >>> tm.fallbacks
+    {'uk': ('uk', 'ru', 'en')}
+
+Default language is always appended to the fallback list.
+
+:py:class:`~wheezy.core.i18n.TranslationsManager` supports dictionary access
+that accepts a language code as a key. So the following represents all
+translations related to ``en`` language code::
+
+    lang = tm['en']
+
+``lang`` is an instance of 
+:py:class:`~wheezy.core.collections.defaultattrdict` where attributes 
+correspond to translation file (translation domain), if it is not available 
+fallback to an instance of ``gettext.NullTranslations``::
+    
+    assert 'Hello' == lang.messages.gettext('hello')
+
+Seamless integration with ``gettext`` module simplifies your application
+internationalization and localization.
+
+introspection
+-------------
+
+Type introspection is a capability to determine the type of an object at 
+runtime.
+
+:py:meth:`~wheezy.core.introspection.import_name` - dynamically imports 
+object by its full name. The following two imports are equivalent::
+
+    from datetime import timedelta
+    import_name('datetime.timedelta')
+
+:py:meth:`~wheezy.core.introspection.import_name` let you introduce lazy
+imports into your application.
+
+url
+---
+Every URL consists of the following: the scheme name (or protocol), 
+followed by a colon and two slashes, then, a domain name (alternatively, 
+IP address), a port number (optionally), the path of the resource to be 
+fetched, a query string, and an optional fragment identifier. Here is the 
+syntax::
+    
+    scheme://domain:port/path?query_string#fragment_id
+
+The :py:mod:`~wheezy.core.url` module provides integration with `urlparse`_
+module. 
+
+:py:class:`~wheezy.core.url.UrlParts` - concrete class for 
+:func:`urlparse.urlsplit` results, where argument ``parts`` is a tupple of 
+length 6. There are the following methods:
+
+* ``geturl()`` - returns the re-combined version of the original URL as a 
+  string.
+* ``join(other)`` - joins with another ``UrlParts`` instance by taking 
+  none-empty values from ``other``. Returns new ``UrlParts`` instance.
+
+There is factory function :py:meth:`~wheezy.core.url.urlparts` for 
+:py:class:`~wheezy.core.url.UrlParts` that let you create an instance of 
+:py:class:`~wheezy.core.url.UrlParts` with partial content.
+
+uuid
+----
+
+A universally unique identifier (UUID) is an identifier that enable 
+distributed systems to uniquely identify information without significant 
+central coordination. A UUID is a 16-byte (128-bit) number.
+
+There are the following functions available:
+
+* :py:meth:`~wheezy.core.uuid.shrink_uuid` - returns base64 representation 
+  of ``uuid``::
+  
+    >>> shrink_uuid(UUID('a4af2f54-e988-4f5c-bfd6-351c79299b74'))
+    'pK8vVOmIT1y_1jUceSmbdA'
+    
+* :py:meth:`~wheezy.core.uuid.parse_uuid` - decodes base64 string to ``uuid``::
+
+    >>> parse_uuid('pK8vVOmIT1y_1jUceSmbdA')
+    UUID('a4af2f54-e988-4f5c-bfd6-351c79299b74')
+
+There is also defined module attribute ``UUID_EMPTY`` that is just an 
+instance of UUID ``'00000000-0000-0000-0000-000000000000'``.
+
+
+
+.. _`urlparse`: http://docs.python.org/library/urlparse.html
+

src/wheezy/core/collections.py

 
-""" ``collections`` module.
+""" The ``collections`` module  contains types and functions that define
+    various collections and algorithms.
 """
 
 import struct
 
 
 def gzip_iterator(items, compress_level=6):
-    """
+    """ Iterates over ``items`` and returns generator of gzipped items.
+
         ``items`` - a list of bytes
 
         >>> items = [ntob('Hello World', 'latin1')]

src/wheezy/core/datetime.py

 
 
 def format_http_datetime(stamp):
-    """ Format datetime to a string following rfc1123 pattern.
+    """ Formats datetime to a string following rfc1123 pattern.
 
         >>> now = datetime(2011, 9, 19, 10, 45, 30, 0, UTC)
         >>> format_http_datetime(now)
 
 
 def parse_http_datetime(stamp):
-    """
+    """ Parses a string in rfc1123 format to ``datetime``.
+
         >>> parse_http_datetime('Mon, 19 Sep 2011 10:45:30 GMT')
         datetime.datetime(2011, 9, 19, 10, 45, 30)
     """

src/wheezy/core/introspection.py

 
 
 def import_name(fullname):
-    """
+    """ Dynamically imports object by its full name.
+
         >>> from datetime import timedelta
         >>> import_name('datetime.timedelta') is timedelta
         True

src/wheezy/core/url.py

 
 def urlparts(parts=None, scheme=None, netloc=None, path=None,
         query=None, fragment=None):
-    """ ``parts`` must be a 5-tuple:
+    """ Factory function for :py:class:`~wheezy.core.url.UrlParts` that
+        create an instance :py:class:`~wheezy.core.url.UrlParts` with
+        partial content.
+
+        ``parts`` must be a 5-tuple:
         (scheme, netloc, path, query, fragment)
 
         >>> from wheezy.core.comp import urlsplit
 
 
 class UrlParts(tuple):
+    """ Concrete class for :func:`urlparse.urlsplit` results.
+    """
 
     def __init__(self, parts):
         assert len(parts) == 5, '`parts` must be a tupple of length 6'
         return 'urlparts' + super(UrlParts, self).__repr__()
 
     def geturl(self):
-        """
+        """ Return the re-combined version of the original URL as a string.
+
             >>> from wheezy.core.comp import urlsplit
             >>> parts = urlsplit('http://www.python.org/dev/peps/pep-3333')
             >>> parts = urlparts(parts)
         return urlunsplit(self)
 
     def join(self, other):
-        """
+        """ Joins with another ``UrlParts`` instance by taking
+            none-empty values from ``other``. Returns new ``UrlParts``
+            instance.
+
             >>> from wheezy.core.comp import urlsplit
             >>> parts = urlsplit('http://www.python.org/dev/peps/pep-3333')
             >>> parts = urlparts(parts)

src/wheezy/core/uuid.py

 
 
 def shrink_uuid(uuid):
-    """
+    """ Returns base64 representation of ``uuid``.
+
         >>> shrink_uuid(UUID('a4af2f54-e988-4f5c-bfd6-351c79299b74'))
         'pK8vVOmIT1y_1jUceSmbdA'
         >>> shrink_uuid(UUID('d17aba88-19c3-400e-adee-3ecf935db272'))