edgar-sec

edgar-sec

A feature-rich python package for interacting with the US Securities and Exchange Commission API: EDGAR

Features

• Native support for asynchronous requests (async).
• All method outputs are mapped to dataclasses for better usability.
• Local caching for easier data access and faster execution times.
• Built-in rate limiter that doesn't exceed 10 calls per second (ignores local caching).
• MyPy compatible type stubs.

Installation

You can install the package using pip:

pip install edgar-sec

Using conda

edgar-sec is available on Anaconda through the author's channel:

conda install -c nikhilxsunder edgar-sec

We recommend creating a dedicated environment:

conda create -n edgar-env
conda activate edgar-env
conda install -c nikhilxsunder edgar-sec

Note: edgar-sec will be submitted to conda-forge in the future for broader distribution.

Rest API Usage

I recommend consulting the documentation at: https://nikhilxsunder.github.io/edgar-sec/

Here is a simple example of how to use the package:

# EDGAR API
import edgar_sec as ed
edgar = ed.EdgarAPI()

# Get company concept disclosures
company_concept = edgar.get_company_concept(central_index_key='0001067983', taxonomy='us-gaap', tag='AccountsPayableCurrent')
print(company_concept.label)

# Get company concept disclosures (async)
import asyncio
async def main():
    edgar = ed.EdgarAPI()
    company_concept = await edgar.get_company_concept(central_index_key='0001067983', taxonomy='us-gaap', tag='AccountsPayableCurrent')
    print(company_concept.label)
asyncio.run(main())

Important Notes

• OpenSSF Badge in progress.

Continuous Integration

Edgar-SEC uses GitHub Actions for continuous integration. The following workflows run automatically:

• Build and Test: Triggered on every push and pull request to verify the codebase builds and tests pass
• Analyze: Runs static code analysis to identify potential issues
• Test: Comprehensive test suite with coverage reporting
• CodeQL: Security analysis to detect vulnerabilities

These checks ensure that all contributions maintain code quality and don't introduce regressions.

Status badges at the top of this README reflect the current state of our CI pipelines.

Development

Edgar-SEC uses standard Python packaging tools:

• Poetry: For dependency management and package building
• pytest: For testing
• Sphinx: For documentation generation

To set up the development environment:

# Install Poetry
curl -sSL https://install.python-poetry.org | python3 -

# Clone the repository
git clone https://github.com/nikhilxsunder/edgar-sec.git
cd edgar-sec

# Install dependencies
poetry install

# Run tests
poetry run pytest

Testing

The project uses pytest as its testing framework. Tests are located in the tests/ directory.

To run the complete test suite:

poetry run pytest

For running tests with coverage reports:

poetry run pytest --cov=edgar_sec tests/

To run a specific test file:

poetry run pytest tests/test_specific_module.py

Test Coverage

We aim to maintain a minimum of 80% code coverage across the codebase. This includes:

• Core functionality: 90%+ coverage
• Edge cases and error handling: 80%+ coverage
• Utility functions: 75%+ coverage

Continuous integration automatically runs tests on all pull requests and commits to the main branch.

Test Policy

Edgar-SEC requires tests for all new functionality. When contributing:

• All new features must include appropriate tests
• Bug fixes should include tests that verify the fix
• Tests should be added to the automated test suite in the tests/ directory

Security

For information about reporting security vulnerabilities in Edgar-SEC, please see our Security Policy.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

This project is licensed under the GNU Affero General Public License v3.0 - see the LICENSE file for details.