| Name | terminal-stonks JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Terminal-based stock chart visualization library |
| upload_time | 2025-07-10 18:47:17 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License
Copyright (c) 2024 Terminal Stonks 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. |
| keywords |
stocks
charts
terminal
visualization
candlestick
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
yfinance
rich
pynput
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Terminal Stonks 📈
[](https://badge.fury.io/py/terminal-stonks)
[](https://pypi.org/project/terminal-stonks/)
[](https://opensource.org/licenses/MIT)
A Python library for rendering beautiful stock candlestick charts directly in your terminal using ASCII art and colors.
## Preview
*Example of a candlestick chart rendered in the terminal*
## Features
- 🎨 **Beautiful ASCII charts** - Render K-line/candlestick charts in your terminal
- 🌈 **Color-coded candles** - Red for bullish, green for bearish movements
- 📏 **Auto-scaling** - Charts automatically scale to fit your terminal size
- 📅 **Date labels** - X-axis shows relevant dates for better context
- 💰 **Price labels** - Y-axis displays price levels
- 🔄 **Real-time compatible** - Perfect for live data visualization
## Installation
Install from PyPI:
```bash
pip install terminal-stonks
```
Or install from source:
```bash
git clone https://github.com/yourusername/terminal-stonks.git
cd terminal-stonks
pip install -e .
```
## Quick Start
```python
import pandas as pd
from terminal_stonks import KChart
# Create sample data
data = pd.DataFrame({
'Open': [100, 102, 101, 103, 105],
'High': [105, 106, 104, 107, 108],
'Low': [99, 101, 100, 102, 104],
'Close': [102, 101, 103, 105, 107]
}, index=pd.date_range('2024-01-01', periods=5, freq='D'))
# Create and render chart
chart = KChart(data)
chart.render(title="My Stock Chart")
```
## API Reference
### KChart Class
#### `__init__(data: pd.DataFrame)`
Initialize a KChart with stock data.
**Parameters:**
- `data` (pd.DataFrame): DataFrame with columns 'Open', 'High', 'Low', 'Close' and a DatetimeIndex
**Raises:**
- `TypeError`: If the index is not a DatetimeIndex
#### `render(title: str = "")`
Render the chart to the terminal.
**Parameters:**
- `title` (str, optional): Chart title to display at the top
## Data Format
Your DataFrame should have the following structure:
```python
import pandas as pd
data = pd.DataFrame({
'Open': [float], # Opening prices
'High': [float], # Highest prices
'Low': [float], # Lowest prices
'Close': [float] # Closing prices
}, index=pd.DatetimeIndex) # Must be a DatetimeIndex
```
## Examples
### Basic Usage
```python
from terminal_stonks import KChart
import pandas as pd
# Sample OHLC data
data = pd.DataFrame({
'Open': [150.0, 152.0, 151.0, 153.0],
'High': [155.0, 156.0, 154.0, 157.0],
'Low': [149.0, 151.0, 150.0, 152.0],
'Close': [152.0, 151.0, 153.0, 155.0]
}, index=pd.date_range('2024-01-01', periods=4))
chart = KChart(data)
chart.render("AAPL Stock Chart")
```
### With Yahoo Finance Data
```python
import yfinance as yf
from terminal_stonks import KChart
# Fetch real data
ticker = yf.Ticker("AAPL")
data = ticker.history(period="1mo")
# Render chart
chart = KChart(data)
chart.render("Apple Inc. (AAPL) - Last 30 Days")
```
**Example Output:**
## Chart Components
- **Candlestick Body**: Represented by `█` characters
- Red: Bullish (Close > Open)
- Green: Bearish (Close < Open)
- **Shadows/Wicks**: Represented by `│` characters
- **Price Scale**: Left side Y-axis with price levels
- **Date Labels**: Bottom X-axis with date information
## Requirements
- Python 3.8+
- pandas >= 1.3.0
- rich >= 10.0.0
## Development
To set up for development:
```bash
git clone https://github.com/yourusername/terminal-stonks.git
cd terminal-stonks
pip install -e ".[dev]"
```
Run tests:
```bash
pytest
```
Format code:
```bash
black terminal_stonks/
```
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
### Generating Example Screenshots
To update the example image (`images/example.png`):
```bash
# Run the screenshot-friendly script
python scripts/generate_example.py
# Take a screenshot when the chart appears
# Save as images/example.png
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- Built with [Rich](https://github.com/Textualize/rich) for beautiful terminal output
- Inspired by the need for simple, terminal-based financial data visualization
## Changelog
### 0.1.0 (Initial Release)
- Basic candlestick chart rendering
- Auto-scaling charts
- Color-coded bullish/bearish candles
- Date and price axis labels
## Author
**Sun Jiaxuan**
Email: [sunjiaxuan@hotmail.com](mailto:sunjiaxuan@hotmail.com)
Raw data
{
"_id": null,
"home_page": null,
"name": "terminal-stonks",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Sun Jiaxuan <sunjiaxuan@hotmail.com>",
"keywords": "stocks, charts, terminal, visualization, candlestick",
"author": null,
"author_email": "Sun Jiaxuan <sunjiaxuan@hotmail.com>",
"download_url": "https://files.pythonhosted.org/packages/e9/5f/dc1ac94f3a00b6e520b231560cf21595654bb54873ddafca4d2dafd787f1/terminal_stonks-0.1.0.tar.gz",
"platform": null,
"description": "# Terminal Stonks \ud83d\udcc8\n\n[](https://badge.fury.io/py/terminal-stonks)\n[](https://pypi.org/project/terminal-stonks/)\n[](https://opensource.org/licenses/MIT)\n\nA Python library for rendering beautiful stock candlestick charts directly in your terminal using ASCII art and colors.\n\n## Preview\n\n\n*Example of a candlestick chart rendered in the terminal*\n\n## Features\n\n- \ud83c\udfa8 **Beautiful ASCII charts** - Render K-line/candlestick charts in your terminal\n- \ud83c\udf08 **Color-coded candles** - Red for bullish, green for bearish movements\n- \ud83d\udccf **Auto-scaling** - Charts automatically scale to fit your terminal size\n- \ud83d\udcc5 **Date labels** - X-axis shows relevant dates for better context\n- \ud83d\udcb0 **Price labels** - Y-axis displays price levels\n- \ud83d\udd04 **Real-time compatible** - Perfect for live data visualization\n\n## Installation\n\nInstall from PyPI:\n\n```bash\npip install terminal-stonks\n```\n\nOr install from source:\n\n```bash\ngit clone https://github.com/yourusername/terminal-stonks.git\ncd terminal-stonks\npip install -e .\n```\n\n## Quick Start\n\n```python\nimport pandas as pd\nfrom terminal_stonks import KChart\n\n# Create sample data\ndata = pd.DataFrame({\n 'Open': [100, 102, 101, 103, 105],\n 'High': [105, 106, 104, 107, 108],\n 'Low': [99, 101, 100, 102, 104],\n 'Close': [102, 101, 103, 105, 107]\n}, index=pd.date_range('2024-01-01', periods=5, freq='D'))\n\n# Create and render chart\nchart = KChart(data)\nchart.render(title=\"My Stock Chart\")\n```\n\n## API Reference\n\n### KChart Class\n\n#### `__init__(data: pd.DataFrame)`\n\nInitialize a KChart with stock data.\n\n**Parameters:**\n- `data` (pd.DataFrame): DataFrame with columns 'Open', 'High', 'Low', 'Close' and a DatetimeIndex\n\n**Raises:**\n- `TypeError`: If the index is not a DatetimeIndex\n\n#### `render(title: str = \"\")`\n\nRender the chart to the terminal.\n\n**Parameters:**\n- `title` (str, optional): Chart title to display at the top\n\n## Data Format\n\nYour DataFrame should have the following structure:\n\n```python\nimport pandas as pd\n\ndata = pd.DataFrame({\n 'Open': [float], # Opening prices\n 'High': [float], # Highest prices\n 'Low': [float], # Lowest prices\n 'Close': [float] # Closing prices\n}, index=pd.DatetimeIndex) # Must be a DatetimeIndex\n```\n\n## Examples\n\n### Basic Usage\n\n```python\nfrom terminal_stonks import KChart\nimport pandas as pd\n\n# Sample OHLC data\ndata = pd.DataFrame({\n 'Open': [150.0, 152.0, 151.0, 153.0],\n 'High': [155.0, 156.0, 154.0, 157.0],\n 'Low': [149.0, 151.0, 150.0, 152.0],\n 'Close': [152.0, 151.0, 153.0, 155.0]\n}, index=pd.date_range('2024-01-01', periods=4))\n\nchart = KChart(data)\nchart.render(\"AAPL Stock Chart\")\n```\n\n### With Yahoo Finance Data\n\n```python\nimport yfinance as yf\nfrom terminal_stonks import KChart\n\n# Fetch real data\nticker = yf.Ticker(\"AAPL\")\ndata = ticker.history(period=\"1mo\")\n\n# Render chart\nchart = KChart(data)\nchart.render(\"Apple Inc. (AAPL) - Last 30 Days\")\n```\n\n**Example Output:**\n\n\n## Chart Components\n\n- **Candlestick Body**: Represented by `\u2588` characters\n - Red: Bullish (Close > Open)\n - Green: Bearish (Close < Open)\n- **Shadows/Wicks**: Represented by `\u2502` characters\n- **Price Scale**: Left side Y-axis with price levels\n- **Date Labels**: Bottom X-axis with date information\n\n## Requirements\n\n- Python 3.8+\n- pandas >= 1.3.0\n- rich >= 10.0.0\n\n## Development\n\nTo set up for development:\n\n```bash\ngit clone https://github.com/yourusername/terminal-stonks.git\ncd terminal-stonks\npip install -e \".[dev]\"\n```\n\nRun tests:\n\n```bash\npytest\n```\n\nFormat code:\n\n```bash\nblack terminal_stonks/\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Generating Example Screenshots\n\nTo update the example image (`images/example.png`):\n\n```bash\n# Run the screenshot-friendly script\npython scripts/generate_example.py\n\n# Take a screenshot when the chart appears\n# Save as images/example.png\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Built with [Rich](https://github.com/Textualize/rich) for beautiful terminal output\n- Inspired by the need for simple, terminal-based financial data visualization\n\n## Changelog\n\n### 0.1.0 (Initial Release)\n- Basic candlestick chart rendering\n- Auto-scaling charts\n- Color-coded bullish/bearish candles\n- Date and price axis labels\n\n## Author\n\n**Sun Jiaxuan** \nEmail: [sunjiaxuan@hotmail.com](mailto:sunjiaxuan@hotmail.com) \n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2024 Terminal Stonks Contributors\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE. ",
"summary": "Terminal-based stock chart visualization library",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/TianMingNanWei/terminal-stonks/issues",
"Documentation": "https://github.com/TianMingNanWei/terminal-stonks#readme",
"Homepage": "https://github.com/TianMingNanWei/terminal-stonks",
"Repository": "https://github.com/TianMingNanWei/terminal-stonks.git"
},
"split_keywords": [
"stocks",
" charts",
" terminal",
" visualization",
" candlestick"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a8f9dea23e3e66a8666fc8f1f34c78acba883bdc6c0462ddfa3c2f2691366ff2",
"md5": "35ec0d52e840d368ea2619ea4971637c",
"sha256": "43f769ae449f1709f45e2de95c91e06ae134132e57210adb80217ce03c2e3042"
},
"downloads": -1,
"filename": "terminal_stonks-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "35ec0d52e840d368ea2619ea4971637c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7517,
"upload_time": "2025-07-10T18:47:16",
"upload_time_iso_8601": "2025-07-10T18:47:16.527581Z",
"url": "https://files.pythonhosted.org/packages/a8/f9/dea23e3e66a8666fc8f1f34c78acba883bdc6c0462ddfa3c2f2691366ff2/terminal_stonks-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e95fdc1ac94f3a00b6e520b231560cf21595654bb54873ddafca4d2dafd787f1",
"md5": "9ecf1b5d349351ff359439302a216e19",
"sha256": "a4073c794ac61740b3c83cad0d8a83f45e1f74f3f4d7653ebee99d136e724ebd"
},
"downloads": -1,
"filename": "terminal_stonks-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "9ecf1b5d349351ff359439302a216e19",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 177070,
"upload_time": "2025-07-10T18:47:17",
"upload_time_iso_8601": "2025-07-10T18:47:17.854386Z",
"url": "https://files.pythonhosted.org/packages/e9/5f/dc1ac94f3a00b6e520b231560cf21595654bb54873ddafca4d2dafd787f1/terminal_stonks-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-10 18:47:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "TianMingNanWei",
"github_project": "terminal-stonks",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "yfinance",
"specs": []
},
{
"name": "rich",
"specs": []
},
{
"name": "pynput",
"specs": []
}
],
"lcname": "terminal-stonks"
}
