Skip to content

Commit 53d5947

Browse files
dgunningdgunning
committed
Reorganized README and add images
1 parent 19af92b commit 53d5947

File tree

3 files changed

+285
-168
lines changed

3 files changed

+285
-168
lines changed

‎README.md‎

Lines changed: 130 additions & 168 deletions
Original file line numberDiff line numberDiff line change
@@ -54,182 +54,41 @@
5454

5555
# Getting started
5656

57-
Install using pip
57+
## Installing
5858
```bash
5959
pip install edgartools
6060
```
6161

62-
Import and start using
63-
```python
64-
from edgar import *
65-
66-
# Tell the SEC who you are
67-
set_identity("Michael Mccallum [email protected]")
68-
69-
filings = get_filings()
70-
```
71-
72-
![](docs/images/get_filings.png)
73-
74-
# Key Concepts
7562

76-
## Getting financials
77-
```python
78-
c = Company("AAPL")
79-
# Get the latest 10-Q filing
80-
81-
filing = c.latest("10-Q")
82-
83-
# Convert to a data object, in this case a TenQ object
84-
tenq = filing.obj()
85-
86-
# Get the financials
87-
financials = tenq.financials
88-
```
89-
90-
## Listing filings
63+
## Usage
9164

92-
```python
93-
filings = get_filings(form=['10-K', '10-Q'], year=2020)
94-
filing = filings[0]
95-
```
65+
### Importing and setting your identity
9666

97-
## Finding things
67+
To get started import the library using `from edgar import *` then set your identity using `set_identity()`
9868

9969
```python
100-
filing = find("0001065280-23-000273")
101-
```
102-
For a deeper dive see **[Finding things with edgartools](https://github.com/dgunning/edgartools/wiki/FindingThings)**
103-
104-
105-
# How to use edgartools
106-
107-
| | Code |
108-
|--------------------------------------|-------------------------------------------------------|
109-
| Set your EDGAR identity in Linux/Mac | `export EDGAR_IDENTITY="[email protected]"` |
110-
| Set your EDGAR identity in Windows | `set EDGAR_IDENTITY="[email protected]"` |
111-
| Set identity in Windows Powershell | `$env:EDGAR_IDENTITY="[email protected]"` |
112-
| Set identity in Python | `set_identity("[email protected]")` |
113-
| Importing the library | `from edgar import *` |
114-
115-
### Working with filings 📁
116-
117-
#### 🔍 Getting Filings
118-
119-
| | Code |
120-
|----------------------------------------|-------------------------------------------------|
121-
| 📅 Get filings for the year to date | `filings = get_filings()` |
122-
| 📊 Get only XBRL filings | `filings = get_filings(index="xbrl")` |
123-
| 📆 Get filings for a specific year | `filings = get_filings(2020)` |
124-
| 🗓️ Get filings for a specific quarter | `filings = get_filings(2020, 1)` |
125-
| 📚 Get filings for multiple years | `filings = get_filings([2020, 2021])` |
126-
| 📈 Get filings for a range of years | `filings = get_filings(year=range(2010, 2020))` |
127-
| 📈 Get filings released just now | `filings = get_latest_filings()` |
128-
129-
#### 📄 Filtering Filings
130-
131-
| | Code |
132-
|-----------------------------------|------------------------------------------------------------------|
133-
| 📝 Filter by form type | `filings.filter(form="10-K")` |
134-
| 📑 Filter by multiple forms | `filings.filter(form=["10-K", "10-Q"])` |
135-
| 🔄 Include form amendments | `filings.filter(form="10-K", amendments=True)` |
136-
| 🏢 Filter by CIK | `filings.filter(cik="0000320193")` |
137-
| 🏙️ Filter by multiple CIKs | `filings.filter(cik=["0000320193", "1018724"])` |
138-
| 🏷️ Filter by ticker | `filings.filter(ticker="AAPL")` |
139-
| 🏷️🏷️ Filter by multiple tickers | `filings.filter(ticker=["AAPL", "MSFT"])` |
140-
| 📅 Filter on a specific date | `filings.filter(date="2020-01-01")` |
141-
| 📅↔️📅 Filter between dates | `filings.filter(date="2020-01-01:2020-03-01")` |
142-
| 📅⬅️ Filter before a date | `filings.filter(date=":2020-03-01")` |
143-
| 📅➡️ Filter after a date | `filings.filter(date="2020-03-01:")` |
144-
| 🔀 Combine multiple filters | `filings.filter(form="10-K", date="2020-01-01:", ticker="AAPL")` |
145-
146-
#### 📊 Viewing and Manipulating Filings
147-
148-
| | Code |
149-
|--------------------------------------|--------------------------|
150-
| ⏭️ Show the next page of filings | `filings.next()` |
151-
| ⏮️ Show the previous page of filings | `filings.prev()` |
152-
| 🔝 Get the first n filings | `filings.head(20)` |
153-
| 🔚 Get the last n filings | `filings.tail(20)` |
154-
| 🕒 Get the latest n filings by date | `filings.latest(20)` |
155-
| 🎲 Get a random sample of filings | `filings.sample(20)` |
156-
| 🐼 Get filings as a pandas dataframe | `filings.to_pandas()` |
157-
158-
### Working with a filing 📄
159-
160-
#### 🔍 Accessing and viewing a Filing
161-
162-
| | Code |
163-
|-------------------------------------|-----------------------------------------------------------|
164-
| 📌 Get a single filing | `filing = filings[3]` |
165-
| 🔢 Get a filing by accession number | `filing = get_by_accession_number("0000320193-20-34576")` |
166-
| 🏠 Get the filing homepage | `filing.homepage` |
167-
| 🌐 Open a filing in the browser | `filing.open()` |
168-
| 🏠 Open homepage in the browser | `filing.homepage.open()` |
169-
| 💻 View the filing in the terminal | `filing.view()` |
170-
171-
#### 📊 Extracting Filing Content
172-
173-
| | Code |
174-
|-------------------------------------|-----------------------------|
175-
| 🌐 Get the HTML of the filing | `filing.html()` |
176-
| 📊 Get the XBRL of the filing | `filing.xbrl()` |
177-
| 📝 Get the filing as markdown | `filing.markdown()` |
178-
| 📄 Get the full submission text | `filing.full_text_submission()` |
179-
| 🔢 Get and parse filing data object | `filing.obj()` |
180-
| 📑 Get filing header | `filing.header` |
181-
182-
#### 🔎 Searching inside a Filing
183-
184-
| | Code |
185-
|-----------------------------|----------------------------------------|
186-
| 🔍 Search within the filing | `filing.search("query")` |
187-
| 🔍 Search with regex | `filing.search("pattern", regex=True)` |
188-
| 📊 Get filing sections | `filing.sections()` |
189-
190-
#### 📎 Working with Attachments
191-
192-
| | Code |
193-
|-------------------------------|-----------------------------------|
194-
| 📁 Get all filing attachments | `filing.attachments` |
195-
| 📄 Get a single attachment | `attachment = filing.attachments[0]` |
196-
| 🌐 Open attachment in browser | `attachment.open()` |
197-
| ⬇️ Download an attachment | `content = attachment.download()` |
198-
199-
### Working with a company
200-
201-
| | Code |
202-
|------------------------------------------|---------------------------------------------------------------|
203-
| Get a company by ticker | `company = Company("AAPL")` |
204-
| Get a company by CIK | `company = Company("0000320193")` |
205-
| Get company facts | `company.get_facts()` |
206-
| Get company facts as a pandas dataframe | `company.get_facts().to_pandas()` |
207-
| Get company filings | `company.get_filings()` |
208-
| Get company filings by form | `company.get_filings(form="10-K")` |
209-
| Get the latest 10-Q | `company.latest("10-Q")` |
210-
| Get the last 5 10-Q's | `company.get_filings(form="10-Q", 5)` |
211-
| Get a company filing by accession_number | `company.get_filing(accession_number="0000320193-21-000139")` |
212-
| Get the company's financials | `company.financials` |
213-
| Get the company's balance sheet | `company.financials.get_balance_sheet` |
214-
| Get the company's income statement | `company.financials.get_income_statement` |
215-
| Get the company's cash flow statement | `company.financials.get_cash_flow_statement` |
70+
# 1. Import the necessary functions from edgartools
71+
from edgar import *
21672

217-
# Installation
73+
# 2. Tell the SEC who you are
74+
set_identity("[email protected]")
21875

219-
```console
220-
pip install edgartools
76+
# 3. Start using the library
77+
filings = get_filings()
78+
filings
22179
```
22280

223-
# Usage
81+
![Getting filings](docs/images/get_filings.png)
22482

83+
After getting filings you can select a single filing and view its attachments
84+
![Getting filings attachments](docs/images/filing_and_attachments.png)
22585

226-
## Set your Edgar user identity
86+
## Set your Edgar user identity as an environment variable
87+
As an alternative to using `set_identity()` you can set your Edgar user identity as an environment variable.
22788

228-
Before you can access the SEC Edgar API you need to set the identity that you will use to access Edgar.
229-
This is usually your name and email, or a company name and email but you can also just use an email.
230-
```bash
231-
Sample Company Name AdminContact@<sample company domain>.com
232-
```
89+
The reason you need to set your identity is that the SEC Edgar API requires all requests to be identified.
90+
So you should set your user identity so that the library can make API requests on your behalf.
91+
Your identity is usually a name and email, but you can also just use an email.
23392

23493
The user identity is sent in the User-Agent string and the Edgar API will refuse to respond to your request without it.
23594

@@ -253,14 +112,6 @@ set_identity("[email protected]")
253112
```
254113
For more detail see https://www.sec.gov/os/accessing-edgar-data
255114

256-
## Usage
257-
258-
### Importing edgar
259-
260-
```python
261-
from edgar import *
262-
```
263-
264115
## [Using the Filing API](https://github.com/dgunning/edgartools/wiki/WorkingWithFilings)
265116
Use the Filing API when you are not working with a specific company, but want to get a list of filings.
266117

@@ -502,6 +353,117 @@ class Attachments:
502353
# Usage
503354
filing.attachments.download(path)
504355
```
356+
# Usage Examples
357+
358+
| | Code |
359+
|--------------------------------------|-------------------------------------------------------|
360+
| Set your EDGAR identity in Linux/Mac | `export EDGAR_IDENTITY="[email protected]"` |
361+
| Set your EDGAR identity in Windows | `set EDGAR_IDENTITY="[email protected]"` |
362+
| Set identity in Windows Powershell | `$env:EDGAR_IDENTITY="[email protected]"` |
363+
| Set identity in Python | `set_identity("[email protected]")` |
364+
| Importing the library | `from edgar import *` |
365+
366+
### Working with filings 📁
367+
368+
#### 🔍 Getting Filings
369+
370+
| | Code |
371+
|----------------------------------------|-------------------------------------------------|
372+
| 📅 Get filings for the year to date | `filings = get_filings()` |
373+
| 📊 Get only XBRL filings | `filings = get_filings(index="xbrl")` |
374+
| 📆 Get filings for a specific year | `filings = get_filings(2020)` |
375+
| 🗓️ Get filings for a specific quarter | `filings = get_filings(2020, 1)` |
376+
| 📚 Get filings for multiple years | `filings = get_filings([2020, 2021])` |
377+
| 📈 Get filings for a range of years | `filings = get_filings(year=range(2010, 2020))` |
378+
| 📈 Get filings released just now | `filings = get_latest_filings()` |
379+
380+
#### 📄 Filtering Filings
381+
382+
| | Code |
383+
|-----------------------------------|------------------------------------------------------------------|
384+
| 📝 Filter by form type | `filings.filter(form="10-K")` |
385+
| 📑 Filter by multiple forms | `filings.filter(form=["10-K", "10-Q"])` |
386+
| 🔄 Include form amendments | `filings.filter(form="10-K", amendments=True)` |
387+
| 🏢 Filter by CIK | `filings.filter(cik="0000320193")` |
388+
| 🏙️ Filter by multiple CIKs | `filings.filter(cik=["0000320193", "1018724"])` |
389+
| 🏷️ Filter by ticker | `filings.filter(ticker="AAPL")` |
390+
| 🏷️🏷️ Filter by multiple tickers | `filings.filter(ticker=["AAPL", "MSFT"])` |
391+
| 📅 Filter on a specific date | `filings.filter(date="2020-01-01")` |
392+
| 📅↔️📅 Filter between dates | `filings.filter(date="2020-01-01:2020-03-01")` |
393+
| 📅⬅️ Filter before a date | `filings.filter(date=":2020-03-01")` |
394+
| 📅➡️ Filter after a date | `filings.filter(date="2020-03-01:")` |
395+
| 🔀 Combine multiple filters | `filings.filter(form="10-K", date="2020-01-01:", ticker="AAPL")` |
396+
397+
#### 📊 Viewing and Manipulating Filings
398+
399+
| | Code |
400+
|--------------------------------------|--------------------------|
401+
| ⏭️ Show the next page of filings | `filings.next()` |
402+
| ⏮️ Show the previous page of filings | `filings.prev()` |
403+
| 🔝 Get the first n filings | `filings.head(20)` |
404+
| 🔚 Get the last n filings | `filings.tail(20)` |
405+
| 🕒 Get the latest n filings by date | `filings.latest(20)` |
406+
| 🎲 Get a random sample of filings | `filings.sample(20)` |
407+
| 🐼 Get filings as a pandas dataframe | `filings.to_pandas()` |
408+
409+
### Working with a filing 📄
410+
411+
#### 🔍 Accessing and viewing a Filing
412+
413+
| | Code |
414+
|-------------------------------------|-----------------------------------------------------------|
415+
| 📌 Get a single filing | `filing = filings[3]` |
416+
| 🔢 Get a filing by accession number | `filing = get_by_accession_number("0000320193-20-34576")` |
417+
| 🏠 Get the filing homepage | `filing.homepage` |
418+
| 🌐 Open a filing in the browser | `filing.open()` |
419+
| 🏠 Open homepage in the browser | `filing.homepage.open()` |
420+
| 💻 View the filing in the terminal | `filing.view()` |
421+
422+
#### 📊 Extracting Filing Content
423+
424+
| | Code |
425+
|-------------------------------------|-----------------------------|
426+
| 🌐 Get the HTML of the filing | `filing.html()` |
427+
| 📊 Get the XBRL of the filing | `filing.xbrl()` |
428+
| 📝 Get the filing as markdown | `filing.markdown()` |
429+
| 📄 Get the full submission text | `filing.full_text_submission()` |
430+
| 🔢 Get and parse filing data object | `filing.obj()` |
431+
| 📑 Get filing header | `filing.header` |
432+
433+
#### 🔎 Searching inside a Filing
434+
435+
| | Code |
436+
|-----------------------------|----------------------------------------|
437+
| 🔍 Search within the filing | `filing.search("query")` |
438+
| 🔍 Search with regex | `filing.search("pattern", regex=True)` |
439+
| 📊 Get filing sections | `filing.sections()` |
440+
441+
#### 📎 Working with Attachments
442+
443+
| | Code |
444+
|-------------------------------|-----------------------------------|
445+
| 📁 Get all filing attachments | `filing.attachments` |
446+
| 📄 Get a single attachment | `attachment = filing.attachments[0]` |
447+
| 🌐 Open attachment in browser | `attachment.open()` |
448+
| ⬇️ Download an attachment | `content = attachment.download()` |
449+
450+
### Working with a company
451+
452+
| | Code |
453+
|------------------------------------------|---------------------------------------------------------------|
454+
| Get a company by ticker | `company = Company("AAPL")` |
455+
| Get a company by CIK | `company = Company("0000320193")` |
456+
| Get company facts | `company.get_facts()` |
457+
| Get company facts as a pandas dataframe | `company.get_facts().to_pandas()` |
458+
| Get company filings | `company.get_filings()` |
459+
| Get company filings by form | `company.get_filings(form="10-K")` |
460+
| Get the latest 10-Q | `company.latest("10-Q")` |
461+
| Get the last 5 10-Q's | `company.get_filings(form="10-Q", 5)` |
462+
| Get a company filing by accession_number | `company.get_filing(accession_number="0000320193-21-000139")` |
463+
| Get the company's financials | `company.financials` |
464+
| Get the company's balance sheet | `company.financials.get_balance_sheet` |
465+
| Get the company's income statement | `company.financials.get_income_statement` |
466+
| Get the company's cash flow statement | `company.financials.get_cash_flow_statement` |
505467

506468

507469
# Contributing

0 commit comments

Comments
 (0)