Edgartools

https://edgartools.readthedocs.io/en/latest
Admin
Project details are unavailable as the provided content is a Cloudflare verification page, not the...
Tokens:366,644
Snippets:4,142
Trust Score:8.3
Update:5 months ago
Show doc for...
Tokens:
Raw
### Quick Start: Native Cloud Storage

Source: https://edgartools.readthedocs.io/en/latest/guides/cloud-storage

Recommended setup for native cloud storage integration. Install the necessary extras, configure your cloud bucket, and then use edgartools to read from or write to the cloud.

```python
import edgar

# Install: pip install "edgartools[s3]"
edgar.use_cloud_storage('s3://my-edgar-bucket/')

# Read from cloud
company = edgar.Company("AAPL")

# Write to cloud
edgar.download_filings('2025-01-15', upload_to_cloud=True)

# Or sync existing local data
edgar.sync_to_cloud('filings')
```

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

### Example Custom Data Directory Setup (Shell)

Source: https://edgartools.readthedocs.io/en/latest/configuration

Configure a custom directory for local Edgar data storage and enable local data usage simultaneously using environment variables.

```shell
# Custom data directory for project
export EDGAR_LOCAL_DATA_DIR="/project/edgar_data"
export EDGAR_USE_LOCAL_DATA="True"
```

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

### Setup Local Storage for Development

Source: https://edgartools.readthedocs.io/en/latest/guides/local-storage

Configure `use_local_storage()` to direct downloads to a specified directory, enabling faster data access for development. This example also downloads essential data for 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
```

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

### Quick Start: Company Subset Functions

Source: https://edgartools.readthedocs.io/en/latest/company-subsets

Demonstrates basic usage of functions for selecting companies by exchange, getting popular companies, and random sampling.

```python
from edgar.reference.company_subsets import (
    CompanySubset, 
    get_companies_by_exchanges,
    get_popular_companies,
    get_random_sample
)

# Simple exchange-based selection
nyse_companies = get_companies_by_exchanges('NYSE')
print(f"Found {len(nyse_companies)} NYSE companies")

# Get popular companies
popular = get_popular_companies()
print(f"Found {len(popular)} popular companies")

# Random sampling
random_100 = get_random_sample(n=100, random_state=42)
print(f"Sampled {len(random_100)} random companies")

```

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

### Quick Start: Native Cloud Storage

Source: https://edgartools.readthedocs.io/en/latest/guides/cloud-storage

This snippet demonstrates the recommended approach for using edgartools with native cloud storage, including installation, configuration, and basic read/write operations.

```APIDOC
## Quick Start: Native Cloud Storage

### Description
This guide outlines the initial steps for integrating edgartools with cloud storage, focusing on the recommended native support.

### Method
N/A (Configuration and Usage)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

### Usage Example
```python
import edgar

# Install: pip install "edgartools[s3]"
edgar.use_cloud_storage('s3://my-edgar-bucket/')

# Read from cloud
company = edgar.Company("AAPL")

# Write to cloud
edgar.download_filings('2025-01-15', upload_to_cloud=True)

# Or sync existing local data
edgar.sync_to_cloud('filings')
```
```

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

### Enable and Start Systemd Service

Source: https://edgartools.readthedocs.io/en/latest/guides/cloud-storage

Enables the systemd service to start on boot and starts the service immediately.

```bash
sudo systemctl enable edgar-s3
sudo systemctl start edgar-s3
```

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

### Install edgartools with uv

Source: https://edgartools.readthedocs.io/en/latest

Install the edgartools library using uv for faster installation.

```bash
uv pip install edgartools
```

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

### Batch Process Filings

Source: https://edgartools.readthedocs.io/en/latest/api/filings

Example of fetching a batch of 8-K filings for a specific year and quarter, intended as a starting point for further processing.

```python
from edgar import get_filings

filings = get_filings(2024, 1, form="8-K")
```

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

### Quick Start: Perform Ranked Search

Source: https://edgartools.readthedocs.io/en/latest/advanced-search

This snippet demonstrates how to get a filing, parse it into a structured document, and perform a ranked search using the hybrid algorithm. Ensure you have the necessary imports and a Company object initialized.

```python
from edgar import Company
from edgar.documents.search import DocumentSearch

# Get a filing
company = Company("AAPL")
filing = company.get_filings(form="10-K").latest(1)

# Parse HTML into structured Document
document = filing.parse()

# Create search interface
searcher = DocumentSearch(document)

# Search with ranking
results = searcher.ranked_search(
    query="revenue growth",
    algorithm="hybrid",
    top_k=5
)

# Access results
for result in results:
    print(f"Score: {result.score:.3f}")
    print(f"Section: {result.section}")
    print(f"Snippet: {result.snippet}")

```

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

### Python Function Example with Docstrings

Source: https://edgartools.readthedocs.io/en/latest/contributing

Example of a Python function adhering to the code style guide, including type hints and a descriptive docstring.

```python
def get_filing_documents(
    filing: Filing,
    document_type: Optional[str] = None
) -> List[Document]:
    """
    Retrieve documents from an SEC filing.

    Args:
        filing: The Filing object to extract documents from
        document_type: Optional filter for specific document types

    Returns:
        List of Document objects matching the criteria
    """
    # Implementation
```

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

### Download Essential Edgar Data

Source: https://edgartools.readthedocs.io/en/latest/guides/local-storage

Quick start example to set up local storage and download essential SEC data. This involves creating the directory, setting the path, and initiating the download.

```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()
```

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

### Setup High-Performance Storage for Analysis

Source: https://edgartools.readthedocs.io/en/latest/guides/local-storage

This setup uses `use_local_storage()` with a temporary directory for high-performance analysis. It demonstrates downloading specific filings and accessing their XBRL data instantly from local storage.

```python
from edgar import use_local_storage, download_filings, get_filings
import os

# Setup high-performance storage
os.makedirs("/tmp/edgar_fast", exist_ok=True)
use_local_storage("/tmp/edgar_fast")

# Download specific filings for analysis
filings = get_filings(form="10-K", year=2024)
download_filings(filings=filings)

# All subsequent operations are lightning fast
for filing in filings:
    financial_data = filing.xbrl()  # Instant from local storage
```

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

### Install blobfuse2 on Ubuntu

Source: https://edgartools.readthedocs.io/en/latest/guides/cloud-storage

Installs blobfuse2 on Ubuntu systems by adding the Microsoft package repository.

```bash
wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
sudo apt-get update && sudo apt-get install blobfuse2
```

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

### Install EdgarTools

Source: https://edgartools.readthedocs.io/en/latest/complete-guide

Install the edgartools library using pip.

```bash
pip install edgartools
```

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

### Install EdgarTools

Source: https://edgartools.readthedocs.io/en/latest/ai/mcp-setup

Install the EdgarTools package with AI capabilities using pip. This is the first step for setting up the MCP server.

```bash
pip install "edgartools[ai]"
```

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

### Revenue Hierarchy Example in Mappings

Source: https://edgartools.readthedocs.io/en/latest/advanced/customizing-standardization

Shows a real-world example of revenue concept mappings in JSON, demonstrating hierarchy separation for clarity.

```json
{
  "_comment_revenue_hierarchy": "REVENUE HIERARCHY FIX: Separated total revenue from component revenue types to prevent duplicate labels.",

  "Revenue": [
    "us-gaap:Revenue",
    "us-gaap:Revenues",
    "us-gaap:SalesRevenueNet",
    "us-gaap:OperatingRevenue"
  ],

  "Contract Revenue": [
    "us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax",
    "us-gaap:RevenueFromContractWithCustomerIncludingAssessedTax"
  ],

  "Product Revenue": [
    "us-gaap:SalesRevenueGoodsNet",
    "us-gaap:ProductSales"
  ]
}
```

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

### Activate Development Environment

Source: https://edgartools.readthedocs.io/en/latest/contributing

Use Hatch to activate the development environment, which installs all necessary dependencies.

```bash
hatch shell
```

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

### Complete Company Data Retrieval Example

Source: https://edgartools.readthedocs.io/en/latest/api/company

A comprehensive example showing how to retrieve and display basic company information, recent filings, financial data, facts, and address.

```python
from edgar import Company

# Create company instance
company = Company("AAPL")

# Basic information
print(f"Company: {company.name}")
print(f"CIK: {company.cik}")
print(f"Industry: {company.industry}")
print(f"Fiscal Year End: {company.fiscal_year_end}")

# Key metrics — simple property access
print(f"Shares Outstanding: {company.shares_outstanding:,.0f}")
print(f"Public Float: ${company.public_float:,.0f}")

# Get recent filings
recent_filings = company.get_filings(
    form=["10-K", "10-Q"],
    filing_date="2023-01-01:",
    limit=5
)

print(f"\nRecent Filings ({len(recent_filings)}):")
for filing in recent_filings:
    print(f"  {filing.form}: {filing.filing_date}")

# Get financial data
financials = company.get_financials()
if financials:
    revenue = financials.income.loc['Revenue'].iloc[0]
    print(f"\nLatest Revenue: ${revenue/1e9:.1f}B")

# Get company facts
facts = company.get_facts()
if facts:
    print(f"Total XBRL Facts: {facts.num_facts()}")

# Address information
address = company.business_address()
if address:
    print(f"Location: {address.city}, {address.state_or_country}")
```

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

### Install rclone on Linux

Source: https://edgartools.readthedocs.io/en/latest/guides/cloud-storage

Installs rclone on Linux systems using the official installation script.

```bash
curl https://rclone.org/install.sh | sudo bash
```

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

### Install s3fs-fuse on Ubuntu/Debian

Source: https://edgartools.readthedocs.io/en/latest/guides/cloud-storage

Installs the s3fs-fuse package using apt-get.

```bash
sudo apt-get install s3fs
```

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

### Development Installation of edgartools

Source: https://edgartools.readthedocs.io/en/latest/installation

Clone the repository and install edgartools in development mode for contributing or using the latest development version. Includes installation with development dependencies.

```bash
# Clone the repository
git clone https://github.com/dgunning/edgartools.git
cd edgartools

# Install in development mode
pip install -e .

# Or with development dependencies
pip install -e ".[dev]"
```

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

### Real Example: Microsoft (msft_mappings.json)

Source: https://edgartools.readthedocs.io/en/latest/advanced/customizing-standardization

An example of a company mapping JSON for Microsoft Corporation, illustrating unique categorizations for revenue and expenses.

```json
{
  "entity_info": {
    "name": "Microsoft Corporation",
    "cik": "0000789019",
    "ticker": "MSFT",
    "description": "Microsoft-specific concept mappings for unique business terminology"
  },

  "concept_mappings": {
    "_comment_msft_revenue": "Microsoft uses specific revenue categorization that differs from standard tech companies",

    "Product Revenue": [
      "msft:ProductRevenue",
      "msft:WindowsCommercialRevenue",
      "msft:WindowsConsumerRevenue",
      "msft:OfficeCommercialRevenue"
    ],

    "Service Revenue": [
      "msft:ServiceRevenue",
      "msft:CloudServicesRevenue",
      "msft:ConsultingServicesRevenue"
    ],

    "Subscription Revenue": [
      "msft:Office365CommercialRevenue",
      "msft:Office365ConsumerRevenue",
      "msft:DynamicsRevenue"
    ],

    "Platform Revenue": [
      "msft:AzureRevenue",
      "msft:XboxContentAndServicesRevenue"
    ],

    "_comment_msft_expenses": "Microsoft has unique expense categorizations",

    "Sales and Marketing Expense": [
      "msft:SalesAndMarketingExpense",
      "msft:AdvertisingAndPromotionExpense"
    ],

    "Technical Support Expense": [
      "msft:TechnicalSupportExpense",
      "msft:CustomerSupportExpense"
    ]
  },

  "hierarchy_rules": {
    "_comment": "Rules for handling Microsoft-specific hierarchical relationships",

    "revenue_hierarchy": {
      "parent": "Revenue",
      "children": ["Product Revenue", "Service Revenue", "Subscription Revenue", "Platform Revenue"],
      "calculation_rule": "sum"
    },

    "expense_hierarchy": {
      "parent": "Operating Expenses",
      "children": ["Sales and Marketing Expense", "Technical Support Expense"],
      "calculation_rule": "sum"
    }
  }
}
```

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

### Cache Management Examples

Source: https://edgartools.readthedocs.io/en/latest/advanced-search

Demonstrates how to manage the search index cache, including clearing and disabling.

```APIDOC
### Cache Management

```python
# Clear instance cache only
searcher.clear_cache(memory_only=True)

# Clear all caches (memory + disk)
searcher.clear_cache(memory_only=False)

# Disable caching (for testing)
searcher = DocumentSearch(document, use_cache=False)
```
```

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

### Corporate Mirror Setup Configuration

Source: https://edgartools.readthedocs.io/en/latest/configuration

Complete environment variable configuration for a corporate SEC mirror setup, including identity, URLs, rate limits, and local data settings.

```bash
# Corporate SEC mirror with higher rate limits
export EDGAR_IDENTITY="Corporate Compliance compliance@company.com"
export EDGAR_BASE_URL="https://sec-mirror.company.com"
export EDGAR_DATA_URL="https://sec-data.company.com"
export EDGAR_XBRL_URL="https://sec-xbrl.company.com"
export EDGAR_RATE_LIMIT_PER_SEC="50"
export EDGAR_ACCESS_MODE="NORMAL"
export EDGAR_USE_LOCAL_DATA="True"
export EDGAR_LOCAL_DATA_DIR="/var/lib/edgar"

```

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

### Serve Documentation Locally

Source: https://edgartools.readthedocs.io/en/latest/contributing

Use Hatch to start a local development server for previewing documentation changes. Visit the provided URL to view.

```bash
hatch run mkdocs serve
```

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

### Initializing MappingStore

Source: https://edgartools.readthedocs.io/en/latest/advanced/customizing-standardization

Demonstrates how to initialize the MappingStore, which loads core and company-specific mappings. A custom source path can be provided for future enhancements.

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

# Default initialization (loads packaged mappings)
store = MappingStore()

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

```

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

### Get Filings for a Company

Source: https://edgartools.readthedocs.io/en/latest/guides/working-with-filing

Retrieve filings for a specific company using its ticker symbol. This example shows how to get the latest 10-K filing and print its basic information.

```python
from edgar import Company

company = Company("AAPL")
filings = company.get_filings(form="10-K")
filing = filings.latest()

print(filing.company)      # "Apple Inc."
print(filing.form)         # "10-K"
print(filing.filing_date)  # "2023-11-03"

```

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

### Install EdgarTools with S3 Support

Source: https://edgartools.readthedocs.io/en/latest/guides/cloud-storage

Install EdgarTools along with the necessary dependencies for AWS S3, Cloudflare R2, MinIO, and DigitalOcean Spaces. This enables seamless integration with these S3-compatible storage services.

```bash
# AWS S3, Cloudflare R2, MinIO, DigitalOcean Spaces
pip install "edgartools[s3]"
```

```bash
# Google Cloud Storage
pip install "edgartools[gcs]"
```

```bash
# Azure Blob Storage
pip install "edgartools[azure]"
```

```bash
# All cloud providers
pip install "edgartools[all-cloud]"
```

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

### Get filing sections

Source: https://edgartools.readthedocs.io/en/latest/quick-guide

Retrieves all sections of a filing. No specific setup is required beyond having a filing object.

```python
filing.sections()
```

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

### Set up S3 Bucket for Static Website Hosting

Source: https://edgartools.readthedocs.io/en/latest/guides/cloud-storage

Commands to create an S3 bucket, enable static website hosting, and set a public read policy for accessing Edgar data.

```bash
# Create bucket
aws s3 mb s3://my-edgar-data --region us-east-1

# Enable static website hosting
aws s3 website s3://my-edgar-data \
    --index-document index.html \
    --error-document error.html
```

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "PublicReadGetObject",
            "Effect": "Allow",
            "Principal": "*",
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::my-edgar-data/*"
        }
    ]
}
```

```bash
aws s3api put-bucket-policy \
    --bucket my-edgar-data \
    --policy file://bucket-policy.json
```

```bash
# Sync local edgar data to S3
aws s3 sync ~/.edgar s3://my-edgar-data/ --storage-class STANDARD_IA
```

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

### Metadata Quick Reference

Source: https://edgartools.readthedocs.io/en/latest/eightk-filings

A reference guide to the properties available for a filing object, detailing what each property returns and providing an example.

```APIDOC
## Metadata Quick Reference

### Description
Provides a quick lookup for common properties of a filing object, including their return type and an example.

### Parameters
None

### Properties
- **company** (str) - Company name. Example: `"Apple Inc."`
- **form** (str) - Form type. Example: `"8-K"`
- **filing_date** (str) - Date filed with SEC. Example: `"2024-02-01"`
- **period_of_report** (str) - Report date. Example: `"2024-01-31"`
- **date_of_report** (str) - Formatted report date. Example: `"January 31, 2024"`
- **items** (list) - List of disclosed items. Example: `['Item 2.02', 'Item 9.01']`
- **has_press_release** (bool) - Indicates if a press release exhibit is present. Example: `True`
- **has_earnings** (bool) - Indicates if parseable earnings data is available. Example: `True`
```

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

### Get Company Object

Source: https://edgartools.readthedocs.io/en/latest/quickstart

Retrieve a Company object by its ticker symbol. This object serves as the starting point for accessing company data.

```python
from edgar import Company

company = Company("AAPL")  # Apple Inc.
```

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

### One-Step Local Storage Setup

Source: https://edgartools.readthedocs.io/en/latest/guides/local-storage

This function creates and sets the local data directory, enabling local storage in a single call. It supports path strings and tilde expansion.

```python
from edgar import use_local_storage
import os

# Create and set directory, enable local storage in one call
os.makedirs("/tmp/edgar_data", exist_ok=True)
use_local_storage("/tmp/edgar_data")
```

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

### Get Filing Plain Text Content

Source: https://edgartools.readthedocs.io/en/latest/guides/working-with-filing

Extract the plain text content from an SEC filing. This example prints the first 500 characters.

```python
text = filing.text()
print(text[:500])  # First 500 characters

```

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

### Get Place Name by State Code

Source: https://edgartools.readthedocs.io/en/latest/guides/reference-data

Retrieves the full name of a state given its two-letter code. Example: 'DE' returns 'Delaware'.

```python
get_place_name("DE")                        # "Delaware"
```

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

### FilingViewer Quick Reference

Source: https://edgartools.readthedocs.io/en/latest/guides/sec-viewer-guide

A quick reference guide to the properties and methods of the FilingViewer object.

```APIDOC
## Quick Reference

### FilingViewer

| Property / Method | Returns | Description |
|---|---|---|
| `viewer.financial_statements` | `List[ViewerReport]` | Statement-category reports |
| `viewer.notes` | `List[ViewerReport]` | Note-category reports |
| `viewer.policies` | `List[ViewerReport]` | Policy-category reports |
| `viewer.tables` | `List[ViewerReport]` | Table-category reports |
| `viewer.details` | `List[ViewerReport]` | Detail-category reports |
| `viewer.all_reports` | `List[ViewerReport]` | All reports |
| `viewer.concepts` | `ConceptGraph` | Full concept graph |
| `viewer['label']` | `Concept` | Concept lookup by label or tag ID |
| `viewer.search(query)` | `List[Concept]` | Search by keyword |
| `viewer.validate()` | `List[dict]` | Check calculation trees |
| `viewer.compare(xbrl)` | `ComparisonResults` | Cross-validate against XBRL parser |
| `viewer.compare_context(xbrl, stmt)` | `str` | LLM-ready side-by-side comparison |
| `viewer.view(name)` | — | Display a report in the terminal |
| `viewer.to_context()` | `str` | AI-optimized summary |
```

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

### Get a Parsed 6-K Filing

Source: https://edgartools.readthedocs.io/en/latest/guides/sixk-data-object-guide

Retrieve and parse a specific Form 6-K filing for a company. This is the starting point for accessing all data within the filing.

```python
from edgar import Company

tm = Company("TM")
filing = tm.get_filings(form="6-K")[3]
six_k = filing.obj()
six_k
```

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

### Migrate MCP Server Entry Point

Source: https://edgartools.readthedocs.io/en/latest/ai/mcp-setup

Compares the deprecated entry point for running the MCP server with the new recommended method using uvx. The new method is preferred for modern setups.

```json
// Old (deprecated)
{ "command": "python", "args": ["/path/to/edgartools/edgar/ai/run_mcp_server.py"] }

```

```json
// New
{ "command": "uvx", "args": ["--from", "edgartools[ai]", "edgartools-mcp"] }

```

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

### Get Filer Type by State Code

Source: https://edgartools.readthedocs.io/en/latest/guides/reference-data

Determines the filer type (e.g., 'Domestic') associated with a given state code. Example: 'DE' returns 'Domestic'.

```python
get_filer_type("DE")                        # "Domestic"
```

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

### Real-World XBRL Filing with Footnotes

Source: https://edgartools.readthedocs.io/en/latest/guides/xbrl-footnotes

Demonstrates how to fetch a real XBRL filing using the Filing class and process its footnotes. This example shows how to check for footnotes, display their details, and find facts with footnotes within specific financial statements.

```python
from edgar import Filing
from pathlib import Path

# Get a filing and parse its XBRL
filing = Filing(form='10-K', cik=1234567, accession_no='0001234567-23-000001')
xbrl = filing.xbrl()

# Check if the document has footnotes
if xbrl.footnotes:
    print(f"Document contains {len(xbrl.footnotes)} footnotes")

    # Show footnote details
    for footnote_id, footnote in list(xbrl.footnotes.items())[:3]:
        print(f"\nFootnote ID: {footnote_id}")
        print(f"Text: {footnote.text[:100]}...")
        print(f"Language: {footnote.lang}")
        print(f"Linked to {len(footnote.related_fact_ids)} facts")

    # Find facts with footnotes in the balance sheet
    balance_sheet = xbrl.get_statement("BalanceSheet")
    if balance_sheet:
        for item in balance_sheet.get_all_line_items():
            facts = item.get("facts", [])
            for fact in facts:
                if fact.footnotes:
                    print(f"\n{item['label']} has footnotes:")
                    for fn_id in fact.footnotes:
                        if fn_id in xbrl.footnotes:
                            print(f"  • {xbrl.footnotes[fn_id].text[:80]}...")
else:
    print("No footnotes found in this document")

```

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

### Get Filings with Expanded Date Range

Source: https://edgartools.readthedocs.io/en/latest/resources/troubleshooting

Retrieve filings within a specified start and end date. Useful for finding older filings or when the exact date is unknown.

```python
filings = company.get_filings(
       form="10-K",
       start_date="2010-01-01",  # Try a wider date range
       end_date="2023-12-31"
   )
```

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

### Get Filing XML Content

Source: https://edgartools.readthedocs.io/en/latest/guides/working-with-filing

Retrieve XML content from filings that contain it, such as ownership forms. The example shows how to parse the XML using Python's ElementTree.

```python
xml = filing.xml()
if xml:
    import xml.etree.ElementTree as ET
    root = ET.fromstring(xml)
    # Parse XML data

```

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

### Create and Activate a Virtual Environment

Source: https://edgartools.readthedocs.io/en/latest/resources/troubleshooting

Set up an isolated Python environment to manage dependencies and avoid conflicts. Activate the environment before installing packages.

```bash
# Create a new virtual environment
python -m venv edgar_env

# Activate it
source edgar_env/bin/activate  # On Windows: edgar_env\Scripts\activate

# Install edgartools
pip install edgartools

```

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

### Typical Analytical Workflow

Source: https://edgartools.readthedocs.io/en/latest/guides/full-text-search

Combine `search_filings` with `grep` for a comprehensive analysis. First, find relevant filings, then refine results and perform deep dives into specific documents or notes.

```python
from edgar import search_filings, Company

# Step 1: Find filings across EDGAR
results = search_filings('"exclusive license" "trade secret"', forms=["8-K"])
print(f"{results.total:,} filings mention these terms")

# Step 2: Triage from metadata
material = results.filter(items="1.01")       # Material agreements
high_score = results.filter(min_score=15.0)    # Strong matches

# Step 3: Check who shows up most
for a in results.aggregations.entities[:5]:
    print(f"{a.key}: {a.count} filings")

# Step 4: Deep dive on an interesting hit
filing = results[0].get_filing()
tenk = Company(results[0].cik).get_filings(form="10-K").latest(1).obj()

# Step 5: Grep the 10-K for related terms
tenk.grep("going concern")
tenk.grep("Level 3")
tenk.notes.grep("intangible asset")
```

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

### Get Filing Markdown Content

Source: https://edgartools.readthedocs.io/en/latest/guides/working-with-filing

Convert the filing content to Markdown format. This can be saved to a file or processed further. Options include including page breaks and setting the start page number.

```python
md = filing.markdown()

# Save to file
with open("filing.md", "w") as f:
    f.write(md)

```

```python
md = filing.markdown(include_page_breaks=True, start_page_number=1)

```

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

### Download Metadata and Filing Documents

Source: https://edgartools.readthedocs.io/en/latest/guides/local-storage

This example demonstrates the correct sequence for downloading metadata and then specific filing documents to enable offline XBRL parsing. `download_edgar_data()` alone is insufficient for offline XBRL.

```python
# ❌ This won't work offline - download_edgar_data() doesn't include filing content
download_edgar_data()
filing = get_filings()[0]
xbrl = filing.xbrl()  # Still needs network access!

# ✅ You need to also download the filing documents
download_edgar_data()                    # Metadata
download_filings("2024-01-01:")          # Actual filing documents
filing = get_filings()[0]
xbrl = filing.xbrl()                     # Now works offline!
```

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

### Comprehensive Financial Analysis with Ratios

Source: https://edgartools.readthedocs.io/en/latest/guides/extract-statements

Demonstrates how to retrieve a dictionary of all key financial metrics, including automatically calculated ratios like 'current_ratio', 'debt_to_assets', and 'free_cash_flow'.

```python
# Get comprehensive metrics dictionary
metrics = financials.get_financial_metrics()

# All the standard metrics are available
print(f"Revenue: ${metrics['revenue']:,.0f}")
print(f"Net Income: ${metrics['net_income']:,.0f}")
print(f"Total Assets: ${metrics['total_assets']:,.0f}")

# Plus calculated ratios
print(f"Current Ratio: {metrics['current_ratio']:.2f}")
print(f"Debt to Assets: {metrics['debt_to_assets']:.2f}")
print(f"Free Cash Flow: ${metrics['free_cash_flow']:,.0f}")
```

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

### Create Company Instance using Factory Functions

Source: https://edgartools.readthedocs.io/en/latest/api/company

Shows how to create Company instances using the `get_company` and `get_entity` factory functions.

```python
from edgar import get_company, get_entity

# Factory function
company = get_company("AAPL")

# More general entity function (returns Company for companies)
entity = get_entity("AAPL")
```

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

### Get Latest Filing Object

Source: https://edgartools.readthedocs.io/en/latest/data-objects

Retrieve the latest filing for a given company and form type. This example demonstrates initializing a `Company` object and fetching the most recent '10-K' filing, then obtaining its parsed object representation.

```python
from edgar import Company

apple = Company("AAPL")
filing = apple.get_latest_filing("10-K")
tenk = filing.obj()          # returns a TenK with all sections and financials
```

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

### Install goofys Binary

Source: https://edgartools.readthedocs.io/en/latest/guides/cloud-storage

Downloads the goofys binary, makes it executable, and moves it to the system's PATH.

```bash
# Download binary
wget https://github.com/kahing/goofys/releases/latest/download/goofys
chmod +x goofys
sudo mv goofys /usr/local/bin/
```

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

### Initialize XBRL Parser

Source: https://edgartools.readthedocs.io/en/latest/api/xbrl

Instantiate the main XBRL parser for processing SEC filing data.

```python
from edgar.xbrl import XBRL

class XBRL:
    """Main XBRL parser integrating all components of the XBRL parsing system."""

```

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

### Financial Data API Server Setup

Source: https://edgartools.readthedocs.io/en/latest/guides/multi-year-financial-data-api

This Python code defines the FastAPI application for the financial data API. It includes an endpoint for comparing financial metrics across multiple companies. Ensure all necessary libraries are installed.

```python
from typing import List
from fastapi import FastAPI, Query, HTTPException

# Assuming Company class is defined elsewhere and imported
# from your_company_module import Company

# Placeholder for Company class if not provided
class Company:
    def __init__(self, ticker):
        self.ticker = ticker
        self.name = f
```

```python
        self.facts = True # Placeholder

    def income_statement(self, periods, annual):
        # Placeholder for income statement data
        return Statement(periods=periods, annual=annual)

    def balance_sheet(self, periods, annual):
        # Placeholder for balance sheet data
        return Statement(periods=periods, annual=annual)

class Statement:
    def __init__(self, periods, annual):
        self.periods = periods
        self.annual = annual
        self.items = {'revenue': MetricItem(), 'net_income': MetricItem(), 'assets': MetricItem()}

    def find_item(self, metric_name):
        return self.items.get(metric_name)

class MetricItem:
    def __init__(self):
        self.values = [100, 110, 120] # Placeholder values

app = FastAPI()

@app.post("/financial/compare")
async def compare_companies(
    tickers: List[str],
    periods: int = Query(3, description="Number of periods", ge=1, le=5),
    metrics: List[str] = Query(['revenue', 'net_income'], description="Metrics to compare")
):
    """Compare financial metrics across multiple companies"""
    try:
        comparison_data = []

        for ticker in tickers:
            try:
                company = Company(ticker.upper())

                if not company.facts:
                    continue

                company_data = {
                    'ticker': ticker.upper(),
                    'name': company.name,
                    'metrics': {}
                }

                # Get statements based on requested metrics
                income_stmt = company.income_statement(periods=periods, annual=True)
                balance_sheet = company.balance_sheet(periods=periods, annual=True)

                for metric in metrics:
                    if metric.lower() in ['revenue', 'net_income']:
                        stmt = income_stmt
                    else:
                        stmt = balance_sheet

                    if stmt:
                        metric_item = stmt.find_item(metric)
                        if metric_item:
                            company_data['metrics'][metric] = {
                                'periods': stmt.periods,
                                'values': metric_item.values
                            }

                comparison_data.append(company_data)

            except Exception as e:
                print(f"Error processing {ticker}: {e}")
                continue

        return {
            'comparison': comparison_data,
            'metadata': {
                'companies_compared': len(comparison_data),
                'periods_requested': periods,
                'metrics_requested': metrics
            }
        }

    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))
```

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

### Configure Mapping Paths with Constructor Parameters

Source: https://edgartools.readthedocs.io/en/latest/advanced/customizing-standardization

Instantiate MappingStore with explicit paths for core mappings and company mappings directory. This allows for flexible path management.

```python
store = MappingStore(
    core_mappings_path='/path/to/concept_mappings.json',
    company_mappings_dir='/path/to/company_mappings/'
)

```

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

### Download Filing with Defaults

Source: https://edgartools.readthedocs.io/en/latest/api/filing

Download filing data to the default local directory using default compression settings.

```python
# Download with defaults
filing.download()
```

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

### Install Skills for Claude Code

Source: https://edgartools.readthedocs.io/en/latest/ai/skills

Installs skills automatically for Claude Code, making them discoverable and usable for improving code generation. The skills are installed to the ~/.claude/skills/edgartools/ directory.

```python
from edgar.ai import install_skill
install_skill()  # Installs to ~/.claude/skills/edgartools/

```

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

### Module-Level Singletons (Recommended)

Source: https://edgartools.readthedocs.io/en/latest/xbrl/concepts/standardization

Use module-level singletons for efficient, one-time loading of mappings. This is the recommended approach for best performance.

```APIDOC
## Module-Level Singletons (Recommended)

### Description
For best performance, use the module-level singletons which load mappings once per session.

### Usage
```python
from edgar.xbrl.standardization import (
    get_default_mapper,
    get_default_store,
    StandardConcept,
    StandardizationCache
)

# Get the singleton mapper - eliminates redundant file I/O
mapper = get_default_mapper()

# Map a company concept to standardized label
label = mapper.map_concept(
    "us-gaap_AccountsPayableCurrent",
    "Accounts Payable",
    {"statement_type": "BalanceSheet"}
)
# Returns: "Accounts Payable"
```
```

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

### Install rclone on macOS

Source: https://edgartools.readthedocs.io/en/latest/guides/cloud-storage

Installs rclone on macOS using Homebrew.

```bash
brew install rclone
```

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

### Install s3fs-fuse on macOS

Source: https://edgartools.readthedocs.io/en/latest/guides/cloud-storage

Installs the s3fs-fuse package using Homebrew.

```bash
brew install s3fs
```

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

### Verify MCP Server

Source: https://edgartools.readthedocs.io/en/latest/ai/mcp-setup

Run this command to test if the MCP server starts correctly and all checks pass. This confirms the server is ready for use.

```bash
python3 -m edgar.ai --test
```

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

### Check edgartools Installation

Source: https://edgartools.readthedocs.io/en/latest/resources/troubleshooting

Verify if the edgartools package is installed and check its version using pip.

```bash
pip show edgartools

```

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

### Proxy Voting Data Filtering Examples

Source: https://edgartools.readthedocs.io/en/latest/guides/npx-data-object-guide

Examples demonstrating how to filter proxy vote data.

```APIDOC
### Filter Examples

```python
# Filter by issuer
apple_votes = npx.proxy_votes.filter_by_issuer("APPLE")

# Filter by vote type
against_votes = npx.proxy_votes.filter_by_vote("AGAINST")

# Filter by category
climate_votes = npx.proxy_votes.filter_by_category("CLIMATE")
```
```

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

### Priority 4 Boost Example

Source: https://edgartools.readthedocs.io/en/latest/advanced/customizing-standardization

Illustrates how a concept prefix matching a company identifier can boost the priority of company-specific mappings.

```python
# P4 boost example
concept = "tsla:AutomotiveRevenue"
# System detects "tsla:" prefix
# Checks if "tsla" company mappings exist
# Boosts priority from P2 → P4 for Tesla mappings
```

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

### Install gcsfuse on Ubuntu/Debian

Source: https://edgartools.readthedocs.io/en/latest/guides/cloud-storage

Installs gcsfuse on Ubuntu/Debian systems by adding the Google Cloud APT repository.

```bash
export GCSFUSE_REPO=gcsfuse-$(lsb_release -c -s)
echo "deb https://packages.cloud.google.com/apt $GCSFUSE_REPO main" | sudo tee /etc/apt/sources.list.d/gcsfuse.list
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -
sudo apt-get update && sudo apt-get install gcsfuse
```

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

### Configure Claude Desktop (Windows)

Source: https://edgartools.readthedocs.io/en/latest/ai/mcp-setup

Add the edgartools MCP server configuration for Windows. Use 'python' as the command, assuming it's on your PATH.

```json
{
  "mcpServers": {
    "edgartools": {
      "command": "python",
      "args": ["-m", "edgar.ai"],
      "env": {
        "EDGAR_IDENTITY": "Your Name your.email@example.com"
      }
    }
  }
}
```

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

### Production FastAPI App Setup

Source: https://edgartools.readthedocs.io/en/latest/guides/multi-year-financial-data-api

Configures a FastAPI application for production, including GZip compression and CORS middleware. Logging is set to INFO level.

```python
# production_config.py
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from fastapi.middleware.gzip import GZipMiddleware
import logging

def create_production_app():
    app = FastAPI(
        title="Financial Data API",
        description="Production financial data service",
        version="1.0.0",
        docs_url="/docs" if settings.DEBUG else None
    )

    # Add middleware
    app.add_middleware(GZipMiddleware, minimum_size=1000)
    app.add_middleware(
        CORSMiddleware,
        allow_origins=["https://yourdomain.com"],
        allow_credentials=True,
        allow_methods=["GET", "POST"],
        allow_headers=["*"],
    )

    # Configure logging
    logging.basicConfig(level=logging.INFO)

    return app

app = create_production_app()

```

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

### Python Test Function Example

Source: https://edgartools.readthedocs.io/en/latest/contributing

Example of a Python test function following testing guidelines, with a descriptive name and assertions.

```python
def test_company_retrieval_by_ticker():
    """Test that companies can be retrieved by ticker symbol."""
    company = Company("AAPL")
    assert company.name == "Apple Inc."
    assert company.cik == 320193
```

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

### Get FinancialStatement Shape

Source: https://edgartools.readthedocs.io/en/latest/api/entity-facts-reference

Access the `shape` property to get the dimensions (rows, columns) of the underlying DataFrame for a `FinancialStatement` object.

```python
stmt = company.income_statement()
print(stmt.shape)  # (10, 4)
```

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

### Initialize XBRL Query

Source: https://edgartools.readthedocs.io/en/latest/xbrl-querying

Import necessary libraries and load an XBRL filing for a specific company. This sets up the initial XBRL object for querying.

```python
from edgar import *
from edgar.xbrl import XBRL

# Get an XBRL filing
company = Company("AAPL")
filing = company.latest("10-K")
xb = filing.xbrl()
```

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

### Track Offering Lifecycle with Form C

Source: https://edgartools.readthedocs.io/en/latest/guides/formc-data-object-guide

Retrieves a Form C filing and demonstrates how to access the complete offering lifecycle, including initial filings, updates, annual reports, and amendments. Use `get_offering()` to get the `Offering` object.

```python
from edgar import get_filings

# Get a Form C filing
filing = get_filings(form="C").head(1)[0]
formc = filing.obj()

# Get the complete offering lifecycle
offering = formc.get_offering()

# View all filings for this offering
print(offering.timeline())

# Access specific filing types
initial_filing = offering.initial()      # Original Form C
updates = offering.updates()             # Form C-U progress updates
annual_reports = offering.annual_reports()  # Form C-AR reports
amendments = offering.amendments()       # Form C/A amendments
```

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

### Methods Quick Reference

Source: https://edgartools.readthedocs.io/en/latest/eightk-filings

A reference guide to the methods available on a filing object, explaining what each method does and what it returns.

```APIDOC
## Methods Quick Reference

### Description
Provides a quick lookup for methods available on filing objects, detailing their functionality and return values.

### Methods
- **`eight_k['2.02']`** (str) - Get item content by number. Returns the content of the specified item as a string.
- **`eight_k.press_releases`** (`PressReleases`) - Collection of press release exhibits. Returns an object containing press release exhibits.
- **`eight_k.earnings`** (`EarningsRelease`) - Parsed earnings tables from EX-99.1. Returns an object with parsed earnings data.
- **`eight_k.income_statement`** (`FinancialTable`) - Income statement or None. Returns the income statement financial table if available.
- **`eight_k.balance_sheet`** (`FinancialTable`) - Balance sheet or None. Returns the balance sheet financial table if available.
- **`eight_k.cash_flow_statement`** (`FinancialTable`) - Cash flow statement or None. Returns the cash flow statement financial table if available.
- **`eight_k.get_income_statement()`** (`DataFrame`) - Income statement (empty DataFrame if missing). Returns the income statement as a pandas DataFrame.
- **`eight_k.get_balance_sheet()`** (`DataFrame`) - Balance sheet (empty DataFrame if missing). Returns the balance sheet as a pandas DataFrame.
- **`eight_k.get_cash_flow_statement()`** (`DataFrame`) - Cash flow (empty DataFrame if missing). Returns the cash flow statement as a pandas DataFrame.
```

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

### Create a Sample Company Subset from Exchange

Source: https://edgartools.readthedocs.io/en/latest/guides/reference-data

Generates a sample subset of companies listed on a specific exchange (e.g., NYSE). Requires setup for CompanySubset.

```python
CompanySubset().from_exchange("NYSE").sample(100).get()
```

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

### Get Number of Filings in Collection

Source: https://edgartools.readthedocs.io/en/latest/api/filings

Demonstrates how to get the total number of filings within a Filings collection using the `len()` function.

```python
print(f"Collection contains {len(filings)} filings")

```

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

### Core Mappings Example (Priority 1)

Source: https://edgartools.readthedocs.io/en/latest/advanced/customizing-standardization

Example of a Priority 1 mapping for base US-GAAP concepts. These are applied when no company-specific mapping exists.

```json
# P1 mapping example
"Revenue": [
  "us-gaap:Revenue",
  "us-gaap:Revenues",
  "us-gaap:SalesRevenueNet"
]
```

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

### Get FinancialStatement Index (Concepts)

Source: https://edgartools.readthedocs.io/en/latest/api/entity-facts-reference

Access the `index` property of a `FinancialStatement` to get the row labels, which usually correspond to financial concept names.

```python
concepts = stmt.index
print(list(concepts))  # ['Revenue', 'Cost of Revenue', 'Gross Profit', ...]
```

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

### Create XBRL from Directory

Source: https://edgartools.readthedocs.io/en/latest/api/xbrl

Create an XBRL instance by providing a path to a directory containing XBRL files. This method is useful for local XBRL data.

```python
@classmethod
def from_directory(cls, directory: str) -> XBRL:

    """Create an XBRL instance from a directory containing XBRL files."""

```

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

### Quick Start: Legacy FUSE Mount (Linux/macOS)

Source: https://edgartools.readthedocs.io/en/latest/guides/cloud-storage

This snippet provides instructions for setting up a legacy FUSE mount for accessing Edgar data on Linux and macOS systems.

```APIDOC
## Quick Start: Legacy FUSE Mount (Linux/macOS)

### Description
Instructions for setting up a legacy FUSE mount point to access Edgar data on Linux and macOS systems using tools like goofys.

### Method
N/A (Command Line and Environment Variables)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

### Usage Example
```bash
goofys my-edgar-bucket /mnt/edgar-data
export EDGAR_LOCAL_DATA_DIR=/mnt/edgar-data
export EDGAR_USE_LOCAL_DATA=1
```
```

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

### Install edgartools with --user flag

Source: https://edgartools.readthedocs.io/en/latest/installation

Use this command to install edgartools with the --user flag, which can help resolve permission errors on Windows.

```bash
pip install --user edgartools
```

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

### Verify edgartools Installation

Source: https://edgartools.readthedocs.io/en/latest/installation

Run this Python code to verify that edgartools is installed correctly. An ImportError indicates a potential conflict with another package named 'edgar'.

```python
from edgar import get_filings
print("EdgarTools installed successfully!")
```

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

### Fluent Interface: CompanySubset Class

Source: https://edgartools.readthedocs.io/en/latest/company-subsets

Illustrates building complex company selections using method chaining with the CompanySubset class, including filtering and sampling.

```python
from edgar.reference.company_subsets import CompanySubset, PopularityTier

# Complex selection with method chaining
companies = (
    CompanySubset()
    .from_exchange(['NYSE', 'Nasdaq'])        # Major exchanges only
    .exclude_tickers(['JPM', 'GS', 'C'])      # Exclude some financials
    .sample(50, random_state=42)              # Take random sample
    .get()                                   # Get the DataFrame
)

print(f"Selected {len(companies)} companies")
print(companies.head())

# Popular tech companies
tech_subset = (
    CompanySubset()
    .from_popular(PopularityTier.POPULAR)   # Popular companies
    .filter_by(lambda df: df['name'].str.contains('tech|software|computer', case=False))
    .top(20, by='ticker')                   # Top 20 alphabetically
    .get()
)

```

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

### Company-Specific Mapping Example (Priority 2)

Source: https://edgartools.readthedocs.io/en/latest/advanced/customizing-standardization

Example of a Priority 2 mapping for Tesla, demonstrating company-specific overrides. This is applied when a company mapping file exists.

```json
# P2 mapping example (Tesla)
"Automotive Revenue": [
  "tsla:AutomotiveRevenue",
  "tsla:AutomotiveSales"
]
```

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

### Quick Start: Parse Offering Terms from 424B5 Filing

Source: https://edgartools.readthedocs.io/en/latest/guides/prospectus424b-data-object-guide

Instantiate a Company object, retrieve the first 424B5 filing, and access the normalized deal terms. Properties on the `Deal` object may return `None` if data is unavailable in the filing.

```python
from edgar import Company

company = Company("ALZN")
filing = company.get_filings(form="424B5")[0]
prospectus = filing.obj()          # Prospectus424B
deal = prospectus.deal             # Deal: normalized summary

deal.price                         # 2.48
deal.shares                        # 1_500_000
deal.gross_proceeds                # 3_720_000.0
deal.lead_bookrunner               # "H.C. Wainwright & Co."

```
Tokens:
Raw