Skip to main content

Python interface to EDGAR filings.

Project description


Python package for downloading EDGAR documents and data


There are two primary interfaces to this library, namely filings and indices. is the main module for interacting with EDGAR forms.

Simple example:

from pyedgar import Filing
f = Filing(20, '0000893220-96-000500')

#output: <EDGAR filing (20/0000893220-96-000500) Headers:False, Text:False, Documents:False>

print(f.type, f)
# output: 10-K <EDGAR filing (20/0000893220-96-000500) Headers:True, Text:True, Documents:False>

# Output:
#                               WASHINGTON, D.C. 20549
#                                     FORM 10-K
#  (Mark One)
#  /X/  Annual report pursuant to section 13 or 15(d) of the Securities Exchange
#       Act of 1934 [Fee Required] for the fiscal year ended December 30, 1995 or
#  / / Transition report pursuant to section 13 or 15(d) of the Securities
#      Exchange Act of 1934 [No Fee Required] for the transition period from
#      ________ to ________
#                             K-TRON INTERNATIONAL, INC.
#                 New Jersey                                22-1759452
#     (State or other jurisdiction of         (I.R.S. Employer Identification No.)

The forms are loaded lazily, so only when you request the data is the file read from disk or downloaded from the EDGAR website. Filing objects have the following properties:

  • path: path to cached filing on disk
  • urls: URLs the EDGAR website location for the full text file and the index file
  • full_text: Full text of the entire .nc filing (not just the first document)
  • headers: Dictionary of all the headers from the full filing (i.e. not the exhibits). E.g. CIK, ACCESSION, PERIOD, etc.
  • type: The general type of the document, extracted from the TYPE header and cleaned up (so 10-K405 --> 10-K)
  • type_exact: The exact text extracted from the TYPE field
  • documents: Array of all the documents (between <DOCUMENT></DOCUMENT> tags). 0th is typically the main form, i.e. the 10-K filing, subsequent documents are exhibits.
    • Each document in this array is itself a dictionary, with fields: TYPE, SEQUENCE, DESCRIPTION (typically the file name), FULL_TEXT. The latter is the text of the exhibit, i.e. just the 10-K filing in text or HTML. is the main module for accessing extracted EDGAR indices. The indices are created in pyedgar.utilities.indices by the IndexMaker class. Once these indices are created (which you can do by setting force_download=True), you can view them via the indices property:

from pyedgar import EDGARIndex
all_indices = EDGARIndex(force_download=False)

# Output:
# {'': '/data/storage/edgar/indices/',
#  '': '/data/storage/edgar/indices/',
#  '': '/data/storage/edgar/indices/',
#  '': '/data/storage/edgar/indices/',
#  '': '/data/storage/edgar/indices/',
#  '': '/data/storage/edgar/indices/',
#  '': '/data/storage/edgar/indices/'}

These indices are accessible as a pandas dataframe via [] or the get_index method, where the index is selected via the key above (with or without the form_ or .tab).

form_10k = all_indices['10-K']

# Output:
#       cik                      name  form    filedate             accession
#    0   20  K TRON INTERNATIONAL INC  10-K  1996-03-28  0000893220-96-000500

To get a type of form that isn't automatically extracted, you can use form_all:

df_s1 = EDGARIndex().get_index('all').query("form.str.startswith('S-1')")

# Output:
#        cik        name form    filedate             accession
# 5600  1961  WORLDS INC  S-1  2014-02-04  0001264931-14-000033

All indices are loaded and saved by pandas, so pandas is a requirement for using this functionality.


Config files named pyedgar.conf, .pyedgar, pyedgar.ini are searched for at (in order):

  1. os.environ.get("PYEDGAR_CONF", '.') <-- PYEDGAR_CONF environmental variable
  2. ./
  3. ~/.config/pyedgar
  4. ~/AppData/Local/pyedgar
  5. ~/AppData/Roaming/pyedgar
  6. ~/Library/Preferences/pyedgar
  7. ~/.config/
  8. ~/
  9. ~/Documents/
  10. os.path.abspath(os.path.dirname(__file__)) <-- directory of the package. Default package ships with this existing.

See the example config file for commented config settings.

Running multiple configs is quite easy, by setting os.environ manually:

import os
# os.environ['PYEDGAR_CONF'] = os.path.expanduser('~/Dropbox/config/pyedgar/hades.local.pyedgar.conf')
os.environ['PYEDGAR_CONF'] = os.path.expanduser('~/Dropbox/config/pyedgar/hades.desb.pyedgar.conf')

from pyedgar import config

# Output:
#     WARNING:pyedgar.config:Loaded config file from '[~]/Dropbox/config/pyedgar/hades.desb.pyedgar.conf'.
#     ALERT!!!! FILING_PATH_FORMAT is '{accession[11:13]}/{accession}.nc'.
#     [~]/Dropbox/config/pyedgar/hades.desb.pyedgar.conf


Pip installable:

pip install pyedgar

Or pip installable from github:

pip install git+

or by checking out from github and installing in editable mode:

git clone
cd pyedgar
pip install -e ./


w3m for converting HTML to plaintext (tested on Linux). A fallback method might one day be added.

Tested only on Python >3.4

HTML parsing tested only on Linux. Other HTML->text conversion methodologies were tried (html2text, BeautifulSoup, lxml) but w3m was fastest even with the subprocess calling. Converting multiple HTML files could probably be optimized with one instance of w3m instead of spawning a subprocess for each call. But that's for future Mac to work on.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pyedgar, version 0.1.5
Filename, size File type Python version Upload date Hashes
Filename, size pyedgar-0.1.5.tar.gz (40.8 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page