earningscall 1.1.0__tar.gz → 1.1.1__tar.gz

{earningscall-1.1.0 → earningscall-1.1.1}/.gitignore

@@ -36,4 +36,7 @@ tasks.xml
 
 # Root files
 /.coverage*
-/.mypy_cache/
+/.mypy_cache/
+
+# Downloaded Data from Scripts
+/data

{earningscall-1.1.0 → earningscall-1.1.1}/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Release `1.1.1` - 2025-01-26
+
+* Modify default retry strategy to use 1s base delay and 10 max attempts (necessary for starter plan).
+* Check for HTTP 401 Unauthorized status code from server and raise a helpful error message to the user.
+* Update documentation and example scripts to reflect new retry configuration
+
 ## Release `1.1.0` - 2025-01-26
 
 * Add backoff and retry logic to all API calls.

{earningscall-1.1.0 → earningscall-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: earningscall
-Version: 1.1.0
+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
@@ -324,8 +324,8 @@ Depending on your specific requirements, you can adjust the retry strategy. For
 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 3 seconds).
-- **max_attempts**: int — sets the maximum number of total request attempts (default is 5).
+- **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
 
@@ -336,8 +336,8 @@ import earningscall
 
 earningscall.retry_strategy = {
     "strategy": "exponential",
-    "base_delay": 3,
-    "max_attempts": 5,
+    "base_delay": 1,
+    "max_attempts": 10,
 }
 ```
 
@@ -350,7 +350,7 @@ import earningscall
 
 earningscall.retry_strategy = {
     "strategy": "exponential",
-    "base_delay": 3,
+    "base_delay": 1,
     "max_attempts": 1,
 }
 ```

{earningscall-1.1.0 → earningscall-1.1.1}/README.md

@@ -272,8 +272,8 @@ Depending on your specific requirements, you can adjust the retry strategy. For
 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 3 seconds).
-- **max_attempts**: int — sets the maximum number of total request attempts (default is 5).
+- **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
 
@@ -284,8 +284,8 @@ import earningscall
 
 earningscall.retry_strategy = {
     "strategy": "exponential",
-    "base_delay": 3,
-    "max_attempts": 5,
+    "base_delay": 1,
+    "max_attempts": 10,
 }
 ```
 
@@ -298,7 +298,7 @@ import earningscall
 
 earningscall.retry_strategy = {
     "strategy": "exponential",
-    "base_delay": 3,
+    "base_delay": 1,
     "max_attempts": 1,
 }
 ```

{earningscall-1.1.0 → earningscall-1.1.1}/earningscall/__init__.py

@@ -5,10 +5,6 @@ from earningscall.symbols import Symbols, load_symbols
 
 api_key: Optional[str] = None
 enable_requests_cache: bool = True
-retry_strategy: Dict[str, Union[str, int, float]] = {
-    "strategy": "exponential",
-    "base_delay": 3,
-    "max_attempts": 5,
-}
+retry_strategy: Optional[Dict[str, Union[str, int, float]]] = None
 
 __all__ = ["get_company", "get_all_companies", "get_sp500_companies", "Symbols", "load_symbols"]

{earningscall-1.1.0 → earningscall-1.1.1}/earningscall/api.py

@@ -5,17 +5,23 @@ 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():
@@ -121,8 +127,9 @@ def do_get(
         full_url = f"{url}?{urllib.parse.urlencode(params)}"
         log.debug(f"GET: {full_url}")
 
-    delay = earningscall.retry_strategy["base_delay"]
-    max_attempts = int(earningscall.retry_strategy["max_attempts"])
+    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:
@@ -138,16 +145,22 @@ def do_get(
         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 earningscall.retry_strategy["strategy"] == "exponential":
-                wait_time = delay * (2**attempt)  # Exponential backoff: 3s -> 6s -> 12s -> 24s -> 48s
-            elif earningscall.retry_strategy["strategy"] == "linear":
-                wait_time = delay * (attempt + 1)  # Linear backoff: 3s -> 6s -> 9s -> 12s -> 15s
+            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})"
             )

{earningscall-1.1.0 → earningscall-1.1.1}/earningscall/errors.py

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

{earningscall-1.1.0 → earningscall-1.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "earningscall"
-version = "1.1.0"
+version = "1.1.1"
 description = "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."
 readme = "README.md"
 authors = [{ name = "EarningsCall", email = "dev@earningscall.biz" }]

{earningscall-1.1.0 → earningscall-1.1.1}/scripts/get_all_company_transcripts.py

@@ -1,7 +1,10 @@
+import earningscall  # noqa: F401
 from earningscall import get_company
 
+# earningscall.api_key = "YOUR API KEY HERE"
 
-company = get_company("aapl")  # Lookup Apple, Inc by its ticker symbol, "AAPL"
+
+company = get_company("AAPL")  # Lookup Apple, Inc by its ticker symbol, "AAPL"
 
 print(f"Getting all transcripts for: {company}..")
 

earningscall-1.1.1/scripts/get_all_sp500_transcript_texts.py

@@ -0,0 +1,44 @@
+from datetime import datetime
+import os
+
+import earningscall  # noqa: F401
+from earningscall import get_sp500_companies
+from earningscall.company import Company
+
+# TODO: Set your API key here:
+# earningscall.api_key = "YOUR SECRET API KEY GOES HERE"
+
+directory = "data/transcript_texts"
+os.makedirs(directory, exist_ok=True)
+
+
+def download_transcript_texts(company: Company):
+    print(f"Downloading all transcript texts for: {company}..")
+    for event in company.events():
+        if datetime.now().timestamp() < event.conference_date.timestamp():
+            print(
+                f"* {company.company_info.symbol} Q{event.quarter} {event.year} -- skipping, conference date in the future"
+            )
+            continue
+        file_name = os.path.join(
+            directory,
+            f"{company.company_info.exchange}_{company.company_info.symbol}_{event.year}_Q{event.quarter}.text",
+        )
+        if os.path.exists(file_name):
+            print(f"* {company.company_info.symbol} Q{event.quarter} {event.year} -- already downloaded")
+        else:
+            print(f"* Downloading transcript text for {company.company_info.symbol} Q{event.quarter} {event.year}...")
+            transcript = company.get_transcript(event=event)
+            if transcript:
+                # Save transcript text to file
+                with open(file_name, "w") as fd:
+                    fd.write(transcript.text)
+                print(
+                    f" Downloaded transcript text for {company.company_info.symbol} Q{event.quarter} {event.year} to: {file_name}"
+                )
+            else:
+                print(f" No transcript text found for {company.company_info.symbol} Q{event.quarter} {event.year}")
+
+
+for company in get_sp500_companies():
+    download_transcript_texts(company)

{earningscall-1.1.0 → earningscall-1.1.1}/scripts/get_single_transcript.py

@@ -4,10 +4,9 @@ from earningscall import get_company
 
 
 # TODO: Set your API key here:
-# earningscall.api_key = "YOUR SECRET API KEY GOES HERE"
+# earningscall.api_key = "YOUR API KEY HERE"
 
-
-company = get_company("aapl")
+company = get_company("AAPL")
 
 transcript = company.get_transcript(year=2021, quarter=3, level=2)
 

{earningscall-1.1.0 → earningscall-1.1.1}/tests/test_get_transcript.py

@@ -8,7 +8,7 @@ import earningscall
 from earningscall import get_company
 from earningscall.api import purge_cache
 from earningscall.company import Company
-from earningscall.errors import InsufficientApiAccessError
+from earningscall.errors import InsufficientApiAccessError, InvalidApiKeyError
 from earningscall.event import EarningsEvent
 from earningscall.symbols import clear_symbols, CompanyInfo
 from earningscall.transcript import Transcript
@@ -372,6 +372,20 @@ def test_get_transcript_fails_all_attempts_invalid_retry_strategy():
         company.get_transcript(year=2023, quarter=1, level=1)
 
 
+@responses.activate
+def test_get_company_fails_not_authorized():
+    # Always throttle the caller
+    responses.add(
+        responses.GET,
+        "https://v2.api.earningscall.biz/symbols-v2.txt",
+        body=json.dumps({"error": "Not authorized"}),
+        status=401,
+    )
+    ##
+    with pytest.raises(InvalidApiKeyError):
+        get_company("aapl")
+
+
 # Uncomment and run following code to generate demo-symbols-v2.yaml file
 #
 # import requests