DOC: Clarify passing epoch timestamp to Timestamp with timezone.

[mroeschke]

In [9]: int_arg = Timestamp('2010-01-01 12:00:00').value

In [10]: int_arg
Out[10]: 1262347200000000000

# With tz string
In [11]: Timestamp(int_arg, tz='US/Pacific')
Out[11]: Timestamp('2010-01-01 04:00:00-0800', tz='US/Pacific')

In [12]: Timestamp('2010-01-01 12:00:00', tz='US/Pacific') # correct
Out[12]: Timestamp('2010-01-01 12:00:00-0800', tz='US/Pacific')

# With tzinfo object
In [13]: Timestamp(int_arg, tzinfo=pytz.FixedOffset(60))
Out[13]: Timestamp('2010-01-01 13:00:00+0100', tz='pytz.FixedOffset(60)')

In [14]: Timestamp('2010-01-01 12:00:00', tzinfo=pytz.FixedOffset(60)) # correct
Out[14]: Timestamp('2010-01-01 12:00:00+0100', tz='pytz.FixedOffset(60)')

Output of pd.show_versions()

INSTALLED VERSIONS

commit: be4ad6fb532e2892bacc5896d673c8769cd0035a
python: 3.6.4.final.0
python-bits: 64
OS: Linux
OS-release: 4.4.0-43-Microsoft
machine: x86_64
processor: x86_64
byteorder: little
LC_ALL: None
LANG: en_US.UTF-8
LOCALE: en_US.UTF-8

pandas: 0.23.0.dev0+483.gbe4ad6f.dirty
pytest: 3.3.2
pip: 9.0.1
setuptools: 38.4.0
Cython: 0.27.3
numpy: 1.14.0
scipy: 1.0.0
pyarrow: 0.8.0
xarray: 0.10.0
IPython: 6.2.1
sphinx: 1.6.6
patsy: 0.5.0
dateutil: 2.6.1
pytz: 2017.3
blosc: None
bottleneck: 1.2.1
tables: 3.4.2
numexpr: 2.6.4
feather: 0.4.0
matplotlib: 2.1.2
openpyxl: 2.4.10
xlrd: 1.1.0
xlwt: 1.3.0
xlsxwriter: 1.0.2
lxml: 4.1.1
bs4: 4.6.0
html5lib: 1.0.1
sqlalchemy: 1.2.1
pymysql: 0.7.11.None
psycopg2: None
jinja2: 2.10
s3fs: 0.1.2
fastparquet: 0.1.4
pandas_gbq: None
pandas_datareader: None

[jreback]

we have an issue about this, though can't seem to find it ATM. yeah this is a bug. if you'd have a look thru the issues would be great (and of course a PR to fix!)

[mroeschke]

Actually, I think this behavior is expected. It only makes sense for a passed int or float to be an epoch timestamp (from UTC), so the localization makes sense. Maybe this can be clarified in the docs (timeseries.rst).

[jreback]

ok that sounds good