Commits

Andriy Kornatskyy committed 351c377

Added banchmark and json sections to documentation

Comments (0)

Files changed (4)

 .. automodule:: wheezy.core
    :members:
 
+wheezy.core.benchmark
+-----------------------
+
+.. automodule:: wheezy.core.benchmark
+   :members:
+
 wheezy.core.collections
 -----------------------
 
 
 .. automodule:: wheezy.core.introspection
    :members:
+   
+wheezy.core.json
+----------------
+
+.. automodule:: wheezy.core.json
+   :members:
 
 wheezy.core.url
 ---------------

doc/userguide.rst

 
 :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 
+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`` 
+* :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 
+* :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 
+* :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 
+* :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.distinct` - returns generator for unique 
+* :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`` 
+* :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 
+: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}
 
 Functions:
 
-* :py:meth:`~wheezy.core.datetime.format_http_datetime` - formats datetime 
+* :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 
+* :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 
+* :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 
+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 
+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 
+: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).
 
 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
 
     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 
+``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
 introspection
 -------------
 
-Type introspection is a capability to determine the type of an object at 
+Type introspection is a capability to determine the type of an object at
 runtime.
 
-:py:meth:`~wheezy.core.introspection.import_name` - dynamically imports 
+:py:meth:`~wheezy.core.introspection.import_name` - dynamically imports
 object by its full name. The following two imports are equivalent::
 
     from datetime import 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.
+
+* :py:meth:`~wheezy.core.json.json_encode` encodes ``obj`` as a JSON formatted
+  string. correctly escapes forward slash to be able embed javascript code.
+  Decimal objects are converted to string (same applies when used with 
+  ``simplejson``).
+* :py:meth:`~wheezy.core.json.json_decode` decodes a JSON document to a Python
+  object. Float is parsed as Decimal.
+
 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 
+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. 
+module.
 
-:py:class:`~wheezy.core.url.UrlParts` - concrete class for 
-:func:`urlparse.urlsplit` results, where argument ``parts`` is a tupple of 
+: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 
+* ``geturl()`` - returns the re-combined version of the original URL as a
   string.
-* ``join(other)`` - joins with another ``UrlParts`` instance by taking 
+* ``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 
+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 
+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 
+* :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 
+There is also defined module attribute ``UUID_EMPTY`` that is just an
 instance of UUID ``'00000000-0000-0000-0000-000000000000'``.
 
 

src/wheezy/core/benchmark.py

     """
 
     def __init__(self, targets, number, warmup_number=None):
+        """
+            ``targets`` - a list of targets (callables) to be tested.
+
+            ``number`` - how many times each target is executed.
+
+            ``warmup_number`` - how many times each target is warmed up
+            before the bechmark is measured.
+        """
         self.targets = targets
         self.number = number
         self.warmup_number = warmup_number or max(int(number / 100), 10)

src/wheezy/core/json.py

 
 from decimal import Decimal
 
-from wheezy.core.comp import SimpleJSONEncoder
 from wheezy.core.comp import json_dumps
 from wheezy.core.comp import json_loads
+from wheezy.core.comp import SimpleJSONEncoder
 from wheezy.core.datetime import format_iso_datetime
 from wheezy.core.datetime import format_iso_time
 from wheezy.core.introspection import import_name