From d0d0c8a17fe46f9f69f1e692907c4ab193afbf17 Mon Sep 17 00:00:00 2001
From: Martin Lange <martin.lange@ufz.de>
Date: Fri, 25 Nov 2022 23:05:42 +0100
Subject: [PATCH] update docstrings for new time arguments
---
src/finam/interfaces.py | 6 ++++++
src/finam/schedule.py | 14 +++++++++++++-
src/finam/sdk/component.py | 16 +++++++++++++++-
src/finam/tools/connect_helper.py | 2 +-
4 files changed, 35 insertions(+), 3 deletions(-)
diff --git a/src/finam/interfaces.py b/src/finam/interfaces.py
index 966f42ff..30efe0ba 100644
--- a/src/finam/interfaces.py
+++ b/src/finam/interfaces.py
@@ -75,6 +75,12 @@ class IComponent(ABC):
After each method call, the component should have :attr:`.status` :attr:`.ComponentStatus.CONNECTED` if
connecting was completed, :attr:`.ComponentStatus.CONNECTING` if some but not all required initial input(s)
could be pulled, and :attr:`.ComponentStatus.CONNECTING_IDLE` if nothing could be pulled.
+
+ Parameters
+ ----------
+ start_time : :class:`datetime <datetime.datetime>`
+ The composition's starting time.
+ Can be before the component's actual time.
"""
@abstractmethod
diff --git a/src/finam/schedule.py b/src/finam/schedule.py
index 58301659..17b5505b 100644
--- a/src/finam/schedule.py
+++ b/src/finam/schedule.py
@@ -144,6 +144,13 @@ class Composition(Loggable):
"""Performs the connect and validate phases of the composition
If this was not called by the user, it is called at the start of :meth:`.run`.
+
+ Parameters
+ ----------
+ time : :class:`datetime <datetime.datetime>`, optional
+ Starting time of the composition.
+ If provided, it should be the starting time of the earliest component.
+ If not provided, the composition tries to determine the starting time automatically.
"""
if self.is_connected:
raise FinamStatusError("Composition was already connected.")
@@ -194,7 +201,12 @@ class Composition(Loggable):
Parameters
----------
- t_max : :class:`datetime <datetime.datetime>` or None, optional
+ t : :class:`datetime <datetime.datetime>`, optional
+ Starting time of the composition.
+ If provided, it should be the starting time of the earliest component.
+ If not provided, the composition tries to determine the starting time automatically.
+ Ignored if :meth:`.connect` was already called.
+ t_max : :class:`datetime <datetime.datetime>`, optional
Simulation time up to which to simulate.
Should be ``None`` if no components with time are present.
"""
diff --git a/src/finam/sdk/component.py b/src/finam/sdk/component.py
index 406a8707..7cbcd050 100644
--- a/src/finam/sdk/component.py
+++ b/src/finam/sdk/component.py
@@ -83,6 +83,12 @@ class Component(IComponent, Loggable, ABC):
After each method call, the component should have :attr:`.status` :attr:`.ComponentStatus.CONNECTED` if
connecting was completed, :attr:`.ComponentStatus.CONNECTING` if some but not all required initial input(s)
could be pulled, and :attr:`.ComponentStatus.CONNECTING_IDLE` if nothing could be pulled.
+
+ Parameters
+ ----------
+ start_time : :class:`datetime <datetime.datetime>`
+ The composition's starting time.
+ Can be before the component's actual time.
"""
if start_time is not None and not isinstance(start_time, datetime):
raise FinamTimeError("Time in connect must be either None or a datetime")
@@ -100,6 +106,14 @@ class Component(IComponent, Loggable, ABC):
"""Connect exchange data and metadata with linked components.
Components must overwrite this method.
+
+ Parameters
+ ----------
+ start_time : :class:`datetime <datetime.datetime>`
+ The composition's starting time.
+ Can be before the component's actual time.
+
+ Should be passed to :meth:`.try_connect` calls.
"""
raise NotImplementedError(
f"Method `_connect` must be implemented by all components, but implementation is missing in {self.name}."
@@ -347,7 +361,7 @@ class Component(IComponent, Loggable, ABC):
Parameters
----------
time : :class:`datetime <datetime.datetime>`
- time for data pulls
+ the composition's starting time as passed to :meth:`.Component.try_connect`
exchange_infos : dict of [str, Info]
currently or newly available input data infos by input name
push_infos : dict of [str, Info]
diff --git a/src/finam/tools/connect_helper.py b/src/finam/tools/connect_helper.py
index df305a7a..2c73d7f1 100644
--- a/src/finam/tools/connect_helper.py
+++ b/src/finam/tools/connect_helper.py
@@ -340,7 +340,7 @@ class ConnectHelper(Loggable):
Parameters
----------
time : :class:`datetime <datetime.datetime>`
- time for data pulls
+ the composition's starting time as passed to :meth:`.Component.try_connect`
exchange_infos : dict
currently or newly available input data infos by input name
push_infos : dict
--
GitLab