pygkit 1.0.8__tar.gz → 1.2.1__tar.gz

{pygkit-1.0.8 → pygkit-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pygkit
-Version: 1.0.8
+Version: 1.2.1
 Summary: General-purpose Pygame CE runtime kit: UI widgets, audio, timers, interpolation, and more.
 Author: pygkit contributors
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -694,6 +694,14 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pygame-ce>=2.5
+Provides-Extra: ui
+Provides-Extra: audio
+Provides-Extra: animation
+Provides-Extra: lighting
+Provides-Extra: transitions
+Provides-Extra: inventory
+Provides-Extra: all
+Requires-Dist: pygkit[animation,audio,inventory,lighting,transitions,ui]; extra == "all"
 Dynamic: license-file
 
 # pygkit
@@ -708,7 +716,7 @@ import pygkit
 
 ## Features
 
-- **UI**: Box-model widgets with plugin compositing — progress bars, cooldown overlays, containers, dialog system
+- **UI**: Box-model widgets with plugin compositing — progress bars, cooldown overlays, containers, dialog system, buttons, menubar container, anchor/row/grid placement helpers
 - **Animation**: Multi-state `AnimationPlayer` where every state owns its own spritesheet — mixed image sizes and grids (e.g. `idle_spritesheet.png` vs `run_spritesheet.png`) in one player; pure image API, no JSON
 - **Dialog**: Typewriter effect with customizable speeds, speaker names, and progress indicators
 - **Inventory**: Grid-based item management with stacking, weight tracking, events, and serialization
@@ -722,5 +730,11 @@ import pygkit
 ## Installation
 
 ```bash
-pip install pygkit
+pip install pygkit            # core: signals, utils, protocols
+pip install "pygkit[ui]"      # widgets, dialog, cooldowns
+pip install "pygkit[all]"     # everything
 ```
+
+Available extras: `ui`, `audio`, `animation`, `lighting`,
+`transitions`, `inventory`, `all`. `import pygkit` alone loads
+core only; subsystems load lazily on first use.

{pygkit-1.0.8 → pygkit-1.2.1}/README.md

@@ -10,7 +10,7 @@ import pygkit
 
 ## Features
 
-- **UI**: Box-model widgets with plugin compositing — progress bars, cooldown overlays, containers, dialog system
+- **UI**: Box-model widgets with plugin compositing — progress bars, cooldown overlays, containers, dialog system, buttons, menubar container, anchor/row/grid placement helpers
 - **Animation**: Multi-state `AnimationPlayer` where every state owns its own spritesheet — mixed image sizes and grids (e.g. `idle_spritesheet.png` vs `run_spritesheet.png`) in one player; pure image API, no JSON
 - **Dialog**: Typewriter effect with customizable speeds, speaker names, and progress indicators
 - **Inventory**: Grid-based item management with stacking, weight tracking, events, and serialization
@@ -24,5 +24,11 @@ import pygkit
 ## Installation
 
 ```bash
-pip install pygkit
+pip install pygkit            # core: signals, utils, protocols
+pip install "pygkit[ui]"      # widgets, dialog, cooldowns
+pip install "pygkit[all]"     # everything
 ```
+
+Available extras: `ui`, `audio`, `animation`, `lighting`,
+`transitions`, `inventory`, `all`. `import pygkit` alone loads
+core only; subsystems load lazily on first use.

{pygkit-1.0.8 → pygkit-1.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pygkit"
-version = "1.0.8"
+version = "1.2.1"
 description = "General-purpose Pygame CE runtime kit: UI widgets, audio, timers, interpolation, and more."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -26,6 +26,21 @@ classifiers = [
   "Topic :: Software Development :: Libraries",
 ]
 
+[project.optional-dependencies]
+# One extra per subsystem. Empty for now: every subsystem is pure
+# pygame-ce + stdlib. Slots are reserved for future speedups
+# (lighting color math -> numpy, sprite pack -> pillow) without
+# taxing core installs.
+ui = []
+audio = []
+animation = []
+lighting = []
+transitions = []
+inventory = []
+all = [
+  "pygkit[ui, audio, animation, lighting, transitions, inventory]",
+]
+
 [project.urls]
 Homepage = "https://github.com/FluffyBrudy/pygkit"
 Repository = "https://github.com/FluffyBrudy/pygkit"

pygkit-1.2.1/src/pygkit/__init__.py

@@ -0,0 +1,223 @@
+"""pygkit - Pygame CE runtime kit.
+
+Core (signals, utils, protocols) imports eagerly. Subsystems load
+lazily on first attribute use, so ``import pygkit`` stays cheap::
+
+    pip install pygkit          # core only
+    pip install "pygkit[ui]"    # + widgets, dialog, cooldowns
+    pip install "pygkit[all]"   # everything
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+from .protocols import Clickable, Drawable, Renderable, UIElement, Updateable, Widget
+from .signals import Signal, SignalBus, signal
+from .utils import (
+    SimpleInterpolation,
+    Timer,
+    ease_in,
+    ease_in_out,
+    ease_out,
+    fit,
+    lerp,
+    load_font,
+    outline,
+    render_multiline,
+    shadow,
+    smoothstep,
+    wrap,
+)
+
+_LAZY_ATTRS: dict[str, str] = {
+    "SoundManager": "audio",
+    "SFX_CHANNELS": "audio",
+    "AnimationPlayer": "animation",
+    "AnimationSheet": "animation",
+    "PackOptions": "animation",
+    "pack_spritesheet": "animation",
+    "LightMap": "lighting",
+    "PointLight": "lighting",
+    "Spotlight": "lighting",
+    "DynamicLight": "lighting",
+    "glow_sprite": "lighting",
+    "spotlight_sprite": "lighting",
+    "dynamic_glow_sprite": "lighting",
+    "clear_sprite_cache": "lighting",
+    "RGB_ADD": "lighting",
+    "RGB_SUB": "lighting",
+    "RGB_MULT": "lighting",
+    "RGB_MIN": "lighting",
+    "RGB_MAX": "lighting",
+    "RGBA_ADD": "lighting",
+    "RGBA_SUB": "lighting",
+    "RGBA_MULT": "lighting",
+    "RGBA_MIN": "lighting",
+    "RGBA_MAX": "lighting",
+    "LIGHT_ADD": "lighting",
+    "SCENE_MULT": "lighting",
+    "TransitionRunner": "transitions",
+    "TransitionState": "transitions",
+    "FadeToBlack": "transitions",
+    "FadeFromBlack": "transitions",
+    "Crossfade": "transitions",
+    "Flash": "transitions",
+    "IrisIn": "transitions",
+    "IrisOut": "transitions",
+    "Slide": "transitions",
+    "PixelDissolve": "transitions",
+    "Shake": "transitions",
+    "Container": "ui",
+    "CooldownOverlay": "ui",
+    "ProgressBarUI": "ui",
+    "UIBase": "ui",
+    "UIOptions": "ui",
+    "BoxModel": "ui",
+    "BoxModelResult": "ui",
+    "generate_box_model": "ui",
+    "DialogBox": "ui",
+    "DialogConfig": "ui",
+    "DialogColors": "ui",
+    "DialogLine": "ui",
+    "TypewriterSpeed": "ui",
+    "Button": "ui",
+    "ButtonStyle": "ui",
+    "Menubar": "ui",
+    "ANCHORS": "ui",
+    "anchor_point": "ui",
+    "place": "ui",
+    "row": "ui",
+    "column": "ui",
+    "grid": "ui",
+    "ItemData": "inventory",
+    "InventoryConfig": "inventory",
+    "ItemStack": "inventory",
+    "InventoryEvent": "inventory",
+    "RARITY_COLORS": "inventory",
+    "DEFAULT_INVENTORY_CONFIG": "inventory",
+    "Inventory": "inventory",
+    "AssetCache": "inventory",
+    "get_cache": "inventory",
+    "generate_procedural_icon": "inventory",
+    "render_quantity_text": "inventory",
+    "Tooltip": "inventory",
+    "DragDropState": "inventory",
+    "InventoryWidget": "inventory",
+    "InventoryManager": "inventory",
+}
+
+__all__ = [
+    "SoundManager",
+    "SFX_CHANNELS",
+    "AnimationPlayer",
+    "AnimationSheet",
+    "PackOptions",
+    "pack_spritesheet",
+    "LightMap",
+    "PointLight",
+    "Spotlight",
+    "DynamicLight",
+    "glow_sprite",
+    "spotlight_sprite",
+    "dynamic_glow_sprite",
+    "clear_sprite_cache",
+    "RGB_ADD",
+    "RGB_SUB",
+    "RGB_MULT",
+    "RGB_MIN",
+    "RGB_MAX",
+    "RGBA_ADD",
+    "RGBA_SUB",
+    "RGBA_MULT",
+    "RGBA_MIN",
+    "RGBA_MAX",
+    "LIGHT_ADD",
+    "SCENE_MULT",
+    "TransitionRunner",
+    "TransitionState",
+    "FadeToBlack",
+    "FadeFromBlack",
+    "Crossfade",
+    "Flash",
+    "IrisIn",
+    "IrisOut",
+    "Slide",
+    "PixelDissolve",
+    "Shake",
+    "Container",
+    "CooldownOverlay",
+    "ProgressBarUI",
+    "UIBase",
+    "UIOptions",
+    "BoxModel",
+    "BoxModelResult",
+    "generate_box_model",
+    "DialogBox",
+    "DialogConfig",
+    "DialogColors",
+    "DialogLine",
+    "TypewriterSpeed",
+    "Button",
+    "ButtonStyle",
+    "Menubar",
+    "ANCHORS",
+    "anchor_point",
+    "place",
+    "row",
+    "column",
+    "grid",
+    "ItemData",
+    "InventoryConfig",
+    "ItemStack",
+    "InventoryEvent",
+    "RARITY_COLORS",
+    "DEFAULT_INVENTORY_CONFIG",
+    "Inventory",
+    "AssetCache",
+    "get_cache",
+    "generate_procedural_icon",
+    "render_quantity_text",
+    "Tooltip",
+    "DragDropState",
+    "InventoryWidget",
+    "InventoryManager",
+    "SimpleInterpolation",
+    "Timer",
+    "lerp",
+    "smoothstep",
+    "ease_in_out",
+    "ease_out",
+    "ease_in",
+    "load_font",
+    "outline",
+    "shadow",
+    "wrap",
+    "render_multiline",
+    "fit",
+    "Signal",
+    "SignalBus",
+    "signal",
+    "Renderable",
+    "UIElement",
+    "Drawable",
+    "Updateable",
+    "Clickable",
+    "Widget",
+]
+
+
+def __getattr__(name: str) -> Any:
+    try:
+        sub = _LAZY_ATTRS[name]
+    except KeyError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+    module = importlib.import_module(f"{__name__}.{sub}")
+    value = getattr(module, name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

{pygkit-1.0.8 → pygkit-1.2.1}/src/pygkit/inventory/__init__.py

@@ -1,20 +1,5 @@
 """
-Pygkit Inventory System - Production-grade inventory management for Pygame.
-
-A complete, generic, and optimized inventory system with:
-- Data-driven item definitions
-- Grid-based slot management
-- Drag-and-drop interactions
-- Tooltips and visual feedback
-- Asset caching for performance
-- Event-driven architecture
-- Save/load serialization support
-
-Modules:
-    data: Type definitions and data structures
-    core: Inventory logic and state management
-    assets: Asset caching and procedural generation
-    ui: UI rendering and user interaction
+Grid inventory: data definitions, slot logic, icon assets, widgets.
 
 Usage:
     from pygkit.inventory import Inventory, InventoryWidget, ItemData

{pygkit-1.0.8 → pygkit-1.2.1}/src/pygkit/inventory/assets.py

@@ -1,8 +1,5 @@
 """
-Asset caching and procedural generation for the Inventory System.
-
-Provides optimized caching of static UI elements and procedural
-generation of item icons to avoid runtime overhead.
+Slot surface cache and item icon generation.
 """
 
 from __future__ import annotations

{pygkit-1.0.8 → pygkit-1.2.1}/src/pygkit/inventory/core.py

@@ -19,8 +19,7 @@ from .data import (
 
 
 class Inventory:
-    """
-    Generic inventory container with full item management capabilities.
+    """Grid slot container with stacking, weight, events, serialization.
 
     Features:
     - Grid-based slot system with configurable size

{pygkit-1.0.8 → pygkit-1.2.1}/src/pygkit/inventory/data.py

@@ -14,8 +14,7 @@ from pygame.typing import ColorLike
 
 
 class ItemData(TypedDict, total=False):
-    """
-    Flexible item definition with required core fields and optional metadata.
+    """Item definition with required core fields and optional metadata.
 
     Required:
         id: Unique string identifier (e.g., "potion_health_small")

{pygkit-1.0.8 → pygkit-1.2.1}/src/pygkit/lighting/__init__.py

@@ -18,7 +18,7 @@ the scene) with game-agnostic lights. Straight imports, no game wiring::
         lightmap.apply(scene, blend=RGBA_MULT)
 """
 
-from pygkit.lighting.blend import (
+from .blend import (
     LIGHT_ADD,
     RGB_ADD,
     RGB_MAX,
@@ -32,9 +32,9 @@ from pygkit.lighting.blend import (
     RGBA_SUB,
     SCENE_MULT,
 )
-from pygkit.lighting.lightmap import LightMap
-from pygkit.lighting.lights import DynamicLight, PointLight, Spotlight
-from pygkit.lighting.sprites import (
+from .lightmap import LightMap
+from .lights import DynamicLight, PointLight, Spotlight
+from .sprites import (
     clear_sprite_cache,
     dynamic_glow_sprite,
     glow_sprite,

{pygkit-1.0.8 → pygkit-1.2.1}/src/pygkit/lighting/lightmap.py

@@ -23,7 +23,7 @@ from __future__ import annotations
 import pygame
 from pygame import Surface
 
-from pygkit.lighting.blend import LIGHT_ADD, SCENE_MULT
+from .blend import LIGHT_ADD, SCENE_MULT
 
 __all__ = ["LightMap"]
 

{pygkit-1.0.8 → pygkit-1.2.1}/src/pygkit/lighting/lights.py

@@ -17,9 +17,9 @@ import random
 import pygame
 from pygame import Surface
 
-from pygkit.lighting.blend import LIGHT_ADD
-from pygkit.lighting.lightmap import LightMap
-from pygkit.lighting.sprites import dynamic_glow_sprite, glow_sprite, spotlight_sprite
+from .blend import LIGHT_ADD
+from .lightmap import LightMap
+from .sprites import dynamic_glow_sprite, glow_sprite, spotlight_sprite
 
 __all__ = ["PointLight", "Spotlight", "DynamicLight"]
 

pygkit-1.2.1/src/pygkit/protocols.py

@@ -0,0 +1,49 @@
+from typing import Any, Protocol, runtime_checkable
+
+from pygame import Surface
+
+from .signals import Signal
+
+
+class Renderable(Protocol):
+    def render(self, screen: Surface, pos_offset: tuple[int, int] = (0, 0)): ...
+
+    def update(self): ...
+
+
+class UIElement(Protocol):
+    def render(self, screen: Surface): ...
+
+    def update(self): ...
+
+    @property
+    def size(self) -> tuple[int, int]: ...
+
+    @property
+    def pos(self) -> tuple[int, int]: ...
+
+
+class Drawable(Protocol):
+    def draw(self, surface: Surface): ...
+
+
+class Updateable(Protocol):
+    def update(self): ...
+
+
+@runtime_checkable
+class Widget(Renderable, Protocol):
+    @property
+    def size(self) -> tuple[int, int]: ...
+
+
+class Clickable(Widget, Protocol):
+    # contains/press/activate take screen coords; widgets track origin at render.
+
+    on_press: Signal[Any]
+
+    def contains(self, pos: tuple[int, int]) -> bool: ...
+
+    def press(self, pos: tuple[int, int]) -> bool: ...
+
+    def activate(self, pos: tuple[int, int]) -> bool: ...

{pygkit-1.0.8 → pygkit-1.2.1}/src/pygkit/ui/__init__.py

@@ -1,7 +1,10 @@
+from .anchors import ANCHORS, anchor_point, column, grid, place, row
 from .base import UIBase, UIOptions, BoxModel, BoxModelResult, generate_box_model
+from .button import Button, ButtonStyle
 from .container import Container
 from .cooldown import CooldownOverlay
 from .dialog import DialogBox, DialogConfig, DialogColors, DialogLine, TypewriterSpeed
+from .menubar import Menubar
 from .progressbar import ProgressBarUI
 
 __all__ = [
@@ -18,4 +21,13 @@ __all__ = [
     "DialogColors",
     "DialogLine",
     "TypewriterSpeed",
+    "Button",
+    "ButtonStyle",
+    "Menubar",
+    "ANCHORS",
+    "anchor_point",
+    "place",
+    "row",
+    "column",
+    "grid",
 ]

pygkit-1.2.1/src/pygkit/ui/anchors.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from pygame import Rect
+
+ANCHORS = (
+    "topleft",
+    "midtop",
+    "topright",
+    "midleft",
+    "center",
+    "midright",
+    "bottomleft",
+    "midbottom",
+    "bottomright",
+)
+
+
+def anchor_point(rect: Rect, anchor: str) -> tuple[int, int]:
+    if anchor not in ANCHORS:
+        raise ValueError(f"unknown anchor {anchor!r}; pick from {list(ANCHORS)}")
+    point = getattr(rect, anchor)
+    return (point[0], point[1])
+
+
+def place(
+    size: tuple[int, int],
+    within: Rect,
+    anchor: str = "topleft",
+    dx: int = 0,
+    dy: int = 0,
+) -> Rect:
+    rect = Rect((0, 0), (max(0, size[0]), max(0, size[1])))
+    ax, ay = anchor_point(within, anchor)
+    setattr(rect, anchor, (ax + dx, ay + dy))
+    return rect
+
+
+def row(
+    sizes: list[tuple[int, int]],
+    *,
+    gap: int = 0,
+    origin: tuple[int, int] = (0, 0),
+) -> list[Rect]:
+    rects: list[Rect] = []
+    x = origin[0]
+    for w, h in sizes:
+        rects.append(Rect(x, origin[1], max(0, w), max(0, h)))
+        x += max(0, w) + gap
+    return rects
+
+
+def column(
+    sizes: list[tuple[int, int]],
+    *,
+    gap: int = 0,
+    origin: tuple[int, int] = (0, 0),
+) -> list[Rect]:
+    rects: list[Rect] = []
+    y = origin[1]
+    for w, h in sizes:
+        rects.append(Rect(origin[0], y, max(0, w), max(0, h)))
+        y += max(0, h) + gap
+    return rects
+
+
+def grid(
+    count: int,
+    cols: int,
+    cell: tuple[int, int],
+    *,
+    gap: int = 0,
+    origin: tuple[int, int] = (0, 0),
+) -> list[Rect]:
+    if cols <= 0:
+        raise ValueError(f"cols must be > 0, got {cols}")
+    cw, ch = max(0, cell[0]), max(0, cell[1])
+    return [
+        Rect(origin[0] + (i % cols) * (cw + gap), origin[1] + (i // cols) * (ch + gap), cw, ch)
+        for i in range(max(0, count))
+    ]