Special Notes: Parameter Conversion and Helper Utilities (edgar-sec)#

The Edgar-SEC package uses automatic parameter normalization, CIK resolution helpers, and async-safe conversion tools for consistent and clean API usage.

This page summarizes key internal utilities and design patterns.

—

Parameter Conversion in Edgar-SEC#

Edgar-SEC automatically handles conversions for common parameter types.

Supported Conversions#

  • datetime.datetime → YYYY-MM-DD:

    from datetime import datetime
edgar.get_submissions(
    cik="0000320193",
    start=datetime(2021, 1, 1)
)

  • str → padded CIK:

    Automatically zero-fills short CIKs to 10 digits via internal validation.

    edgar.get_submissions(cik="320193")  # Becomes "0000320193"

  • str → CY####Q# formatted period:

    edgar.EdgarHelpers.string_cy_conversion("2022-09-30")  # -> "CY2022Q3"

  • datetime → CY####Q# formatted period:

    from datetime import datetime
edgar.EdgarHelpers.datetime_cy_conversion(datetime(2022, 3, 31))  # -> "CY2022Q1"

—

Helper Methods#

Conversion and validation utilities are accessible via:

  • edgar_sec.EdgarHelpers.get_cik

  • edgar_sec.EdgarHelpers.get_universe

  • edgar_sec.EdgarHelpers.cik_validation

  • edgar_sec.EdgarHelpers.string_cy_conversion

  • edgar_sec.EdgarHelpers.datetime_cy_conversion

Each has an async equivalent as well (e.g. get_cik_async, datetime_cy_conversion_async).

—

CIK Search and Universe Fetching#

Examples:

  • Search for a company CIK by name or ticker:

    edgar.EdgarHelpers.get_cik(ticker="AAPL")
edgar.EdgarHelpers.get_cik(search_text="Tesla")

  • Fetch full company list:

    universe = edgar.EdgarHelpers.get_universe()
print(universe[0].name, universe[0].cik)

—

Validating CIK Format#

CIKs are zero-padded to 10-digit strings automatically.

edgar.EdgarHelpers.cik_validation("320193")  # -> "0000320193"

Used internally by all client methods.

—

Calendar Period Utilities#

For converting reporting periods into SEC-style CY####Q# format:

from edgar_sec import EdgarHelpers
EdgarHelpers.string_cy_conversion("2023-06-30")     # -> "CY2023Q2"
EdgarHelpers.datetime_cy_conversion(datetime(2023, 6, 30))  # -> "CY2023Q2"

Validation:

EdgarHelpers.string_cy_validation("CY2022Q3")  # -> True
EdgarHelpers.string_cy_validation("2022Q3")    # -> False

—

Async Conversion Utilities#

All conversion methods are async-safe using asyncio.to_thread(…).

await edgar.EdgarHelpers.string_cy_conversion_async("2023-06-30")
await edgar.EdgarHelpers.get_cik_async(ticker="GOOG")

—