marketstack-python-client 1.0.0__tar.gz

marketstack_python_client-1.0.0/LICENSE

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

marketstack_python_client-1.0.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+include openapi.yaml
+recursive-include marketstack *.py

marketstack_python_client-1.0.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: marketstack-python-client
+Version: 1.0.0
+Summary: A Python client for the Marketstack API.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.13.4
+Dynamic: license-file
+
+# Marketstack Python Client
+
+A modern, fully-typed Python client for the [Marketstack API (v2)](https://marketstack.com/). Built on top of `httpx` and `pydantic`, this client offers high performance, strict type validation, and an elegant fluent API interface.
+
+---
+
+## Features
+
+- **Modern Python Support:** Optimized for Python `>= 3.10`.
+- **Fully Typed Requests & Responses:** Leverages Pydantic v2 and PEP 692 `Unpack` for complete autocomplete, editor hints, and runtime validation.
+- **Fluent & Hierarchical API:** Easily access nested endpoints (e.g., `client.tickers("AAPL").eod.list()`).
+- **Comprehensive Coverage:** Supports 25+ namespaces covering end-of-day (EOD) data, intraday, tickers, stock exchanges, stock splits, dividends, ETFs, indices, currencies, bonds, commodities, company fundamentals, and more.
+
+---
+
+## Installation
+
+Install the package via `pip`:
+
+```bash
+pip install marketstack-python-client
+```
+
+Or using `uv`:
+
+```bash
+uv add marketstack-python-client
+```
+
+---
+
+## Quick Start
+
+To use the client, you will need a Marketstack API key. Get one by registering at [marketstack.com](https://marketstack.com/).
+
+```python
+import os
+from marketstack import Marketstack
+
+# Initialize the client with your access key
+client = Marketstack(api_key=os.environ["MARKETSTACK_API_KEY"])
+
+# 1. Fetch generic End-of-Day (EOD) stock data
+eod_data = client.eod.list(symbols="AAPL,MSFT")
+for bar in eod_data.data:
+    print(f"{bar.symbol} closed at {bar.close} on {bar.date}")
+
+# 2. Access Ticker-specific data using the fluent API
+aapl_ticker = client.tickers("AAPL").get()
+print(f"Name: {aapl_ticker.name}, Stock Exchange: {aapl_ticker.stock_exchange.name}")
+
+# Fetch EOD prices specifically for AAPL
+aapl_eod = client.tickers("AAPL").eod.list(limit=10)
+for bar in aapl_eod.data:
+    print(f"AAPL Close: {bar.close}")
+
+# 3. Access Stock Exchange specific tickers and EOD data
+nasdaq_eod = client.exchanges("XNAS").eod.list(symbols="AAPL", limit=5)
+print(f"Fetched {len(nasdaq_eod.data)} records from NASDAQ")
+```
+
+---
+
+## Client Namespaces & API Coverage
+
+The `Marketstack` client provides dedicated namespaces mapping to the various endpoints of the Marketstack API.
+
+### 1. Tickers (Fluent API)
+Interact with a specific ticker symbol.
+```python
+ticker = client.tickers("AAPL")
+
+ticker.get()                      # Basic ticker information
+ticker.eod.list()                 # End-of-Day historical data
+ticker.eod.latest()               # Latest End-of-Day bar
+ticker.eod.for_a_date("2023-10-27") # End-of-Day bar for a specific date
+ticker.intraday.list()            # Intraday / Real-time data
+ticker.intraday.latest()          # Latest intraday data
+ticker.intraday.for_a_date("2023-10-27")
+ticker.splits.list()              # Split history
+ticker.dividends.list()           # Dividend history
+```
+
+### 2. Stock Exchanges (Fluent API)
+Interact with stock exchanges.
+```python
+exchange = client.exchanges("XNAS")
+
+exchange.get()                    # Basic exchange info
+exchange.tickers.list()           # All tickers listed on this exchange
+exchange.eod.list(symbols="AAPL") # EOD data for a ticker on this exchange
+exchange.intraday.list(symbols="AAPL") # Intraday data for a ticker on this exchange
+```
+
+### 3. End-of-Day (EOD) & Intraday Market Data
+Retrieve general EOD and Intraday datasets.
+```python
+# General EOD endpoints
+client.eod.list(symbols="AAPL", date_from="2023-01-01")
+client.eod.latest(symbols="AAPL")
+client.eod.for_a_date(date="2023-10-27", symbols="AAPL")
+
+# General Intraday endpoints
+client.intraday.list(symbols="AAPL")
+client.intraday.latest(symbols="AAPL")
+client.intraday.for_a_date(date="2023-10-27", symbols="AAPL")
+```
+
+### 4. Other Specialized Namespaces
+The client supports many other endpoints depending on your Marketstack subscription tier:
+
+- **Dividends & Splits:**
+  - `client.dividends.list(symbols="AAPL")`
+  - `client.splits.list(symbols="AAPL")`
+- **Currencies & Timezones:**
+  - `client.currencies.list()`
+  - `client.timezones.list()`
+- **Bonds & Index Info:**
+  - `client.bondlist.list(country="US")`
+  - `client.bond.get(country="US")`
+  - `client.indexlist.list()`
+  - `client.indexinfo.get(index="SPX")`
+- **ETFs:**
+  - `client.etflist.list(ticker="SPY")`
+  - `client.etfholdings.get(ticker="PRSVX")`
+- **Company Fundamentals (Requires Enterprise/Tier Plan):**
+  - `client.company_facts.get(cik_code="0000320193")`
+  - `client.companyname.get(cik_code="0000320193")`
+  - `client.companyratings.get(ticker="AAPL")`
+  - `client.concept.get_accounts_payable(cik_code="0000320193")`
+
+---
+
+## Development
+
+We use `uv` for dependency management and workspace workflows.
+
+### Prerequisites
+
+- Python 3.10 or higher
+- `uv` package manager
+
+### Setup
+
+Clone the repository and install the dependencies:
+
+```bash
+uv sync
+```
+
+### Running Tests
+
+This project uses `pytest` for unit and integration testing.
+
+```bash
+# Run all unit tests
+uv run pytest -v
+```
+
+To run the integration tests against the live Marketstack API, make sure to set the `MARKETSTACK_API_KEY` environment variable in your `.env` or current session. Note that some tests require higher-tier plans and are marked to be skipped if your API key lacks access.
+
+```bash
+export MARKETSTACK_API_KEY="your_api_key_here"
+uv run pytest tests/test_integration.py
+```
+
+---
+
+## License
+
+This project is licensed under the MIT License. See individual files or package settings for more details.

marketstack_python_client-1.0.0/README.md

@@ -0,0 +1,171 @@
+# Marketstack Python Client
+
+A modern, fully-typed Python client for the [Marketstack API (v2)](https://marketstack.com/). Built on top of `httpx` and `pydantic`, this client offers high performance, strict type validation, and an elegant fluent API interface.
+
+---
+
+## Features
+
+- **Modern Python Support:** Optimized for Python `>= 3.10`.
+- **Fully Typed Requests & Responses:** Leverages Pydantic v2 and PEP 692 `Unpack` for complete autocomplete, editor hints, and runtime validation.
+- **Fluent & Hierarchical API:** Easily access nested endpoints (e.g., `client.tickers("AAPL").eod.list()`).
+- **Comprehensive Coverage:** Supports 25+ namespaces covering end-of-day (EOD) data, intraday, tickers, stock exchanges, stock splits, dividends, ETFs, indices, currencies, bonds, commodities, company fundamentals, and more.
+
+---
+
+## Installation
+
+Install the package via `pip`:
+
+```bash
+pip install marketstack-python-client
+```
+
+Or using `uv`:
+
+```bash
+uv add marketstack-python-client
+```
+
+---
+
+## Quick Start
+
+To use the client, you will need a Marketstack API key. Get one by registering at [marketstack.com](https://marketstack.com/).
+
+```python
+import os
+from marketstack import Marketstack
+
+# Initialize the client with your access key
+client = Marketstack(api_key=os.environ["MARKETSTACK_API_KEY"])
+
+# 1. Fetch generic End-of-Day (EOD) stock data
+eod_data = client.eod.list(symbols="AAPL,MSFT")
+for bar in eod_data.data:
+    print(f"{bar.symbol} closed at {bar.close} on {bar.date}")
+
+# 2. Access Ticker-specific data using the fluent API
+aapl_ticker = client.tickers("AAPL").get()
+print(f"Name: {aapl_ticker.name}, Stock Exchange: {aapl_ticker.stock_exchange.name}")
+
+# Fetch EOD prices specifically for AAPL
+aapl_eod = client.tickers("AAPL").eod.list(limit=10)
+for bar in aapl_eod.data:
+    print(f"AAPL Close: {bar.close}")
+
+# 3. Access Stock Exchange specific tickers and EOD data
+nasdaq_eod = client.exchanges("XNAS").eod.list(symbols="AAPL", limit=5)
+print(f"Fetched {len(nasdaq_eod.data)} records from NASDAQ")
+```
+
+---
+
+## Client Namespaces & API Coverage
+
+The `Marketstack` client provides dedicated namespaces mapping to the various endpoints of the Marketstack API.
+
+### 1. Tickers (Fluent API)
+Interact with a specific ticker symbol.
+```python
+ticker = client.tickers("AAPL")
+
+ticker.get()                      # Basic ticker information
+ticker.eod.list()                 # End-of-Day historical data
+ticker.eod.latest()               # Latest End-of-Day bar
+ticker.eod.for_a_date("2023-10-27") # End-of-Day bar for a specific date
+ticker.intraday.list()            # Intraday / Real-time data
+ticker.intraday.latest()          # Latest intraday data
+ticker.intraday.for_a_date("2023-10-27")
+ticker.splits.list()              # Split history
+ticker.dividends.list()           # Dividend history
+```
+
+### 2. Stock Exchanges (Fluent API)
+Interact with stock exchanges.
+```python
+exchange = client.exchanges("XNAS")
+
+exchange.get()                    # Basic exchange info
+exchange.tickers.list()           # All tickers listed on this exchange
+exchange.eod.list(symbols="AAPL") # EOD data for a ticker on this exchange
+exchange.intraday.list(symbols="AAPL") # Intraday data for a ticker on this exchange
+```
+
+### 3. End-of-Day (EOD) & Intraday Market Data
+Retrieve general EOD and Intraday datasets.
+```python
+# General EOD endpoints
+client.eod.list(symbols="AAPL", date_from="2023-01-01")
+client.eod.latest(symbols="AAPL")
+client.eod.for_a_date(date="2023-10-27", symbols="AAPL")
+
+# General Intraday endpoints
+client.intraday.list(symbols="AAPL")
+client.intraday.latest(symbols="AAPL")
+client.intraday.for_a_date(date="2023-10-27", symbols="AAPL")
+```
+
+### 4. Other Specialized Namespaces
+The client supports many other endpoints depending on your Marketstack subscription tier:
+
+- **Dividends & Splits:**
+  - `client.dividends.list(symbols="AAPL")`
+  - `client.splits.list(symbols="AAPL")`
+- **Currencies & Timezones:**
+  - `client.currencies.list()`
+  - `client.timezones.list()`
+- **Bonds & Index Info:**
+  - `client.bondlist.list(country="US")`
+  - `client.bond.get(country="US")`
+  - `client.indexlist.list()`
+  - `client.indexinfo.get(index="SPX")`
+- **ETFs:**
+  - `client.etflist.list(ticker="SPY")`
+  - `client.etfholdings.get(ticker="PRSVX")`
+- **Company Fundamentals (Requires Enterprise/Tier Plan):**
+  - `client.company_facts.get(cik_code="0000320193")`
+  - `client.companyname.get(cik_code="0000320193")`
+  - `client.companyratings.get(ticker="AAPL")`
+  - `client.concept.get_accounts_payable(cik_code="0000320193")`
+
+---
+
+## Development
+
+We use `uv` for dependency management and workspace workflows.
+
+### Prerequisites
+
+- Python 3.10 or higher
+- `uv` package manager
+
+### Setup
+
+Clone the repository and install the dependencies:
+
+```bash
+uv sync
+```
+
+### Running Tests
+
+This project uses `pytest` for unit and integration testing.
+
+```bash
+# Run all unit tests
+uv run pytest -v
+```
+
+To run the integration tests against the live Marketstack API, make sure to set the `MARKETSTACK_API_KEY` environment variable in your `.env` or current session. Note that some tests require higher-tier plans and are marked to be skipped if your API key lacks access.
+
+```bash
+export MARKETSTACK_API_KEY="your_api_key_here"
+uv run pytest tests/test_integration.py
+```
+
+---
+
+## License
+
+This project is licensed under the MIT License. See individual files or package settings for more details.

marketstack_python_client-1.0.0/marketstack/__init__.py

@@ -0,0 +1 @@
+from .client.marketstack import Marketstack

marketstack_python_client-1.0.0/marketstack/client/http.py

@@ -0,0 +1,36 @@
+import httpx
+
+
+class HTTPClient:
+    def __init__(self, base_url: str, params: dict = None):
+        self.base_url = base_url
+        self.params = params or {}
+
+    def get(self, endpoint: str, params: dict = None):
+        merged_params = {**self.params}
+        if params:
+            cleaned_params = {k: v for k, v in params.items() if v is not None}
+            merged_params.update(cleaned_params)
+        with httpx.Client(base_url=self.base_url, timeout=30.0) as client:
+            response = client.get(endpoint, params=merged_params)
+            response.raise_for_status()
+            data = response.json()
+            if isinstance(data, dict):
+                if "error" in data:
+                    err = data["error"]
+                    err_msg = err.get("message", "Unknown error") if isinstance(err, dict) else str(err)
+                    err_code = err.get("code", "unknown") if isinstance(err, dict) else "unknown"
+                    raise httpx.HTTPStatusError(
+                        message=f"API Error ({err_code}): {err_msg}",
+                        request=response.request,
+                        response=response,
+                    )
+                if data.get("message") == "error":
+                    err_msg = data.get("details", "Unknown error")
+                    err_code = data.get("code", "unknown")
+                    raise httpx.HTTPStatusError(
+                        message=f"API Error ({err_code}): {err_msg}",
+                        request=response.request,
+                        response=response,
+                    )
+            return data

marketstack_python_client-1.0.0/marketstack/client/marketstack.py

@@ -0,0 +1,148 @@
+from marketstack.client.http import HTTPClient
+from marketstack.namespaces.bond import Bond
+from marketstack.namespaces.bondlist import BondList
+from marketstack.namespaces.cikcode import CIKCode
+from marketstack.namespaces.commodities import Commodities
+from marketstack.namespaces.commoditieshistory import CommoditiesHistory
+from marketstack.namespaces.company_facts import CompanyFacts
+from marketstack.namespaces.companyname import CompanyName
+from marketstack.namespaces.companyratings import CompanyRatings
+from marketstack.namespaces.concept import Concept
+from marketstack.namespaces.currencies import Currencies
+from marketstack.namespaces.dividends import Dividends
+from marketstack.namespaces.eod import EOD
+from marketstack.namespaces.etfholdings import ETFHoldings
+from marketstack.namespaces.etflist import ETFList
+from marketstack.namespaces.exchanges import Exchanges
+from marketstack.namespaces.frames import Frames
+from marketstack.namespaces.indexinfo import IndexInfo
+from marketstack.namespaces.indexlist import IndexList
+from marketstack.namespaces.intraday import Intraday
+from marketstack.namespaces.splits import Splits
+from marketstack.namespaces.stockprice import StockPrice
+from marketstack.namespaces.submissions import Submissions
+from marketstack.namespaces.tickerinfo import TickerInfo
+from marketstack.namespaces.tickers import Tickers
+from marketstack.namespaces.tickerslist import TickersList
+from marketstack.namespaces.timezones import Timezones
+
+
+class Marketstack:
+    """
+    The marketstack API was built to deliver worldwide stock market data
+    (real-time, intraday and historical), together with information on stock
+    exchanges, tickers, indices, ETFs, bonds, commodities and company
+    fundamentals, in a simple, lightweight JSON format. Requests to the REST API
+    are made using a straightforward HTTP GET URL structure. This documentation
+    covers the v2 API surface.
+    """
+
+    def __init__(self, api_key: str):
+        self.http_client = HTTPClient(
+            base_url="https://api.marketstack.com",
+            params={"access_key": api_key},
+        )
+
+    @property
+    def bond(self) -> Bond:
+        return Bond(http_client=self.http_client)
+
+    @property
+    def bondlist(self) -> BondList:
+        return BondList(http_client=self.http_client)
+
+    @property
+    def cikcode(self) -> CIKCode:
+        return CIKCode(http_client=self.http_client)
+
+    @property
+    def commodities(self) -> Commodities:
+        return Commodities(http_client=self.http_client)
+
+    @property
+    def commoditieshistory(self) -> CommoditiesHistory:
+        return CommoditiesHistory(http_client=self.http_client)
+
+    @property
+    def company_facts(self) -> CompanyFacts:
+        return CompanyFacts(http_client=self.http_client)
+
+    @property
+    def companyname(self) -> CompanyName:
+        return CompanyName(http_client=self.http_client)
+
+    @property
+    def companyratings(self) -> CompanyRatings:
+        return CompanyRatings(http_client=self.http_client)
+
+    @property
+    def concept(self) -> Concept:
+        return Concept(http_client=self.http_client)
+
+    @property
+    def currencies(self) -> Currencies:
+        return Currencies(http_client=self.http_client)
+
+    @property
+    def dividends(self) -> Dividends:
+        return Dividends(http_client=self.http_client)
+
+    @property
+    def eod(self) -> EOD:
+        return EOD(http_client=self.http_client)
+
+    @property
+    def etfholdings(self) -> ETFHoldings:
+        return ETFHoldings(http_client=self.http_client)
+
+    @property
+    def etflist(self) -> ETFList:
+        return ETFList(http_client=self.http_client)
+
+    @property
+    def exchanges(self) -> Exchanges:
+        return Exchanges(http_client=self.http_client)
+
+    @property
+    def frames(self) -> Frames:
+        return Frames(http_client=self.http_client)
+
+    @property
+    def indexinfo(self) -> IndexInfo:
+        return IndexInfo(http_client=self.http_client)
+
+    @property
+    def indexlist(self) -> IndexList:
+        return IndexList(http_client=self.http_client)
+
+    @property
+    def intraday(self) -> Intraday:
+        return Intraday(http_client=self.http_client)
+
+    @property
+    def splits(self) -> Splits:
+        return Splits(http_client=self.http_client)
+
+    @property
+    def stockprice(self) -> StockPrice:
+        return StockPrice(http_client=self.http_client)
+
+    @property
+    def submissions(self) -> Submissions:
+        return Submissions(http_client=self.http_client)
+
+    @property
+    def tickerinfo(self) -> TickerInfo:
+        return TickerInfo(http_client=self.http_client)
+
+    @property
+    def tickers(self) -> Tickers:
+        return Tickers(http_client=self.http_client)
+
+    @property
+    def tickerslist(self) -> TickersList:
+        return TickersList(http_client=self.http_client)
+
+    @property
+    def timezones(self) -> Timezones:
+        return Timezones(http_client=self.http_client)

marketstack_python_client-1.0.0/marketstack/models/bond.py

@@ -0,0 +1,47 @@
+from pydantic import BaseModel, Field
+from typing import Union
+from types import NoneType
+from .pagination import Pagniation, PaginationRequest
+from typing import TypedDict
+
+
+class BondRequest(TypedDict, total=False):
+    country: Union[NoneType, str] = None
+    """Filter bonds by country."""
+
+class BondListRequest(PaginationRequest, total=False):
+    country: Union[NoneType, str] = None
+    """Filter bond list by country."""
+
+class BondInfoItem(BaseModel):
+    region: str
+    """Region where the bond is supported."""
+    country: str
+    """Country where the bond is supported."""
+    type: str
+    """Bond tenor/type (for example 10Y)."""
+    yield_: str = Field(..., alias="yield")
+    """Current bond yield."""
+    price_change_day: str
+    """Price change day-over-day."""
+    percentage_week: str
+    """Weekly change percentage."""
+    percentage_month: str
+    """Monthly change percentage."""
+    percentage_year: str
+    """Yearly change percentage."""
+    date: str
+    """Quote date."""
+    model_config = {"populate_by_name": True}
+
+class BondInfoResponse(BaseModel):
+    pagination: Pagniation
+    data: list["BondInfoItem"]
+
+class BondListItem(BaseModel):
+    country: str
+    """Country supported for bonds."""
+
+class BondListResponse(BaseModel):
+    pagination: Pagniation
+    data: list["BondListItem"]

marketstack_python_client-1.0.0/marketstack/models/cik_code.py

@@ -0,0 +1,26 @@
+from pydantic import BaseModel
+from typing import Union
+from types import NoneType
+from .pagination import Pagniation, PaginationRequest
+from typing import TypedDict
+
+
+class CIKCodeRequest(PaginationRequest, total=False):
+    company_name: Union[NoneType, str] = None
+    """Search by company name."""
+
+class CIKItem(BaseModel):
+    cik_code: str
+    """Company CIK code."""
+    company_name: str
+    """Company name."""
+    ein: str
+    """Employer Identification Number."""
+    sic: str
+    """Standard Industrial Classification."""
+    sic_description: str
+    """SIC description."""
+
+class CIKSearchResponse(BaseModel):
+    pagination: Pagniation
+    data: list["CIKItem"]