tvfinance 1.0.0__tar.gz

tvfinance-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Run Ruff Lint
+        run: uv run ruff check .
+
+      - name: Run Ruff Format Check
+        run: uv run ruff format --check .
+
+      - name: Run tests
+        run: uv run pytest

tvfinance-1.0.0/.github/workflows/docs.yml

@@ -0,0 +1,35 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Build and Deploy documentation
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          uv run mkdocs gh-deploy --force

tvfinance-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build-and-publish:
+    name: Build and publish Python distribution to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      # This permission is required for Trusted Publishing / OIDC
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Build package distribution
+        run: uv build
+
+      - name: Publish package distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+

tvfinance-1.0.0/.gitignore

@@ -0,0 +1,19 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Cache directories
+.ruff_cache/
+.pytest_cache/
+
+# MkDocs build outputs
+site/
+
+

tvfinance-1.0.0/.python-version

@@ -0,0 +1 @@
+3.10

tvfinance-1.0.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [1.0.0] - 2026-06-20
+
+### Added
+- **Initial Release of tvfinance**: A unified lightweight library for querying TradingView financial and general market data.
+- **Dual Namespace Structure**: Supports both synchronous (`tvfinance`) and asynchronous (`tvfinance.aio`) APIs.
+- **Object-Oriented Wrappers**: Features sync `Ticker`/`Tickers` and async `Ticker`/`Tickers` (under `tvfinance.aio`) wrapper classes.
+- **Connection Reuse Context**: Includes `Session` and `AsyncSession` context managers using `contextvars` for pooling.
+- **Comprehensive Scrapers**: Support for Quotes, History, Options, News, Calendars, Forecasts, and Technical Indicators.

tvfinance-1.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Community Pledge
+
+All participants, contributors, and maintainers pledge to make participation in this
+project a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+All participants pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Community Standards
+
+Examples of behavior that contributes to a positive environment for the
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by mistakes,
+  and learning from the experience
+* Focusing on what is best for the overall community, not just the individual
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and unwelcome sexual attention or
+  advances
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Repository maintainers are responsible for clarifying and enforcing the standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Repository maintainers have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all project spaces, and also applies when
+an individual is officially representing the project in public spaces.
+Examples of representing the project include using an official e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the repository maintainers via GitHub Issues. All complaints
+will be reviewed and investigated promptly and fairly.
+
+All repository maintainers are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][version].
+
+[homepage]: https://www.contributor-covenant.org
+[version]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

tvfinance-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# Contributing to tvfinance
+
+Thank you for your interest in contributing to `tvfinance`! We welcome bug reports, feature suggestions, documentation enhancements, and pull requests.
+
+---
+
+## Development Setup
+
+We use `uv` for python dependency and virtual environment management.
+
+1. **Clone the Repository**:
+   ```bash
+   git clone https://github.com/adrianeth/tvfinance.git
+   cd tvfinance
+   ```
+
+2. **Install Development Dependencies**:
+   Install the package in editable mode with all dependency groups (`dev`, `lint`, `docs`):
+   ```bash
+   uv sync --all-groups
+   ```
+
+---
+
+## Code Quality, Linting & Formatting
+
+To maintain a clean and consistent codebase, we enforce code quality checks using **Ruff**. All pull requests are checked for style conformity.
+
+1. **Lint Checks**:
+   Analyze the codebase for bugs, syntax errors, and style violations:
+   ```bash
+   uv run ruff check .
+   ```
+
+2. **Auto-Formatting**:
+   Automatically format code imports and layout before committing changes:
+   ```bash
+   uv run ruff format .
+   ```
+
+3. **Auto-Fixing Lint Errors**:
+   Automatically fix safe lint violations:
+   ```bash
+   uv run ruff check --fix .
+   ```
+
+---
+
+## Running Tests
+
+We use `pytest` with `pytest-asyncio` for unit testing. Always ensure the entire test suite passes before submitting a pull request.
+
+1. **Run All Tests**:
+   ```bash
+   uv run pytest
+   ```
+
+2. **Run Specific Test File**:
+   ```bash
+   uv run pytest tests/test_tickers.py
+   ```
+
+---
+
+## Documentation
+
+Documentation is built using `mkdocs` with `mkdocs-material` and `mkdocstrings`.
+
+1. **Run Dev Server Locally**:
+   Start a local hot-reloading documentation server at `http://127.0.0.1:8000`:
+   ```bash
+   uv run mkdocs serve
+   ```
+
+2. **Build Site**:
+   ```bash
+   uv run mkdocs build
+   ```
+
+---
+
+## Pull Request Checklist
+
+Before submitting a Pull Request, please ensure:
+1. All lint errors are resolved: `uv run ruff check .`
+2. Code is formatted: `uv run ruff format .`
+3. All tests pass successfully: `uv run pytest`
+4. The documentation builds cleanly without warnings: `uv run mkdocs build`
+5. You have updated `CHANGELOG.md` with a summary of your changes if applicable.

tvfinance-1.0.0/DISCLAIMER.md

@@ -0,0 +1,31 @@
+# LEGAL DISCLAIMER & TERMS OF USE
+
+> [!CAUTION]
+> **PLEASE READ THIS DISCLAIMER CAREFULLY BEFORE USING THIS SOFTWARE. BY USING OR ACCESSING THIS SOFTWARE, YOU AGREE TO BE BOUND BY ALL CLAUSES DESCRIBED HEREIN.**
+
+---
+
+### 1. Strictly for Educational & Research Purposes
+This software (`tvfinance`) is an open-source research and educational utility designed for analyzing network protocols, data structures, and web interface engineering. It is **not** a commercial product, **not** a financial advisory service, and must **never** be used for any production, commercial, or institutional purposes.
+
+### 2. No Affiliation with TradingView, Inc.
+This software is an independent, community-driven project. It has **no** affiliation, sponsorship, authorization, endorsement, or validation from TradingView, Inc., or any of its data providers or partners. All product names, logos, brands, and trademarks (including "TradingView") are the property of their respective owners.
+
+### 3. Absolute Waiver of Liability
+To the maximum extent permitted by applicable law, the author(s), maintainer(s), and contributor(s) of this project:
+- **DISCLAIM ALL WARRANTIES**, express or implied, including but not limited to the warranties of merchantability and fitness for a particular purpose.
+- **ACCEPT ZERO LIABILITY** for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, IP bans, network blockages, service disruptions, account suspensions, financial losses, or trading losses) arising in any way out of the use of this software, even if advised of the possibility of such damage.
+
+### 4. End-User Compliance & Responsibility
+The execution of this software is controlled solely by the end-user. All network requests originate from the end-user's local computer/network and use the end-user's internet connection. 
+- The end-user assumes **sole and absolute responsibility** for ensuring that their use of this software complies with TradingView's Terms of Service, Privacy Policy, local laws, and regulations.
+- The author **does not condone, encourage, or facilitate** automated scraping, commercial data exploitation, or any access patterns that violate the platform's terms.
+
+### 5. No Reverse Engineering or Security Bypassing
+This software **does not** decrypt, crack, or bypass any password protection, access control system, or digital rights management (DRM) mechanisms implemented by TradingView, Inc. It only queries and formats publicly visible data endpoints accessible to any standard web browser.
+
+### 6. No Data Redistribution
+This software does not host, cache, distribute, or store any market data. It is a client-side formatting script. All requests are real-time, client-to-host queries.
+
+### 7. Immediate Compliance & Takedown Policy
+The author respects all intellectual property rights and platform terms. If TradingView, Inc., or its authorized legal representatives request the removal of this repository, the author will comply and take down the repository immediately.

tvfinance-1.0.0/LICENSE

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

tvfinance-1.0.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: tvfinance
+Version: 1.0.0
+Summary: Python tools for TradingView finance data research
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: curl-cffi>=0.15.0
+Requires-Dist: lxml
+Description-Content-Type: text/markdown
+
+# tvfinance
+
+A lightweight, high-performance Python package for querying TradingView financial and general market data synchronously and asynchronously.
+
+> [!CAUTION]
+> **CRITICAL LEGAL NOTICE & DISCLAIMER: READ BEFORE USE**
+>
+> **BEFORE ACCESSING OR USING THIS REPOSITORY, YOU MUST READ AND AGREE TO THE FULL [LEGAL DISCLAIMER & TERMS OF USE](DISCLAIMER.md).**
+>
+> 1. **STRICTLY FOR EDUCATIONAL & PERSONAL RESEARCH ONLY**: This project (`tvfinance`) is an open-source educational research tool designed to analyze web protocols. It is **NOT** a commercial product, **NOT** a financial service, and **MUST NOT** be used for production or commercial purposes.
+> 2. **NO AFFILIATION WITH TRADINGVIEW**: This library is **NOT** affiliated with, sponsored by, endorsed by, or associated with TradingView, Inc. or any of its partners or affiliates. "TradingView" is a registered trademark of TradingView, Inc.
+> 3. **USE AT YOUR OWN RISK (NO WARRANTY)**: This software is provided "AS IS", without warranty of any kind, express or implied. The author, contributors, and maintainers **ACCEPT ZERO LIABILITY** for any damages, losses, server bans, IP blocks, or account suspensions that may result from using this software.
+> 4. **COMPLIANCE & TERMS OF SERVICE**: Users are solely and fully responsible for ensuring compliance with TradingView's Terms of Use, policies, and local laws. The author does **not** encourage, condone, or facilitate automated scraping, commercial exploitation, or any access patterns that violate TradingView's policies.
+> 5. **NO FINANCIAL OR INVESTMENT ADVICE**: Any data retrieved by this tool is strictly informational. It does **not** constitute financial, trading, or investment advice. The author is **not** a financial advisor and shall **not** be held liable for any trading decisions or investment losses.
+
+---
+
+## Features
+
+- **Real-Time Quotes**: Stream or fetch real-time quotes including prices, change percentages, and company logos.
+- **Historical Data**: Fetch OHLCV bar data with custom timeframes and resolutions.
+- **Economic Calendar**: Query upcoming or past economic events with date, country, and importance filters.
+- **Fundamental & Company Data**: Extract Bonds, ETFs, SEC Documents, Holdings, community Ideas, and Financial Overview.
+- **Search**: Dynamic fuzzy symbol search supporting econometrics and FRED data.
+- **Option Chains**: Fetch and pair options contracts cleanly.
+
+## Installation
+
+Install using `pip` from a local directory or your preferred method:
+
+```bash
+pip install tvfinance
+```
+
+Or using `uv`:
+
+```bash
+uv add tvfinance
+```
+
+## Quickstart
+
+### Ticker Wrapper
+
+The `Ticker` class wraps all functional interfaces into an object-oriented package:
+
+```python
+from tvfinance import Ticker
+
+# Instantiate a ticker (requires exchange prefix)
+aapl = Ticker("NASDAQ:AAPL")
+
+# Get real-time quote
+quote = aapl.quote()
+print(f"Price: {quote.last} | Logo: {quote.logo_url}")
+
+# Fetch 30 daily price bars (OHLCV)
+history = aapl.history(count=30)
+
+# Fetch company profile & fundamentals
+profile = aapl.profile()
+print(f"CEO: {profile['ceo']} | Market Cap: {profile['market_cap']}")
+```
+
+### Economic Calendar
+
+Query global economic events:
+
+```python
+from tvfinance import calendar
+
+events = calendar(countries="US,JP", importance=1)
+for event in events[:3]:
+    print(f"[{event['date']}] {event['country']} - {event['title']}")
+```
+
+## Command Line Interface (CLI)
+
+`tvfinance` installs a command-line interface for quick terminal queries:
+
+```bash
+# Get quote
+tvfinance quote NASDAQ:AAPL
+
+# Search economic calendar
+tvfinance calendar --countries US,JP --limit 5
+```
+
+## Documentation
+
+To build the interactive documentation site locally:
+
+```bash
+uv run mkdocs build
+uv run mkdocs serve
+```
+
+## License
+
+This project is licensed under the MIT License.

tvfinance-1.0.0/README.md

@@ -0,0 +1,100 @@
+# tvfinance
+
+A lightweight, high-performance Python package for querying TradingView financial and general market data synchronously and asynchronously.
+
+> [!CAUTION]
+> **CRITICAL LEGAL NOTICE & DISCLAIMER: READ BEFORE USE**
+>
+> **BEFORE ACCESSING OR USING THIS REPOSITORY, YOU MUST READ AND AGREE TO THE FULL [LEGAL DISCLAIMER & TERMS OF USE](DISCLAIMER.md).**
+>
+> 1. **STRICTLY FOR EDUCATIONAL & PERSONAL RESEARCH ONLY**: This project (`tvfinance`) is an open-source educational research tool designed to analyze web protocols. It is **NOT** a commercial product, **NOT** a financial service, and **MUST NOT** be used for production or commercial purposes.
+> 2. **NO AFFILIATION WITH TRADINGVIEW**: This library is **NOT** affiliated with, sponsored by, endorsed by, or associated with TradingView, Inc. or any of its partners or affiliates. "TradingView" is a registered trademark of TradingView, Inc.
+> 3. **USE AT YOUR OWN RISK (NO WARRANTY)**: This software is provided "AS IS", without warranty of any kind, express or implied. The author, contributors, and maintainers **ACCEPT ZERO LIABILITY** for any damages, losses, server bans, IP blocks, or account suspensions that may result from using this software.
+> 4. **COMPLIANCE & TERMS OF SERVICE**: Users are solely and fully responsible for ensuring compliance with TradingView's Terms of Use, policies, and local laws. The author does **not** encourage, condone, or facilitate automated scraping, commercial exploitation, or any access patterns that violate TradingView's policies.
+> 5. **NO FINANCIAL OR INVESTMENT ADVICE**: Any data retrieved by this tool is strictly informational. It does **not** constitute financial, trading, or investment advice. The author is **not** a financial advisor and shall **not** be held liable for any trading decisions or investment losses.
+
+---
+
+## Features
+
+- **Real-Time Quotes**: Stream or fetch real-time quotes including prices, change percentages, and company logos.
+- **Historical Data**: Fetch OHLCV bar data with custom timeframes and resolutions.
+- **Economic Calendar**: Query upcoming or past economic events with date, country, and importance filters.
+- **Fundamental & Company Data**: Extract Bonds, ETFs, SEC Documents, Holdings, community Ideas, and Financial Overview.
+- **Search**: Dynamic fuzzy symbol search supporting econometrics and FRED data.
+- **Option Chains**: Fetch and pair options contracts cleanly.
+
+## Installation
+
+Install using `pip` from a local directory or your preferred method:
+
+```bash
+pip install tvfinance
+```
+
+Or using `uv`:
+
+```bash
+uv add tvfinance
+```
+
+## Quickstart
+
+### Ticker Wrapper
+
+The `Ticker` class wraps all functional interfaces into an object-oriented package:
+
+```python
+from tvfinance import Ticker
+
+# Instantiate a ticker (requires exchange prefix)
+aapl = Ticker("NASDAQ:AAPL")
+
+# Get real-time quote
+quote = aapl.quote()
+print(f"Price: {quote.last} | Logo: {quote.logo_url}")
+
+# Fetch 30 daily price bars (OHLCV)
+history = aapl.history(count=30)
+
+# Fetch company profile & fundamentals
+profile = aapl.profile()
+print(f"CEO: {profile['ceo']} | Market Cap: {profile['market_cap']}")
+```
+
+### Economic Calendar
+
+Query global economic events:
+
+```python
+from tvfinance import calendar
+
+events = calendar(countries="US,JP", importance=1)
+for event in events[:3]:
+    print(f"[{event['date']}] {event['country']} - {event['title']}")
+```
+
+## Command Line Interface (CLI)
+
+`tvfinance` installs a command-line interface for quick terminal queries:
+
+```bash
+# Get quote
+tvfinance quote NASDAQ:AAPL
+
+# Search economic calendar
+tvfinance calendar --countries US,JP --limit 5
+```
+
+## Documentation
+
+To build the interactive documentation site locally:
+
+```bash
+uv run mkdocs build
+uv run mkdocs serve
+```
+
+## License
+
+This project is licensed under the MIT License.

tvfinance-1.0.0/docs/api/calendar.md

@@ -0,0 +1,55 @@
+# Calendar APIs
+
+These functions retrieve economic, earnings, dividend, and IPO events from TradingView.
+
+## Synchronous APIs
+
+### `calendar`
+::: tvfinance.calendar
+
+---
+
+### `earnings`
+::: tvfinance.earnings
+
+---
+
+### `dividends`
+::: tvfinance.dividends
+
+---
+
+### `ipo`
+::: tvfinance.ipo
+
+---
+
+### `revenue`
+::: tvfinance.revenue
+
+---
+
+## Asynchronous APIs
+
+### `calendar` (Async)
+::: tvfinance.aio.calendar
+
+---
+
+### `earnings` (Async)
+::: tvfinance.aio.earnings
+
+---
+
+### `dividends` (Async)
+::: tvfinance.aio.dividends
+
+---
+
+### `ipo` (Async)
+::: tvfinance.aio.ipo
+
+---
+
+### `revenue` (Async)
+::: tvfinance.aio.revenue

tvfinance-1.0.0/docs/api/market_data.md

@@ -0,0 +1,45 @@
+# Market Data APIs
+
+These functions provide low-level interfaces for quotes, streaming data, symbol search, and history.
+
+## Synchronous APIs
+
+### `quote`
+::: tvfinance.quote
+
+---
+
+### `stream`
+::: tvfinance.stream
+
+---
+
+### `history`
+::: tvfinance.history
+
+---
+
+### `search`
+::: tvfinance.search
+
+---
+
+## Asynchronous APIs
+
+### `quote` (Async)
+::: tvfinance.aio.quote
+
+---
+
+### `stream` (Async)
+::: tvfinance.aio.stream
+
+---
+
+### `history` (Async)
+::: tvfinance.aio.history
+
+---
+
+### `search` (Async)
+::: tvfinance.aio.search