A new way to document code

"There are only two hard things in computer science: cache invalidation, naming things, and off-by-one errors."

With the Filing and Filings classes edgartools gets the naming right. The naming makes the many-to-one relationship between the two classes perfectly clear. And that clarity means you expect multiple filings to be contained in a Filings from which you can get a single Filing - the specific set documents a company filed with the SEC.

But it's not job done. Implicit is good, explicit is necessary. For one, there's a lot of functionality wrapped within these classes. So much of the utility of the library revolves around finding, viewing, transforming and analyzing filings that understanding the fundamental concepts makes you more productive. This article fills in some details about filings that will make working with edgartools even more pleasant.

The source of filings

2 sources actually, and that's why there are 2 filing classes - Filings and EntityFilings.

Filings

The first - Filings is populated from the get_filings function which reads the SEC's filing index files which have a url pattern like https://www.sec.gov/Archives/edgar/full-index/2025/QTR2/. These are partitioned by quarter which means multiple fetches for date periods larger than a quarter.

By default get_filings fetches filings for the year to date.

EntityFilings

The second - EntityFilings what you get when you call company.get_filings which is populated from company submission json files. The overall view and behaviour is similar to Filings even though it has a different underlying schema.

Filing vs EntityFiling

The schema differences are significant but most evident when you get the Filing or EntityFiling .

Filing is created from a basic set of fields

EntityFiling has a lot more fields on initial creation.

This makes it more convenient to access filings through the Company if you are looking for fields like file_number, report_date, or acceptance_datetime. You can still get access to these fields from the regular Filing class e.g. from filing.header but it might require additional http requests and so will be slower.

The Filing class actually has an as_company_filing to convert to an EntityFiling which will give access to the additional fields if you need to. And just as I typed that sentence I realized I hadn't explained Company vs Entity.

Company vs Entity

An Entity is an individual or a company registered to file with the SEC. A Company is not an individual and not Warren Buffet. That last condition is not a joke - Mr Buffet resembles a company so much that the code has an explicit check for him.

Filing as a data and document source

Back to the main point - if you have a Filing or EntityFiling you are at the core of edgartools - the ability to do analysis on the documents or data attached to the filing. You can get the html, xml, or xbrl, convert to financial data for analysis. This is the core of user journeys which I will speak about in another blog post, but essentially as an investment analyst your journey may be getting a company by ticker, finding their most recent 8-K filings and extracting investment signals from the recent company events. But to enable user journeys we need to improve the level of the documentation.

Docs

There is a new class called Docs which represents the documentation for some component or class. On some of the core classes Filing, Filings, EntityFilings I've added a property docs that when called will display essential documentation about that component. Here is what is displayed when you call filing.docs

This displays in markdown the documentation for the Filing class. Technically this is a fairly minor feature and easy enough to have Claude Code generate. But as the library becomes more mature, as AI assisted development becomes mainstream, the value of quality documentation readable by both humans and AI increases. So this mini-framework will allow for better documentation throughout the framework.

Conclusion

This article was about the core classes of edgartools - Filing and Filings but also about improving the productivity and ease of use of the library.

If you haven't given edgartools a try install it using pip install -U edgartools and head over to the project on Github and give it a star.