Metadata-Version: 1.0
Name: bda.intellidatetime
Version: 1.0
Summary: Converter adapter for date and time input to datetime object.
Home-page: https://svn.plone.org/svn/collective/bda.intellidatetime
Author: Robert Niedereiter
Author-email: rnix@squarewave.at
License: General Public Licence
Description: ===================
        bda.intellidatetime
        ===================
        
        
        Overview
        --------
        
        bda.intellidatetime provides a converter for date and time input to python
        datetime.datetime objects.
        
        the input format is definded by a locale2pattern mapping and is provided by
        a seperate interface.
        
        Currently provided locales are:
        
        - en
        
        - de
        
        - fr
        
        - es
        
        - uk
        
        - it
        
        - cs
        
        - and the special locale ``iso``, which is used as default.
        
        
        Example
        -------
        
        the converter is designed as adapter accepting any object (the adapted object
        is never used).::
        
        >>> from bda.intellidatetime import IIntelliDateTime
        >>> converter = IIntelliDateTime(object())
        >>> converter.convert('1.1.08', locale='de')
        datetime.datetime(2008, 1, 1, 0, 0)
        
        
        API doc
        -------
        
        convert(date, time=None, tzinfo=None, locale='iso')
        Convert the input to a datetime object.
        
        The convert function accepts unicode or non-unicode strings and tries
        to parse out Date and Time information as follows:
        
        - First try to get the localized datetime pattern information
        
        - If no one is found, a default pattern is used.
        
        - Parse the input by the definitions of the localized datetime pattern
        
        - Create a datetime object and return it
        
        The ``intelligence`` is defined by following behaviour:
        
        Date:
        
        - If only one value is found f.e. ``1``, this value is handled as the
        day value, for month and for year the current ones are used.
        
        - Respective, if two values are given, they are handled as day and
        month, year is autocompleted with the current year.
        
        - 3 values are a complete date information, if year is a 2-character
        string, it is handled as year in the current century
        
        - as limiters are all non-numeric values accepted
        
        - date input can be done without limiters, therefor all characters
        must be numbers, and the string length must be either 2, 4, 6 or 8
        characters. 2 characters define the day, 4 characters the day and
        the month, 6 characters day, month and the year of the current
        century and 8 characters define a complete date.
        
        Time:
        
        - If time is None, time is set to 00:00
        
        - if time is a 2-character string, it is handled as the hour, minutes
        are defined as 00
        
        - time input can be done without a limiter, therefor time must be an
        all numeric 4-character string, the first 2 chars are handled as
        hour, the second 2 chars as minute.
        
        - as limiter are all non-numeric values accepted
        
        - seconds are never computed and are therefor ALWAYS handled as '00'
        
        Limiters can be any 1 or more character non numeric values. An input can
        look like ``  %_2008 1 abcde 5 ---`` and is still valid and with default
        locale converted to ``datetime.datetime(2008, 1, 5, 0, 0)``.
        
        If parsing of the input values is not possible or converting the parsed
        values to numeric values is not possible or the valid date and time
        range falls out of scope, a DateTimeConversionError is raised.
        
        - @param date - a date as string
        
        - @param time - a time as string
        
        - @param tzinfo - a tzinfo object to be considered, defaults to None. If
        given the date and time taken as in the given timezone. If the timezone
        is DST-aware time will be normalized for DST/non-DST.
        
        - @param locale - a locale name, which is used to determine the date and
        time patterns. There exists a special locale named 'iso', define the
        input in ISO format which further is used as default.
        
        - @return datetime - datetime.datetime object
        
        - @raise DateTimeConversionError - if conversion failes
        
        TODO
        ----
        
        - complete the locale2pattern mappings.
        
        - provide converter as utility and deprecate the adapter solution.
        
        
        Licence
        -------
        
        - GNU General Public Licence Version 2 or later
        
        
        Credits
        -------
        
        - Written by Robert Niederreiter
        Squarewave Computing, Bluedynamics Alliance Austria
        - Contributions: co-concept and timezone handling by Jens W. Klein
        Bluedynamics Alliance, Klein & Partner KEG, Austria
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Zope3
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
