### Installation and Setup

Source: https://github.com/dgunning/edgartools/blob/main/notebooks/10k-business-description-python.ipynb

Instructions on how to install the edgartools library and set up your identity for SEC requests.

```APIDOC
## Installation

Install the edgartools library using pip:

```python
!pip install -U edgartools
```

## Setup

The SEC requires automated tools to identify themselves. Replace the placeholder email with your own valid email address.

```python
from edgar import *

# The SEC requires you to identify yourself (any email works)
set_identity("your.name@example.com")
```
```

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

### Development Setup

Source: https://github.com/dgunning/edgartools/blob/main/edgar/ai/README.md

Instructions for setting up the development environment, installing dependencies, and running tests for the edgar.ai library.

```APIDOC
## Development

To contribute to the AI features:

### 1. Install development dependencies:
```bash
pip install -e ".[ai,ai-dev]"
```

### 2. Run tests:
```bash
# Test MCP tools
pytest tests/test_mcp_tools.py

# Test AI features
pytest tests/test_ai_features.py

# Test AI skills
pytest tests/test_ai_skill_export.py
```

### 3. Check AI capabilities:
```python
from edgar.ai import check_ai_capabilities
print(check_ai_capabilities())
```
```

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

### FormC Class - Quick Start

Source: https://github.com/dgunning/edgartools/blob/main/edgar/offerings/docs/FormC.md

A quick start guide to initialize the FormC class and access basic offering information.

```APIDOC
## FormC Class - Quick Start

Get started with Form C in 3 lines:

```python
from edgar import Company

# Get a company with Form C filings
company = Company("1881570")  # ViiT Health (example company with crowdfunding)

# Get Form C filings
filings = company.get_filings(form="C")
filing = filings[0]

# Parse into FormC object
formc = filing.obj()

# Access offering information
print(f"Issuer: {formc.issuer_name}")
print(f"Target: ${formc.offering_information.target_amount:,.0f}")
print(f"Deadline: {formc.offering_information.deadline_date}")

# Get complete offering lifecycle
offering = formc.get_offering()
print(offering.timeline())
```
```

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

### Quick Start: Initialize and Use Form3 Object

Source: https://github.com/dgunning/edgartools/blob/main/edgar/ownership/docs/Form3.md

Demonstrates how to quickly get started with the Form3 class by initializing a Company object, retrieving its Form 3 filings, parsing a filing into a Form3 object, and accessing basic insider and issuer information.

```python
from edgar import Company

# Get a company's Form 3 filings
company = Company("AAPL")
filings = company.get_filings(form="3")
filing = filings[0]

# Parse into Form3 object
form3 = filing.obj()

# Access ownership information
print(f"Insider: {form3.insider_name}")
print(f"Position: {form3.position}")
print(f"Issuer: {form3.issuer.name}")

# Get ownership summary
summary = form3.get_ownership_summary()
print(f"Total Shares: {summary.total_shares:,}")
print(f"Has Derivatives: {summary.has_derivatives}")
```

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

### Quick Start: Initialize and Access Financials (Python)

Source: https://github.com/dgunning/edgartools/blob/main/docs/guides/company-facts.md

A quick start guide showing the basic usage of the Company Facts API. It covers initializing a Company object and accessing fundamental financial statements like income, balance sheet, and cash flow.

```python
from edgar import Company

# Get any public company
company = Company('AAPL')  # Ticker symbol
# or
company = Company(320193)  # CIK number

# Access key metrics instantly
print(f"Shares Outstanding: {company.shares_outstanding:,.0f}")
print(f"Public Float: ${company.public_float:,.0f}")

# Get enhanced multi-period financial statements
income_stmt = company.income_statement()  # Shows multiple periods with hierarchy
balance_sheet = company.balance_sheet()
cash_flow = company.cashflow_statement()

print(income_stmt)  # Rich multi-period display

# Get concise format for quick overview
income_compact = company.income_statement(concise_format=True)
print(income_compact)  # Shows $1.0B instead of $1,000,000,000
```

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

### Quick Start: Basic Usage

Source: https://github.com/dgunning/edgartools/blob/main/edgar/ai/skills/core/readme.md

Demonstrates how to set up your identity and retrieve the first 5 10-K filings for a company.

```APIDOC
## Quick Start: Basic Usage

### Description
This snippet shows the initial setup for using the EdgarTools library, including setting your identity and fetching company filings.

### Method
Python Script

### Endpoint
N/A (Library Usage)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from edgar import set_identity, Company
set_identity("Your Name your@email.com")  # Required

company = Company("AAPL")
company.get_filings(form="10-K")[:5]
```

### Response
#### Success Response (200)
Returns a list of Filing objects for the specified company and form type.

#### Response Example
(Output will be a list of Filing objects, not shown here for brevity)
```

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

### Install and Setup edgartools Library

Source: https://github.com/dgunning/edgartools/blob/main/notebooks/Filtering-by-industry.ipynb

Installs the edgartools library using pip and sets the user identity required for making API calls to the SEC Edgar database. This is the initial setup step for using the library.

```python
!pip install edgartools
```

```python
from edgar import *

set_identity("user@edgartools.io")
```

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

### Configure Compression and Storage Paths

Source: https://github.com/dgunning/edgartools/blob/main/docs/guides/local-storage.md

Demonstrates how to set compression levels for downloads and specify local storage directories for different performance needs.

```python
download_filings("2025-01-15", compression_level=9)
use_local_storage("~/edgar_test")
use_local_storage("/fast_ssd/edgar_data")
```

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

### Install edgartools and Dependencies

Source: https://github.com/dgunning/edgartools/blob/main/notebooks/Initial-Insider-Transactions.ipynb

Installs the necessary Python libraries: edgartools, seaborn, and matplotlib. This is a prerequisite for running the subsequent code examples.

```python
!pip install -U edgartools seaborn matplotlib
```

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

### Install and Setup edgartools

Source: https://github.com/dgunning/edgartools/blob/main/notebooks/Ticker-Search-with-edgartools.ipynb

Installs the edgartools library and sets up the necessary identity for SEC requests. The SEC requires automated tools to identify themselves with an email address.

```python
!pip install -U edgartools
from edgar import *

# The SEC requires you to identify yourself (any email works)
set_identity("your.name@example.com")
```

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

### MappingStore Initialization

Source: https://github.com/dgunning/edgartools/blob/main/docs/advanced/customizing-standardization.md

Demonstrates how to initialize the MappingStore with default, custom, or read-only configurations.

```APIDOC
## MappingStore Initialization

### Description
Initializes the `MappingStore` which loads and manages XBRL concept mappings. It supports default packaged mappings, custom mapping files, and a read-only mode.

### Method
`MappingStore(source=None, read_only=False)`

### Parameters
- **source** (str, optional): Path to a custom mapping JSON file. Defaults to None (uses packaged mappings).
- **read_only** (bool, optional): If True, the store will not allow modifications. Defaults to False.

### Request Example
```python
from edgar.xbrl.standardization import MappingStore

# Default initialization
store = MappingStore()

# Custom source initialization
store = MappingStore(source="/path/to/custom_mappings.json")

# Read-only mode initialization
store = MappingStore(read_only=True)
```

### Response
#### Success Response (200)
- **MappingStore object**: An initialized instance of the MappingStore.

#### Response Example
```json
{
  "message": "MappingStore initialized successfully."
}
```
```

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

### Install and Configure Edgartools

Source: https://github.com/dgunning/edgartools/blob/main/notebooks/XBRL2-PeriodViews.ipynb

Installs the edgartools package and configures the user identity required for SEC EDGAR API access. This setup is a prerequisite for all subsequent data retrieval operations.

```bash
pip install -U edgartools
```

```python
from edgar import *

set_identity('periodviews@testing.net')
```

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

### Performing Complete Offering Workflow

Source: https://github.com/dgunning/edgartools/blob/main/edgar/offerings/docs/FormC.md

A comprehensive example showing how to fetch filings for a company, group them by file number, and analyze each offering's details and financials.

```python
from edgar import Company
from edgar.offerings.formc import group_offerings_by_file_number
from edgar.offerings import Offering

company = Company("1881570")
filings = company.get_filings(form=["C", "C/A", "C-U", "C-AR"])
grouped = group_offerings_by_file_number(filings)

for file_num, offering_filings in grouped.items():
    offering = Offering(file_num, cik=company.cik)
    print(offering.timeline())
```

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

### Quick Start: Getting TransactionSummary

Source: https://github.com/dgunning/edgartools/blob/main/edgar/ownership/docs/TransactionSummary.md

Demonstrates how to obtain a TransactionSummary object from a company's SEC filings.

```APIDOC
## Quick Start

Get a TransactionSummary from any Form 4 or Form 5:

```python
from edgar import Company

company = Company("AAPL")
filing = company.get_filings(form="4")[0]
form4 = filing.obj()

# Get the transaction summary
summary = form4.get_ownership_summary()

# Access computed properties
print(f"Net Change: {summary.net_change:,} shares")
print(f"Net Value: ${summary.net_value:,.2f}")
print(f"Activity: {summary.primary_activity}")
```
```

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

### Setup and Importing

Source: https://github.com/dgunning/edgartools/blob/main/docs/quick-guide.md

Instructions for setting up your EDGAR identity and importing the EdgarTools library.

```APIDOC
## Setup and Importing

### Description
Set up your EDGAR identity and import the EdgarTools library to begin.

### Code Examples

**Set EDGAR Identity (Linux/Mac):**
```bash
export EDGAR_IDENTITY="email@domain.com"
```

**Set EDGAR Identity (Windows CMD):**
```cmd
set EDGAR_IDENTITY="email@domain.com"
```

**Set EDGAR Identity (Windows PowerShell):**
```powershell
$env:EDGAR_IDENTITY="email@domain.com"
```

**Set Identity in Python:**
```python
set_identity("email@domain.com")
```

**Importing the Library:**
```python
from edgar import *
```
```

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

### Retrieve Expense Examples

Source: https://github.com/dgunning/edgartools/blob/main/docs/guides/prospectus497k-data-object-guide.md

Get hypothetical costs for holding $10,000 over 1, 3, 5, and 10-year periods.

```python
p.expense_example
```

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

### Edgartools BDC Data Access Example

Source: https://github.com/dgunning/edgartools/blob/main/notebooks/bdc-business-development-company-python.ipynb

Provides a concise example of how to access BDC data using edgartools, including getting the list of BDCs, retrieving a specific BDC's portfolio, and fetching bulk DERA data.

```python
from edgar.bdc import get_bdc_list, find_bdc, fetch_bdc_dataset
bdcs = get_bdc_list()                      # All active BDCs
arcc = bdcs.get_by_ticker("ARCC")
investments = arcc.portfolio_investments()  # Parsed holdings
dataset = fetch_bdc_dataset(2024, 3)       # DERA bulk data
```

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

### Initialize MappingStore with Auto-Detection

Source: https://github.com/dgunning/edgartools/blob/main/docs/advanced/customizing-standardization.md

Demonstrates how to initialize a MappingStore which automatically detects the file format (CSV or JSON) based on the provided file extension.

```python
from edgar.xbrl.standardization import MappingStore

# Automatically loads CSV or JSON based on extension
store = MappingStore(source="my_mappings.csv")
```

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

### Install and Initialize edgartools

Source: https://github.com/dgunning/edgartools/blob/main/notebooks/XBRL2-FactQueries.ipynb

Sets up the environment by installing the edgartools package and configuring the identity for API access.

```python
!pip install edgartools
import pandas as pd
from edgar import *
from edgar.xbrl import XBRL, FactQuery, FactsView
set_identity("PeriodViews@notebook.com")
```