feat: Add top-level convenience functions for Edgar API and corresponding tests

Author: areed1192

CHANGELOG.md

@@ -9,6 +9,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **edgar/\_\_init\_\_.py**: Top-level convenience functions for reduced boilerplate.
+  - `edgar.company("AAPL")` — create a `Company` without instantiating `EdgarClient`.
+  - `edgar.get_filings("AAPL", form="10-K")` — fetch filings in one call.
+  - `edgar.search("revenue recognition")` — full-text search in one call.
+  - `edgar.set_user_agent()` — set user-agent programmatically.
+  - `SEC_EDGAR_USER_AGENT` environment variable auto-detected as fallback.
+  - Lazy singleton `EdgarClient` created on first use and cached.
+- **tests/test_convenience.py**: 17 unit tests for convenience functions (`set_user_agent`, `_get_client`, `company`, `get_filings`, `search`, env var fallback, caching, exports).
+- **samples/use_convenience.py**: Sample file demonstrating top-level convenience functions (env var, `set_user_agent`, `company`, `get_filings`, `search`).
 - **edgar/models.py**: `Fact` and `Facts` XBRL dataclass models.
   - `Facts` wraps the deeply nested `company_facts` JSON (4 levels) with `get(taxonomy, concept, unit=None)` returning a flat `list[Fact]` sorted by end date.
   - `Facts.taxonomies` lists available namespaces (e.g. `['dei', 'us-gaap', 'ifrs-full']`).

edgar/__init__.py

@@ -1,4 +1,22 @@
-"""SEC EDGAR API client library."""
+"""SEC EDGAR API client library.
+
+Top-level convenience functions let you skip the ``EdgarClient`` boilerplate::
+
+    import edgar
+
+    company = edgar.company("AAPL")
+    filings = edgar.get_filings("AAPL", form="10-K")
+    results = edgar.search("revenue recognition")
+
+Set the ``SEC_EDGAR_USER_AGENT`` environment variable to avoid passing
+``user_agent`` on every call::
+
+    export SEC_EDGAR_USER_AGENT="Your Name your-email@example.com"
+"""
+
+from __future__ import annotations
+
+import os
 
 from edgar.client import EdgarClient
 from edgar.exceptions import EdgarError, EdgarRequestError, EdgarParseError
@@ -8,4 +26,103 @@
     "EdgarError",
     "EdgarRequestError",
     "EdgarParseError",
+    "company",
+    "get_filings",
+    "search",
+    "set_user_agent",
 ]
+
+_ENV_VAR = "SEC_EDGAR_USER_AGENT"
+_user_agent: str | None = None
+_client: EdgarClient | None = None
+
+
+def set_user_agent(user_agent: str) -> None:
+    """Set the default user-agent for module-level convenience functions.
+
+    This value takes priority over the ``SEC_EDGAR_USER_AGENT``
+    environment variable.
+    """
+
+    global _user_agent, _client  # pylint: disable=global-statement
+    _user_agent = user_agent
+    _client = None  # force re-creation on next call
+
+
+def _get_client() -> EdgarClient:
+    """Return a lazily-initialised shared ``EdgarClient``.
+
+    Resolution order for the user-agent string:
+
+    1. Value set via ``set_user_agent()``.
+    2. The ``SEC_EDGAR_USER_AGENT`` environment variable.
+
+    Raises ``EdgarError`` if neither is available.
+    """
+
+    global _client  # pylint: disable=global-statement
+    if _client is not None:
+        return _client
+
+    agent = _user_agent or os.environ.get(_ENV_VAR)
+    if not agent:
+        raise EdgarError(
+            "No user-agent configured. Either call edgar.set_user_agent() "
+            f"or set the {_ENV_VAR} environment variable."
+        )
+    _client = EdgarClient(user_agent=agent)
+    return _client
+
+
+def company(identifier: str) -> object:
+    """Return a ``Company`` object for the given ticker or CIK.
+
+    >>> import edgar
+    >>> edgar.company("AAPL").name
+    'Apple Inc.'
+    """
+
+    return _get_client().company(identifier)
+
+
+def get_filings(
+    identifier: str,
+    form: str | None = None,
+    start: int = 0,
+    number_of_filings: int = 100,
+) -> list:
+    """Return filings for a company as ``Filing`` model objects.
+
+    >>> import edgar
+    >>> edgar.get_filings("AAPL", form="10-K")[0].form_type
+    '10-K'
+    """
+
+    return _get_client().company(identifier).get_filings(
+        form=form, start=start, number_of_filings=number_of_filings
+    )
+
+
+def search(
+    q: str,
+    form_types: list[str] | None = None,
+    start_date: str | None = None,
+    end_date: str | None = None,
+    start: int = 0,
+    size: int = 100,
+) -> list:
+    """Full-text search across SEC EDGAR filings.
+
+    >>> import edgar
+    >>> edgar.search("revenue recognition", form_types=["10-K"])[0].company_name
+    'Apple Inc. ...'
+    """
+
+    return _get_client().search(
+        q=q,
+        form_types=form_types,
+        start_date=start_date,
+        end_date=end_date,
+        start=start,
+        size=size,
+    )

samples/use_convenience.py

@@ -0,0 +1,55 @@
+"""Example usage of top-level convenience functions."""
+
+import edgar
+
+# ---------------------------------------------------------------------------
+# Option A: Set user-agent via environment variable (recommended for scripts)
+# ---------------------------------------------------------------------------
+
+# In your shell:
+#   export SEC_EDGAR_USER_AGENT="Your Name your-email@example.com"
+#
+# Then simply:
+#   import edgar
+#   company = edgar.company("AAPL")
+
+# ---------------------------------------------------------------------------
+# Option B: Set user-agent programmatically
+# ---------------------------------------------------------------------------
+
+edgar.set_user_agent("Your Name your-email@example.com")
+
+# ---------------------------------------------------------------------------
+# Quick company lookup — no EdgarClient needed
+# ---------------------------------------------------------------------------
+
+company = edgar.company("AAPL")
+print(company)
+# Output: <Company ticker='AAPL' cik='0000320193' name='Apple Inc.'>
+
+# ---------------------------------------------------------------------------
+# Get filings directly by ticker
+# ---------------------------------------------------------------------------
+
+filings = edgar.get_filings("AAPL", form="10-K")
+print(f"Found {len(filings)} 10-K filings")
+print(filings[0])
+# Output: Filing(form_type='10-K', filing_date='...', accession_number='...')
+
+# ---------------------------------------------------------------------------
+# Full-text search — one line
+# ---------------------------------------------------------------------------
+
+results = edgar.search("revenue recognition", form_types=["10-K"], size=5)
+print(f"Found {len(results)} search results")
+for result in results[:3]:
+    print(f"  {result.company_name} — {result.form} ({result.filing_date})")
+
+# ---------------------------------------------------------------------------
+# All original EdgarClient functionality still works
+# ---------------------------------------------------------------------------
+
+client = edgar.EdgarClient(user_agent="Your Name your-email@example.com")
+company = client.company("MSFT")
+print(company.name)
+# Output: MICROSOFT CORP