earningscall 1.0.2__py3-none-any.whl → 1.1.1__py3-none-any.whl

earningscall/__init__.py

@@ -1,9 +1,10 @@
-from typing import Optional
+from typing import Dict, Optional, Union
 
 from earningscall.exports import get_company, get_all_companies, get_sp500_companies
 from earningscall.symbols import Symbols, load_symbols
 
 api_key: Optional[str] = None
 enable_requests_cache: bool = True
+retry_strategy: Optional[Dict[str, Union[str, int, float]]] = None
 
 __all__ = ["get_company", "get_all_companies", "get_sp500_companies", "Symbols", "load_symbols"]

earningscall/api.py

@@ -3,18 +3,25 @@ import platform
 import urllib.parse
 import logging
 import os
+import time
 from importlib.metadata import PackageNotFoundError
-from typing import Optional
+from typing import Dict, Optional, Union
 
 import requests
 from requests_cache import CachedSession
 
 import earningscall
+from earningscall.errors import InvalidApiKeyError
 
 log = logging.getLogger(__file__)
 
-DOMAIN = os.environ.get("ECALL_DOMAIN", "earningscall.biz")
+DOMAIN = os.environ.get("EARNINGSCALL_DOMAIN", "earningscall.biz")
 API_BASE = f"https://v2.api.{DOMAIN}"
+DEFAULT_RETRY_STRATEGY: Dict[str, Union[str, int, float]] = {
+    "strategy": "exponential",
+    "base_delay": 1,
+    "max_attempts": 10,
+}
 
 
 def get_api_key():
@@ -81,13 +88,27 @@ def get_headers():
     }
 
 
+def can_retry(response: requests.Response) -> bool:
+    if response.status_code == 429:
+        return True
+    # Check for 5XX errors
+    if response.status_code >= 500 and response.status_code < 600:
+        return True
+    return False
+
+
+def is_success(response: requests.Response) -> bool:
+    # TODO: Do we need to check for 2xx status codes?
+    return response.status_code == 200
+
+
 def do_get(
     path: str,
     use_cache: bool = False,
     **kwargs,
 ) -> requests.Response:
     """
-    Do a GET request to the API.
+    Do a GET request to the API with exponential backoff retry for rate limits.
 
     Args:
         path (str): The path to request.
@@ -105,15 +126,47 @@ def do_get(
     if log.isEnabledFor(logging.DEBUG):
         full_url = f"{url}?{urllib.parse.urlencode(params)}"
         log.debug(f"GET: {full_url}")
-    if use_cache and earningscall.enable_requests_cache:
-        return cache_session().get(url, params=params)
-    else:
-        return requests.get(
-            url,
-            params=params,
-            headers=get_headers(),
-            stream=kwargs.get("stream"),
-        )
+
+    retry_strategy = earningscall.retry_strategy or DEFAULT_RETRY_STRATEGY
+    delay = retry_strategy["base_delay"]
+    max_attempts = int(retry_strategy["max_attempts"])
+
+    for attempt in range(max_attempts):
+        if use_cache and earningscall.enable_requests_cache:
+            response = cache_session().get(url, params=params)
+        else:
+            response = requests.get(
+                url,
+                params=params,
+                headers=get_headers(),
+                stream=kwargs.get("stream"),
+            )
+
+        if is_success(response):
+            return response
+
+        if response.status_code == 401:
+            raise InvalidApiKeyError(
+                "Your API key is invalid. You can get your API key at: https://earningscall.biz/api-key"
+            )
+
+        if not can_retry(response):
+            return response
+
+        if attempt < max_attempts - 1:  # Don't sleep after the last attempt
+            if retry_strategy["strategy"] == "exponential":
+                wait_time = delay * (2**attempt)  # Exponential backoff: 1s -> 2s -> 4s -> 8s -> 16s -> 32s -> 64s
+            elif retry_strategy["strategy"] == "linear":
+                wait_time = delay * (attempt + 1)  # Linear backoff: 1s -> 2s -> 3s -> 4s -> 5s -> 6s -> 7s
+            else:
+                raise ValueError("Invalid retry strategy. Must be one of: 'exponential', 'linear'")
+            # TODO: Should we log a warning here?  Does the customer want to see this log?
+            log.warning(
+                f"Rate limited (429). Retrying in {wait_time} seconds... (Attempt {attempt + 1}/{max_attempts})"
+            )
+            time.sleep(wait_time)
+
+    return response  # Return the last response if all retries failed
 
 
 def get_events(exchange: str, symbol: str):

earningscall/errors.py

@@ -22,3 +22,7 @@ class ClientError(BaseError):
 
 class InsufficientApiAccessError(ClientError):
     pass
+
+
+class InvalidApiKeyError(ClientError):
+    pass

earningscall/symbols.py

@@ -8,7 +8,17 @@ from earningscall.errors import InsufficientApiAccessError
 from earningscall.sectors import sector_to_index, industry_to_index, index_to_sector, index_to_industry
 
 # WARNING: Add new indexes to the *END* of this list
-EXCHANGES_IN_ORDER = ["NYSE", "NASDAQ", "AMEX", "TSX", "TSXV", "OTC", "LSE", "CBOE", "STO"]
+EXCHANGES_IN_ORDER = [
+    "NYSE",
+    "NASDAQ",
+    "AMEX",
+    "TSX",
+    "TSXV",
+    "OTC",
+    "LSE",
+    "CBOE",
+    "STO",
+]
 
 log = logging.getLogger(__file__)
 

{earningscall-1.0.2.dist-info → earningscall-1.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: earningscall
-Version: 1.0.2
+Version: 1.1.1
 Summary: The EarningsCall Python library provides convenient access to the EarningsCall API.  It includes a pre-defined set of classes for API resources that initialize themselves dynamically from API responses.
 Project-URL: Homepage, https://earningscall.biz
 Project-URL: Documentation, https://github.com/EarningsCall/earningscall-python
@@ -32,7 +32,7 @@ License: MIT License
         SOFTWARE.
 License-File: LICENSE
 Keywords: earning call app,earnings call,earnings call api,earnings call app,earnings call transcript api,earnings call transcripts,earnings call transcripts api,earnings calls,earnings transcript api,listen to earnings calls,transcripts,where to listen to earnings calls
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
@@ -41,6 +41,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.8
@@ -55,6 +56,7 @@ Description-Content-Type: text/markdown
 [![Build Status](https://github.com/EarningsCall/earningscall-python/actions/workflows/release.yml/badge.svg?branch=master)](https://github.com/EarningsCall/earningscall-python/actions?query=branch%3Amaster)
 [![Coverage Status](https://coveralls.io/repos/github/EarningsCall/earningscall-python/badge.svg?branch=master)](https://coveralls.io/github/EarningsCall/earningscall-python?branch=master)
 [![PyPI - Downloads](https://img.shields.io/pypi/dm/earningscall?color=blue)](https://pypi.org/project/earningscall/)
+[![GitHub Stars](https://img.shields.io/github/stars/EarningsCall/earningscall-python.svg?style=social&label=Star)](https://github.com/EarningsCall/earningscall-python)
 
 [![Python](https://img.shields.io/badge/Python-14354C?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)
 
@@ -310,3 +312,60 @@ import earningscall
 
 earningscall.enable_requests_cache = False
 ```
+
+### Retry Strategy
+
+The library implements a flexible retry strategy to handle rate limiting and HTTP 5xx errors effectively. By default, it retries with increasing delays: 3 seconds, 6 seconds, 12 seconds, 24 seconds, and finally 48 seconds. If the request fails after five attempts, the library raises an exception.
+
+#### Customizing the Retry Strategy
+
+Depending on your specific requirements, you can adjust the retry strategy. For latency-sensitive applications, consider reducing the base delay and limiting the number of retry attempts. Conversely, for plans with lower rate limits, such as the "Starter" plan, a higher base delay with more retry attempts can improve reliability. For higher-rate-limit plans, such as "Enterprise," a shorter delay and fewer attempts may be more appropriate.
+
+To customize the retry behavior, set the `retry_strategy` variable with the desired parameters:
+
+- **strategy**: "exponential" | "linear" — defines the type of retry strategy (default is "exponential").
+- **base_delay**: float (in seconds) — specifies the delay between retries (default is 1 seconds).
+- **max_attempts**: int — sets the maximum number of total request attempts (default is 10).
+
+#### Default Retry Strategy
+
+Below is the default retry configuration:
+
+```python
+import earningscall
+
+earningscall.retry_strategy = {
+    "strategy": "exponential",
+    "base_delay": 1,
+    "max_attempts": 10,
+}
+```
+
+#### Disabling Retries
+
+To disable retries entirely and limit the request to a single attempt, set `max_attempts` to `1`:
+
+```python
+import earningscall
+
+earningscall.retry_strategy = {
+    "strategy": "exponential",
+    "base_delay": 1,
+    "max_attempts": 1,
+}
+```
+
+#### Linear Retry Strategy
+
+You can switch to a linear retry strategy by setting the `strategy` parameter to "linear":
+
+```python
+import earningscall
+
+earningscall.retry_strategy = {
+    "strategy": "linear",
+    "base_delay": 1,
+    "max_attempts": 3,
+}
+```
+

earningscall-1.1.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+earningscall/__init__.py,sha256=6yPTdUeBrKo4sVVW_hJHduTlQUDTw-30BwV5-2PlzYM,413
+earningscall/api.py,sha256=honHHVfJISlWrikNYNE3CjXAkKJWqCa0Jk4q2cg9v1U,7633
+earningscall/company.py,sha256=Ie3LwW5GjXsy3_it5F25JjHfbU3pW8Zefhpv3IjIk4U,6609
+earningscall/errors.py,sha256=aLgwrrpMmYThYEZjCGOhqS57a-GoC0xj2BdbtJ20sy8,490
+earningscall/event.py,sha256=Jf7KPvpeaF9KkeHe46LbL_HIYLXkyHrs3psq-ZY-bkI,692
+earningscall/exports.py,sha256=YAo3vyX3PTgpKBFYwovVy-9797THrvMrdXWqLEHMtME,1425
+earningscall/sectors.py,sha256=Xd6DLkAQ_fQkC2s-N9pReC8b_M3iy77OoFftoZj9FWY,5114
+earningscall/symbols.py,sha256=NxabgKfZZI1YwDLUwh_MlNgyfkR9VZdcU-LqkGWwi28,6521
+earningscall/transcript.py,sha256=P-CeTYhE5T78SXDHFEJ0AlVUFz2XPxDMtkeiorziBiw,1007
+earningscall/utils.py,sha256=Qx8KhlumUdzyBSZRKMS6vpWlb8MGZpLKA4OffJaMdCE,1032
+earningscall-1.1.1.dist-info/METADATA,sha256=3clQWAU4LnVOmlHgW4YMCXIXlxv_49niY0hZtdqjsRE,15446
+earningscall-1.1.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+earningscall-1.1.1.dist-info/licenses/LICENSE,sha256=ktEB_UcRMg2cQlX9wiDs544xWncWizwS9mEZuGsCLrM,1069
+earningscall-1.1.1.dist-info/RECORD,,

earningscall-1.0.2.dist-info/RECORD

@@ -1,14 +0,0 @@
-earningscall/__init__.py,sha256=0mANmPlE7LEWtOGzV2cmmlPfBIWBWlWRDkyqPHJ1jm8,333
-earningscall/api.py,sha256=SNa07842eWWvVWI6wYGXP9TRDV_0tDE4g0lV_AwnQAs,5508
-earningscall/company.py,sha256=Ie3LwW5GjXsy3_it5F25JjHfbU3pW8Zefhpv3IjIk4U,6609
-earningscall/errors.py,sha256=EA-d6qIYgQs9csp8JptQiAaYoM0M9HhCGJgKA9GAWPg,440
-earningscall/event.py,sha256=Jf7KPvpeaF9KkeHe46LbL_HIYLXkyHrs3psq-ZY-bkI,692
-earningscall/exports.py,sha256=YAo3vyX3PTgpKBFYwovVy-9797THrvMrdXWqLEHMtME,1425
-earningscall/sectors.py,sha256=Xd6DLkAQ_fQkC2s-N9pReC8b_M3iy77OoFftoZj9FWY,5114
-earningscall/symbols.py,sha256=842DO8zfglTvPKb_6QkQwAhIAnxqy_zasijBcY-ctm4,6482
-earningscall/transcript.py,sha256=P-CeTYhE5T78SXDHFEJ0AlVUFz2XPxDMtkeiorziBiw,1007
-earningscall/utils.py,sha256=Qx8KhlumUdzyBSZRKMS6vpWlb8MGZpLKA4OffJaMdCE,1032
-earningscall-1.0.2.dist-info/METADATA,sha256=jXMRbhV7u7vM42arV7ySlEvx1Ms6DbdIoNr-0GjP6lg,13265
-earningscall-1.0.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-earningscall-1.0.2.dist-info/licenses/LICENSE,sha256=ktEB_UcRMg2cQlX9wiDs544xWncWizwS9mEZuGsCLrM,1069
-earningscall-1.0.2.dist-info/RECORD,,