gh-space-shooter 0.0.1__py3-none-any.whl

gh_space_shooter/__init__.py

@@ -0,0 +1,19 @@
+"""GitHub contribution graph gamification tool."""
+
+from .github_client import (
+    ContributionData,
+    ContributionDay,
+    ContributionWeek,
+    GitHubAPIError,
+    GitHubClient,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "GitHubClient",
+    "GitHubAPIError",
+    "ContributionData",
+    "ContributionDay",
+    "ContributionWeek",
+]

gh_space_shooter/cli.py

@@ -0,0 +1,177 @@
+"""CLI interface for gh-space-shooter."""
+
+import json
+import os
+import sys
+
+import typer
+from dotenv import load_dotenv
+from rich.console import Console
+
+from gh_space_shooter.game.strategies.base_strategy import BaseStrategy
+
+from .console_printer import ContributionConsolePrinter
+from .game import Animator, ColumnStrategy, RandomStrategy, RowStrategy
+from .github_client import ContributionData, GitHubAPIError, GitHubClient
+
+# Load environment variables from .env file
+load_dotenv()
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+class CLIError(Exception):
+    """Base exception for CLI errors with user-friendly messages."""
+    pass
+
+
+def main(
+    username: str = typer.Argument(None, help="GitHub username to fetch data for"),
+    raw_input: str = typer.Option(
+        None,
+        "--raw-input",
+        "--raw-in",
+        "-ri",
+        help="Load contribution data from JSON file (skips GitHub API call)",
+    ),
+    raw_output: str = typer.Option(
+        None,
+        "--raw-output",
+        "--raw-out",
+        "-ro",
+        help="Save contribution data to JSON file",
+    ),
+    out: str = typer.Option(
+        None,
+        "--output",
+        "-out",
+        "-o",
+        help="Generate animated GIF visualization",
+    ),
+    strategy: str = typer.Option(
+        "random",
+        "--strategy",
+        "-s",
+        help="Strategy for clearing enemies (column, row, random)",
+    ),
+) -> None:
+    """
+    Fetch or load GitHub contribution graph data and display it.
+
+    You can either fetch fresh data from GitHub or load from a previously saved file.
+    This is useful for saving API rate limits.
+
+    Examples:
+      # Fetch from GitHub and save
+      gh-space-shooter czl9707 --raw-output data.json
+
+      # Load from saved file
+      gh-space-shooter --raw-input data.json
+    """
+    try:
+        if not username:
+            raise CLIError("Username is required when not using --raw-input")
+        if not out:
+            out = f"{username}-gh-space-shooter.gif"
+        # Load data from file or GitHub
+        if raw_input:
+            data = _load_data_from_file(raw_input)
+        else:
+            data = _load_data_from_github(username)
+
+        # Display the data
+        printer = ContributionConsolePrinter()
+        printer.display_stats(data)
+        printer.display_contribution_graph(data)
+
+        # Save to file if requested
+        if raw_output:
+            _save_data_to_file(data, raw_output)
+
+        # Generate GIF if requested
+        _generate_gif(data, out, strategy)
+
+    except CLIError as e:
+        err_console.print(f"[bold red]Error:[/bold red] {e}")
+        sys.exit(1)
+
+    except Exception as e:
+        err_console.print(f"[bold red]Unexpected error:[/bold red] {e}")
+        sys.exit(1)
+
+
+def _load_env_and_validate() -> str:
+    """Load environment variables and validate required settings. Returns token."""
+    token = os.getenv("GH_TOKEN")
+    if not token:
+        raise CLIError(
+            "GitHub token not found. "
+            "Set your GitHub token in the GH_TOKEN environment variable."
+        )
+    return token
+
+
+def _load_data_from_file(file_path: str) -> ContributionData:
+    """Load contribution data from a JSON file."""
+    console.print(f"[bold blue]Loading data from {file_path}...[/bold blue]")
+    try:
+        with open(file_path, "r") as f:
+            return json.load(f)
+    except FileNotFoundError:
+        raise CLIError(f"File '{file_path}' not found")
+    except json.JSONDecodeError as e:
+        raise CLIError(f"Invalid JSON in '{file_path}': {e}")
+
+
+def _load_data_from_github(username: str) -> ContributionData:
+    """Fetch contribution data from GitHub API."""
+    token = _load_env_and_validate()
+
+    console.print(f"[bold blue]Fetching contribution data for {username}...[/bold blue]")
+    try:
+        with GitHubClient(token) as client:
+            return client.get_contribution_graph(username)
+    except GitHubAPIError as e:
+        raise CLIError(f"GitHub API error: {e}")
+
+
+def _save_data_to_file(data: ContributionData, file_path: str) -> None:
+    """Save contribution data to a JSON file."""
+    try:
+        with open(file_path, "w") as f:
+            json.dump(data, f, indent=2)
+        console.print(f"\n[green]✓[/green] Data saved to {file_path}")
+    except IOError as e:
+        raise CLIError(f"Failed to save file '{file_path}': {e}")
+
+
+def _generate_gif(data: ContributionData, file_path: str, strategy_name: str) -> None:
+    """Generate animated GIF visualization."""
+    console.print("\n[bold blue]Generating GIF animation...[/bold blue]")
+
+    if strategy_name == "column":
+        strategy: BaseStrategy = ColumnStrategy()
+    elif strategy_name == "row":
+        strategy = RowStrategy()
+    elif strategy_name == "random":
+        strategy = RandomStrategy()
+    else:
+        raise CLIError(
+            f"Unknown strategy '{strategy_name}'. Available: column, row, random"
+        )
+
+    # Create animator and generate GIF
+    try:
+        animator = Animator(data, strategy)
+        animator.generate_gif(file_path)
+        console.print(f"[green]✓[/green] GIF saved to {file_path}")
+    except Exception as e:
+        raise CLIError(f"Failed to generate GIF: {e}")
+
+
+app = typer.Typer()
+app.command()(main)
+
+if __name__ == "__main__":
+    app()

gh_space_shooter/console_printer.py

@@ -0,0 +1,65 @@
+"""Console output formatting and display functions."""
+
+from rich.console import Console
+from rich.text import Text
+
+from .github_client import ContributionData
+
+console = Console()
+
+class ContributionConsolePrinter:
+    def display_stats(self, data: ContributionData) -> None:
+        """Display contribution statistics in a one-liner."""
+        # Get date range
+        all_days = [day for week in data["weeks"] for day in week["days"]]
+        if all_days:
+            start_date = all_days[0]["date"]
+            end_date = all_days[-1]["date"]
+
+            console.print(
+                f"\n[bold green]✓[/bold green] @{data['username']}: "
+                f"{data['total_contributions']} contributions from {start_date} to {end_date}, "
+                f"{len(data['weeks'])} weeks in total.\n"
+            )
+
+    def display_contribution_graph(self, data: ContributionData) -> None:
+        """Display a GitHub-style contribution graph."""
+        weeks = data["weeks"]
+        day_labels = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]
+
+        console.print("[bold]Contribution Graph:[/bold]\n")
+
+        for day_idx in range(7):  # 0=Sunday, 6=Saturday
+            console.print(f"  {day_labels[day_idx]} ", end="")
+
+            # Print colored blocks for this day across all weeks
+            for week in weeks:
+                
+                if day_idx < len(week["days"]):
+                    day = week["days"][day_idx]
+                    level = day["level"]
+                else:
+                    level = 0
+                self._print_block(level)
+
+            console.print()  # New line after each day row
+
+        # Print legend
+        console.print("\n  Less ", end="")
+        for level in range(5):
+            self._print_block(level)
+            console.print("  ", end="")
+        console.print("More")
+
+    COLOR_MAP = {
+        0: "",        # Transparent
+        1: "on rgb(0,109,50)",           # Light green
+        2: "on rgb(38,166,65)",          # Medium green
+        3: "on rgb(57,211,83)",          # Bright green
+        4: "on rgb(87,242,135)",         # Very bright green
+    }
+
+    def _print_block(self, level: int) -> None:
+        """Print a colored block based on contribution level."""
+        text = Text("  ", style=self.COLOR_MAP.get(level, ""))
+        console.print(text, end="")

gh_space_shooter/constants.py

@@ -0,0 +1,11 @@
+"""Global constants for the application."""
+
+# GitHub contribution graph dimensions
+NUM_WEEKS = 52  # Number of weeks in contribution graph
+NUM_DAYS = 7  # Number of days in a week (Sun-Sat)
+SHIP_POSITION_Y = NUM_DAYS + 3  # Ship is positioned just below the grid
+
+SHIP_SPEED = 0.25  # Cells per frame the ship moves
+BULLET_SPEED = 0.15  # Cells per frame the bullet moves
+FRAME_DURATION_MS = 20  # Duration of each frame in milliseconds
+SHIP_SHOOT_COOLDOWN_FRAMES = 10  # Frames between ship shots

gh_space_shooter/game/__init__.py

@@ -0,0 +1,27 @@
+"""Game animation module for GitHub contribution visualization."""
+
+from .animator import Animator
+from .drawables import Bullet, Drawable, Enemy, Explosion, Ship, Starfield
+from .game_state import GameState
+from .renderer import Renderer
+from .strategies.base_strategy import Action, BaseStrategy
+from .strategies.column_strategy import ColumnStrategy
+from .strategies.random_strategy import RandomStrategy
+from .strategies.row_strategy import RowStrategy
+
+__all__ = [
+    "Animator",
+    "Bullet",
+    "Drawable",
+    "Enemy",
+    "Explosion",
+    "GameState",
+    "Renderer",
+    "Ship",
+    "Starfield",
+    "BaseStrategy",
+    "Action",
+    "ColumnStrategy",
+    "RowStrategy",
+    "RandomStrategy",
+]

gh_space_shooter/game/animator.py

@@ -0,0 +1,101 @@
+"""Animator for generating GIF animations from game strategies."""
+
+from typing import Iterator
+
+from PIL import Image
+
+
+from ..constants import FRAME_DURATION_MS
+from ..github_client import ContributionData
+from .game_state import GameState
+from .renderer import Renderer
+from .strategies.base_strategy import BaseStrategy
+from .render_context import RenderContext
+
+
+class Animator:
+    """Generates animated GIFs from game strategies."""
+
+    def __init__(
+        self,
+        contribution_data: ContributionData,
+        strategy: BaseStrategy,
+        frame_duration: int = FRAME_DURATION_MS,
+    ):
+        """
+        Initialize animator.
+
+        Args:
+            contribution_data: The GitHub contribution data
+            strategy: The strategy to use for clearing enemies
+            frame_duration: Duration of each frame in milliseconds
+        """
+        self.contribution_data = contribution_data
+        self.strategy = strategy
+        self.frame_duration = frame_duration
+
+    def generate_gif(self, output_path: str) -> None:
+        """
+        Generate animated GIF and save to file.
+
+        Args:
+            output_path: Path where GIF should be saved
+        """
+        # Initialize game state
+        game_state = GameState(self.contribution_data)
+        renderer = Renderer(game_state, RenderContext.darkmode())
+
+        frames = self._generate_frames(game_state, renderer)
+
+        # Save as GIF
+        if frames:
+            next(frames).save(
+                output_path,
+                save_all=True,
+                append_images=list(frames),
+                duration=self.frame_duration,
+                loop=0,  # Loop forever
+                optimize=False,
+            )
+
+    def _generate_frames(
+        self, game_state: GameState, renderer: Renderer
+    ) -> Iterator[Image.Image]:
+        """
+        Generate all animation frames.
+
+        Args:
+            game_state: The game state
+            renderer: The renderer
+
+        Returns:
+            List of PIL Images representing animation frames
+        """
+
+        # Add initial frame showing starting state
+        yield renderer.render_frame()
+
+        # Process each action from the strategy
+        for action in self.strategy.generate_actions(game_state):
+            game_state.ship.move_to(action.x)
+            while game_state.can_take_action() is False:
+                game_state.animate()
+                yield renderer.render_frame()
+
+            if action.shoot:
+                game_state.shoot()
+                game_state.animate()
+                yield renderer.render_frame()
+
+        force_kill_countdown = 100
+        # Add final frames showing completion
+        while not game_state.is_complete():
+            game_state.animate()
+            yield renderer.render_frame()
+            
+            force_kill_countdown -= 1
+            if force_kill_countdown <= 0:
+                break
+            
+        for _ in range(5):
+            yield renderer.render_frame()

gh_space_shooter/game/drawables/__init__.py

@@ -0,0 +1,17 @@
+"""Drawable game objects."""
+
+from .bullet import Bullet
+from .drawable import Drawable
+from .enemy import Enemy
+from .explosion import Explosion
+from .ship import Ship
+from .starfield import Starfield
+
+__all__ = [
+    "Bullet",
+    "Drawable",
+    "Enemy",
+    "Explosion",
+    "Ship",
+    "Starfield",
+]

gh_space_shooter/game/drawables/bullet.py

@@ -0,0 +1,83 @@
+"""Bullet objects fired by the ship."""
+
+from typing import TYPE_CHECKING
+
+from PIL import ImageDraw
+
+from ...constants import BULLET_SPEED, SHIP_POSITION_Y
+from .drawable import Drawable
+from .explosion import Explosion
+
+if TYPE_CHECKING:
+    from .enemy import Enemy
+    from ..game_state import GameState
+    from ..render_context import RenderContext
+
+
+class Bullet(Drawable):
+    """Represents a bullet fired by the ship."""
+
+    def __init__(self, x: int, game_state: "GameState"):
+        """
+        Initialize a bullet at ship's firing position.
+
+        Args:
+            x: Week position where bullet is fired (0-51)
+            game_state: Reference to game state for collision detection and self-removal
+        """
+        self.x = x
+        self.y: float = SHIP_POSITION_Y - 1
+        self.game_state = game_state
+
+
+    def _check_collision(self) -> "Enemy | None":
+        """Check if bullet has hit an enemy at its current position."""
+        for enemy in self.game_state.enemies:
+            if enemy.x == self.x and enemy.y >= self.y:
+                return enemy
+        return None
+
+    def animate(self) -> None:
+        """Update bullet position, check for collisions, and remove on hit."""
+        self.y -= BULLET_SPEED
+        hit_enemy = self._check_collision()
+        if hit_enemy:
+            explosion = Explosion(self.x, self.y, "small", self.game_state)
+            self.game_state.explosions.append(explosion)
+            hit_enemy.take_damage()
+            self.game_state.bullets.remove(self)
+        if self.y < -10:  # magic number to remove off-screen bullets
+            self.game_state.bullets.remove(self)
+
+    def draw(self, draw: ImageDraw.ImageDraw, context: "RenderContext") -> None:
+        """Draw the bullet with trailing tail effect."""
+
+        trail_num = 3
+        for i in range(trail_num):
+            trail_y = self.y + (i + 1) * BULLET_SPEED
+            fade_factor = (i + 1) / trail_num / 2
+            self._draw_bullet(draw, context, (self.x, trail_y), fade_factor=fade_factor)
+
+        self._draw_bullet(draw, context, (self.x, self.y), fade_factor=0.3, offset=.6)
+        self._draw_bullet(draw, context, (self.x, self.y), fade_factor=0.4, offset=.4)
+        self._draw_bullet(draw, context, (self.x, self.y), fade_factor=0.5, offset=.2)
+        self._draw_bullet(draw, context, (self.x, self.y))
+
+    def _draw_bullet(
+        self,
+        draw: ImageDraw.ImageDraw,
+        context: "RenderContext",
+        position: tuple[float, float],
+        fade_factor: float = 1,
+        offset: float = 0
+    ) -> None:
+        x, y = context.get_cell_position(position[0], position[1])
+        x += context.cell_size // 2
+        y += context.cell_size // 2
+
+        r_x = 0.5 + offset
+        r_y = 4 + offset
+        draw.rectangle(
+            [x - r_x, y - r_y, x + r_x, y + r_y],
+            fill=(*context.bullet_color, int(fade_factor * 255)),
+        )

gh_space_shooter/game/drawables/drawable.py

@@ -0,0 +1,29 @@
+"""Base Drawable interface for game objects."""
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+from PIL import ImageDraw
+
+if TYPE_CHECKING:
+    from .render_context import RenderContext
+
+
+class Drawable(ABC):
+    """Interface for objects that can be animated and drawn."""
+
+    @abstractmethod
+    def animate(self) -> None:
+        """Update the object's state for the next animation frame."""
+        pass
+
+    @abstractmethod
+    def draw(self, draw: ImageDraw.ImageDraw, context: "RenderContext") -> None:
+        """
+        Draw the object on the image.
+
+        Args:
+            draw: PIL ImageDraw object
+            context: Rendering context with helper functions and constants
+        """
+        pass

gh_space_shooter/game/drawables/enemy.py

@@ -0,0 +1,58 @@
+"""Enemy objects representing contribution graph data."""
+
+from typing import TYPE_CHECKING
+
+from PIL import ImageDraw
+
+from .drawable import Drawable
+from .explosion import Explosion
+
+if TYPE_CHECKING:
+    from ..game_state import GameState
+    from ..render_context import RenderContext
+
+
+class Enemy(Drawable):
+    """Represents an enemy at a specific position."""
+
+    def __init__(self, x: int, y: int, health: int, game_state: "GameState"):
+        """
+        Initialize an enemy.
+
+        Args:
+            x: Week position in contribution grid (0-51)
+            y: Day position in contribution grid (0-6, Sun-Sat)
+            health: Initial health/lives (1-4)
+            game_state: Reference to game state for self-removal when destroyed
+        """
+        self.x = x
+        self.y = y
+        self.health = health
+        self.game_state = game_state
+
+    def take_damage(self) -> None:
+        """
+        Enemy takes 1 damage and removes itself from game if destroyed.
+        Creates a large explosion when destroyed.
+        """
+        self.health -= 1
+        if self.health <= 0:
+            # Create large explosion with green color (enemy color)
+            explosion = Explosion(self.x, self.y, "large", self.game_state)
+            self.game_state.explosions.append(explosion)
+            self.game_state.enemies.remove(self)
+
+    def animate(self) -> None:
+        """Update enemy state for next frame (enemies don't animate currently)."""
+        pass
+
+    def draw(self, draw: ImageDraw.ImageDraw, context: "RenderContext") -> None:
+        """Draw the enemy at its position with rounded corners."""
+        x, y = context.get_cell_position(self.x, self.y)
+        color = context.enemy_colors.get(self.health, context.enemy_colors[1])
+
+        draw.rounded_rectangle(
+            [x, y, x + context.cell_size, y + context.cell_size],
+            radius=2,
+            fill=color,
+        )

gh_space_shooter/game/drawables/explosion.py

@@ -0,0 +1,72 @@
+"""Explosion effects for bullet hits and enemy destruction."""
+
+import math
+import random
+from typing import TYPE_CHECKING, Literal
+
+from PIL import ImageDraw
+
+from .drawable import Drawable
+
+if TYPE_CHECKING:
+    from ..game_state import GameState
+    from ..render_context import RenderContext
+
+
+class Explosion(Drawable):
+    """Particle explosion effect that expands and fades out."""
+
+    def __init__(self, x: float, y: float, size: Literal["small", "large"], game_state: "GameState"):
+        """
+        Initialize an explosion.
+
+        Args:
+            x: X position (week, 0-51)
+            y: Y position (day, 0-6)
+            size: "small" for bullet hits, "large" for enemy destruction
+            game_state: Reference to game state for self-removal
+        """
+        self.x = x
+        self.y = y
+        self.game_state = game_state
+        self.frame = 0
+        self.max_frames = 6 if size == "small" else 20
+        self.max_radius = 10 if size == "small" else 20
+        self.particle_count = 4 if size == "small" else 8
+        # Generate random angles for each particle
+        self.particle_angles = [random.uniform(0, 2 * math.pi) for _ in range(self.particle_count)]
+
+    def animate(self) -> None:
+        """Progress the explosion animation and remove when complete."""
+        self.frame += 1
+        if self.frame >= self.max_frames:
+            self.game_state.explosions.remove(self)
+
+    def draw(self, draw: ImageDraw.ImageDraw, context: "RenderContext") -> None:
+        """Draw expanding particle explosion with fade effect."""
+        # Calculate animation progress (0 to 1)
+        progress = self.frame / self.max_frames
+        fade = 1 - progress  # Fade out as animation progresses
+
+        # Get center position
+        center_x, center_y = context.get_cell_position(self.x, self.y)
+        center_x += context.cell_size // 2
+        center_y += context.cell_size // 2
+
+        # Draw expanding particles in random directions
+        for i in range(self.particle_count):
+            distance = progress * self.max_radius
+            angle = self.particle_angles[i]
+
+            # Particle position using random angle
+            px = int(center_x + distance * math.cos(angle))
+            py = int(center_y + distance * math.sin(angle))
+
+            # Particle size decreases as it expands
+            particle_size = int((1 - progress * 0.5) * 3) + 1
+
+            draw.rectangle(
+                [px - particle_size, py - particle_size,
+                 px + particle_size, py + particle_size],
+                fill=(*context.bullet_color, int(255 * fade))
+            )