===================
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