earningscall 1.2.1__tar.gz → 1.3.1__tar.gz

{earningscall-1.2.1 → earningscall-1.3.1}/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## Release `1.3.1` - 2025-07-18
+
+* Update README.md with new slide deck download example.
+
+## Release `1.3.0` - 2025-07-17
+
+* Add `download_slide_deck` function to the `Company` class.
+
 ## Release `1.2.1` - 2025-04-04
 
 * Bugfix: handle case where Q&A section is missing from the transcript for level 4 transcription.

{earningscall-1.2.1 → earningscall-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: earningscall
-Version: 1.2.1
+Version: 1.3.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
@@ -257,7 +257,19 @@ from earningscall import get_company
 company = get_company("aapl")  # Lookup Apple, Inc by its ticker symbol, "AAPL"
 
 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")
+audio_file = company.download_audio_file(year=2021, quarter=3, file_name="Apple-Q3-2021.mp3")
+print(f"Downloaded audio file to: {audio_file}")
+```
+
+## Download Slide Deck
+
+```python
+from earningscall import get_company
+
+company = get_company("MSFT")  # Lookup Microsoft by its ticker symbol, "MSFT"
+
+slide_deck_filename = company.download_slide_deck(year=2025, quarter=1, file_name="Microsoft-Q1-2025-Slides.pdf")
+print(f"Downloaded slide deck to: {slide_deck_filename}")
 ```
 
 ## Get Earnings Event Calendar

{earningscall-1.2.1 → earningscall-1.3.1}/README.md

@@ -205,7 +205,19 @@ from earningscall import get_company
 company = get_company("aapl")  # Lookup Apple, Inc by its ticker symbol, "AAPL"
 
 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")
+audio_file = company.download_audio_file(year=2021, quarter=3, file_name="Apple-Q3-2021.mp3")
+print(f"Downloaded audio file to: {audio_file}")
+```
+
+## Download Slide Deck
+
+```python
+from earningscall import get_company
+
+company = get_company("MSFT")  # Lookup Microsoft by its ticker symbol, "MSFT"
+
+slide_deck_filename = company.download_slide_deck(year=2025, quarter=1, file_name="Microsoft-Q1-2025-Slides.pdf")
+print(f"Downloaded slide deck to: {slide_deck_filename}")
 ```
 
 ## Get Earnings Event Calendar

{earningscall-1.2.1 → earningscall-1.3.1}/earningscall/api.py

@@ -1,10 +1,9 @@
-import importlib
+import importlib.metadata
 import logging
 import os
 import platform
 import time
 import urllib.parse
-from importlib.metadata import PackageNotFoundError
 from typing import Dict, Optional, Union
 
 import requests
@@ -65,7 +64,7 @@ def purge_cache():
 def get_earnings_call_version():
     try:
         return importlib.metadata.version("earningscall")
-    except PackageNotFoundError:
+    except importlib.metadata.PackageNotFoundError:
         return None
 
 
@@ -164,7 +163,7 @@ def do_get(
             log.warning(
                 f"Rate limited (429). Retrying in {wait_time} seconds... (Attempt {attempt + 1}/{max_attempts})"
             )
-            time.sleep(wait_time)
+            time.sleep(float(wait_time))
 
     return response  # Return the last response if all retries failed
 
@@ -266,3 +265,36 @@ def download_audio_file(
             for chunk in response.iter_content(chunk_size=8192):
                 f.write(chunk)
     return local_filename
+
+
+def download_slide_deck(
+    exchange: str,
+    symbol: str,
+    year: int,
+    quarter: int,
+    file_name: Optional[str] = None,
+) -> Optional[str]:
+    """
+    Get the slide deck for a given exchange, symbol, year, and quarter.
+
+    :param str exchange: The exchange to get the slide deck for.
+    :param str symbol: The symbol to get the slide deck for.
+    :param int year: The 4-digit year to get the slide deck for.
+    :param int quarter: The quarter to get the slide deck for (1, 2, 3, or 4).
+    :param file_name: Optionally specify the filename to save the slide deck to.
+    :return: The filename of the downloaded slide deck file.
+    :rtype Optional[str]: The filename of the downloaded slide deck file.
+    """
+    params = {
+        "exchange": exchange,
+        "symbol": symbol,
+        "year": str(year),
+        "quarter": str(quarter),
+    }
+    local_filename = file_name or f"{exchange}_{symbol}_{year}_{quarter}_slides.pdf"
+    with do_get("slides", params=params, stream=True) as response:
+        response.raise_for_status()
+        with open(local_filename, "wb") as f:
+            for chunk in response.iter_content(chunk_size=8192):
+                f.write(chunk)
+    return local_filename

{earningscall-1.2.1 → earningscall-1.3.1}/earningscall/company.py

@@ -164,3 +164,51 @@ class Company:
                 log.error(error_message)
                 raise InsufficientApiAccessError(error_message)
             raise error
+
+    def download_slide_deck(
+        self,
+        year: Optional[int] = None,
+        quarter: Optional[int] = None,
+        event: Optional[EarningsEvent] = None,
+        file_name: Optional[str] = None,
+    ) -> Optional[str]:
+        """
+        Download the slide deck for a given year and quarter.
+
+        :param Optional[int] year: The year to get the slide deck for.
+        :param Optional[int] quarter: The quarter to get the slide deck for.
+        :param Optional[EarningsEvent] event: The event to get the slide deck for.
+        :param Optional[str] file_name: The file name to save the slide deck to.
+
+        :return: The filename of the downloaded slide deck file.
+        """
+        if not self.company_info.exchange or not self.company_info.symbol:
+            return None
+        if (not year or not quarter) and event:
+            year = event.year
+            quarter = event.quarter
+        if not year or not quarter:
+            raise ValueError("Must specify either event or year and quarter")
+        if quarter < 1 or quarter > 4:
+            raise ValueError("Invalid quarter. Must be one of: {1,2,3,4}")
+        try:
+            resp = api.download_slide_deck(
+                exchange=self.company_info.exchange,
+                symbol=self.company_info.symbol,
+                year=year,
+                quarter=quarter,
+                file_name=file_name,
+            )
+            return resp
+        except requests.exceptions.HTTPError as error:
+            if error.response.status_code == 404:
+                return None
+            if error.response.status_code == 403:
+                plan_name = error.response.headers["X-Plan-Name"]
+                error_message = (
+                    f"Your plan ({plan_name}) does not include Slide Decks. "
+                    "Upgrade your plan here: https://earningscall.biz/api-pricing"
+                )
+                log.error(error_message)
+                raise InsufficientApiAccessError(error_message)
+            raise error

{earningscall-1.2.1 → earningscall-1.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "earningscall"
-version = "1.2.1"
+version = "1.3.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.3.1/scripts/download_slides.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+"""
+Script to download slides for a given company and quarter
+"""
+
+import earningscall
+
+
+def test_slides_api():
+    """Test the new slides API functionality"""
+
+    # Get a company
+    company = earningscall.get_company("MSFT")
+    if not company:
+        print("Could not find MSFT company")
+        return
+
+    print(f"Testing slides API for {company.company_info.name}")
+
+    try:
+        # Try to download slides for Q1 2025 (using demo data)
+        slide_file = company.download_slide_deck(year=2025, quarter=1)
+        if slide_file:
+            print(f"Successfully downloaded slides: {slide_file}")
+        else:
+            print("No slides available for the requested quarter")
+
+    except Exception as e:
+        print(f"Error downloading slides: {e}")
+        # This is expected for demo account or if slides aren't available
+
+
+if __name__ == "__main__":
+    test_slides_api()

earningscall-1.3.1/tests/data/meta-q3-2024-slides-not-authorized.yaml

@@ -0,0 +1,15 @@
+responses:
+- response:
+    auto_calculate_content_length: false
+    body: ''
+    content_type: text/plain
+    headers:
+      Transfer-Encoding: chunked
+      Via: 1.1 dda997f5acee0f79dcf70db4a17d82f6.cloudfront.net (CloudFront)
+      X-Amz-Cf-Id: hHQoX1-pbWB6rw1QN1G5grABhjXtX_cdjfpnR4lkIU4ypiZRBRk4kQ==
+      X-Amz-Cf-Pop: IAH50-C4
+      X-Cache: Error from cloudfront
+      X-Plan-Name: basic
+    method: GET
+    status: 403
+    url: https://v2.api.earningscall.biz/slides?apikey=foobar&exchange=NASDAQ&symbol=META&year=2024&quarter=3 

earningscall-1.3.1/tests/data/meta-q3-2024-slides-not-found.yaml

@@ -0,0 +1,16 @@
+responses:
+- response:
+    auto_calculate_content_length: false
+    body: '<?xml version="1.0" encoding="UTF-8"?>
+
+      <Error><Code>NoSuchKey</Code><Message>The specified key does not exist.</Message><Key>404.html</Key><RequestId>C1SFD1W2WXC0JHHC</RequestId><HostId>Fp+yajCTsxImKV1EaTFJ7C9i+jpeNUy1t4FcY8Iq0B3Z8js6baJPx4qhYaTECecl8jiD85Odqoc=</HostId></Error>'
+    content_type: text/plain
+    headers:
+      Transfer-Encoding: chunked
+      Via: 1.1 dda997f5acee0f79dcf70db4a17d82f6.cloudfront.net (CloudFront)
+      X-Amz-Cf-Id: hHQoX1-pbWB6rw1QN1G5grABhjXtX_cdjfpnR4lkIU4ypiZRBRk4kQ==
+      X-Amz-Cf-Pop: IAH50-C4
+      X-Cache: Error from cloudfront
+    method: GET
+    status: 404
+    url: https://v2.api.earningscall.biz/slides?apikey=foobar&exchange=NASDAQ&symbol=META&year=2024&quarter=3 

earningscall-1.3.1/tests/data/meta-q3-2024-slides-other-error.yaml

@@ -0,0 +1,15 @@
+responses:
+- response:
+    auto_calculate_content_length: false
+    body: ''
+    content_type: text/plain
+    headers:
+      Transfer-Encoding: chunked
+      Via: 1.1 dda997f5acee0f79dcf70db4a17d82f6.cloudfront.net (CloudFront)
+      X-Amz-Cf-Id: hHQoX1-pbWB6rw1QN1G5grABhjXtX_cdjfpnR4lkIU4ypiZRBRk4kQ==
+      X-Amz-Cf-Pop: IAH50-C4
+      X-Cache: Error from cloudfront
+      X-Plan-Name: basic
+    method: GET
+    status: 500
+    url: https://v2.api.earningscall.biz/slides?apikey=foobar&exchange=NASDAQ&symbol=META&year=2024&quarter=3 

earningscall-1.3.1/tests/data/msft-q1-2022-slide-deck-short-clip.yaml

@@ -0,0 +1,62 @@
+responses:
+- response:
+    auto_calculate_content_length: false
+    body: '%PDF-1.4
+1 0 obj
+<<
+/Type /Catalog
+/Pages 2 0 R
+>>
+endobj
+2 0 obj
+<<
+/Type /Pages
+/Kids [3 0 R]
+/Count 1
+>>
+endobj
+3 0 obj
+<<
+/Type /Page
+/Parent 2 0 R
+/MediaBox [0 0 612 792]
+/Contents 4 0 R
+>>
+endobj
+4 0 obj
+<<
+/Length 44
+>>
+stream
+BT
+/F1 12 Tf
+100 700 Td
+(Test Slide Deck) Tj
+ET
+endstream
+endobj
+xref
+0 5
+0000000000 65535 f 
+0000000009 00000 n 
+0000000058 00000 n 
+0000000115 00000 n 
+0000000208 00000 n 
+trailer
+<<
+/Size 5
+/Root 1 0 R
+>>
+startxref
+299
+%%EOF'
+    content_type: application/pdf
+    headers:
+      Transfer-Encoding: chunked
+      Via: 1.1 dda997f5acee0f79dcf70db4a17d82f6.cloudfront.net (CloudFront)
+      X-Amz-Cf-Id: hHQoX1-pbWB6rw1QN1G5grABhjXtX_cdjfpnR4lkIU4ypiZRBRk4kQ==
+      X-Amz-Cf-Pop: IAH50-C4
+      X-Cache: Hit from cloudfront
+    method: GET
+    status: 200
+    url: https://v2.api.earningscall.biz/slides?apikey=demo&exchange=NASDAQ&symbol=MSFT&year=2022&quarter=1 

earningscall-1.3.1/tests/test_download_slide_decks.py

@@ -0,0 +1,147 @@
+import os
+
+import pytest
+import responses
+from requests import HTTPError
+
+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.event import EarningsEvent
+from earningscall.symbols import CompanyInfo, clear_symbols
+from earningscall.utils import data_path
+
+
+@pytest.fixture(autouse=True)
+def run_before_and_after_tests():
+    """Fixture to execute asserts before and after a test is run"""
+    # Setup: fill with any logic you want
+    earningscall.api_key = None
+    earningscall.retry_strategy = {
+        "strategy": "exponential",
+        "base_delay": 0.001,
+        "max_attempts": 3,
+    }
+    purge_cache()
+    clear_symbols()
+    yield  # this is where the testing happens
+    # Teardown : fill with any logic you want
+    earningscall.api_key = None
+
+
+@responses.activate
+def test_download_slide_deck():
+    ##
+    responses._add_from_file(file_path=data_path("symbols-v2.yaml"))
+    responses._add_from_file(file_path=data_path("msft-q1-2022-slide-deck-short-clip.yaml"))
+    responses._add_from_file(file_path=data_path("msft-company-events.yaml"))
+    ##
+    company = get_company("msft")
+    file_name = company.download_slide_deck(year=2022, quarter=1)
+    #
+    assert os.path.exists(file_name)
+    assert os.path.getsize(file_name) > 0
+    # Check that it's a PDF file (starts with %PDF)
+    with open(file_name, 'rb') as f:
+        assert f.read(4) == b'%PDF'
+    os.unlink(file_name)
+
+
+@responses.activate
+def test_download_slide_deck_event():
+    ##
+    responses._add_from_file(file_path=data_path("symbols-v2.yaml"))
+    responses._add_from_file(file_path=data_path("msft-q1-2022-slide-deck-short-clip.yaml"))
+    responses._add_from_file(file_path=data_path("msft-company-events.yaml"))
+    ##
+    company = get_company("msft")
+    file_name = company.download_slide_deck(event=EarningsEvent(year=2022, quarter=1))
+    #
+    assert os.path.exists(file_name)
+    assert os.path.getsize(file_name) > 0
+    # Check that it's a PDF file (starts with %PDF)
+    with open(file_name, 'rb') as f:
+        assert f.read(4) == b'%PDF'
+    os.unlink(file_name)
+
+
+@responses.activate
+def test_download_slide_deck_missing_params_raises_value_error():
+    ##
+    responses._add_from_file(file_path=data_path("symbols-v2.yaml"))
+    ##
+    company = get_company("msft")
+    with pytest.raises(ValueError):
+        company.download_slide_deck()
+    with pytest.raises(ValueError):
+        company.download_slide_deck(year=2023)
+    with pytest.raises(ValueError):
+        company.download_slide_deck(quarter=1)
+    with pytest.raises(ValueError):
+        company.download_slide_deck(quarter=0)
+    with pytest.raises(ValueError):
+        company.download_slide_deck(year=2023, quarter=5)
+    ##
+    invalid_company = Company(company_info=CompanyInfo())
+    slide_deck = invalid_company.download_slide_deck(year=2023, quarter=1)
+    ##
+    assert slide_deck is None
+
+
+@responses.activate
+def test_download_slide_deck_missing_from_server():
+    ##
+    earningscall.api_key = "foobar"  # Set to a bogus API Key.
+    responses._add_from_file(file_path=data_path("symbols-v2.yaml"))
+    responses._add_from_file(file_path=data_path("meta-q3-2024-slides-not-found.yaml"))
+    ##
+    company = get_company("meta")
+    output_file = company.download_slide_deck(year=2024, quarter=3)
+    ##
+    assert output_file is None
+
+
+@responses.activate
+def test_download_slide_deck_not_authorized():
+    ##
+    earningscall.api_key = "foobar"  # Set to a bogus API Key.
+    responses._add_from_file(file_path=data_path("symbols-v2.yaml"))
+    responses._add_from_file(file_path=data_path("meta-q3-2024-slides-not-authorized.yaml"))
+    ##
+    company = get_company("meta")
+    with pytest.raises(InsufficientApiAccessError):
+        company.download_slide_deck(year=2024, quarter=3)
+
+
+@responses.activate
+def test_download_slide_deck_500_error():
+    ##
+    earningscall.api_key = "foobar"  # Set to a bogus API Key.
+    responses._add_from_file(file_path=data_path("symbols-v2.yaml"))
+    responses._add_from_file(file_path=data_path("meta-q3-2024-slides-other-error.yaml"))
+    ##
+    company = get_company("meta")
+    with pytest.raises(HTTPError):
+        company.download_slide_deck(year=2024, quarter=3)
+
+
+@responses.activate
+def test_download_slide_deck_custom_filename():
+    ##
+    responses._add_from_file(file_path=data_path("symbols-v2.yaml"))
+    responses._add_from_file(file_path=data_path("msft-q1-2022-slide-deck-short-clip.yaml"))
+    responses._add_from_file(file_path=data_path("msft-company-events.yaml"))
+    ##
+    company = get_company("msft")
+    custom_filename = "test_custom_slides.pdf"
+    file_name = company.download_slide_deck(year=2022, quarter=1, file_name=custom_filename)
+    #
+    assert file_name == custom_filename
+    assert os.path.exists(file_name)
+    assert os.path.getsize(file_name) > 0
+    # Check that it's a PDF file (starts with %PDF)
+    with open(file_name, 'rb') as f:
+        assert f.read(4) == b'%PDF'
+    os.unlink(file_name)