charz-input 0.1.3__tar.gz

charz_input-0.1.3/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Havsalt
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

charz_input-0.1.3/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: charz-input
+Version: 0.1.3
+Summary: Versatile input interfaces, for keyboard and console
+Keywords: input,keyboard,console,interface,terminal,pygame
+Author: Havsalt
+Author-email: Havsalt <77575424+Havsalt@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Typing :: Typed
+Requires-Dist: keyboard~=0.13.5
+Requires-Dist: linflex~=0.3.3
+Requires-Dist: pygame~=2.6
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/havsalt/charz-input
+Project-URL: Repository, https://github.com/havsalt/charz-input
+Project-URL: Documentation, https://havsalt.github.io/charz-input
+Project-URL: Issues, https://github.com/havsalt/charz-input/issues
+Project-URL: Changelog, https://github.com/havsalt/charz-input/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# Charz Input
+
+Versatile input interfaces, for keyboard and console.
+
+## Examples
+
+Defining an **Action Enum**, with _all_ possible actions as variants:
+
+```python
+from enum import Enum, auto
+
+
+class Action(Enum):
+    SWITCH_INPUT = auto()
+    MOVE_LEFT = auto()
+    MOVE_RIGHT = auto()
+```
+
+Switching between `Keyboard` and `Controller` input methods:
+
+```python
+# ... defined `Action` enum ...
+
+from charz_input import Input, Keyboard, Controller
+import pygame
+
+handler: Input[Action] = Keyboard({
+    Action.SWITCH_INPUT: "Space",
+    Action.MOVE_LEFT: "A",
+    Action.MOVE_RIGHT: "D",
+})
+player_position_x: int = 0
+
+while True:
+    handler.capture_states()
+
+    if handler.is_action_just_pressed(Action.SWITCH_INPUT):
+        if isinstance(handler, Keyboard):
+            handler = Controller({
+                Action.SWITCH_INPUT: pygame.CONTROLLER_BUTTON_A,
+                Action.MOVE_LEFT: Controller.Trigger(
+                    pygame.CONTROLLER_AXIS_LEFTX,
+                    Controller.Trigger.Limit.NEGATIVE,
+                ),
+                Action.MOVE_RIGHT: Controller.Trigger(
+                    pygame.CONTROLLER_AXIS_LEFTX,
+                    Controller.Trigger.Limit.POSITIVE,
+                    deadzone=35,
+                ),
+            })
+        elif isinstance(handler, Controller):
+            handler = Keyboard({
+                Action.SWITCH_INPUT: "Space",
+                Action.MOVE_LEFT: "A",
+                Action.MOVE_RIGHT: "D",
+            })
+        continue
+
+    if handler.is_action_pressed(Action.MOVE_LEFT):
+        player_position_x -= 1
+    if handler.is_action_pressed(Action.MOVE_RIGHT):
+        player_position_x += 1
+
+    print(f"The player is located at x = {player_position_x}")
+```
+
+Declearing default keybinds:
+
+```python
+import charz_input
+
+# ... defined `Action` enum ...
+
+
+class CustomKeyboard(charz_input.Keyboard):
+    default_action_binds = {
+        Action.SWITCH_INPUT: "Space",
+        Action.MOVE_LEFT: "A",
+        Action.MOVE_RIGHT: "D",
+    }
+
+
+handler = CustomKeyboard[Action]()
+different_handler = CustomKeyboard({
+    Action.MOVE_RIGHT: "Y",  # Overrides keybind
+    # NOTE: The rest are set to their defaults,
+    # as defined by `default_action_binds`
+})
+
+# ... logic to check for action presses ...
+```
+
+You can ensure all actions are mapped at **runtime**, using a **typed class item** when instantiating:
+
+```python
+                # ┌──────┬─────> Action enum, as class item
+handler = Keyboard[Action]({
+    Action.SWITCH_INPUT: "Space",
+    Action.MOVE_LEFT: "A",
+    # Missing `Action.MOVE_RIGHT`
+})
+handler.capture_states()  # This triggers the check
+>> AssertionError: Missing actions
+
+# Annotating the variable, and not the instance, will have different results:
+handler: Keyboard[Action] = Keyboard({...})
+```
+
+Checking for keyboard presses with a modifier:
+
+```python
+handler = Keyboard[Action](
+    # ... keybinds ...
+    Action.MOVE_LEFT: "W+{modifier}",  # Dynamic, in the sense of initializing
+    Action.MOVE_RIGHT: "W",
+    Action.SWITCH_INPUT: "Ctrl+Space"  # Can also be hardcoded
+    modifier="Space",  # Default: "Shift"
+)
+
+handler.capture_states()
+print(handler.is_pressed())
+handler.action_binds
+handler.capture_states()
+print(handler.is_pressed())
+```
+
+## Roadmap
+
+- [ ] Expose action binds at runtime, so they can be changed
+- [ ] Figure out whether automatic device detection for controller is ideal
+
+## License
+
+MIT

charz_input-0.1.3/README.md

@@ -0,0 +1,134 @@
+# Charz Input
+
+Versatile input interfaces, for keyboard and console.
+
+## Examples
+
+Defining an **Action Enum**, with _all_ possible actions as variants:
+
+```python
+from enum import Enum, auto
+
+
+class Action(Enum):
+    SWITCH_INPUT = auto()
+    MOVE_LEFT = auto()
+    MOVE_RIGHT = auto()
+```
+
+Switching between `Keyboard` and `Controller` input methods:
+
+```python
+# ... defined `Action` enum ...
+
+from charz_input import Input, Keyboard, Controller
+import pygame
+
+handler: Input[Action] = Keyboard({
+    Action.SWITCH_INPUT: "Space",
+    Action.MOVE_LEFT: "A",
+    Action.MOVE_RIGHT: "D",
+})
+player_position_x: int = 0
+
+while True:
+    handler.capture_states()
+
+    if handler.is_action_just_pressed(Action.SWITCH_INPUT):
+        if isinstance(handler, Keyboard):
+            handler = Controller({
+                Action.SWITCH_INPUT: pygame.CONTROLLER_BUTTON_A,
+                Action.MOVE_LEFT: Controller.Trigger(
+                    pygame.CONTROLLER_AXIS_LEFTX,
+                    Controller.Trigger.Limit.NEGATIVE,
+                ),
+                Action.MOVE_RIGHT: Controller.Trigger(
+                    pygame.CONTROLLER_AXIS_LEFTX,
+                    Controller.Trigger.Limit.POSITIVE,
+                    deadzone=35,
+                ),
+            })
+        elif isinstance(handler, Controller):
+            handler = Keyboard({
+                Action.SWITCH_INPUT: "Space",
+                Action.MOVE_LEFT: "A",
+                Action.MOVE_RIGHT: "D",
+            })
+        continue
+
+    if handler.is_action_pressed(Action.MOVE_LEFT):
+        player_position_x -= 1
+    if handler.is_action_pressed(Action.MOVE_RIGHT):
+        player_position_x += 1
+
+    print(f"The player is located at x = {player_position_x}")
+```
+
+Declearing default keybinds:
+
+```python
+import charz_input
+
+# ... defined `Action` enum ...
+
+
+class CustomKeyboard(charz_input.Keyboard):
+    default_action_binds = {
+        Action.SWITCH_INPUT: "Space",
+        Action.MOVE_LEFT: "A",
+        Action.MOVE_RIGHT: "D",
+    }
+
+
+handler = CustomKeyboard[Action]()
+different_handler = CustomKeyboard({
+    Action.MOVE_RIGHT: "Y",  # Overrides keybind
+    # NOTE: The rest are set to their defaults,
+    # as defined by `default_action_binds`
+})
+
+# ... logic to check for action presses ...
+```
+
+You can ensure all actions are mapped at **runtime**, using a **typed class item** when instantiating:
+
+```python
+                # ┌──────┬─────> Action enum, as class item
+handler = Keyboard[Action]({
+    Action.SWITCH_INPUT: "Space",
+    Action.MOVE_LEFT: "A",
+    # Missing `Action.MOVE_RIGHT`
+})
+handler.capture_states()  # This triggers the check
+>> AssertionError: Missing actions
+
+# Annotating the variable, and not the instance, will have different results:
+handler: Keyboard[Action] = Keyboard({...})
+```
+
+Checking for keyboard presses with a modifier:
+
+```python
+handler = Keyboard[Action](
+    # ... keybinds ...
+    Action.MOVE_LEFT: "W+{modifier}",  # Dynamic, in the sense of initializing
+    Action.MOVE_RIGHT: "W",
+    Action.SWITCH_INPUT: "Ctrl+Space"  # Can also be hardcoded
+    modifier="Space",  # Default: "Shift"
+)
+
+handler.capture_states()
+print(handler.is_pressed())
+handler.action_binds
+handler.capture_states()
+print(handler.is_pressed())
+```
+
+## Roadmap
+
+- [ ] Expose action binds at runtime, so they can be changed
+- [ ] Figure out whether automatic device detection for controller is ideal
+
+## License
+
+MIT

charz_input-0.1.3/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["uv_build~=0.12.0"]
+build-backend = "uv_build"
+
+[project]
+name = "charz-input"
+version = "0.1.3"
+description = "Versatile input interfaces, for keyboard and console"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+keywords = [
+    "input",
+    "keyboard",
+    "console",
+    "interface",
+    "terminal",
+    "pygame",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development :: User Interfaces",
+    "Typing :: Typed",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "keyboard~=0.13.5",
+    "linflex~=0.3.3",
+    "pygame~=2.6",
+]
+
+[[project.authors]]
+name = "Havsalt"
+email = "77575424+Havsalt@users.noreply.github.com"
+
+[project.urls]
+Homepage = "https://github.com/havsalt/charz-input"
+Repository = "https://github.com/havsalt/charz-input"
+Documentation = "https://havsalt.github.io/charz-input"
+Issues = "https://github.com/havsalt/charz-input/issues"
+Changelog = "https://github.com/havsalt/charz-input/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+    { include-group = "test" },
+    { include-group = "docs" },
+    "commitizen",
+]
+test = [
+    "ty==0.0.65",
+    "ruff~=0.16.0",
+    "pytest~=9.1",
+    "tox~=4.58",
+    "tox-uv~=1.36",
+]
+docs = [
+    "zensical==0.0.52",
+    "pydoc-markdown~=4.8",
+    "pydoc-markdown-havsalt~=0.1.3",
+]
+
+[tool.uv.sources.commitizen]
+git = "https://github.com/havsalt/commitizen"

charz_input-0.1.3/pyproject.toml.orig

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["uv_build~=0.12.0"]
+build-backend = "uv_build"
+
+[project]
+name = "charz-input"
+version = "0.1.3"
+description = "Versatile input interfaces, for keyboard and console"
+authors = [
+    { name = "Havsalt", email = "77575424+Havsalt@users.noreply.github.com" }
+]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+keywords = ["input", "keyboard", "console", "interface", "terminal", "pygame"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development :: User Interfaces",
+    "Typing :: Typed",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "keyboard~=0.13.5",
+    "linflex~=0.3.3",
+    "pygame~=2.6",
+]
+
+[dependency-groups]
+dev = [
+    { include-group = "test" },
+    { include-group = "docs" },
+    "commitizen",  # Use custom version until v5 with overrides
+]
+test = [
+    "ty==0.0.65",
+    "ruff~=0.16.0",
+    "pytest~=9.1",
+    "tox~=4.58",
+    "tox-uv~=1.36",
+]
+docs = [
+    "zensical==0.0.52",
+    "pydoc-markdown~=4.8",
+    "pydoc-markdown-havsalt~=0.1.3",
+]
+
+[tool.uv.sources]
+commitizen = { git = "https://github.com/havsalt/commitizen" }
+
+[project.urls]
+Homepage = "https://github.com/havsalt/charz-input"
+Repository = "https://github.com/havsalt/charz-input"
+Documentation = "https://havsalt.github.io/charz-input"
+Issues = "https://github.com/havsalt/charz-input/issues"
+Changelog = "https://github.com/havsalt/charz-input/blob/main/CHANGELOG.md"

charz_input-0.1.3/src/charz_input/__init__.py

@@ -0,0 +1,18 @@
+"""
+Charz: Input
+============
+
+Versatile input interfaces, for keyboard and console.
+"""
+
+__all__ = [
+    "AbstractInput",
+    "Controller",
+    "Input",
+    "Keyboard",
+]
+
+from ._abstract import AbstractInput
+from ._controller import Controller
+from ._interface import Input
+from ._keyboard import Keyboard

charz_input-0.1.3/src/charz_input/_abstract.py

@@ -0,0 +1,52 @@
+from abc import ABC, abstractmethod
+from enum import Enum
+
+from linflex import Vec2
+
+
+class AbstractInput[Action: Enum](ABC):
+    """Abstract base class for [`Input`] implementations.
+
+    Inheriting from [`AbstractInput`] was chosen over `Protocol`,
+    to provide better inferred type relation in subclasses:
+
+    ```python
+    handler: Input = Controller[MyAction]()
+    reveal_type(handler)  # type is: Input[MyAction]
+    ```
+
+    `Protocol` would have yielded `Input[Unknown]`.
+
+    An **advantage** to using an **abstract base class**,
+    is partial default behaviour, like `get_vector`.
+    """
+
+    @abstractmethod
+    def capture_states(self) -> None:
+        """Capture press state of all `Action` variants.
+
+        Used for monitoring changes over time.
+
+        !!! tip "Technical"
+
+            Should be called at the start of the frame,
+            **before** actions are checked for.
+        """
+
+    @abstractmethod
+    def is_action_pressed(self, action: Action) -> bool: ...
+
+    @abstractmethod
+    def is_action_just_pressed(self, action: Action) -> bool: ...
+
+    def get_vector(
+        self,
+        negative_x: Action,
+        positive_x: Action,
+        negative_y: Action,
+        positive_y: Action,
+    ) -> Vec2:
+        return Vec2(
+            self.is_action_pressed(positive_x) - self.is_action_pressed(negative_x),
+            self.is_action_pressed(positive_y) - self.is_action_pressed(negative_y),
+        )

charz_input-0.1.3/src/charz_input/_controller.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from enum import Enum, auto
+from typing import assert_never, get_args
+
+import pygame
+
+from ._abstract import AbstractInput
+
+type Positive[N: (int, float, complex)] = N
+type Percent = int
+"""Example: `x: Percent = 10`, meaning _10%_. When computing: `result = x / 100`"""
+
+
+class Controller[Action: Enum](AbstractInput[Action]):
+    """[`Controller`] implementation for [`Input`] handler."""
+
+    type DeviceID = int
+    type Button = int
+    type Axis = int
+    type ActionBinds = Mapping[Action, Controller.Button | Controller.Trigger]
+
+    # Can be defined in subclass definition
+    default_action_binds: ActionBinds  # ClassVar
+
+    class Trigger:
+        class Limit(Enum):
+            POSITIVE = auto()
+            NEGATIVE = auto()
+
+        def __init__(
+            self,
+            axis: Controller.Axis,
+            limit: Controller.Trigger.Limit | None = None,
+            deadzone: Positive[Percent] = 10,
+        ) -> None:
+            if deadzone <= 0:
+                raise ValueError(f"Argument 'deadzone' <= 0, got {deadzone}")
+
+            if not pygame.display.get_init():
+                pygame.display.init()
+            if not pygame.joystick.get_init():
+                pygame.joystick.init()
+
+            self.axis = axis
+            self.limit = limit
+            self.deadzone = deadzone
+
+    def __init__(
+        self,
+        action_binds: Controller.ActionBinds | None = None,
+        device_id: Controller.DeviceID | None = None,
+    ) -> None:
+        if device_id is not None:
+            self._joystick = pygame.joystick.Joystick(device_id)
+        else:  # Attempt to connect to the next available controller
+            # NOTE: This branch _might_ be redundant,
+            #       and param `device_id` should be required
+            for attempt_id in range(pygame.joystick.get_count()):
+                try:
+                    joystick = pygame.joystick.Joystick(attempt_id)
+                except pygame.error:
+                    continue
+                self._joystick = joystick
+                break
+            else:  # nobreak
+                raise ValueError("Could not automatically find an available controller")
+        self._action_states = dict[Action, bool]()
+        self._last_action_states = dict[Action, bool]()
+
+        default_binds: Controller.ActionBinds = getattr(
+            self,
+            "default_action_binds",
+            {},
+        )
+        final_binds = dict(default_binds)  # Prevent mutable reference
+        override_binds = action_binds or {}
+        final_binds.update(override_binds)
+        self._action_binds: Controller.ActionBinds = final_binds
+
+    def capture_states(self) -> None:
+        """Capture all action state.
+
+        If instantiated with `handler = Controller[MyAction]()`,
+        then `MyAction` will be available at runtime.
+        Therefore, by calling this method,
+        all actions are ensured they map correctly from an action variant to its state.
+
+        `NOTE` Requires `pygame.event.pump` to be called **before** `capture_states`.
+        """
+        if (orig_class := getattr(self, "__orig_class__", None)) is not None:
+            action_enum = get_args(orig_class)[0]
+            assert all(map(self._action_binds.__contains__, action_enum)), (
+                "Missing actions"
+            )
+        self._last_action_states = self._action_states
+        self._action_states = {
+            action: self.is_action_pressed(action) for action in self._action_binds
+        }
+
+    def is_action_pressed(self, action: Action) -> bool:
+        trigger = self._action_binds[action]
+
+        if not isinstance(trigger, Controller.Trigger):
+            return self._joystick.get_button(trigger)
+
+        strength = self._joystick.get_axis(trigger.axis)
+        match trigger.limit:
+            case Controller.Trigger.Limit.POSITIVE:
+                return strength > trigger.deadzone / 100
+            case Controller.Trigger.Limit.NEGATIVE:
+                return strength < -trigger.deadzone / 100
+            case None:
+                return abs(strength) > trigger.deadzone / 100
+            case _:
+                assert_never(trigger.limit)
+
+    def is_action_just_pressed(self, action: Action) -> bool:
+        return (  # fmt: off
+            not self._last_action_states.get(action, True)
+            and self.is_action_pressed(action)
+        )
+        # fmt: on

charz_input-0.1.3/src/charz_input/_interface.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from linflex import Vec2
+
+
+class Input[Action: Enum](Protocol):
+    """Protocol for implementing input handlers.
+
+    Implementations of [`Input`] are used as input handlers,
+    which then can be **swapped at runtime**.
+
+    Example:
+        You have a game that takes input from the keyboard,
+        until a controller is detected.
+    """
+
+    def capture_states(self) -> None: ...
+    def is_action_pressed(self, action: Action) -> bool: ...
+    def is_action_just_pressed(self, action: Action) -> bool: ...
+    def get_vector(
+        self,
+        negative_x: Action,
+        positive_x: Action,
+        negative_y: Action,
+        positive_y: Action,
+    ) -> Vec2: ...

charz_input-0.1.3/src/charz_input/_keyboard.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from enum import Enum
+from typing import get_args
+
+import keyboard
+
+from ._abstract import AbstractInput
+
+
+class Keyboard[Action: Enum](AbstractInput[Action]):
+    """[`Keyboard`] implementation for [`Input`] handler."""
+
+    type Key = str | int
+    type ScanCode = int
+    type KeyCombination = str | list[ScanCode]
+    type ActionBinds = Mapping[Action, Keyboard.Key | Keyboard.KeyCombination]
+
+    #: Can be defined in subclass definition
+    default_action_binds: ActionBinds  # ClassVar
+
+    def __init__(
+        self,
+        action_binds: ActionBinds | None = None,
+        modifier_key: Keyboard.Key = "Shift",
+    ) -> None:
+        self._action_states = dict[Action, bool]()
+        self._last_action_states = dict[Action, bool]()
+        self._modifier_key = modifier_key
+
+        default_binds: Keyboard.ActionBinds = getattr(self, "default_action_binds", {})
+        final_binds = dict(default_binds)  # Prevent mutable reference
+        override_binds = action_binds or {}
+        final_binds.update(override_binds)
+        self._action_binds: Keyboard.ActionBinds = final_binds
+
+    def capture_states(self) -> None:
+        # Ensure all actions are mapped.
+        # If instantiated with `handler = Keyboard[MyAction]()`,
+        # then `MyAction` will be available at runtime
+        if (orig_class := getattr(self, "__orig_class__", None)) is not None:
+            action_enum = get_args(orig_class)[0]
+            assert all(map(self._action_binds.__contains__, action_enum)), (
+                "Missing actions"
+            )
+        self._last_action_states = self._action_states
+        self._action_states = {
+            action: self.is_action_pressed(action) for action in self._action_binds
+        }
+
+    def is_action_pressed(self, action: Action) -> bool:
+        trigger = self._action_binds[action]
+        if isinstance(trigger, str):
+            keys = trigger.format(modifier=self._modifier_key)
+            return keyboard.is_pressed(keys)
+        # Single scancode or list of scancodes
+        return keyboard.is_pressed(trigger)
+
+    def is_action_just_pressed(self, action: Action) -> bool:
+        return (  # fmt: off
+            not self._last_action_states.get(action, True)
+            and self.is_action_pressed(action)
+        )
+        # fmt: on