### 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")
```
```

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

### Quick Start Local Storage Setup

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

Initialize local storage and download essential data for offline use.

```python
import os
from edgar import use_local_storage, download_edgar_data

# Setup in one line
os.makedirs("~/edgar", exist_ok=True)
use_local_storage("~/edgar")

# Download essential data
download_edgar_data()

# All subsequent operations use local storage when available
```

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

### 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 Setup for Development

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

Initializes a local storage directory and downloads essential reference data for standard company lookups.

```python
from edgar import use_local_storage, download_edgar_data
import os

# Setup local storage in one command
os.makedirs("~/edgar_dev", exist_ok=True)
use_local_storage("~/edgar_dev")

# Download essential data
download_edgar_data(submissions=True, reference=True)

# Now all queries use local data when available
from edgar import Company
apple = Company("AAPL")  # Uses local data
```

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

### 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")
```

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

### 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 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
```

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

### Preview Documentation Locally

Source: https://github.com/dgunning/edgartools/blob/main/CONTRIBUTING.md

Starts a local development server to preview the external documentation site.

```bash
hatch run mkdocs serve
```

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

### 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")
```

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

### 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}")
```
```

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

### Set Up Multiple Test Environments

Source: https://github.com/dgunning/edgartools/blob/main/scripts/mcp-testing/README.md

Demonstrates how to install and configure multiple isolated test environments for the project using bash scripts. It shows installation and switching between environments.

```bash
# Development environment
./install-local-mcp.sh ~/mcp-dev

# Staging environment
./install-local-mcp.sh ~/mcp-staging

# Switch between them
./configure-claude-mcp.sh ~/mcp-dev/bin/python
# or
./configure-claude-mcp.sh ~/mcp-staging/bin/python
```

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

### 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
```

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

### Custom Data Repository Examples

Source: https://github.com/dgunning/edgartools/blob/main/docs/configuration.md

Examples for using CDNs or private data repositories.

```bash
# Use CDN for data downloads
export EDGAR_DATA_URL="https://cdn.sec-data.company.com"

# Corporate data repository
export EDGAR_DATA_URL="https://sec-data.company.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."
}
```
```

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

### 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
```