earningscall 0.0.17__tar.gz → 0.0.19__tar.gz

{earningscall-0.0.17 → earningscall-0.0.19}/.gitignore

@@ -32,6 +32,7 @@ tasks.xml
 /build
 /sc.egg-info
 /packages
+/audio_files
 
 # Root files
 /.coverage*

earningscall-0.0.19/.python-version

@@ -0,0 +1 @@
+3.12.6

earningscall-0.0.19/CHANGELOG.md

@@ -0,0 +1,30 @@
+## Release `0.0.19` - 2024-10-07
+
+* Add Advanced Transcript Data structures (Beta: and subject to change in the future).
+* Add additional client-side verification and parameter checking.
+* Don't throw an exception when audio file is missing, just return `None`.
+* Throw useful error in the case of not authorized to download Audio Files.
+* Add additional unit test coverage.
+
+## Release `0.0.18` - 2024-10-01
+
+* Add Download Audio File Feature: add `download_audio_file` function to the `Company` class.
+* Add "LSE" to the list of exchanges.
+
+## Release `0.0.17` - 2024-08-04
+
+* Remove apikey from the ignored parameters list.
+
+When `apikey=demo`, the API will return different results.  If we change
+apikey to some other value, then the old result from when `apikey=demo`
+would be returned.  This is incorrect.
+
+## Release `0.0.16` - 2024-06-12
+* Bump version number.
+
+## Release `0.0.15` - 2024-06-12
+* Remove `dataclasses` as a project dependency.  It is built directly into Python.
+
+## Release `0.0.14` - 2024-06-08
+* Add caching to improve client performance.
+* Add `company_info` attribute in `Company` class.

{earningscall-0.0.17 → earningscall-0.0.19}/DEVELOPMENT.md

@@ -1,7 +1,12 @@
 # Development
 
-First, install Hatch.  See the Hatch [installation instructions](https://hatch.pypa.io/latest/install/).
+First, install Hatch plus other build dependencies.  See the Hatch [installation instructions](https://hatch.pypa.io/latest/install/).
 
+My preferred way to install it is to use `pip`:
+
+```shell
+pip install hatch coverage black
+```
 
 ## Run Build
 
@@ -9,7 +14,6 @@ First, install Hatch.  See the Hatch [installation instructions](https://hatch.p
 hatch build
 ```
 
-
 ### Running Unit Tests
 
 ```shell

{earningscall-0.0.17 → earningscall-0.0.19}/PKG-INFO

@@ -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.17 → earningscall-0.0.19}/TODO.md

@@ -3,7 +3,6 @@
 
 * Add ability to retrieve advanced transcript data
 * Raise helpful error if the user tries to make a call that the current plan doesn't support
-* Add documentation on how to disable caching
 
 
 # Considerations

earningscall-0.0.19/earningscall/api.py

@@ -0,0 +1,182 @@
+import importlib
+import logging
+import os
+from typing import Optional
+
+import requests
+from requests_cache import CachedSession
+
+import earningscall
+
+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():
+    if earningscall.api_key:
+        return earningscall.api_key
+    return os.environ.get("ECALL_API_KEY", "demo")
+
+
+def api_key_param():
+    return {"apikey": get_api_key()}
+
+
+def is_demo_account():
+    return get_api_key() == "demo"
+
+
+def cache_session() -> CachedSession:
+    return CachedSession(
+        ".earningscall_cache",
+        backend="sqlite",
+        cache_control=True,
+        use_temp=True,
+        ignored_parameters=[],
+    )
+
+
+def cached_urls():
+    return cache_session().cache.urls()
+
+
+def purge_cache():
+    return cache_session().cache.clear()
+
+
+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", {}),
+    }
+    url = f"{API_BASE}/{path}"
+    log.debug(f"do_get url: {url} params: {params}")
+    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"),
+        )
+
+
+def get_events(exchange: str, symbol: str):
+    log.debug(f"get_events exchange: {exchange} symbol: {symbol}")
+    params = {
+        **api_key_param(),
+        "exchange": exchange,
+        "symbol": symbol,
+    }
+    response = do_get("events", params=params)
+    if response.status_code != 200:
+        return None
+    return response.json()
+
+
+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)
+    response.raise_for_status()
+    return response.json()
+
+
+def get_symbols_v2():
+    log.debug("get_symbols_v2")
+    response = do_get("symbols-v2.txt", use_cache=True)
+    if response.status_code != 200:
+        return None
+    return response.text
+
+
+def get_sp500_companies_txt_file():
+    log.debug("get_sp500_companies_txt_file")
+    response = do_get("symbols/sp500.txt", use_cache=True)
+    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-0.0.19/earningscall/company.py

@@ -0,0 +1,159 @@
+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
+
+log = logging.getLogger(__file__)
+
+
+class Company:
+    """
+    A class representing a company.
+    """
+
+    company_info: CompanyInfo
+    name: Optional[str]
+    _events: Optional[List[EarningsEvent]]
+
+    def __init__(self, company_info: CompanyInfo):
+        if not company_info:
+            raise ValueError("company_info must be present.")
+        self.company_info = company_info
+        self.name = company_info.name
+        self._events = None
+
+    def __str__(self):
+        return str(self.name)
+
+    def _get_events(self) -> List[EarningsEvent]:
+        if not self.company_info.exchange or not self.company_info.symbol:
+            return []
+        raw_response = api.get_events(self.company_info.exchange, self.company_info.symbol)
+        if not raw_response:
+            return []
+        return [EarningsEvent.from_dict(event) for event in raw_response["events"]]  # type: ignore
+
+    def events(self) -> List[EarningsEvent]:
+        if not self._events:
+            self._events = self._get_events()
+        return self._events
+
+    def get_transcript(
+        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:
+            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}")
+        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
+        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-0.0.17 → earningscall-0.0.19}/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-0.0.19/earningscall/transcript.py

@@ -0,0 +1,25 @@
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+from dataclasses_json import dataclass_json
+
+from earningscall.event import EarningsEvent
+
+
+@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: 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 → earningscall-0.0.19}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "earningscall"
-version = "0.0.17"
+version = "0.0.19"
 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 = [

earningscall-0.0.19/scripts/download_audio_files.py

@@ -0,0 +1,45 @@
+import argparse
+import os
+
+import earningscall  # noqa: F401
+from earningscall import get_company
+from earningscall.company import Company
+from earningscall.utils import configure_sane_logging
+
+
+# TODO: Set your API key here:
+# earningscall.api_key = "YOUR SECRET API KEY GOES HERE"
+
+
+parser = argparse.ArgumentParser(description='')
+parser.add_argument('--debug', action='store_true', help='Enable debug logs')
+parser.add_argument('--sp-500', action='store_true', help='Show S&P500 Companies')
+
+args = parser.parse_args()
+configure_sane_logging()
+
+
+directory = "audio_files"
+os.makedirs(directory, exist_ok=True)
+
+
+def download_audio_files(company: Company):
+    print(f"Downloading all audio files for: {company}..")
+    for event in company.events():
+        file_name = os.path.join(
+            directory,
+            f"{company.company_info.exchange}_{company.company_info.symbol}_{event.year}_Q{event.quarter}.mp3",
+        )
+        if os.path.exists(file_name):
+            print(f"* {company.company_info.symbol} Q{event.quarter} {event.year} -- already downloaded")
+        else:
+            print(f"* Downloading audio file for {company.company_info.symbol} Q{event.quarter} {event.year}...")
+            audio_file = company.download_audio_file(event=event, file_name=file_name)
+            if audio_file:
+                print(f" Downloaded audio file: \"{audio_file}\"")
+            else:
+                print(f" No audio file found for {company.company_info.symbol} Q{event.quarter} {event.year}")
+
+
+company = get_company("aapl")  # Lookup Apple, Inc by its ticker symbol, "AAPL"
+download_audio_files(company)

earningscall-0.0.19/scripts/download_single_audio_file.py

@@ -0,0 +1,29 @@
+import argparse
+import os
+
+import earningscall  # noqa: F401
+from earningscall import get_company
+from earningscall.utils import configure_sane_logging
+
+# TODO: Set your API key here:
+# earningscall.api_key = "YOUR SECRET API KEY GOES HERE"
+
+
+parser = argparse.ArgumentParser(description='')
+parser.add_argument('--debug', action='store_true', help='Enable debug logs')
+parser.add_argument('--sp-500', action='store_true', help='Show S&P500 Companies')
+
+args = parser.parse_args()
+configure_sane_logging()
+
+
+directory = "audio_files"
+os.makedirs(directory, exist_ok=True)
+
+
+file_name = os.path.join(
+    directory,
+    "NASDAQ_META_2024_Q3.mp3",
+)
+company = get_company("meta")  # Lookup Meta, Inc by its ticker symbol, "META"
+company.download_audio_file(year=2024, quarter=3, file_name=file_name)

earningscall-0.0.19/scripts/download_sp500_audio_files.py

@@ -0,0 +1,33 @@
+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 = "audio_files"
+os.makedirs(directory, exist_ok=True)
+
+
+def download_audio_files(company: Company):
+    print(f"Downloading all audio files for: {company}..")
+    for event in company.events():
+        file_name = os.path.join(
+            directory,
+            f"{company.company_info.exchange}_{company.company_info.symbol}_{event.year}_Q{event.quarter}.mp3",
+        )
+        if os.path.exists(file_name):
+            print(f"* {company.company_info.symbol} Q{event.quarter} {event.year} -- already downloaded")
+        else:
+            print(f"* Downloading audio file for {company.company_info.symbol} Q{event.quarter} {event.year}...")
+            audio_file = company.download_audio_file(event=event, file_name=file_name)
+            if audio_file:
+                print(f" Downloaded audio file: \"{audio_file}\"")
+            else:
+                print(f" No audio file found for {company.company_info.symbol} Q{event.quarter} {event.year}")
+
+
+for company in get_sp500_companies():
+    download_audio_files(company)

earningscall-0.0.19/scripts/get_single_transcript.py

@@ -0,0 +1,13 @@
+import earningscall  # noqa: F401
+
+from earningscall import get_company
+
+
+# TODO: Set your API key here:
+# earningscall.api_key = "YOUR SECRET API KEY GOES HERE"
+
+
+company = get_company("aapl")
+
+transcript = company.get_transcript(year=2021, quarter=3, level=4)
+print(f"{company} Q3 2021 Transcript Text: \"{transcript.text[:100]}...\"")

{earningscall-0.0.17 → earningscall-0.0.19}/scripts/list_companies.py

@@ -4,7 +4,6 @@ import logging
 from earningscall import get_all_companies, get_sp500_companies
 from earningscall.utils import configure_sane_logging
 
-
 parser = argparse.ArgumentParser(description='')
 parser.add_argument('--debug', action='store_true', help='Enable debug logs')
 parser.add_argument('--sp-500', action='store_true', help='Show S&P500 Companies')