1 .. _utilities:

     2 

     3 Custom PyAMS utilities

     4 ======================

     5 

     6 PyAMS_utils provides a small set of utilities. You can create some of them as global utilities registered in

     7 the global components registry; other ones can be created manually by a site administrator and

     8 are then registered automatically.

     9 

    10 

    11 Server timezone

    12 ---------------

    13 

    14 To manage timezones correctly, and display datetimes based on current server timezone, all datetimes should

    15 be defined and stored in UTC.

    16 

    17 PyAMS_utils provides a :py:class:`ServerTimezoneUtility <pyams_utils.timezone.utility.ServerTimezoneUtility>` which

    18 allows you to assign a default timezone to your server.

    19 

    20 To display a datetime with correct timezone, you can use the :py:func:`tztime <pyams_utils.timezone.tztime>` function,

    21 which assign server timezone to the given parameter:

    22 

    23 .. code-block:: python

    24 

    25     from datetime import datetime

    26     from pyams_utils.timezone import tztime

    27 

    28     now = datetime.utcnow()

    29     my_date = tztime(now)  # converts *now* to server timezone

    30 

    31 We could imagine that datetimes could be displayed with current user timezone. But it's quite impossible to know

    32 the user timazone from a server request. The only options are:

    33 

    34 - you ask an authenticated user to update a timezone setting in his profile

    35 

    36 - you can include Javascript libraries which will try to detect browser timezone from their computer configuration, and

    37   do an AJAX request to update data in their session.

    38 

    39 That should require an update of :py:func:`tzinfo` adapter to get timezone info from session, request or user profile.

    40 

    41