Metadata-Version: 2.4
Name: tvfinance
Version: 1.0.1
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.
