Initial commit

venv/lib/python3.10/site-packages/edgar/docs/Filing.md

@@ -0,0 +1,263 @@
+# Filing Class Documentation
+
+## Overview
+
+The `Filing` class is the core object in edgartools for working with individual SEC filings. It provides comprehensive access to filing content, metadata, documents, and related functionality, making it easy to analyze and extract data from SEC filings.
+
+## Common Actions
+
+Quick reference for the most frequently used Filing methods:
+
+### Access Filing Content
+```python
+# Get HTML content
+html = filing.html()
+
+# Get plain text
+text = filing.text()
+
+# Get markdown formatted content
+markdown = filing.markdown()
+```
+
+### Get Structured Data
+```python
+# Get form-specific object (10-K, 10-Q, 8-K, etc.)
+report = filing.obj()
+
+# Get XBRL financial data
+xbrl = filing.xbrl()
+```
+
+### View in Browser
+```python
+# Open filing in web browser
+filing.open()
+```
+
+### Get Attachments
+```python
+# Access all filing attachments
+attachments = filing.attachments
+```
+
+## Constructor
+
+```python
+Filing(cik: int, company: str, form: str, filing_date: str, accession_no: str)
+```
+
+**Parameters:**
+- `cik`: Company's Central Index Key (integer)
+- `company`: Company name (string) 
+- `form`: SEC form type (e.g., "10-K", "8-K", "DEF 14A")
+- `filing_date`: Date of filing (YYYY-MM-DD format)
+- `accession_no`: Unique SEC accession number
+
+## Core Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `cik` | int | Company's Central Index Key |
+| `company` | str | Company name |
+| `form` | str | SEC form type |
+| `filing_date` | str | Filing date |
+| `accession_no` | str | SEC accession number |
+| `accession_number` | str | Alias for accession_no |
+
+## Document Access
+
+### Primary Documents
+- **`document`** - The primary display document (HTML/XHTML)
+- **`primary_documents`** - List of all primary documents
+- **`attachments`** - All filing attachments
+- **`exhibits`** - Filing exhibits
+
+### Content Formats
+- **`html()`** - HTML content of the primary document
+- **`xml()`** - XML content of the primary document  
+- **`text()`** - Plain text version of the document
+- **`markdown()`** - Markdown formatted version
+
+## Financial Data Access
+
+### XBRL Data
+```python
+# Access structured financial data
+filing.xbrl()  # Returns XBRLInstance with financial statements
+filing.statements  # Direct access to financial statements
+```
+
+### SGML Data
+```python
+# Access SGML filing data
+filing.sgml()  # Returns SGMLFiling object
+```
+
+## Navigation & URLs
+
+| Property/Method | Description |
+|----------------|-------------|
+| `homepage` | Filing homepage information |
+| `homepage_url` | URL to the filing homepage |
+| `filing_url` | URL to the main filing document |
+| `text_url` | URL to the text version |
+| `base_dir` | Base directory URL for the filing |
+
+## Search & Analysis
+
+### Content Search
+```python
+# Search filing content
+results = filing.search("revenue recognition", regex=False)
+
+# Search with regex
+results = filing.search(r"\b\d+\.\d+%", regex=True)
+```
+
+### Document Structure
+- **`sections()`** - Get HTML sections for advanced search
+- **`period_of_report`** - Get the reporting period
+
+## Entity Relationships
+
+### Company Integration
+```python
+# Get the associated Company object
+company = filing.get_entity()
+
+# Convert to company filing with additional data
+company_filing = filing.as_company_filing()
+
+# Find related filings
+related = filing.related_filings()
+```
+
+## Display & Interaction
+
+### Console Display
+```python
+# Rich console display
+filing.view()  # Display in console with rich formatting
+
+# String representations
+str(filing)    # Concise string representation
+repr(filing)   # Detailed representation
+```
+
+### Browser Integration
+```python
+# Open filing in web browser
+filing.open()           # Open main document
+filing.open_homepage()  # Open filing homepage
+
+# Serve filing locally
+filing.serve(port=8000)  # Serve on localhost:8000
+```
+
+## Data Export & Persistence
+
+### Export Formats
+```python
+# Convert to different formats
+filing_dict = filing.to_dict()      # Dictionary
+filing_df = filing.to_pandas()      # DataFrame
+summary_df = filing.summary()       # Summary DataFrame
+```
+
+### Save & Load
+```python
+# Save filing for later use
+filing.save("my_filing.pkl")        # Save to file
+filing.save("/path/to/directory/")  # Save to directory
+
+# Load saved filing
+loaded_filing = Filing.load("my_filing.pkl")
+```
+
+## Class Methods
+
+### Alternative Constructors
+```python
+# Create from dictionary
+filing = Filing.from_dict(data_dict)
+
+# Create from JSON file
+filing = Filing.from_json("filing_data.json")
+
+# Create from SGML data
+filing = Filing.from_sgml(sgml_source)
+```
+
+## Common Usage Patterns
+
+### Basic Filing Analysis
+```python
+# Get a filing and explore its content
+filing = company.get_filings(form="10-K").latest(1)[0]
+
+# Access financial statements
+statements = filing.xbrl()
+income_statement = statements.income_statement
+
+# Search for specific content
+results = filing.search("risk factors")
+
+# View in browser
+filing.open()
+```
+
+### Working with Attachments
+```python
+# Get all attachments
+attachments = filing.attachments
+
+# Find specific exhibits
+exhibits = filing.exhibits
+exhibit_99_1 = [ex for ex in exhibits if "99.1" in ex.description]
+
+# Access exhibit content
+if exhibit_99_1:
+    content = exhibit_99_1[0].html()
+```
+
+### Financial Data Extraction
+```python
+# Get financial statements
+xbrl = filing.xbrl()
+
+# Access different statement types
+balance_sheet = xbrl.balance_sheet
+income_statement = xbrl.income_statement  
+cash_flow = xbrl.cash_flow_statement
+
+# Get specific facts
+revenue = xbrl.get_facts("Revenues")
+```
+
+## Error Handling
+
+The Filing class handles various edge cases gracefully:
+
+- **Missing documents**: Returns None or empty collections
+- **Network errors**: Raises appropriate HTTP exceptions
+- **Malformed data**: Provides informative error messages
+- **File access**: Handles permissions and missing files
+
+## Integration with Other Classes
+
+The Filing class works seamlessly with other edgartools components:
+
+- **Company**: Get filings from companies, convert back to company context
+- **Filings**: Part of filing collections with filtering and search
+- **XBRLInstance**: Access structured financial data
+- **Attachments**: Work with filing documents and exhibits
+
+## Performance Considerations
+
+- **Lazy loading**: Documents and data are loaded only when accessed
+- **Caching**: Network requests are cached to improve performance  
+- **Streaming**: Large documents can be processed in chunks
+- **Async support**: Some operations support asynchronous execution
+
+This comprehensive API makes the Filing class the primary interface for working with SEC filing data in edgartools.

venv/lib/python3.10/site-packages/edgar/docs/Filings.md

@@ -0,0 +1,302 @@
+# Filings Class Documentation
+
+## Overview
+
+The `Filings` class is a powerful container for SEC filing data that provides comprehensive functionality for filtering, searching, pagination, and data manipulation. It's built on PyArrow tables for efficient processing of large datasets and offers an intuitive interface for working with collections of SEC filings.
+
+## Getting Filings
+
+```python
+filings = get_filings()
+```
+- **Parameters**: 
+  - `year`: Year of filings (optional)
+  - `quarter`: Quarter of filings (optional)
+  - `amendments`: Include amended filings (default: True)
+  - `ticker`: Company ticker symbol (optional)
+  - `filing_date`: Date or date range for filtering (optional)
+
+## Core Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `data` | pa.Table | PyArrow table with filing information |
+| `date_range` | Tuple[str, str] | Start and end dates of filings |
+| `start_date` | str | Earliest filing date in collection |
+| `end_date` | str | Latest filing date in collection |
+| `empty` | bool | True if collection contains no filings |
+| `summary` | str | Description of current page/total filings |
+
+## Data Access & Conversion
+
+### DataFrame Conversion
+```python
+# Convert to pandas DataFrame
+df = filings.to_pandas()                    # All columns
+df = filings.to_pandas('form', 'company')   # Specific columns
+```
+
+### Individual Filing Access
+```python
+# Get filing by index
+filing = filings.get_filing_at(0)          # First filing
+filing = filings[0]                        # Alternative syntax
+
+# Get filing by accession number
+filing = filings.get("0000320193-23-000077")
+
+# Get filing by index or accession
+filing = filings.get(5)                    # By index
+filing = filings.get("0000320193-23-000077")  # By accession
+```
+
+### Export & Persistence
+```python
+# Save as Parquet file
+filings.save_parquet("filings_data.parquet")
+filings.save("filings_data.parquet")      # Alternative
+
+# Convert to dictionary
+data_dict = filings.to_dict(max_rows=1000)
+```
+
+## Filtering & Search
+
+### Form-based Filtering
+```python
+# Single form type
+filings.filter(form="10-K")
+filings.filter(form="8-K")
+
+# Multiple form types
+filings.filter(form=["10-K", "10-Q"])
+filings.filter(form=["8-K", "DEF 14A"])
+
+# Include/exclude amendments
+filings.filter(form="10-K", amendments=True)   # Include amendments
+filings.filter(form="10-K", amendments=False)  # Exclude amendments
+```
+
+### Date Filtering
+```python
+# Specific date
+filings.filter(date="2023-06-15")
+filings.filter(filing_date="2023-06-15")     # Alternative
+
+# Date ranges
+filings.filter(date="2023-01-01:2023-03-31") # Between dates
+filings.filter(date="2023-01-01:")           # From date onwards
+filings.filter(date=":2023-03-31")           # Up to date
+```
+
+### Company-based Filtering
+```python
+# By CIK (Central Index Key)
+filings.filter(cik=320193)                   # Single CIK
+filings.filter(cik=[320193, 789019])         # Multiple CIKs
+
+# By ticker symbol
+filings.filter(ticker="AAPL")
+filings.filter(ticker=["AAPL", "MSFT"])
+
+# By exchange
+filings.filter(exchange="NASDAQ")
+filings.filter(exchange=["NYSE", "NASDAQ"])
+
+# By accession number
+filings.filter(accession_number="0000320193-23-000077")
+```
+
+### Company Search
+```python
+# Search for company and filter
+apple_filings = filings.find("Apple")
+microsoft_filings = filings.find("Microsoft Corporation")
+```
+
+### Combined Filtering
+```python
+# Complex filtering example
+filtered = filings.filter(
+    form=["10-K", "10-Q"],
+    date="2023-01-01:2023-12-31",
+    ticker=["AAPL", "MSFT", "GOOGL"],
+    amendments=False
+)
+```
+
+## Data Selection & Sampling
+
+### Latest Filings
+```python
+# Get most recent filings
+latest_filing = filings.latest()           # Most recent (default n=1)
+latest_five = filings.latest(5)            # Most recent 5
+```
+
+### Head & Tail
+```python
+# Get first/last n filings
+first_ten = filings.head(10)               # First 10 filings
+last_ten = filings.tail(10)                # Last 10 filings
+```
+
+### Random Sampling
+```python
+# Get random sample
+sample = filings.sample(20)                # Random 20 filings
+```
+
+## Pagination
+
+### Navigation
+```python
+# Navigate through pages
+current_page = filings.current()           # Current page info
+next_page = filings.next()                 # Next page
+prev_page = filings.previous()             # Previous page
+```
+
+### Page Information
+```python
+# Check pagination status
+print(filings.summary)                     # "Page 1 of 50 (total: 12,543 filings)"
+is_empty = filings.empty                   # Check if no results
+```
+
+## File Operations
+
+### Download Filings
+```python
+# Download all filings in collection
+filings.download()                         # Download to default directory
+filings.download("./my_filings/")          # Download to specific directory
+```
+
+## Integration with Other Classes
+
+### Filing Objects
+```python
+# Each item returns a Filing object
+for filing in filings:
+    print(f"Form: {filing.form}")
+    print(f"Company: {filing.company}")
+    print(f"Date: {filing.filing_date}")
+    
+    # Access filing content
+    html_content = filing.html()
+    attachments = filing.attachments
+    xbrl_data = filing.xbrl()
+```
+
+### Company Integration
+```python
+# Convert filing to company context
+filing = filings[0]
+company = filing.get_entity()              # Get Company object
+company_filing = filing.as_company_filing() # Enhanced filing with company data
+```
+
+## Rich Console Display
+
+The Filings class provides formatted console output showing:
+- Filing table with Form, CIK, Ticker, Company, Filing Date, Accession Number
+- Pagination information
+- Navigation hints
+
+```python
+# Display in console
+print(filings)                             # Rich formatted table
+filings.view()                             # Alternative display method
+```
+
+## Common Usage Patterns
+
+### Quarterly Filing Analysis
+```python
+# Get all 10-K filings for 2023
+annual_reports = get_filings(2023).filter(form="10-K", amendments=False)
+
+# Find latest 10-Q for major tech companies
+tech_quarterlies = get_filings(2023, 4).filter(
+    form="10-Q",
+    ticker=["AAPL", "MSFT", "GOOGL", "TSLA"]
+).latest(4)
+```
+
+### Company-Specific Research
+```python
+# Get all Apple filings from Q1 2023
+apple_filings = get_filings(2023, 1).find("Apple Inc")
+
+# Filter for specific forms
+apple_major_filings = apple_filings.filter(
+    form=["10-K", "10-Q", "8-K"],
+    amendments=False
+)
+```
+
+### Event-Driven Analysis
+```python
+# Find 8-K filings around specific dates
+event_filings = get_filings(2023, 2).filter(
+    form="8-K",
+    date="2023-02-01:2023-02-28"
+)
+
+# Sample for analysis
+sample_events = event_filings.sample(50)
+```
+
+### Bulk Data Processing
+```python
+# Get large dataset and save for later
+all_2023_filings = get_filings(2023)
+all_2023_filings.save_parquet("2023_filings.parquet")
+
+# Convert to pandas for analysis
+df = all_2023_filings.to_pandas(['form', 'company', 'filing_date'])
+```
+
+## Performance Considerations
+
+- **PyArrow Backend**: Efficient columnar data processing
+- **Lazy Evaluation**: Filters are applied efficiently without loading full documents
+- **Pagination**: Large datasets are handled through pagination
+- **Caching**: Network requests are cached for improved performance
+- **Parallel Processing**: Some operations support concurrent execution
+
+## Error Handling
+
+The Filings class handles various scenarios gracefully:
+
+- **Empty Results**: Returns empty Filings object with `empty=True`
+- **Invalid Filters**: Raises informative ValueError with guidance
+- **Network Issues**: Propagates HTTP errors with context
+- **Data Type Mismatches**: Automatic type conversion where possible
+
+## Method Chaining
+
+Most filtering and selection methods return new Filings objects, enabling method chaining:
+
+```python
+# Chain multiple operations
+result = (filings
+    .filter(form=["10-K", "10-Q"])
+    .filter(date="2023-01-01:2023-06-30")
+    .filter(amendments=False)
+    .latest(10))
+```
+
+## Schema Information
+
+The underlying PyArrow table contains these key columns:
+- `form`: SEC form type
+- `cik`: Company Central Index Key
+- `ticker`: Stock ticker symbol
+- `company`: Company name
+- `filing_date`: Date of filing
+- `accession_number`: Unique SEC identifier
+- Additional metadata columns for enhanced functionality
+
+This comprehensive API makes the Filings class the primary interface for working with collections of SEC filing data in edgartools, providing both power and ease of use for financial data analysis.