TradeChart 2.0.0__tar.gz

tradechart-2.0.0/LICENSE

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

tradechart-2.0.0/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: TradeChart
+Version: 2.0.0
+Summary: Production-quality financial chart generator — candlestick, line, area, OHLC, Heikin-Ashi with technical indicators.
+Author-email: "TRADELY.DEV" <dev@tradely.dev>
+License: MIT
+Project-URL: Homepage, https://github.com/techareaone/TradeChart
+Project-URL: Documentation, https://doc.tradely.dev
+Project-URL: Repository, https://github.com/techareaone/TradeChart
+Project-URL: Issues, https://github.com/techareaone/TradeChart/issues
+Project-URL: Changelog, https://github.com/techareaone/TradeChart/blob/main/CHANGELOG.md
+Keywords: finance,chart,candlestick,stock,trading,ohlc,technical-analysis,matplotlib,yfinance
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: pandas>=2.0
+Requires-Dist: yfinance>=0.2.18
+Requires-Dist: numpy>=1.24
+Provides-Extra: tradingview
+Requires-Dist: tvDatafeed>=2.1; extra == "tradingview"
+Provides-Extra: mplfinance
+Requires-Dist: mplfinance>=0.12; extra == "mplfinance"
+Provides-Extra: xlsx
+Requires-Dist: openpyxl>=3.1; extra == "xlsx"
+Provides-Extra: all
+Requires-Dist: tvDatafeed>=2.1; extra == "all"
+Requires-Dist: mplfinance>=0.12; extra == "all"
+Requires-Dist: openpyxl>=3.1; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# TradeChart — Library Edition v2.0.0
+
+**Python → Financial Charts**
+Generate production-quality candlestick, line, area, and OHLC charts from code.
+
+## Quick Start
+
+```python
+import tradechart as tc
+
+tc.terminal("full")
+tc.chart("AAPL", "1mo", "candle", indicators=["sma", "bollinger"])
+```
+
+## API Reference
+
+| Command | Required | Default | Description |
+|---|---|---|---|
+| `tc.terminal(mode)` | No | `"on_done"` | Set logging verbosity |
+| `tc.theme(name)` | No | `"dark"` | Set chart colour theme |
+| `tc.watermark(enabled)` | No | `True` | Toggle the TRADELY logo watermark |
+| `tc.config(**kwargs)` | No | — | Batch-set global options (see below) |
+| `tc.chart(...)` | — | — | Fetch data and render a chart image |
+| `tc.compare(...)` | — | — | Overlay multiple tickers on one chart |
+| `tc.data(...)` | — | — | Fetch raw OHLCV data as a DataFrame |
+| `tc.export(...)` | — | — | Export market data to CSV / JSON / XLSX |
+| `tc.clear_cache()` | No | — | Flush the in-memory data cache |
+
+## `tc.chart()` — Render a Chart
+
+```python
+path = tc.chart(
+    "AAPL",
+    duration="3mo",
+    chart_type="candle",
+    indicators=["sma", "rsi", "macd"],
+    show_volume=True,
+    fmt="png",
+    output_location="./charts",
+    output_name="apple_q1.png",
+)
+print(f"Saved → {path}")
+```
+
+| Parameter | Required | Default | Description |
+|---|---|---|---|
+| `ticker` | Yes | — | Instrument symbol — `"AAPL"`, `"BTC-USD"`, `"EURUSD=X"` |
+| `duration` | No | `"1mo"` | Time span (see Durations below) |
+| `chart_type` | No | `"candle"` | `"candle"` `"line"` `"ohlc"` `"area"` `"heikin_ashi"` |
+| `output_location` | No | cwd | Directory for the output file |
+| `output_name` | No | auto | Filename — defaults to `{TICKER}_{duration}_{type}.{fmt}` |
+| `fmt` | No | `"png"` | `"png"` `"jpg"` `"svg"` `"pdf"` `"webp"` |
+| `indicators` | No | None | List of indicator names (see Indicators below) |
+| `show_volume` | No | `True` | Show volume sub-panel |
+
+## `tc.compare()` — Multi-Ticker Overlay
+
+```python
+path = tc.compare(
+    ["AAPL", "MSFT", "GOOG"],
+    duration="6mo",
+    normalise=True,
+    fmt="png",
+)
+```
+
+| Parameter | Required | Default | Description |
+|---|---|---|---|
+| `tickers` | Yes | — | 2–8 ticker symbols to compare |
+| `duration` | No | `"1mo"` | Shared time span |
+| `normalise` | No | `True` | Show percentage change from period start |
+| `output_location` | No | cwd | Output directory |
+| `output_name` | No | auto | Output filename |
+| `fmt` | No | `"png"` | Output format |
+
+## `tc.data()` — Raw Data
+
+```python
+df = tc.data("TSLA", "3mo")
+print(df.head())
+```
+
+Returns a `pandas.DataFrame` with columns `Open`, `High`, `Low`, `Close`, `Volume` and a `DatetimeIndex`.
+
+## `tc.export()` — Export Data
+
+```python
+path = tc.export("AAPL", "1y", fmt="csv", output_location="./exports")
+```
+
+| Parameter | Required | Default | Description |
+|---|---|---|---|
+| `ticker` | Yes | — | Instrument symbol |
+| `duration` | No | `"1mo"` | Time span |
+| `fmt` | No | `"csv"` | `"csv"` `"json"` `"xlsx"` |
+| `output_location` | No | cwd | Output directory |
+| `output_name` | No | auto | Output filename |
+
+## Durations
+
+| Value | Period |
+|---|---|
+| `"1d"` | 1 day (5-min bars) |
+| `"5d"` | 5 days (15-min bars) |
+| `"1mo"` | 1 month (daily) |
+| `"3mo"` | 3 months (daily) |
+| `"6mo"` | 6 months (daily) |
+| `"1y"` | 1 year (weekly) |
+| `"2y"` | 2 years (weekly) |
+| `"5y"` | 5 years (weekly) |
+| `"10y"` | 10 years (monthly) |
+| `"max"` | All available (monthly) |
+
+## Indicators
+
+| Name | Panel | Description |
+|---|---|---|
+| `"sma"` | Price overlay | Simple Moving Average (20) |
+| `"ema"` | Price overlay | Exponential Moving Average (20) |
+| `"bollinger"` | Price overlay | Bollinger Bands (20, 2σ) |
+| `"vwap"` | Price overlay | Volume-Weighted Average Price |
+| `"rsi"` | Sub-panel | Relative Strength Index (14) |
+| `"macd"` | Sub-panel | MACD (12/26/9) |
+| `"volume"` | Sub-panel | Volume bars |
+
+## Themes
+
+| Name | Background | Style |
+|---|---|---|
+| `"dark"` | `#1e1e2f` | Dark mode — green/red candles |
+| `"light"` | `#ffffff` | Light mode — green/red candles |
+| `"classic"` | `#f5f5dc` | Parchment — dark green/dark red candles, visible spines |
+
+```python
+tc.theme("light")
+tc.chart("MSFT", "6mo", "candle")
+```
+
+## Terminal Modes
+
+Control how much console output TradeChart produces.
+
+| Mode | What prints | Best for |
+|---|---|---|
+| `"full"` | Every step, every log line, full detail | Debugging |
+| `"on_done"` | Summary after completion | Normal use |
+| `"none"` | Nothing at all — complete silence | Production / scripting |
+
+## `tc.config()` — Batch Settings
+
+```python
+tc.config(
+    theme="light",
+    dpi=200,
+    overwrite=True,
+    fig_size=(16, 9),
+    cache_ttl=600,
+)
+```
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `terminal` | str | `"on_done"` | Logging mode |
+| `theme` | str | `"dark"` | Colour theme |
+| `watermark` | bool | `True` | TRADELY logo on/off |
+| `overwrite` | bool | `False` | Allow overwriting existing files |
+| `dpi` | int | `150` | Output resolution (50–600) |
+| `fig_size` | tuple | `(14, 7)` | Figure dimensions in inches |
+| `cache_ttl` | int | `300` | Data cache time-to-live in seconds |
+
+## Data Providers
+
+TradeChart tries providers in order and falls back automatically:
+
+| Priority | Provider | Requires |
+|---|---|---|
+| 1 | yfinance | `pip install yfinance` (included) |
+| 2 | TradingView | `pip install tvDatafeed` (optional) |
+| 3 | Stooq | Nothing (free CSV endpoint) |
+
+If yfinance returns data, TradingView and Stooq are never called. If yfinance fails, the next provider is tried, and so on.
+
+## Installation
+
+```bash
+pip install TradeChart
+```
+
+With optional extras:
+
+```bash
+pip install TradeChart[all]          # TradingView + mplfinance + xlsx export
+pip install TradeChart[tradingview]  # TradingView fallback provider
+pip install TradeChart[mplfinance]   # Enhanced candlestick rendering
+pip install TradeChart[xlsx]         # Excel export support
+```
+
+---
+
+## Notes
+
+- **Caching**: Fetched data is cached in-memory for `cache_ttl` seconds (default 300). Call `tc.clear_cache()` to force a re-fetch.
+
+- **File collisions**: By default, TradeChart appends `_1`, `_2`, etc. if the output file already exists. Set `tc.config(overwrite=True)` to overwrite instead.
+
+- **Watermark**: The TRADELY logo is stamped in the bottom-left corner by default. Disable with `tc.watermark(False)` or `tc.config(watermark=False)`.
+
+- **Thread safety**: The global settings singleton and engine initialisation are thread-safe. You can call `tc.chart()` from multiple threads.
+
+- **Heikin-Ashi**: The `"heikin_ashi"` chart type converts standard OHLC data to Heikin-Ashi candles before rendering — the original data is not modified.
+
+- **mplfinance**: If `mplfinance` is installed, candlestick charts use it for higher-quality rendering. Otherwise, a pure-matplotlib fallback is used automatically.
+
+## Further Details
+
+Check out [TradeChart by TRADELY](https://doc.tradely.dev)
+
+PyPI Library available at: [PyPI TradeChart](https://pypi.org/project/TradeChart/)
+
+Use the README there to set up the library.

tradechart-2.0.0/README.md

@@ -0,0 +1,220 @@
+# TradeChart — Library Edition v2.0.0
+
+**Python → Financial Charts**
+Generate production-quality candlestick, line, area, and OHLC charts from code.
+
+## Quick Start
+
+```python
+import tradechart as tc
+
+tc.terminal("full")
+tc.chart("AAPL", "1mo", "candle", indicators=["sma", "bollinger"])
+```
+
+## API Reference
+
+| Command | Required | Default | Description |
+|---|---|---|---|
+| `tc.terminal(mode)` | No | `"on_done"` | Set logging verbosity |
+| `tc.theme(name)` | No | `"dark"` | Set chart colour theme |
+| `tc.watermark(enabled)` | No | `True` | Toggle the TRADELY logo watermark |
+| `tc.config(**kwargs)` | No | — | Batch-set global options (see below) |
+| `tc.chart(...)` | — | — | Fetch data and render a chart image |
+| `tc.compare(...)` | — | — | Overlay multiple tickers on one chart |
+| `tc.data(...)` | — | — | Fetch raw OHLCV data as a DataFrame |
+| `tc.export(...)` | — | — | Export market data to CSV / JSON / XLSX |
+| `tc.clear_cache()` | No | — | Flush the in-memory data cache |
+
+## `tc.chart()` — Render a Chart
+
+```python
+path = tc.chart(
+    "AAPL",
+    duration="3mo",
+    chart_type="candle",
+    indicators=["sma", "rsi", "macd"],
+    show_volume=True,
+    fmt="png",
+    output_location="./charts",
+    output_name="apple_q1.png",
+)
+print(f"Saved → {path}")
+```
+
+| Parameter | Required | Default | Description |
+|---|---|---|---|
+| `ticker` | Yes | — | Instrument symbol — `"AAPL"`, `"BTC-USD"`, `"EURUSD=X"` |
+| `duration` | No | `"1mo"` | Time span (see Durations below) |
+| `chart_type` | No | `"candle"` | `"candle"` `"line"` `"ohlc"` `"area"` `"heikin_ashi"` |
+| `output_location` | No | cwd | Directory for the output file |
+| `output_name` | No | auto | Filename — defaults to `{TICKER}_{duration}_{type}.{fmt}` |
+| `fmt` | No | `"png"` | `"png"` `"jpg"` `"svg"` `"pdf"` `"webp"` |
+| `indicators` | No | None | List of indicator names (see Indicators below) |
+| `show_volume` | No | `True` | Show volume sub-panel |
+
+## `tc.compare()` — Multi-Ticker Overlay
+
+```python
+path = tc.compare(
+    ["AAPL", "MSFT", "GOOG"],
+    duration="6mo",
+    normalise=True,
+    fmt="png",
+)
+```
+
+| Parameter | Required | Default | Description |
+|---|---|---|---|
+| `tickers` | Yes | — | 2–8 ticker symbols to compare |
+| `duration` | No | `"1mo"` | Shared time span |
+| `normalise` | No | `True` | Show percentage change from period start |
+| `output_location` | No | cwd | Output directory |
+| `output_name` | No | auto | Output filename |
+| `fmt` | No | `"png"` | Output format |
+
+## `tc.data()` — Raw Data
+
+```python
+df = tc.data("TSLA", "3mo")
+print(df.head())
+```
+
+Returns a `pandas.DataFrame` with columns `Open`, `High`, `Low`, `Close`, `Volume` and a `DatetimeIndex`.
+
+## `tc.export()` — Export Data
+
+```python
+path = tc.export("AAPL", "1y", fmt="csv", output_location="./exports")
+```
+
+| Parameter | Required | Default | Description |
+|---|---|---|---|
+| `ticker` | Yes | — | Instrument symbol |
+| `duration` | No | `"1mo"` | Time span |
+| `fmt` | No | `"csv"` | `"csv"` `"json"` `"xlsx"` |
+| `output_location` | No | cwd | Output directory |
+| `output_name` | No | auto | Output filename |
+
+## Durations
+
+| Value | Period |
+|---|---|
+| `"1d"` | 1 day (5-min bars) |
+| `"5d"` | 5 days (15-min bars) |
+| `"1mo"` | 1 month (daily) |
+| `"3mo"` | 3 months (daily) |
+| `"6mo"` | 6 months (daily) |
+| `"1y"` | 1 year (weekly) |
+| `"2y"` | 2 years (weekly) |
+| `"5y"` | 5 years (weekly) |
+| `"10y"` | 10 years (monthly) |
+| `"max"` | All available (monthly) |
+
+## Indicators
+
+| Name | Panel | Description |
+|---|---|---|
+| `"sma"` | Price overlay | Simple Moving Average (20) |
+| `"ema"` | Price overlay | Exponential Moving Average (20) |
+| `"bollinger"` | Price overlay | Bollinger Bands (20, 2σ) |
+| `"vwap"` | Price overlay | Volume-Weighted Average Price |
+| `"rsi"` | Sub-panel | Relative Strength Index (14) |
+| `"macd"` | Sub-panel | MACD (12/26/9) |
+| `"volume"` | Sub-panel | Volume bars |
+
+## Themes
+
+| Name | Background | Style |
+|---|---|---|
+| `"dark"` | `#1e1e2f` | Dark mode — green/red candles |
+| `"light"` | `#ffffff` | Light mode — green/red candles |
+| `"classic"` | `#f5f5dc` | Parchment — dark green/dark red candles, visible spines |
+
+```python
+tc.theme("light")
+tc.chart("MSFT", "6mo", "candle")
+```
+
+## Terminal Modes
+
+Control how much console output TradeChart produces.
+
+| Mode | What prints | Best for |
+|---|---|---|
+| `"full"` | Every step, every log line, full detail | Debugging |
+| `"on_done"` | Summary after completion | Normal use |
+| `"none"` | Nothing at all — complete silence | Production / scripting |
+
+## `tc.config()` — Batch Settings
+
+```python
+tc.config(
+    theme="light",
+    dpi=200,
+    overwrite=True,
+    fig_size=(16, 9),
+    cache_ttl=600,
+)
+```
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `terminal` | str | `"on_done"` | Logging mode |
+| `theme` | str | `"dark"` | Colour theme |
+| `watermark` | bool | `True` | TRADELY logo on/off |
+| `overwrite` | bool | `False` | Allow overwriting existing files |
+| `dpi` | int | `150` | Output resolution (50–600) |
+| `fig_size` | tuple | `(14, 7)` | Figure dimensions in inches |
+| `cache_ttl` | int | `300` | Data cache time-to-live in seconds |
+
+## Data Providers
+
+TradeChart tries providers in order and falls back automatically:
+
+| Priority | Provider | Requires |
+|---|---|---|
+| 1 | yfinance | `pip install yfinance` (included) |
+| 2 | TradingView | `pip install tvDatafeed` (optional) |
+| 3 | Stooq | Nothing (free CSV endpoint) |
+
+If yfinance returns data, TradingView and Stooq are never called. If yfinance fails, the next provider is tried, and so on.
+
+## Installation
+
+```bash
+pip install TradeChart
+```
+
+With optional extras:
+
+```bash
+pip install TradeChart[all]          # TradingView + mplfinance + xlsx export
+pip install TradeChart[tradingview]  # TradingView fallback provider
+pip install TradeChart[mplfinance]   # Enhanced candlestick rendering
+pip install TradeChart[xlsx]         # Excel export support
+```
+
+---
+
+## Notes
+
+- **Caching**: Fetched data is cached in-memory for `cache_ttl` seconds (default 300). Call `tc.clear_cache()` to force a re-fetch.
+
+- **File collisions**: By default, TradeChart appends `_1`, `_2`, etc. if the output file already exists. Set `tc.config(overwrite=True)` to overwrite instead.
+
+- **Watermark**: The TRADELY logo is stamped in the bottom-left corner by default. Disable with `tc.watermark(False)` or `tc.config(watermark=False)`.
+
+- **Thread safety**: The global settings singleton and engine initialisation are thread-safe. You can call `tc.chart()` from multiple threads.
+
+- **Heikin-Ashi**: The `"heikin_ashi"` chart type converts standard OHLC data to Heikin-Ashi candles before rendering — the original data is not modified.
+
+- **mplfinance**: If `mplfinance` is installed, candlestick charts use it for higher-quality rendering. Otherwise, a pure-matplotlib fallback is used automatically.
+
+## Further Details
+
+Check out [TradeChart by TRADELY](https://doc.tradely.dev)
+
+PyPI Library available at: [PyPI TradeChart](https://pypi.org/project/TradeChart/)
+
+Use the README there to set up the library.