ghmap

2.0.4 verified Sat May 09 auth: no python

A GitHub event mapping and analysis tool that processes GitHub Events API data to generate human-readable summaries. Version 2.0.4, actively maintained with monthly releases.

pip install ghmap

Common errors

error ModuleNotFoundError: No module named 'ghmap' ↓

cause ghmap is not installed or installed in a different environment.

fix

Run pip install ghmap in your active environment.

error ImportError: cannot import name 'GHMap' from 'ghmap' ↓

cause Trying to import GHMap from the wrong submodule or using an outdated import path.

fix

Use from ghmap import GHMap.

error TypeError: 'NoneType' object is not iterable ↓

cause map_events returned None (no events found) and you tried to iterate over it.

fix

Check if the result is None before iterating: if summary: then process.

error requests.exceptions.HTTPError: 401 Client Error: Unauthorized ↓

cause GitHub token is missing or invalid, required since v2.0.0.

fix

Set GITHUB_TOKEN environment variable or pass token parameter to GHMap constructor.

error ValueError: Invalid format 'json'. Valid formats are: 'text', 'csv' ↓

cause Using deprecated `--output-format` flag with removed value 'json'.

fix

Use --format json instead.

Warnings

breaking In v2.0.0, the `get_repo_events` method now requires a token; previously it worked without authentication for public repos. ↓

fix Provide a valid GITHUB_TOKEN via environment variable or constructor argument.

deprecated The `--output-format` CLI argument was deprecated in v1.0.6 and removed in v2.0.0. Use `--format` instead. ↓

fix Replace `--output-format json` with `--format json`.

gotcha The `map_events` method returns `None` if no events are found, not an empty list. ↓

fix Check return value with `if summary is not None:` or use `or` to provide a default.

gotcha On Windows, paths containing backslashes cause parsing errors in the config files. Fixed in v2.0.1 but if you use custom config paths, use forward slashes or raw strings. ↓

fix Use raw strings or forward slashes in config paths, or upgrade to >=2.0.1.

Imports

GHMap
wrong
```
import ghmap.GHMap
```
correct
```
from ghmap import GHMap
```
GHMap is a class in the main ghmap module, not a submodule
process_events
wrong
```
from ghmap.events import process_events
```
correct
```
from ghmap import process_events
```
process_events is exported at the package level, not in a submodule

Quickstart

Quickstart showing how to initialize GHMap with a GitHub token and map events from a repository.

from ghmap import GHMap
import os

# Initialize with token from environment
ghmap = GHMap(token=os.environ.get('GITHUB_TOKEN', ''))

# Process events for a repository
events = ghmap.get_repo_events('owner/repo')
summary = ghmap.map_events(events)
print(summary)