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 make Zope management easier.

    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 To remove remaining spaces or convert them to another character, you can use the "spaces" parameter

    49 which can contain any string to be used instead of initial spaces:

    50 

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

    52     >>> unicode.translateString(sample, spaces=' ')

    53     u'cprogram filesmy applicationtest.txt'

    54     >>> unicode.translateString(sample, spaces='-')

    55     u'cprogram-filesmy-applicationtest.txt'

    56 

    57 Spaces replacement is made in the last step, so using it with "escapeSlashes" parameter only affects

    58 the final result:

    59 

    60     >>> unicode.translateString(sample, escapeSlashes=True, spaces='-')

    61     u'test.txt'

    62 

    63 

    64 Dates functions

    65 ---------------

    66 

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

    68 

    69     >>> from datetime import datetime

    70     >>> from ztfy.utils import date

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

    72     >>> now

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

    74 

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

    76 converted to GMT:

    77 

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

    79     >>> udate

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

    81 

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

    83 

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

    85     >>> ddate

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

    87 

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

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

    90 

    91     >>> ddate.date()

    92     datetime.date(2008, 3, 8)

    93     >>> date.datetodatetime(ddate)

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

    95     >>> date.datetodatetime(ddate.date())

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

    97 

    98 

    99 Timezones handling

   100 ------------------

   101 

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

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

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

   105 - store this timezone in user's profile,

   106 - define a static server's timezone

   107 - create and register a ServerTimezoneUtility to handle server default timezone.

   108 

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

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

   111 

   112     >>> from ztfy.utils import timezone

   113     >>> timezone.tztime(ddate)

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

   115 

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

   117 

   118     >>> timezone.gmtime(now)

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