flexreportfinance 0.1.0__tar.gz

flexreportfinance-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+dist/
+__pycache__/
+*.egg-info/
+.env

flexreportfinance-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Curt Beck
+
+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.

flexreportfinance-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.5
+Name: flexreportfinance
+Version: 0.1.0
+Summary: A Python client for Flexreport Finance's REST API, dedicated to the streaming of real-time stock updates and full-research reports.
+Project-URL: Repository, https://github.com/cbecks1212/flexreport-python-client
+Project-URL: Documentation, https://app.flexreportfinapi.com/api-docs
+Author-email: Curt Beck <curt@flexreportfinapi.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: tqdm>=4.70
+Description-Content-Type: text/markdown
+
+# Flexreport Finance
+
+Python client for the Flexreport Finance REST API. A username and password are required to use the client. If you do not have those, please create a free account at https://app.flexreportfinapi.com/register-api. For more information, please visit https://app.flexreportfinapi.com/ and https://app.flexreportfinapi.com/api-docs.
+
+## Quick Install
+
+```bash
+pip install flexreportfinance
+```
+
+## Quick example of real-time streaming
+
+```python
+from flexreportfinance import FlexreportClient
+
+with FlexreportClient("username", "password") as client:
+    for event_id, event in client.events.stream(symbols=["AAPL"]):
+        print(event_id, event)
+```
+
+`stream()` keeps the connection open and yields events as they arrive, so the loop runs until you break out of it. Live updates are not published on weekends.
+
+## Quick example of downloading the latest research for AAPL
+
+```python
+import base64
+from flexreportfinance import FlexreportClient
+
+with FlexreportClient("username", "password") as client:
+    report_data = client.reports.get(symbols=["AAPL"])
+
+for symbol, report in report_data["rendered"].items():
+    file_path = f"{symbol}_report.pdf"
+    with open(file_path, "wb") as f:
+        f.write(base64.b64decode(report["result"]["pdf"]))
+    print(f"{report['result']['headline']} -> saved to {file_path}")
+```
+
+## Downloading all of the latest reports from today
+
+```python
+import base64
+from datetime import date
+from flexreportfinance import FlexreportClient
+
+today = date.today().isoformat()  # YYYY-MM-DD
+with FlexreportClient("username", "password") as client:
+    report_plans = client.reports.available(report_date=today)
+    symbols = list(dict.fromkeys(plan["symbol"] for plan in report_plans))
+    if not symbols:
+        raise SystemExit(f"No reports for {today} (none are published on weekends).")
+    report_data = client.reports.get(symbols=symbols)
+
+for symbol, report in report_data["rendered"].items():
+    file_path = f"{symbol}_report.pdf"
+    with open(file_path, "wb") as f:
+        f.write(base64.b64decode(report["result"]["pdf"]))
+    print(f"{report['result']['headline']} -> saved to {file_path}")
+```
+
+The client logs in on the first authenticated call and logs in again if the token expires.

flexreportfinance-0.1.0/README.md

@@ -0,0 +1,61 @@
+# Flexreport Finance
+
+Python client for the Flexreport Finance REST API. A username and password are required to use the client. If you do not have those, please create a free account at https://app.flexreportfinapi.com/register-api. For more information, please visit https://app.flexreportfinapi.com/ and https://app.flexreportfinapi.com/api-docs.
+
+## Quick Install
+
+```bash
+pip install flexreportfinance
+```
+
+## Quick example of real-time streaming
+
+```python
+from flexreportfinance import FlexreportClient
+
+with FlexreportClient("username", "password") as client:
+    for event_id, event in client.events.stream(symbols=["AAPL"]):
+        print(event_id, event)
+```
+
+`stream()` keeps the connection open and yields events as they arrive, so the loop runs until you break out of it. Live updates are not published on weekends.
+
+## Quick example of downloading the latest research for AAPL
+
+```python
+import base64
+from flexreportfinance import FlexreportClient
+
+with FlexreportClient("username", "password") as client:
+    report_data = client.reports.get(symbols=["AAPL"])
+
+for symbol, report in report_data["rendered"].items():
+    file_path = f"{symbol}_report.pdf"
+    with open(file_path, "wb") as f:
+        f.write(base64.b64decode(report["result"]["pdf"]))
+    print(f"{report['result']['headline']} -> saved to {file_path}")
+```
+
+## Downloading all of the latest reports from today
+
+```python
+import base64
+from datetime import date
+from flexreportfinance import FlexreportClient
+
+today = date.today().isoformat()  # YYYY-MM-DD
+with FlexreportClient("username", "password") as client:
+    report_plans = client.reports.available(report_date=today)
+    symbols = list(dict.fromkeys(plan["symbol"] for plan in report_plans))
+    if not symbols:
+        raise SystemExit(f"No reports for {today} (none are published on weekends).")
+    report_data = client.reports.get(symbols=symbols)
+
+for symbol, report in report_data["rendered"].items():
+    file_path = f"{symbol}_report.pdf"
+    with open(file_path, "wb") as f:
+        f.write(base64.b64decode(report["result"]["pdf"]))
+    print(f"{report['result']['headline']} -> saved to {file_path}")
+```
+
+The client logs in on the first authenticated call and logs in again if the token expires.

flexreportfinance-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "flexreportfinance"
+version = "0.1.0"
+description = "A Python client for Flexreport Finance's REST API, dedicated to the streaming of real-time stock updates and full-research reports."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Curt Beck", email = "curt@flexreportfinapi.com" }]
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.28.0",
+    "tqdm>=4.70",
+]
+
+[project.urls]
+Repository = "https://github.com/cbecks1212/flexreport-python-client"
+Documentation = "https://app.flexreportfinapi.com/api-docs"

flexreportfinance-0.1.0/src/flexreportfinance/__init__.py

@@ -0,0 +1,3 @@
+from ._client import FlexreportClient
+
+__all__ = ["FlexreportClient"]

flexreportfinance-0.1.0/src/flexreportfinance/_client.py

@@ -0,0 +1,58 @@
+from typing import Any
+
+import httpx
+
+from .catalog import Catalog
+from .events import Events
+from .reports import Reports
+
+BASE_URL = "https://flexreportfinapi.com"
+
+
+class _TokenAuth(httpx.Auth):
+    """Adds the bearer token, fetching it on first use and again if the API answers 401."""
+
+    def __init__(self, client: "FlexreportClient"):
+        self._client = client
+        self._token: str | None = None
+
+    def auth_flow(self, request):
+        if self._token is None:
+            self._token = self._client._fetch_token()
+        request.headers["Authorization"] = f"Bearer {self._token}"
+        response = yield request
+
+        if response.status_code == 401:
+            self._token = self._client._fetch_token()
+            request.headers["Authorization"] = f"Bearer {self._token}"
+            yield request
+
+
+class FlexreportClient:
+    def __init__(self, username: str, password: str, base_url: str = BASE_URL, timeout: float = 30):
+        self._username = username
+        self._password = password
+        self._http = httpx.Client(base_url=base_url, timeout=timeout, auth=_TokenAuth(self))
+
+        self.catalog = Catalog(self)
+        self.reports = Reports(self)
+        self.events = Events(self)
+
+    def _fetch_token(self) -> str:
+        resp = self._http.post("/token", data={"username": self._username, "password": self._password}, auth=None)
+        resp.raise_for_status()
+        return resp.json()["access_token"]
+
+    def _json(self, method: str, url: str, **kwargs) -> Any:
+        resp = self._http.request(method, url, **kwargs)
+        resp.raise_for_status()
+        return resp.json()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "FlexreportClient":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()

flexreportfinance-0.1.0/src/flexreportfinance/catalog.py

@@ -0,0 +1,17 @@
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ._client import FlexreportClient
+
+
+class Catalog:
+    """Public reference data; these endpoints need no login."""
+
+    def __init__(self, client: "FlexreportClient"):
+        self._client = client
+
+    def symbols(self) -> Any:
+        return self._client._json("GET", "/list-tickers", auth=None)
+
+    def topics(self) -> Any:
+        return self._client._json("GET", "/list-realtime-event-options", auth=None)

flexreportfinance-0.1.0/src/flexreportfinance/events.py

@@ -0,0 +1,45 @@
+import json
+from collections.abc import Iterator
+from typing import TYPE_CHECKING
+
+import httpx
+
+if TYPE_CHECKING:
+    from ._client import FlexreportClient
+
+
+class Events:
+    def __init__(self, client: "FlexreportClient"):
+        self._client = client
+
+    def stream(
+        self,
+        topics: list[str] | None = None,
+        symbols: list[str] | None = None,
+        last_event_id: str | None = None,
+        read_timeout: float = 30,
+    ) -> Iterator[tuple[str | None, dict]]:
+        """Yield (event_id, event) from the server-sent event stream.
+
+        Pass the last event_id you saw as last_event_id to resume after a disconnect.
+        """
+        params = {k: v for k, v in {"topics": topics, "symbols": symbols}.items() if v is not None}
+        headers = {"Last-Event-ID": last_event_id} if last_event_id else {}
+
+        with self._client._http.stream(
+            "GET", "/events", params=params, headers=headers, timeout=httpx.Timeout(10, read=read_timeout)
+        ) as resp:
+            resp.raise_for_status()
+            frame: dict[str, str] = {}
+
+            for line in resp.iter_lines():
+                if line:
+                    if line.startswith(":"):
+                        continue
+                    key, _, value = line.partition(":")
+                    value = value.removeprefix(" ")
+                    frame[key] = f"{frame[key]}\n{value}" if key == "data" and key in frame else value
+                    continue
+                if frame.get("event") == "event" and "data" in frame:
+                    yield frame.get("id"), json.loads(frame["data"])
+                frame = {}

flexreportfinance-0.1.0/src/flexreportfinance/reports.py

@@ -0,0 +1,56 @@
+import time
+from typing import TYPE_CHECKING, Any
+
+from tqdm.auto import tqdm
+
+if TYPE_CHECKING:
+    from ._client import FlexreportClient
+
+TERMINAL = {"SUCCESS", "FAILURE", "REVOKED"}
+
+
+class Reports:
+    def __init__(self, client: "FlexreportClient"):
+        self._client = client
+
+    def available(self, report_date: str, event_types: list[str] | None = None) -> Any:
+        return self._client._json("POST", "/list-available-reports", json={"event_types": event_types, "report_date": report_date}, timeout=60)
+
+    def get(self, symbols: list[str], *, max_wait: float = 900, poll_every: float = 3.0, progress: bool = True) -> dict:
+        if not symbols:
+            raise ValueError("symbols must not be empty")
+
+        data = self._client._json("POST", "/get-cached-reports", json=symbols, timeout=900)
+        cached = data.get("result", [])
+        missing = data.get("missing", [])
+        rendering = data.get("rendering", {})  # {ticker: {"task_id", "status", "symbol"}}
+
+        total = len(cached) + len(missing) + len(rendering)
+        rendered, failed = {}, {}
+        with tqdm(total=total, desc="Reports", unit="sym", disable=not progress) as pbar:
+            pbar.update(len(cached) + len(missing))
+
+            pending = {t: v["task_id"] for t, v in rendering.items()}
+            deadline = time.monotonic() + max_wait
+
+            while pending and time.monotonic() < deadline:
+                for ticker, task_id in list(pending.items()):
+                    body = self._client._json("GET", "/task-status", params={"task_id": task_id})
+                    status = body.get("status")
+
+                    if status in TERMINAL:
+                        (rendered if status == "SUCCESS" else failed)[ticker] = body
+                        del pending[ticker]
+                        pbar.update(1)
+                    else:
+                        pbar.set_postfix_str(f"{ticker}: {status}")
+
+                if pending:
+                    time.sleep(poll_every)
+
+            if pending:
+                if progress:
+                    tqdm.write(f"Timed out waiting on: {sorted(pending)}")
+                failed.update({t: {"status": "TIMEOUT", "task_id": tid} for t, tid in pending.items()})
+
+        return {"cached": cached, "rendered": rendered, "missing": missing, "failed": failed}