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

invinite_data_api-4.0.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: invinite_data_api
+Version: 4.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.
+  scripts/package-data-sdk.mjs 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) `/v2` at
+`api.data.invinite.com` — companies, standardized and as-reported financials, metrics,
+SEC filings and documents, 13F holdings, insider trades, IPOs, earnings events and
+transcripts, guidance, investor documents and news. 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 CompaniesApi
+
+config = invinite_data_api.Configuration(access_token=os.environ["INVINITE_DATA_API_KEY"])
+
+with invinite_data_api.ApiClient(config) as client:
+    api = CompaniesApi(client)
+    page = api.list_companies(q="NVDA", limit=5)
+    for company in page.data:
+        print(company.ticker, company.name, company.cik)
+    nvidia = api.get_company(company="NVDA")
+```
+
+Every API class is named after a docs group (`CompaniesApi`, `FinancialsApi`,
+`FilingsApi`, `EventsApi`, …) and every method after the operation's verb-first
+`operationId` in snake_case (`list_filings`, `get_company`). Arguments keep the wire's
+snake_case names; a range filter's dot becomes `_` (`filed_at_gte` for `filed_at.gte`)
+and a Python keyword gets a `var_` prefix. The company is always a filter: `company`
+takes a ticker or a CIK, or a comma list of up to 50. Date parameters take a
+`datetime.date`.
+
+## Lists, cursors and the pager
+
+Every list answers ONE envelope: `data`, `has_more`, `next_cursor`, `meta`. Pass
+`next_cursor` back as `cursor` with the SAME filters (changed filters answer
+`400 cursor_mismatch`) until `has_more` is false — or let the pager do it:
+
+```python
+from invinite_data_api import FilingsApi
+from invinite_data_api.pagination import iterate_items, iterate_pages
+
+with invinite_data_api.ApiClient(config) as client:
+    api = FilingsApi(client)
+    for filing in iterate_items(api.list_filings, company="AAPL", form="10-K", limit=100):
+        print(filing.accession, filing.form, filing.filed_at)
+    for page in iterate_pages(api.list_filings, company="AAPL", max_pages=3):
+        print(len(page.data), page.meta.coverage.state if page.meta.coverage else None)
+```
+
+Each page is one billed call. `meta.coverage.state` is `pending` / `partial` /
+`complete`: a scope the store is still filling answers `200` with `data: []` and
+`pending`, never an error.
+
+## Reading credits
+
+Each call reports what it cost in the `X-Credits-Charged` and `X-Credits-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, so look them up case-insensitively:
+
+```python
+response = api.list_filings_with_http_info(company="AAPL")
+headers = {name.lower(): value for name, value in response.headers.items()}
+print(headers["x-credits-charged"])
+print(headers["x-credits-remaining"])
+page = response.data
+```
+
+## Error handling
+
+On a non-2xx response the client raises `ApiException` (with per-status subclasses).
+The body is an RFC 9457 `application/problem+json` document with a stable `code`
+(`not_covered`, `invalid_parameter`, `cursor_mismatch`, `rate_limited`, …) and a
+`request_id`. On `429` and `503`, wait for the `Retry-After` header before retrying.
+
+```python
+import json
+from invinite_data_api.exceptions import ApiException
+
+try:
+    api.list_filings(company="NOPE")
+except ApiException as error:
+    problem = json.loads(error.body) if error.body else {}
+    print(error.status, problem.get("code"), problem.get("detail"), problem.get("request_id"))
+```
+
+## Upgrading from 3.x
+
+4.0.0 is generated from the `/v2` API only; the `/v1` classes are gone (the `/v1` routes keep
+working until their announced sunset). Lists use the cursor envelope above instead of
+`offset` / `next_url`, errors are problem documents instead of `{"error", "message"}`, and
+booleans are real booleans.
+
+| 3.x | 4.0.0 |
+|---|---|
+| `CompanyApi` | `CompaniesApi` (`list_companies`, `get_company`, filers, people) |
+| `Standardized…Api`, `AsReported…Api` (24 classes) | `FinancialsApi` (6 operations: basis × plain / detailed / presentation, `statement` filter) |
+| `FinancialMetricsApi`, `SegmentedFinancialsApi` | `MetricsApi` |
+| `SECApi`, `InstitutionalOwnershipApi` | `FilingsApi`, `DocumentsApi`, `HoldingsApi` |
+| `InsiderTradesApi`, `IPOsApi`, `NewsApi` | same class names, `/v2` operations |
+| `EarningsCallsApi` | `EventsApi`, `TranscriptsApi`, `CallAnalyticsApi`, `GuidanceApi`, `InvestorDocumentsApi`, `WebhooksApi` |
+| `MarketApi`, `MetadataApi` | `ReferenceApi`, `CatalogApi` |
+| `AccountApi` | `AccountApi` (`get_me`, `get_my_usage`) |
+| `HealthApi`, `StatusApi` | not in 4.0.0 (plain `GET /health`, `/status`) |
+
+## Not in this client
+
+- The realtime stream at `/v2/stream` (WebSocket) —
+  [realtime 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 (`WebhooksApi`).
+
+## Regeneration
+
+This client is a generated artifact; if a type looks wrong, the fix belongs in the API's
+contract, 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

invinite_data_api-4.0.0/README.md

@@ -0,0 +1,161 @@
+<!--
+  Canonical, hand-written README for the invinite-data-api PyPI package.
+  scripts/package-data-sdk.mjs 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) `/v2` at
+`api.data.invinite.com` — companies, standardized and as-reported financials, metrics,
+SEC filings and documents, 13F holdings, insider trades, IPOs, earnings events and
+transcripts, guidance, investor documents and news. 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 CompaniesApi
+
+config = invinite_data_api.Configuration(access_token=os.environ["INVINITE_DATA_API_KEY"])
+
+with invinite_data_api.ApiClient(config) as client:
+    api = CompaniesApi(client)
+    page = api.list_companies(q="NVDA", limit=5)
+    for company in page.data:
+        print(company.ticker, company.name, company.cik)
+    nvidia = api.get_company(company="NVDA")
+```
+
+Every API class is named after a docs group (`CompaniesApi`, `FinancialsApi`,
+`FilingsApi`, `EventsApi`, …) and every method after the operation's verb-first
+`operationId` in snake_case (`list_filings`, `get_company`). Arguments keep the wire's
+snake_case names; a range filter's dot becomes `_` (`filed_at_gte` for `filed_at.gte`)
+and a Python keyword gets a `var_` prefix. The company is always a filter: `company`
+takes a ticker or a CIK, or a comma list of up to 50. Date parameters take a
+`datetime.date`.
+
+## Lists, cursors and the pager
+
+Every list answers ONE envelope: `data`, `has_more`, `next_cursor`, `meta`. Pass
+`next_cursor` back as `cursor` with the SAME filters (changed filters answer
+`400 cursor_mismatch`) until `has_more` is false — or let the pager do it:
+
+```python
+from invinite_data_api import FilingsApi
+from invinite_data_api.pagination import iterate_items, iterate_pages
+
+with invinite_data_api.ApiClient(config) as client:
+    api = FilingsApi(client)
+    for filing in iterate_items(api.list_filings, company="AAPL", form="10-K", limit=100):
+        print(filing.accession, filing.form, filing.filed_at)
+    for page in iterate_pages(api.list_filings, company="AAPL", max_pages=3):
+        print(len(page.data), page.meta.coverage.state if page.meta.coverage else None)
+```
+
+Each page is one billed call. `meta.coverage.state` is `pending` / `partial` /
+`complete`: a scope the store is still filling answers `200` with `data: []` and
+`pending`, never an error.
+
+## Reading credits
+
+Each call reports what it cost in the `X-Credits-Charged` and `X-Credits-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, so look them up case-insensitively:
+
+```python
+response = api.list_filings_with_http_info(company="AAPL")
+headers = {name.lower(): value for name, value in response.headers.items()}
+print(headers["x-credits-charged"])
+print(headers["x-credits-remaining"])
+page = response.data
+```
+
+## Error handling
+
+On a non-2xx response the client raises `ApiException` (with per-status subclasses).
+The body is an RFC 9457 `application/problem+json` document with a stable `code`
+(`not_covered`, `invalid_parameter`, `cursor_mismatch`, `rate_limited`, …) and a
+`request_id`. On `429` and `503`, wait for the `Retry-After` header before retrying.
+
+```python
+import json
+from invinite_data_api.exceptions import ApiException
+
+try:
+    api.list_filings(company="NOPE")
+except ApiException as error:
+    problem = json.loads(error.body) if error.body else {}
+    print(error.status, problem.get("code"), problem.get("detail"), problem.get("request_id"))
+```
+
+## Upgrading from 3.x
+
+4.0.0 is generated from the `/v2` API only; the `/v1` classes are gone (the `/v1` routes keep
+working until their announced sunset). Lists use the cursor envelope above instead of
+`offset` / `next_url`, errors are problem documents instead of `{"error", "message"}`, and
+booleans are real booleans.
+
+| 3.x | 4.0.0 |
+|---|---|
+| `CompanyApi` | `CompaniesApi` (`list_companies`, `get_company`, filers, people) |
+| `Standardized…Api`, `AsReported…Api` (24 classes) | `FinancialsApi` (6 operations: basis × plain / detailed / presentation, `statement` filter) |
+| `FinancialMetricsApi`, `SegmentedFinancialsApi` | `MetricsApi` |
+| `SECApi`, `InstitutionalOwnershipApi` | `FilingsApi`, `DocumentsApi`, `HoldingsApi` |
+| `InsiderTradesApi`, `IPOsApi`, `NewsApi` | same class names, `/v2` operations |
+| `EarningsCallsApi` | `EventsApi`, `TranscriptsApi`, `CallAnalyticsApi`, `GuidanceApi`, `InvestorDocumentsApi`, `WebhooksApi` |
+| `MarketApi`, `MetadataApi` | `ReferenceApi`, `CatalogApi` |
+| `AccountApi` | `AccountApi` (`get_me`, `get_my_usage`) |
+| `HealthApi`, `StatusApi` | not in 4.0.0 (plain `GET /health`, `/status`) |
+
+## Not in this client
+
+- The realtime stream at `/v2/stream` (WebSocket) —
+  [realtime 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 (`WebhooksApi`).
+
+## Regeneration
+
+This client is a generated artifact; if a type looks wrong, the fix belongs in the API's
+contract, 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