Added examples for using `get_timezone_name` to documentation.

diff --git a/babel/dates.py b/babel/dates.py
index daea499988d8b636d863d89d45a3340364f57f7d..d9f3a6409dcb2972cd502d5c8116533afc33641e 100644 (file)
--- a/babel/dates.py
+++ b/babel/dates.py
@@ -367,7 +367,7 @@ def get_timezone_name(dt_or_tzinfo=None, width='long', uncommon=False,
     if dt_or_tzinfo is None or isinstance(dt_or_tzinfo, (int, long)):
         dt = None
         tzinfo = UTC
-    elif isinstance(dt_or_tzinfo, (datetime, time)):
+    elif isinstance(dt_or_tzinfo, (date, time)):
         dt = dt_or_tzinfo
         if dt.tzinfo is not None:
             tzinfo = dt.tzinfo

diff --git a/doc/dates.txt b/doc/dates.txt
index 6ed88e6dc2a178f57dd985707797d270ea4313a7..916b85839c8fb7f991055b5dff42c80b6d98e038 100644 (file)
--- a/doc/dates.txt
+++ b/doc/dates.txt
@@ -197,7 +197,7 @@ Time Fields
   +----------+--------+--------------------------------------------------------+
 
 
-Time-Zone Support
+Time-zone Support
 =================
 
 Many of the verbose time formats include the time-zone, but time-zone
@@ -243,6 +243,43 @@ should be used.
  .. _`pytz`: http://pytz.sourceforge.net/
 
 
+Localized Time-zone Names
+-------------------------
+
+While the ``Locale`` class provides access to various locale display names
+related to time-zones, the process of building a localized name of a time-zone
+is actually quite complicated. Babel implements it in separately usable
+functions in the ``babel.dates`` module, most importantly the
+``get_timezone_name`` function:
+
+.. code-block:: pycon
+
+    >>> from pytz import timezone
+    >>> from babel import Locale
+    >>> from babel.dates import get_timezone_name
+
+    >>> tz = timezone('Europe/Berlin')
+    >>> get_timezone_name(tz, locale=Locale.parse('pt_PT'))
+    u'Hor\xe1rio Alemanha'
+
+You can pass the function either a ``datetime.tzinfo`` object, or a
+``datetime.date`` or ``datetime.datetime`` object. If you pass an actual date,
+the function will be able to take daylight savings time into account. If you
+pass just the time-zone, Babel does not know whether daylight savings time is
+in effect, so it uses a generic representation, which is useful for example to
+display a list of time-zones to the user.
+
+.. code-block:: pycon
+
+    >>> from datetime import datetime
+
+    >>> dt = tz.localize(datetime(2007, 8, 15))
+    >>> get_timezone_name(dt, locale=Locale.parse('de_DE'))
+    u'Mitteleurop\xe4ische Sommerzeit'
+    >>> get_timezone_name(tz, locale=Locale.parse('de_DE'))
+    u'Deutschland'
+
+
 Parsing Dates
 =============
 
@@ -251,3 +288,5 @@ Babel can also parse date and time information in a locale-sensitive manner:
 .. code-block:: pycon
 
     >>> from babel.dates import parse_date, parse_datetime, parse_time
+
+.. note:: Date/time parsing is not properly implemented yet

diff --git a/doc/numbers.txt b/doc/numbers.txt
index 8cd8ff7e349465979c6cc5dab39eecbee971f7c5..3a4a7ef96324493169419efb43df46095afcba39 100644 (file)
--- a/doc/numbers.txt
+++ b/doc/numbers.txt
@@ -109,3 +109,5 @@ Examples:
     Traceback (most recent call last):
       ...
     NumberFormatError: '2,109,998' is not a valid decimal number
+
+.. note:: Number parsing is not properly implemented yet