GitHub Heatmap

2.3.0 verified Mon Apr 27 auth: no python

Generate SVG heatmaps and skyline visualizations for GitHub-like contribution graphs. Version 2.3.0 is the latest. Active development with frequent releases.

pip install github-heatmap

Common errors

error ModuleNotFoundError: No module named 'github_heatmap' ↓

cause The package is installed with a hyphen but imported with an underscore. Some users mistakenly import 'github-heatmap'.

fix

Install the package: pip install github-heatmap. Then import as: from github_heatmap import GitHubPoster

error AttributeError: 'GitHubPoster' object has no attribute 'run' ↓

cause Using the old API from version 1.x where the class was 'Poster' and method was 'make'.

fix

Upgrade to version 2.x and update code: from github_heatmap import GitHubPoster; poster = GitHubPoster(...); poster.run(...)

error ValueError: year must be an integer ↓

cause Passing a list or string instead of an integer for the 'year' argument in run().

fix

Poster.run(username='example', year=2023) # single integer, not [2023]

Warnings

gotcha The GitHub token must have the 'repo' and 'user' scopes. Using a token without the correct scopes will result in a 403 or empty output. ↓

fix Generate a token with scopes: repo, user. Or use a fine-grained token with 'public_repo' access for public repos.

breaking Version 2.x changed the API: the main class is now 'GitHubPoster' instead of 'Poster'. The 'run' method now accepts 'year' as integer (not 'years' list). ↓

fix Update imports: 'from github_heatmap import GitHubPoster'. Pass 'year=2023' instead of 'years=[2023]'.

deprecated The 'mode' parameter (e.g., 'mode=github') is deprecated. Version 2.3.0 auto-detects the platform. ↓

fix Remove the 'mode' parameter from the constructor or run() call.

Imports

GitHubPoster
wrong
```
from github_heatmap import Poster
```
correct
```
from github_heatmap import GitHubPoster
```
Class name is 'GitHubPoster', not 'Poster' or 'Heatmap'.

Quickstart

Initialize with a GitHub token, generate a heatmap SVG for a given user and year.

import os
from github_heatmap import GitHubPoster

poster = GitHubPoster(token=os.environ.get('GITHUB_TOKEN', ''))
poster.run(username='example_user', year=2023)
with open('output.svg', 'rb') as f:
    print(f.read()[:100])