Merge pull request #7672 from rockg/holiday-doc

Add some documentation on gotchas related to pytz updates #7620

Author: jreback

doc/source/io.rst

@@ -2938,6 +2938,8 @@ Furthermore ``ptrepack in.h5 out.h5`` will *repack* the file to allow
 you to reuse previously deleted space. Aalternatively, one can simply
 remove the file and write again, or use the ``copy`` method.
 
+.. _io.hdf5-notes:
+
 Notes & Caveats
 ~~~~~~~~~~~~~~~
 
@@ -2960,6 +2962,13 @@ Notes & Caveats
      ``tables``. The sizes of a string based indexing column
      (e.g. *columns* or *minor_axis*) are determined as the maximum size
      of the elements in that axis or by passing the parameter
+   - Be aware that timezones (e.g., ``pytz.timezone('US/Eastern')``) 
+     are not necessarily equal across timezone versions.  So if data is
+     localized to a specific timezone in the HDFStore using one version
+     of a timezone library and that data is updated with another version, the data
+     will be converted to UTC since these timezones are not considered
+     equal.  Either use the same version of timezone library or use ``tz_convert`` with
+     the updated timezone definition.
 
 .. warning::
 

doc/source/timeseries.rst

@@ -1343,7 +1343,14 @@ tz-aware data to another time zone:
 
 	Be wary of conversions between libraries. For some zones ``pytz`` and ``dateutil`` have different
 	definitions of the zone. This is more of a problem for unusual timezones than for
-	'standard' zones like ``US/Eastern``.
+	'standard' zones like ``US/Eastern``.  
+
+.. warning:: 
+
+       Be aware that a timezone definition across versions of timezone libraries may not 
+       be considered equal.  This may cause problems when working with stored data that 
+       is localized using one version and operated on with a different version.  
+       See :ref:`here<io.hdf5-notes>` for how to handle such a situation.
 
 Under the hood, all timestamps are stored in UTC. Scalar values from a
 ``DatetimeIndex`` with a time zone will have their fields (day, hour, minute)