secedgar

https://sec-edgar.github.io/sec-edgar/
Admin
secedgar is a Python library for downloading SEC EDGAR filings and financial documents for publicly...
Tokens:21,541
Snippets:161
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install from source

Source: https://sec-edgar.github.io/sec-edgar/_sources/install.rst.txt

Clones the repository and installs the package locally.

```bash
$ git clone https://github.com/sec-edgar/sec-edgar.git
$ cd sec-edgar
$ pip install .
```

--------------------------------

### Install development version

Source: https://sec-edgar.github.io/sec-edgar/_sources/install.rst.txt

Installs the latest development version directly from the GitHub repository.

```bash
$ pip install git+https://github.com/sec-edgar/sec-edgar.git
```

--------------------------------

### Install nest-asyncio

Source: https://sec-edgar.github.io/sec-edgar/usage.html

Install the nest-asyncio package if you are using Jupyter Notebook.

```bash
pip install nest-asyncio

```

--------------------------------

### Setup virtual environment

Source: https://sec-edgar.github.io/sec-edgar/_sources/install.rst.txt

Commands to create and activate a virtual environment for the project.

```bash
$ pip install virtualenv
$ virtualenv env
$ source env/bin/activate
```

--------------------------------

### Install secedgar from source

Source: https://sec-edgar.github.io/sec-edgar/install.html

Clone the repository and install secedgar locally. This method is useful for developers contributing to the project.

```bash
git clone https://github.com/sec-edgar/sec-edgar.git
cd sec-edgar
pip install .
```

--------------------------------

### Set up a virtual environment

Source: https://sec-edgar.github.io/sec-edgar/install.html

It is recommended to use a virtual environment to manage project dependencies. Activate the environment before installing packages.

```bash
pip install virtualenv
virtualenv env
source env/bin/activate
```

--------------------------------

### Install sec-edgar via pip

Source: https://sec-edgar.github.io/sec-edgar/_sources/install.rst.txt

Installs the latest stable release of the library.

```bash
$ pip install secedgar
```

--------------------------------

### Install and Apply nest-asyncio for Jupyter

Source: https://sec-edgar.github.io/sec-edgar/_sources/usage.rst.txt

Install the nest-asyncio package using pip. Then, apply it at the start of your Jupyter Notebook to handle asynchronous operations.

```bash
pip install nest-asyncio
```

```python
import nest_asyncio
nest_asyncio.apply()
```

--------------------------------

### Install secedgar development version

Source: https://sec-edgar.github.io/sec-edgar/install.html

Install the latest development version directly from the GitHub repository.

```bash
pip install git+https://github.com/sec-edgar/sec-edgar.git
```

--------------------------------

### Example Directory Structure Output

Source: https://sec-edgar.github.io/sec-edgar/filings.html

Visual representation of the directory hierarchy generated by the custom pattern configuration.

```text
my_directory/
├── cik_aapl
│   └── 10-q
│       ├── 0000320193-19-000066.txt
│       ├── 0000320193-19-000076.txt
│       ├── 0000320193-20-000010.txt
│       ├── 0000320193-20-000052.txt
│       └── 0000320193-20-000062.txt
└── cik_msft
   └── 10-q
      ├── 0001564590-19-012709.txt
      ├── 0001564590-19-037549.txt
      ├── 0001564590-20-002450.txt
      ├── 0001564590-20-019706.txt
      └── 0001564590-20-047996.txt
```

--------------------------------

### Fetching All Quarterly Filings

Source: https://sec-edgar.github.io/sec-edgar/filings.html

Illustrates how to retrieve all filings for a specific quarter using start and end dates, and then save them.

```APIDOC
## Fetching All Quarterly Filings

### Description
This example demonstrates how to fetch all filings within a given quarter (defined by start and end dates) and save them to a specified directory.

### Method
`filings()` followed by `.save()`

### Endpoint
N/A (This is a library function call)

### Parameters
- **start_date** (date) - The start date of the quarter.
- **end_date** (date) - The end date of the quarter.
- **user_agent** (str) - The user agent string for making requests.
- **save_path** (str) - The directory path where the filings will be saved.

### Request Example
```python
from datetime import date
from secedgar import filings

quarterly_filings = filings(start_date=date(2020, 1 ,1),
                            end_date=date(2020, 3, 31),
                            user_agent="Name (email)")
quarterly_filings.save("/path/to/directory")
```

### Response
- **save()** method returns None, but saves filings to the specified path.
```

--------------------------------

### Install secedgar with pip

Source: https://sec-edgar.github.io/sec-edgar/install.html

Use this command to install the latest stable release of the secedgar package.

```bash
pip install secedgar
```

--------------------------------

### Initialize CompanyFilings Until Today

Source: https://sec-edgar.github.io/sec-edgar/filings.html

Initializes the CompanyFilings class to fetch filings from a start date until the current date. The end date defaults to today's date.

```python
from secedgar import FilingType, CompanyFilings
from datetime import date


```

--------------------------------

### Download Filings with ComboFilings

Source: https://sec-edgar.github.io/sec-edgar/filings.html

Use ComboFilings to download all filings between two specified dates and save them to a directory. Ensure you have the 'secedgar' library installed and import necessary modules.

```python
from datetime import date
from secedgar import ComboFilings

combo_filings = ComboFilings(start_date=date(2020, 1, 6),
                             end_date=date(2020, 11, 5))
combo_filings.save('/my_directory')
```

--------------------------------

### Initialize CompanyFilings for a single company

Source: https://sec-edgar.github.io/sec-edgar/filings.html

Initializes a CompanyFilings object for a single CIK with a specific filing type and start date.

```python
filing = CompanyFilings(cik_lookup="aapl",
                        filing_type=FilingType.FILING_10K,
                        start_date=date(2015, 1, 1),
                        user_agent="Name (email)")
```

--------------------------------

### GET /get_soup

Source: https://sec-edgar.github.io/sec-edgar/client.html

Fetches a page and returns it as a BeautifulSoup object.

```APIDOC
## GET /get_soup

### Description
Executes an HTTP request and parses the response text into a BeautifulSoup object using the lxml parser.

### Parameters
- **path** (str) - Required - A properly-formatted path.
- **params** (dict) - Required - Dictionary of parameters to pass to request.

### Response
- **soup** (BeautifulSoup) - The parsed HTML content.
```

--------------------------------

### Sec Edgar CLI Usage

Source: https://sec-edgar.github.io/sec-edgar/_sources/cli.rst.txt

The secedgar project provides a command-line interface for downloading EDGAR filings. Ensure you have 'click' installed (`pip install secedgar[cli]`) to use this feature.

```APIDOC
## Sec Edgar CLI

### Description
The secedgar project provides an easy-to-use command line interface to download filings from EDGAR without writing any code.

### Installation
To use the CLI, make sure you have click installed as a dependency. When installing from PyPi, you can use ``pip install secedgar[cli]``.

### Usage Example
```bash
secedgar <command>
```

(The specific commands and options are generated by the `click` library and are not detailed here.)
```

--------------------------------

### GET /get_response

Source: https://sec-edgar.github.io/sec-edgar/client.html

Executes an HTTP request and returns the response object.

```APIDOC
## GET /get_response

### Description
Executes an HTTP request to the specified path and returns a requests.Response object.

### Parameters
- **path** (str) - Required - A properly-formatted path.
- **params** (dict) - Optional - Dictionary of parameters to pass to request.
- **backoff_factor** (float) - Optional - Backoff factor for retries.

### Response
- **response** (requests.Response) - The response object from the request.
```

--------------------------------

### GET /get_urls

Source: https://sec-edgar.github.io/sec-edgar/filings.html

Retrieves the list of URLs for the specified filings.

```APIDOC
## GET /get_urls

### Description
Fetches the list of URLs for all text files associated with the CIKs and filing criteria defined in the object.

### Parameters
- **kwargs** (dict) - Optional - Arguments passed to the underlying NetworkClient.

### Response
- **urls** (list) - A list of URLs for the .txt files to download.
```

--------------------------------

### Apply nest-asyncio in Jupyter

Source: https://sec-edgar.github.io/sec-edgar/usage.html

Apply nest-asyncio at the start of your Jupyter Notebook to handle asynchronous operations.

```python
import nest_asyncio
nest_asyncio.apply()

```

--------------------------------

### secedgar.filings() Function

Source: https://sec-edgar.github.io/sec-edgar/filings.html

The primary utility method to get the most appropriate filing object based on provided arguments. It acts as a factory for different filing classes.

```APIDOC
## GET secedgar.filings()

### Description
Utility method to get the best filing object based on provided arguments. It acts as a factory for different filing classes like `CompanyFilings`, `DailyFilings`, `QuarterlyFilings`, and `ComboFilings`.

### Method
GET (conceptual, as it's a function call)

### Endpoint
N/A (Python function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **cik_lookup** (str) - Optional - Central Index Key (CIK) for the company of interest. Can be a single CIK or a list of CIKs.
- **start_date** (datetime.date) - Optional - The start date for fetching filings.
- **end_date** (datetime.date) - Optional - The end date for fetching filings. Defaults to December 9, 2025.
- **filing_type** (secedgar.core.filing_types.FilingType) - Optional - The specific type of filing to fetch. If None, all filing types for the specified CIKs will be returned.
- **count** (int) - Optional - The maximum number of filings to fetch. Defaults to fetching all available filings.
- **client** (secedgar.client.NetworkClient) - Optional - A pre-configured NetworkClient instance to use for fetching. Defaults to `secedgar.client.NetworkClient` if not provided.
- **entry_filter** (function) - Optional - A boolean function that determines if a `FilingEntry` should be kept. Defaults to `lambda _: True`.
- **user_agent** (str) - Required for API calls - A user-agent string identifying your application, typically in the format "Name (email)".
- ****kwargs** - Optional - Additional keyword arguments to pass to the `NetworkClient` if no client is specified.

### Request Example
```python
from datetime import date
from secedgar import filings, FilingType

# Example 1: Fetch filings over a time span
my_filings = filings(start_date=date(2020, 12, 10),
                     end_date=date(2020, 12, 15),
                     filing_type=FilingType.FILING_4,
                     user_agent="Name (email)",
                     count=50)

# Example 2: Fetch filings for specific companies and filing type
company_filings = filings(cik_lookup=["aapl", "fb"],
                          filing_type=FilingType.FILING_10Q,
                          user_agent="Name (email)")

# Example 3: Fetch all filings for a single day
daily_filings = filings(start_date=date(2020, 1, 3),
                        end_date=date(2020, 1, 3),
                        user_agent="Name (email)")
```

### Response
#### Success Response (200)
Returns an object that represents the fetched filings. The specific type of object returned depends on the arguments provided (e.g., `ComboFilings`, `CompanyFilings`, `DailyFilings`, `QuarterlyFilings`). This object will have methods like `get_urls()` and `save()`.

#### Response Example
```json
{
  "filings_data": [
    {
      "accession_number": "0001193125-20-317898",
      "filing_date": "2020-12-15",
      "report_date": "2020-12-15",
      "form": "4",
      "company_name": "Apple Inc.",
      "cik": "0000320193"
    }
    // ... more filing entries
  ]
}
```
```

--------------------------------

### Get Ticker to CIK Map - secedgar

Source: https://sec-edgar.github.io/sec-edgar/cikmap.html

Fetches a dictionary mapping company tickers to CIK numbers. Requires a user agent string. The cache can be cleared using `get_cik_map.cache_clear()`.

```python
from secedgar.cik_lookup import get_cik_map

dict(list(get_cik_map(user_agent="Example (email@example.com)")["ticker"].items())[:5])
```

--------------------------------

### Get Company Name to CIK Map - secedgar

Source: https://sec-edgar.github.io/sec-edgar/cikmap.html

Fetches a dictionary mapping company names (titles) to CIK numbers. Requires a user agent string. The cache can be cleared using `get_cik_map.cache_clear()`.

```python
from secedgar.cik_lookup import get_cik_map

dict(list(get_cik_map(user_agent="Example (email@example.com)")["title"].items())[:5])
```

--------------------------------

### Configure Custom Filing Directory Structure with Python

Source: https://sec-edgar.github.io/sec-edgar/_sources/filings.rst.txt

Demonstrates using 'dir_pattern' and 'file_pattern' with 'CompanyFilings' to organize downloaded files by CIK and filing type.

```python
from secedgar import CompanyFilings, FilingType

f = CompanyFilings(cik_lookup=["aapl", "msft"],
                   filing_type=FilingType.FILING_10Q,
                   count=5,
                   user_agent="Name (email)")
f.save("./my_directory",
       dir_pattern="cik_{cik}/{type}",
       file_pattern="{accession_number}")
```

--------------------------------

### Download Quarterly Filings

Source: https://sec-edgar.github.io/sec-edgar/filings.html

Initializes a QuarterlyFilings instance with a user agent and saves the filings to a specified directory.

```python
import secedgar as sec
quarterly = sec.QuarterlyFilings(year=2021,
                                 quarter=2,
                                 user_agent="Name (email)")
quarterly.save("/path/to/dir")
```

--------------------------------

### ComboFilings Initialization and Usage

Source: https://sec-edgar.github.io/sec-edgar/filings.html

This snippet demonstrates how to initialize the ComboFilings class and save the retrieved filings to a local directory.

```APIDOC
## ComboFilings Class

### Description
Class for retrieving all filings between specified dates. Internally, this class uses a mixture of `DailyFilings` and `QuarterlyFilings` to get all of the needed filings.

### Method
Initialization

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Constructor Parameters
- **start_date** (Union[str, `datetime.datetime`, `datetime.date`]) - Optional - Date before which not to fetch reports. Stands for “date after.” Defaults to None (will fetch all filings before `end_date`).
- **end_date** (Union[str, `datetime.datetime`, `datetime.date`]) - Optional - Date after which not to fetch reports. Stands for “date before.” Defaults to today.
- **user_agent** (Union[str, None]) - Optional - Value used for HTTP header “User-Agent” for all requests. If given None, a valid client with user_agent must be given.
- **client** (Union[None, `secedgar.client.NetworkClient`]) - Optional - Client to use for fetching data. If None is given, a user_agent must be given.
- **entry_filter** (function) - Optional - A boolean function to determine if the FilingEntry should be kept. Defaults to lambda _: True.
- **balancing_point** (int) - Optional - Number of days from which to change lookup method from using `DailyFilings` to `QuarterlyFilings`. Defaults to 30.
- **kwargs** - Optional - Any keyword arguments to pass to `NetworkClient` if no client is specified.

### Methods
#### `get_urls()`

##### Description
Get all urls between `start_date` and `end_date`.

##### Parameters
None

#### `save(directory, dir_pattern=None, file_pattern='{accession_number}', download_all=False, daily_date_format='%Y%m%d')`

##### Description
Save all filings between `start_date` and `end_date`. Only filings that satisfy args given at initialization will be saved.

##### Parameters
- **directory** (str) - Required - Directory where filings should be stored.
- **dir_pattern** (str) - Optional - Format string for subdirectories. Defaults to None.
- **file_pattern** (str) - Optional - Format string for files. Defaults to “{accession_number}”.
- **download_all** (bool) - Optional - Type of downloading system, if true downloads all data for each day, if false downloads each file in index. Defaults to False.
- **daily_date_format** (str) - Optional - Format string to use for the {date} pattern. Defaults to “%Y%m%d”.

### Example
```python
from datetime import date
from secedgar import ComboFilings

combo_filings = ComboFilings(start_date=date(2020, 1, 6),
                             end_date=date(2020, 11, 5))
combo_filings.save('/my_directory')
```
```

--------------------------------

### Initialize CompanyFilings with Date Range

Source: https://sec-edgar.github.io/sec-edgar/filings.html

Initializes the CompanyFilings class to fetch 10-K filings for a specific company within a given date range. Requires a user-agent string.

```python
from secedgar import FilingType, CompanyFilings
from datetime import date

filing = CompanyFilings(cik_lookup="aapl",
                        filing_type=FilingType.FILING_10K,
                        start_date=date(2015, 1, 1),
                        end_date=date(2019, 1, 1),
                        user_agent="Name (email)")
```

--------------------------------

### Instantiate NetworkClient

Source: https://sec-edgar.github.io/sec-edgar/client.html

Create a basic instance of NetworkClient. The 'user_agent' argument is mandatory. This is the default client used by secedgar.

```python
from secedgar.client import NetworkClient
client = NetworkClient(user_agent="Name (email)")
```

--------------------------------

### Fetch All Quarterly Filings

Source: https://sec-edgar.github.io/sec-edgar/filings.html

Fetches all quarterly filings for a given date range. Requires a user-agent string.

```python
from datetime import date
from secedgar import filings

# all quarterly filings
quarterly_filings = filings(start_date=date(2020, 1 ,1),
                            end_date=date(2020, 3, 31),
                            user_agent="Name (email)")
quarterly_filings.save("/path/to/directory")
```

--------------------------------

### Initialize CompanyFilings for multiple CIKs

Source: https://sec-edgar.github.io/sec-edgar/usage.html

Initialize the CompanyFilings class to fetch filings for multiple companies using a list of CIKs or company names. A user agent is required.

```python
from secedgar import CompanyFilings, FilingType

my_filings = CompanyFilings(cik_lookup=['aapl', 'msft', 'Facebook'],
                            filing_type=FilingType.FILING_10Q,
                            count=15,
                            user_agent='Name (email)')

```

--------------------------------

### Initialize DailyFilings with Custom Filter

Source: https://sec-edgar.github.io/sec-edgar/filings.html

Instantiate the DailyFilings class with a specific date and a custom entry_filter function. Ensure a valid user_agent is provided for authentication.

```python
from datetime import date
from secedgar.core import DailyFilings

d = DailyFilings(date=date(2020, 12, 10),
                 entry_filter=get_company_ab_10k,
                 user_agent="Name (email)")
```

--------------------------------

### Initialize CompanyFilings for a Single Ticker

Source: https://sec-edgar.github.io/sec-edgar/_sources/usage.rst.txt

Instantiate the CompanyFilings class to fetch filings for a specific company. Ensure you provide a valid CIK lookup, filing type, count, and a descriptive user agent string.

```python
from secedgar import CompanyFilings, FilingType

my_filings = CompanyFilings(cik_lookup='aapl',
							filing_type=FilingType.FILING_10Q,
							count=15,
							user_agent='Name (email)')
```

--------------------------------

### Initialize CompanyFilings for Multiple Tickers

Source: https://sec-edgar.github.io/sec-edgar/_sources/usage.rst.txt

Fetch filings for multiple companies by passing a list of tickers or company names to the 'cik_lookup' argument. This allows for batch downloading of financial data.

```python
from secedgar import CompanyFilings, FilingType

my_filings = CompanyFilings(cik_lookup=['aapl', 'msft', 'Facebook'],
							filing_type=FilingType.FILING_10Q,
							count=15,
							user_agent='Name (email)')
```

--------------------------------

### Initialize CompanyFilings for a single CIK

Source: https://sec-edgar.github.io/sec-edgar/usage.html

Initialize the CompanyFilings class to fetch filings for a single company using its CIK. Ensure you provide a valid user agent string.

```python
from secedgar import CompanyFilings, FilingType

my_filings = CompanyFilings(cik_lookup='aapl',
                            filing_type=FilingType.FILING_10Q,
                            count=15,
                            user_agent='Name (email)')

```

--------------------------------

### Initialize CompanyFilings for multiple companies

Source: https://sec-edgar.github.io/sec-edgar/filings.html

Initializes a CompanyFilings object for a list of CIKs. Requires the secedgar and datetime modules.

```python
from secedgar import FilingType, CompanyFilings
from datetime import date

filing = CompanyFilings(cik_lookup=["aapl", "msft", "fb"],
                        filing_type=FilingType.FILING_10K,
                        start_date=date(2015, 1, 1),
                        user_agent="Name (email)")
```

--------------------------------

### NetworkClient Initialization

Source: https://sec-edgar.github.io/sec-edgar/client.html

Initializes a new NetworkClient instance for handling SEC EDGAR requests.

```APIDOC
## NetworkClient Initialization

### Description
Creates a new instance of the NetworkClient to manage requests to the SEC EDGAR database.

### Parameters
- **user_agent** (str) - Required - Value used for HTTP header "User-Agent".
- **retry_count** (int) - Optional - Number of times to retry connecting. Defaults to 3.
- **batch_size** (int) - Optional - Number of filings to receive per request. Defaults to 10.
- **backoff_factor** (float) - Optional - Backoff factor for retries. Defaults to 0.
- **rate_limit** (int) - Optional - Number of requests per second. Defaults to 10.

### Request Example
from secedgar.client import NetworkClient
client = NetworkClient(user_agent="Name (email)", backoff_factor=1)
```

--------------------------------

### CompanyFilings Class Initialization

Source: https://sec-edgar.github.io/sec-edgar/filings.html

Details on how to initialize the CompanyFilings class to retrieve filings for a specific company, with options for filing type, date range, and user agent.

```APIDOC
## CompanyFilings Class Initialization

### Description
This section details the parameters for initializing the `CompanyFilings` class, which is the base class for receiving EDGAR filings for a specific company. It allows for filtering by company CIK, filing type, date range, and other options.

### Method
`secedgar.CompanyFilings()`

### Endpoint
N/A (This is a class constructor)

### Parameters
- **cik_lookup** (str) - Central Index Key (CIK) for the company of interest. (Required)
- **filing_type** (FilingType enum or None) - Specifies the type of filing to retrieve. Defaults to None (all filing types).
- **user_agent** (str or None) - Value for the HTTP header "User-Agent". Required if no client is provided.
- **start_date** (str, datetime, date, or None) - Date before which not to fetch reports. Defaults to None.
- **end_date** (str, datetime, date, or None) - Date after which not to fetch reports. Defaults to today's date.
- **count** (int) - Maximum number of filings to fetch. Defaults to all available filings.
- **ownership** (str) - Whether to include or exclude ownership filings. Must be 'include' or 'exclude'. Defaults to 'include'.
- **match_format** (str) - Format to match filings. Must be 'EXACT', 'AMEND', or 'ALL'. Defaults to 'ALL'.
- **client** (NetworkClient) - An instance of NetworkClient. See `secedgar.client.NetworkClient` for accepted kwargs.

### Request Example
```python
from secedgar import FilingType, CompanyFilings
from datetime import date

filing = CompanyFilings(cik_lookup="aapl",
                        filing_type=FilingType.FILING_10K,
                        start_date=date(2015, 1, 1),
                        end_date=date(2019, 1, 1),
                        user_agent="Name (email)")
```

### Response
- Initializes a `CompanyFilings` object with the specified parameters.
```

--------------------------------

### Fetching Limited Quarterly Filings (10-K and 10-Q)

Source: https://sec-edgar.github.io/sec-edgar/filings.html

Shows how to fetch quarterly filings and apply a filter to include only 10-K and 10-Q forms, then save them.

```APIDOC
## Fetching Limited Quarterly Filings (10-K and 10-Q)

### Description
This example demonstrates how to fetch quarterly filings within a specific date range and apply a filter to include only '10-K' and '10-Q' filings. The filtered filings are then saved to a local directory.

### Method
`filings()` followed by `.save()`

### Endpoint
N/A (This is a library function call)

### Parameters
- **start_date** (date) - The start date for fetching filings.
- **end_date** (date) - The end date for fetching filings.
- **user_agent** (str) - The user agent string for making requests.
- **entry_filter** (function) - A function to filter filings, specifically for '10-K' and '10-Q' forms in this case.
- **save_path** (str) - The directory path where the filings will be saved.

### Request Example
```python
from datetime import date
from secedgar import filings

limit_to_10k_10q = lambda f: f.form_type.lower() in ("10-k", "10-q")
quarterly_filings_limited = filings(start_date=date(2020, 1 ,1),
                                    end_date=date(2020, 3, 31),
                                    user_agent="Name (email)",
                                    entry_filter=limit_to_10k_10q)
quarterly_filings_limited.save("/path/to/other/directory")
```

### Response
- **save()** method returns None, but saves filings to the specified path.
```

--------------------------------

### Fetch and Save Limited Daily Filings

Source: https://sec-edgar.github.io/sec-edgar/filings.html

Fetches daily filings and saves only form 4 filings to a specified directory. Requires a user-agent string.

```python
limit_to_form4 = lambda f: f.form_type.lower() == "4"
daily_filings_limited = filings(start_date=date(2020, 1 ,3),
                                end_date=date(2020, 1, 3),
                                user_agent="Name (email)",
                                entry_filter=limit_to_form4)
daily_filings_limited.save("/path/to/other/directory")
```

--------------------------------

### Instantiate NetworkClient with Backoff Factor

Source: https://sec-edgar.github.io/sec-edgar/client.html

Instantiate NetworkClient and configure the 'backoff_factor' to handle 429 errors. This setting influences retry behavior when encountering rate limiting issues.

```python
from secedgar.client import NetworkClient
client = NetworkClient(user_agent="Name (email)", backoff_factor=1)
```

--------------------------------

### Fetch Limited Quarterly Filings

Source: https://sec-edgar.github.io/sec-edgar/filings.html

Fetches quarterly filings and saves only 10-K and 10-Q forms to a specified directory. Requires a user-agent string.

```python
# limit which quarterly filings to use
# saves only 10-K and 10-Q filings from quarter
limit_to_10k_10q = lambda f: f.form_type.lower() in ("10-k", "10-q")
quarterly_filings_limited = filings(start_date=date(2020, 1 ,1),
                                    end_date=date(2020, 3, 31),
                                    user_agent="Name (email)",
                                    entry_filter=limit_to_10k_10q)
quarterly_filings_limited.save("/path/to/other/directory")
```

--------------------------------

### Initialize CIKLookup with Tickers and User Agent

Source: https://sec-edgar.github.io/sec-edgar/_sources/ciklookup.rst.txt

Instantiate the CIKLookup class with a list of company tickers or names and a required user agent string. This prepares the lookup object for retrieving CIKs.

```python
from secedgar.cik_lookup import CIKLookup

lookups = CIKLookup(['aapl', 'msft', 'Facebook'],
                    user_agent="Name (email)")
```

--------------------------------

### Class: QuarterlyFilings

Source: https://sec-edgar.github.io/sec-edgar/filings.html

Initializes the QuarterlyFilings object to prepare for fetching filings from a specific year and quarter.

```APIDOC
## QuarterlyFilings Initialization

### Description
Initializes the class for retrieving all filings from a specific year and quarter.

### Parameters
- **year** (int) - Required - Must be between 1993 and the current year.
- **quarter** (int) - Required - Must be 1, 2, 3, or 4.
- **user_agent** (str) - Optional - Value for HTTP 'User-Agent' header.
- **client** (NetworkClient) - Optional - Client used for fetching data.
- **entry_filter** (function) - Optional - Boolean function to filter FilingEntry objects.

### Request Example
```python
import secedgar as sec
quarterly = sec.QuarterlyFilings(year=2021, quarter=2, user_agent="Name (email)")
```
```

--------------------------------

### Save Fetched Filings to a Directory

Source: https://sec-edgar.github.io/sec-edgar/_sources/usage.rst.txt

Use the 'save' method to store all downloaded filings to a specified local directory. The path can be relative or absolute.

```python
my_filings.save('~/tempdir')
```

--------------------------------

### CompanyFilings Initialization

Source: https://sec-edgar.github.io/sec-edgar/filings.html

Initializes a new CompanyFilings object to define the scope of filings to be retrieved.

```APIDOC
## CompanyFilings Initialization

### Description
Initializes the filing search parameters for one or more companies.

### Parameters
- **cik_lookup** (list/str) - Required - CIK or list of CIKs to search.
- **filing_type** (FilingType) - Required - The type of filing (e.g., FilingType.FILING_10K).
- **start_date** (date) - Optional - Start date for the search.
- **user_agent** (str) - Required - User agent string for SEC identification.

### Request Example
filing = CompanyFilings(cik_lookup=["aapl", "msft"], filing_type=FilingType.FILING_10K, start_date=date(2015, 1, 1), user_agent="Name (email)")
```

--------------------------------

### POST /save

Source: https://sec-edgar.github.io/sec-edgar/filings.html

Downloads and saves the retrieved filings to the local filesystem.

```APIDOC
## POST /save

### Description
Saves the retrieved filing files into the specified directory structure.

### Parameters
- **directory** (str) - Required - Path to the directory where files should be saved.
- **dir_pattern** (str) - Optional - Format string for subdirectories (default: "{cik}/{type}").
- **file_pattern** (str) - Optional - Format string for files (default: "{accession_number}").

### Response
- **None** - Returns nothing upon success.

### Errors
- **ValueError** - Raised if no text URLs are available for the filing object.
```

--------------------------------

### DailyFilings Class Initialization

Source: https://sec-edgar.github.io/sec-edgar/filings.html

Initialize the DailyFilings class to fetch filings for a specific date. You can optionally provide a user agent, a custom network client, and an entry filter function.

```APIDOC
## DailyFilings Class

### Description
Class for retrieving all daily filings from https://www.sec.gov/Archives/edgar/daily-index.

### Parameters
- **date** (datetime.date) - Required - Date of daily filing to fetch.
- **user_agent** (Union[str, NoneType], optional) - Value used for HTTP header “User-Agent” for all requests. If given None, a valid client with user_agent must be given. Defaults to None.
- **client** (Union[NoneType, secedgar.client.NetworkClient], optional) - Client to use for fetching data. If None is given, a user_agent must be given to pass to `secedgar.client.NetworkClient`. Defaults to `secedgar.client.NetworkClient` if none is given.
- **entry_filter** (function, optional) - A boolean function to determine if the FilingEntry should be kept. Defaults to lambda _: True. The `FilingEntry` object exposes 7 variables which can be used to filter which filings to keep. These are “cik”, “company_name”, “form_type”, “date_filed”, “file_name”, and “path”.
- **kwargs** - Keyword arguments to pass to `secedgar.filings._index.IndexFilings`.

### Example Usage
```python
from datetime import date
from secedgar.core import DailyFilings

# Example with user_agent
d = DailyFilings(date=date(2020, 12, 10), user_agent="Name (email)")

# Example with entry_filter
def get_company_a_filings(filing_entry):
    return filing_entry.company_name == "Company A"

d_filtered = DailyFilings(date=date(2020, 12, 10), entry_filter=get_company_a_filings, user_agent="Name (email)")
```
```

--------------------------------

### Fetching and Saving Daily Filings with Form Type Filter

Source: https://sec-edgar.github.io/sec-edgar/filings.html

Demonstrates how to fetch daily filings and filter them to include only Form 4 filings, then save them to a specified directory.

```APIDOC
## Fetching and Saving Daily Filings with Form Type Filter

### Description
This example shows how to retrieve daily filings for a specific date range and apply a filter to include only 'Form 4' filings. The filtered filings are then saved to a local directory.

### Method
`filings()` followed by `.save()`

### Endpoint
N/A (This is a library function call)

### Parameters
- **start_date** (date) - The start date for fetching filings.
- **end_date** (date) - The end date for fetching filings.
- **user_agent** (str) - The user agent string for making requests.
- **entry_filter** (function) - A function to filter filings based on criteria (e.g., form type).
- **save_path** (str) - The directory path where the filings will be saved.

### Request Example
```python
from datetime import date
from secedgar import filings

limit_to_form4 = lambda f: f.form_type.lower() == "4"
daily_filings_limited = filings(start_date=date(2020, 1 ,3),
                                end_date=date(2020, 1, 3),
                                user_agent="Name (email)",
                                entry_filter=limit_to_form4)
daily_filings_limited.save("/path/to/other/directory")
```

### Response
- **save()** method returns None, but saves filings to the specified path.
```

--------------------------------

### Filing Classes

Source: https://sec-edgar.github.io/sec-edgar/filings.html

Directly use specific classes for more control over fetching filings, such as `CompanyFilings`, `DailyFilings`, `QuarterlyFilings`, and `ComboFilings`.

```APIDOC
### Description
These classes provide more granular control over fetching SEC EDGAR filings compared to the general `secedgar.filings()` function.

- **`secedgar.CompanyFilings`**: For fetching filings for specific companies.
- **`secedgar.DailyFilings`**: For fetching filings from a specific date.
- **`secedgar.QuarterlyFilings`**: For fetching filings from a specific quarter.
- **`secedgar.ComboFilings`**: For fetching filings over a time span, useful for spanning multiple quarters.

### Usage
Instantiate the desired class with appropriate parameters and then use its methods (e.g., `get_urls()`, `save()`).

### Example
```python
from secedgar import CompanyFilings, FilingType

# Example: Fetching 10-Q filings for Apple Inc.
company_filings = CompanyFilings(cik_lookup="AAPL",
                                 filing_type=FilingType.FILING_10Q,
                                 user_agent="Name (email)")

# Get URLs of the filings
urls = company_filings.get_urls()

# Save the filings to a directory
company_filings.save("/path/to/save/filings")
```

### Parameters (General)
Parameters vary by class, but commonly include:
- **cik_lookup** (str or list[str]): CIK(s) of the company/companies.
- **start_date** (datetime.date): Start date for the filing period.
- **end_date** (datetime.date): End date for the filing period.
- **filing_type** (FilingType): The type of filing to retrieve.
- **user_agent** (str): Required user-agent string.
- **client** (NetworkClient): Optional NetworkClient instance.

### Response
Each class instance provides methods to retrieve filing information, such as URLs, and to save the filings.
```

--------------------------------

### Method: save

Source: https://sec-edgar.github.io/sec-edgar/filings.html

Saves all daily filings for the specified quarter to a local directory.

```APIDOC
## save(directory, dir_pattern, file_pattern, download_all)

### Description
Saves all daily filings to the specified directory, organizing them by company name and form type.

### Parameters
- **directory** (str) - Required - Directory where filings should be stored.
- **dir_pattern** (str) - Optional - Format string for subdirectories (default: {year}/QTR{quarter}/{cik}).
- **file_pattern** (str) - Optional - Format string for files (default: {accession_number}).
- **download_all** (bool) - Optional - If true, downloads all data for each day; if false, downloads each file in index (default: False).

### Request Example
```python
quarterly.save("/path/to/dir")
```
```

--------------------------------

### Retrieve and access company facts

Source: https://sec-edgar.github.io/sec-edgar/rest_api.html

Demonstrates fetching company facts and accessing specific fields like value, fiscal year, and filing date from the returned dictionary.

```python
>>> facts = get_company_facts(["aapl"], "Name (email@example.com)")
>>> single_fact = facts["aapl"]["facts"]["us-gaap"]["Assets"]["units"]["USD"][0]
>>> single_fact["val"]
39572000000
>>> single_fact["fy"]
2009
>>> single_fact["fp"]
Q3
>>> single_fact["form"]
'10-Q'
>>> single_fact["filed"]
'2009-07-22'
```

--------------------------------

### Fetch CIKs by Ticker

Source: https://sec-edgar.github.io/sec-edgar/_sources/cikmap.rst.txt

Fetches CIKs using company tickers as keys. Requires a user agent string. Only the first 5 results are shown.

```python
from secedgar.cik_lookup import get_cik_map
dict(list(get_cik_map(user_agent="Example (email@example.com)")["ticker"].items())[:5])
```

--------------------------------

### CIKLookup Class Initialization

Source: https://sec-edgar.github.io/sec-edgar/_sources/ciklookup.rst.txt

Initializes the CIKLookup class to map company identifiers to CIKs.

```APIDOC
## CIKLookup Initialization

### Description
Initializes the CIKLookup object to resolve company tickers or names to CIKs.

### Parameters
- **lookups** (list/tuple) - Required - A list or tuple of strings representing company tickers or names.
- **user_agent** (string) - Required - The user agent string required for SEC requests.

### Request Example
from secedgar.cik_lookup import CIKLookup

lookups = CIKLookup(['aapl', 'msft', 'Facebook'], user_agent="Name (email)")

### Response
- **lookup_dict** (dict) - A dictionary mapping the input identifiers to their corresponding CIK strings.
```

--------------------------------

### Fetch CIKs by Company Name

Source: https://sec-edgar.github.io/sec-edgar/_sources/cikmap.rst.txt

Fetches CIKs using company names (titles) as keys. Requires a user agent string. Only the first 5 results are shown.

```python
from secedgar.cik_lookup import get_cik_map
dict(list(get_cik_map(user_agent="Example (email@example.com)")["title"].items())[:5])
```

--------------------------------

### Retrieve filings for a single day

Source: https://sec-edgar.github.io/sec-edgar/filings.html

Fetches all filings available for a specific date.

```python
from datetime import date
from secedgar import filings

# all filings for
daily_filings = filings(start_date=date(2020, 1 ,3),
                        end_date=date(2020, 1, 3),
                        user_agent="Name (email)")
daily_filings.save("/path/to/directory")
```

--------------------------------

### Save Fetched Filings

Source: https://sec-edgar.github.io/sec-edgar/usage.html

Use the save method to store all fetched filings to a specified directory. The path can be a relative or absolute path.

```python
my_filings.save('~/tempdir')

```

--------------------------------

### CLI Command: secedgar daily

Source: https://sec-edgar.github.io/sec-edgar/cli.html

Downloads daily filings from EDGAR for a specified date.

```APIDOC
## CLI Command: secedgar daily

### Description
Downloads daily filings from EDGAR for a specific date.

### Usage
`secedgar daily [OPTIONS]`

### Options
- **-u, --user-agent** (str) - Required - User agent string for HTTP headers.
- **-d, --date** (str) - Required - Date to look up filings (YYYYMMDD).
- **--directory** (str) - Optional - Directory to save files (defaults to current working directory).
```

--------------------------------

### DailyFilings.save() Method

Source: https://sec-edgar.github.io/sec-edgar/filings.html

Save all daily filings to a specified directory with customizable patterns for subdirectories and filenames.

```APIDOC
## DailyFilings.save()

### Description
Save all daily filings.
Store all filings for each unique company name under a separate subdirectory within given directory argument. Creates directory with date in YYYYMMDD format within given directory.

### Parameters
- **directory** (str) - Required - Directory where filings should be stored. Will be broken down further by company name and form type.
- **dir_pattern** (str, optional) - Format string for subdirectories. Default is {date}/{cik}. Valid options that must be wrapped in curly braces are date and cik.
- **date_format** (str, optional) - Format string to use for the {date} pattern. Default is `%Y%m%d`.
- **file_pattern** (str, optional) - Format string for files. Default is {accession_number}. Valid options are accession_number.
- **download_all** (bool, optional) - Type of downloading system, if true downloads all data for the day, if false downloads each file in index. Default is False.

### Example Usage
```python
from datetime import date
from secedgar.core import DailyFilings

d = DailyFilings(date=date(2020, 12, 10), user_agent="Name (email)")
d.save(directory="./filings", dir_pattern="{date}/{company_name}", file_pattern="{form_type}-{accession_number}")
```
```

--------------------------------

### Retrieve filings over a time span

Source: https://sec-edgar.github.io/sec-edgar/filings.html

Fetches a specific number of filings within a date range using the filings factory function.

```python
from datetime import date
from secedgar import filings, FilingType

# secedgar creates correct filing object for given arguments
# this will fetch the first 50 filings found over the time span
my_filings = filings(start_date=date(2020, 12, 10),
                     end_date=date(2020, 12, 15),
                     filing_type=FilingType.FILING_4,
                     user_agent="Name (email)",
                     count=50)

# easy access to methods shared across all 4 different filing classes
my_filings_urls = my_filings.get_urls()
my_filings.save("/path/to/directory")
```

--------------------------------

### CLI Command: secedgar filing

Source: https://sec-edgar.github.io/sec-edgar/cli.html

Downloads specific company or ticker filings from EDGAR.

```APIDOC
## CLI Command: secedgar filing

### Description
Downloads filings for specific companies or tickers based on filing type and date range.

### Usage
`secedgar filing [OPTIONS]`

### Options
- **-u, --user-agent** (str) - Required - User agent string for HTTP headers.
- **-l, --lookups** (str) - Required - Companies and tickers to include.
- **-t, --ftype** (str) - Required - Filing type (e.g., FILING_10K).
- **-s, --start** (str) - Optional - Start date (YYYYMMDD).
- **-e, --end** (str) - Optional - End date (YYYYMMDD).
- **-n, --count** (int) - Optional - Number of filings to save.
- **--directory** (str) - Optional - Directory to save files.
```

--------------------------------

### get_xbrl_frames()

Source: https://sec-edgar.github.io/sec-edgar/rest_api.html

Fetches XBRL data for a specific concept name within a given year and optionally quarter.

```APIDOC
## GET /xbrl-frames

### Description
Get data for concept name in year (and quarter, if given).

### Method
GET

### Endpoint
/xbrl-frames

### Parameters
#### Query Parameters
- **user_agent** (str) - Required - User agent to send to the SEC.
- **concept_name** (str) - Required - Concept name to get. For example, “Assets”.
- **year** (int) - Required - Year to get concept data for.
- **quarter** (int | None) - Optional - Quarter to get data for. If given None, will look for data for the entire year. Defaults to None.
- **currency** (str) - Optional - Currency to filter by. Defaults to 'USD'.
- **instantaneous** (bool) - Optional - Whether to look for instantaneous data. See SEC website for more. Defaults to False.

### Response
#### Success Response (200)
- **dict** - Dictionary with information about concept_name. Dig into the data key for all period data.

### Request Example
```python
frames = get_xbrl_frames(user_agent="Name (email@example.com)",
                         concept_name="Assets",
                         year=2020,
                         quarter=3,
                         instantaneous=True)
print(frames["data"][-1]["entityName"])
# Prints "MOXIAN (BVI) INC"
print(frames["data"][-1]["val"])
# Prints 2295657
print(frames["data"][-1]["accn"])
# Prints "0001493152-22-013323"
```
```

--------------------------------

### Retrieve company concepts

Source: https://sec-edgar.github.io/sec-edgar/rest_api.html

Fetches specific company concept data using a ticker or CIK. Requires a valid user agent string.

```python
concept = "AccountsPayableCurrent"
get_company_concepts(lookups=["AAPL"],
                     user_agent="Name (email@example.com)",
                     concept_name=concept)
```

--------------------------------

### secedgar.client.NetworkClient

Source: https://sec-edgar.github.io/sec-edgar/_sources/client.rst.txt

The NetworkClient class is the primary interface for interacting with the SEC's website. It handles all necessary utilities for data requests.

```APIDOC
## secedgar.client.NetworkClient

### Description
This class provides utilities for interacting with the SEC's website and making data requests.

### Method
N/A (Class documentation)

### Endpoint
N/A (Class documentation)

### Parameters
N/A (Class documentation)

### Request Example
N/A (Class documentation)

### Response
N/A (Class documentation)
```

--------------------------------

### Retrieve filings for specific companies

Source: https://sec-edgar.github.io/sec-edgar/filings.html

Fetches a specific filing type for one or more company tickers.

```python
from secedgar import filings, FilingType

# similar to above, but fetches filings for specific tickers
company_filings = filings(cik_lookup=["aapl", "fb"],
                          filing_type=sec.FilingType.FILING_10Q,
                          user_agent="Name (email)")
company_filings_urls = company_filings.get_urls()
company_filings.save("/path/to/directory")
```

--------------------------------

### Access CIK lookup dictionary

Source: https://sec-edgar.github.io/sec-edgar/ciklookup.html

The lookup_dict property returns a dictionary mapping the provided search terms to their respective CIK strings.

```python
{'aapl': '320193', 'msft': '789019', 'Facebook': '0001326801'}
```
Tokens:
Raw