ss# fedfred
## A feature-rich python package for interacting with the Federal Reserve Bank of St. Louis Economic Database: FRED
<div align="center">
<img src="https://raw.githubusercontent.com/nikhilxsunder/fedfred/main/docs/source/_static/fedfred-logo.png" width="30%" alt="FedFred Logo">
</div>
<div align="center">
<a href="https://github.com/nikhilxsunder/fedfred/actions/workflows/main.yml"><img src="https://github.com/nikhilxsunder/fedfred/actions/workflows/main.yml/badge.svg" alt="Build and test GitHub"></a>
<a href="https://github.com/nikhilxsunder/fedfred/actions/workflows/analyze.yml"><img src="https://github.com/nikhilxsunder/fedfred/actions/workflows/analyze.yml/badge.svg" alt="Analyze Status"></a>
<a href="https://github.com/nikhilxsunder/fedfred/actions/workflows/test.yml"><img src="https://github.com/nikhilxsunder/fedfred/actions/workflows/test.yml/badge.svg" alt="Test Status"></a>
<a href="https://github.com/nikhilxsunder/fedfred/actions/workflows/codeql.yml"><img src="https://github.com/nikhilxsunder/fedfred/actions/workflows/codeql.yml/badge.svg" alt="CodeQL"></a>
<a href="https://www.bestpractices.dev/projects/10158"><img src="https://www.bestpractices.dev/projects/10158/badge"></a>
<a href="https://codecov.io/gh/nikhilxsunder/fedfred"><img src="https://codecov.io/gh/nikhilxsunder/fedfred/graph/badge.svg?token=VVEK415DF6" alt="Code Coverage"></a>
<a href="https://socket.dev/pypi/package/fedfred/overview/1.2.9/tar-gz"><img src="https://socket.dev/api/badge/pypi/package/fedfred/1.2.9?artifact_id=tar-gz"></a>
<a href="https://repology.org/project/python%3Afedfred/versions"><img src="https://repology.org/badge/tiny-repos/python%3Afedfred.svg" alt="Packaging status"></a>
<a href="https://pypi.org/project/fedfred/"><img src="https://img.shields.io/pypi/v/fedfred.svg" alt="PyPI version"></a>
<a href="https://pepy.tech/projects/fedfred"><img src="https://static.pepy.tech/badge/fedfred" alt="PyPI Downloads"></a>
<a href="https://anaconda.org/conda-forge/fedfred"><img src="https://anaconda.org/conda-forge/fedfred/badges/version.svg" alt="Conda-Forge version"></a>
<a href="https://anaconda.org/conda-forge/fedfred"><img src="https://anaconda.org/conda-forge/fedfred/badges/downloads.svg" alt="Conda-Forge downloads"></a>
</div>
### Features
- Now available on Conda-Forge!
- Pandas/Polars/Dask DataFrame native support.
- GeoPandas/Polars-ST/Geopandas-Dask GeoDataframe native support
- Native support for asynchronous requests (async).
- Local caching for easier data access and faster execution times.
- Built-in rate limiter that doesn't exceed 120 calls per minute (ignores local caching).
### Installation
You can install the package using pip:
```sh
pip install fedfred
```
Or install from conda-forge:
```sh
conda install -c conda-forge fedfred
```
For type checking support, install with optional type stubs:
```sh
pip install fedfred[types]
```
For use with Polars DataFrames and GeoDataFrames, install with:
```sh
pip install fedfred[polars]
```
For use with Dask DataFrames and GeoDataFrames, install with:
```sh
pip install fedfred[dask]
```
We recommend using a virtual environment with either installation method.
### Rest API Usage
I recommend consulting the documentation at:
https://nikhilxsunder.github.io/fedfred/
Here is a simple example of how to use the package:
```python
# FredAPI
import fedfred as fd
api_key = 'your_api_key'
fred = fd.FredAPI(api_key)
# Get Series Observations as a pandas DataFrame
gdp = fred.get_series_observations('GDP')
gdp.head()
# Get Series Observations as a pandas DataFrame (async)
import asyncio
async def main():
fred = fd.FredAPI(api_key).Async
gdp = fred.get_series_observations('GNPCA')
print(observations.head())
asyncio.run(main())
```
### Important Notes
- Store your API keys and secrets in environment variables or secure storage solutions.
- Do not hardcode your API keys and secrets in your scripts.
- XML filetype (file_type='xml') is currently not supported but will be in a future update
### Continuous Integration
FedFred 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
- **Docs**: Deploys Github Pages website for documentation, built off of sphinx docs.
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
FedFred 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:
```sh
# Install Poetry
curl -sSL https://install.python-poetry.org | python3 -
# Clone the repository
git clone https://github.com/nikhilxsunder/fedfred.git
cd fedfred
# 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:
```sh
poetry run pytest
```
For running tests with coverage reports:
```sh
poetry run pytest --cov=fedfred tests/
```
To run a specific test file:
```sh
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
FedFred 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 FedFred, please see our [Security Policy](https://github.com/nikhilxsunder/fedfred/blob/main/SECURITY.md).
### 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](https://github.com/nikhilxsunder/fedfred/blob/main/LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/nikhilxsunder/fedfred",
"name": "fedfred",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "fred, federal reserve, api, economics, finance, economic data, financial data, fred pandas, fred polars, fred dask, fred geopandas, async, pandas, polars, dask, geopandas, cache, financial analysis, economic analysis, data analysis, data science, data visualization, data mining, data wrangling, data cleaning",
"author": "Nikhil Sunder",
"author_email": "nsunder724@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/37/87/4e261dc472462552f894e7873a39a0500fb6d25d615cb4c3ade7dd4cf15b/fedfred-2.1.1.tar.gz",
"platform": null,
"description": "ss# fedfred\n\n## A feature-rich python package for interacting with the Federal Reserve Bank of St. Louis Economic Database: FRED\n\n<div align=\"center\">\n <img src=\"https://raw.githubusercontent.com/nikhilxsunder/fedfred/main/docs/source/_static/fedfred-logo.png\" width=\"30%\" alt=\"FedFred Logo\">\n</div>\n\n<div align=\"center\">\n <a href=\"https://github.com/nikhilxsunder/fedfred/actions/workflows/main.yml\"><img src=\"https://github.com/nikhilxsunder/fedfred/actions/workflows/main.yml/badge.svg\" alt=\"Build and test GitHub\"></a>\n <a href=\"https://github.com/nikhilxsunder/fedfred/actions/workflows/analyze.yml\"><img src=\"https://github.com/nikhilxsunder/fedfred/actions/workflows/analyze.yml/badge.svg\" alt=\"Analyze Status\"></a>\n <a href=\"https://github.com/nikhilxsunder/fedfred/actions/workflows/test.yml\"><img src=\"https://github.com/nikhilxsunder/fedfred/actions/workflows/test.yml/badge.svg\" alt=\"Test Status\"></a>\n <a href=\"https://github.com/nikhilxsunder/fedfred/actions/workflows/codeql.yml\"><img src=\"https://github.com/nikhilxsunder/fedfred/actions/workflows/codeql.yml/badge.svg\" alt=\"CodeQL\"></a>\n <a href=\"https://www.bestpractices.dev/projects/10158\"><img src=\"https://www.bestpractices.dev/projects/10158/badge\"></a>\n <a href=\"https://codecov.io/gh/nikhilxsunder/fedfred\"><img src=\"https://codecov.io/gh/nikhilxsunder/fedfred/graph/badge.svg?token=VVEK415DF6\" alt=\"Code Coverage\"></a>\n <a href=\"https://socket.dev/pypi/package/fedfred/overview/1.2.9/tar-gz\"><img src=\"https://socket.dev/api/badge/pypi/package/fedfred/1.2.9?artifact_id=tar-gz\"></a>\n <a href=\"https://repology.org/project/python%3Afedfred/versions\"><img src=\"https://repology.org/badge/tiny-repos/python%3Afedfred.svg\" alt=\"Packaging status\"></a>\n <a href=\"https://pypi.org/project/fedfred/\"><img src=\"https://img.shields.io/pypi/v/fedfred.svg\" alt=\"PyPI version\"></a>\n <a href=\"https://pepy.tech/projects/fedfred\"><img src=\"https://static.pepy.tech/badge/fedfred\" alt=\"PyPI Downloads\"></a>\n <a href=\"https://anaconda.org/conda-forge/fedfred\"><img src=\"https://anaconda.org/conda-forge/fedfred/badges/version.svg\" alt=\"Conda-Forge version\"></a>\n <a href=\"https://anaconda.org/conda-forge/fedfred\"><img src=\"https://anaconda.org/conda-forge/fedfred/badges/downloads.svg\" alt=\"Conda-Forge downloads\"></a>\n</div>\n\n### Features\n\n- Now available on Conda-Forge!\n- Pandas/Polars/Dask DataFrame native support.\n- GeoPandas/Polars-ST/Geopandas-Dask GeoDataframe native support\n- Native support for asynchronous requests (async).\n- Local caching for easier data access and faster execution times.\n- Built-in rate limiter that doesn't exceed 120 calls per minute (ignores local caching).\n\n### Installation\n\nYou can install the package using pip:\n\n```sh\npip install fedfred\n```\n\nOr install from conda-forge:\n\n```sh\nconda install -c conda-forge fedfred\n```\n\nFor type checking support, install with optional type stubs:\n\n```sh\npip install fedfred[types]\n```\n\nFor use with Polars DataFrames and GeoDataFrames, install with:\n\n```sh\npip install fedfred[polars]\n```\n\nFor use with Dask DataFrames and GeoDataFrames, install with:\n\n```sh\npip install fedfred[dask]\n```\n\nWe recommend using a virtual environment with either installation method.\n\n### Rest API Usage\n\nI recommend consulting the documentation at:\nhttps://nikhilxsunder.github.io/fedfred/\n\nHere is a simple example of how to use the package:\n\n```python\n# FredAPI\nimport fedfred as fd\napi_key = 'your_api_key'\nfred = fd.FredAPI(api_key)\n\n# Get Series Observations as a pandas DataFrame\ngdp = fred.get_series_observations('GDP')\ngdp.head()\n\n# Get Series Observations as a pandas DataFrame (async)\nimport asyncio\nasync def main():\n fred = fd.FredAPI(api_key).Async\n gdp = fred.get_series_observations('GNPCA')\n print(observations.head())\nasyncio.run(main())\n```\n\n### Important Notes\n\n- Store your API keys and secrets in environment variables or secure storage solutions.\n- Do not hardcode your API keys and secrets in your scripts.\n- XML filetype (file_type='xml') is currently not supported but will be in a future update\n\n### Continuous Integration\n\nFedFred uses GitHub Actions for continuous integration. The following workflows run automatically:\n\n- **Build and Test**: Triggered on every push and pull request to verify the codebase builds and tests pass\n- **Analyze**: Runs static code analysis to identify potential issues\n- **Test**: Comprehensive test suite with coverage reporting\n- **CodeQL**: Security analysis to detect vulnerabilities\n- **Docs**: Deploys Github Pages website for documentation, built off of sphinx docs.\n\nThese checks ensure that all contributions maintain code quality and don't introduce regressions.\n\nStatus badges at the top of this README reflect the current state of our CI pipelines.\n\n### Development\n\nFedFred uses standard Python packaging tools:\n\n- **Poetry**: For dependency management and package building\n- **pytest**: For testing\n- **Sphinx**: For documentation generation\n\nTo set up the development environment:\n\n```sh\n# Install Poetry\ncurl -sSL https://install.python-poetry.org | python3 -\n\n# Clone the repository\ngit clone https://github.com/nikhilxsunder/fedfred.git\ncd fedfred\n\n# Install dependencies\npoetry install\n\n# Run tests\npoetry run pytest\n```\n\n### Testing\n\nThe project uses pytest as its testing framework. Tests are located in the `tests/` directory.\n\nTo run the complete test suite:\n\n```sh\npoetry run pytest\n```\n\nFor running tests with coverage reports:\n\n```sh\npoetry run pytest --cov=fedfred tests/\n```\n\nTo run a specific test file:\n\n```sh\npoetry run pytest tests/test_specific_module.py\n```\n\n#### Test Coverage\n\nWe aim to maintain a minimum of 80% code coverage across the codebase. This includes:\n\n- Core functionality: 90%+ coverage\n- Edge cases and error handling: 80%+ coverage\n- Utility functions: 75%+ coverage\n\nContinuous integration automatically runs tests on all pull requests and commits to the main branch.\n\n#### Test Policy\n\nFedFred requires tests for all new functionality. When contributing:\n\n- All new features must include appropriate tests\n- Bug fixes should include tests that verify the fix\n- Tests should be added to the automated test suite in the `tests/` directory\n\n## Security\n\nFor information about reporting security vulnerabilities in FedFred, please see our [Security Policy](https://github.com/nikhilxsunder/fedfred/blob/main/SECURITY.md).\n\n### Contributing\n\nContributions are welcome! Please open an issue or submit a pull request.\n\n### License\n\nThis project is licensed under the GNU Affero General Public License v3.0 - see the [LICENSE](https://github.com/nikhilxsunder/fedfred/blob/main/LICENSE) file for details.\n",
"bugtrack_url": null,
"license": "AGPL-3.0-or-later",
"summary": "A feature-rich python package for interacting with the Federal Reserve Bank of St. Louis Economic Database: FRED",
"version": "2.1.1",
"project_urls": {
"Documentation": "https://nikhilxsunder.github.io/fedfred/",
"Homepage": "https://github.com/nikhilxsunder/fedfred",
"Repository": "https://github.com/nikhilxsunder/fedfred"
},
"split_keywords": [
"fred",
" federal reserve",
" api",
" economics",
" finance",
" economic data",
" financial data",
" fred pandas",
" fred polars",
" fred dask",
" fred geopandas",
" async",
" pandas",
" polars",
" dask",
" geopandas",
" cache",
" financial analysis",
" economic analysis",
" data analysis",
" data science",
" data visualization",
" data mining",
" data wrangling",
" data cleaning"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e8f17bc051a7ec9844ba4bc31dd8a9a2fa96546d36bb1f70587aecb456cef616",
"md5": "d6d9c376dc2cf303323b7e6c7734c2cb",
"sha256": "69965419189a8f80382c1a40ede644b8536420897e0950b93ec41ed5c9d39ad8"
},
"downloads": -1,
"filename": "fedfred-2.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d6d9c376dc2cf303323b7e6c7734c2cb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 51446,
"upload_time": "2025-07-08T12:57:36",
"upload_time_iso_8601": "2025-07-08T12:57:36.614600Z",
"url": "https://files.pythonhosted.org/packages/e8/f1/7bc051a7ec9844ba4bc31dd8a9a2fa96546d36bb1f70587aecb456cef616/fedfred-2.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "37874e261dc472462552f894e7873a39a0500fb6d25d615cb4c3ade7dd4cf15b",
"md5": "4affee22d604e1451ad89ba42dd44479",
"sha256": "d117585bb287ea0b183f17df303989c674358293dcd937a34a8588258c68c209"
},
"downloads": -1,
"filename": "fedfred-2.1.1.tar.gz",
"has_sig": false,
"md5_digest": "4affee22d604e1451ad89ba42dd44479",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 50487,
"upload_time": "2025-07-08T12:57:37",
"upload_time_iso_8601": "2025-07-08T12:57:37.883772Z",
"url": "https://files.pythonhosted.org/packages/37/87/4e261dc472462552f894e7873a39a0500fb6d25d615cb4c3ade7dd4cf15b/fedfred-2.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-08 12:57:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nikhilxsunder",
"github_project": "fedfred",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "fedfred"
}
JSON
