diff --git a/latest-dev/reference/frequenz/client/base/grpc_streaming_helper/index.html b/latest-dev/reference/frequenz/client/base/grpc_streaming_helper/index.html new file mode 100644 index 0000000..98fec2f --- /dev/null +++ b/latest-dev/reference/frequenz/client/base/grpc_streaming_helper/index.html @@ -0,0 +1,18 @@ + + + + + Redirecting + + + + + Redirecting to ../../../../../../v0.0-dev/reference/frequenz/client/base/grpc_streaming_helper/... + + diff --git a/latest-dev/reference/frequenz/client/base/retry_strategy/index.html b/latest-dev/reference/frequenz/client/base/retry_strategy/index.html new file mode 100644 index 0000000..fc20b83 --- /dev/null +++ b/latest-dev/reference/frequenz/client/base/retry_strategy/index.html @@ -0,0 +1,18 @@ + + + + + Redirecting + + + + + Redirecting to ../../../../../../v0.0-dev/reference/frequenz/client/base/retry_strategy/... + + diff --git a/v0-dev/reference/frequenz/client/base/grpc_streaming_helper/index.html b/v0-dev/reference/frequenz/client/base/grpc_streaming_helper/index.html new file mode 100644 index 0000000..98fec2f --- /dev/null +++ b/v0-dev/reference/frequenz/client/base/grpc_streaming_helper/index.html @@ -0,0 +1,18 @@ + + + + + Redirecting + + + + + Redirecting to ../../../../../../v0.0-dev/reference/frequenz/client/base/grpc_streaming_helper/... + + diff --git a/v0-dev/reference/frequenz/client/base/retry_strategy/index.html b/v0-dev/reference/frequenz/client/base/retry_strategy/index.html new file mode 100644 index 0000000..fc20b83 --- /dev/null +++ b/v0-dev/reference/frequenz/client/base/retry_strategy/index.html @@ -0,0 +1,18 @@ + + + + + Redirecting + + + + + Redirecting to ../../../../../../v0.0-dev/reference/frequenz/client/base/retry_strategy/... + + diff --git a/v0.0-dev/404.html b/v0.0-dev/404.html index daed60b..eef5093 100644 --- a/v0.0-dev/404.html +++ b/v0.0-dev/404.html @@ -252,6 +252,12 @@ + + + + + + @@ -278,6 +284,9 @@ + + + @@ -444,9 +453,51 @@ + + + +
  • + + + + + + + + + + diff --git a/v0.0-dev/CONTRIBUTING/index.html b/v0.0-dev/CONTRIBUTING/index.html index 143041b..6301353 100644 --- a/v0.0-dev/CONTRIBUTING/index.html +++ b/v0.0-dev/CONTRIBUTING/index.html @@ -13,7 +13,7 @@ - + @@ -259,6 +259,12 @@ + + + + + + @@ -285,6 +291,9 @@ + + + @@ -453,9 +462,51 @@ + + + +
  • + + + + + + + + + + @@ -877,7 +980,7 @@

    Cross-Arch Testing -

    - base + retry_strategy

    diff --git a/v0.0-dev/SUMMARY/index.html b/v0.0-dev/SUMMARY/index.html index 69bca74..446687d 100644 --- a/v0.0-dev/SUMMARY/index.html +++ b/v0.0-dev/SUMMARY/index.html @@ -252,6 +252,12 @@ + + + + + + @@ -278,6 +284,9 @@ + + + @@ -444,9 +453,51 @@ + + + +
  • + + + + + + + + + + diff --git a/v0.0-dev/_scripts/__pycache__/macros.cpython-311.pyc b/v0.0-dev/_scripts/__pycache__/macros.cpython-311.pyc index 6aaad0e..554252d 100644 Binary files a/v0.0-dev/_scripts/__pycache__/macros.cpython-311.pyc and b/v0.0-dev/_scripts/__pycache__/macros.cpython-311.pyc differ diff --git a/v0.0-dev/index.html b/v0.0-dev/index.html index a5255c5..244fb36 100644 --- a/v0.0-dev/index.html +++ b/v0.0-dev/index.html @@ -261,6 +261,12 @@ + + + + + + @@ -287,6 +293,9 @@ + + + @@ -514,9 +523,51 @@ + + + +
  • + + + + + + + + + + @@ -703,13 +806,13 @@

    Contributing
    • -

    • + + + + @@ -559,7 +662,11 @@

    SUMMARY

    @@ -619,7 +700,7 @@ -

    base

    +

    Index

    @@ -635,7 +716,6 @@

    Utilities for writing Frequenz API clients.

    -

    TODO(cookiecutter): Add a more descriptive module description.

    @@ -647,146 +727,10 @@

    -

    Functions¤

    - - -
    -

    - frequenz.client.base.delete_me - - -¤

    -
    delete_me(*, blow_up: bool = False) -> bool
-
    - -
    - -

    Do stuff for demonstration purposes.

    - - - - - - - - - - - - - - - - -
    PARAMETER DESCRIPTION
    blow_up -
    -

    If True, raise an exception.

    -
    -

    - - TYPE: - bool - - - DEFAULT: - False - -

    -
    - - - - - - - - - - - - - - - - -
    RETURNSDESCRIPTION
    - - bool - - -
    -

    True if no exception was raised.

    -
    -
    - - - - - - - - - - - - - - - - -
    RAISESDESCRIPTION
    - - RuntimeError - - -
    -

    if blow_up is True.

    -
    -
    - -
    - Source code in frequenz/client/base/__init__.py - 
    11
-12
-13
-14
-15
-16
-17
-18
-19
-20
-21
-22
-23
-24
-25
    def delete_me(*, blow_up: bool = False) -> bool:
-    """Do stuff for demonstration purposes.
-
-    Args:
-        blow_up: If True, raise an exception.
-
-    Returns:
-        True if no exception was raised.
-
-    Raises:
-        RuntimeError: if blow_up is True.
-    """
-    if blow_up:
-        raise RuntimeError("This function should be removed!")
-    return True
-
    -
    -
    - -
    - - -

    @@ -836,13 +780,13 @@

    -
    + Skip to content + + +
    +
    + +
    + + + + + + +
    + + +
    + +
    + + + + + + + + + +
    +
    + + + +
    +
    +
    + + + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + + + +

    retry_strategy

    + +
    + + + + +

    + frequenz.client.base.retry_strategy + + +¤

    + +
    + +

    Implementations for retry strategies.

    + + + +
    + + + + + + +

    Classes¤

    + +
    + + + + +

    + frequenz.client.base.retry_strategy.ExponentialBackoff + + +¤

    + + +
    +

    + Bases: RetryStrategy

    + + +

    Provides methods for calculating the exponential interval between retries.

    + +
    + Source code in frequenz/client/base/retry_strategy.py + 
    116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
    class ExponentialBackoff(RetryStrategy):
+    """Provides methods for calculating the exponential interval between retries."""
+
+    DEFAULT_INTERVAL = _DEFAULT_RETRY_INTERVAL
+    """Default retry interval, in seconds."""
+
+    DEFAULT_MAX_INTERVAL = 60.0
+    """Default maximum retry interval, in seconds."""
+
+    DEFAULT_MULTIPLIER = 2.0
+    """Default multiplier for exponential increment."""
+
+    # pylint: disable=too-many-arguments
+    def __init__(
+        self,
+        initial_interval: float = DEFAULT_INTERVAL,
+        max_interval: float = DEFAULT_MAX_INTERVAL,
+        multiplier: float = DEFAULT_MULTIPLIER,
+        jitter: float = _DEFAULT_RETRY_JITTER,
+        limit: int | None = None,
+    ) -> None:
+        """Create a `ExponentialBackoff` instance.
+
+        Args:
+            initial_interval: time to wait for before the first retry, in
+                seconds.
+            max_interval: maximum interval, in seconds.
+            multiplier: exponential increment for interval.
+            jitter: a jitter to add to the retry interval.
+            limit: max number of retries before giving up.  `None` means no
+                limit, and `0` means no retry.
+        """
+        self._initial = initial_interval
+        self._max = max_interval
+        self._multiplier = multiplier
+        self._jitter = jitter
+        self._limit = limit
+
+        self._count = 0
+
+    def next_interval(self) -> float | None:
+        """Return the time to wait before the next retry.
+
+        Returns `None` if the retry limit has been reached, and no more retries
+        are possible.
+
+        Returns:
+            Time until next retry when below retry limit, and None otherwise.
+        """
+        if self._limit is not None and self._count >= self._limit:
+            return None
+        self._count += 1
+        exp_backoff_interval = self._initial * self._multiplier ** (self._count - 1)
+        return min(exp_backoff_interval + random.uniform(0.0, self._jitter), self._max)
+
    +
    + + + +
    + + + + + +
    Attributes¤
    + +
    + + + + +
    + DEFAULT_INTERVAL + + + + class-attribute + instance-attribute + + +¤
    +
    DEFAULT_INTERVAL = _DEFAULT_RETRY_INTERVAL
+
    + +
    + +

    Default retry interval, in seconds.

    +
    + +
    + +
    + + + + +
    + DEFAULT_MAX_INTERVAL + + + + class-attribute + instance-attribute + + +¤
    +
    DEFAULT_MAX_INTERVAL = 60.0
+
    + +
    + +

    Default maximum retry interval, in seconds.

    +
    + +
    + +
    + + + + +
    + DEFAULT_MULTIPLIER + + + + class-attribute + instance-attribute + + +¤
    +
    DEFAULT_MULTIPLIER = 2.0
+
    + +
    + +

    Default multiplier for exponential increment.

    +
    + +
    + +
    Functions¤
    + + +
    + + + + +
    + __init__ + + +¤
    +
    __init__(
+    initial_interval: float = DEFAULT_INTERVAL,
+    max_interval: float = DEFAULT_MAX_INTERVAL,
+    multiplier: float = DEFAULT_MULTIPLIER,
+    jitter: float = _DEFAULT_RETRY_JITTER,
+    limit: int | None = None,
+) -> None
+
    + +
    + +

    Create a ExponentialBackoff instance.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    PARAMETER DESCRIPTION
    initial_interval +
    +

    time to wait for before the first retry, in +seconds.

    +
    +

    + + TYPE: + float + + + DEFAULT: + DEFAULT_INTERVAL + +

    +
    max_interval +
    +

    maximum interval, in seconds.

    +
    +

    + + TYPE: + float + + + DEFAULT: + DEFAULT_MAX_INTERVAL + +

    +
    multiplier +
    +

    exponential increment for interval.

    +
    +

    + + TYPE: + float + + + DEFAULT: + DEFAULT_MULTIPLIER + +

    +
    jitter +
    +

    a jitter to add to the retry interval.

    +
    +

    + + TYPE: + float + + + DEFAULT: + _DEFAULT_RETRY_JITTER + +

    +
    limit +
    +

    max number of retries before giving up. None means no +limit, and 0 means no retry.

    +
    +

    + + TYPE: + int | None + + + DEFAULT: + None + +

    +
    + +
    + Source code in frequenz/client/base/retry_strategy.py + 
    129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
    def __init__(
+    self,
+    initial_interval: float = DEFAULT_INTERVAL,
+    max_interval: float = DEFAULT_MAX_INTERVAL,
+    multiplier: float = DEFAULT_MULTIPLIER,
+    jitter: float = _DEFAULT_RETRY_JITTER,
+    limit: int | None = None,
+) -> None:
+    """Create a `ExponentialBackoff` instance.
+
+    Args:
+        initial_interval: time to wait for before the first retry, in
+            seconds.
+        max_interval: maximum interval, in seconds.
+        multiplier: exponential increment for interval.
+        jitter: a jitter to add to the retry interval.
+        limit: max number of retries before giving up.  `None` means no
+            limit, and `0` means no retry.
+    """
+    self._initial = initial_interval
+    self._max = max_interval
+    self._multiplier = multiplier
+    self._jitter = jitter
+    self._limit = limit
+
+    self._count = 0
+
    +
    +
    + +
    + + +
    + + + + +
    + __iter__ + + +¤
    +
    __iter__() -> Iterator[float]
+
    + +
    + +

    Return an iterator over the retry intervals.

    + + + + + + + + + + + + + + + + +
    YIELDSDESCRIPTION
    + + float + + +
    +

    Next retry interval in seconds.

    +
    +
    + +
    + Source code in frequenz/client/base/retry_strategy.py + 
    65
+66
+67
+68
+69
+70
+71
+72
+73
+74
+75
    def __iter__(self) -> Iterator[float]:
+    """Return an iterator over the retry intervals.
+
+    Yields:
+        Next retry interval in seconds.
+    """
+    while True:
+        interval = self.next_interval()
+        if interval is None:
+            break
+        yield interval
+
    +
    +
    + +
    + + +
    + + + + +
    + copy + + +¤
    +
    copy() -> RetryStrategy
+
    + +
    + +

    Create a new instance of self.

    + + + + + + + + + + + + + + + + +
    RETURNSDESCRIPTION
    + + RetryStrategy + + +
    +

    A deepcopy of self.

    +
    +
    + +
    + Source code in frequenz/client/base/retry_strategy.py + 
    55
+56
+57
+58
+59
+60
+61
+62
+63
    def copy(self) -> RetryStrategy:
+    """Create a new instance of `self`.
+
+    Returns:
+        A deepcopy of `self`.
+    """
+    ret = deepcopy(self)
+    ret.reset()
+    return ret
+
    +
    +
    + +
    + + +
    + + + + +
    + get_progress + + +¤
    +
    get_progress() -> str
+
    + +
    + +

    Return a string denoting the retry progress.

    + + + + + + + + + + + + + + + + +
    RETURNSDESCRIPTION
    + + str + + +
    +

    String denoting retry progress in the form "(count/limit)"

    +
    +
    + +
    + Source code in frequenz/client/base/retry_strategy.py + 
    37
+38
+39
+40
+41
+42
+43
+44
+45
+46
    def get_progress(self) -> str:
+    """Return a string denoting the retry progress.
+
+    Returns:
+        String denoting retry progress in the form "(count/limit)"
+    """
+    if self._limit is None:
+        return f"({self._count}/∞)"
+
+    return f"({self._count}/{self._limit})"
+
    +
    +
    + +
    + + +
    + + + + +
    + next_interval + + +¤
    +
    next_interval() -> float | None
+
    + +
    + +

    Return the time to wait before the next retry.

    +

    Returns None if the retry limit has been reached, and no more retries +are possible.

    + + + + + + + + + + + + + + + + +
    RETURNSDESCRIPTION
    + + float | None + + +
    +

    Time until next retry when below retry limit, and None otherwise.

    +
    +
    + +
    + Source code in frequenz/client/base/retry_strategy.py + 
    156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
    def next_interval(self) -> float | None:
+    """Return the time to wait before the next retry.
+
+    Returns `None` if the retry limit has been reached, and no more retries
+    are possible.
+
+    Returns:
+        Time until next retry when below retry limit, and None otherwise.
+    """
+    if self._limit is not None and self._count >= self._limit:
+        return None
+    self._count += 1
+    exp_backoff_interval = self._initial * self._multiplier ** (self._count - 1)
+    return min(exp_backoff_interval + random.uniform(0.0, self._jitter), self._max)
+
    +
    +
    + +
    + + +
    + + + + +
    + reset + + +¤
    +
    reset() -> None
+
    + +
    + +

    Reset the retry counter.

    +

    To be called as soon as a connection is successful.

    + +
    + Source code in frequenz/client/base/retry_strategy.py + 
    48
+49
+50
+51
+52
+53
    def reset(self) -> None:
+    """Reset the retry counter.
+
+    To be called as soon as a connection is successful.
+    """
+    self._count = 0
+
    +
    +
    + +
    + + + +
    + +
    + +
    + +
    + + + + +

    + frequenz.client.base.retry_strategy.LinearBackoff + + +¤

    + + +
    +

    + Bases: RetryStrategy

    + + +

    Provides methods for calculating the interval between retries.

    + +
    + Source code in frequenz/client/base/retry_strategy.py + 
     78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
    class LinearBackoff(RetryStrategy):
+    """Provides methods for calculating the interval between retries."""
+
+    def __init__(
+        self,
+        interval: float = _DEFAULT_RETRY_INTERVAL,
+        jitter: float = _DEFAULT_RETRY_JITTER,
+        limit: int | None = None,
+    ) -> None:
+        """Create a `LinearBackoff` instance.
+
+        Args:
+            interval: time to wait for before the next retry, in seconds.
+            jitter: a jitter to add to the retry interval.
+            limit: max number of retries before giving up.  `None` means no
+                limit, and `0` means no retry.
+        """
+        self._interval = interval
+        self._jitter = jitter
+        self._limit = limit
+
+        self._count = 0
+
+    def next_interval(self) -> float | None:
+        """Return the time to wait before the next retry.
+
+        Returns `None` if the retry limit has been reached, and no more retries
+        are possible.
+
+        Returns:
+            Time until next retry when below retry limit, and None otherwise.
+        """
+        if self._limit is not None and self._count >= self._limit:
+            return None
+        self._count += 1
+        return self._interval + random.uniform(0.0, self._jitter)
+
    +
    + + + +
    + + + + + + + +
    Functions¤
    + + +
    + + + + +
    + __init__ + + +¤
    +
    __init__(
+    interval: float = _DEFAULT_RETRY_INTERVAL,
+    jitter: float = _DEFAULT_RETRY_JITTER,
+    limit: int | None = None,
+) -> None
+
    + +
    + +

    Create a LinearBackoff instance.

    + + + + + + + + + + + + + + + + + + + + + + + + +
    PARAMETER DESCRIPTION
    interval +
    +

    time to wait for before the next retry, in seconds.

    +
    +

    + + TYPE: + float + + + DEFAULT: + _DEFAULT_RETRY_INTERVAL + +

    +
    jitter +
    +

    a jitter to add to the retry interval.

    +
    +

    + + TYPE: + float + + + DEFAULT: + _DEFAULT_RETRY_JITTER + +

    +
    limit +
    +

    max number of retries before giving up. None means no +limit, and 0 means no retry.

    +
    +

    + + TYPE: + int | None + + + DEFAULT: + None + +

    +
    + +
    + Source code in frequenz/client/base/retry_strategy.py + 
    81
+82
+83
+84
+85
+86
+87
+88
+89
+90
+91
+92
+93
+94
+95
+96
+97
+98
+99
    def __init__(
+    self,
+    interval: float = _DEFAULT_RETRY_INTERVAL,
+    jitter: float = _DEFAULT_RETRY_JITTER,
+    limit: int | None = None,
+) -> None:
+    """Create a `LinearBackoff` instance.
+
+    Args:
+        interval: time to wait for before the next retry, in seconds.
+        jitter: a jitter to add to the retry interval.
+        limit: max number of retries before giving up.  `None` means no
+            limit, and `0` means no retry.
+    """
+    self._interval = interval
+    self._jitter = jitter
+    self._limit = limit
+
+    self._count = 0
+
    +
    +
    + +
    + + +
    + + + + +
    + __iter__ + + +¤
    +
    __iter__() -> Iterator[float]
+
    + +
    + +

    Return an iterator over the retry intervals.

    + + + + + + + + + + + + + + + + +
    YIELDSDESCRIPTION
    + + float + + +
    +

    Next retry interval in seconds.

    +
    +
    + +
    + Source code in frequenz/client/base/retry_strategy.py + 
    65
+66
+67
+68
+69
+70
+71
+72
+73
+74
+75
    def __iter__(self) -> Iterator[float]:
+    """Return an iterator over the retry intervals.
+
+    Yields:
+        Next retry interval in seconds.
+    """
+    while True:
+        interval = self.next_interval()
+        if interval is None:
+            break
+        yield interval
+
    +
    +
    + +
    + + +
    + + + + +
    + copy + + +¤
    +
    copy() -> RetryStrategy
+
    + +
    + +

    Create a new instance of self.

    + + + + + + + + + + + + + + + + +
    RETURNSDESCRIPTION
    + + RetryStrategy + + +
    +

    A deepcopy of self.

    +
    +
    + +
    + Source code in frequenz/client/base/retry_strategy.py + 
    55
+56
+57
+58
+59
+60
+61
+62
+63
    def copy(self) -> RetryStrategy:
+    """Create a new instance of `self`.
+
+    Returns:
+        A deepcopy of `self`.
+    """
+    ret = deepcopy(self)
+    ret.reset()
+    return ret
+
    +
    +
    + +
    + + +
    + + + + +
    + get_progress + + +¤
    +
    get_progress() -> str
+
    + +
    + +

    Return a string denoting the retry progress.

    + + + + + + + + + + + + + + + + +
    RETURNSDESCRIPTION
    + + str + + +
    +

    String denoting retry progress in the form "(count/limit)"

    +
    +
    + +
    + Source code in frequenz/client/base/retry_strategy.py + 
    37
+38
+39
+40
+41
+42
+43
+44
+45
+46
    def get_progress(self) -> str:
+    """Return a string denoting the retry progress.
+
+    Returns:
+        String denoting retry progress in the form "(count/limit)"
+    """
+    if self._limit is None:
+        return f"({self._count}/∞)"
+
+    return f"({self._count}/{self._limit})"
+
    +
    +
    + +
    + + +
    + + + + +
    + next_interval + + +¤
    +
    next_interval() -> float | None
+
    + +
    + +

    Return the time to wait before the next retry.

    +

    Returns None if the retry limit has been reached, and no more retries +are possible.

    + + + + + + + + + + + + + + + + +
    RETURNSDESCRIPTION
    + + float | None + + +
    +

    Time until next retry when below retry limit, and None otherwise.

    +
    +
    + +
    + Source code in frequenz/client/base/retry_strategy.py + 
    101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
    def next_interval(self) -> float | None:
+    """Return the time to wait before the next retry.
+
+    Returns `None` if the retry limit has been reached, and no more retries
+    are possible.
+
+    Returns:
+        Time until next retry when below retry limit, and None otherwise.
+    """
+    if self._limit is not None and self._count >= self._limit:
+        return None
+    self._count += 1
+    return self._interval + random.uniform(0.0, self._jitter)
+
    +
    +
    + +
    + + +
    + + + + +
    + reset + + +¤
    +
    reset() -> None
+
    + +
    + +

    Reset the retry counter.

    +

    To be called as soon as a connection is successful.

    + +
    + Source code in frequenz/client/base/retry_strategy.py + 
    48
+49
+50
+51
+52
+53
    def reset(self) -> None:
+    """Reset the retry counter.
+
+    To be called as soon as a connection is successful.
+    """
+    self._count = 0
+
    +
    +
    + +
    + + + +
    + +
    + +
    + +
    + + + + +

    + frequenz.client.base.retry_strategy.RetryStrategy + + +¤

    + + +
    +

    + Bases: ABC

    + + +

    Interface for implementing retry strategies.

    + +
    + Source code in frequenz/client/base/retry_strategy.py + 
    20
+21
+22
+23
+24
+25
+26
+27
+28
+29
+30
+31
+32
+33
+34
+35
+36
+37
+38
+39
+40
+41
+42
+43
+44
+45
+46
+47
+48
+49
+50
+51
+52
+53
+54
+55
+56
+57
+58
+59
+60
+61
+62
+63
+64
+65
+66
+67
+68
+69
+70
+71
+72
+73
+74
+75
    class RetryStrategy(ABC):
+    """Interface for implementing retry strategies."""
+
+    _limit: int | None
+    _count: int
+
+    @abstractmethod
+    def next_interval(self) -> float | None:
+        """Return the time to wait before the next retry.
+
+        Returns `None` if the retry limit has been reached, and no more retries
+        are possible.
+
+        Returns:
+            Time until next retry when below retry limit, and None otherwise.
+        """
+
+    def get_progress(self) -> str:
+        """Return a string denoting the retry progress.
+
+        Returns:
+            String denoting retry progress in the form "(count/limit)"
+        """
+        if self._limit is None:
+            return f"({self._count}/∞)"
+
+        return f"({self._count}/{self._limit})"
+
+    def reset(self) -> None:
+        """Reset the retry counter.
+
+        To be called as soon as a connection is successful.
+        """
+        self._count = 0
+
+    def copy(self) -> RetryStrategy:
+        """Create a new instance of `self`.
+
+        Returns:
+            A deepcopy of `self`.
+        """
+        ret = deepcopy(self)
+        ret.reset()
+        return ret
+
+    def __iter__(self) -> Iterator[float]:
+        """Return an iterator over the retry intervals.
+
+        Yields:
+            Next retry interval in seconds.
+        """
+        while True:
+            interval = self.next_interval()
+            if interval is None:
+                break
+            yield interval
+
    +
    + + + +
    + + + + + + + +
    Functions¤
    + + +
    + + + + +
    + __iter__ + + +¤
    +
    __iter__() -> Iterator[float]
+
    + +
    + +

    Return an iterator over the retry intervals.

    + + + + + + + + + + + + + + + + +
    YIELDSDESCRIPTION
    + + float + + +
    +

    Next retry interval in seconds.

    +
    +
    + +
    + Source code in frequenz/client/base/retry_strategy.py + 
    65
+66
+67
+68
+69
+70
+71
+72
+73
+74
+75
    def __iter__(self) -> Iterator[float]:
+    """Return an iterator over the retry intervals.
+
+    Yields:
+        Next retry interval in seconds.
+    """
+    while True:
+        interval = self.next_interval()
+        if interval is None:
+            break
+        yield interval
+
    +
    +
    + +
    + + +
    + + + + +
    + copy + + +¤
    +
    copy() -> RetryStrategy
+
    + +
    + +

    Create a new instance of self.

    + + + + + + + + + + + + + + + + +
    RETURNSDESCRIPTION
    + + RetryStrategy + + +
    +

    A deepcopy of self.

    +
    +
    + +
    + Source code in frequenz/client/base/retry_strategy.py + 
    55
+56
+57
+58
+59
+60
+61
+62
+63
    def copy(self) -> RetryStrategy:
+    """Create a new instance of `self`.
+
+    Returns:
+        A deepcopy of `self`.
+    """
+    ret = deepcopy(self)
+    ret.reset()
+    return ret
+
    +
    +
    + +
    + + +
    + + + + +
    + get_progress + + +¤
    +
    get_progress() -> str
+
    + +
    + +

    Return a string denoting the retry progress.

    + + + + + + + + + + + + + + + + +
    RETURNSDESCRIPTION
    + + str + + +
    +

    String denoting retry progress in the form "(count/limit)"

    +
    +
    + +
    + Source code in frequenz/client/base/retry_strategy.py + 
    37
+38
+39
+40
+41
+42
+43
+44
+45
+46
    def get_progress(self) -> str:
+    """Return a string denoting the retry progress.
+
+    Returns:
+        String denoting retry progress in the form "(count/limit)"
+    """
+    if self._limit is None:
+        return f"({self._count}/∞)"
+
+    return f"({self._count}/{self._limit})"
+
    +
    +
    + +
    + + +
    + + + + +
    + next_interval + + + + abstractmethod + + +¤
    +
    next_interval() -> float | None
+
    + +
    + +

    Return the time to wait before the next retry.

    +

    Returns None if the retry limit has been reached, and no more retries +are possible.

    + + + + + + + + + + + + + + + + +
    RETURNSDESCRIPTION
    + + float | None + + +
    +

    Time until next retry when below retry limit, and None otherwise.

    +
    +
    + +
    + Source code in frequenz/client/base/retry_strategy.py + 
    26
+27
+28
+29
+30
+31
+32
+33
+34
+35
    @abstractmethod
+def next_interval(self) -> float | None:
+    """Return the time to wait before the next retry.
+
+    Returns `None` if the retry limit has been reached, and no more retries
+    are possible.
+
+    Returns:
+        Time until next retry when below retry limit, and None otherwise.
+    """
+
    +
    +
    + +
    + + +
    + + + + +
    + reset + + +¤
    +
    reset() -> None
+
    + +
    + +

    Reset the retry counter.

    +

    To be called as soon as a connection is successful.

    + +
    + Source code in frequenz/client/base/retry_strategy.py + 
    48
+49
+50
+51
+52
+53
    def reset(self) -> None:
+    """Reset the retry counter.
+
+    To be called as soon as a connection is successful.
+    """
+    self._count = 0
+
    +
    +
    + +
    + + + +
    + +
    + +
    + + + + +
    + +
    + +
    + + + + + + +
    +
    + + +
    + + + +
    + + + +
    +
    +
    +
    + + + + + + + + + \ No newline at end of file diff --git a/v0.0-dev/search/search_index.json b/v0.0-dev/search/search_index.json index 04dba7c..42c81ba 100644 --- a/v0.0-dev/search/search_index.json +++ b/v0.0-dev/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Freqenz Client Base Library","text":""},{"location":"#introduction","title":"Introduction","text":"

    Utilities for writing Frequenz API clients

    TODO(cookiecutter): Improve the README file

    "},{"location":"#supported-platforms","title":"Supported Platforms","text":"

    The following platforms are officially supported (tested):

    • Python: 3.11
    • Operating System: Ubuntu Linux 20.04
    • Architectures: amd64, arm64
    "},{"location":"#contributing","title":"Contributing","text":"

    If you want to know how to build this project and contribute to it, please check out the Contributing Guide.

    "},{"location":"CONTRIBUTING/","title":"Contributing to Freqenz Client Base Library","text":""},{"location":"CONTRIBUTING/#build","title":"Build","text":"

    You can use build to simply build the source and binary distribution:

    python -m pip install build\npython -m build\n
    "},{"location":"CONTRIBUTING/#local-development","title":"Local development","text":"

    You can use editable installs to develop the project locally (it will install all the dependencies too):

    python -m pip install -e .\n

    Or you can install all development dependencies (mypy, pylint, pytest, etc.) in one go too: 

    python -m pip install -e .[dev]\n

    If you don't want to install all the dependencies, you can also use nox to run the tests and other checks creating its own virtual environments:

    python -m pip install .[dev-noxfile]\nnox\n

    You can also use nox -R to reuse the current testing environment to speed up test at the expense of a higher chance to end up with a dirty test environment.

    "},{"location":"CONTRIBUTING/#running-tests-checks-individually","title":"Running tests / checks individually","text":"

    For a better development test cycle you can install the runtime and test dependencies and run pytest manually.

    python -m pip install .[dev-pytest]  # included in .[dev] too\n# And for example\npytest tests/test_*.py\n

    Or you can use nox:

    nox -R -s pytest -- test/test_*.py\n

    The same appliest to pylint or mypy for example:

    nox -R -s pylint -- test/test_*.py\nnox -R -s mypy -- test/test_*.py\n
    "},{"location":"CONTRIBUTING/#building-the-documentation","title":"Building the documentation","text":"

    To build the documentation, first install the dependencies (if you didn't install all dev dependencies):

    python -m pip install -e .[dev-mkdocs]\n

    Then you can build the documentation (it will be written in the site/ directory):

    mkdocs build\n

    Or you can just serve the documentation without building it using:

    mkdocs serve\n

    Your site will be updated live when you change your files (provided that you used pip install -e ., beware of a common pitfall of using pip install without -e, in that case the API reference won't change unless you do a new pip install).

    To build multi-version documentation, we use mike. If you want to see how the multi-version sites looks like locally, you can use:

    mike deploy my-version\nmike set-default my-version\nmike serve\n

    mike works in mysterious ways. Some basic information:

    • mike deploy will do a mike build and write the results to your local gh-pages branch. my-version is an arbitrary name for the local version you want to preview.
    • mike set-default is needed so when you serve the documentation, it goes to your newly produced documentation by default.
    • mike serve will serve the contents of your local gh-pages branch. Be aware that, unlike mkdocs serve, changes to the sources won't be shown live, as the mike deploy step is needed to refresh them.

    Be careful not to use --push with mike deploy, otherwise it will push your local gh-pages branch to the origin remote.

    That said, if you want to test the actual website in your fork, you can always use mike deploy --push --remote your-fork-remote, and then access the GitHub pages produced for your fork.

    "},{"location":"CONTRIBUTING/#releasing","title":"Releasing","text":"

    These are the steps to create a new release:

    1. Get the latest head you want to create a release from.

    2. Update the RELEASE_NOTES.md file if it is not complete, up to date, and remove template comments (<!-- ... ->) and empty sections. Submit a pull request if an update is needed, wait until it is merged, and update the latest head you want to create a release from to get the new merged pull request.

    3. Create a new signed tag using the release notes and a semver compatible version number with a v prefix, for example:

    git tag -s --cleanup=whitespace -F RELEASE_NOTES.md v0.0.1\n

    1. Push the new tag.

    2. A GitHub action will test the tag and if all goes well it will create a GitHub Release, and upload a new package to PyPI automatically.

    3. Once this is done, reset the RELEASE_NOTES.md with the template:

    cp .github/RELEASE_NOTES.template.md RELEASE_NOTES.md\n

    Commit the new release notes and create a PR (this step should be automated eventually too).

    1. Celebrate!
    "},{"location":"CONTRIBUTING/#cross-arch-testing","title":"Cross-Arch Testing","text":"

    This project has built-in support for testing across multiple architectures. Currently, our CI conducts tests on arm64 machines using QEMU emulation. We also have the flexibility to expand this support to include additional architectures in the future.

    This project contains Dockerfiles that can be used in the CI to test the python package in non-native machine architectures, e.g., arm64. The Dockerfiles exist in the directory .github/containers/nox-cross-arch, and follow a naming scheme so that they can be easily used in build matrices in the CI, in nox-cross-arch job. The naming scheme is:

    <arch>-<os>-python-<python-version>.Dockerfile\n

    E.g.,

    arm64-ubuntu-20.04-python-3.11.Dockerfile\n

    If a Dockerfile for your desired target architecture, OS, and python version does not exist here, please add one before proceeding to add your options to the test matrix.

    "},{"location":"SUMMARY/","title":"SUMMARY","text":"
    • Home
    • API Reference
    • Contributing
    "},{"location":"reference/SUMMARY/","title":"SUMMARY","text":"
    • frequenz
      • client
        • base
    "},{"location":"reference/frequenz/client/base/","title":"base","text":""},{"location":"reference/frequenz/client/base/#frequenz.client.base","title":"frequenz.client.base","text":"

    Utilities for writing Frequenz API clients.

    TODO(cookiecutter): Add a more descriptive module description.

    "},{"location":"reference/frequenz/client/base/#frequenz.client.base-functions","title":"Functions","text":""},{"location":"reference/frequenz/client/base/#frequenz.client.base.delete_me","title":"frequenz.client.base.delete_me","text":"
    delete_me(*, blow_up: bool = False) -> bool\n

    Do stuff for demonstration purposes.

    PARAMETER DESCRIPTION blow_up

    If True, raise an exception.

    TYPE: bool DEFAULT: False

    RETURNS DESCRIPTION bool

    True if no exception was raised.

    RAISES DESCRIPTION RuntimeError

    if blow_up is True.

    Source code in frequenz/client/base/__init__.py 
    def delete_me(*, blow_up: bool = False) -> bool:\n\"\"\"Do stuff for demonstration purposes.\n    Args:\n        blow_up: If True, raise an exception.\n    Returns:\n        True if no exception was raised.\n    Raises:\n        RuntimeError: if blow_up is True.\n    \"\"\"\nif blow_up:\nraise RuntimeError(\"This function should be removed!\")\nreturn True\n
    "}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Freqenz Client Base Library","text":""},{"location":"#introduction","title":"Introduction","text":"

    Utilities for writing Frequenz API clients

    TODO(cookiecutter): Improve the README file

    "},{"location":"#supported-platforms","title":"Supported Platforms","text":"

    The following platforms are officially supported (tested):

    • Python: 3.11
    • Operating System: Ubuntu Linux 20.04
    • Architectures: amd64, arm64
    "},{"location":"#contributing","title":"Contributing","text":"

    If you want to know how to build this project and contribute to it, please check out the Contributing Guide.

    "},{"location":"CONTRIBUTING/","title":"Contributing to Freqenz Client Base Library","text":""},{"location":"CONTRIBUTING/#build","title":"Build","text":"

    You can use build to simply build the source and binary distribution:

    python -m pip install build\npython -m build\n
    "},{"location":"CONTRIBUTING/#local-development","title":"Local development","text":"

    You can use editable installs to develop the project locally (it will install all the dependencies too):

    python -m pip install -e .\n

    Or you can install all development dependencies (mypy, pylint, pytest, etc.) in one go too: 

    python -m pip install -e .[dev]\n

    If you don't want to install all the dependencies, you can also use nox to run the tests and other checks creating its own virtual environments:

    python -m pip install .[dev-noxfile]\nnox\n

    You can also use nox -R to reuse the current testing environment to speed up test at the expense of a higher chance to end up with a dirty test environment.

    "},{"location":"CONTRIBUTING/#running-tests-checks-individually","title":"Running tests / checks individually","text":"

    For a better development test cycle you can install the runtime and test dependencies and run pytest manually.

    python -m pip install .[dev-pytest]  # included in .[dev] too\n# And for example\npytest tests/test_*.py\n

    Or you can use nox:

    nox -R -s pytest -- test/test_*.py\n

    The same appliest to pylint or mypy for example:

    nox -R -s pylint -- test/test_*.py\nnox -R -s mypy -- test/test_*.py\n
    "},{"location":"CONTRIBUTING/#building-the-documentation","title":"Building the documentation","text":"

    To build the documentation, first install the dependencies (if you didn't install all dev dependencies):

    python -m pip install -e .[dev-mkdocs]\n

    Then you can build the documentation (it will be written in the site/ directory):

    mkdocs build\n

    Or you can just serve the documentation without building it using:

    mkdocs serve\n

    Your site will be updated live when you change your files (provided that you used pip install -e ., beware of a common pitfall of using pip install without -e, in that case the API reference won't change unless you do a new pip install).

    To build multi-version documentation, we use mike. If you want to see how the multi-version sites looks like locally, you can use:

    mike deploy my-version\nmike set-default my-version\nmike serve\n

    mike works in mysterious ways. Some basic information:

    • mike deploy will do a mike build and write the results to your local gh-pages branch. my-version is an arbitrary name for the local version you want to preview.
    • mike set-default is needed so when you serve the documentation, it goes to your newly produced documentation by default.
    • mike serve will serve the contents of your local gh-pages branch. Be aware that, unlike mkdocs serve, changes to the sources won't be shown live, as the mike deploy step is needed to refresh them.

    Be careful not to use --push with mike deploy, otherwise it will push your local gh-pages branch to the origin remote.

    That said, if you want to test the actual website in your fork, you can always use mike deploy --push --remote your-fork-remote, and then access the GitHub pages produced for your fork.

    "},{"location":"CONTRIBUTING/#releasing","title":"Releasing","text":"

    These are the steps to create a new release:

    1. Get the latest head you want to create a release from.

    2. Update the RELEASE_NOTES.md file if it is not complete, up to date, and remove template comments (<!-- ... ->) and empty sections. Submit a pull request if an update is needed, wait until it is merged, and update the latest head you want to create a release from to get the new merged pull request.

    3. Create a new signed tag using the release notes and a semver compatible version number with a v prefix, for example:

    git tag -s --cleanup=whitespace -F RELEASE_NOTES.md v0.0.1\n

    1. Push the new tag.

    2. A GitHub action will test the tag and if all goes well it will create a GitHub Release, and upload a new package to PyPI automatically.

    3. Once this is done, reset the RELEASE_NOTES.md with the template:

    cp .github/RELEASE_NOTES.template.md RELEASE_NOTES.md\n

    Commit the new release notes and create a PR (this step should be automated eventually too).

    1. Celebrate!
    "},{"location":"CONTRIBUTING/#cross-arch-testing","title":"Cross-Arch Testing","text":"

    This project has built-in support for testing across multiple architectures. Currently, our CI conducts tests on arm64 machines using QEMU emulation. We also have the flexibility to expand this support to include additional architectures in the future.

    This project contains Dockerfiles that can be used in the CI to test the python package in non-native machine architectures, e.g., arm64. The Dockerfiles exist in the directory .github/containers/nox-cross-arch, and follow a naming scheme so that they can be easily used in build matrices in the CI, in nox-cross-arch job. The naming scheme is:

    <arch>-<os>-python-<python-version>.Dockerfile\n

    E.g.,

    arm64-ubuntu-20.04-python-3.11.Dockerfile\n

    If a Dockerfile for your desired target architecture, OS, and python version does not exist here, please add one before proceeding to add your options to the test matrix.

    "},{"location":"SUMMARY/","title":"SUMMARY","text":"
    • Home
    • API Reference
    • Contributing
    "},{"location":"reference/SUMMARY/","title":"SUMMARY","text":"
    • frequenz
      • client
        • base
          • grpc_streaming_helper
          • retry_strategy
    "},{"location":"reference/frequenz/client/base/","title":"Index","text":""},{"location":"reference/frequenz/client/base/#frequenz.client.base","title":"frequenz.client.base","text":"

    Utilities for writing Frequenz API clients.

    "},{"location":"reference/frequenz/client/base/grpc_streaming_helper/","title":"grpc_streaming_helper","text":""},{"location":"reference/frequenz/client/base/grpc_streaming_helper/#frequenz.client.base.grpc_streaming_helper","title":"frequenz.client.base.grpc_streaming_helper","text":"

    Implementation of the grpc streaming helper.

    "},{"location":"reference/frequenz/client/base/grpc_streaming_helper/#frequenz.client.base.grpc_streaming_helper-classes","title":"Classes","text":""},{"location":"reference/frequenz/client/base/grpc_streaming_helper/#frequenz.client.base.grpc_streaming_helper.GrpcStreamingHelper","title":"frequenz.client.base.grpc_streaming_helper.GrpcStreamingHelper","text":"

    Bases: Generic[_InputT, _OutputT]

    Helper class to handle grpc streaming methods.

    Source code in frequenz/client/base/grpc_streaming_helper.py 
    class GrpcStreamingHelper(typing.Generic[_InputT, _OutputT]):\n\"\"\"Helper class to handle grpc streaming methods.\"\"\"\ndef __init__(\nself,\nstream_name: str,\nstream_method: typing.Callable[[], UnaryStreamCall[typing.Any, _InputT]],\ntransform: typing.Callable[[_InputT], _OutputT],\nretry_spec: retry_strategy.RetryStrategy | None = None,\n):\n\"\"\"Initialize the streaming helper.\n        Args:\n            stream_name: A name to identify the stream in the logs.\n            stream_method: A function that returns the grpc stream. This function is\n                called everytime the connection is lost and we want to retry.\n            transform: A function to transform the input type to the output type.\n            retry_spec: The retry strategy to use, when the connection is lost. Defaults\n                to retries every 3 seconds, with a jitter of 1 second, indefinitely.\n        \"\"\"\nself._stream_name = stream_name\nself._stream_method = stream_method\nself._transform = transform\nself._retry_spec = (\nretry_strategy.LinearBackoff() if retry_spec is None else retry_spec.copy()\n)\nself._channel: channels.Broadcast[_OutputT] = channels.Broadcast(\nf\"GrpcStreamingHelper-{stream_name}\"\n)\nself._task = asyncio.create_task(self._run())\ndef new_receiver(self, maxsize: int = 50) -> channels.Receiver[_OutputT]:\n\"\"\"Create a new receiver for the stream.\n        Args:\n            maxsize: The maximum number of messages to buffer.\n        Returns:\n            A new receiver.\n        \"\"\"\nreturn self._channel.new_receiver(maxsize=maxsize)\nasync def stop(self) -> None:\n\"\"\"Stop the streaming helper.\"\"\"\nif self._task.done():\nreturn\nself._task.cancel()\ntry:\nawait self._task\nexcept asyncio.CancelledError:\npass\nawait self._channel.close()\nasync def _run(self) -> None:\n\"\"\"Run the streaming helper.\"\"\"\nsender = self._channel.new_sender()\nwhile True:\n_logger.debug(\"Making call to grpc streaming method: %s\", self._stream_name)\ntry:\ncall = self._stream_method()\nasync for msg in call:\nawait sender.send(self._transform(msg))\nexcept grpc.aio.AioRpcError:\n_logger.exception(\n\"Error in grpc streaming method: %s\", self._stream_name\n)\nif interval := self._retry_spec.next_interval():\n_logger.warning(\n\"`%s`, connection ended, retrying %s in %0.3f seconds.\",\nself._stream_name,\nself._retry_spec.get_progress(),\ninterval,\n)\nawait asyncio.sleep(interval)\nelse:\n_logger.warning(\n\"`%s`, connection ended, retry limit exceeded %s.\",\nself._stream_name,\nself._retry_spec.get_progress(),\n)\nawait self._channel.close()\nbreak\n
    "},{"location":"reference/frequenz/client/base/grpc_streaming_helper/#frequenz.client.base.grpc_streaming_helper.GrpcStreamingHelper-functions","title":"Functions","text":""},{"location":"reference/frequenz/client/base/grpc_streaming_helper/#frequenz.client.base.grpc_streaming_helper.GrpcStreamingHelper.__init__","title":"__init__","text":"
    __init__(\nstream_name: str,\nstream_method: typing.Callable[\n[], UnaryStreamCall[typing.Any, _InputT]\n],\ntransform: typing.Callable[[_InputT], _OutputT],\nretry_spec: retry_strategy.RetryStrategy | None = None,\n)\n

    Initialize the streaming helper.

    PARAMETER DESCRIPTION stream_name

    A name to identify the stream in the logs.

    TYPE: str

    stream_method

    A function that returns the grpc stream. This function is called everytime the connection is lost and we want to retry.

    TYPE: Callable[[], UnaryStreamCall[Any, _InputT]]

    transform

    A function to transform the input type to the output type.

    TYPE: Callable[[_InputT], _OutputT]

    retry_spec

    The retry strategy to use, when the connection is lost. Defaults to retries every 3 seconds, with a jitter of 1 second, indefinitely.

    TYPE: RetryStrategy | None DEFAULT: None

    Source code in frequenz/client/base/grpc_streaming_helper.py 
    def __init__(\nself,\nstream_name: str,\nstream_method: typing.Callable[[], UnaryStreamCall[typing.Any, _InputT]],\ntransform: typing.Callable[[_InputT], _OutputT],\nretry_spec: retry_strategy.RetryStrategy | None = None,\n):\n\"\"\"Initialize the streaming helper.\n    Args:\n        stream_name: A name to identify the stream in the logs.\n        stream_method: A function that returns the grpc stream. This function is\n            called everytime the connection is lost and we want to retry.\n        transform: A function to transform the input type to the output type.\n        retry_spec: The retry strategy to use, when the connection is lost. Defaults\n            to retries every 3 seconds, with a jitter of 1 second, indefinitely.\n    \"\"\"\nself._stream_name = stream_name\nself._stream_method = stream_method\nself._transform = transform\nself._retry_spec = (\nretry_strategy.LinearBackoff() if retry_spec is None else retry_spec.copy()\n)\nself._channel: channels.Broadcast[_OutputT] = channels.Broadcast(\nf\"GrpcStreamingHelper-{stream_name}\"\n)\nself._task = asyncio.create_task(self._run())\n
    "},{"location":"reference/frequenz/client/base/grpc_streaming_helper/#frequenz.client.base.grpc_streaming_helper.GrpcStreamingHelper.new_receiver","title":"new_receiver","text":"
    new_receiver(\nmaxsize: int = 50,\n) -> channels.Receiver[_OutputT]\n

    Create a new receiver for the stream.

    PARAMETER DESCRIPTION maxsize

    The maximum number of messages to buffer.

    TYPE: int DEFAULT: 50

    RETURNS DESCRIPTION Receiver[_OutputT]

    A new receiver.

    Source code in frequenz/client/base/grpc_streaming_helper.py 
    def new_receiver(self, maxsize: int = 50) -> channels.Receiver[_OutputT]:\n\"\"\"Create a new receiver for the stream.\n    Args:\n        maxsize: The maximum number of messages to buffer.\n    Returns:\n        A new receiver.\n    \"\"\"\nreturn self._channel.new_receiver(maxsize=maxsize)\n
    "},{"location":"reference/frequenz/client/base/grpc_streaming_helper/#frequenz.client.base.grpc_streaming_helper.GrpcStreamingHelper.stop","title":"stop async","text":"
    stop() -> None\n

    Stop the streaming helper.

    Source code in frequenz/client/base/grpc_streaming_helper.py 
    async def stop(self) -> None:\n\"\"\"Stop the streaming helper.\"\"\"\nif self._task.done():\nreturn\nself._task.cancel()\ntry:\nawait self._task\nexcept asyncio.CancelledError:\npass\nawait self._channel.close()\n
    "},{"location":"reference/frequenz/client/base/retry_strategy/","title":"retry_strategy","text":""},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy","title":"frequenz.client.base.retry_strategy","text":"

    Implementations for retry strategies.

    "},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy-classes","title":"Classes","text":""},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy.ExponentialBackoff","title":"frequenz.client.base.retry_strategy.ExponentialBackoff","text":"

    Bases: RetryStrategy

    Provides methods for calculating the exponential interval between retries.

    Source code in frequenz/client/base/retry_strategy.py 
    class ExponentialBackoff(RetryStrategy):\n\"\"\"Provides methods for calculating the exponential interval between retries.\"\"\"\nDEFAULT_INTERVAL = _DEFAULT_RETRY_INTERVAL\n\"\"\"Default retry interval, in seconds.\"\"\"\nDEFAULT_MAX_INTERVAL = 60.0\n\"\"\"Default maximum retry interval, in seconds.\"\"\"\nDEFAULT_MULTIPLIER = 2.0\n\"\"\"Default multiplier for exponential increment.\"\"\"\n# pylint: disable=too-many-arguments\ndef __init__(\nself,\ninitial_interval: float = DEFAULT_INTERVAL,\nmax_interval: float = DEFAULT_MAX_INTERVAL,\nmultiplier: float = DEFAULT_MULTIPLIER,\njitter: float = _DEFAULT_RETRY_JITTER,\nlimit: int | None = None,\n) -> None:\n\"\"\"Create a `ExponentialBackoff` instance.\n        Args:\n            initial_interval: time to wait for before the first retry, in\n                seconds.\n            max_interval: maximum interval, in seconds.\n            multiplier: exponential increment for interval.\n            jitter: a jitter to add to the retry interval.\n            limit: max number of retries before giving up.  `None` means no\n                limit, and `0` means no retry.\n        \"\"\"\nself._initial = initial_interval\nself._max = max_interval\nself._multiplier = multiplier\nself._jitter = jitter\nself._limit = limit\nself._count = 0\ndef next_interval(self) -> float | None:\n\"\"\"Return the time to wait before the next retry.\n        Returns `None` if the retry limit has been reached, and no more retries\n        are possible.\n        Returns:\n            Time until next retry when below retry limit, and None otherwise.\n        \"\"\"\nif self._limit is not None and self._count >= self._limit:\nreturn None\nself._count += 1\nexp_backoff_interval = self._initial * self._multiplier ** (self._count - 1)\nreturn min(exp_backoff_interval + random.uniform(0.0, self._jitter), self._max)\n
    "},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy.ExponentialBackoff-attributes","title":"Attributes","text":""},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy.ExponentialBackoff.DEFAULT_INTERVAL","title":"DEFAULT_INTERVAL class-attribute instance-attribute","text":"
    DEFAULT_INTERVAL = _DEFAULT_RETRY_INTERVAL\n

    Default retry interval, in seconds.

    "},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy.ExponentialBackoff.DEFAULT_MAX_INTERVAL","title":"DEFAULT_MAX_INTERVAL class-attribute instance-attribute","text":"
    DEFAULT_MAX_INTERVAL = 60.0\n

    Default maximum retry interval, in seconds.

    "},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy.ExponentialBackoff.DEFAULT_MULTIPLIER","title":"DEFAULT_MULTIPLIER class-attribute instance-attribute","text":"
    DEFAULT_MULTIPLIER = 2.0\n

    Default multiplier for exponential increment.

    "},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy.ExponentialBackoff-functions","title":"Functions","text":""},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy.ExponentialBackoff.__init__","title":"__init__","text":"
    __init__(\ninitial_interval: float = DEFAULT_INTERVAL,\nmax_interval: float = DEFAULT_MAX_INTERVAL,\nmultiplier: float = DEFAULT_MULTIPLIER,\njitter: float = _DEFAULT_RETRY_JITTER,\nlimit: int | None = None,\n) -> None\n

    Create a ExponentialBackoff instance.

    PARAMETER DESCRIPTION initial_interval

    time to wait for before the first retry, in seconds.

    TYPE: float DEFAULT: DEFAULT_INTERVAL

    max_interval

    maximum interval, in seconds.

    TYPE: float DEFAULT: DEFAULT_MAX_INTERVAL

    multiplier

    exponential increment for interval.

    TYPE: float DEFAULT: DEFAULT_MULTIPLIER

    jitter

    a jitter to add to the retry interval.

    TYPE: float DEFAULT: _DEFAULT_RETRY_JITTER

    limit

    max number of retries before giving up. None means no limit, and 0 means no retry.

    TYPE: int | None DEFAULT: None

    Source code in frequenz/client/base/retry_strategy.py 
    def __init__(\nself,\ninitial_interval: float = DEFAULT_INTERVAL,\nmax_interval: float = DEFAULT_MAX_INTERVAL,\nmultiplier: float = DEFAULT_MULTIPLIER,\njitter: float = _DEFAULT_RETRY_JITTER,\nlimit: int | None = None,\n) -> None:\n\"\"\"Create a `ExponentialBackoff` instance.\n    Args:\n        initial_interval: time to wait for before the first retry, in\n            seconds.\n        max_interval: maximum interval, in seconds.\n        multiplier: exponential increment for interval.\n        jitter: a jitter to add to the retry interval.\n        limit: max number of retries before giving up.  `None` means no\n            limit, and `0` means no retry.\n    \"\"\"\nself._initial = initial_interval\nself._max = max_interval\nself._multiplier = multiplier\nself._jitter = jitter\nself._limit = limit\nself._count = 0\n
    "},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy.ExponentialBackoff.__iter__","title":"__iter__","text":"
    __iter__() -> Iterator[float]\n

    Return an iterator over the retry intervals.

    YIELDS DESCRIPTION float

    Next retry interval in seconds.

    Source code in frequenz/client/base/retry_strategy.py 
    def __iter__(self) -> Iterator[float]:\n\"\"\"Return an iterator over the retry intervals.\n    Yields:\n        Next retry interval in seconds.\n    \"\"\"\nwhile True:\ninterval = self.next_interval()\nif interval is None:\nbreak\nyield interval\n
    "},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy.ExponentialBackoff.copy","title":"copy","text":"
    copy() -> RetryStrategy\n

    Create a new instance of self.

    RETURNS DESCRIPTION RetryStrategy

    A deepcopy of self.

    Source code in frequenz/client/base/retry_strategy.py 
    def copy(self) -> RetryStrategy:\n\"\"\"Create a new instance of `self`.\n    Returns:\n        A deepcopy of `self`.\n    \"\"\"\nret = deepcopy(self)\nret.reset()\nreturn ret\n
    "},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy.ExponentialBackoff.get_progress","title":"get_progress","text":"
    get_progress() -> str\n

    Return a string denoting the retry progress.

    RETURNS DESCRIPTION str

    String denoting retry progress in the form \"(count/limit)\"

    Source code in frequenz/client/base/retry_strategy.py 
    def get_progress(self) -> str:\n\"\"\"Return a string denoting the retry progress.\n    Returns:\n        String denoting retry progress in the form \"(count/limit)\"\n    \"\"\"\nif self._limit is None:\nreturn f\"({self._count}/\u221e)\"\nreturn f\"({self._count}/{self._limit})\"\n
    "},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy.ExponentialBackoff.next_interval","title":"next_interval","text":"
    next_interval() -> float | None\n

    Return the time to wait before the next retry.

    Returns None if the retry limit has been reached, and no more retries are possible.

    RETURNS DESCRIPTION float | None

    Time until next retry when below retry limit, and None otherwise.

    Source code in frequenz/client/base/retry_strategy.py 
    def next_interval(self) -> float | None:\n\"\"\"Return the time to wait before the next retry.\n    Returns `None` if the retry limit has been reached, and no more retries\n    are possible.\n    Returns:\n        Time until next retry when below retry limit, and None otherwise.\n    \"\"\"\nif self._limit is not None and self._count >= self._limit:\nreturn None\nself._count += 1\nexp_backoff_interval = self._initial * self._multiplier ** (self._count - 1)\nreturn min(exp_backoff_interval + random.uniform(0.0, self._jitter), self._max)\n
    "},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy.ExponentialBackoff.reset","title":"reset","text":"
    reset() -> None\n

    Reset the retry counter.

    To be called as soon as a connection is successful.

    Source code in frequenz/client/base/retry_strategy.py 
    def reset(self) -> None:\n\"\"\"Reset the retry counter.\n    To be called as soon as a connection is successful.\n    \"\"\"\nself._count = 0\n
    "},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy.LinearBackoff","title":"frequenz.client.base.retry_strategy.LinearBackoff","text":"

    Bases: RetryStrategy

    Provides methods for calculating the interval between retries.

    Source code in frequenz/client/base/retry_strategy.py 
    class LinearBackoff(RetryStrategy):\n\"\"\"Provides methods for calculating the interval between retries.\"\"\"\ndef __init__(\nself,\ninterval: float = _DEFAULT_RETRY_INTERVAL,\njitter: float = _DEFAULT_RETRY_JITTER,\nlimit: int | None = None,\n) -> None:\n\"\"\"Create a `LinearBackoff` instance.\n        Args:\n            interval: time to wait for before the next retry, in seconds.\n            jitter: a jitter to add to the retry interval.\n            limit: max number of retries before giving up.  `None` means no\n                limit, and `0` means no retry.\n        \"\"\"\nself._interval = interval\nself._jitter = jitter\nself._limit = limit\nself._count = 0\ndef next_interval(self) -> float | None:\n\"\"\"Return the time to wait before the next retry.\n        Returns `None` if the retry limit has been reached, and no more retries\n        are possible.\n        Returns:\n            Time until next retry when below retry limit, and None otherwise.\n        \"\"\"\nif self._limit is not None and self._count >= self._limit:\nreturn None\nself._count += 1\nreturn self._interval + random.uniform(0.0, self._jitter)\n
    "},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy.LinearBackoff-functions","title":"Functions","text":""},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy.LinearBackoff.__init__","title":"__init__","text":"
    __init__(\ninterval: float = _DEFAULT_RETRY_INTERVAL,\njitter: float = _DEFAULT_RETRY_JITTER,\nlimit: int | None = None,\n) -> None\n

    Create a LinearBackoff instance.

    PARAMETER DESCRIPTION interval

    time to wait for before the next retry, in seconds.

    TYPE: float DEFAULT: _DEFAULT_RETRY_INTERVAL

    jitter

    a jitter to add to the retry interval.

    TYPE: float DEFAULT: _DEFAULT_RETRY_JITTER

    limit

    max number of retries before giving up. None means no limit, and 0 means no retry.

    TYPE: int | None DEFAULT: None

    Source code in frequenz/client/base/retry_strategy.py 
    def __init__(\nself,\ninterval: float = _DEFAULT_RETRY_INTERVAL,\njitter: float = _DEFAULT_RETRY_JITTER,\nlimit: int | None = None,\n) -> None:\n\"\"\"Create a `LinearBackoff` instance.\n    Args:\n        interval: time to wait for before the next retry, in seconds.\n        jitter: a jitter to add to the retry interval.\n        limit: max number of retries before giving up.  `None` means no\n            limit, and `0` means no retry.\n    \"\"\"\nself._interval = interval\nself._jitter = jitter\nself._limit = limit\nself._count = 0\n
    "},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy.LinearBackoff.__iter__","title":"__iter__","text":"
    __iter__() -> Iterator[float]\n

    Return an iterator over the retry intervals.

    YIELDS DESCRIPTION float

    Next retry interval in seconds.

    Source code in frequenz/client/base/retry_strategy.py 
    def __iter__(self) -> Iterator[float]:\n\"\"\"Return an iterator over the retry intervals.\n    Yields:\n        Next retry interval in seconds.\n    \"\"\"\nwhile True:\ninterval = self.next_interval()\nif interval is None:\nbreak\nyield interval\n
    "},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy.LinearBackoff.copy","title":"copy","text":"
    copy() -> RetryStrategy\n

    Create a new instance of self.

    RETURNS DESCRIPTION RetryStrategy

    A deepcopy of self.

    Source code in frequenz/client/base/retry_strategy.py 
    def copy(self) -> RetryStrategy:\n\"\"\"Create a new instance of `self`.\n    Returns:\n        A deepcopy of `self`.\n    \"\"\"\nret = deepcopy(self)\nret.reset()\nreturn ret\n
    "},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy.LinearBackoff.get_progress","title":"get_progress","text":"
    get_progress() -> str\n

    Return a string denoting the retry progress.

    RETURNS DESCRIPTION str

    String denoting retry progress in the form \"(count/limit)\"

    Source code in frequenz/client/base/retry_strategy.py 
    def get_progress(self) -> str:\n\"\"\"Return a string denoting the retry progress.\n    Returns:\n        String denoting retry progress in the form \"(count/limit)\"\n    \"\"\"\nif self._limit is None:\nreturn f\"({self._count}/\u221e)\"\nreturn f\"({self._count}/{self._limit})\"\n
    "},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy.LinearBackoff.next_interval","title":"next_interval","text":"
    next_interval() -> float | None\n

    Return the time to wait before the next retry.

    Returns None if the retry limit has been reached, and no more retries are possible.

    RETURNS DESCRIPTION float | None

    Time until next retry when below retry limit, and None otherwise.

    Source code in frequenz/client/base/retry_strategy.py 
    def next_interval(self) -> float | None:\n\"\"\"Return the time to wait before the next retry.\n    Returns `None` if the retry limit has been reached, and no more retries\n    are possible.\n    Returns:\n        Time until next retry when below retry limit, and None otherwise.\n    \"\"\"\nif self._limit is not None and self._count >= self._limit:\nreturn None\nself._count += 1\nreturn self._interval + random.uniform(0.0, self._jitter)\n
    "},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy.LinearBackoff.reset","title":"reset","text":"
    reset() -> None\n

    Reset the retry counter.

    To be called as soon as a connection is successful.

    Source code in frequenz/client/base/retry_strategy.py 
    def reset(self) -> None:\n\"\"\"Reset the retry counter.\n    To be called as soon as a connection is successful.\n    \"\"\"\nself._count = 0\n
    "},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy.RetryStrategy","title":"frequenz.client.base.retry_strategy.RetryStrategy","text":"

    Bases: ABC

    Interface for implementing retry strategies.

    Source code in frequenz/client/base/retry_strategy.py 
    class RetryStrategy(ABC):\n\"\"\"Interface for implementing retry strategies.\"\"\"\n_limit: int | None\n_count: int\n@abstractmethod\ndef next_interval(self) -> float | None:\n\"\"\"Return the time to wait before the next retry.\n        Returns `None` if the retry limit has been reached, and no more retries\n        are possible.\n        Returns:\n            Time until next retry when below retry limit, and None otherwise.\n        \"\"\"\ndef get_progress(self) -> str:\n\"\"\"Return a string denoting the retry progress.\n        Returns:\n            String denoting retry progress in the form \"(count/limit)\"\n        \"\"\"\nif self._limit is None:\nreturn f\"({self._count}/\u221e)\"\nreturn f\"({self._count}/{self._limit})\"\ndef reset(self) -> None:\n\"\"\"Reset the retry counter.\n        To be called as soon as a connection is successful.\n        \"\"\"\nself._count = 0\ndef copy(self) -> RetryStrategy:\n\"\"\"Create a new instance of `self`.\n        Returns:\n            A deepcopy of `self`.\n        \"\"\"\nret = deepcopy(self)\nret.reset()\nreturn ret\ndef __iter__(self) -> Iterator[float]:\n\"\"\"Return an iterator over the retry intervals.\n        Yields:\n            Next retry interval in seconds.\n        \"\"\"\nwhile True:\ninterval = self.next_interval()\nif interval is None:\nbreak\nyield interval\n
    "},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy.RetryStrategy-functions","title":"Functions","text":""},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy.RetryStrategy.__iter__","title":"__iter__","text":"
    __iter__() -> Iterator[float]\n

    Return an iterator over the retry intervals.

    YIELDS DESCRIPTION float

    Next retry interval in seconds.

    Source code in frequenz/client/base/retry_strategy.py 
    def __iter__(self) -> Iterator[float]:\n\"\"\"Return an iterator over the retry intervals.\n    Yields:\n        Next retry interval in seconds.\n    \"\"\"\nwhile True:\ninterval = self.next_interval()\nif interval is None:\nbreak\nyield interval\n
    "},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy.RetryStrategy.copy","title":"copy","text":"
    copy() -> RetryStrategy\n

    Create a new instance of self.

    RETURNS DESCRIPTION RetryStrategy

    A deepcopy of self.

    Source code in frequenz/client/base/retry_strategy.py 
    def copy(self) -> RetryStrategy:\n\"\"\"Create a new instance of `self`.\n    Returns:\n        A deepcopy of `self`.\n    \"\"\"\nret = deepcopy(self)\nret.reset()\nreturn ret\n
    "},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy.RetryStrategy.get_progress","title":"get_progress","text":"
    get_progress() -> str\n

    Return a string denoting the retry progress.

    RETURNS DESCRIPTION str

    String denoting retry progress in the form \"(count/limit)\"

    Source code in frequenz/client/base/retry_strategy.py 
    def get_progress(self) -> str:\n\"\"\"Return a string denoting the retry progress.\n    Returns:\n        String denoting retry progress in the form \"(count/limit)\"\n    \"\"\"\nif self._limit is None:\nreturn f\"({self._count}/\u221e)\"\nreturn f\"({self._count}/{self._limit})\"\n
    "},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy.RetryStrategy.next_interval","title":"next_interval abstractmethod","text":"
    next_interval() -> float | None\n

    Return the time to wait before the next retry.

    Returns None if the retry limit has been reached, and no more retries are possible.

    RETURNS DESCRIPTION float | None

    Time until next retry when below retry limit, and None otherwise.

    Source code in frequenz/client/base/retry_strategy.py 
    @abstractmethod\ndef next_interval(self) -> float | None:\n\"\"\"Return the time to wait before the next retry.\n    Returns `None` if the retry limit has been reached, and no more retries\n    are possible.\n    Returns:\n        Time until next retry when below retry limit, and None otherwise.\n    \"\"\"\n
    "},{"location":"reference/frequenz/client/base/retry_strategy/#frequenz.client.base.retry_strategy.RetryStrategy.reset","title":"reset","text":"
    reset() -> None\n

    Reset the retry counter.

    To be called as soon as a connection is successful.

    Source code in frequenz/client/base/retry_strategy.py 
    def reset(self) -> None:\n\"\"\"Reset the retry counter.\n    To be called as soon as a connection is successful.\n    \"\"\"\nself._count = 0\n
    "}]} \ No newline at end of file diff --git a/v0.0-dev/sitemap.xml.gz b/v0.0-dev/sitemap.xml.gz index 90019d1..c762303 100644 Binary files a/v0.0-dev/sitemap.xml.gz and b/v0.0-dev/sitemap.xml.gz differ diff --git a/versions.json b/versions.json index e9cd34b..ce74c9f 100644 --- a/versions.json +++ b/versions.json @@ -1 +1,10 @@ -[{"version":"v0.0-dev","title":"v0.0-dev (84f948d)","aliases":["v0-dev","latest-dev"]}] \ No newline at end of file +[ + { + "version": "v0.0-dev", + "title": "v0.0-dev (039d4af)", + "aliases": [ + "latest-dev", + "v0-dev" + ] + } +]