feat: Enhance logging across the EDGAR API modules with debug-level messages and add NullHandler to prevent logging warnings

Author: areed1192

CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Changed
+
+- **edgar/\_\_init\_\_.py**: Added `NullHandler` to the `edgar` logger — follows Python library logging best practice so applications control log output.
+- **edgar/session.py**: Downgraded per-request URL, parameter, and rate-limit sleep logs from `info` to `debug`.
+- **edgar/async_session.py**: Same `info` → `debug` log-level fix as `session.py`.
+- **edgar/parser.py**: Downgraded pagination URL and entry-count logs from `info` to `debug`.
+- **edgar/client.py**: Added `logger` — logs `debug` on init (rate_limit, cache settings).
+- **edgar/cache.py**: Added `logger` — logs `debug` on cache hit, miss, expired, set, and invalidate.
+- **edgar/tickers.py**: Added `debug` logging for cache hit/miss and successful resolution; `warning` on failed ticker/CIK lookup.
+- **edgar/submissions.py**: Added `logger` — logs `debug` on submissions cache hit.
+- **edgar/xbrl.py**: Added `logger` — logs `debug` on company_facts cache hit.
+- **edgar/datasets.py**: Added `logger` — logs `info` on bulk download start, `debug` on per-file extraction with row counts.
+- **edgar/search.py**: Added `logger` — logs `debug` with EFTS search params before request.
+- **edgar/company.py**: Added `logger` — logs `debug` on identifier resolution path (CIK vs ticker).
+
 ## [0.2.0] - 2026-04-19
 
 ### Added

edgar/__init__.py

@@ -16,12 +16,18 @@
 
 from __future__ import annotations
 
+import logging
 import os
 
 from edgar.client import EdgarClient
 from edgar.async_client import EdgarAsyncClient
 from edgar.exceptions import EdgarError, EdgarRequestError, EdgarParseError
 
+# Library best practice: add a NullHandler so users don't see
+# "No handlers could be found for logger 'edgar'" warnings.
+# Users configure logging in their own applications.
+logging.getLogger("edgar").addHandler(logging.NullHandler())
+
 __all__ = [
     "EdgarClient",
     "EdgarAsyncClient",

edgar/async_session.py

@@ -145,8 +145,8 @@ async def make_request(  # pylint: disable=too-many-positional-arguments
 
         url = self.build_url(endpoint=endpoint, use_api=use_api, base_url=base_url)
 
-        logger.info("URL: %s", url)
-        logger.info("PARAMETERS %s", params)
+        logger.debug("URL: %s", url)
+        logger.debug("Parameters: %s", params)
 
         await self._throttle()
 
@@ -289,7 +289,7 @@ async def _throttle(self) -> None:
         if len(self._request_times) >= self._rate_limit:
             sleep_duration = 1.0 - (now - self._request_times[0])
             if sleep_duration > 0:
-                logger.info(
+                logger.debug(
                     "Rate limit: %d requests in window, sleeping %.3fs",
                     len(self._request_times),
                     sleep_duration,

edgar/cache.py

@@ -2,8 +2,11 @@
 
 from __future__ import annotations
 
+import logging
 import time
 
+logger = logging.getLogger(__name__)
+
 
 # Default TTLs in seconds.
 TTL_TICKERS = 86400       # 24 hours — ticker data changes ~quarterly
@@ -26,22 +29,27 @@ def get(self, key: str) -> object | None:
 
         entry = self._store.get(key)
         if entry is None:
+            logger.debug("Cache miss: %s", key)
             return None
         value, expires_at = entry
         if time.monotonic() >= expires_at:
             del self._store[key]
+            logger.debug("Cache expired: %s", key)
             return None
+        logger.debug("Cache hit: %s", key)
         return value
 
     def set(self, key: str, value: object, ttl: float) -> None:
         """Store *value* under *key* with a TTL of *ttl* seconds."""
 
         self._store[key] = (value, time.monotonic() + ttl)
+        logger.debug("Cache set: %s (ttl=%.0fs)", key, ttl)
 
     def invalidate(self, key: str) -> None:
         """Remove a single key from the cache."""
 
         self._store.pop(key, None)
+        logger.debug("Cache invalidated: %s", key)
 
     def clear(self) -> None:
         """Remove all entries from the cache."""

edgar/client.py

@@ -1,5 +1,7 @@
 """Main entry-point client for the SEC EDGAR API."""
 
+import logging
+
 from edgar.cache import TTLCache
 from edgar.xbrl import Xbrl
 from edgar.series import Series
@@ -18,6 +20,11 @@
 from edgar.ownership_filings import OwnershipFilings
 from edgar.variable_insurance_products import VariableInsuranceProducts
 
+from edgar.models import SearchResult
+
+
+logger = logging.getLogger(__name__)
+
 
 class EdgarClient:
     """
@@ -59,6 +66,11 @@ def __init__(self, user_agent: str, rate_limit: int = 10, cache: bool = True) ->
         )
         self._services: dict = {}
 
+        logger.debug(
+            "EdgarClient initialized (rate_limit=%d, cache=%s)",
+            rate_limit, cache,
+        )
+
     def __repr__(self) -> str:
         """String representation of the `EdgarClient` object."""
 
@@ -380,8 +392,6 @@ def search(
             'Apple Inc.  (AAPL)  (CIK 0000320193)'
         """
 
-        from edgar.models import SearchResult
-
         raw = self.full_text_search().full_text_search(
             q=q,
             form_types=form_types,

edgar/company.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging
 from enum import Enum
 from typing import TYPE_CHECKING, Union
 
@@ -10,6 +11,8 @@
 from edgar.submissions import Submissions
 from edgar.xbrl import Xbrl
 
+logger = logging.getLogger(__name__)
+
 if TYPE_CHECKING:
     from edgar.session import EdgarSession
     from edgar.tickers import Tickers
@@ -57,12 +60,14 @@ def __init__(
         stripped = str(identifier).lstrip("0")
         if stripped.isdigit():
             # CIK path — resolve to get metadata.
+            logger.debug("Resolving identifier as CIK: %s", identifier)
             entries = tickers_service.resolve_cik(identifier)
             self._cik: str = str(entries[0]["cik_str"]).zfill(10)
             self._ticker: str = entries[0]["ticker"]
             self._name: str = entries[0]["title"]
         else:
             # Ticker path — resolve to get CIK.
+            logger.debug("Resolving identifier as ticker: %s", identifier)
             self._cik = tickers_service.resolve_ticker(identifier)
             self._ticker = identifier.upper()
             # Look up the company name from the resolved CIK.

edgar/datasets.py

@@ -4,10 +4,13 @@
 
 import csv
 import io
+import logging
 import zipfile
 
 from edgar.session import EdgarSession
 
+logger = logging.getLogger(__name__)
+
 _DERA_BASE = "/files/dera/data/financial-statement-data-sets"
 
 
@@ -157,6 +160,7 @@ def get_financial_statements(
             raise ValueError(f"quarter must be between 1 and 4, got {quarter}")
 
         endpoint = f"{_DERA_BASE}/{year}q{quarter}.zip"
+        logger.info("Downloading DERA dataset %dQ%d", year, quarter)
         zip_bytes = self.edgar_session.fetch_page(
             self.edgar_session.build_url(endpoint=endpoint)
         )
@@ -233,5 +237,6 @@ def _extract_tsv_zip(zip_bytes: bytes) -> dict[str, list[dict]]:
                 text = io.TextIOWrapper(f, encoding="utf-8")
                 reader = csv.DictReader(text, delimiter="\t")
                 result[key] = list(reader)
+            logger.debug("Extracted %s (%d rows)", key, len(result[key]))
 
     return result

edgar/parser.py

@@ -103,7 +103,7 @@ def parse_entries(
                 keep_going = False
             elif fetch_page:
                 page_content = fetch_page(next_page)
-                logger.info("Grabbed Next URL: %s", next_page)
+                logger.debug("Grabbed next URL: %s", next_page)
 
                 if page_content:
                     try:
@@ -286,7 +286,7 @@ def parse_issuer_table(
 
             master_list.append(master_dict)
 
-            logger.info("Pulling URL: %s", next_page_link)
+            logger.debug("Pulling URL: %s", next_page_link)
 
             if next_page_link and fetch_page:
                 page_content = fetch_page(next_page_link)
@@ -428,8 +428,8 @@ def parse_variable_products_company_table(
             )
             product_list_all = product_list_all + product_list
 
-            logger.info("Pulling URL: %s", link)
-            logger.info("Total Entries Scraped: %s", len(product_list_all))
+            logger.debug("Pulling URL: %s", link)
+            logger.debug("Total entries scraped: %s", len(product_list_all))
 
         return product_list_all
 

edgar/search.py

@@ -2,8 +2,12 @@
 
 from __future__ import annotations
 
+import logging
+
 from edgar.session import EdgarSession
 
+logger = logging.getLogger(__name__)
+
 EFTS_BASE_URL = "https://efts.sec.gov"
 
 
@@ -101,6 +105,8 @@ def full_text_search(
             if end_date:
                 params["enddt"] = end_date
 
+        logger.debug("EFTS search params: %s", params)
+
         return self.edgar_session.make_request(
             method="get",
             endpoint="/LATEST/search-index",

edgar/session.py

@@ -189,8 +189,8 @@ def make_request(
         # Build the URL.
         url = self.build_url(endpoint=endpoint, use_api=use_api, base_url=base_url)
 
-        logger.info("URL: %s", url)
-        logger.info("PARAMETERS %s", params)
+        logger.debug("URL: %s", url)
+        logger.debug("Parameters: %s", params)
 
         # Build the request kwargs.
         request_kwargs = {
@@ -284,7 +284,7 @@ def _throttle(self) -> None:
         if len(self._request_times) >= self._rate_limit:
             sleep_duration = 1.0 - (now - self._request_times[0])
             if sleep_duration > 0:
-                logger.info(
+                logger.debug(
                     "Rate limit: %d requests in window, sleeping %.3fs",
                     len(self._request_times),
                     sleep_duration,