earningscall 0.0.17__py3-none-any.whl → 0.0.19__py3-none-any.whl

earningscall/api.py

@@ -1,3 +1,4 @@
+import importlib
 import logging
 import os
 from typing import Optional
@@ -11,13 +12,13 @@ log = logging.getLogger(__file__)
 
 DOMAIN = os.environ.get("ECALL_DOMAIN", "earningscall.biz")
 API_BASE = f"https://v2.api.{DOMAIN}"
+EARNINGS_CALL_VERSION = importlib.metadata.version("earningscall")
 
 
 def get_api_key():
-    api_key = earningscall.api_key
-    if not api_key:
-        return os.environ.get("ECALL_API_KEY", "demo")
-    return api_key
+    if earningscall.api_key:
+        return earningscall.api_key
+    return os.environ.get("ECALL_API_KEY", "demo")
 
 
 def api_key_param():
@@ -46,7 +47,29 @@ def purge_cache():
     return cache_session().cache.clear()
 
 
-def do_get(path: str, use_cache: bool = False, **kwargs):
+def get_headers():
+    return {
+        "User-Agent": f"EarningsCall Python/{EARNINGS_CALL_VERSION}",
+        "X-EarningsCall-Version": EARNINGS_CALL_VERSION,
+    }
+
+
+def do_get(
+    path: str,
+    use_cache: bool = False,
+    **kwargs,
+) -> requests.Response:
+    """
+    Do a GET request to the API.
+
+    Args:
+        path (str): The path to request.
+        use_cache (bool): Whether to use the cache.
+        **kwargs: Additional arguments to pass to the request.
+
+    Returns:
+        requests.Response: The response from the API.
+    """
     params = {
         **api_key_param(),
         **kwargs.get("params", {}),
@@ -56,7 +79,12 @@ def do_get(path: str, use_cache: bool = False, **kwargs):
     if use_cache and earningscall.enable_requests_cache:
         return cache_session().get(url, params=params)
     else:
-        return requests.get(url, params=params)
+        return requests.get(
+            url,
+            params=params,
+            headers=get_headers(),
+            stream=kwargs.get("stream"),
+        )
 
 
 def get_events(exchange: str, symbol: str):
@@ -72,19 +100,35 @@ def get_events(exchange: str, symbol: str):
     return response.json()
 
 
-def get_transcript(exchange: str, symbol: str, year: int, quarter: int) -> Optional[str]:
-
-    log.debug(f"get_transcript year: {year} quarter: {quarter}")
+def get_transcript(
+    exchange: str,
+    symbol: str,
+    year: int,
+    quarter: int,
+    level: Optional[int] = None,
+) -> Optional[dict]:
+    """
+    Get the transcript for a given exchange, symbol, year, and quarter.
+
+    :param str exchange: The exchange to get the transcript for.
+    :param str symbol: The symbol to get the transcript for.
+    :param int year: The year to get the transcript for.
+    :param int quarter: The quarter to get the transcript for.
+    :param Optional[int] level: The level to get the transcript for.
+
+    :return: The transcript for the given exchange, symbol, year, and quarter.
+    """
+    log.debug(f"get_transcript exchange: {exchange} symbol: {symbol} year: {year} quarter: {quarter} level: {level}")
     params = {
         **api_key_param(),
         "exchange": exchange,
         "symbol": symbol,
         "year": str(year),
         "quarter": str(quarter),
+        "level": str(level or 1),
     }
     response = do_get("transcript", params=params)
-    if response.status_code != 200:
-        return None
+    response.raise_for_status()
     return response.json()
 
 
@@ -102,3 +146,37 @@ def get_sp500_companies_txt_file():
     if response.status_code != 200:
         return None
     return response.text
+
+
+def download_audio_file(
+    exchange: str,
+    symbol: str,
+    year: int,
+    quarter: int,
+    file_name: Optional[str] = None,
+) -> Optional[str]:
+    """
+    Get the audio for a given exchange, symbol, year, and quarter.
+
+    :param str exchange: The exchange to get the audio for.
+    :param str symbol: The symbol to get the audio for.
+    :param int year: The 4-digit year to get the audio for.
+    :param int quarter: The quarter to get the audio for (1, 2, 3, or 4).
+    :param file_name: Optionally specify the filename to save the audio to.
+    :return: The filename of the downloaded audio file.
+    :rtype Optional[str]: The filename of the downloaded audio file.
+    """
+    params = {
+        **api_key_param(),
+        "exchange": exchange,
+        "symbol": symbol,
+        "year": str(year),
+        "quarter": str(quarter),
+    }
+    local_filename = file_name or f"{exchange}_{symbol}_{year}_{quarter}.mp3"
+    with do_get("audio", 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/company.py

@@ -1,7 +1,10 @@
 import logging
 from typing import Optional, List
 
+import requests
+
 from earningscall import api
+from earningscall.errors import InsufficientApiAccessError
 from earningscall.event import EarningsEvent
 from earningscall.symbols import CompanyInfo
 from earningscall.transcript import Transcript
@@ -10,6 +13,9 @@ log = logging.getLogger(__file__)
 
 
 class Company:
+    """
+    A class representing a company.
+    """
 
     company_info: CompanyInfo
     name: Optional[str]
@@ -39,17 +45,115 @@ class Company:
         return self._events
 
     def get_transcript(
-        self, year: Optional[int] = None, quarter: Optional[int] = None, event: Optional[EarningsEvent] = None
+        self,
+        year: Optional[int] = None,
+        quarter: Optional[int] = None,
+        event: Optional[EarningsEvent] = None,
+        level: Optional[int] = None,
     ) -> Optional[Transcript]:
+        """
+        Get the transcript for a given year and quarter.
+
+        :param Optional[int] year: The year to get the transcript for.
+        :param Optional[int] quarter: The quarter to get the transcript for.
+        :param Optional[EarningsEvent] event: The event to get the transcript for.
+        :param Optional[int] level: The transcript level to retrieve.  Default: 1
 
+        :return: The transcript for the given year and quarter.
+        """
         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) and not event:
+        if not year or not quarter:
             raise ValueError("Must specify either event or year and quarter")
-        resp = api.get_transcript(self.company_info.exchange, self.company_info.symbol, year, quarter)  # type: ignore
-        if not resp:
+        if quarter < 1 or quarter > 4:
+            raise ValueError("Invalid level. Must be one of: {1,2,3,4}")
+        if level is None:
+            level = 1
+        if type(level) is not int or level <= 0 or level > 4:
+            raise ValueError(f"Invalid level: {level}. Must be one of: 1, 2, 3, or 4.")
+        try:
+            response_payload = api.get_transcript(
+                self.company_info.exchange,
+                self.company_info.symbol,
+                year,
+                quarter,
+                level=level,
+            )
+            # TODO: Investigate alternatives to @dataclass for level 3 transcripts, as this is
+            #       extremely slow.
+            transcript = Transcript.from_dict(response_payload)  # type: ignore
+            if level == 3:
+                for speaker in transcript.speakers:
+                    speaker.text = " ".join(speaker.words)
+            if 2 <= level <= 3:
+                transcript.text = " ".join(map(lambda spk: spk.text, transcript.speakers))
+            elif level == 4:
+                transcript.text = " ".join([transcript.prepared_remarks, transcript.questions_and_answers])
+            return transcript
+        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.get("X-Plan-Name", "unknown")
+                if 2 <= level <= 4:
+                    error_message = (
+                        f"Your plan ({plan_name}) does not include Advanced Transcript Data. "
+                        "Upgrade your plan here: https://earningscall.biz/api-pricing"
+                    )
+                else:
+                    error_message = f"Unexpected error code was returned from the server.  Your plan is: {plan_name}"
+                log.error(error_message)
+                raise InsufficientApiAccessError(error_message)
+            raise error
+
+    def download_audio_file(
+        self,
+        year: Optional[int] = None,
+        quarter: Optional[int] = None,
+        event: Optional[EarningsEvent] = None,
+        file_name: Optional[str] = None,
+    ) -> Optional[str]:
+        """
+        Download the audio file for a given year and quarter.
+
+        :param Optional[int] year: The year to get the audio for.
+        :param Optional[int] quarter: The quarter to get the audio for.
+        :param Optional[EarningsEvent] event: The event to get the audio for.
+        :param Optional[str] file_name: The file name to save the audio to.
+
+        :return: The audio for the given year and quarter.
+        """
+        log.info(f"Downloading audio file for {self.company_info.symbol} {event}")
+        if not self.company_info.exchange or not self.company_info.symbol:
             return None
-        return Transcript.from_dict(resp)  # type: ignore
+        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 level. Must be one of: {1,2,3,4}")
+        try:
+            resp = api.download_audio_file(
+                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 Audio Files. "
+                    "Upgrade your plan here: https://earningscall.biz/api-pricing"
+                )
+                log.error(error_message)
+                raise InsufficientApiAccessError(error_message)
+            raise error

earningscall/symbols.py

@@ -8,7 +8,7 @@ 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"]
+EXCHANGES_IN_ORDER = ["NYSE", "NASDAQ", "AMEX", "TSX", "TSXV", "OTC", "LSE"]
 
 log = logging.getLogger(__file__)
 

earningscall/transcript.py

@@ -1,17 +1,25 @@
-import logging
 from dataclasses import dataclass, field
-from typing import Optional
+from typing import List, Optional
 
 from dataclasses_json import dataclass_json
 
 from earningscall.event import EarningsEvent
 
-log = logging.getLogger(__file__)
+
+@dataclass_json
+@dataclass
+class Speaker:
+    speaker: str
+    text: Optional[str] = field(default=None)
+    words: Optional[List[str]] = field(default=None)
+    start_times: Optional[List[float]] = field(default=None)
 
 
 @dataclass_json
 @dataclass
 class Transcript:
-
-    text: str
+    text: Optional[str] = field(default=None)
     event: Optional[EarningsEvent] = field(default=None)
+    speakers: Optional[List[Speaker]] = field(default=None)
+    prepared_remarks: Optional[str] = field(default=None)
+    questions_and_answers: Optional[str] = field(default=None)

{earningscall-0.0.17.dist-info → earningscall-0.0.19.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: earningscall
-Version: 0.0.17
+Version: 0.0.19
 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

earningscall-0.0.19.dist-info/RECORD

@@ -0,0 +1,14 @@
+earningscall/__init__.py,sha256=0mANmPlE7LEWtOGzV2cmmlPfBIWBWlWRDkyqPHJ1jm8,333
+earningscall/api.py,sha256=jxf2M8A0VHhr2x0IK2R3PD_enKzA-YvrJ9kBZ2YBxIM,4956
+earningscall/company.py,sha256=aae_GjA1ffz3wYY0vGvPQ71VpYwRGXU6psurwDdgNuU,6431
+earningscall/errors.py,sha256=EA-d6qIYgQs9csp8JptQiAaYoM0M9HhCGJgKA9GAWPg,440
+earningscall/event.py,sha256=Jf7KPvpeaF9KkeHe46LbL_HIYLXkyHrs3psq-ZY-bkI,692
+earningscall/exports.py,sha256=i9UWHY6Lq1OzZTZX_1SdNzrNd_PSlPwpB337lGMK4oM,837
+earningscall/sectors.py,sha256=Xd6DLkAQ_fQkC2s-N9pReC8b_M3iy77OoFftoZj9FWY,5114
+earningscall/symbols.py,sha256=39tL7oP1HT8BturwKW7mgS33dX2Y_X8cw5GKK0aV02k,6354
+earningscall/transcript.py,sha256=Sm--ruKTEhkHiZSPP4I1njUgQNx_SfEIuQqjlTpLBh0,718
+earningscall/utils.py,sha256=Qx8KhlumUdzyBSZRKMS6vpWlb8MGZpLKA4OffJaMdCE,1032
+earningscall-0.0.19.dist-info/METADATA,sha256=gU0XJGI8Q0L--cF7oMSQVVlKfrVqXuPxlSAHpFFgiYU,7177
+earningscall-0.0.19.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+earningscall-0.0.19.dist-info/licenses/LICENSE,sha256=ktEB_UcRMg2cQlX9wiDs544xWncWizwS9mEZuGsCLrM,1069
+earningscall-0.0.19.dist-info/RECORD,,

earningscall-0.0.17.dist-info/RECORD

@@ -1,14 +0,0 @@
-earningscall/__init__.py,sha256=0mANmPlE7LEWtOGzV2cmmlPfBIWBWlWRDkyqPHJ1jm8,333
-earningscall/api.py,sha256=F_1h8ib7xCK0r8wMtp79D8BQgiusYmfsaRrAaPF9eic,2488
-earningscall/company.py,sha256=ZNF75htXg37oXtNzwrHH8DoTdyFJ3PBB9qSNBp_vo8c,1943
-earningscall/errors.py,sha256=EA-d6qIYgQs9csp8JptQiAaYoM0M9HhCGJgKA9GAWPg,440
-earningscall/event.py,sha256=Jf7KPvpeaF9KkeHe46LbL_HIYLXkyHrs3psq-ZY-bkI,692
-earningscall/exports.py,sha256=i9UWHY6Lq1OzZTZX_1SdNzrNd_PSlPwpB337lGMK4oM,837
-earningscall/sectors.py,sha256=Xd6DLkAQ_fQkC2s-N9pReC8b_M3iy77OoFftoZj9FWY,5114
-earningscall/symbols.py,sha256=Fsk9F2SYzn5TUQnL84AO1_xgiMg6G1DyvBGm7-_3LH4,6347
-earningscall/transcript.py,sha256=vuI0FOSaWDGKYaUxq1i6cnBZQJ2TAuARAWAhHlfuNRc,329
-earningscall/utils.py,sha256=Qx8KhlumUdzyBSZRKMS6vpWlb8MGZpLKA4OffJaMdCE,1032
-earningscall-0.0.17.dist-info/METADATA,sha256=Ph8kEPLaoGnl3KEEXDqN_oU1i21-vrnG6wG5Pz7V-CU,7177
-earningscall-0.0.17.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
-earningscall-0.0.17.dist-info/licenses/LICENSE,sha256=ktEB_UcRMg2cQlX9wiDs544xWncWizwS9mEZuGsCLrM,1069
-earningscall-0.0.17.dist-info/RECORD,,