deepctl-plugin-example 0.1.0__py3-none-any.whl

deepctl_plugin_example/__init__.py

@@ -0,0 +1,6 @@
+"""Example plugin package for deepctl."""
+
+from .command import ExampleCommand
+from .models import ExampleResult
+
+__all__ = ["ExampleCommand", "ExampleResult"]

deepctl_plugin_example/command.py

@@ -0,0 +1,161 @@
+"""Example plugin command for deepctl."""
+
+from typing import Any
+
+from deepctl_core import AuthManager, BaseCommand, Config, DeepgramClient
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+console = Console()
+
+
+class ExampleCommand(BaseCommand):
+    """Example plugin command demonstrating the plugin system."""
+
+    name = "example"
+    help = "Example plugin command demonstrating the plugin system"
+    short_help = "Example plugin command"
+
+    # This example command doesn't require authentication
+    requires_auth = False
+    requires_project = False
+    ci_friendly = True
+
+    def get_arguments(self) -> list[dict[str, Any]]:
+        """Get command arguments and options."""
+        return [
+            {
+                "names": ["--greeting", "-g"],
+                "help": "Custom greeting message",
+                "type": str,
+                "default": "Hello",
+                "required": False,
+                "is_option": True,
+            },
+            {
+                "names": ["--name", "-n"],
+                "help": "Name to greet",
+                "type": str,
+                "default": "World",
+                "required": False,
+                "is_option": True,
+            },
+            {
+                "names": ["--show-info"],
+                "help": "Show plugin system information",
+                "is_flag": True,
+                "is_option": True,
+            },
+        ]
+
+    def handle(
+        self,
+        config: Config,
+        auth_manager: AuthManager,
+        client: DeepgramClient,
+        **kwargs: Any,
+    ) -> Any:
+        """Handle the example command."""
+        greeting = kwargs.get("greeting", "Hello")
+        name = kwargs.get("name", "World")
+        show_info = kwargs.get("show_info", False)
+
+        # Show plugin information if requested
+        if show_info:
+            # Display greeting
+            console.print(f"\n[bold blue]{greeting}, {name}![/bold blue]\n")
+            self._show_plugin_info()
+            # Return None to avoid additional output
+            return None
+
+        # For normal operation, return structured data for output formatting
+        # Don't print directly unless in help mode
+        if kwargs.get("help_mode", False):
+            self._show_help()
+            return None
+
+        # Return result for output formatting
+        from .models import ExampleResult
+
+        return ExampleResult(
+            message=f"{greeting}, {name}!",
+            plugin="deepctl-plugin-example",
+            version="0.1.0",
+            greeting=greeting,
+            name=name,
+        )
+
+    def _show_help(self) -> None:
+        """Show help information about the plugin."""
+        # Create help panel
+        help_content = """
+This is an example plugin for deepctl demonstrating how to create
+custom commands that integrate seamlessly with the CLI.
+
+[bold]Usage:[/bold]
+  deepctl example [OPTIONS]
+
+[bold]Options:[/bold]
+  -g, --greeting TEXT    Custom greeting message [default: Hello]
+  -n, --name TEXT        Name to greet [default: World]
+  --show-info            Show plugin system information
+
+[bold]Examples:[/bold]
+  # Basic usage
+  deepctl example
+
+  # Custom greeting
+  deepctl example --greeting "Howdy" --name "Partner"
+
+  # Show plugin info
+  deepctl example --show-info
+"""
+
+        panel = Panel(
+            help_content.strip(),
+            title="[bold]Example Plugin Help[/bold]",
+            border_style="blue",
+            padding=(1, 2),
+        )
+        console.print(panel)
+
+    def _show_plugin_info(self) -> None:
+        """Show information about the plugin system."""
+        console.print("[bold]Plugin System Information[/bold]\n")
+
+        # Create info table
+        table = Table(show_header=True, header_style="bold blue")
+        table.add_column("Property", style="cyan")
+        table.add_column("Value")
+
+        table.add_row("Plugin Name", "deepctl-plugin-example")
+        table.add_row("Version", "0.1.0")
+        table.add_row("Command Name", self.name)
+        table.add_row("Entry Point", "deepctl.commands")
+        table.add_row("Base Class", "deepctl_core.BaseCommand")
+        table.add_row("Requires Auth", str(self.requires_auth))
+        table.add_row("Requires Project", str(self.requires_project))
+
+        console.print(table)
+        console.print()
+
+        # Show how plugin loading works
+        info_panel = Panel(
+            """[bold]How Plugin Loading Works:[/bold]
+
+1. Plugins register via entry points in pyproject.toml
+2. The CLI's PluginManager discovers them at runtime
+3. Plugins must inherit from BaseCommand
+4. When installed alongside the CLI, they become available
+
+To create your own plugin:
+- Copy this example package
+- Modify the command class
+- Update pyproject.toml metadata
+- Install with: pip install -e ./your-plugin/""",
+            title="[bold]Plugin Development Guide[/bold]",
+            border_style="green",
+            padding=(1, 2),
+        )
+        console.print(info_panel)

deepctl_plugin_example/models.py

@@ -0,0 +1,13 @@
+"""Data models for the example plugin."""
+
+from pydantic import BaseModel
+
+
+class ExampleResult(BaseModel):
+    """Result model for the example command."""
+
+    message: str
+    plugin: str
+    version: str
+    greeting: str | None = None
+    name: str | None = None

deepctl_plugin_example-0.1.0.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: deepctl-plugin-example
+Version: 0.1.0
+Summary: Example plugin for deepctl
+Author-email: Deepgram <devrel@deepgram.com>
+Maintainer-email: Deepgram <devrel@deepgram.com>
+License-Expression: MIT
+Keywords: deepgram,cli,plugin,example
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: deepctl-core
+Requires-Dist: click>=8.0.0
+Requires-Dist: rich>=13.0.0
+
+# deepctl Plugin Example
+
+An example plugin for deepctl demonstrating how to create and distribute custom commands as separate packages.
+
+## Overview
+
+This plugin shows how to extend deepctl with custom commands that can be:
+
+- Developed independently
+- Distributed via PyPI
+- Installed alongside the CLI
+- Discovered automatically at runtime
+
+**Note:** This plugin is NOT a dependency of deepctl. It must be installed separately to demonstrate how the plugin system works for third-party developers. This example plugin is published to PyPI with each deepctl release to ensure the documentation is always testable.
+
+## Installation
+
+### Development Installation
+
+To install the plugin in development mode:
+
+```bash
+# From the plugin directory
+pip install -e .
+
+# Or using uv
+uv pip install -e .
+```
+
+### Production Installation
+
+For users who have deepctl installed globally:
+
+```bash
+# Recommended: Using pipx (if deepctl was installed with pipx)
+pipx install deepctl  # If not already installed
+pipx inject deepctl deepctl-plugin-example
+
+# Alternative: Using pip (only works in development environments)
+pip install deepctl deepctl-plugin-example
+```
+
+**Note:** If you installed deepctl with `uv tool install`, plugin installation requires manual workarounds. We recommend using pipx for the best plugin experience.
+
+## Usage
+
+Once installed, the plugin command becomes available in the CLI:
+
+```bash
+# Basic usage
+deepctl example
+
+# Custom greeting
+deepctl example --greeting "Howdy" --name "Partner"
+
+# Show plugin system information
+deepctl example --show-info
+```
+
+## How It Works
+
+1. **Entry Point Registration**: The plugin registers itself via the `deepctl.plugins` entry point in `pyproject.toml`
+2. **Command Discovery**: The CLI's PluginManager discovers the plugin at runtime using `importlib.metadata`
+3. **Command Loading**: The plugin's command class is instantiated and added to the CLI
+4. **Execution**: When the user runs the command, the plugin's `handle()` method is called
+
+## Creating Your Own Plugin
+
+To create your own deepctl plugin:
+
+1. **Copy this example package** as a starting point
+2. **Rename the package** and update metadata in `pyproject.toml`
+3. **Implement your command** by modifying the `command.py` file
+4. **Define arguments** in the `get_arguments()` method
+5. **Implement logic** in the `handle()` method
+6. **Test locally** with `pip install -e .`
+7. **Publish to PyPI** when ready
+8. **Users install it** with `pipx inject deepctl your-plugin-name`
+
+### Key Requirements
+
+- Must inherit from `deepctl_core.BaseCommand`
+- Must implement required properties: `name`, `help`
+- Must implement `handle()` method
+- Must be registered via entry point
+
+### Example Command Structure
+
+```python
+from deepctl_core import BaseCommand
+
+class MyCommand(BaseCommand):
+    name = "mycommand"
+    help = "Description of my command"
+
+    def handle(self, config, auth_manager, client, **kwargs):
+        # Your command logic here
+        pass
+```
+
+## Development
+
+### Running Tests
+
+```bash
+uv run pytest
+```
+
+### Building the Package
+
+```bash
+python -m build
+```
+
+## Plugin Capabilities
+
+Plugins have access to:
+
+- Configuration management via `Config`
+- Authentication via `AuthManager`
+- Deepgram API client via `DeepgramClient`
+- Rich terminal output via `rich`
+- Command-line argument parsing via `click`
+
+## License
+
+MIT

deepctl_plugin_example-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+deepctl_plugin_example/__init__.py,sha256=AnwY75aFeXi-NiIw37WN4eQdTQ9r4U-Y_OITWEMEBsA,160
+deepctl_plugin_example/command.py,sha256=X3CMw_5IYWoDb3LP3JEYoGUY3WWn5CjG7f2OjFljkdk,5016
+deepctl_plugin_example/models.py,sha256=C7a-bfBNPuzYuTQJ6or51ViqgWjD73xzCbWZn8px4gU,267
+deepctl_plugin_example-0.1.0.dist-info/METADATA,sha256=mcQ2-73xMpVDtwJKIoJeXojhexP7p_UA0BzPGflReUc,4054
+deepctl_plugin_example-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+deepctl_plugin_example-0.1.0.dist-info/entry_points.txt,sha256=t14ZnFsfjxlXf_f32q-vx9ZSqNNDwi1MxTtkBMVJJAk,74
+deepctl_plugin_example-0.1.0.dist-info/top_level.txt,sha256=HFzBg8VDfBdYp4pBirFQzVG12LOxaOIFWd28A9UeIK4,23
+deepctl_plugin_example-0.1.0.dist-info/RECORD,,

deepctl_plugin_example-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

deepctl_plugin_example-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[deepctl.plugins]
+example = deepctl_plugin_example.command:ExampleCommand

deepctl_plugin_example-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+deepctl_plugin_example