onetick-py 1.162.2__tar.gz → 1.163.0__tar.gz

{onetick_py-1.162.2 → onetick_py-1.163.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: onetick-py
-Version: 1.162.2
+Version: 1.163.0
 Summary: Python package that allows you to work with OneTick
 Author-email: solutions <solutions@onetick.com>
 License-Expression: MIT

{onetick_py-1.162.2 → onetick_py-1.163.0}/src/onetick/py/_version.py

@@ -1,2 +1,2 @@
 # This file was generated automatically. DO NOT CHANGE.
-VERSION = '1.162.2'
+VERSION = '1.163.0'

{onetick_py-1.162.2 → onetick_py-1.163.0}/src/onetick/py/aggregations/_docs.py

@@ -31,7 +31,9 @@ _column_doc = param_doc(
 _running_doc = param_doc(
     name='running',
     desc='''
-    Aggregation will be calculated as sliding window.
+    See :ref:`Aggregation buckets guide <buckets_guide>` to see examples of how this parameter works.
+
+    Specifies if the aggregation will be calculated as a sliding window.
     ``running`` and ``bucket_interval`` parameters determines when new buckets are created.
 
     * ``running`` = True
@@ -45,10 +47,10 @@ _running_doc = param_doc(
 
       * ``bucket_interval`` = 0
 
-        Left boundary of window will be bound to start time. For each tick aggregation will be calculated in
-        [start_time; tick_t].
+        Left boundary of window will be set to query start time. For each tick aggregation will be calculated in
+        the interval [start_time; tick_t] from query start time to the tick's timestamp (inclusive).
 
-    * ``running`` = False
+    * ``running`` = False (default)
 
       buckets partition the [query start time, query end time) interval into non-overlapping intervals
       of size ``bucket_interval`` (with the last interval possibly of a smaller size).
@@ -68,6 +70,8 @@ _running_doc = param_doc(
 _all_fields_doc = param_doc(
     name='all_fields',
     desc="""
+    See :ref:`Aggregation buckets guide <buckets_guide>` to see examples of how this parameter works.
+
     * ``all_fields`` = True
 
       output ticks include all fields from the input ticks
@@ -95,15 +99,25 @@ _all_fields_doc = param_doc(
 _all_fields_with_policy_doc = param_doc(
     name='all_fields',
     desc="""
+    See :ref:`Aggregation buckets guide <buckets_guide>` to see examples of how this parameter works.
+
     - If ``all_fields`` False - output tick will have only aggregation fields.
 
+    - If ``all_fields`` is True and ``running`` is False - additional fields will be copied from the first
+      tick in the bucket to the output tick.
+
     - If ``all_fields`` False and ``running`` True - output ticks are created when a tick enters or leaves the
       sliding window.
 
-    - If ``all_fields`` True - an output tick is generated only for arrival events,
+    - If ``all_fields`` True and ``running`` True - an output tick is generated only for arrival events,
       but all attributes from the input tick causing an arrival event are copied over to the output tick
       and the aggregation is added as another attribute.
 
+    - If ``all_fields`` True and ``running`` "when_ticks_exit_window" -
+      an output tick is generated only for exit events,
+      but all attributes from the exiting tick are copied over to the output tick
+      and the aggregation is added as another attribute.
+
     - If ``all_fields`` set to "first", "last", "high", or "low" - explicitly set tick selection policy for all
       fields values. For "high" and "low" "PRICE" field will be selected as an input.
       Otherwise, you will get the runtime error.
@@ -114,7 +128,8 @@ _all_fields_with_policy_doc = param_doc(
       first parameter.
     """,
     default=False,
-    annotation=Union[Literal[True, False, "first", "last", "high", "low"], HighTick, LowTick]
+    str_annotation=("True, False, 'when_ticks_exit_window', 'first', 'last', 'high', 'low', "
+                    ":py:func:`~onetick.py.agg.high_tick`, :py:func:`~onetick.py.agg.low_tick`"),
 )
 _bucket_interval_doc = param_doc(
     name='bucket_interval',

{onetick_py-1.162.2 → onetick_py-1.163.0}/src/onetick/py/functions.py

@@ -902,8 +902,18 @@ def join_by_time(sources, how="outer", on=None, policy=None, check_schema=True,
     0 2003-12-01 00:00:00.001  1  0
     1 2003-12-01 00:00:00.003  2  1
 
-    In case you willing to add prefix/suffix to all columns in one of the sources you should use
-    :func:`Source.add_prefix` or :func:`Source.add_suffix`
+    Note
+    ----
+    In case different ``sources`` have matching columns, the exception will be raised.
+
+    To fix this error,
+    functions :func:`Source.add_prefix` or :func:`Source.add_suffix` can be used to rename all columns in the source.
+
+    Note that resulting **TIMESTAMP** pseudo-column will be taken from the leading source,
+    and timestamps of ticks from non-leading sources will not be added to the output,
+    so if you need to save them, you need to copy the timestamp to some other column.
+
+    See examples below.
 
     Parameters
     ----------
@@ -1047,7 +1057,8 @@ def join_by_time(sources, how="outer", on=None, policy=None, check_schema=True,
 
     Default joining logic, outer join with the first source is the leader by default:
 
-    >>> otp.run(otp.join_by_time([d1, d2]))
+    >>> data = otp.join_by_time([d1, d2])
+    >>> otp.run(data)
                          Time  A  B
     0 2003-12-01 00:00:00.001  1  0
     1 2003-12-01 00:00:00.002  2  1
@@ -1055,7 +1066,8 @@ def join_by_time(sources, how="outer", on=None, policy=None, check_schema=True,
 
     Leading source can be changed by using parameter ``leading``:
 
-    >>> otp.run(otp.join_by_time([d1, d2], leading=1))
+    >>> data = otp.join_by_time([d1, d2], leading=1)
+    >>> otp.run(data)
                          Time  A  B
     0 2003-12-01 00:00:00.001  1  1
     1 2003-12-01 00:00:00.002  2  2
@@ -1064,7 +1076,8 @@ def join_by_time(sources, how="outer", on=None, policy=None, check_schema=True,
     Note that OneTick's logic is different depending on the order of sources specified,
     so specifying ``leading`` parameter in the previous example is not the same as changing the order of sources here:
 
-    >>> otp.run(otp.join_by_time([d2, d1], leading=0))
+    >>> data = otp.join_by_time([d2, d1], leading=0)
+    >>> otp.run(data)
                          Time  B  A
     0 2003-12-01 00:00:00.001  1  0
     1 2003-12-01 00:00:00.002  2  1
@@ -1073,7 +1086,8 @@ def join_by_time(sources, how="outer", on=None, policy=None, check_schema=True,
     Parameter ``source_fields_order`` can be used to change the order of fields in the output,
     but it also affects the joining logic the same way as changing the order of sources:
 
-    >>> otp.run(otp.join_by_time([d1, d2], leading=1, source_fields_order=[1, 0]))
+    >>> data = otp.join_by_time([d1, d2], leading=1, source_fields_order=[1, 0])
+    >>> otp.run(data)
                          Time  B  A
     0 2003-12-01 00:00:00.001  1  0
     1 2003-12-01 00:00:00.002  2  1
@@ -1082,26 +1096,48 @@ def join_by_time(sources, how="outer", on=None, policy=None, check_schema=True,
     Parameter ``how`` can be set to "inner".
     In this case only ticks that were successfully joined from all sources will be propagated:
 
-    >>> otp.run(otp.join_by_time([d1, d2], how='inner'))
+    >>> data = otp.join_by_time([d1, d2], how='inner')
+    >>> otp.run(data)
                          Time  A  B
     0 2003-12-01 00:00:00.002  2  1
     1 2003-12-01 00:00:00.003  3  2
 
     Set parameter ``match_if_identical_times`` to only join ticks with the same timestamps:
 
-    >>> otp.run(otp.join_by_time([d1, d2], how='inner', match_if_identical_times=True))
+    >>> data = otp.join_by_time([d1, d2], how='inner', match_if_identical_times=True)
+    >>> otp.run(data)
                          Time  A  B
     0 2003-12-01 00:00:00.001  1  1
     1 2003-12-01 00:00:00.002  2  2
 
-    Adding prefix to right source for all columns:
+    In case of conflicting names in different sources, exception will be raised:
+
+    >>> d3 = otp.Ticks({'A': [1, 2, 4], 'offset': [1, 2, 4]})
+    >>> data = otp.join_by_time([d1, d3])
+    Traceback (most recent call last):
+        ...
+    ValueError: There are matched columns between sources: A
+
+    Adding prefix to right source for all columns will fix this problem:
 
-    >>> otp.run(otp.join_by_time([d1, d2.add_prefix('right_')]))
-                         Time  A  right_B
+    >>> data = otp.join_by_time([d1, d3.add_prefix('right_')])
+    >>> otp.run(data)
+                         Time  A  right_A
     0 2003-12-01 00:00:00.001  1        0
     1 2003-12-01 00:00:00.002  2        1
     2 2003-12-01 00:00:00.003  3        2
 
+    Note that timestamps from the non-leading source are not added to the output.
+    You can add them manually in a different field:
+
+    >>> d3['D3_TIMESTAMP'] = d3['TIMESTAMP']
+    >>> data = otp.join_by_time([d1, d3.add_prefix('right_')])
+    >>> otp.run(data)
+                         Time  A  right_A      right_D3_TIMESTAMP
+    0 2003-12-01 00:00:00.001  1        0 1969-12-31 19:00:00.000
+    1 2003-12-01 00:00:00.002  2        1 2003-12-01 00:00:00.001
+    2 2003-12-01 00:00:00.003  3        2 2003-12-01 00:00:00.002
+
     Use parameter ``output_type_index`` to specify which input class to use to create output object.
     It may be useful in case some custom user class was used as input:
 

{onetick_py-1.162.2 → onetick_py-1.163.0}/src/onetick_py.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: onetick-py
-Version: 1.162.2
+Version: 1.163.0
 Summary: Python package that allows you to work with OneTick
 Author-email: solutions <solutions@onetick.com>
 License-Expression: MIT