1 ==================

     2 ZTFY.utils package

     3 ==================

     4 

     5 Introduction

     6 ------------

     7 

     8 This package is composed of a set of utility functions, which in complement with zope.app.zapi

     9 package can facilite Zope management.

    10 

    11 

    12 Unicode functions

    13 -----------------

    14 

    15 While working with extended characters sets containing accentuated characters, it's necessary to

    16 conversing strings to UTF8 so that they can be used without any conversion problem.

    17 

    18     >>> from ztfy.utils import unicode

    19 

    20 'translateString' is a utility function which can be used, for example, to generate an object's id

    21 without space and with accentuated characters converted to their unaccentuated version:

    22 

    23     >>> sample = 'Mon titre accentué'

    24     >>> unicode.translateString(sample)

    25     u'mon titre accentue'

    26 

    27 Results are lower-cased by default ; this can be avoided be setting the 'forceLower' parameter

    28 to False:

    29 

    30     >>> unicode.translateString(sample, forceLower=False)

    31     u'Mon titre accentue'

    32 

    33 If input string can contain 'slashes' (/) or 'backslashes' (\), they are normally removed ; 

    34 by using the 'escapeSlashes' parameter, the input string is splitted and only the last element is

    35 returned ; this is handy to handle filenames on Windows platform:

    36 

    37     >>> sample = 'Autre / chaîne / accentuée'

    38     >>> unicode.translateString(sample)

    39     u'autre chaine accentuee'

    40     >>> unicode.translateString(sample, escapeSlashes=True)

    41     u'accentuee'

    42     >>> sample = 'C:\\Program Files\\My Application\\test.txt'

    43     >>> unicode.translateString(sample)

    44     u'cprogram filesmy applicationtest.txt'

    45     >>> unicode.translateString(sample, escapeSlashes=True)

    46     u'test.txt'

    47 

    48 

    49 Dates functions

    50 ---------------

    51 

    52 Dates functions are used to convert dates from/to string representation:

    53 

    54     >>> from datetime import datetime

    55     >>> from ztfy.utils import date

    56     >>> now = datetime.fromtimestamp(1205000000)

    57     >>> now

    58     datetime.datetime(2008, 3, 8, 19, 13, 20)

    59 

    60 You can get an unicode representation of a date in ASCII format using 'unidate' fonction ; date is

    61 converted to GMT:

    62 

    63     >>> udate = date.unidate(now)

    64     >>> udate

    65     u'2008-03-08T19:13:20+00:00'

    66 

    67 'parsedate' can be used to convert ASCII format into datetime:

    68 

    69     >>> ddate = date.parsedate(udate)

    70     >>> ddate

    71     datetime.datetime(2008, 3, 8, 19, 13, 20, tzinfo=<StaticTzInfo 'GMT'>)

    72 

    73 'datetodatetime' can be used to convert a 'date' type to a 'datetime' value ; if a 'datetime' value

    74 is used as argument, it is returned 'as is':

    75 

    76     >>> ddate.date()

    77     datetime.date(2008, 3, 8)

    78     >>> date.datetodatetime(ddate)

    79     datetime.datetime(2008, 3, 8, 19, 13, 20, tzinfo=<StaticTzInfo 'GMT'>)

    80     >>> date.datetodatetime(ddate.date())

    81     datetime.datetime(2008, 3, 8, 0, 0)

    82 

    83 

    84 Timezones handling

    85 ------------------

    86 

    87 Timezones handling game me headaches at first. I finally concluded that the best way (for me !) to handle

    88 TZ data was to store every datetime value in GMT timezone.

    89 As far as I know, there is no easy way to know the user's timezone from his request settings. So you can:

    90 - store this timezone in user's profile,

    91 - define a static server's timezone :-/

    92 

    93 My current default user's timezone is set to 'Europe/Paris' ; you should probably update this setting in

    94 'timezone.py' if you are located elsewhere.

    95 

    96     >>> from ztfy.utils import timezone

    97     >>> timezone.tztime(ddate)

    98     datetime.datetime(2008, 3, 8, 20, 13, 20, tzinfo=<DstTzInfo 'Europe/Paris' CET+1:00:00 STD>)

    99 

   100 'gmtime' function can be used to convert a datetime to GMT:

   101 

   102     >>> timezone.gmtime(now)

   103     datetime.datetime(2008, 3, 8, 19, 13, 20, tzinfo=<StaticTzInfo 'GMT'>)