sec-downloader 0.12.2
Useful extensions for sec-edgar-downloader.
License: MIT License
Requires Python: >=3.7
Keywords: nbdev jupyter notebook python

# sec-downloader

<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

<a href="https://pypistats.org/packages/sec-downloader"><img src="https://img.shields.io/pypi/dm/sec-downloader?color=success" alt="PyPI downloads"></a>
<a href="LICENSE"><img src="https://img.shields.io/github/license/elijas/sec-downloader.svg?color=success" alt="Licence"></a>
<a href="https://github.com/elijas/sec-downloader/actions/workflows/test.yaml"><img alt="GitHub Workflow Status" src="https://img.shields.io/github/actions/workflow/status/elijas/sec-downloader/test.yaml?label=build"></a>
<a href="https://pypi.org/project/sec-downloader/"><img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/sec-downloader"></a>
<a href="https://badge.fury.io/py/sec-downloader"><img src="https://badge.fury.io/py/sec-downloader.svg" alt="PyPI version" /></a>

A better version of `sec-edgar-downloader`. Includes an alternative
implementation (a wrapper instead of a fork), to keep compatibility with
new `sec-edgar-downloader` releases. This library partially uses
[nbdev](https://nbdev.fast.ai/).

# Features

Advantages over `sec-edgar-downloader`:

**Flexibility in Download Process**

- Tailored for choosing *what*, *where*, and *how* to download.
- Files stored in memory for faster operations and no unnecessary disk
  clutter.

**Separate Metadata and File Downloads**

- Easily skip unneeded files.
- Download metadata first, then selectively download files.
- Option to save metadata for better organization.

**More Input Options**

- Ticker or CIK (e.g., `AAPL`, `0000320193`) for latest filings.
- Accession Number (e.g., `0000320193-23-000077`). Not supported in
  `sec-edgar-downloader`.
- SEC EDGAR URL (e.g.,
  `https://www.sec.gov/ix?doc=/Archives/edgar/data/0001067983/000119312523272204/d564412d8k.htm`).
  Not supported in `sec-edgar-downloader`.

# Install

``` sh
pip install sec-downloader
```

# How to use

## Download the metadata

> **Note** The company name and email address are used to form a
> user-agent string that adheres to the SEC EDGAR’s fair access policy
> for programmatic downloading.
> [Source](https://www.sec.gov/os/webmaster-faq#code-support)

``` python
from sec_downloader import Downloader

dl = Downloader("MyCompanyName", "email@example.com")
```

Find a filing with an Accession Number

``` python
metadatas = dl.get_filing_metadatas("AAPL/0000320193-23-000077")
print(metadatas)
```

    [FilingMetadata(accession_number='0000320193-23-000077',
                    form_type='10-Q',
                    primary_doc_url='https://www.sec.gov/Archives/edgar/data/320193/000032019323000077/aapl-20230701.htm',
                    items='',
                    primary_doc_description='10-Q',
                    filing_date='2023-08-04',
                    report_date='2023-07-01',
                    cik='0000320193',
                    company_name='Apple Inc.',
                    tickers=[Ticker(symbol='AAPL', exchange='Nasdaq')])]

Alternatively, you can also use any of these to get the same answer:

    metadatas = dl.get_filing_metadatas("aapl/000032019323000077")
    metadatas = dl.get_filing_metadatas("320193/000032019323000077")
    metadatas = dl.get_filing_metadatas("320193/0000320193-23-000077")
    metadatas = dl.get_filing_metadatas("0000320193/0000320193-23-000077")
    metadatas = dl.get_filing_metadatas(CompanyAndAccessionNumber(ticker_or_cik="320193", accession_number="0000320193-23-000077"))

Find the filing matching a SEC EDGAR Filing URL. Only CIK and Accession
Number are used from the URL:

``` python
metadatas = dl.get_filing_metadatas(
    "https://www.sec.gov/ix?doc=/Archives/edgar/data/0001067983/000119312523272204/d564412d8k.htm"
)
print(metadatas)
```

    [FilingMetadata(accession_number='0001193125-23-272204',
                    form_type='8-K',
                    primary_doc_url='https://www.sec.gov/Archives/edgar/data/1067983/000119312523272204/d564412d8k.htm',
                    items='2.02,9.01',
                    primary_doc_description='8-K',
                    filing_date='2023-11-07',
                    report_date='2023-11-04',
                    cik='0001067983',
                    company_name='BERKSHIRE HATHAWAY INC',
                    tickers=[Ticker(symbol='BRK-B', exchange='NYSE'),
                             Ticker(symbol='BRK-A', exchange='NYSE')])]

Alternatively, you can also URLs in other formats and get the same
answer:

    metadatas = dl.get_filing_metadatas("https://www.sec.gov/Archives/edgar/data/1067983/000119312523272204/d564412d8k.htm")

Find latest filings by company ticker or CIK:

``` python
from sec_downloader.types import RequestedFilings

metadatas = dl.get_filing_metadatas(
    RequestedFilings(ticker_or_cik="MSFT", form_type="10-K", limit=2)
)
print(metadatas)
```

    [FilingMetadata(accession_number='0000950170-24-087843',
                    form_type='10-K',
                    primary_doc_url='https://www.sec.gov/Archives/edgar/data/789019/000095017024087843/msft-20240630.htm',
                    items='',
                    primary_doc_description='10-K',
                    filing_date='2024-07-30',
                    report_date='2024-06-30',
                    cik='0000789019',
                    company_name='MICROSOFT CORP',
                    tickers=[Ticker(symbol='MSFT', exchange='Nasdaq')]),
     FilingMetadata(accession_number='0000950170-23-035122',
                    form_type='10-K',
                    primary_doc_url='https://www.sec.gov/Archives/edgar/data/789019/000095017023035122/msft-20230630.htm',
                    items='',
                    primary_doc_description='10-K',
                    filing_date='2023-07-27',
                    report_date='2023-06-30',
                    cik='0000789019',
                    company_name='MICROSOFT CORP',
                    tickers=[Ticker(symbol='MSFT', exchange='Nasdaq')])]

Alternatively, you can also use any of these to get the same answer:

    metadatas = dl.get_filing_metadatas("2/msft/10-K")
    metadatas = dl.get_filing_metadatas("2/789019/10-K")
    metadatas = dl.get_filing_metadatas("2/0000789019/10-K")

The parameters `limit` and `form_type` are optional. If omitted, `limit`
defaults to 1, and `form_type` defaults to ‘10-Q’.

``` python
metadatas = dl.get_filing_metadatas("NFLX")
print(metadatas)
```

    [FilingMetadata(accession_number='0001065280-24-000287',
                    form_type='10-Q',
                    primary_doc_url='https://www.sec.gov/Archives/edgar/data/1065280/000106528024000287/nflx-20240930.htm',
                    items='',
                    primary_doc_description='10-Q',
                    filing_date='2024-10-18',
                    report_date='2024-09-30',
                    cik='0001065280',
                    company_name='NETFLIX INC',
                    tickers=[Ticker(symbol='NFLX', exchange='Nasdaq')])]

Alternatively, you can also use any of these to get the same answer:

    metadatas = dl.get_filing_metadatas("nflx")
    metadatas = dl.get_filing_metadatas("1/NFLX")
    metadatas = dl.get_filing_metadatas("NFLX/10-Q")
    metadatas = dl.get_filing_metadatas("1/NFLX/10-Q")
    metadatas = dl.get_filing_metadatas(RequestedFilings(ticker_or_cik="NFLX"))
    metadatas = dl.get_filing_metadatas(RequestedFilings(limit=1, ticker_or_cik="NFLX", form_type="10-Q"))

## Download the HTML files

After obtaining the Primary Document URL, for example from the metadata,
you can proceed to download the HTML using this URL.

``` python
for metadata in metadatas:
    html = dl.download_filing(url=metadata.primary_doc_url).decode()
    print(html[:50])
    break  # same for all filings, let's just print the first one
```

    "<?xml version='1.0' encoding='ASCII'?>\n<!--XBRL Do"

# Alternative implementation: Wrapper

Files are downloaded to a temporary folder, immediately read into
memory, and then deleted. Let’s demonstrate how to download a single
file (latest 10-Q filing details in HTML format) to memory. The “glob”
pattern is used to select which files are read to memory.

``` python
from sec_edgar_downloader import Downloader as SecEdgarDownloader
from sec_downloader.download_storage import DownloadStorage

ONLY_HTML = "**/*.htm*"

storage = DownloadStorage(filter_pattern=ONLY_HTML)
with storage as path:
    dl = SecEdgarDownloader("MyCompanyName", "email@example.com", path)
    dl.get("10-Q", "AAPL", limit=1, download_details=True)
# all files are now deleted and only stored in memory

content = storage.get_file_contents()[0].content
print(f"{content[:50]}...")
```

    "<?xml version='1.0' encoding='ASCII'?>\n<!--XBRL Do..."

Downloading multiple documents:

``` python
storage = DownloadStorage()
with storage as path:
    dl = SecEdgarDownloader("MyCompanyName", "email@example.com", path)
    dl.get("10-K", "GOOG", limit=2)
# all files are now deleted and only stored in memory

for path, content in storage.get_file_contents():
    print(f"Path: {path}\nContent [len={len(content)}]: {content[:30]}...\n")
```

    ('Path: sec-edgar-filings/GOOG/10-K/0001652044-25-000014/full-submission.txt\n'
     'Content [len=14773739]: <SEC-DOCUMENT>0001652044-25-00...\n')
    ('Path: sec-edgar-filings/GOOG/10-K/0001652044-24-000022/full-submission.txt\n'
     'Content [len=13927595]: <SEC-DOCUMENT>0001652044-24-00...\n')

``` python
from sec_downloader import Downloader
dl = Downloader("MyCompanyName", "my.email@domain.com")
metadata = dl.get_filing_metadatas("https://www.sec.gov/Archives/edgar/data/2488/000000248825000009/0001193125-10-034401-index.htm", include_amends=True)
metadata
```

    [FilingMetadata(accession_number='0000002488-25-000009', form_type='8-K', primary_doc_url='https://www.sec.gov/Archives/edgar/data/2488/000000248825000009/amd-20250204.htm', items='2.02,7.01,9.01', primary_doc_description='8-K', filing_date='2025-02-04', report_date='2025-02-04', cik='0000002488', company_name='ADVANCED MICRO DEVICES INC', tickers=[Ticker(symbol='AMD', exchange='Nasdaq')])]

# Frequently Asked Questions (FAQ)

**Q: I’m encountering a ValueError stating ‘8-K/A’ forms are not
supported. How can I download “8-K/A” filings?**

**A:** To download amended filings such as “8-K/A”, you need to set the
parameter `include_amends=True`. For example, to download [this
filing](https://www.sec.gov/Archives/edgar/data/2488/000000248825000009/0001193125-10-034401-index.htm),
you would use:

``` python
from sec_downloader import Downloader
dl = Downloader("MyCompanyName", "my.email@domain.com")
str_cik = "0000002488"
str_acc = "0001193125-10-034401"
metadata = dl.get_filing_metadatas(f"{str_cik}/{str_acc}", include_amends=True)
metadata
```

    [FilingMetadata(accession_number='0001193125-10-034401', form_type='8-K', primary_doc_url='https://www.sec.gov/Archives/edgar/data/2488/000119312510034401/d8ka.htm', items='5.02', primary_doc_description='FORM 8-K/A', filing_date='2010-02-19', report_date='2010-02-16', cik='0000002488', company_name='ADVANCED MICRO DEVICES INC', tickers=[Ticker(symbol='AMD', exchange='Nasdaq')])]

# Contributing

Follow these steps to install the project locally for development:

1.  Install the project with the command `pip install -e ".[dev]"`.

> **Note** We highly recommend using virtual environments for Python
> development. If you’d like to use virtual environments, follow these
> steps instead:
>
> - Create a virtual environment `python3 -m venv .venv`
> - Activate the virtual environment `source .venv/bin/activate`
> - Install the project with the command `pip install -e ".[dev]"`