Source

wheezy.core / doc / userguide.rst

User Guide

:ref:`wheezy.core` comes with extensions to the following features:

  • benchmark
  • collections
  • config
  • datetime
  • descriptors
  • i18n
  • introspection
  • json
  • url
  • uuid

benchmark

The :py:mod:`~wheezy.core.benchmark` module contains a single class :py:class:`~wheezy.core.benchmark.Benchmark` that measures execution time of your code.

Here is an example:

class BenchmarkTestCase(PublicTestCase):

    def runTest(self):
        p = Benchmark((
            self.test_home,
            self.test_about
            ), 1000)
        p.report('public', baselines={
                'test_home': 1.0,
                'test_about': 0.926
        })

Sample output:

public: 2 x 1000
baseline throughput change target
  100.0%     839rps  +0.0% test_home
   96.2%     807rps  +3.9% test_about

Each of test cases has been run 1000 times. It shows productivity gain from first test case (it serves baseline purpose for others), throughput in requests per second, change from baselines argument passed to report method and target being benchmarked.

Report is being printed as results are available.

collections

The :py:mod:`~wheezy.core.collections` module contains types and functions that define various collections, iterators and algorithms.

Classes:

Functions:

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:

Functions:

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.

json

Extends standard json module from Python2.6 and simplejson for Python2.5 with support for date, datetime, time and Decimal types.

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:

There is also defined module attribute UUID_EMPTY that is just an instance of UUID '00000000-0000-0000-0000-000000000000'.