Signal8 0.1.0__py3-none-any.whl

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.
signal8/__init__.py ADDED
@@ -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__"]
signal8/client.py ADDED
@@ -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"]
signal8/py.typed ADDED
File without changes
@@ -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,7 @@
1
+ signal8/__init__.py,sha256=f9XnSxtz1jsuVCQQFZ-PgrMmw2jojjtAeiEHLtkKkdg,267
2
+ signal8/client.py,sha256=ooeDh01JCbHmJevi3fOVCu8XV5LCU6f2ipp0bz7Ecnw,12902
3
+ signal8/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
4
+ signal8-0.1.0.dist-info/METADATA,sha256=rdiF0sS7-LHN0ZJctzUuk2dZpP2qY6sF3jx5hYgUy_c,5172
5
+ signal8-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
6
+ signal8-0.1.0.dist-info/licenses/LICENSE,sha256=5gY5GxM3DkkRUOzH_7o6snzR_ZYDykmy-VA1QsTXFKI,1069
7
+ signal8-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -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.