Updated date documentation for the new timezone support

diff --git a/babel/dates.py b/babel/dates.py
index e604147608574706e8f804d6321e3458870dd139..a4a0beb9e13753313beba4bf0f8f6b0cf26b1487 100644 (file)
--- a/babel/dates.py
+++ b/babel/dates.py
@@ -339,7 +339,10 @@ def get_timezone_location(dt_or_tzinfo=None, locale=LC_TIME):
     if dt_or_tzinfo is None:
         dt = None
         tzinfo = LOCALTZ
-    elif dt_or_tzinfo is None or isinstance(dt_or_tzinfo, (int, long)):
+    elif isinstance(dt_or_tzinfo, basestring):
+        dt = None
+        tzinfo = get_timezone(dt_or_tzinfo)
+    elif isinstance(dt_or_tzinfo, (int, long)):
         dt = None
         tzinfo = UTC
     elif isinstance(dt_or_tzinfo, (datetime, time)):
@@ -448,7 +451,10 @@ def get_timezone_name(dt_or_tzinfo=None, width='long', uncommon=False,
     if dt_or_tzinfo is None:
         dt = None
         tzinfo = LOCALTZ
-    elif dt_or_tzinfo is None or isinstance(dt_or_tzinfo, (int, long)):
+    elif isinstance(dt_or_tzinfo, basestring):
+        dt = None
+        tzinfo = get_timezone(dt_or_tzinfo)
+    elif isinstance(dt_or_tzinfo, (int, long)):
         dt = None
         tzinfo = UTC
     elif isinstance(dt_or_tzinfo, (datetime, time)):

diff --git a/docs/dates.rst b/docs/dates.rst
index e58c77207530d456337649a70ca02a097f305c87..d69a08d333d1c9e2f2c39ead8fd88771cfe94694 100644 (file)
--- a/docs/dates.rst
+++ b/docs/dates.rst
@@ -242,17 +242,18 @@ class, which you need appropriate implementations for to actually use in your
 application. Babel includes a ``tzinfo`` implementation for UTC (Universal
 Time).
 
-For real time-zone support, it is strongly recommended that you use the
-third-party package `pytz`_, which includes the definitions of practically all
-of the time-zones used on the world, as well as important functions for
-reliably converting from UTC to local time, and vice versa:
+Babel uses `pytz`_ for real timezone support which includes the
+definitions of practically all of the time-zones used on the world, as
+well as important functions for reliably converting from UTC to local
+time, and vice versa.  The module is generally wrapped for you so you can
+directly interface with it from within Babel:
 
 .. code-block:: pycon
 
     >>> from datetime import time
-    >>> from pytz import timezone, utc
-    >>> dt = datetime(2007, 04, 01, 15, 30, tzinfo=utc)
-    >>> eastern = timezone('US/Eastern')
+    >>> from babel.dates import get_timezone, UTC
+    >>> dt = datetime(2007, 04, 01, 15, 30, tzinfo=UTC)
+    >>> eastern = get_timezone('US/Eastern')
     >>> format_datetime(dt, 'H:mm Z', tzinfo=eastern, locale='en_US')
     u'11:30 -0400'
 
@@ -265,7 +266,7 @@ unchanged:
 
 .. code-block:: pycon
 
-    >>> british = timezone('Europe/London')
+    >>> british = get_timezone('Europe/London')
     >>> format_datetime(dt, 'H:mm zzzz', tzinfo=british, locale='en_US')
     u'16:30 British Summer Time'
 
@@ -275,6 +276,24 @@ applied to ``format_time``, but because the actual date is unknown in that
 case, the current day is assumed to determine whether DST or standard time
 should be used.
 
+For many timezones it's also possible to ask for the next timezone
+transition.  This for instance is useful to answer the question “when do I
+have to move the clock forward next”:
+
+.. code-block:: pycon
+
+    >>> t = get_next_timezone_transition('Europe/Vienna', datetime(2011, 3, 2))
+    >>> t
+    <TimezoneTransition CET -> CEST (2011-03-27 01:00:00)>
+    >>> t.from_offset
+    3600.0
+    >>> t.to_offset
+    7200.0
+    >>> t.from_tz
+    'CET'
+    >>> t.to_tz
+    'CEST'
+
  .. _`pytz`: http://pytz.sourceforge.net/