Signal8 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,4 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.egg-info/
4
+ .pytest_cache/
signal8-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Signal8 Inc.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
signal8-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,149 @@
1
+ Metadata-Version: 2.5
2
+ Name: signal8
3
+ Version: 0.1.0
4
+ Summary: Python client for the Signal8 API: SEC filings, insider and Congress trades, 13F holdings and dilution data for US stocks.
5
+ Project-URL: Homepage, https://signal8.ai
6
+ Project-URL: Documentation, https://signal8.ai/developer
7
+ Project-URL: API keys, https://signal8.ai/developer/api-keys
8
+ Project-URL: MCP server, https://signal8.ai/mcp
9
+ Author-email: Signal8 <business@signal8.ai>
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: 13f,api,dilution,edgar,filings,finance,insider trading,sec,stocks
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Intended Audience :: Financial and Insurance Industry
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Topic :: Office/Business :: Financial :: Investment
19
+ Classifier: Typing :: Typed
20
+ Requires-Python: >=3.9
21
+ Requires-Dist: requests>=2.28
22
+ Provides-Extra: test
23
+ Requires-Dist: pytest>=7; extra == 'test'
24
+ Requires-Dist: responses>=0.23; extra == 'test'
25
+ Description-Content-Type: text/markdown
26
+
27
+ # signal8
28
+
29
+ Python client for the [Signal8](https://signal8.ai) API: SEC filings and full-text search,
30
+ Form 4 insider trades, 13F institutional holdings, trades by members of Congress and
31
+ executive-branch officials, quotes, and dilution data (warrants, convertibles, shelves, ATMs,
32
+ equity lines, cash runway) for US-listed stocks.
33
+
34
+ A thin wrapper over the documented REST API. Every method returns the parsed JSON body
35
+ unchanged, so field names match the API reference at
36
+ [signal8.ai/developer](https://signal8.ai/developer).
37
+
38
+ ## Install
39
+
40
+ ```bash
41
+ pip install signal8
42
+ ```
43
+
44
+ Python 3.9 or newer. The only dependency is `requests`.
45
+
46
+ ## API key
47
+
48
+ API access is part of Signal8 Pro (120 requests a minute, 10,000 a day, up to 3 keys). Create
49
+ a key at [signal8.ai/developer/api-keys](https://signal8.ai/developer/api-keys). Test keys
50
+ (`sk_test_...`) return real data at 10 requests a minute and are useful while you integrate.
51
+
52
+ ```bash
53
+ export SIGNAL8_API_KEY=sk_live_your_key_here
54
+ ```
55
+
56
+ ## Usage
57
+
58
+ ```python
59
+ from signal8 import Signal8, Signal8Error
60
+
61
+ s8 = Signal8() # reads SIGNAL8_API_KEY, or Signal8(api_key="sk_live_...")
62
+
63
+ # Companies
64
+ s8.search_companies("co-diagnostics", limit=5)
65
+ s8.company("CODX") # also accepts a former ticker or a CIK
66
+ s8.quote("AAPL")
67
+ s8.quotes(["AAPL", "MSFT"]) # up to 500 tickers in one call
68
+ s8.split_history("AAPL")
69
+
70
+ # Insiders and institutions
71
+ s8.insider_transactions("AAPL", year=2026, transaction_code="P")
72
+ s8.insider_cluster_buys("AAPL")
73
+ s8.institutions("AAPL")
74
+ s8.institution_holdings(1067983, limit=20)
75
+
76
+ # Dilution: check coverage first, it is the cheap call
77
+ cov = s8.dilution_coverage("AZTR")
78
+ risk = s8.dilution_risk("AZTR")
79
+ warrants = s8.dilution_instruments("AZTR", "warrants")
80
+ cash = s8.cash_position("AZTR")
81
+
82
+ # Filings
83
+ s8.edgar_filings(formTypes="8-K", dateFrom="2026-11-01", pageSize=25)
84
+ s8.edgar_search_text("going concern", formType="10-Q", limit=10)
85
+ s8.accession("0001193125-26-458624")
86
+
87
+ # Market and Congress
88
+ s8.movers("gainers", session="premarket", market_cap_max=300_000_000)
89
+ s8.trading_halts()
90
+ s8.congress_trades_by_ticker("NVDA", days=90)
91
+
92
+ # Anything else in the API reference
93
+ s8.get("/calendar/earnings", **{"from": "2026-11-23", "to": "2026-11-27"})
94
+ ```
95
+
96
+ ### Errors
97
+
98
+ Non-2xx responses raise `Signal8Error` with the API's error code:
99
+
100
+ ```python
101
+ try:
102
+ s8.dilution_risk("AZTR")
103
+ except Signal8Error as e:
104
+ print(e.status, e.code, e) # e.g. 403 FEATURE_NOT_AVAILABLE ...
105
+ ```
106
+
107
+ 429 and 502/503/504 responses are retried (`max_retries=2` by default, honouring
108
+ `Retry-After`).
109
+
110
+ ### Usage headers
111
+
112
+ After each call, `s8.rate_limit` holds the rate-limit, daily-allowance and credit headers from
113
+ the last response:
114
+
115
+ ```python
116
+ s8.quote("AAPL")
117
+ print(s8.rate_limit.remaining, s8.rate_limit.daily_remaining)
118
+ ```
119
+
120
+ ### Reading the data
121
+
122
+ The API reports a value it could not measure as missing (null or `available: false` with a
123
+ reason), never as zero. A company without a dilution analysis returns `not_covered`, which is
124
+ not the same as having no dilution. This client passes those responses through unchanged.
125
+
126
+ ## Related
127
+
128
+ - MCP server for Claude, ChatGPT, Cursor and other MCP clients: [signal8.ai/mcp](https://signal8.ai/mcp)
129
+ - Free CC BY 4.0 datasets (reverse splits, listing deficiency notices): [signal8.ai/datasets](https://signal8.ai/datasets)
130
+
131
+ ## Licence
132
+
133
+ MIT. Use of the API is subject to the [Signal8 Terms](https://signal8.ai/terms). Nothing
134
+ returned by the API is investment advice.
135
+
136
+ ## Maintainer notes: publishing
137
+
138
+ Not yet on PyPI. To publish (from this directory, with a PyPI API token for the `signal8`
139
+ project; the name was unclaimed on 2026-11-20):
140
+
141
+ ```bash
142
+ python -m pip install --upgrade build twine
143
+ rm -rf dist && python -m build # dist/signal8-0.1.0.tar.gz + .whl
144
+ python -m twine check dist/*
145
+ python -m twine upload --repository testpypi dist/* # optional dry run on test.pypi.org
146
+ python -m twine upload dist/* # username __token__, password = PyPI token
147
+ ```
148
+
149
+ Bump `version` in `pyproject.toml` and `__version__` in `src/signal8/__init__.py` together.
@@ -0,0 +1,123 @@
1
+ # signal8
2
+
3
+ Python client for the [Signal8](https://signal8.ai) API: SEC filings and full-text search,
4
+ Form 4 insider trades, 13F institutional holdings, trades by members of Congress and
5
+ executive-branch officials, quotes, and dilution data (warrants, convertibles, shelves, ATMs,
6
+ equity lines, cash runway) for US-listed stocks.
7
+
8
+ A thin wrapper over the documented REST API. Every method returns the parsed JSON body
9
+ unchanged, so field names match the API reference at
10
+ [signal8.ai/developer](https://signal8.ai/developer).
11
+
12
+ ## Install
13
+
14
+ ```bash
15
+ pip install signal8
16
+ ```
17
+
18
+ Python 3.9 or newer. The only dependency is `requests`.
19
+
20
+ ## API key
21
+
22
+ API access is part of Signal8 Pro (120 requests a minute, 10,000 a day, up to 3 keys). Create
23
+ a key at [signal8.ai/developer/api-keys](https://signal8.ai/developer/api-keys). Test keys
24
+ (`sk_test_...`) return real data at 10 requests a minute and are useful while you integrate.
25
+
26
+ ```bash
27
+ export SIGNAL8_API_KEY=sk_live_your_key_here
28
+ ```
29
+
30
+ ## Usage
31
+
32
+ ```python
33
+ from signal8 import Signal8, Signal8Error
34
+
35
+ s8 = Signal8() # reads SIGNAL8_API_KEY, or Signal8(api_key="sk_live_...")
36
+
37
+ # Companies
38
+ s8.search_companies("co-diagnostics", limit=5)
39
+ s8.company("CODX") # also accepts a former ticker or a CIK
40
+ s8.quote("AAPL")
41
+ s8.quotes(["AAPL", "MSFT"]) # up to 500 tickers in one call
42
+ s8.split_history("AAPL")
43
+
44
+ # Insiders and institutions
45
+ s8.insider_transactions("AAPL", year=2026, transaction_code="P")
46
+ s8.insider_cluster_buys("AAPL")
47
+ s8.institutions("AAPL")
48
+ s8.institution_holdings(1067983, limit=20)
49
+
50
+ # Dilution: check coverage first, it is the cheap call
51
+ cov = s8.dilution_coverage("AZTR")
52
+ risk = s8.dilution_risk("AZTR")
53
+ warrants = s8.dilution_instruments("AZTR", "warrants")
54
+ cash = s8.cash_position("AZTR")
55
+
56
+ # Filings
57
+ s8.edgar_filings(formTypes="8-K", dateFrom="2026-11-01", pageSize=25)
58
+ s8.edgar_search_text("going concern", formType="10-Q", limit=10)
59
+ s8.accession("0001193125-26-458624")
60
+
61
+ # Market and Congress
62
+ s8.movers("gainers", session="premarket", market_cap_max=300_000_000)
63
+ s8.trading_halts()
64
+ s8.congress_trades_by_ticker("NVDA", days=90)
65
+
66
+ # Anything else in the API reference
67
+ s8.get("/calendar/earnings", **{"from": "2026-11-23", "to": "2026-11-27"})
68
+ ```
69
+
70
+ ### Errors
71
+
72
+ Non-2xx responses raise `Signal8Error` with the API's error code:
73
+
74
+ ```python
75
+ try:
76
+ s8.dilution_risk("AZTR")
77
+ except Signal8Error as e:
78
+ print(e.status, e.code, e) # e.g. 403 FEATURE_NOT_AVAILABLE ...
79
+ ```
80
+
81
+ 429 and 502/503/504 responses are retried (`max_retries=2` by default, honouring
82
+ `Retry-After`).
83
+
84
+ ### Usage headers
85
+
86
+ After each call, `s8.rate_limit` holds the rate-limit, daily-allowance and credit headers from
87
+ the last response:
88
+
89
+ ```python
90
+ s8.quote("AAPL")
91
+ print(s8.rate_limit.remaining, s8.rate_limit.daily_remaining)
92
+ ```
93
+
94
+ ### Reading the data
95
+
96
+ The API reports a value it could not measure as missing (null or `available: false` with a
97
+ reason), never as zero. A company without a dilution analysis returns `not_covered`, which is
98
+ not the same as having no dilution. This client passes those responses through unchanged.
99
+
100
+ ## Related
101
+
102
+ - MCP server for Claude, ChatGPT, Cursor and other MCP clients: [signal8.ai/mcp](https://signal8.ai/mcp)
103
+ - Free CC BY 4.0 datasets (reverse splits, listing deficiency notices): [signal8.ai/datasets](https://signal8.ai/datasets)
104
+
105
+ ## Licence
106
+
107
+ MIT. Use of the API is subject to the [Signal8 Terms](https://signal8.ai/terms). Nothing
108
+ returned by the API is investment advice.
109
+
110
+ ## Maintainer notes: publishing
111
+
112
+ Not yet on PyPI. To publish (from this directory, with a PyPI API token for the `signal8`
113
+ project; the name was unclaimed on 2026-11-20):
114
+
115
+ ```bash
116
+ python -m pip install --upgrade build twine
117
+ rm -rf dist && python -m build # dist/signal8-0.1.0.tar.gz + .whl
118
+ python -m twine check dist/*
119
+ python -m twine upload --repository testpypi dist/* # optional dry run on test.pypi.org
120
+ python -m twine upload dist/* # username __token__, password = PyPI token
121
+ ```
122
+
123
+ Bump `version` in `pyproject.toml` and `__version__` in `src/signal8/__init__.py` together.
@@ -0,0 +1,39 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "signal8"
7
+ version = "0.1.0"
8
+ description = "Python client for the Signal8 API: SEC filings, insider and Congress trades, 13F holdings and dilution data for US stocks."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ requires-python = ">=3.9"
13
+ authors = [{ name = "Signal8", email = "business@signal8.ai" }]
14
+ keywords = ["sec", "edgar", "filings", "insider trading", "13f", "dilution", "stocks", "api", "finance"]
15
+ classifiers = [
16
+ "Development Status :: 4 - Beta",
17
+ "Intended Audience :: Developers",
18
+ "Intended Audience :: Financial and Insurance Industry",
19
+ "Operating System :: OS Independent",
20
+ "Programming Language :: Python :: 3",
21
+ "Topic :: Office/Business :: Financial :: Investment",
22
+ "Typing :: Typed",
23
+ ]
24
+ dependencies = ["requests>=2.28"]
25
+
26
+ [project.optional-dependencies]
27
+ test = ["pytest>=7", "responses>=0.23"]
28
+
29
+ [project.urls]
30
+ Homepage = "https://signal8.ai"
31
+ Documentation = "https://signal8.ai/developer"
32
+ "API keys" = "https://signal8.ai/developer/api-keys"
33
+ "MCP server" = "https://signal8.ai/mcp"
34
+
35
+ [tool.hatch.build.targets.wheel]
36
+ packages = ["src/signal8"]
37
+
38
+ [tool.hatch.build.targets.sdist]
39
+ include = ["src/signal8", "tests", "README.md", "LICENSE", "pyproject.toml"]
@@ -0,0 +1,6 @@
1
+ """Python client for the Signal8 API (https://signal8.ai/developer)."""
2
+ __version__ = "0.1.0"
3
+
4
+ from .client import DEFAULT_BASE_URL, RateLimit, Signal8, Signal8Error # noqa: E402
5
+
6
+ __all__ = ["Signal8", "Signal8Error", "RateLimit", "DEFAULT_BASE_URL", "__version__"]
@@ -0,0 +1,301 @@
1
+ """Thin client for the Signal8 public REST API (https://signal8.ai/developer)."""
2
+ from __future__ import annotations
3
+
4
+ import os
5
+ import time
6
+ from dataclasses import dataclass
7
+ from typing import Any, Dict, Iterable, Literal, Mapping, Optional, Union
8
+
9
+ import requests
10
+
11
+ from . import __version__
12
+
13
+ DEFAULT_BASE_URL = "https://api.signal8.ai/api/v1/public"
14
+
15
+ JSON = Dict[str, Any]
16
+ Params = Mapping[str, Union[str, int, float, bool, None]]
17
+
18
+ InstrumentFamily = Literal[
19
+ "warrants", "convertibles", "preferred", "shelfs", "atms", "elocs",
20
+ "s1_offerings", "equity_plans", "exchangeables", "recent_offerings", "rights",
21
+ ]
22
+ MoverDirection = Literal["gainers", "losers", "active"]
23
+ Session = Literal["premarket", "regular", "afterhours"]
24
+ Universe = Literal["sp500", "ndx", "dji"]
25
+
26
+
27
+ class Signal8Error(Exception):
28
+ """A non-2xx response. `code` is the API's machine-readable error code
29
+ (for example API_KEY_REQUIRED, FEATURE_NOT_AVAILABLE, RATE_LIMITED)."""
30
+
31
+ def __init__(self, message: str, *, status: int, code: str = "API_ERROR",
32
+ details: Any = None) -> None:
33
+ super().__init__(message)
34
+ self.status = status
35
+ self.code = code
36
+ self.details = details
37
+
38
+ def __repr__(self) -> str:
39
+ return f"Signal8Error(status={self.status}, code={self.code!r}, message={str(self)!r})"
40
+
41
+
42
+ @dataclass
43
+ class RateLimit:
44
+ """Usage headers from the most recent response (None when not sent)."""
45
+
46
+ limit: Optional[int] = None
47
+ remaining: Optional[int] = None
48
+ reset: Optional[int] = None
49
+ daily_limit: Optional[int] = None
50
+ daily_remaining: Optional[int] = None
51
+ daily_reset: Optional[int] = None
52
+ credit_cost: Optional[int] = None
53
+ credits_remaining: Optional[int] = None
54
+ sandbox: bool = False
55
+
56
+ @classmethod
57
+ def from_headers(cls, h: Mapping[str, str]) -> "RateLimit":
58
+ def num(name: str) -> Optional[int]:
59
+ v = h.get(name)
60
+ try:
61
+ return int(float(v)) if v is not None else None
62
+ except ValueError:
63
+ return None
64
+
65
+ return cls(
66
+ limit=num("X-RateLimit-Limit"), remaining=num("X-RateLimit-Remaining"),
67
+ reset=num("X-RateLimit-Reset"), daily_limit=num("X-DailyLimit-Limit"),
68
+ daily_remaining=num("X-DailyLimit-Remaining"), daily_reset=num("X-DailyLimit-Reset"),
69
+ credit_cost=num("X-Credit-Cost"), credits_remaining=num("X-Credits-Remaining"),
70
+ sandbox=str(h.get("X-Sandbox", "")).lower() == "true",
71
+ )
72
+
73
+
74
+ def _clean(params: Optional[Params]) -> Dict[str, Any]:
75
+ out: Dict[str, Any] = {}
76
+ for k, v in (params or {}).items():
77
+ if v is None:
78
+ continue
79
+ out[k] = ("true" if v else "false") if isinstance(v, bool) else v
80
+ return out
81
+
82
+
83
+ class Signal8:
84
+ """Client for the Signal8 API.
85
+
86
+ >>> s8 = Signal8() # reads SIGNAL8_API_KEY
87
+ >>> s8.search_companies("apple")["data"]
88
+
89
+ Every method returns the parsed JSON body unchanged, so field names match
90
+ the API reference at https://signal8.ai/developer. Missing values in the
91
+ API mean "not measured", never zero; this client does not fill them in.
92
+ """
93
+
94
+ def __init__(self, api_key: Optional[str] = None, *, base_url: str = DEFAULT_BASE_URL,
95
+ timeout: float = 30.0, max_retries: int = 2,
96
+ session: Optional[requests.Session] = None) -> None:
97
+ self.api_key = api_key or os.environ.get("SIGNAL8_API_KEY")
98
+ if not self.api_key:
99
+ raise ValueError("No API key. Pass api_key= or set SIGNAL8_API_KEY "
100
+ "(create one at https://signal8.ai/developer/api-keys).")
101
+ self.base_url = base_url.rstrip("/")
102
+ self.timeout = timeout
103
+ self.max_retries = max_retries
104
+ self.session = session or requests.Session()
105
+ self.rate_limit = RateLimit()
106
+
107
+ # ------------------------------------------------------------------ core
108
+
109
+ def request(self, method: str, path: str, *, params: Optional[Params] = None,
110
+ json: Any = None) -> JSON:
111
+ url = f"{self.base_url}/{path.lstrip('/')}"
112
+ headers = {
113
+ "Authorization": f"Bearer {self.api_key}",
114
+ "Accept": "application/json",
115
+ "User-Agent": f"signal8-python/{__version__}",
116
+ }
117
+ attempt = 0
118
+ while True:
119
+ resp = self.session.request(method, url, params=_clean(params), json=json,
120
+ headers=headers, timeout=self.timeout)
121
+ self.rate_limit = RateLimit.from_headers(resp.headers)
122
+ if resp.status_code in (429, 502, 503, 504) and attempt < self.max_retries:
123
+ attempt += 1
124
+ wait = resp.headers.get("Retry-After")
125
+ try:
126
+ delay = float(wait) if wait is not None else 2.0 ** attempt
127
+ except ValueError:
128
+ delay = 2.0 ** attempt
129
+ time.sleep(min(delay, 60.0))
130
+ continue
131
+ return self._parse(resp)
132
+
133
+ def get(self, path: str, **params: Any) -> JSON:
134
+ """GET any documented endpoint, e.g. ``s8.get("/splits/AAPL")``."""
135
+ return self.request("GET", path, params=params)
136
+
137
+ @staticmethod
138
+ def _parse(resp: requests.Response) -> JSON:
139
+ try:
140
+ body = resp.json()
141
+ except ValueError:
142
+ body = None
143
+ if resp.ok and isinstance(body, dict):
144
+ return body
145
+ err = body.get("error") if isinstance(body, dict) else None
146
+ if isinstance(err, dict):
147
+ raise Signal8Error(err.get("message") or f"HTTP {resp.status_code}",
148
+ status=resp.status_code, code=err.get("code") or "API_ERROR",
149
+ details=err.get("details"))
150
+ if isinstance(err, str):
151
+ raise Signal8Error(err, status=resp.status_code)
152
+ if resp.ok:
153
+ raise Signal8Error("Response was not a JSON object", status=resp.status_code,
154
+ code="PARSE_ERROR")
155
+ raise Signal8Error(f"HTTP {resp.status_code}", status=resp.status_code)
156
+
157
+ # ------------------------------------------------------------- companies
158
+
159
+ def search_companies(self, q: str, limit: Optional[int] = None) -> JSON:
160
+ return self.get("/companies/search", q=q, limit=limit)
161
+
162
+ def company(self, ticker: str) -> JSON:
163
+ """Company profile. `ticker` may also be a former ticker or a CIK."""
164
+ return self.get(f"/companies/{ticker}")
165
+
166
+ def quote(self, ticker: str) -> JSON:
167
+ return self.get(f"/companies/{ticker}/quote")
168
+
169
+ def quotes(self, tickers: Iterable[str]) -> JSON:
170
+ """Quotes for up to 500 tickers in one call."""
171
+ return self.request("POST", "/market/quotes", json={"tickers": list(tickers)})
172
+
173
+ def financials(self, ticker: str, limit: Optional[int] = None) -> JSON:
174
+ return self.get(f"/companies/{ticker}/financials", limit=limit)
175
+
176
+ def earnings(self, ticker: str, limit: Optional[int] = None) -> JSON:
177
+ return self.get(f"/companies/{ticker}/earnings", limit=limit)
178
+
179
+ def news(self, ticker: str, limit: Optional[int] = None, page: Optional[int] = None) -> JSON:
180
+ return self.get(f"/companies/{ticker}/news", limit=limit, page=page)
181
+
182
+ def float_shares(self, ticker: str) -> JSON:
183
+ """Float and shares outstanding (/companies/{ticker}/float)."""
184
+ return self.get(f"/companies/{ticker}/float")
185
+
186
+ def float_history(self, ticker: str, days: Optional[int] = None) -> JSON:
187
+ return self.get(f"/companies/{ticker}/float-history", days=days)
188
+
189
+ def short_interest(self, ticker: str) -> JSON:
190
+ return self.get(f"/companies/{ticker}/short-interest")
191
+
192
+ def split_history(self, ticker: str) -> JSON:
193
+ return self.get(f"/splits/{ticker}")
194
+
195
+ # ---------------------------------------------------------- insiders/13F
196
+
197
+ def insiders(self, ticker: str) -> JSON:
198
+ return self.get(f"/intelligence/{ticker}/insiders")
199
+
200
+ def insider_transactions(self, ticker: str, *, year: Optional[int] = None,
201
+ month: Optional[int] = None, transaction_code: Optional[str] = None,
202
+ limit: Optional[int] = None, offset: Optional[int] = None) -> JSON:
203
+ return self.get(f"/intelligence/{ticker}/insider-transactions", year=year, month=month,
204
+ transactionCode=transaction_code, limit=limit, offset=offset)
205
+
206
+ def insider_cluster_buys(self, ticker: str) -> JSON:
207
+ return self.get(f"/intelligence/{ticker}/cluster-buys")
208
+
209
+ def ownership(self, ticker: str) -> JSON:
210
+ return self.get(f"/intelligence/{ticker}/ownership")
211
+
212
+ def institutions(self, ticker: str) -> JSON:
213
+ return self.get(f"/intelligence/{ticker}/institutions")
214
+
215
+ def institution(self, cik: Union[str, int]) -> JSON:
216
+ return self.get(f"/intelligence/institution/{cik}")
217
+
218
+ def institution_holdings(self, cik: Union[str, int], *, period: Optional[str] = None,
219
+ limit: Optional[int] = None, offset: Optional[int] = None) -> JSON:
220
+ return self.get(f"/intelligence/institution/{cik}/holdings", period=period,
221
+ limit=limit, offset=offset)
222
+
223
+ # -------------------------------------------------------------- dilution
224
+
225
+ def dilution_coverage(self, ticker: str) -> JSON:
226
+ """Cheap check for whether a dilution analysis exists. Call this first."""
227
+ return self.get(f"/dilution/{ticker}/coverage")
228
+
229
+ def dilution_snapshot(self, ticker: str) -> JSON:
230
+ return self.get(f"/dilution/{ticker}/snapshot")
231
+
232
+ def dilution_instruments(self, ticker: str, family: InstrumentFamily) -> JSON:
233
+ return self.get(f"/dilution/{ticker}/instruments", family=family)
234
+
235
+ def dilution_risk(self, ticker: str) -> JSON:
236
+ return self.get(f"/dilution/{ticker}/risk")
237
+
238
+ def dilution_history(self, ticker: str) -> JSON:
239
+ return self.get(f"/dilution/{ticker}/history")
240
+
241
+ def cash_position(self, ticker: str) -> JSON:
242
+ return self.get(f"/cash-position/{ticker}")
243
+
244
+ def compliance(self, ticker: str) -> JSON:
245
+ return self.get(f"/compliance/{ticker}/evaluation")
246
+
247
+ # ---------------------------------------------------------------- filings
248
+
249
+ def edgar_filings(self, **filters: Any) -> JSON:
250
+ """Search filings. Filters are passed through as documented, e.g.
251
+ ``ciks="320193", formTypes="8-K", dateFrom="2026-01-01"``."""
252
+ return self.get("/edgar/filings", **filters)
253
+
254
+ def edgar_search_text(self, pattern: str, **filters: Any) -> JSON:
255
+ return self.get("/edgar/search-text", pattern=pattern, **filters)
256
+
257
+ def accession(self, accession_number: str) -> JSON:
258
+ return self.get(f"/edgar/accession/{accession_number}")
259
+
260
+ def recent_material_filings(self, universe: Universe, items: Optional[str] = None,
261
+ limit: Optional[int] = None) -> JSON:
262
+ return self.get("/filings/recent-material", universe=universe, items=items, limit=limit)
263
+
264
+ def filing_calendar(self, **filters: Any) -> JSON:
265
+ return self.get("/calendar/filings", **filters)
266
+
267
+ # ----------------------------------------------------------------- market
268
+
269
+ def movers(self, direction: MoverDirection = "gainers", *, limit: Optional[int] = None,
270
+ session: Optional[Session] = None, market_cap_min: Optional[float] = None,
271
+ market_cap_max: Optional[float] = None) -> JSON:
272
+ return self.get(f"/market/movers/{direction}", limit=limit, session=session,
273
+ marketCapMin=market_cap_min, marketCapMax=market_cap_max)
274
+
275
+ def trading_halts(self) -> JSON:
276
+ return self.get("/trading-halts")
277
+
278
+ def screener(self, **filters: Any) -> JSON:
279
+ """Company screener, e.g. ``maxFloat=10_000_000, minPrice=1``."""
280
+ return self.get("/screener", **filters)
281
+
282
+ # ------------------------------------------------------------- politicians
283
+
284
+ def politicians(self, **filters: Any) -> JSON:
285
+ return self.get("/senate-insiders", **filters)
286
+
287
+ def politician(self, slug: str) -> JSON:
288
+ return self.get(f"/senate-insiders/{slug}")
289
+
290
+ def politician_transactions(self, slug: str, **filters: Any) -> JSON:
291
+ return self.get(f"/senate-insiders/{slug}/transactions", **filters)
292
+
293
+ def congress_trades_by_ticker(self, ticker: str, *, days: Optional[int] = None,
294
+ limit: Optional[int] = None) -> JSON:
295
+ return self.get(f"/senate-insiders/by-ticker/{ticker}/recent-trades", days=days, limit=limit)
296
+
297
+ def recent_congress_trades(self, *, days: Optional[int] = None, limit: Optional[int] = None) -> JSON:
298
+ return self.get("/senate-insiders/discovery/recent-trades", days=days, limit=limit)
299
+
300
+
301
+ __all__ = ["Signal8", "Signal8Error", "RateLimit", "DEFAULT_BASE_URL"]
File without changes
@@ -0,0 +1,105 @@
1
+ import json
2
+
3
+ import pytest
4
+ import responses
5
+
6
+ from signal8 import DEFAULT_BASE_URL, Signal8, Signal8Error
7
+
8
+ B = DEFAULT_BASE_URL
9
+
10
+
11
+ @pytest.fixture
12
+ def s8():
13
+ return Signal8("sk_test_123", max_retries=1)
14
+
15
+
16
+ def test_requires_key(monkeypatch):
17
+ monkeypatch.delenv("SIGNAL8_API_KEY", raising=False)
18
+ with pytest.raises(ValueError):
19
+ Signal8()
20
+
21
+
22
+ def test_key_from_env(monkeypatch):
23
+ monkeypatch.setenv("SIGNAL8_API_KEY", "sk_test_env")
24
+ assert Signal8().api_key == "sk_test_env"
25
+
26
+
27
+ @responses.activate
28
+ def test_search_sends_auth_and_params(s8):
29
+ responses.get(f"{B}/companies/search", json={"data": [{"ticker": "AAPL"}]},
30
+ headers={"X-RateLimit-Remaining": "119", "X-DailyLimit-Remaining": "9999",
31
+ "X-Sandbox": "true"})
32
+ out = s8.search_companies("apple", limit=5)
33
+ assert out["data"][0]["ticker"] == "AAPL"
34
+ req = responses.calls[0].request
35
+ assert req.headers["Authorization"] == "Bearer sk_test_123"
36
+ assert req.headers["User-Agent"].startswith("signal8-python/")
37
+ assert "q=apple" in req.url and "limit=5" in req.url
38
+ assert s8.rate_limit.remaining == 119 and s8.rate_limit.daily_remaining == 9999
39
+ assert s8.rate_limit.sandbox is True
40
+
41
+
42
+ @responses.activate
43
+ def test_none_params_dropped_and_bools_lowercased(s8):
44
+ responses.get(f"{B}/screener", json={"data": []})
45
+ s8.screener(maxFloat=10_000_000, excludeHalted=True, sector=None)
46
+ url = responses.calls[0].request.url
47
+ assert "maxFloat=10000000" in url and "excludeHalted=true" in url and "sector" not in url
48
+
49
+
50
+ @responses.activate
51
+ def test_dilution_instruments_family(s8):
52
+ responses.get(f"{B}/dilution/AZTR/instruments", json={"data": {"rows": []}})
53
+ s8.dilution_instruments("AZTR", "warrants")
54
+ assert "family=warrants" in responses.calls[0].request.url
55
+
56
+
57
+ @responses.activate
58
+ def test_batch_quotes_post_body(s8):
59
+ responses.post(f"{B}/market/quotes", json={"data": []})
60
+ s8.quotes(["AAPL", "MSFT"])
61
+ assert json.loads(responses.calls[0].request.body) == {"tickers": ["AAPL", "MSFT"]}
62
+
63
+
64
+ @responses.activate
65
+ def test_movers_path_and_camelcase(s8):
66
+ responses.get(f"{B}/market/movers/losers", json={"data": []})
67
+ s8.movers("losers", session="premarket", market_cap_max=3e8)
68
+ url = responses.calls[0].request.url
69
+ assert "session=premarket" in url and "marketCapMax=300000000.0" in url
70
+
71
+
72
+ @responses.activate
73
+ def test_error_envelope(s8):
74
+ responses.get(f"{B}/dilution/AAPL/risk", status=403,
75
+ json={"error": {"code": "FEATURE_NOT_AVAILABLE", "message": "Pro required",
76
+ "details": {"requiredTier": "pro"}}})
77
+ with pytest.raises(Signal8Error) as e:
78
+ s8.dilution_risk("AAPL")
79
+ assert e.value.status == 403 and e.value.code == "FEATURE_NOT_AVAILABLE"
80
+ assert e.value.details == {"requiredTier": "pro"}
81
+
82
+
83
+ @responses.activate
84
+ def test_non_json_error(s8):
85
+ responses.get(f"{B}/companies/AAPL", status=502, body="bad gateway")
86
+ responses.get(f"{B}/companies/AAPL", status=502, body="bad gateway")
87
+ with pytest.raises(Signal8Error) as e:
88
+ s8.company("AAPL")
89
+ assert e.value.status == 502
90
+
91
+
92
+ @responses.activate
93
+ def test_retries_429_then_succeeds(s8, monkeypatch):
94
+ monkeypatch.setattr("signal8.client.time.sleep", lambda s: None)
95
+ responses.get(f"{B}/trading-halts", status=429, headers={"Retry-After": "1"},
96
+ json={"error": {"code": "RATE_LIMITED", "message": "slow down"}})
97
+ responses.get(f"{B}/trading-halts", json={"data": []})
98
+ assert s8.trading_halts() == {"data": []}
99
+ assert len(responses.calls) == 2
100
+
101
+
102
+ @responses.activate
103
+ def test_generic_get(s8):
104
+ responses.get(f"{B}/splits/AAPL", json={"data": [{"ratio": "4:1"}]})
105
+ assert s8.get("/splits/AAPL")["data"][0]["ratio"] == "4:1"