{"id":37072547,"url":"https://github.com/zhirodadkhah/candlekit","last_synced_at":"2026-01-14T08:31:08.291Z","repository":{"id":327937986,"uuid":"1113077320","full_name":"zhirodadkhah/CandleKit","owner":"zhirodadkhah","description":"Python Library to detect candlestick patterns","archived":false,"fork":false,"pushed_at":"2025-12-23T12:16:46.000Z","size":36,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-25T01:52:26.827Z","etag":null,"topics":["candlestick-patterns-detection","candlesticks","nison"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zhirodadkhah.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-09T13:44:43.000Z","updated_at":"2025-12-23T12:16:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zhirodadkhah/CandleKit","commit_stats":null,"previous_names":["zhirodadkhah/candlekit"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zhirodadkhah/CandleKit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhirodadkhah%2FCandleKit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhirodadkhah%2FCandleKit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhirodadkhah%2FCandleKit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhirodadkhah%2FCandleKit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zhirodadkhah","download_url":"https://codeload.github.com/zhirodadkhah/CandleKit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhirodadkhah%2FCandleKit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28414165,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T08:16:59.381Z","status":"ssl_error","status_checked_at":"2026-01-14T08:13:45.490Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["candlestick-patterns-detection","candlesticks","nison"],"created_at":"2026-01-14T08:31:07.676Z","updated_at":"2026-01-14T08:31:08.283Z","avatar_url":"https://github.com/zhirodadkhah.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CandleKit\n\nA lightweight, pandas-friendly Python library for detecting candlestick patterns in financial time-series data.\n\n## ✨ Features\n- **20+ Classic Patterns**: Detect Hammer, Engulfing, Morning Star, and more\n- **Pandas Integration**: Works directly with pandas DataFrames (OHLC format)\n- **Clear Classification**: Bullish/bearish/neutral signal identification\n- **Academic Foundation**: Based on Nison's \"Japanese Candlestick Charting Techniques\"\n- **Production Ready**: Comprehensive testing and type hints\n- **Easy Extension**: Simple API for adding custom patterns\n\n## 📊 Supported Patterns\n\n### Single-Candle Patterns\n- **Doji** - Indecision (neutral)\n- **Hammer** - Bullish reversal after downtrend\n- **Shooting Star** - Bearish reversal after uptrend\n- **Bullish/Bearish Marubozu** - Strong conviction with minimal shadows\n- **Bullish/Bearish Belt Hold** - Strong opening at extreme\n\n### Two-Candle Patterns\n- **Bullish/Bearish Engulfing** - Reversal patterns\n- **Piercing Line / Dark Cloud Cover** - Counter-trend reversals\n- **Harami Cross** - Reversal with doji\n- **Kicking** - Reversal with marubozu gap\n\n### Three-Candle Patterns\n- **Morning/Evening Star** - Classic reversal patterns\n- **Morning/Evening Doji Star** - Reversal with doji confirmation\n- **Three White Soldiers** - Strong bullish continuation\n- **Three Black Crows** - Strong bearish continuation\n- **Three Inside/Outside Up** - Bullish reversal variations\n\n### Five-Candle Patterns\n- **Rising/Falling Three Methods** - Continuation patterns\n- **Mat Hold** - Bullish continuation with pullback\n\n## 📦 Installation\n\n```bash\npip install candlekit\n```\n\n## 🚀 Quick Start\n\n```python\nimport pandas as pd\nfrom candlekit import scan_symbol_df, CandlePatterns\n\n# Your OHLC data (lowercase column names required)\ndata = {\n    'open':  [100, 102, 101, 103, 105],\n    'high':  [103, 104, 102, 106, 107],\n    'low':   [99,  101, 100, 102, 104],\n    'close': [102, 101, 102, 105, 106]\n}\ndf = pd.DataFrame(data)\n\n# Scan for all patterns\nresults_df = scan_symbol_df(df)\nprint(results_df)\n```\n\n**Output:**\n```\n   index        pattern_name signal_type  candles\n0      1              Hammer     bullish        1\n1      3   Bullish Engulfing     bullish        2\n```\n\n## 📚 Basic Usage\n\n### Detect Specific Pattern\n```python\nfrom candlekit import detect_pattern_at_index\n\n# Check if index 1 is a Hammer\nis_hammer = detect_pattern_at_index(CandlePatterns.Hammer, df, index=1)\nprint(f\"Hammer detected: {is_hammer}\")  # True\n```\n\n### Get Results as List\n```python\nfrom candlekit import scan_symbol\n\nresults_list = scan_symbol(df)\n# Returns: [(1, 'Hammer', 'bullish'), (3, 'BullishEngulfing', 'bullish')]\n```\n\n### Scan Specific Patterns Only\n```python\n# Scan only for reversal patterns\nreversal_patterns = [\n    CandlePatterns.Hammer,\n    CandlePatterns.ShootingStar,\n    CandlePatterns.BullishEngulfing,\n    CandlePatterns.MorningStar\n]\n\nresults = scan_symbol_df(df, patterns=reversal_patterns)\n```\n\n## 🔧 Working with Real Data\n\n### Using yfinance (Optional)\n```python\nimport yfinance as yf\nfrom candlekit import scan_symbol_df\n\n# Download data\nticker = yf.Ticker(\"AAPL\")\ndf = ticker.history(period=\"1mo\", interval=\"1d\")\n\n# Ensure correct column names\ndf.columns = [col.lower() for col in df.columns]\n\n# Scan for patterns\npatterns = scan_symbol_df(df)\n\n# Filter recent bullish patterns\nrecent_bullish = patterns[\n    (patterns['signal_type'] == 'bullish') \u0026 \n    (patterns['index'] \u003e len(df) - 5)\n]\n```\n\n### Using CSV Data\n```python\nimport pandas as pd\nfrom candlekit import scan_symbol_df\n\n# Load from CSV (ensure column names match)\ndf = pd.read_csv('your_data.csv')\ndf.columns = ['open', 'high', 'low', 'close', 'volume']  # Rename if needed\n\n# Scan for patterns\nresults = scan_symbol_df(df)\n```\n\n## ⚙️ Advanced Configuration\n\n### Custom Pattern Parameters\n```python\n# Adjust sensitivity for Doji detection\ndetect_pattern_at_index(\n    CandlePatterns.Doji, \n    df, \n    index=0, \n    max_body_ratio=0.15  # Default: 0.1\n)\n\n# Custom Hammer parameters\ndetect_pattern_at_index(\n    CandlePatterns.Hammer,\n    df,\n    index=1,\n    max_body_ratio=0.3,           # Default: 0.25\n    min_lower_wick_to_body=1.5,   # Default: 2.0\n    max_upper_wick_ratio=0.4      # Default: 0.33\n)\n```\n\n### Pattern-Specific Parameters\nEach pattern has sensible defaults, but you can adjust:\n- `max_body_ratio`: Maximum body-to-total-length ratio (for thin candles)\n- `min_body_ratio`: Minimum body-to-total-length ratio (for thick candles)\n- `min_lower_wick_to_body`: For Hammer pattern\n- `min_upper_wick_to_body`: For Shooting Star pattern\n\n## 🧠 Understanding CandleStick Objects\n\nThe library uses `CandleStick` objects internally. You can access their properties:\n\n```python\nfrom candlekit.src.candlekit.entity import CandleStick\n\ncandle = CandleStick(df, index=0)\nprint(f\"Body length: {candle.body_length}\")\nprint(f\"Top wick: {candle.top_wick}\")\nprint(f\"Bottom wick: {candle.bottom_wick}\")\nprint(f\"Body ratio: {candle.body_ratio:.2%}\")\nprint(f\"Is bullish: {candle.is_bullish}\")\n```\n\n## 📊 Complete Pattern List\n\n### Access All Patterns\n```python\nfrom candlekit import CandlePatterns\n\n# List all available patterns\nfor pattern in CandlePatterns:\n    print(f\"{pattern.pattern_name}: {pattern.signal_type} ({pattern.candles} candle(s))\")\n```\n\n### Pattern Categories\n```python\n# Single-candle patterns\nsingle_candle = [p for p in CandlePatterns if p.candles == 1]\n\n# Multi-candle patterns\nmulti_candle = [p for p in CandlePatterns if p.candles \u003e 1]\n\n# Bullish patterns\nbullish = [p for p in CandlePatterns if p.signal_type == 'bullish']\n\n# Bearish patterns\nbearish = [p for p in CandlePatterns if p.signal_type == 'bearish']\n```\n\n## 🧪 Testing \u0026 Quality\n\n### Run Tests\n```bash\n# Install test dependencies\npip install pytest\n\n# Run all tests\npython -m pytest\n\n# Run specific test file\npython -m pytest tests/test_patterns.py -v\n\n# Run with coverage\npython -m pytest --cov=candlekit tests/\n```\n\n### Example Test\n```python\nimport pytest\nimport pandas as pd\nfrom candlekit import detect_pattern_at_index, CandlePatterns\n\ndef test_hammer_detection():\n    \"\"\"Test Hammer pattern detection\"\"\"\n    df = pd.DataFrame({\n        'open': [100],\n        'high': [105],\n        'low': [95],\n        'close': [99]\n    })\n    \n    # This is NOT a hammer (body too large relative to wick)\n    result = detect_pattern_at_index(CandlePatterns.Hammer, df, index=0)\n    assert result == False\n    \n    # This IS a hammer\n    df = pd.DataFrame({\n        'open': [95],\n        'high': [98],\n        'low': [80],\n        'close': [96]\n    })\n    result = detect_pattern_at_index(CandlePatterns.Hammer, df, index=0)\n    assert result == True\n```\n\n## 🛠️ Development\n\n### Setup Development Environment\n```bash\n# Clone and install\ngit clone https://github.com/zhirodadkhah/candlekit.git\ncd candlekit\npip install -e \".[dev]\"\n\n# Run code quality tools\nflake8 src/candlekit      # Linting\nblack src/candlekit       # Formatting\nmypy src/candlekit        # Type checking\n```\n\n### Adding New Patterns\n1. Add detection function in `patterns.py`\n2. Add to `CandlePatterns` enum in `utils.py`\n3. Write comprehensive tests\n\nExample:\n```python\n# In patterns.py\ndef is_tweezers_top(candle1: CandleStick, candle2: CandleStick) -\u003e bool:\n    \"\"\"Detect Tweezer Top pattern.\"\"\"\n    return (\n        candle1.high == candle2.high and\n        candle1.is_bullish and\n        not candle2.is_bullish\n    )\n\n# In utils.py\nCandlePatterns.TweezerTop = (2, is_tweezers_top, \"bearish\", \"Tweezer Top\")\n```\n\n## 📖 Pattern References \u0026 Methodology\n\nAll patterns are implemented according to **Steve Nison's \"Japanese Candlestick Charting Techniques, 2nd Edition\"**. Each pattern function includes page references to the textbook.\n\n### Key Concepts\n- **Body Ratio**: `body_length / total_length` - measures conviction\n- **Window Gap**: Price gap between candles with no overlap\n- **Engulfment**: Current candle's body completely contains previous\n- **Containment**: Candle's body is within another's range\n\n### Academic Sources\n- Nison, S. (2001). *Japanese Candlestick Charting Techniques*\n- Bulkowski, T. N. (2005). *Encyclopedia of Candlestick Charts*\n- Morris, G. L. (1995). *Candlestick Charting Explained*\n\n## 🤝 Contributing\n\nWe welcome contributions! Please:\n\n1. **Fork** the repository\n2. **Create a feature branch**: `git checkout -b feature/amazing-pattern`\n3. **Add tests** for new functionality\n4. **Ensure tests pass**: `pytest`\n5. **Update documentation** as needed\n6. **Submit a Pull Request**\n\n### Contribution Ideas\n- Add more candlestick patterns\n- Improve performance for large datasets\n- Add visualization helpers\n- Create Jupyter notebook examples\n- Add pattern combination analysis\n\n\n## 🙏 Acknowledgments\n\n- **Steve Nison** for bringing candlestick analysis to markets\n- The **pandas** and **numpy** communities\n- All **contributors** and **users** of this library\n- Financial analysts and quants who provided feedback\n\n## ⚠️ Disclaimer\n\n**IMPORTANT**: This library is for **educational and research purposes only**.\n\n- Trading involves substantial risk of loss\n- Past performance is not indicative of future results\n- Always conduct your own research and consult financial advisors\n- The authors are not responsible for any trading losses\n\nUse this tool as part of a comprehensive trading strategy, not as standalone advice.\n\n---\n\n**Happy analyzing!** 📈\n\n*Found a bug or have a feature request? Please open an issue on GitHub!*\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhirodadkhah%2Fcandlekit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzhirodadkhah%2Fcandlekit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhirodadkhah%2Fcandlekit/lists"}