earningscall 1.1.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

earningscall/__init__.py

@@ -1,14 +1,17 @@
 from typing import Dict, Optional, Union
 
-from earningscall.exports import get_company, get_all_companies, get_sp500_companies
+from earningscall.exports import get_company, get_all_companies, get_sp500_companies, get_calendar
 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"]
+__all__ = [
+    "get_company",
+    "get_all_companies",
+    "get_sp500_companies",
+    "Symbols",
+    "load_symbols",
+    "get_calendar",
+]

earningscall/api.py

@@ -1,21 +1,27 @@
 import importlib
-import platform
-import urllib.parse
 import logging
 import os
+import platform
 import time
+import urllib.parse
 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})"
             )
@@ -156,7 +169,18 @@ def do_get(
     return response  # Return the last response if all retries failed
 
 
-def get_events(exchange: str, symbol: str):
+def get_calendar_api_operation(year: int, month: int, day: int) -> dict:
+    params = {
+        "year": str(year),
+        "month": str(month),
+        "day": str(day),
+    }
+    response = do_get("calendar", params=params)
+    response.raise_for_status()
+    return response.json()
+
+
+def get_events(exchange: str, symbol: str) -> Optional[dict]:
     params = {
         "exchange": exchange,
         "symbol": symbol,

earningscall/calendar.py

@@ -0,0 +1,30 @@
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Optional
+
+from dataclasses_json import config
+from dataclasses_json import dataclass_json
+from marshmallow import fields
+
+
+@dataclass_json
+@dataclass
+class CalendarEvent:
+    """
+    CalendarEvent
+    """
+
+    company_name: str
+    exchange: str
+    symbol: str
+    year: int
+    quarter: int
+    transcript_ready: bool
+    conference_date: Optional[datetime] = field(
+        default=None,
+        metadata=config(
+            encoder=lambda date: date.isoformat() if date else None,
+            decoder=lambda date: datetime.fromisoformat(date) if date else None,
+            mm_field=fields.DateTime(format="iso"),
+        ),
+    )

earningscall/errors.py

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

earningscall/exports.py

@@ -1,7 +1,14 @@
-from typing import Optional, Iterator
+import datetime
+from datetime import date, timedelta
+from typing import List, Optional, Iterator
 
-from earningscall.api import get_sp500_companies_txt_file
+import requests
+
+from earningscall import api
+from earningscall.api import get_sp500_companies_txt_file, is_demo_account
+from earningscall.calendar import CalendarEvent
 from earningscall.company import Company
+from earningscall.errors import InsufficientApiAccessError
 from earningscall.symbols import get_symbols
 
 
@@ -43,3 +50,37 @@ def get_sp500_companies() -> Iterator[Company]:
         company_info = get_symbols().lookup_company(ticker_symbol)
         if company_info:
             yield Company(company_info=company_info)
+
+
+def get_calendar(input_date: date) -> List[CalendarEvent]:
+    """
+    Get the earnings event calendar for a given input date.
+
+    :param date input_date: The date to get the calendar for.
+
+    :return: A list of CalendarEvent objects.
+    """
+    if not input_date:
+        raise ValueError("Date is required")
+    if isinstance(input_date, datetime.datetime):
+        input_date = input_date.date()
+    if not isinstance(input_date, date):
+        raise ValueError("Date must be a date object")
+    if input_date < date(2018, 1, 1):
+        raise ValueError("input_date must be greater than or equal to 2018-01-01")
+    # Check if input_date is greater than 30 days from today
+    if input_date > datetime.datetime.now().date() + timedelta(days=30):
+        raise ValueError("input_date must be less than 30 days from today")
+    if is_demo_account() and input_date != date(2025, 1, 10):
+        raise InsufficientApiAccessError(
+            f"\"{input_date}\" requires an API Key for access.  To get your API Key,"
+            f" see: https://earningscall.biz/api-pricing"
+        )
+    try:
+        json_data = api.get_calendar_api_operation(input_date.year, input_date.month, input_date.day)
+        return [CalendarEvent.from_dict(event) for event in json_data]  # type: ignore
+    except requests.exceptions.HTTPError as error:
+        if error.response.status_code == 404:
+            # Calendar Date not found, simply return an empty list
+            return []
+        raise error

{earningscall-1.1.0.dist-info → earningscall-1.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: earningscall
-Version: 1.1.0
+Version: 1.2.0
 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
@@ -260,6 +260,20 @@ print("Downloading audio file for Apple Inc. Q3 2021...")
 audio_file = company.download_audio_file(year=2021, quarter=3, file_name="Apple Q3 2021.mp3")
 ```
 
+## Get Earnings Event Calendar
+
+```python
+from datetime import date
+
+from earningscall import get_calendar
+
+calendar = get_calendar(date(2025, 1, 10))
+
+for event in calendar:
+    print(f"{event.company_name} - Q{event.quarter} {event.year} on: {event.conference_date.astimezone().isoformat()} Transcript Ready: {event.transcript_ready}")
+```
+
+
 ## List All Companies
 
 ```python
@@ -297,7 +311,6 @@ for company in get_sp500_companies():
     print(f"{company.company_info} -- {company.company_info.sector} -- {company.company_info.industry}")
 ```
 
-
 ## Advanced
 
 ### Disable Caching
@@ -324,8 +337,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 +349,8 @@ import earningscall
 
 earningscall.retry_strategy = {
     "strategy": "exponential",
-    "base_delay": 3,
-    "max_attempts": 5,
+    "base_delay": 1,
+    "max_attempts": 10,
 }
 ```
 
@@ -350,7 +363,7 @@ import earningscall
 
 earningscall.retry_strategy = {
     "strategy": "exponential",
-    "base_delay": 3,
+    "base_delay": 1,
     "max_attempts": 1,
 }
 ```

earningscall-1.2.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+earningscall/__init__.py,sha256=J1cBpSRDBivNtYDB-LIMNBZu6rQ3-_1eCY6ACFHlHhE,470
+earningscall/api.py,sha256=zI7XrxC73pJXZX9Qe1te-EKVS3G-0VVz5FBiuFbi-W8,7936
+earningscall/calendar.py,sha256=nQcb0UsVwCDhvvcr7dqdY0PCqdVGohB7JDON7jtbRyM,725
+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=G9eZqX_QydfS5O039Wa0rl4Si3KrC_pGyBZ_cxfUrtI,3147
+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.2.0.dist-info/METADATA,sha256=sPAakzVwnoinfbbe5Wf0QS1mDsd8qH-rotmyVljSOGw,15789
+earningscall-1.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+earningscall-1.2.0.dist-info/licenses/LICENSE,sha256=ktEB_UcRMg2cQlX9wiDs544xWncWizwS9mEZuGsCLrM,1069
+earningscall-1.2.0.dist-info/RECORD,,

earningscall-1.1.0.dist-info/RECORD

@@ -1,14 +0,0 @@
-earningscall/__init__.py,sha256=_7Xxi8zoSt98fDwzSpEfjrxgiJsc7UobZBwtsAbt3Lg,477
-earningscall/api.py,sha256=H4Z_GcD6RnTCkwGE--imCOsySDLkD9qf4Rj5j-dZHkw,7088
-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=NxabgKfZZI1YwDLUwh_MlNgyfkR9VZdcU-LqkGWwi28,6521
-earningscall/transcript.py,sha256=P-CeTYhE5T78SXDHFEJ0AlVUFz2XPxDMtkeiorziBiw,1007
-earningscall/utils.py,sha256=Qx8KhlumUdzyBSZRKMS6vpWlb8MGZpLKA4OffJaMdCE,1032
-earningscall-1.1.0.dist-info/METADATA,sha256=U7DpkmtPIfIRGfpIB5WM77okwWH2XrLxKRI_adOhv1k,15444
-earningscall-1.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-earningscall-1.1.0.dist-info/licenses/LICENSE,sha256=ktEB_UcRMg2cQlX9wiDs544xWncWizwS9mEZuGsCLrM,1069
-earningscall-1.1.0.dist-info/RECORD,,