finvizp 0.2.2__tar.gz

finvizp-0.2.2/LICENSE

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

finvizp-0.2.2/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: finvizp
+Version: 0.2.2
+Summary: Async, Arrow-native Python client for the public Finviz data surface.
+Keywords: finviz,finance,stocks,pyarrow,async
+Author: Volker Lorrmann
+Author-email: Volker Lorrmann <volker.lorrmann@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Dist: fastreq[curl]>=3.2.0
+Requires-Dist: lxml>=6.0.0
+Requires-Dist: pyarrow>=18.0.0
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/legout/finvizp
+Project-URL: Repository, https://github.com/legout/finvizp
+Project-URL: Issues, https://github.com/legout/finvizp/issues
+Project-URL: Documentation, https://github.com/legout/finvizp/tree/main/docs
+Description-Content-Type: text/markdown
+
+# finvizp
+
+[![CI](https://github.com/legout/finvizp/actions/workflows/ci.yml/badge.svg)](https://github.com/legout/finvizp/actions/workflows/ci.yml)
+[![Python 3.11-3.14](https://img.shields.io/badge/python-3.11--3.14-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+**Finviz for Python** — an unofficial, async-first, Arrow-native Finviz client
+built on [`fastreq`](https://pypi.org/project/fastreq/), direct lxml, and
+PyArrow.
+
+> [!IMPORTANT]
+> `finvizp` is not affiliated with, endorsed by, or sponsored by Finviz.
+> Finviz is a trademark of its respective owner.
+
+## Install
+
+```bash
+uv add finvizp  # or: pip install finvizp
+```
+
+## Quick start
+
+Async-first:
+
+```python
+import asyncio
+import finvizp
+
+
+async def main() -> None:
+    async with finvizp.FinvizClient() as client:
+        universe = await finvizp.symbols_async(client=client)
+        bundle = await finvizp.quote_async("AAPL", client=client)
+        print(bundle.data.snapshot.num_rows)
+
+
+asyncio.run(main())
+```
+
+Every operation has a **sync twin** (same name, no `_async` suffix) for
+scripts and notebooks:
+
+```python
+import finvizp
+
+matches = finvizp.search_symbols("APPLE")
+income = finvizp.statements("AAPL", statement="IA")  # IA/IQ/BA/BQ/CA/CQ
+snap = finvizp.snapshot("AAPL")  # cached, no 2nd request
+quote = finvizp.quote("AAPL")  # complete bundle
+universe = finvizp.symbols()
+finvizp.capabilities()  # implemented/planned ledger
+```
+
+Sync twins reject an active event loop; results, caching, and errors are
+identical.
+
+## What's implemented
+
+| Milestone | Surface | Status |
+|---|---|---|
+| 0.1 | Symbols, statements, quote bundles, cache | ✅ |
+| 0.2 | Screener, signals/earnings, registry drift tools | ✅ |
+| 0.3 | Groups, spectrum, maps, news, insider, calendar | ✅ |
+| 0.4 | Markets, artifacts (charts/spectrum), forex/crypto, futures | ✅ |
+| 0.5 | Frozen-surface + finvizfinance parity audit | ✅ |
+| 1.0 | Stable release | pending |
+
+The full implemented/planned ledger lives in the
+[capability matrix](docs/user/reference/capability-matrix.md) and
+`finvizp.capabilities()`.
+
+## Design in one screen
+
+- **Async-first with sync twins** — one transport, no hidden event loops.
+- **Arrow-native** — every dataset is a versioned, deterministic Arrow table.
+- **Immutable `FetchResult[T]`** — full provenance, typed partial/error
+  diagnostics, no in-place mutation.
+- **Complete compound bundles** — e.g. a quote page yields every relation in
+  one fetch; cache-preserving projections (`snapshot`, `ratings`, `news`,
+  `insider`, `peers`, `etf_holders`) never re-request.
+- **Structured-first sources** — public JSON/XHR or embedded payloads when
+  same-tier, complete, direct, and snapshot-coherent; lxml parsing otherwise.
+- **Explicit proxies, route-isolated auth, conservative pacing/retries,
+  bounded result caching, single-flight coalescing.** A per-client 429
+  circuit breaker trips after 3 consecutive rate limits and fails fast
+  (`CircuitOpenError`, no request sent) until the cooldown passes.
+- **No** login/browser automation, bulk crawling, pandas contract,
+  persistence layer, telemetry, or entitlement bypass.
+
+## Documentation
+
+User docs (Diataxis — tutorials, how-to, reference, explanation), rendered
+with [Zensical](https://zensical.org) from
+[`docs/user/`](docs/user/):
+
+| You want to… | Go to |
+|---|---|
+| Try it in 5 minutes | [Get started](docs/user/tutorials/get-started.md) |
+| Use the sync API | [Use the sync API](docs/user/how-to/sync-api.md) |
+| Set proxies / caching | [Proxies & cache](docs/user/how-to/proxies-and-cache.md) |
+| Migrate from `finvizfinance` | [Migration guide](docs/user/how-to/migrate-from-finvizfinance.md) |
+| Check a dataset's columns | [Arrow schemas](docs/user/reference/schemas-0.1.md) |
+| Understand result envelopes | [Results](docs/user/reference/results.md) |
+| See every capability + status | [Capability matrix](docs/user/reference/capability-matrix.md) |
+
+Deep links: [screener](docs/user/reference/screener.md) ·
+[screener registry](docs/user/reference/screener-registry.md) ·
+[groups/maps/events](docs/user/reference/groups-maps-events.md) ·
+[markets/artifacts](docs/user/reference/markets-and-artifacts.md) ·
+[schema versioning](docs/user/reference/schema-versioning.md) ·
+[keep your own history](docs/user/how-to/caller-owned-history.md) ·
+[access & responsible use](docs/user/explanation/access-and-responsible-use.md)
+
+Build the site locally:
+
+```bash
+uv run zensical build --clean
+```
+
+Background research (surface inventory, finvizfinance audit, Yahoo overlap,
+snapshot-history semantics) lives under
+[`docs/research/`](docs/research) and
+[`docs/brainstorming/`](docs/brainstorming); the
+[foundation design](docs/superpowers/specs/2026-08-27-finvizp-foundation-design.md)
+tracks the approved architecture. Publication mechanics:
+[`docs/publishing.md`](docs/publishing.md).
+
+## Development
+
+```bash
+uv sync --all-groups
+uv run pytest
+uv run ruff format --check . && uv run ruff check .
+uv run ty check src
+uv build
+```
+
+## Access policy
+
+Finviz public pages, Elite features, and export/API endpoints carry
+different entitlements. `finvizp` does not automate login, solve challenges,
+bypass access controls, or rotate proxies to evade limits. Callers are
+responsible for valid access and data-use rights. See
+[access & responsible use](docs/user/explanation/access-and-responsible-use.md).

finvizp-0.2.2/README.md

@@ -0,0 +1,144 @@
+# finvizp
+
+[![CI](https://github.com/legout/finvizp/actions/workflows/ci.yml/badge.svg)](https://github.com/legout/finvizp/actions/workflows/ci.yml)
+[![Python 3.11-3.14](https://img.shields.io/badge/python-3.11--3.14-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+**Finviz for Python** — an unofficial, async-first, Arrow-native Finviz client
+built on [`fastreq`](https://pypi.org/project/fastreq/), direct lxml, and
+PyArrow.
+
+> [!IMPORTANT]
+> `finvizp` is not affiliated with, endorsed by, or sponsored by Finviz.
+> Finviz is a trademark of its respective owner.
+
+## Install
+
+```bash
+uv add finvizp  # or: pip install finvizp
+```
+
+## Quick start
+
+Async-first:
+
+```python
+import asyncio
+import finvizp
+
+
+async def main() -> None:
+    async with finvizp.FinvizClient() as client:
+        universe = await finvizp.symbols_async(client=client)
+        bundle = await finvizp.quote_async("AAPL", client=client)
+        print(bundle.data.snapshot.num_rows)
+
+
+asyncio.run(main())
+```
+
+Every operation has a **sync twin** (same name, no `_async` suffix) for
+scripts and notebooks:
+
+```python
+import finvizp
+
+matches = finvizp.search_symbols("APPLE")
+income = finvizp.statements("AAPL", statement="IA")  # IA/IQ/BA/BQ/CA/CQ
+snap = finvizp.snapshot("AAPL")  # cached, no 2nd request
+quote = finvizp.quote("AAPL")  # complete bundle
+universe = finvizp.symbols()
+finvizp.capabilities()  # implemented/planned ledger
+```
+
+Sync twins reject an active event loop; results, caching, and errors are
+identical.
+
+## What's implemented
+
+| Milestone | Surface | Status |
+|---|---|---|
+| 0.1 | Symbols, statements, quote bundles, cache | ✅ |
+| 0.2 | Screener, signals/earnings, registry drift tools | ✅ |
+| 0.3 | Groups, spectrum, maps, news, insider, calendar | ✅ |
+| 0.4 | Markets, artifacts (charts/spectrum), forex/crypto, futures | ✅ |
+| 0.5 | Frozen-surface + finvizfinance parity audit | ✅ |
+| 1.0 | Stable release | pending |
+
+The full implemented/planned ledger lives in the
+[capability matrix](docs/user/reference/capability-matrix.md) and
+`finvizp.capabilities()`.
+
+## Design in one screen
+
+- **Async-first with sync twins** — one transport, no hidden event loops.
+- **Arrow-native** — every dataset is a versioned, deterministic Arrow table.
+- **Immutable `FetchResult[T]`** — full provenance, typed partial/error
+  diagnostics, no in-place mutation.
+- **Complete compound bundles** — e.g. a quote page yields every relation in
+  one fetch; cache-preserving projections (`snapshot`, `ratings`, `news`,
+  `insider`, `peers`, `etf_holders`) never re-request.
+- **Structured-first sources** — public JSON/XHR or embedded payloads when
+  same-tier, complete, direct, and snapshot-coherent; lxml parsing otherwise.
+- **Explicit proxies, route-isolated auth, conservative pacing/retries,
+  bounded result caching, single-flight coalescing.** A per-client 429
+  circuit breaker trips after 3 consecutive rate limits and fails fast
+  (`CircuitOpenError`, no request sent) until the cooldown passes.
+- **No** login/browser automation, bulk crawling, pandas contract,
+  persistence layer, telemetry, or entitlement bypass.
+
+## Documentation
+
+User docs (Diataxis — tutorials, how-to, reference, explanation), rendered
+with [Zensical](https://zensical.org) from
+[`docs/user/`](docs/user/):
+
+| You want to… | Go to |
+|---|---|
+| Try it in 5 minutes | [Get started](docs/user/tutorials/get-started.md) |
+| Use the sync API | [Use the sync API](docs/user/how-to/sync-api.md) |
+| Set proxies / caching | [Proxies & cache](docs/user/how-to/proxies-and-cache.md) |
+| Migrate from `finvizfinance` | [Migration guide](docs/user/how-to/migrate-from-finvizfinance.md) |
+| Check a dataset's columns | [Arrow schemas](docs/user/reference/schemas-0.1.md) |
+| Understand result envelopes | [Results](docs/user/reference/results.md) |
+| See every capability + status | [Capability matrix](docs/user/reference/capability-matrix.md) |
+
+Deep links: [screener](docs/user/reference/screener.md) ·
+[screener registry](docs/user/reference/screener-registry.md) ·
+[groups/maps/events](docs/user/reference/groups-maps-events.md) ·
+[markets/artifacts](docs/user/reference/markets-and-artifacts.md) ·
+[schema versioning](docs/user/reference/schema-versioning.md) ·
+[keep your own history](docs/user/how-to/caller-owned-history.md) ·
+[access & responsible use](docs/user/explanation/access-and-responsible-use.md)
+
+Build the site locally:
+
+```bash
+uv run zensical build --clean
+```
+
+Background research (surface inventory, finvizfinance audit, Yahoo overlap,
+snapshot-history semantics) lives under
+[`docs/research/`](docs/research) and
+[`docs/brainstorming/`](docs/brainstorming); the
+[foundation design](docs/superpowers/specs/2026-08-27-finvizp-foundation-design.md)
+tracks the approved architecture. Publication mechanics:
+[`docs/publishing.md`](docs/publishing.md).
+
+## Development
+
+```bash
+uv sync --all-groups
+uv run pytest
+uv run ruff format --check . && uv run ruff check .
+uv run ty check src
+uv build
+```
+
+## Access policy
+
+Finviz public pages, Elite features, and export/API endpoints carry
+different entitlements. `finvizp` does not automate login, solve challenges,
+bypass access controls, or rotate proxies to evade limits. Callers are
+responsible for valid access and data-use rights. See
+[access & responsible use](docs/user/explanation/access-and-responsible-use.md).

finvizp-0.2.2/pyproject.toml

@@ -0,0 +1,89 @@
+[project]
+name = "finvizp"
+version = "0.2.2"
+description = "Async, Arrow-native Python client for the public Finviz data surface."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+keywords = [
+    "finviz",
+    "finance",
+    "stocks",
+    "pyarrow",
+    "async",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Office/Business :: Financial :: Investment",
+]
+dependencies = [
+    "fastreq[curl]>=3.2.0",
+    "lxml>=6.0.0",
+    "pyarrow>=18.0.0",
+]
+
+[[project.authors]]
+name = "Volker Lorrmann"
+email = "volker.lorrmann@gmail.com"
+
+[project.urls]
+Homepage = "https://github.com/legout/finvizp"
+Repository = "https://github.com/legout/finvizp"
+Issues = "https://github.com/legout/finvizp/issues"
+Documentation = "https://github.com/legout/finvizp/tree/main/docs"
+
+[dependency-groups]
+dev = [
+    "mkdocstrings-python>=2.0.7",
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "ruff>=0.8.0",
+    "ty>=0.0.1a1",
+    "zensical>=0.0.57",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.8,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "finvizp"
+module-root = "src"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+filterwarnings = [
+    "error",
+    "ignore::DeprecationWarning",
+]
+markers = [
+    "live_public: bounded opt-in checks against public Finviz surfaces",
+    "live_elite: bounded opt-in checks requiring legitimate authenticated state",
+]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "W",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+    "RUF",
+]
+
+[tool.ty.environment]
+python-version = "3.11"

finvizp-0.2.2/pyproject.toml.orig

@@ -0,0 +1,64 @@
+[project]
+name = "finvizp"
+version = "0.2.2"
+description = "Async, Arrow-native Python client for the public Finviz data surface."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Volker Lorrmann", email = "volker.lorrmann@gmail.com" }]
+requires-python = ">=3.11"
+keywords = ["finviz", "finance", "stocks", "pyarrow", "async"]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Office/Business :: Financial :: Investment",
+]
+dependencies = ["fastreq[curl]>=3.2.0", "lxml>=6.0.0", "pyarrow>=18.0.0"]
+
+[project.urls]
+Homepage = "https://github.com/legout/finvizp"
+Repository = "https://github.com/legout/finvizp"
+Issues = "https://github.com/legout/finvizp/issues"
+Documentation = "https://github.com/legout/finvizp/tree/main/docs"
+
+[dependency-groups]
+dev = [
+  "mkdocstrings-python>=2.0.7",
+  "pytest>=8.0.0",
+  "pytest-asyncio>=0.24.0",
+  "ruff>=0.8.0",
+  "ty>=0.0.1a1",
+  "zensical>=0.0.57",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.8,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "finvizp"
+module-root = "src"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+filterwarnings = ["error", "ignore::DeprecationWarning"]
+markers = [
+  "live_public: bounded opt-in checks against public Finviz surfaces",
+  "live_elite: bounded opt-in checks requiring legitimate authenticated state",
+]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.ty.environment]
+python-version = "3.11"