Python API¶
sec_submissions.fetch_reference(output=None, version='latest', data_dir=None, repository=DATA_REPOSITORY, companions=False)
¶
Fetch a corrected reference, evidence, and audit artifacts with checksums.
Files are stored under DATA_DIR/submissions/references/<version>. The
mutable latest manifest is resolved once; every asset URL then
uses the concrete release tag. Interrupted transfers resume automatically.
SEC identification and a GitHub login are not needed for public downloads.
sec_submissions.ReferenceBundle
dataclass
¶
Local paths and metadata for one downloaded, pinned data release.
sec_submissions.data_directory(data_dir=None)
¶
Resolve the Parquet root from an argument, DATA_DIR, or defaults.
The working directory's .env is loaded without overriding existing
environment variables. The fallback is ~/sec-submissions-data/pq_data.
sec_submissions.raw_data_directory(raw_data_dir=None)
¶
Resolve the ZIP root from an argument, RAW_DATA_DIR, or defaults.
The command-line interface and Python functions share the same implementation.
Explicit paths override the documented directory defaults. Otherwise the
functions use DATA_DIR and RAW_DATA_DIR, including values in the local .env.
Core functions¶
sec_submissions.download_submissions(output=None, user_agent=None, raw_data_dir=None)
¶
Download a new submissions ZIP and write a Parquet source manifest.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
output
|
str | Path | None
|
New ZIP path; defaults to a dated file under RAW_DATA_DIR/submissions. |
None
|
user_agent
|
str | None
|
Identifying SEC User-Agent, usually |
None
|
Returns:
| Type | Description |
|---|---|
Path
|
The path to the downloaded ZIP. |
sec_submissions.extract_submissions(zip_path=None, out_path=None, max_seconds=MAX_SECONDS, data_dir=None, raw_data_dir=None)
¶
sec_submissions.make_previous(raw, output)
¶
Create filings_previous.parquet from the 2024 raw reference ZIP.
This is a one-time bootstrap for the worked workflow, not a general rule that later SEC ZIP snapshots use Eastern clock values.
sec_submissions.process(raw=None, previous=None, output=None, cache_dir=None, memory_limit='8GB', sgml_observations=(), live_observations=(), data_dir=None, historical_raw=())
¶
Create a corrected candidate Parquet and a separate diagnostics archive.
Existing outputs are never overwritten. The diagnostic directory is named
from the candidate stem, for example filings_checks. historical_raw
supplies earlier raw Parquet files for exact clock-pair matching, including
clocks whose earlier interpretation was unresolved.
Evidence and audit¶
sec_submissions.collect_live_json(filings=None, raw=None, output=None, since_date=date(2024, 1, 1), sample_blocks=None, seed=20261001, workers=8, rate=5, user_agent=None, resume=False, data_dir=None)
¶
Collect live JSON for unresolved or provisional blocks, freezing the selection.
sec_submissions.collect_sgml(queue, output=None, workers=8, rate=5, max_attempts=2, user_agent=None, resume=False, data_dir=None, index_fallback=False)
¶
Collect SGML and optionally filing-index fallback for an accession queue.
sec_submissions.audit
¶
Audit frozen timestamps against SGML, with filing-index fallback.
Local candidate installation¶
This function installs a local current file; it does not upload a GitHub release. See the maintainer notes.
sec_submissions.publish(candidate=None, current=None, previous=None, archive=None, data_dir=None)
¶
SEC user agent¶
sec_submissions.resolve_user_agent(value=None, prompt=None)
¶
Resolve a SEC identity like dera.pq and prompt only interactively.
sec_submissions.set_user_agent(user_agent, scope='session')
¶
Set the SEC user agent for this process and optionally persist it.
scope may be session, project (the current directory's
.env), or user (~/.config/sec-submissions/config.toml).