invinite-data-api 1.2.0__tar.gz → 3.0.0__tar.gz

invinite_data_api-3.0.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: invinite_data_api
+Version: 3.0.0
+Summary: Typed Python client for the Invinite Data API
+Home-page: 
+Author: OpenAPI Generator community
+Author-email: OpenAPI Generator Community <team@openapitools.org>
+Project-URL: Homepage, https://data.invinite.com
+Project-URL: Documentation, https://data.invinite.com/docs/sdks
+Project-URL: Repository, https://github.com/outraday-org/invinite-data-api
+Keywords: OpenAPI,OpenAPI-Generator,Invinite API
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: urllib3<3.0.0,>=2.1.0
+Requires-Dist: python-dateutil>=2.8.2
+Requires-Dist: pydantic>=2.11
+Requires-Dist: typing-extensions>=4.7.1
+Dynamic: author
+
+<!--
+  Canonical, hand-written README for the invinite-data-api PyPI package.
+  publish-data-sdk.yml copies this over sdks/data/python/README.md (a git-ignored,
+  generator-default file) before the Python build, so this is the page PyPI renders
+  (pyproject.toml `readme = "README.md"`). Edit here, not in the generated tree.
+  scripts/check-data-sdk-names.ts asserts every API class and `api.<method>(` call
+  named below exists in the generated client.
+-->
+
+# invinite-data-api
+
+Typed Python client for the [Invinite Data API](https://data.invinite.com) at
+`api.data.invinite.com` — standardized and as-reported financials, filings, earnings
+calls, ownership, insider trades and market data. It is generated from the API's own
+OpenAPI document, so its request and response models match the
+[reference](https://data.invinite.com/docs).
+
+The client is built on urllib3 + pydantic, needs Python 3.9+, and imports as
+`invinite_data_api`.
+
+## Install
+
+```bash
+pip install invinite-data-api
+```
+
+## Authentication
+
+Create a `Configuration` with your `invd_` Data API key (or an Invinite Data OAuth
+access token) as the access token. The client sends it as an
+`Authorization: Bearer <token>` header on every request.
+
+```python
+import os
+import invinite_data_api
+
+config = invinite_data_api.Configuration(access_token=os.environ["INVINITE_DATA_API_KEY"])
+```
+
+## Quickstart
+
+```python
+import os
+import invinite_data_api
+from invinite_data_api import CompanyApi
+
+config = invinite_data_api.Configuration(access_token=os.environ["INVINITE_DATA_API_KEY"])
+
+with invinite_data_api.ApiClient(config) as client:
+    api = CompanyApi(client)
+    result = api.company_search(query="nvidia", limit=5)
+    for company in result.companies:
+        print(company.ticker, company.name, company.cik)
+```
+
+Every API class is named after an OpenAPI tag (`CompanyApi`, `EarningsCallsApi`,
+`SECApi`, …) and every method after the operation's `operationId` in snake_case.
+Arguments keep the wire's snake_case names; a name that is a Python keyword gets a
+`var_` prefix (`var_from` for `from`, `var_date` for `date`). Date parameters take a
+`datetime.date`, never a string.
+
+## SEC filings and documents (`SECApi`)
+
+`SECApi` reads Invinite's SEC document store: filers, a filer's filings with a form facet,
+pinned document versions (blocks, pages, figures, sections, XBRL fact places), lexical /
+literal search, 13F holdings and metric exports. Every answer carries `readiness`:
+`ready` / `partial` (200), `pending` (202: not billed, retry later), and the refusals
+`excluded` 403, `unknown` 404, `failed` 424, `not_ready` 503 (a capability that is not
+switched on yet, e.g. search) raise `ApiException` with a `SecStoreError` body.
+Paged reads return `next_cursor`; pass it back unchanged.
+
+```python
+from invinite_data_api import SECApi
+
+with invinite_data_api.ApiClient(config) as client:
+    sec = SECApi(client)
+    page = sec.sec_filings(identifier="AAPL", form="10-K", limit=10)
+    filing = page.filings[0]
+    doc = sec.sec_document(accession=filing.accession, filename=filing.primary_document)
+    outline = sec.sec_document_sections(version_id=doc.version["version_id"], outline="legacy")
+```
+
+**1.0.0 removed the legacy SEC filings class** with the `/v1/sec-filings/*` routes. Replacements:
+
+| 0.x method | 1.0.0 |
+|---|---|
+| `sec_filings_list` | `sec_filings` (filer by ticker or CIK; `accession`, `form`, `filing_date`, `report_date`) + `sec_filing` for the documents and their permanent URLs |
+| `sec_filings_available_form_types` | `form_facet` of `sec_filings` |
+| `sec_filings_sections` | `sec_document` (pins the version) → `sec_document_sections` → `sec_document_version(blocks=…)` |
+| `sec_filings_search` | `sec_search` (`mode="lexical"` or `"literal"`, cited passages) |
+
+## Reading credits
+
+Each call reports what it cost in the `X-Credits-Charged` and
+`X-Credits-Included-Remaining` response headers. Every method has a
+`…_with_http_info` twin that returns the headers beside the parsed value. `response.headers`
+is a plain `dict` keyed as the server sent the names (lower-case over the API's proxy), so
+look them up case-insensitively:
+
+```python
+response = api.company_search_with_http_info(query="nvidia")
+headers = {name.lower(): value for name, value in response.headers.items()}
+print(headers["x-credits-charged"])
+print(headers["x-credits-included-remaining"])
+result = response.data
+```
+
+## Error handling
+
+On a non-2xx response the client raises `ApiException` (with per-status subclasses).
+On `429`, wait for the `Retry-After` header before retrying.
+
+```python
+from invinite_data_api.exceptions import ApiException
+
+try:
+    api.company_search(query="nvidia")
+except ApiException as error:
+    retry_after = error.headers.get("Retry-After") if error.headers else None
+    print(error.status, error.body, retry_after)
+```
+
+## Not in this client
+
+- The WebSocket stream at `/v1/ws` (live transcripts and filings) —
+  [WebSocket docs](https://data.invinite.com/docs/realtime).
+- Webhook signature verification — [webhook docs](https://data.invinite.com/docs/webhooks).
+  Managing webhook subscriptions IS in the client (`EarningsCallsApi`).
+
+## Regeneration
+
+This client is a generated artifact; if a type looks wrong, the fix belongs in the API's
+route schema, and regenerating re-derives every model. Releases are published on
+`data-sdk-v*` tags.
+
+## Links
+
+- [Data API docs](https://data.invinite.com/docs)
+- [SDKs](https://data.invinite.com/docs/sdks)
+- [Repository](https://github.com/outraday-org/invinite-data-api)
+
+## License
+
+MIT