typer-extensions 0.2.1__py3-none-any.whl

typer_extensions/__init__.py

@@ -0,0 +1,9 @@
+"""Typer extension for command aliases with grouped help display"""
+
+from typer_extensions._version import __version__
+from typer_extensions.core import ExtendedTyper
+
+__all__ = [
+    "ExtendedTyper",
+    "__version__",
+]

typer_extensions/_version.py

@@ -0,0 +1,3 @@
+"""Version information for typer-extensions"""
+
+__version__ = "0.2.1"

typer_extensions/core.py

@@ -0,0 +1,538 @@
+"""Core ExtendedTyper class extending typer.Typer with alias support"""
+
+import re
+from typing import Any, Callable, Optional, Protocol, Union, cast
+
+import typer
+import typer.main
+from click import Command, Context, Group
+from typer.core import TyperGroup
+
+
+class HasName(Protocol):
+    """Protocol for objects that have a name attribute"""
+
+    __name__: str
+
+
+class AliasedGroup(TyperGroup):
+    """Custom Click Group that handles command aliases"""
+
+    def __init__(
+        self,
+        *args: Any,
+        aliased_typer: Optional["ExtendedTyper"] = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialise the AliasedGroup
+
+        Args:
+            aliased_typer: Reference to the ExtendedTyper instance for alias resolution
+            *args, **kwargs: Arguments passed to Click Group
+        """
+        super().__init__(*args, **kwargs)
+        self.aliased_typer = aliased_typer
+
+    def get_command(self, ctx: Context, cmd_name: str) -> Optional[Command]:
+        """Override Click's get_command to support aliases
+
+        Args:
+            ctx: The Click context
+            cmd_name: The name of the command
+
+        Returns:
+            The command if found, None otherwise
+        """
+        if self.aliased_typer is None:
+            return super().get_command(ctx, cmd_name)
+
+        # Try to resolve as an active alias first
+        primary_cmd = self.aliased_typer._resolve_alias(cmd_name)
+        if primary_cmd is not None:
+            return super().get_command(ctx, primary_cmd)
+
+        cmd = super().get_command(ctx, cmd_name)
+        if cmd is not None:
+            return cmd
+
+        return None
+
+    def format_help(self, ctx: Context, formatter: Any) -> None:
+        """Override TyperGroup's format_help to inject aliases into Rich output
+
+        Args:
+            ctx: The Click context
+            formatter: The Click HelpFormatter instance
+        """
+        # Check if Rich formatting is enabled
+        if not hasattr(self, "rich_markup_mode") or self.rich_markup_mode is None:
+            return super().format_help(ctx, formatter)
+
+        from typer import rich_utils
+
+        # Store original _print_commands_panel
+        original_print = rich_utils._print_commands_panel
+
+        def custom_print_commands_panel(
+            *,
+            name: str,
+            commands: list[Command],
+            markup_mode: Any,
+            console: Any,
+            cmd_len: int,
+        ) -> None:
+            """Wrapper that modifies command names to include aliases
+
+            Args:
+                name: The name of the command group
+                commands: The list of commands in the group
+                markup_mode: The markup mode for the console output
+                console: The console instance for output
+                cmd_len: The length of the longest command name
+            """
+            modified_commands = []
+            max_len = cmd_len
+
+            for command in commands:
+                if (
+                    self.aliased_typer
+                    and self.aliased_typer._show_aliases_in_help
+                    and command.name in self.aliased_typer._command_aliases
+                ):
+                    from .format import format_command_with_aliases
+
+                    formatted_name = format_command_with_aliases(
+                        command.name,
+                        self.aliased_typer._command_aliases[command.name],
+                        display_format=self.aliased_typer._alias_display_format,
+                        max_num=self.aliased_typer._max_num_aliases,
+                        separator=self.aliased_typer._alias_separator,
+                    )
+
+                    # Longest formatted name for correct column width
+                    max_len = max(max_len, len(formatted_name))
+
+                    # Temporary command object with the formatted name
+                    cmd_copy = command
+                    cmd_copy.name = formatted_name
+
+                    modified_commands.append(cmd_copy)
+                else:
+                    modified_commands.append(command)
+
+            # Call the original with modified commands & cmd_len
+            original_print(
+                name=name,
+                commands=modified_commands,
+                markup_mode=markup_mode,
+                console=console,
+                cmd_len=max_len,
+            )
+
+        # Temporarily replace the function
+        rich_utils._print_commands_panel = custom_print_commands_panel  # type: ignore[assignment]
+        try:
+            # Call parent's format_help with custom_print_commands_panel
+            super().format_help(ctx, formatter)
+        finally:
+            # Restore original function
+            rich_utils._print_commands_panel = original_print  # type: ignore[assignment]
+
+
+# Store original function
+_original_get_group_from_info = typer.main.get_group_from_info
+
+
+def _aliased_get_group_from_info(
+    typer_info: "typer.main.TyperInfo",
+    **kwargs: Any,
+) -> Union[AliasedGroup, TyperGroup]:
+    """Custom version of get_group_from_info that returns AliasedGroup for ExtendedTyper instances
+
+    Args:
+        typer_info: The TyperInfo instance containing information about the Typer instance
+        **kwargs: Additional keyword arguments
+
+    Returns:
+        An AliasedGroup if the Typer instance is an ExtendedTyper, otherwise a standard TyperGroup
+    """
+    # Call original function to get standard TyperGroup
+    group = _original_get_group_from_info(typer_info, **kwargs)
+
+    # If Typer instance is ExtendedTyper, wrap it in an AliasedGroup
+    if isinstance(typer_info.typer_instance, ExtendedTyper):
+        aliased_typer = typer_info.typer_instance
+        aliased_group = AliasedGroup(
+            name=group.name,
+            callback=group.callback,
+            params=group.params,
+            help=group.help,
+            epilog=group.epilog,
+            short_help=group.short_help,
+            options_metavar=group.options_metavar,
+            subcommand_metavar=group.subcommand_metavar,
+            chain=group.chain,
+            result_callback=group.result_callback,
+            context_settings=group.context_settings,
+            aliased_typer=aliased_typer,
+            rich_markup_mode=group.rich_markup_mode,
+            rich_help_panel=group.rich_help_panel,
+        )
+
+        for name, cmd in group.commands.items():
+            aliased_group.add_command(cmd, name=name)
+
+        return aliased_group
+
+    # Standard TyperGroup
+    return group
+
+
+# Apply monkey-patch to Typer's group creation function
+typer.main.get_group_from_info = _aliased_get_group_from_info  # type: ignore[assignment]
+
+
+class ExtendedTyper(typer.Typer):
+    """Typer application with alias support"""
+
+    # Expose Typer's Argument and Option
+    Argument = staticmethod(typer.Argument)
+    Option = staticmethod(typer.Option)
+
+    def __init__(
+        self,
+        *args: Any,
+        alias_case_sensitive: Optional[bool] = None,
+        show_aliases_in_help: bool = True,
+        alias_display_format: str = "({aliases})",
+        alias_separator: str = ", ",
+        max_num_aliases: int = 3,
+        **kwargs: Any,
+    ) -> None:
+        """Initialise ExtendedTyper
+
+        Args:
+            *args: Positional arguments for Typer
+            alias_case_sensitive: Whether aliases are case sensitive. If None (default), will match
+                Typer's case_sensitive setting from context_settings (defaults to True)
+            show_aliases_in_help: Whether to show aliases in help
+            alias_display_format: Format string for displaying aliases in help
+                Must include the placeholder '{aliases}'
+            alias_separator: Separator for displaying aliases in help (default: ', ')
+            max_num_aliases: Maximum number of aliases to display before truncating with '+ N more'
+            **kwargs: Keyword arguments for Typer
+        """
+        kwargs.setdefault("rich_markup_mode", "rich")
+        kwargs.setdefault("rich_help_panel", True)
+        super().__init__(*args, **kwargs)
+
+        # Sync with Typer's case_sensitive setting if not explicitly set
+        if alias_case_sensitive is None:
+            context_settings = kwargs.get("context_settings") or {}
+            typer_case_sensitive = context_settings.get("case_sensitive", True)
+            self._alias_case_sensitive = typer_case_sensitive
+        else:
+            self._alias_case_sensitive = alias_case_sensitive
+
+        self._show_aliases_in_help = show_aliases_in_help
+        self._alias_display_format = alias_display_format
+        self._alias_separator = alias_separator
+        self._max_num_aliases = max_num_aliases
+
+        # Mapping of command names to aliases (O(1) lookup)
+        self._command_aliases: dict[str, list[str]] = {}
+        self._alias_to_command: dict[str, str] = {}
+
+    def _normalise_name(self, name: str) -> str:
+        """Normalise command/alias name based on case sensitivity
+
+        Args:
+            name: The command/alias name to normalise
+
+        Returns:
+            The normalised command/alias name (lowercase if case insensitive)
+        """
+        return name.lower() if not self._alias_case_sensitive else name
+
+    def _register_alias(self, command_name: str, alias: str) -> None:
+        """Register an alias for a command
+
+        Args:
+            command_name: The name of the command
+            alias: The alias to register
+
+        Raises:
+            ValueError: If the alias conflicts with an existing command/alias
+        """
+        if not alias or not isinstance(alias, str):
+            raise ValueError("Alias must be a non-empty string")
+
+        if any(c.isspace() for c in alias):
+            raise ValueError("Alias cannot contain whitespace")
+
+        if not re.match(r"^[\w\-]+$", alias, re.UNICODE):
+            raise ValueError(
+                "Alias must only contain alphanumeric characters, dashes, and underscores (Unicode allowed)"
+            )
+
+        normalised_alias = self._normalise_name(alias)
+        normalised_cmd = self._normalise_name(command_name)
+
+        # Check if alias is the same as command name
+        if normalised_alias == normalised_cmd:
+            raise ValueError(
+                f"Alias '{alias}' cannot be the same as command name '{command_name}'"
+            )
+
+        # Check if alias is already registered
+        if normalised_alias in self._alias_to_command:
+            existing_cmd = self._alias_to_command[normalised_alias]
+            raise ValueError(
+                f"Alias '{alias}' is already registered for command '{existing_cmd}'"
+            )
+
+        # Register the alias
+        self._alias_to_command[normalised_alias] = command_name
+
+        # Add alias to command mapping
+        if command_name not in self._command_aliases:
+            self._command_aliases[command_name] = []
+        self._command_aliases[command_name].append(alias)
+
+    def _register_command_with_aliases(
+        self,
+        func: Callable[..., Any],
+        name: str,
+        aliases: Optional[list[str]] = None,
+        **kwargs: Any,
+    ) -> Command:
+        """Register a command with aliases
+
+        Args:
+            func: The command function
+            name: The command name
+            aliases: List of aliases for the command
+            **kwargs: Additional keyword arguments for command registration
+
+        Returns:
+            The registered Click Command object
+
+        Raises:
+            ValueError: If any aliases conflict with existing commands/aliases
+        """
+        aliases = aliases or []
+
+        self.command(name, **kwargs)(func)
+
+        for alias in aliases:
+            self._register_alias(name, alias)
+
+        click_obj = typer.main.get_command(self)
+        if isinstance(click_obj, Group):
+            command = click_obj.commands[name]
+        else:
+            command = click_obj
+
+        return command
+
+    def _resolve_alias(self, name: str) -> Optional[str]:
+        """Resolve a command/alias name to its primary command name
+
+        Args:
+            name: The command/alias name to resolve
+
+        Returns:
+            The primary command name if found, or None if not found or removed
+        """
+        normalised_name = self._normalise_name(name)
+
+        return self._alias_to_command.get(normalised_name)
+
+    def get_command(self, ctx: Context, cmd_name: str) -> Optional[Command]:
+        """Programmatically retrieve a command by its name/alias
+
+        Args:
+            ctx: The context in which the command is being invoked
+            cmd_name: The name or alias of the command to retrieve
+
+        Returns:
+            The command if found, else None
+        """
+        if not hasattr(self, "_group") or self._group is None:
+            if not hasattr(self, "_command") or self._command is None:
+                # Trigger CLI build
+                click_obj = typer.main.get_command(self)
+
+                if hasattr(click_obj, "commands"):
+                    self._group = click_obj
+                else:
+                    self._command = click_obj
+
+        primary_cmd = self._resolve_alias(cmd_name)
+        effective_name = primary_cmd if primary_cmd is not None else cmd_name
+
+        # Single command apps
+        if hasattr(self, "_command"):
+            command = self._command
+            if command.name == effective_name:
+                return command
+            return None
+
+        # Multi-command apps
+        group = cast(Group, self._group)
+        if effective_name in group.commands:
+            return group.commands[effective_name]
+        return group.get_command(ctx, effective_name)
+
+    def command_with_aliases(
+        self,
+        name: Optional[Union[str, Callable[..., Any]]] = None,
+        *,
+        aliases: Optional[list[str]] = None,
+        **kwargs: Any,
+    ) -> Callable[[Callable[..., Any]], Command]:
+        """Decorator to register a command with aliases, similar to Typer's @app.command decorator
+
+        Args:
+            name: The name of the command - if not provided, inferred from the function name
+            aliases: A list of aliases for the command
+            **kwargs: Additional keyword arguments for command registration
+                (e.g. help, hidden, deprecated, context_settings, etc.)
+
+        Returns:
+            A decorator that registers the command with the specified name and aliases
+        """
+        # Decorator used without parentheses (name inferred)
+        if callable(name):
+            func = name
+
+            return self._register_command_with_aliases(
+                func, name=cast(HasName, func).__name__, aliases=None, **kwargs
+            )
+
+        # Standard decorator with parentheses
+        def decorator(func: Callable[..., Any]) -> Command:
+            """Decorator to register a command with aliases
+
+            Args:
+                func: The command function
+
+            Returns:
+                The registered Click Command object
+            """
+            if isinstance(name, str) and name:
+                command_name = name
+            else:
+                command_name = cast(HasName, func).__name__
+
+            return self._register_command_with_aliases(
+                func, name=command_name, aliases=aliases, **kwargs
+            )
+
+        return decorator
+
+    def add_aliased_command(
+        self,
+        func: Callable[..., Any],
+        name: Optional[str] = None,
+        aliases: Optional[list[str]] = None,
+        **kwargs: Any,
+    ) -> Command:
+        """Programmatically register a command with aliases
+
+        Args:
+            func: The command function
+            name: The name of the command - if not provided, inferred from the function name
+            aliases: A list of aliases for the command
+            **kwargs: Additional keyword arguments for command registration
+
+        Returns:
+            The registered Click Command object
+
+        Raises:
+            ValueError: If any alias conflicts with existing commands/aliases
+        """
+        if isinstance(name, str) and name:
+            command_name = name
+        else:
+            command_name = cast(HasName, func).__name__
+
+        return self._register_command_with_aliases(
+            func, name=command_name, aliases=aliases, **kwargs
+        )
+
+    def add_alias(self, command_name: str, alias: str) -> None:
+        """Programmatically add an alias to an existing command
+
+        This does not allow adding aliases to single-command applications, in line with Typer's design principle of treating single-commands apps as the default command, making aliases redundant
+
+        Args:
+            command_name: The name of the existing command
+            alias: The alias to add
+
+        Raises:
+            ValueError: If the command doesn't exist, is a single-command app, or the alias conflicts with existing commands/aliases
+        """
+        # Get the underlying Click group
+        click_obj = typer.main.get_command(self)
+
+        if not isinstance(click_obj, Group):
+            raise ValueError("Cannot add aliases to single-command applications")
+
+        existing_command = click_obj.get_command(Context(click_obj), command_name)
+        if existing_command is None:
+            raise ValueError(f"Command '{command_name}' does not exist")
+
+        self._register_alias(command_name, alias)
+
+    def remove_alias(self, alias: str) -> bool:
+        """Programmatically remove an alias from an existing command
+
+        Args:
+            alias: The alias to remove
+
+        Returns:
+            True if the alias was removed, False if it doesn't exist
+        """
+        normalised_alias = self._normalise_name(alias)
+
+        if normalised_alias not in self._alias_to_command:
+            return False
+
+        primary_name = self._alias_to_command[normalised_alias]
+        del self._alias_to_command[normalised_alias]
+
+        if primary_name in self._command_aliases:
+            try:
+                self._command_aliases[primary_name].remove(alias)
+
+                if not self._command_aliases[primary_name]:
+                    del self._command_aliases[primary_name]
+
+            except ValueError:
+                pass
+
+        return True
+
+    def get_aliases(self, command_name: str) -> list[str]:
+        """Retrieve the list of aliases for a given command
+
+        Args:
+            command_name: The name of the command
+
+        Returns:
+            A list of aliases for the command, or an empty list if no aliases or command doesn't exist
+        """
+        if command_name in self._command_aliases:
+            return self._command_aliases[command_name].copy()
+        return []
+
+    def list_commands_with_aliases(self) -> dict[str, list[str]]:
+        """List all commands and their aliases
+
+        Returns a dictionary mapping command names to their aliases - only includes commands with aliases and returns a copy, so modifications won't affect the original
+
+        Returns:
+            A dictionary mapping command names to their aliases, or an empty dictionary if no commands have aliases
+        """
+        return {cmd: aliases.copy() for cmd, aliases in self._command_aliases.items()}

typer_extensions/format.py

@@ -0,0 +1,104 @@
+"""Help text formatting utilities"""
+
+from typing import Optional
+
+
+def truncate_aliases(
+    aliases: list[str],
+    max_num: int,
+    separator: str = ", ",
+) -> str:
+    """Truncate the list of aliases to a maximum number, join with a separator, and truncate with '+ N more' if needed
+
+    Args:
+        aliases: The list of aliases to truncate
+        max_num: The maximum number of aliases to display
+        separator: The separator to use when joining aliases, defaults to ', '
+
+    Returns:
+        The formatted string of aliases, truncated if necessary
+    """
+    if not aliases:
+        return ""
+
+    # Handle negative max_num edge case
+    if max_num < 0:
+        max_num = 0
+
+    if len(aliases) <= max_num:
+        return separator.join(aliases)
+
+    visible = aliases[:max_num]
+    hidden = len(aliases) - max_num
+
+    return f"{separator.join(visible)}{separator if visible else ''}+{hidden} more"
+
+
+def format_command_with_aliases(
+    command_name: str,
+    aliases: list[str],
+    *,
+    display_format: str = "({aliases})",
+    max_num: int = 3,
+    separator: str = ", ",
+) -> str:
+    """Format a command with its aliases with specified format
+
+    Args:
+        command_name: The name of the command
+        aliases: The list of aliases for the command
+        display_format: The format string for displaying aliases
+        max_num: The maximum number of aliases to display
+        separator: The separator to use between aliases
+
+    Returns:
+        The formatted command string with aliases
+    """
+    if not aliases:
+        return command_name
+
+    aliases_str = truncate_aliases(aliases, max_num, separator)
+
+    aliases_display = display_format.format(aliases=aliases_str)
+
+    return f"{command_name} {aliases_display}"
+
+
+def format_commands_section(
+    commands: list[tuple[str, Optional[str]]],
+    command_aliases: dict[str, list[str]],
+    *,
+    display_format: str = "({aliases})",
+    max_num: int = 3,
+    separator: str = ", ",
+) -> list[tuple[str, Optional[str]]]:
+    """Format a list of commands with their aliases
+
+    Args:
+        commands: The list of commands to format
+        command_aliases: A dictionary mapping command names to their aliases
+        display_format: The format string for displaying aliases
+        max_num: The maximum number of aliases to display
+        separator: The separator to use between aliases
+
+    Returns:
+        A list of (formatted_command, help text) tuples
+    """
+    formatted_commands = []
+
+    for cmd_name, help_text in commands:
+        if cmd_name in command_aliases:
+            aliases = command_aliases[cmd_name]
+            formatted_cmd = format_command_with_aliases(
+                cmd_name,
+                aliases,
+                display_format=display_format,
+                max_num=max_num,
+                separator=separator,
+            )
+        else:
+            formatted_cmd = cmd_name
+
+        formatted_commands.append((formatted_cmd, help_text))
+
+    return formatted_commands

typer_extensions-0.2.1.dist-info/METADATA

@@ -0,0 +1,506 @@
+Metadata-Version: 2.4
+Name: typer-extensions
+Version: 0.2.1
+Summary: Command aliases for Typer CLI applications
+Project-URL: Homepage, https://github.com/rdawebb/typer-extensions
+Project-URL: Documentation, https://github.com/rdawebb/typer-extensions#readme
+Project-URL: Repository, https://github.com/rdawebb/typer-extensions
+Project-URL: Changelog, https://github.com/rdawebb/typer-extensions/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/rdawebb/typer-extensions/issues
+Author: Rob Webb
+License: MIT
+License-File: LICENSE
+Keywords: aliases,cli,click,command-line,typer
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Shells
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: click<9.0.0,>=8.0.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: prek<1.0.0,>=0.2.27; extra == 'dev'
+Requires-Dist: pytest-cov<8.0.0,>=7.0.0; extra == 'dev'
+Requires-Dist: pytest<10.0.0,>=8.0.0; extra == 'dev'
+Requires-Dist: ruff<15.0.0,>=0.14.0; extra == 'dev'
+Requires-Dist: rust-just<2.0.0,>=1.46.0; extra == 'dev'
+Requires-Dist: ty<0.1.0,>=0.0.10; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# typer-extensions
+
+**Command aliases for Typer CLI applications with grouped help text display**
+
+[![CI](https://github.com/rdawebb/typer-extensions/workflows/test/badge.svg)](https://github.com/rdawebb/typer-extensions/actions)
+[![PyPI](https://img.shields.io/pypi/v/typer-extensions.svg)](https://pypi.org/project/typer-extensions/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/typer-extensions.svg)](https://pypi.org/project/typer-extensions/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Overview
+
+`typer-extensions` extends [Typer](https://typer.tiangolo.com/) to provide simple drop-in support for command aliases. Instead of duplicating commands, hiding commands, or maintaining wrapper functions, define aliases directly and have them displayed cleanly in help text.
+
+100% backwards compatible with Typer & existing Typer apps!
+
+### The Problem
+
+Standard Typer requires duplicating or hiding commands to create aliases:
+
+```python
+from typer import Typer
+
+app = Typer()
+
+@app.command()
+def list_items():
+    """List all items."""
+    print("Listing...")
+
+# Registered as separate command, hidden in help
+@app.command("ls", hidden=True)
+def ls_items():
+    list_items()
+
+@app.command("l")("list")  # Duplicate!
+```
+
+**Help output:**
+```
+Commands:
+  list      List all items.
+  l         List all items.
+```
+
+**Issues:**
+- Code duplication
+- Help text shows commands & aliases separately
+- Hidden 'aliases' not shown in help text
+- Maintenance burden
+
+### The Solution
+
+With `typer-extensions`:
+
+```python
+from typer_extensions import ExtendedTyper
+
+app = ExtendedTyper()
+
+@app.command_with_aliases("list", aliases=["ls", "l"])
+def list_items():
+    """List all items."""
+    print("Listing...")
+```
+
+**Help output:**
+```
+Commands:
+  list (ls, l)  List all items.
+```
+
+**All work identically:**
+- `app list`
+- `app ls`
+- `app l`
+
+---
+
+## Features
+
+✨ **Decorator-based alias registration** - Clean, intuitive syntax
+
+🔧 **Programmatic API** - Dynamic alias management at runtime
+
+📋 **Grouped help display** - Aliases shown with their primary command
+
+⚙️ **Highly configurable** - Customise format, separators, truncation
+
+🎯 **Type-safe** - Full type hints and editor support
+
+🔄 **Fully backwards compatible** - Works with all Typer/Click features and existing Typer apps
+
+✅ **Shell completion ready** - Alias support doesn't interfere with existing shell completion
+
+🧪 **Well-tested** - Tested on Python 3.9-3.14 with 100% test coverage
+
+---
+
+## Installation
+
+```bash
+pip install typer-extensions
+```
+
+**Requirements:**
+- Python 3.9+
+- typer >= 0.9.0 (recommend installing the latest version)
+- click >= 8.0.0
+
+---
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from typer_extensions import ExtendedTyper
+
+app = ExtendedTyper()
+
+@app.command_with_aliases("list", aliases=["ls", "l"])
+def list_items():
+    """List all items."""
+    print("Listing items...")
+
+@app.command_with_aliases("delete", aliases=["rm", "remove"])
+def delete_item(name: str):
+    """Delete an item."""
+    print(f"Deleting {name}")
+
+if __name__ == "__main__":
+    app()
+```
+
+**Run it:**
+```bash
+$ python app.py --help
+Commands:
+  list (ls, l)         List all items.
+  delete (rm, remove)  Delete an item.
+
+$ python app.py ls
+Listing items...
+
+$ python app.py rm test.txt
+Deleting test.txt
+```
+
+> 💡 **Want to learn more?** Check the [API Reference](docs/API_REFERENCE.md) for detailed configuration options, or see the [User Guide](docs/USER_GUIDE.md) for patterns and best practices.
+
+### Drop-in Compatibility
+
+Have an existing Typer project? Add alias support without changing your code:
+
+```python
+# Before (regular Typer)
+from typer import Typer
+app = Typer()
+
+# After (with typer-extensions)
+from typer_extensions import ExtendedTyper
+app = ExtendedTyper()
+
+# That's it! Everything else stays the same.
+# Existing commands, shell completion and help text configuration still work exactly as before.
+```
+
+Once migrated, you can add aliases to new commands using `@app.command_with_aliases()`, or to existing commands using the programmatic API.
+
+See [Migration Guide](docs/MIGRATION.md) for detailed migration strategies and patterns.
+
+### Advanced Features
+
+**Programmatic alias management:**
+```python
+# Add aliases dynamically
+app.add_alias("list", "dir")
+
+# Remove aliases
+app.remove_alias("dir")
+
+# Query aliases
+aliases = app.get_aliases("list")  # ["ls", "l"]
+```
+
+**Custom help formatting:**
+```python
+app = ExtendedTyper(
+    alias_display_format="[{aliases}]",   # Use brackets
+    alias_separator=" | ",                # Pipe separator
+    max_aliases_inline=2,                 # Show max 2, then "+N more"
+)
+```
+
+**Configuration-based aliases:**
+```python
+# Load aliases from config
+config = {"list": ["ls", "l", "dir"]}
+for cmd, aliases in config.items():
+    for alias in aliases:
+        app.add_alias(cmd, alias)
+```
+
+---
+
+## Documentation
+
+📚 **[User Guide](docs/USER_GUIDE.md)** - Tutorials and common patterns
+
+📖 **[API Reference](docs/API_REFERENCE.md)** - Complete API documentation
+
+🔄 **[Migration Guide](docs/MIGRATION.md)** - Migrating from standard Typer
+
+---
+
+## Examples
+
+All examples are in the [`examples/`](examples/) directory:
+
+- **[basic_usage.py](examples/basic_usage.py)** - Simple CLI with aliases
+- **[advanced_usage.py](examples/advanced_usage.py)** - Git-like CLI with options
+- **[programmatic_usage.py](examples/programmatic_usage.py)** - Dynamic alias management
+- **[help_formatting.py](examples/help_formatting.py)** - Customising help display
+- **[argument_option_usage.py](examples/argument_option_usage.py)** - Using Typer's Argument & Option
+
+**Run any example:**
+```bash
+python examples/basic_usage.py --help
+python examples/basic_usage.py ls
+```
+
+---
+
+## Real-World Use Cases
+
+### Git-like CLI
+```python
+@app.command_with_aliases("checkout", aliases=["co"])
+def checkout(branch: str):
+    """Switch branches."""
+    ...
+
+@app.command_with_aliases("status", aliases=["st"])
+def status():
+    """Show status."""
+    ...
+```
+
+### Package Manager
+```python
+@app.command_with_aliases("install", aliases=["i", "add"])
+def install(package: str):
+    """Install a package."""
+    ...
+
+@app.command_with_aliases("remove", aliases=["rm", "uninstall"])
+def remove(package: str):
+    """Remove a package."""
+    ...
+```
+
+### Cross-Platform Commands
+```python
+@app.command("list")
+def list_files():
+    """List files."""
+    ...
+
+# Add platform-specific aliases
+if platform.system() == "Windows":
+    app.add_alias("list", "dir")
+else:
+    app.add_alias("list", "ls")
+```
+
+---
+
+## API Overview
+
+### Decorator Registration
+```python
+@app.command_with_aliases(name, aliases=[...])
+```
+
+### Programmatic Registration
+```python
+app.add_aliased_command(func, name, aliases=[...])
+```
+
+### Alias Management
+```python
+app.add_alias(command, alias)            # Add alias
+app.remove_alias(alias) → bool           # Remove alias
+app.get_aliases(command) → list          # Query aliases
+app.list_commands_with_aliases() → dict  # All mappings
+```
+
+### Configuration
+```python
+ExtendedTyper(
+    alias_case_sensitive=None,           # Case-sensitive matching (default True per Typer)
+    show_aliases_in_help=True,           # Display aliases in help
+    alias_display_format="({aliases})",  # Display format
+    alias_separator=", ",                # Between aliases
+    max_num_aliases=3,                   # Before truncation
+)
+```
+
+---
+
+## Development
+
+### Setup
+
+**Standard setup with pip:**
+
+```bash
+git clone https://github.com/rdawebb/typer-extensions.git
+cd typer-extensions
+python -m venv venv
+source venv/bin/activate  # or venv\Scripts\activate on Windows
+pip install -e ".[dev]"
+```
+
+**Or with uv (recommended):**
+
+```bash
+git clone https://github.com/rdawebb/typer-extensions.git
+cd typer-extensions
+uv sync --all-extras
+source .venv/bin/activate
+```
+
+**Quick commands with justfile:**
+
+If you have [just](https://github.com/casey/just) installed (included in `[dev]`), common tasks are available:
+
+```bash
+just test          # Run tests
+just lint          # Run linter
+just format        # Format code
+just type          # Check type safety
+just test-cov      # Full test suite with coverage
+just help          # List all available commands
+```
+
+If you prefer to use `just` without the dev setup, you can install it globally via `pip install rust-just` or your system package manager.
+
+See `Justfile` for all available commands.
+
+### Testing
+
+**With justfile (recommended):**
+
+```bash
+just check       # Run linting, formatting, and type checks
+just test        # Run tests
+just test-cov    # Run tests with coverage report
+just pre         # Full pre-commit check (all checks + tests)
+```
+
+**Or with direct commands:**
+
+```bash
+pytest                   # Run all tests
+pytest --cov             # With coverage
+pytest -v                # Verbose output
+ruff check .             # Lint
+ruff format .            # Format
+ty check src/            # Type check
+```
+
+### Contributing
+
+Contributions are welcome! Please open an issue, ask a question, or submit a pull request.
+
+---
+
+## Project Status
+
+**Current Version:** 0.2.1 (Beta)
+
+✅ **Core Features Complete:**
+- Alias registration (decorator + programmatic)
+- Help text formatting
+- Dynamic alias management
+- Full test coverage
+
+🚧 **In Development:**
+- Dynamic config file loading with import/export
+- Shell completion enhancement and typo suggestions
+- Documentation site
+- Performance optimisations
+
+📋 **Planned Features:**
+- Shared & chained subcommand aliases
+- Per-alias help text
+- Dataclass, Pydantic & Attrs support
+- Custom themes and help text formatting
+- Argument & Option customisation
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.
+
+---
+
+## Why typer-extensions?
+
+**For Users:**
+- ⚡ Faster workflows with short aliases
+- 🎯 Familiar commands (git-like shortcuts)
+- 📖 Clear help text showing all options
+
+**For Developers:**
+- 🧹 DRY - no code duplication
+- 🔧 Flexible - static or dynamic aliases
+- 🎨 Customisable - match your style
+- ✅ Tested - reliable, stable, and type-safe
+
+**Compared to Alternatives:**
+- **Plain Typer:** Requires command duplication or hiding
+- **click-aliases:** Click-specific, no Typer integration
+- **Custom solutions:** Reinventing the wheel
+
+---
+
+## Related Projects
+
+- **[Typer](https://typer.tiangolo.com/)** - The CLI framework this extends
+- **[Click](https://click.palletsprojects.com/)** - The underlying library
+- **[Rich](https://rich.readthedocs.io/)** - Beautiful terminal formatting (used by Typer)
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+---
+
+## Acknowledgments
+
+Built on the excellent [Typer](https://typer.tiangolo.com/) framework by Sebastián Ramírez.
+
+Inspired by Git's command aliasing and various CLI tools that make shortcuts feel natural.
+
+---
+
+## Support
+
+- 🐛 **Issues:** [GitHub Issues](https://github.com/rdawebb/typer-extensions/issues)
+- 💬 **Discussions:** [GitHub Discussions](https://github.com/rdawebb/typer-extensions/discussions)
+- 📧 **Contact:** Create an issue for questions
+
+---
+
+## Links
+
+- **GitHub:** https://github.com/rdawebb/typer-extensions
+- **PyPI:** https://pypi.org/project/typer-extensions/
+- **Changelog:** [CHANGELOG.md](CHANGELOG.md)
+
+---
+
+<p align="center">
+  <i>Making CLI aliases natural and maintainable</i>
+</p>

typer_extensions-0.2.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+typer_extensions/__init__.py,sha256=kmkNxOvj1__xZMSjRsIzKcy2HXuSnmf0ygK8NRUsMJA,222
+typer_extensions/_version.py,sha256=Q2J7zRwFHCkJjeBWiJBf8XlhWEMS3Yaf38zyC6lSXJY,70
+typer_extensions/core.py,sha256=nQ4bLyDWAg7u1EDq1EWOT1DQZ-5zF0QT96BozXw8q9Y,19188
+typer_extensions/format.py,sha256=TjpwinoCj1rMNuledPvHkSBntupjQQD0mMoJiwYycws,3000
+typer_extensions/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+typer_extensions-0.2.1.dist-info/METADATA,sha256=Dtxw__rUspP50nK_FFcwcKyDuC7boDNY5WvYMlj97bQ,13068
+typer_extensions-0.2.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+typer_extensions-0.2.1.dist-info/licenses/LICENSE,sha256=DLjGYQ3mgvK3gtIfFbGR-kW87JH5uVfYUHS-GecmeJM,1052
+typer_extensions-0.2.1.dist-info/RECORD,,

typer_extensions-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

typer_extensions-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Rob Webb
+
+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.