Merge pull request #858 from gaoflow/fix/856-nullhandler

fix: attach NullHandler to the edgar package logger (#856)

Author: dgunning

CHANGELOG.md

@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **`edgar` package logger no longer leaks log output in unconfigured applications** — the package-root logger had no `NullHandler`, so when an application had not configured logging itself, edgartools warnings fell back to Python's `logging.lastResort` handler and were written to stderr. This was especially harmful in MCP / stdio environments, where stray stderr output corrupts the protocol stream. A `NullHandler` is now attached to the `edgar` logger per the Python logging HOWTO for libraries, keeping edgartools silent until the application opts into logging. ([#856](https://github.com/dgunning/edgartools/issues/856))
 - **BDC data sets download again after SEC URL move** — the SEC relocated the DERA BDC data-set files from `/files/structureddata/data/` to `/files/datastandardsinnovation/data/`, which made `fetch_bdc_dataset()` and related functions fail with 404; the base URL now points to the new location.
 - **`FormC.filer_information.ccc` no longer duplicates the CIK** — the Form C parser read the `filerCik` element into both `cik` and `ccc`; `ccc` now reads the actual `filerCcc` element (always redacted to `XXXXXXXX` in disseminated filings) and is `Optional`, returning `None` when absent.
 - **`FormC.filer_information.live_or_test` is no longer always `False`** — the parser looked for a `testOrLive` element under `filer`, but the schema places `liveTestFlag` under `filerInfo`; LIVE filings now correctly report `True` (older `testOrLive` documents remain supported).

edgar/__init__.py

@@ -1,6 +1,7 @@
 # SPDX-FileCopyrightText: 2022-present Dwight Gunning <dgunning@gmail.com>
 #
 # SPDX-License-Identifier: MIT
+import logging
 import re
 from functools import lru_cache, partial
 from typing import List, Optional, Union
@@ -103,6 +104,13 @@
 from edgar.thirteenf import THIRTEENF_FORMS, ThirteenF
 from edgar.xbrl import XBRL
 
+# Attach a NullHandler to the package-root logger so that edgartools never emits
+# log output unless the application configures logging itself, per the Python
+# logging HOWTO guidance for libraries (#856).  Without it, library warnings have
+# no handler in their ancestry and fall back to logging.lastResort (stderr),
+# which is especially harmful in MCP / stdio environments.
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
 # Fix for Issue #457: Clear locale-corrupted cache files on first import
 # This is a one-time operation that only runs if the marker file doesn't exist
 try:

tests/issues/regression/test_issue_856.py

@@ -0,0 +1,34 @@
+"""
+Regression test for Issue #856: Missing NullHandler in the edgar package logger.
+
+A well-behaved library should attach a ``logging.NullHandler`` to its
+package-root logger so that it never emits log output unless the consuming
+application configures logging itself (see the Python logging HOWTO,
+"Configuring Logging for a Library"). Without it, edgartools warnings have no
+handler in their ancestry and fall back to the ``logging.lastResort`` handler,
+which writes to stderr -- especially harmful in MCP / stdio environments where
+stray stderr output corrupts the protocol stream.
+"""
+
+import logging
+
+import edgar  # noqa: F401  (importing configures the package-root logger)
+
+
+class TestPackageRootNullHandler:
+    def test_edgar_logger_has_null_handler(self):
+        """The 'edgar' package-root logger must carry a NullHandler."""
+        handlers = logging.getLogger("edgar").handlers
+        assert any(isinstance(h, logging.NullHandler) for h in handlers), (
+            "edgartools must attach a logging.NullHandler to the 'edgar' logger "
+            "so library logging stays silent until the application configures it"
+        )
+
+    def test_edgar_logger_adds_only_null_handler(self):
+        """The library must not attach handlers other than NullHandler (HOWTO)."""
+        handlers = logging.getLogger("edgar").handlers
+        assert handlers, "the 'edgar' logger should have a NullHandler attached"
+        assert all(isinstance(h, logging.NullHandler) for h in handlers), (
+            "a library must not attach handlers other than NullHandler to its "
+            "package-root logger; that is the application's responsibility"
+        )