docs: add documentation about supported str formats

Author: bednar

influxdb_client/client/write/dataframe_serializer.py

@@ -41,8 +41,10 @@ def __init__(self, data_frame, point_settings, precision=DEFAULT_WRITE_PRECISION
         :param chunk_size: The size of chunk for serializing into chunks.
         :key data_frame_measurement_name: name of measurement for writing Pandas DataFrame
         :key data_frame_tag_columns: list of DataFrame columns which are tags, rest columns will be fields
-        :key data_frame_timestamp_column: DataFrame column which contains timestamp
-        """
+        :key data_frame_timestamp_column: name of DataFrame column which contains a timestamp. The column can be defined as a :class:`~str` value
+                                          formatted as `2018-10-26`, `2018-10-26 12:00`, `2018-10-26 12:00:00-05:00`
+                                          or other formats and types supported by `pandas.to_datetime <https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.to_datetime.html#pandas.to_datetime>`_ - ``DataFrame``
+        """  # noqa: E501
         # This function is hard to understand but for good reason:
         # the approach used here is considerably more efficient
         # than the alternatives.
@@ -279,6 +281,8 @@ def data_frame_to_list_of_points(data_frame, point_settings, precision=DEFAULT_W
     :param precision: The precision for the unix timestamps within the body line-protocol.
     :key data_frame_measurement_name: name of measurement for writing Pandas DataFrame
     :key data_frame_tag_columns: list of DataFrame columns which are tags, rest columns will be fields
-    :key data_frame_timestamp_column: DataFrame column which contains timestamps
-    """
+    :key data_frame_timestamp_column: name of DataFrame column which contains a timestamp. The column can be defined as a :class:`~str` value
+                                      formatted as `2018-10-26`, `2018-10-26 12:00`, `2018-10-26 12:00:00-05:00`
+                                      or other formats and types supported by `pandas.to_datetime <https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.to_datetime.html#pandas.to_datetime>`_ - ``DataFrame``
+    """  # noqa: E501
     return DataframeSerializer(data_frame, point_settings, precision, **kwargs).serialize()

influxdb_client/client/write_api.py

@@ -294,7 +294,9 @@ def write(self, bucket: str, org: str = None,
         :key data_frame_measurement_name: name of measurement for writing Pandas DataFrame - ``DataFrame``
         :key data_frame_tag_columns: list of DataFrame columns which are tags,
                                      rest columns will be fields - ``DataFrame``
-        :key data_frame_timestamp_column: DataFrame column which contains timestamp - ``DataFrame``
+        :key data_frame_timestamp_column: name of DataFrame column which contains a timestamp. The column can be defined as a :class:`~str` value
+                                          formatted as `2018-10-26`, `2018-10-26 12:00`, `2018-10-26 12:00:00-05:00`
+                                          or other formats and types supported by `pandas.to_datetime <https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.to_datetime.html#pandas.to_datetime>`_ - ``DataFrame``
         :key record_measurement_key: key of record with specified measurement -
                                      ``dictionary``, ``NamedTuple``, ``dataclass``
         :key record_measurement_name: static measurement name - ``dictionary``, ``NamedTuple``, ``dataclass``
@@ -323,8 +325,8 @@ def write(self, bucket: str, org: str = None,
                 write_api.write("my-bucket", "my-org", point)
 
         DataFrame:
-            The index of `Pandas DataFrame <https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html>`_
-            is used as a ``timestamp`` for written data. The index should be `PeriodIndex <https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.PeriodIndex.html#pandas.PeriodIndex>`_
+            If the ``data_frame_timestamp_column`` is not specified the index of `Pandas DataFrame <https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html>`_
+            is used as a ``timestamp`` for written data. The index can be `PeriodIndex <https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.PeriodIndex.html#pandas.PeriodIndex>`_
             or its must be transformable to ``datetime`` by
             `pandas.to_datetime <https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.to_datetime.html#pandas.to_datetime>`_.
 

influxdb_client/client/write_api_async.py

@@ -58,7 +58,9 @@ async def write(self, bucket: str, org: str = None,
         :key data_frame_measurement_name: name of measurement for writing Pandas DataFrame - ``DataFrame``
         :key data_frame_tag_columns: list of DataFrame columns which are tags,
                                      rest columns will be fields - ``DataFrame``
-        :key data_frame_timestamp_column: DataFrame column which contains timestamp - ``DataFrame``
+        :key data_frame_timestamp_column: name of DataFrame column which contains a timestamp. The column can be defined as a :class:`~str` value
+                                          formatted as `2018-10-26`, `2018-10-26 12:00`, `2018-10-26 12:00:00-05:00`
+                                          or other formats and types supported by `pandas.to_datetime <https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.to_datetime.html#pandas.to_datetime>`_ - ``DataFrame``
         :key record_measurement_key: key of record with specified measurement -
                                      ``dictionary``, ``NamedTuple``, ``dataclass``
         :key record_measurement_name: static measurement name - ``dictionary``, ``NamedTuple``, ``dataclass``
@@ -88,8 +90,8 @@ async def write(self, bucket: str, org: str = None,
                 await write_api.write("my-bucket", "my-org", point)
 
         DataFrame:
-            The index of `Pandas DataFrame <https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html>`_
-            is used as a ``timestamp`` for written data. The index should be `PeriodIndex <https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.PeriodIndex.html#pandas.PeriodIndex>`_
+            If the ``data_frame_timestamp_column`` is not specified the index of `Pandas DataFrame <https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html>`_
+            is used as a ``timestamp`` for written data. The index can be `PeriodIndex <https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.PeriodIndex.html#pandas.PeriodIndex>`_
             or its must be transformable to ``datetime`` by
             `pandas.to_datetime <https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.to_datetime.html#pandas.to_datetime>`_.
 

tests/test_WriteApiDataFrame.py

@@ -433,6 +433,32 @@ def test_use_timestamp_from_specified_column(self):
         self.assertEqual('test value1=10i,value2=30i 1586044800000000000', points[0])
         self.assertEqual('test value1=20i,value2=40i 1588636800000000000', points[1])
 
+    def test_str_format_for_timestamp(self):
+        from influxdb_client.extras import pd
+
+        time_formats = [
+            ('2018-10-26', 'test value1=10i,value2=20i 1540512000000000000'),
+            ('2018-10-26 10:00', 'test value1=10i,value2=20i 1540548000000000000'),
+            ('2018-10-26 10:00:00-05:00', 'test value1=10i,value2=20i 1540566000000000000'),
+            ('2018-10-26T11:00:00+00:00', 'test value1=10i,value2=20i 1540551600000000000'),
+            ('2018-10-26 12:00:00+00:00', 'test value1=10i,value2=20i 1540555200000000000'),
+            ('2018-10-26T16:00:00-01:00', 'test value1=10i,value2=20i 1540573200000000000'),
+        ]
+
+        for time_format in time_formats:
+            data_frame = pd.DataFrame(data={
+                'column_time': [time_format[0]],
+                'value1': [10],
+                'value2': [20],
+            }, index=['A'])
+            points = data_frame_to_list_of_points(data_frame=data_frame,
+                                                  data_frame_measurement_name="test",
+                                                  data_frame_timestamp_column="column_time",
+                                                  point_settings=PointSettings())
+
+            self.assertEqual(1, len(points))
+            self.assertEqual(time_format[1], points[0])
+
 
 class DataSerializerChunksTest(unittest.TestCase):
     def test_chunks(self):