financialmodelingprep-sdk 0.1.0__tar.gz

financialmodelingprep_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AakshRanjan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

financialmodelingprep_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: financialmodelingprep-sdk
+Version: 0.1.0
+Summary: Async Python SDK for the Financial Modeling Prep stable API.
+Keywords: fmp,financial-modeling-prep,finance,stocks,sdk
+Author: Aaksh Ranjan
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: aiohttp>=3.14.3
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: tenacity>=9.1.4
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/AakshRanjan/Finance-Intelligence-Graph
+Project-URL: Repository, https://github.com/AakshRanjan/Finance-Intelligence-Graph
+Project-URL: Issues, https://github.com/AakshRanjan/Finance-Intelligence-Graph/issues
+Project-URL: Changelog, https://github.com/AakshRanjan/Finance-Intelligence-Graph/blob/master/FMP-SDK/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# financialmodelingprep-sdk
+
+Async Python SDK for the [Financial Modeling Prep](https://site.financialmodelingprep.com/) stable API. Responses are validated with Pydantic; HTTP calls retry through a shared session.
+
+## Install
+
+```bash
+pip install financialmodelingprep-sdk
+```
+
+Requires Python 3.12+. You need an FMP API key.
+
+## Usage
+
+```python
+import asyncio
+
+from fmp_sdk import FMPSession
+
+
+async def main() -> None:
+    async with FMPSession("YOUR_API_KEY") as session:
+        bars = await session.chart("AAPL").historical_price_eod_light()
+        print(bars[0].date, bars[0].price)
+
+
+asyncio.run(main())
+```
+
+`FMPSession.chart(symbol)` binds a symbol so you do not pass it on every call. You can also pass `symbol=` per request.
+
+## Versioning
+
+Releases are cut automatically from Conventional Commits that touch this package:
+
+- `feat:` — minor
+- `fix:` / `perf:` — patch
+- `feat!:` or a `BREAKING CHANGE:` footer — major (stays 0.x until 1.0)
+
+See [CHANGELOG.md](CHANGELOG.md) for published versions.

financialmodelingprep_sdk-0.1.0/README.md

@@ -0,0 +1,40 @@
+# financialmodelingprep-sdk
+
+Async Python SDK for the [Financial Modeling Prep](https://site.financialmodelingprep.com/) stable API. Responses are validated with Pydantic; HTTP calls retry through a shared session.
+
+## Install
+
+```bash
+pip install financialmodelingprep-sdk
+```
+
+Requires Python 3.12+. You need an FMP API key.
+
+## Usage
+
+```python
+import asyncio
+
+from fmp_sdk import FMPSession
+
+
+async def main() -> None:
+    async with FMPSession("YOUR_API_KEY") as session:
+        bars = await session.chart("AAPL").historical_price_eod_light()
+        print(bars[0].date, bars[0].price)
+
+
+asyncio.run(main())
+```
+
+`FMPSession.chart(symbol)` binds a symbol so you do not pass it on every call. You can also pass `symbol=` per request.
+
+## Versioning
+
+Releases are cut automatically from Conventional Commits that touch this package:
+
+- `feat:` — minor
+- `fix:` / `perf:` — patch
+- `feat!:` or a `BREAKING CHANGE:` footer — major (stays 0.x until 1.0)
+
+See [CHANGELOG.md](CHANGELOG.md) for published versions.

financialmodelingprep_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[project]
+name = "financialmodelingprep-sdk"
+version = "0.1.0"
+description = "Async Python SDK for the Financial Modeling Prep stable API."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+keywords = [
+    "fmp",
+    "financial-modeling-prep",
+    "finance",
+    "stocks",
+    "sdk",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "aiohttp>=3.14.3",
+    "pydantic>=2.13.5",
+    "tenacity>=9.1.4",
+]
+
+[[project.authors]]
+name = "Aaksh Ranjan"
+
+[project.urls]
+Homepage = "https://github.com/AakshRanjan/Finance-Intelligence-Graph"
+Repository = "https://github.com/AakshRanjan/Finance-Intelligence-Graph"
+Issues = "https://github.com/AakshRanjan/Finance-Intelligence-Graph/issues"
+Changelog = "https://github.com/AakshRanjan/Finance-Intelligence-Graph/blob/master/FMP-SDK/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.9.10,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "fmp_sdk"
+
+[tool.semantic_release]
+commit_parser = "conventional-monorepo"
+version_toml = ["pyproject.toml:project.version"]
+tag_format = "fmp-sdk-v{version}"
+allow_zero_version = true
+major_on_zero = false
+assets = ["uv.lock"]
+commit_message = "chore(release): fmp-sdk@{version}"
+build_command = """
+pip install uv
+uv lock --upgrade-package "$PACKAGE_NAME"
+git add uv.lock
+uv build
+"""
+
+[tool.semantic_release.commit_parser_options]
+path_filters = ["."]
+
+[tool.semantic_release.changelog]
+mode = "update"
+insertion_flag = "<!-- version list -->"
+
+[tool.semantic_release.changelog.default_templates]
+changelog_file = "CHANGELOG.md"

financialmodelingprep_sdk-0.1.0/pyproject.toml.orig

@@ -0,0 +1,68 @@
+[project]
+name = "financialmodelingprep-sdk"
+version = "0.1.0"
+description = "Async Python SDK for the Financial Modeling Prep stable API."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Aaksh Ranjan" }]
+requires-python = ">=3.12"
+keywords = [
+    "fmp",
+    "financial-modeling-prep",
+    "finance",
+    "stocks",
+    "sdk",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "aiohttp>=3.14.3",
+    "pydantic>=2.13.5",
+    "tenacity>=9.1.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/AakshRanjan/Finance-Intelligence-Graph"
+Repository = "https://github.com/AakshRanjan/Finance-Intelligence-Graph"
+Issues = "https://github.com/AakshRanjan/Finance-Intelligence-Graph/issues"
+Changelog = "https://github.com/AakshRanjan/Finance-Intelligence-Graph/blob/master/FMP-SDK/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.9.10,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "fmp_sdk"
+
+[tool.semantic_release]
+commit_parser = "conventional-monorepo"
+version_toml = ["pyproject.toml:project.version"]
+tag_format = "fmp-sdk-v{version}"
+allow_zero_version = true
+major_on_zero = false
+assets = ["uv.lock"]
+commit_message = "chore(release): fmp-sdk@{version}"
+build_command = """
+pip install uv
+uv lock --upgrade-package "$PACKAGE_NAME"
+git add uv.lock
+uv build
+"""
+
+[tool.semantic_release.commit_parser_options]
+path_filters = ["."]
+
+[tool.semantic_release.changelog]
+mode = "update"
+insertion_flag = "<!-- version list -->"
+
+[tool.semantic_release.changelog.default_templates]
+changelog_file = "CHANGELOG.md"

financialmodelingprep_sdk-0.1.0/src/fmp_sdk/FMPSession.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any, TypeVar
+
+import aiohttp
+from fmp_sdk.exception import FMPResponseError, _RetryableHTTPError
+from fmp_sdk.utils.retrySession import RetrySession
+from pydantic import TypeAdapter, ValidationError
+
+if TYPE_CHECKING:
+    from fmp_sdk.chart.chart import Chart
+
+T = TypeVar("T")
+
+
+class FMPSession:
+    """Async Financial Modeling Prep client backed by RetrySession."""
+
+    BASE_URL = "https://financialmodelingprep.com/stable"
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = BASE_URL,
+        **retry_kwargs: Any,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._session = RetrySession(
+            headers={"apikey": api_key},
+            **retry_kwargs,
+        )
+
+    async def __aenter__(self) -> FMPSession:
+        await self._session.__aenter__()
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self._session.__aexit__(*exc)
+
+    async def close(self) -> None:
+        await self._session.close()
+
+    def chart(self, symbol: str | None = None) -> Chart:
+        from fmp_sdk.chart.chart import Chart
+
+        return Chart(self, symbol)
+
+    async def get(
+        self,
+        path: str,
+        *,
+        response_model: type[T],
+        **params: Any,
+    ) -> T:
+        """GET a stable API path and return a validated pydantic payload."""
+        url = f"{self._base_url}/{path.lstrip('/')}"
+        query = {key: value for key, value in params.items() if value is not None}
+        response = await self._session.get(url, params=query)
+        try:
+            response.raise_for_status()
+            data = await response.json()
+        finally:
+            response.release()
+        try:
+            return TypeAdapter(response_model).validate_python(data)
+        except ValidationError as exc:
+            raise FMPResponseError(path, exc) from exc
+
+    async def check_connectivity(self) -> bool:
+        """Return True if the FMP API is reachable and accepts the API key."""
+        url = f"{self._base_url}/search-symbol"
+        try:
+            response = await self._session.get(url, params={"query": "AAPL"})
+            try:
+                return response.status == 200
+            finally:
+                response.release()
+        except (
+            aiohttp.ClientError,
+            asyncio.TimeoutError,
+            _RetryableHTTPError,
+        ):
+            return False

financialmodelingprep_sdk-0.1.0/src/fmp_sdk/__init__.py

@@ -0,0 +1,27 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from fmp_sdk.FMPSession import FMPSession
+from fmp_sdk.chart import (
+    Chart,
+    HistoricalChartBar,
+    HistoricalPriceEodAdjusted,
+    HistoricalPriceEodFull,
+    HistoricalPriceEodLight,
+)
+from fmp_sdk.exception import FMPResponseError
+
+try:
+    __version__ = version("financialmodelingprep-sdk")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "Chart",
+    "FMPResponseError",
+    "FMPSession",
+    "HistoricalChartBar",
+    "HistoricalPriceEodAdjusted",
+    "HistoricalPriceEodFull",
+    "HistoricalPriceEodLight",
+    "__version__",
+]

financialmodelingprep_sdk-0.1.0/src/fmp_sdk/chart/__init__.py

@@ -0,0 +1,17 @@
+from fmp_sdk.chart.chart import Chart
+from fmp_sdk.chart.models import (
+    HistoricalChartBar,
+    HistoricalPriceEodAdjusted,
+    HistoricalPriceEodFull,
+    HistoricalPriceEodLight,
+)
+from fmp_sdk.exception import FMPResponseError
+
+__all__ = [
+    "Chart",
+    "FMPResponseError",
+    "HistoricalChartBar",
+    "HistoricalPriceEodAdjusted",
+    "HistoricalPriceEodFull",
+    "HistoricalPriceEodLight",
+]

financialmodelingprep_sdk-0.1.0/src/fmp_sdk/chart/chart.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from fmp_sdk.chart.models import (
+    HistoricalChartBar,
+    HistoricalPriceEodAdjusted,
+    HistoricalPriceEodFull,
+    HistoricalPriceEodLight,
+)
+
+if TYPE_CHECKING:
+    from fmp_sdk.FMPSession import FMPSession
+
+ChartInterval = Literal["1min", "5min", "15min", "30min", "1hour", "4hour"]
+
+
+def _normalize_symbol(symbol: str | None) -> str | None:
+    if symbol is None:
+        return None
+    normalized = symbol.strip().upper()
+    return normalized or None
+
+
+class Chart:
+    """FMP Charts endpoints for one optional bound symbol."""
+
+    def __init__(
+        self,
+        session: FMPSession,
+        symbol: str | None = None,
+    ) -> None:
+        self._session = session
+        self._symbol = _normalize_symbol(symbol)
+
+    def _resolve_symbol(self, symbol: str | None) -> str:
+        resolved = _normalize_symbol(symbol) or self._symbol
+        if resolved is None:
+            raise ValueError("symbol is required")
+        return resolved
+
+    def _query(
+        self,
+        symbol: str | None,
+        from_: str | None,
+        to: str | None,
+    ) -> dict[str, str | None]:
+        return {
+            "symbol": self._resolve_symbol(symbol),
+            "from": from_,
+            "to": to,
+        }
+
+    async def historical_price_eod_light(
+        self,
+        symbol: str | None = None,
+        *,
+        from_: str | None = None,
+        to: str | None = None,
+    ) -> list[HistoricalPriceEodLight]:
+        return await self._session.get(
+            "historical-price-eod/light",
+            response_model=list[HistoricalPriceEodLight],
+            **self._query(symbol, from_, to),
+        )
+
+    async def historical_price_eod_full(
+        self,
+        symbol: str | None = None,
+        *,
+        from_: str | None = None,
+        to: str | None = None,
+    ) -> list[HistoricalPriceEodFull]:
+        return await self._session.get(
+            "historical-price-eod/full",
+            response_model=list[HistoricalPriceEodFull],
+            **self._query(symbol, from_, to),
+        )
+
+    async def historical_price_eod_non_split_adjusted(
+        self,
+        symbol: str | None = None,
+        *,
+        from_: str | None = None,
+        to: str | None = None,
+    ) -> list[HistoricalPriceEodAdjusted]:
+        return await self._session.get(
+            "historical-price-eod/non-split-adjusted",
+            response_model=list[HistoricalPriceEodAdjusted],
+            **self._query(symbol, from_, to),
+        )
+
+    async def historical_price_eod_dividend_adjusted(
+        self,
+        symbol: str | None = None,
+        *,
+        from_: str | None = None,
+        to: str | None = None,
+    ) -> list[HistoricalPriceEodAdjusted]:
+        return await self._session.get(
+            "historical-price-eod/dividend-adjusted",
+            response_model=list[HistoricalPriceEodAdjusted],
+            **self._query(symbol, from_, to),
+        )
+
+    async def historical_chart(
+        self,
+        interval: ChartInterval,
+        symbol: str | None = None,
+        *,
+        from_: str | None = None,
+        to: str | None = None,
+    ) -> list[HistoricalChartBar]:
+        return await self._session.get(
+            f"historical-chart/{interval}",
+            response_model=list[HistoricalChartBar],
+            **self._query(symbol, from_, to),
+        )

financialmodelingprep_sdk-0.1.0/src/fmp_sdk/chart/models.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from datetime import date, datetime
+
+from pydantic import Field
+
+from fmp_sdk.models import FMPBaseModel
+
+
+class HistoricalPriceEodLight(FMPBaseModel):
+    """Row from GET /stable/historical-price-eod/light."""
+
+    symbol: str
+    date: date
+    price: float
+    volume: float
+
+
+class HistoricalPriceEodFull(FMPBaseModel):
+    """Row from GET /stable/historical-price-eod/full."""
+
+    symbol: str
+    date: date
+    open: float
+    high: float
+    low: float
+    close: float
+    volume: float
+    change: float
+    change_percent: float = Field(alias="changePercent")
+    vwap: float
+
+
+class HistoricalPriceEodAdjusted(FMPBaseModel):
+    """Row from non-split-adjusted and dividend-adjusted EOD endpoints."""
+
+    symbol: str
+    date: date
+    adj_open: float = Field(alias="adjOpen")
+    adj_high: float = Field(alias="adjHigh")
+    adj_low: float = Field(alias="adjLow")
+    adj_close: float = Field(alias="adjClose")
+    volume: float
+
+
+class HistoricalChartBar(FMPBaseModel):
+    """Row from GET /stable/historical-chart/{interval}."""
+
+    date: datetime
+    open: float
+    high: float
+    low: float
+    close: float
+    volume: float

financialmodelingprep_sdk-0.1.0/src/fmp_sdk/exception.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import aiohttp
+from pydantic import ValidationError
+
+
+class _RetryableHTTPError(Exception):
+    """Raised internally when an HTTP status should trigger a retry."""
+
+    def __init__(self, response: aiohttp.ClientResponse) -> None:
+        self.response = response
+        super().__init__(
+            f"Retryable HTTP {response.status} for {response.method} {response.url}"
+        )
+
+
+class FMPResponseError(Exception):
+    """Raised when an FMP JSON payload does not match the expected model."""
+
+    def __init__(self, path: str, error: ValidationError) -> None:
+        self.path = path
+        self.error = error
+        super().__init__(f"Invalid FMP response for {path}: {error}")

financialmodelingprep_sdk-0.1.0/src/fmp_sdk/models.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class FMPBaseModel(BaseModel):
+    """Shared pydantic config for FMP JSON payloads."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")

financialmodelingprep_sdk-0.1.0/src/fmp_sdk/utils/__init__.py

@@ -0,0 +1,3 @@
+from fmp_sdk.utils.retrySession import RetrySession
+
+__all__ = ["RetrySession"]

financialmodelingprep_sdk-0.1.0/src/fmp_sdk/utils/retrySession.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import aiohttp
+from fmp_sdk.exception import _RetryableHTTPError
+from tenacity import (
+    AsyncRetrying,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential,
+)
+
+
+class RetrySession:
+    """Thin aiohttp.ClientSession wrapper with tenacity retries."""
+
+    def __init__(
+        self,
+        *,
+        session: aiohttp.ClientSession | None = None,
+        max_attempts: int = 5,
+        retry_statuses: frozenset[int] = frozenset({429, 500, 502, 503, 504}),
+        wait_multiplier: float = 1.0,
+        wait_max: float = 60.0,
+        **session_kwargs: Any,
+    ) -> None:
+        self._external_session = session
+        self._session = session
+        self._session_kwargs = session_kwargs
+        self._owns_session = session is None
+        self._max_attempts = max_attempts
+        self._retry_statuses = retry_statuses
+        self._wait_multiplier = wait_multiplier
+        self._wait_max = wait_max
+
+    def _ensure_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession(**self._session_kwargs)
+            self._owns_session = True
+        return self._session
+
+    async def __aenter__(self) -> RetrySession:
+        self._ensure_session()
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        if (
+            self._owns_session
+            and self._session is not None
+            and not self._session.closed
+        ):
+            await self._session.close()
+            self._session = None
+
+    async def request(
+        self, method: str, url: str, **kwargs: Any
+    ) -> aiohttp.ClientResponse:
+        session = self._ensure_session()
+
+        try:
+            async for attempt in AsyncRetrying(
+                stop=stop_after_attempt(self._max_attempts),
+                wait=wait_exponential(
+                    multiplier=self._wait_multiplier,
+                    max=self._wait_max,
+                ),
+                retry=retry_if_exception_type(
+                    (
+                        aiohttp.ClientConnectionError,
+                        aiohttp.ServerTimeoutError,
+                        asyncio.TimeoutError,
+                        _RetryableHTTPError,
+                    )
+                ),
+                reraise=True,
+            ):
+                with attempt:
+                    response = await session.request(method, url, **kwargs)
+                    if response.status in self._retry_statuses:
+                        await response.read()
+                        response.release()
+                        raise _RetryableHTTPError(response)
+                    return response
+        except _RetryableHTTPError as exc:
+            response = exc.response
+            raise aiohttp.ClientResponseError(
+                request_info=response.request_info,
+                history=response.history,
+                status=response.status,
+                message=response.reason or "",
+                headers=response.headers,
+            ) from exc
+
+        raise RuntimeError(
+            "RetrySession.request completed without a response"
+        )  # pragma: no cover
+
+    async def get(self, url: str, **kwargs: Any) -> aiohttp.ClientResponse:
+        return await self.request("GET", url, **kwargs)
+
+    async def post(self, url: str, **kwargs: Any) -> aiohttp.ClientResponse:
+        return await self.request("POST", url, **kwargs)
+
+    async def patch(self, url: str, **kwargs: Any) -> aiohttp.ClientResponse:
+        return await self.request("PATCH", url, **kwargs)
+
+    async def delete(self, url: str, **kwargs: Any) -> aiohttp.ClientResponse:
+        return await self.request("DELETE", url, **kwargs)