The Complete Toolkit

Changelog

All notable changes to this project will be documented in this file.

[0.2.0] - 2026-04-19

Added

• edgar/async_client.py: EdgarAsyncClient — async counterpart of EdgarClient using httpx.
  • Same API surface with await: resolve_ticker(), resolve_cik(), get_company_info(), get_filings(), get_facts(), search(), download().
  • Async context manager support (async with EdgarAsyncClient(...) as client).
  • Enables asyncio.gather() for concurrent requests in web apps and data pipelines.
• edgar/async_session.py: EdgarAsyncSession — async HTTP session with httpx.AsyncClient.
  • Sliding-window rate limiter using asyncio.sleep().
  • Retry logic with exponential backoff on non-200 responses.
  • make_request(), fetch_page(), download(), close() coroutines.
• pyproject.toml: Added [async] optional dependency group (pip install python-sec[async]).
  • Requires httpx>=0.28.
• edgar/__init__.py: Exports EdgarAsyncClient from the top-level package.
• tests/test_async_client.py: 28 unit tests for async session and client (init, rate limiting, URL building, make_request, download, fetch_page, ticker/CIK resolution, search, context manager).
• samples/use_async_client.py: Sample demonstrating async client usage with concurrent requests.
• edgar/datasets.py: Bulk DERA financial statement dataset download and extraction.
  • Datasets.get_financial_statements(year, quarter) downloads quarterly ZIP from SEC DERA and returns parsed TSV data as dict[str, list[dict]] (keys: sub, num, tag, pre).
  • Datasets.get_financial_statements_dataframes(year, quarter) returns the same data as dict[str, pandas.DataFrame] (requires pandas optional dep).
  • Internal _extract_tsv_zip() helper handles ZIP extraction and tab-separated parsing.
• tests/test_datasets.py: 15 unit tests for bulk dataset download, extraction, DataFrame conversion, and error handling.
• samples/use_dataset_service.py: Added bulk financial statements sections demonstrating get_financial_statements() and DataFrame variant.
• edgar/models.py: to_json() and to_csv() serialization methods on all model classes (Filing, CompanyInfo, Submission, Fact, Facts, SearchResult).
  • result.to_json(path=None, indent=2) serializes to a JSON string; optionally writes to file.
  • result.to_csv(path=None) serializes to a CSV string (header + one row); optionally writes to file.
  • Module-level to_json(items, path=None) and to_csv(items, path=None) for serializing lists of models.
  • List/dict properties are JSON-encoded in CSV cells for lossless round-tripping.
• tests/test_serialization.py: 35 unit tests for JSON/CSV serialization (instance methods, module-level functions, file writing, edge cases).
• samples/use_models.py: Added JSON and CSV serialization sections demonstrating to_json() and to_csv().
• samples/cookbook_company_research.ipynb: Cookbook notebook — company research workflow (ticker lookup, metadata, filings, XBRL facts, DataFrame export, multi-company comparison).
• samples/cookbook_xbrl_analysis.ipynb: Cookbook notebook — XBRL financial analysis (taxonomy browsing, concept retrieval, unit filtering, time-series DataFrames, frames cross-company comparison).
• samples/cookbook_filing_search.ipynb: Cookbook notebook — filing search & download (full-text search, form/date filters, pagination, document download, save to file).
• samples/cookbook_bulk_pipeline.ipynb: Cookbook notebook — bulk data pipeline (batch processing, multi-company aggregation, SEC datasets, rate limiting, caching, CSV export).
• edgar/cache.py: In-memory TTL cache for SEC EDGAR API responses.
  • TTLCache class with get(), set(), invalidate(), clear(), __len__(), __repr__().
  • Uses time.monotonic() for expiration immune to wall-clock adjustments.
  • Module-level TTL constants: TTL_TICKERS (24h), TTL_TAXONOMY (24h), TTL_SUBMISSIONS (1h).
• tests/test_cache.py: 29 unit tests for TTLCache (get/set, expiration, invalidate, clear, len/repr, constants) and cache integration with Tickers, Submissions, and Xbrl services.
• 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']).
  • Facts.concepts(taxonomy) lists concept names within a taxonomy.
  • Facts.label(), Facts.description(), Facts.units() for concept metadata.
  • Fact wraps a single data point with value, end, start, fiscal_year, fiscal_period, form, filed, frame properties.
• xbrl.py: get_facts(cik) method returning a structured Facts model.
• company.py: get_facts() method returning a structured Facts model.
• tests/test_xbrl_facts.py: 39 unit tests for Fact, Facts, Company.get_facts(), Xbrl.get_facts(), and taxonomy parameter support.
• edgar/models.py: to_dataframe() standalone function and Facts.to_dataframe() method for pandas integration.
  • to_dataframe(items) converts any list of model objects (Filing, Fact, Submission, SearchResult, CompanyInfo) to a pandas.DataFrame.
  • Facts.to_dataframe(taxonomy, concept, unit=None) returns fact data points as a DataFrame.
  • Graceful ImportError with message "pip install python-sec[pandas]" when pandas is not installed.
• pyproject.toml: [pandas] optional dependency group (pandas>=2.0).
• tests/test_to_dataframe.py: 20 unit tests for to_dataframe(), Facts.to_dataframe(), and graceful import error handling.
• samples/use_dataframes.py: Sample file demonstrating DataFrame conversion for facts, filings, search results, and submissions.

Changed

• edgar/client.py: EdgarClient now accepts rate_limit parameter: EdgarClient(user_agent="...", rate_limit=5).
  • Defaults to 10 (SEC's maximum). Validates range 1–10.
  • Passed through to EdgarSession for sliding-window enforcement.
• edgar/client.py: EdgarClient now accepts cache parameter (bool, default True).
  • cache=True creates a shared TTLCache passed to EdgarSession.
  • cache=False disables caching; all requests hit the network.
• edgar/session.py: EdgarSession accepts optional cache parameter storing a TTLCache instance.
• edgar/tickers.py: Tickers._load() checks/stores data in the TTL cache (TTL_TICKERS).
• edgar/submissions.py: Submissions.get_submissions() checks/stores responses in the TTL cache (TTL_SUBMISSIONS).
• edgar/xbrl.py: Xbrl.company_facts() checks/stores responses in the TTL cache (TTL_TAXONOMY).
• tests/test_rate_limiter.py: 8 new tests for configurable rate limit (custom values, boundary validation, client passthrough). Total: 17 tests.
• xbrl.py: company_concepts() and frames() now accept an optional taxonomy parameter (default "us-gaap"). Previously hardcoded to us-gaap, now supports "ifrs-full", "dei", or any other taxonomy.
• edgar/tickers.py: New Tickers service for ticker/CIK/company name resolution via sec.gov/files/company_tickers.json.
  • resolve_ticker("AAPL") → zero-padded CIK string ("0000320193").
  • resolve_cik(320193) → list of company entries (ticker, title, CIK).
  • search("Apple") → case-insensitive fuzzy search across tickers and company names.
  • Data is fetched once and cached in memory for the session lifetime.
• session.py: download(url, path=None) method to fetch filing documents (HTML, XML, PDF) from any SEC URL. Auto-detects text vs binary content. Optional path parameter saves directly to file.
• client.py: Convenience methods resolve_ticker(), resolve_cik(), tickers(), and download() on EdgarClient.
• samples/use_tickers_and_download.py: Sample file demonstrating ticker resolution, company search, and filing download.
• tests/test_tickers.py: 14 unit tests for the Tickers service (resolve, reverse lookup, search, caching, error handling).
• tests/test_download.py: 9 unit tests for download() (text/binary content, save-to-file, error handling, client delegation).
• edgar/company.py: New fluent Company class for ticker-based SEC EDGAR access.
  • client.company("AAPL") resolves ticker or CIK → Company object with cik, ticker, name properties.
  • company.filings(form="10-K") — fluent chaining to get filings without separate service objects.
  • company.submissions() — fetch full submission history.
  • company.xbrl_facts() — fetch XBRL company facts.
  • company.download(url) — download filing documents.
  • Accepts both ticker symbols ("AAPL") and CIK numbers ("320193").
• client.py: company() method on EdgarClient for fluent company access. Existing filings() / companies() methods remain for...

v0.1.6

Overview

Address an issue where the package was not installing correctly because of the setup.py file. In short, the package was using the find_package function instead of the find_namespace_packages. This prevented the setup.py file from copying all the necessary files that were needed for installation. Meaning that users who did:

pip install python-sec

Would not be able to import the package. To resolve this issue, upgrade the package to version 0.1.6 by running:

pip install upgrade python-sec

Full Changelog

0.1.5...master

v0.1.2

Overview:

Enhances the Python SEC Library by approaching it in a more component based approach. You'll now have access to different service clients that make pulling data easier and more efficient.