GitHub Contribution Graph in your terminal โ€” for hackers who prefer Unicode over UI

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for Gizmet from gravatar.com Gizmet

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License (MIT)
  • Author: Gizmet
  • Maintainer: Gizmet
  • Tags github , terminal , heatmap , contributions , cli , rich
  • Requires: Python >=3.9
  • Provides-Extra: dev
Classifiers
Report project as malware

Project description

GitHub Stats Heatmap Logo

๐Ÿ•ต๏ธโ€โ™‚๏ธ GitHub Stats Heatmap

Your GitHub activity, visualized โ€” hacker style.

Features โ€ข Quick Start โ€ข Installation โ€ข Live Refresh โ€ข Plugins โ€ข Roadmap โ€ข Contributing โ€ข Changelog

๐Ÿ†• What's New

โšก Live Refresh Mode (Latest)

Experience real-time GitHub stats with auto-updating displays! Perfect for demos, monitoring, and live presentations.

New Features:

  • ๐Ÿ”„ Real-time Updates: Auto-refresh every 30+ seconds
  • ๐Ÿ›ก๏ธ Rate Limit Protection: Smart handling of GitHub API limits
  • ๐ŸŽญ Demo Mode: Seamless fallback to realistic sample data
  • ๐Ÿ“Š Status Indicators: Clear visual feedback (LIVE/RATE LIMITED/DEMO)
  • ๐Ÿ’พ Data Caching: Maintains display even when API is unavailable
# Try it now!
ghstats yourusername --live

See the Live Refresh Mode section for complete details.

โœจ Features

Category Features
๐ŸŽฏ Core Zero-config heatmaps โ€ข Rich terminal output โ€ข Cross-platform
๐ŸŽจ Themes GitHub, dark, light, matrix, cyberpunk, monochrome โ€ข Custom JSON themes
๐Ÿ“Š Analytics Streaks, trends, busiest month, activity patterns โ€ข Multiple sparklines โ€ข Advanced analytics โ€ข Smart insights
๐Ÿ”„ Compare Side-by-side user comparison โ€ข Per-user themes โ€ข Diff highlighting โ€ข Overlap analysis
๐Ÿ† Leaderboards Repository/organization contributors โ€ข Global top contributors
๐Ÿ”Œ Plugins Extensible plugin system โ€ข Global leaderboard plugin
๐ŸŽฎ TUI Interactive terminal UI โ€ข Multiple views โ€ข Cell selection โ€ข Theme switching
โšก Live Real-time refresh mode โ€ข Auto-updating displays โ€ข Rate limit protection โ€ข Demo mode โ€ข Smart caching

๐Ÿš€ Quick Start

# Install from PyPI
pip install gh-stats-heatmap

# Instant visualization
ghstats yourusername

# Compare two developers
ghstats user1 --compare user2

# With global context
ghstats username --global-leaderboard --token YOUR_TOKEN

# Live refresh for demos
ghstats username --live

# Live refresh with custom interval
ghstats username --live --refresh-interval 60

๐Ÿ“ฆ Installation

๐ŸŒ PyPI Install (Recommended)

pip install gh-stats-heatmap

๐Ÿบ Homebrew Install (macOS/Linux)

# Add the tap
brew tap gizmet/tap

# Install ghstats
brew install gizmet/tap/ghstats

You can also view and contribute to the Homebrew formula at: https://github.com/Gizmet/homebrew-tap

๐Ÿ”ง From Source

git clone https://github.com/Gizmet/github-contribution-heatmap-viewer
cd github-contribution-heatmap-viewer
pip install -e .

๐ŸŽฏ Usage Examples

Command Result
ghstats torvalds View Linus's contributions
ghstats gizmet --theme matrix Cyberpunk-style heatmap
ghstats user1 --compare user2 Side-by-side comparison
ghstats user1 --compare user2 --theme dark --theme2 matrix Enhanced comparison with different themes
ghstats --plugin global-leaderboard Top GitHub contributors
ghstats username --tui Interactive TUI mode
ghstats username --live Real-time updates
ghstats username --live --refresh-interval 30 Custom refresh interval
ghstats username --watch Watch mode (alias for --live)

๐Ÿ”Œ Plugin System

Available Plugins

ghstats --list-plugins

๐ŸŒ Global Leaderboard Plugin

Shows top GitHub contributors worldwide using GraphQL API:

# Standalone plugin
ghstats --plugin global-leaderboard --token YOUR_TOKEN

# Integrated with heatmap
ghstats username --global-leaderboard --token YOUR_TOKEN

Features:

  • ๐Ÿ”„ Resilient - Retry logic, fallback data, network error handling
  • ๐Ÿ“Š Rich Data - Contributions, followers, rankings
  • ๐ŸŽจ Beautiful Output - Formatted tables with proper alignment
  • โšก Fast - Optimized GraphQL queries with pagination

๐ŸŽฎ Interactive TUI Mode

Experience your GitHub stats with an interactive terminal interface:

# Launch TUI mode
ghstats username --tui

# TUI with custom theme
ghstats username --tui --theme matrix

# TUI with API token
ghstats username --tui --token YOUR_TOKEN

Features:

  • ๐Ÿ“Š Multiple Views: Heatmap, stats, compare, and settings views
  • ๐ŸŽฏ Interactive Navigation: Switch views and explore data
  • ๐ŸŽจ Theme Switching: Change themes on the fly
  • ๐Ÿ“ˆ Detailed Analytics: Comprehensive statistics tables
  • ๐Ÿ”„ Data Refresh: Reload data without restarting

Navigation:

  • h = Heatmap view
  • s = Stats view
  • v = Compare view
  • o = Settings view
  • t = Change theme
  • r = Refresh data
  • q = Quit

See TUI.md for complete documentation.

๐ŸŽจ Themes

Built-in Themes

  • github - GitHub's official colors
  • dark - Dark terminal aesthetic
  • light - Light terminal friendly
  • matrix - Green terminal matrix vibe
  • cyberpunk - Neon magenta/yellow/cyan
  • monochrome - Clean black and white

Custom Themes

Create your own with JSON:

{
  "name": "My Theme",
  "colors": ["#ebedf0", "#9be9a8", "#40c463", "#30a14e", "#216e39"]
}

๐Ÿ“ˆ Sample Output

โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ ๐Ÿ•ต๏ธโ€โ™‚๏ธ GitHub Stats Heatmap โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ
โ”‚                                                                                           โ”‚
โ”‚  GitHub Contributions: torvalds (Past 52 Weeks)                                           โ”‚
โ”‚                                                                                           โ”‚
โ”‚  M  โ–“โ–ˆโ–ˆโ–ˆโ–“โ–“โ–ˆโ–“โ–’โ–“โ–ˆโ–“โ–“โ–ˆโ–ˆโ–ˆโ–ˆโ–’โ–‘โ–ˆโ–“โ–ˆโ–’โ–ˆโ–“โ–ˆโ–“โ–ˆโ–’โ–“โ–ˆโ–’โ–ˆโ–“โ–“โ–‘โ–ˆโ–ˆโ–“โ–ˆโ–’โ–ˆโ–ˆโ–ˆโ–ˆโ–“โ–ˆโ–“โ–ˆโ–ˆโ–ˆโ–“                                  โ”‚
โ”‚  T  โ–ˆโ–“โ–’โ–’โ–’โ–’โ–‘โ–’โ–ˆโ–ˆโ–’โ–’โ–’โ–“โ–’โ–’โ–’โ–ˆโ–ˆโ–‘โ–“โ–“โ–’โ–’โ–“โ–’โ–ˆโ–ˆโ–“โ–’โ–’โ–’โ–’โ–’โ–’โ–ˆโ–ˆโ–“โ–“โ–’โ–“โ–“โ–“โ–‘โ–ˆโ–ˆโ–’โ–“โ–“โ–’โ–’โ–‘                                  โ”‚
โ”‚  W  โ–ˆโ–“โ–’โ–’โ–“โ–’โ–’โ–’โ–ˆโ–ˆโ–‘โ–’โ–’โ–‘โ–“โ–‘โ–“โ–ˆโ–ˆโ–’โ–“โ–“โ–’โ–‘โ–’โ–“โ–ˆโ–ˆโ–’โ–’โ–’โ–“โ–ˆโ–ˆโ–’โ–ˆโ–ˆโ–“โ–’โ–’โ–ˆโ–’โ–“โ–“โ–ˆโ–ˆโ–’โ–ˆโ–’โ–“โ–ˆโ–‘                                  โ”‚
โ”‚  T  โ–“โ–‘โ–’โ–“โ–‘โ–“โ–ˆโ–“โ–ˆโ–ˆโ–“โ–’โ–“โ–’โ–’โ–“โ–“โ–ˆโ–ˆโ–’โ–’โ–“โ–‘โ–’โ–’โ–‘โ–ˆโ–ˆโ–’โ–’โ–’โ–ˆโ–“โ–“โ–’โ–ˆโ–ˆโ–’โ–ˆโ–ˆโ–“โ–“โ–ˆโ–’โ–ˆโ–ˆโ–’โ–ˆโ–“โ–“โ–’โ–‘                                  โ”‚
โ”‚  F  โ–ˆโ–’โ–“โ–“โ–’โ–“โ–ˆโ–ˆโ–ˆโ–ˆโ–“โ–“โ–ˆโ–ˆโ–“โ–“โ–’โ–ˆโ–ˆโ–ˆโ–“โ–ˆโ–“โ–’โ–’โ–ˆโ–ˆโ–ˆโ–’โ–ˆโ–ˆโ–’โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–“โ–’โ–“โ–ˆโ–ˆโ–ˆโ–ˆโ–“โ–ˆโ–“โ–“โ–“โ–‘                                  โ”‚
โ”‚  S  โ–ˆโ–ˆโ–ˆโ–ˆโ–“โ–“โ–ˆโ–“โ–“โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–“โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–“โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–“โ–ˆโ–ˆโ–ˆโ–‘                                  โ”‚
โ”‚  S  โ–ˆโ–’โ–“โ–ˆโ–ˆโ–ˆโ–’โ–’โ–“โ–ˆโ–ˆโ–’โ–ˆโ–‘โ–’โ–’โ–“โ–’โ–ˆโ–“โ–ˆโ–ˆโ–’โ–’โ–“โ–’โ–ˆโ–“โ–ˆโ–ˆโ–ˆโ–ˆโ–’โ–“โ–“โ–ˆโ–’โ–“โ–ˆโ–ˆโ–’โ–ˆโ–ˆโ–“โ–ˆโ–“โ–“โ–ˆโ–“โ–“โ–“โ–‘                                  โ”‚
โ”‚                                                                                           โ”‚
โ”‚  Weekly Activity: โ–„โ–‚โ–‚โ–‚โ–‚โ–‚โ–ƒโ–โ–†โ–…โ–ƒโ–‚โ–‚โ–‚โ–‚โ–‚โ–‚โ–‡โ–„โ–‚โ–‚โ–ƒโ–โ–‚โ–‚โ–‚โ–‡โ–„โ–‚โ–‚โ–‚โ–‚โ–ƒโ–ƒโ–‚โ–ˆโ–…โ–‚โ–ƒโ–ƒโ–‚โ–‚โ–ƒโ–‚โ–‡โ–„โ–‚โ–ƒโ–‚โ–‚โ–‚โ–              โ”‚
โ”‚  Monthly Trend: โ–โ–โ–โ–โ–ˆโ–‚                                                                     โ”‚
โ”‚  Consistency: โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ƒโ–โ–โ–โ–โ–                           โ”‚
โ”‚  Trend: ๐Ÿ“ˆ Accelerating | Peak: This week (24 contributions) | Consistency: โœ… Good (85%)   โ”‚
โ”‚                                                                                           โ”‚
โ”‚  Legend: โ–‘ = 0 โ–’ = 1-3 โ–“ = 4-6 โ–ˆ = 7+                                                     โ”‚
โ”‚                                                                                           โ”‚
โ”‚  โšก Current streak: 1 days | ๐Ÿ“Š Total contributions: 2885 | ๐Ÿ“… Active days: 344/364       โ”‚
โ”‚  (94.5%) | ๐Ÿ† Longest streak: 66 days | ๐Ÿ“ˆ This month: 170 | ๐Ÿ“‰ Inactive weeks: 0 | ๐Ÿ“…    โ”‚
โ”‚  Busiest week: 157 contributions (Week 36) | ๐Ÿฅ‡ Most active weekday: S | ๐ŸŒŸ Busiest       โ”‚
โ”‚  month: May | ๐Ÿ˜ด Least active weekday: T | ๐Ÿ“† Avg/week: 55.5 | ๐Ÿ“ˆ Trend: Up (+241)        โ”‚
โ”‚                                                                                           โ”‚
โ”‚  ๐ŸŽฏ Consistency: 85/100 | โšก Pattern: Weekday focused (Monday peak, Tuesday low)           โ”‚
โ”‚  ๐ŸŒฑ Seasonal: Strong Summer preference | ๐Ÿš€ Momentum: +25% | ๐ŸŒ… Weekend work: 15%         โ”‚
โ”‚  โฐ Peak hours: Early week focus (Monday peak) | ๐Ÿ˜ด Burnout risk: Low (healthy pace)      โ”‚
โ”‚  ๐ŸŽฏ Improvement: High potential (few gaps)                                                โ”‚
โ”‚                                                                                           โ”‚
โ”‚  ๐Ÿ’ญ You've contributed 2885 times in the last 52 weeks. Your consistency is excellent.    โ”‚
โ”‚  You're a weekday warrior. You show a strong summer preference. You're gaining momentum.  โ”‚
โ”‚  You prefer weekday work. You have great potential for growth. You're on a 1-day streak   โ”‚
โ”‚  with increasing activity.                                                                 โ”‚
โ”‚                                                                                           โ”‚
โ”‚  ๐ŸŒ Global GitHub Contributors                                                            โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”             โ”‚
โ”‚  โ”‚ Rank โ”‚ User              โ”‚ Name              โ”‚ Contributions โ”‚ Followers โ”‚             โ”‚
โ”‚  โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค             โ”‚
โ”‚  โ”‚    1 โ”‚ @Charles-Chrismann โ”‚ Charles Chrismann โ”‚      12,290 โ”‚    16,017 โ”‚              โ”‚
โ”‚  โ”‚    2 โ”‚ @lllyasviel        โ”‚ lllyasviel        โ”‚       9,121 โ”‚    19,979 โ”‚              โ”‚
โ”‚  โ”‚    3 โ”‚ @phodal            โ”‚ Fengda Huang      โ”‚       9,052 โ”‚    20,351 โ”‚              โ”‚
โ”‚  โ”‚    4 โ”‚ @skydoves          โ”‚ Jaewoong Eum      โ”‚       7,045 โ”‚    12,058 โ”‚              โ”‚
โ”‚  โ”‚    5 โ”‚ @jeresig           โ”‚ John Resig        โ”‚       6,066 โ”‚    18,881 โ”‚              โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜             โ”‚
โ”‚                                                                                           โ”‚
โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ

๐Ÿ› ๏ธ API Tokens

When you need tokens:

  • ๐Ÿ”’ Private repository data
  • ๐Ÿ† Repository/organization leaderboards
  • ๐ŸŒ Global leaderboard plugin
  • ๐Ÿ“Š Integrated global leaderboard feature

When you DON'T need tokens:

  • โœ… Public profile heatmaps
  • โœ… Basic statistics
  • โœ… Compare mode (public users)
  • โœ… Theme customization

Create tokens at: https://github.com/settings/tokens

๐Ÿ”ง Plugin Development

Extend functionality with custom plugins:

from plugins.base import GhStatsPlugin

class MyPlugin(GhStatsPlugin):
    def name(self) -> str:
        return "my-plugin"
    
    def description(self) -> str:
        return "My custom plugin"
    
    def requires_token(self) -> bool:
        return False
    
    def execute(self, **kwargs) -> Dict[str, Any]:
        # Your plugin logic here
        return {"success": True, "data": "..."}

๐Ÿ“‹ Roadmap

Status Feature Description
โœ… Complete Core heatmap rendering Beautiful terminal output with Unicode blocks
โœ… Complete Theme system Built-in + custom JSON themes
โœ… Complete Statistics engine Streaks, trends, patterns, analytics
โœ… Complete Compare mode Side-by-side user comparison
โœ… Complete Plugin architecture Extensible plugin system
โœ… Complete Global leaderboard Top GitHub contributors worldwide
โœ… Complete Live refresh Real-time updates
๐Ÿ”„ In Progress Export features PNG, HTML, JSON export
๐Ÿ”„ In Progress TUI mode Interactive terminal UI
๐Ÿ“‹ Planned Team analytics Organization insights
๐Ÿ“‹ Planned Historical trends Year-over-year comparisons
๐Ÿ“‹ Planned Custom metrics User-defined contribution types

๐Ÿ—๏ธ Project Structure

github-contribution-heatmap-viewer/
โ”œโ”€โ”€ ghstats.py              # CLI entry point
โ”œโ”€โ”€ github_api.py           # GitHub API integration
โ”œโ”€โ”€ heatmap.py              # Grid generation logic
โ”œโ”€โ”€ render.py               # Rich terminal rendering
โ”œโ”€โ”€ utils.py                # Utility functions
โ”œโ”€โ”€ plugins/                # Plugin system
โ”‚   โ”œโ”€โ”€ __init__.py         # Plugin manager
โ”‚   โ”œโ”€โ”€ base.py             # Base plugin class
โ”‚   โ””โ”€โ”€ global_leaderboard.py # Global leaderboard plugin
โ”œโ”€โ”€ tests/                  # Test suite
โ”œโ”€โ”€ themes/                 # Theme definitions
โ””โ”€โ”€ README.md               # This file

๐Ÿงช Development

# Install in development mode
pip install -e .

# Run tests
pytest

# Run with coverage
pytest --cov=.

# Format code
black .

# Lint code
flake8 .

๐Ÿค Contributing

We welcome contributions! Here's how:

  1. ๐Ÿด Fork the repository
  2. ๐ŸŒฑ Create a feature branch: git checkout -b feature/amazing-thing
  3. ๐Ÿ’ฅ Commit your changes: git commit -m 'Add amazing thing'
  4. ๐Ÿš€ Push to the branch: git push origin feature/amazing-thing
  5. ๐Ÿ“ฌ Open a Pull Request

Guidelines:

  • Follow PEP 8 style guidelines
  • Add tests for new functionality
  • Update documentation for new features
  • Write clear commit messages

๐Ÿ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.

๐Ÿ™ Acknowledgments

  • Rich - Beautiful terminal rendering
  • GitHub API - Data source
  • Unicode - For the glorious โ–‘โ–’โ–“โ–ˆ blocks
  • committers.top - Inspiration for global leaderboards

Made with โค๏ธ for developers who live in the terminal

โญ Star this repo if you find it useful! โญ

โšก Live Refresh Mode

Experience real-time GitHub stats with auto-updating displays perfect for demos, monitoring, and live presentations:

# Basic live refresh (30s minimum interval)
ghstats username --live

# Custom refresh interval
ghstats username --live --refresh-interval 60

# Watch mode (alias for --live)
ghstats username --watch

# Live refresh with compare mode
ghstats username --compare user2 --live

# Live refresh with custom theme
ghstats username --live --theme matrix

๐ŸŽฏ Live Refresh Features

  • ๐Ÿ”„ Auto-Updating: Real-time data refresh with customizable intervals
  • ๐Ÿ›ก๏ธ Rate Limit Protection: Automatic detection and graceful handling of GitHub API rate limits
  • ๐ŸŽญ Demo Mode: Seamless fallback to realistic sample data when rate limited
  • ๐Ÿ“Š Status Indicators: Clear visual feedback (LIVE/RATE LIMITED/DEMO)
  • ๐Ÿ’พ Data Caching: Uses cached data when API calls fail
  • โฐ Smart Intervals: Minimum 30-second intervals to prevent rate limiting
  • ๐ŸŽจ Theme Support: Full theme compatibility in live mode
  • ๐Ÿ”„ Compare Mode: Side-by-side live comparison of multiple users

๐ŸŽญ Demo Mode

When rate limited, the live refresh automatically switches to demo mode:

  • Realistic Data: Generates authentic-looking contribution patterns
  • Weekday Patterns: Higher activity on weekdays, lower on weekends
  • Random Variation: Natural-looking contribution counts and patterns
  • Seamless Transition: No interruption to the live display

๐Ÿ“Š Status Display

Live refresh provides comprehensive status information:

Last update: 14:30:25 | Updates: 15 | Status: LIVE | Next refresh in 60s
Rate limit: 4850/5000 requests remaining | Reset at 15:00:00

Status Types:

  • [green]LIVE[/green] - Real-time data from GitHub API
  • [yellow]RATE LIMITED[/yellow] - Using cached data due to rate limits
  • [yellow]DEMO[/yellow] - Using sample data in demo mode

๐Ÿ›ก๏ธ Error Handling

  • Retry Logic: Automatic retry with exponential backoff
  • Graceful Degradation: Falls back to cached data when API fails
  • Rate Limit Awareness: Detects and handles GitHub API rate limits
  • User Feedback: Clear error messages and status updates

๐Ÿ“– For detailed documentation, see LIVE_REFRESH.md

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for Gizmet from gravatar.com Gizmet

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License (MIT)
  • Author: Gizmet
  • Maintainer: Gizmet
  • Tags github , terminal , heatmap , contributions , cli , rich
  • Requires: Python >=3.9
  • Provides-Extra: dev
Classifiers

Release history Release notifications | RSS feed

1.0.3

1.0.2

This version

1.0.1

1.0.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gh_stats_heatmap-1.0.1.tar.gz (1.9 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

gh_stats_heatmap-1.0.1-py3-none-any.whl (34.7 kB view details)

Uploaded Python 3

File details

Details for the file gh_stats_heatmap-1.0.1.tar.gz.

File metadata

  • Download URL: gh_stats_heatmap-1.0.1.tar.gz
  • Upload date:
  • Size: 1.9 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.5

File hashes

Hashes for gh_stats_heatmap-1.0.1.tar.gz
Algorithm Hash digest
SHA256 df18f52f07c2d815b53888ee581540be89e6ea6766298db4f08830faec40f408
MD5 8fc44cc91b5418524956699af6e3c575
BLAKE2b-256 837b1a082ec068e56952b227b496f031d0f18dd339e3d53a33ba8d8253dfac44

See more details on using hashes here.

File details

Details for the file gh_stats_heatmap-1.0.1-py3-none-any.whl.

File metadata

File hashes

Hashes for gh_stats_heatmap-1.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 24d614683bf98c2d854ba93c32732ef58154f3794e60cf630b516e3b95850e77
MD5 0c615ac8ce746f3b11bd5dea15233970
BLAKE2b-256 c4f5fde395175afc28fac92fbf0f9c7099194fa2ed648c600ebf1c41458e311a

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page