ultraclick 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- ultraclick-0.1.0/PKG-INFO +314 -0
- ultraclick-0.1.0/license.txt +674 -0
- ultraclick-0.1.0/pyproject.toml +164 -0
- ultraclick-0.1.0/readme.md +280 -0
- ultraclick-0.1.0/setup.cfg +4 -0
- ultraclick-0.1.0/src/ultraclick/__init__.py +500 -0
- ultraclick-0.1.0/src/ultraclick.egg-info/PKG-INFO +314 -0
- ultraclick-0.1.0/src/ultraclick.egg-info/SOURCES.txt +10 -0
- ultraclick-0.1.0/src/ultraclick.egg-info/dependency_links.txt +1 -0
- ultraclick-0.1.0/src/ultraclick.egg-info/requires.txt +9 -0
- ultraclick-0.1.0/src/ultraclick.egg-info/top_level.txt +1 -0
- ultraclick-0.1.0/tests/test_demo.py +106 -0
|
@@ -0,0 +1,314 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: ultraclick
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Thin wrapper around the Python 'click' library to allow building class based CLIs
|
|
5
|
+
Author-email: Ronny Rentner <ultraclick.code@ronny-rentner.de>
|
|
6
|
+
Maintainer-email: Ronny Rentner <ultraclick.code@ronny-rentner.de>
|
|
7
|
+
License-Expression: GPL-3.0-or-later
|
|
8
|
+
Project-URL: Homepage, https://github.com/ronny-rentner/ultraclick
|
|
9
|
+
Project-URL: Bug Reports, https://github.com/ronny-rentner/ultraclick/issues
|
|
10
|
+
Project-URL: Source, https://github.com/ronny-rentner/ultraclick
|
|
11
|
+
Keywords: ultraclick,cli,click,setuptools,development
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
|
|
15
|
+
Classifier: Topic :: Software Development :: User Interfaces
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
23
|
+
Requires-Python: >=3.9
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
License-File: license.txt
|
|
26
|
+
Requires-Dist: click
|
|
27
|
+
Requires-Dist: rich
|
|
28
|
+
Requires-Dist: rich_click
|
|
29
|
+
Provides-Extra: dev
|
|
30
|
+
Requires-Dist: check-manifest; extra == "dev"
|
|
31
|
+
Provides-Extra: test
|
|
32
|
+
Requires-Dist: coverage; extra == "test"
|
|
33
|
+
Dynamic: license-file
|
|
34
|
+
|
|
35
|
+
# ultraclick
|
|
36
|
+
|
|
37
|
+
In contrast to plain version of [click](https://github.com/pallets/click), ultraclick allows you to define your CLI using Python classes. ultraclick is based on rich-click which is adding colors to click.
|
|
38
|
+
|
|
39
|
+
## Table of Contents
|
|
40
|
+
|
|
41
|
+
- [Features](#features)
|
|
42
|
+
- [Installation](#installation)
|
|
43
|
+
- [Help Output](#help-output)
|
|
44
|
+
- [Demo Code](#demo-code)
|
|
45
|
+
|
|
46
|
+
## Features
|
|
47
|
+
|
|
48
|
+
- **Class-based CLI structure**: Define your command-line interface using Python classes
|
|
49
|
+
- **Nested command groups**: Organize commands in a hierarchical structure
|
|
50
|
+
- **Automatic context sharing**: Share context between commands in the same class instance
|
|
51
|
+
- **Context Proxy**: Access the Click context directly with `click.ctx` without passing it as a parameter
|
|
52
|
+
- **Rich output formatting**: Colored output and better help text formatting via rich-click
|
|
53
|
+
- **Interactive command execution**: Preserves colors, progress bars, and interactive output from subprocesses
|
|
54
|
+
- **Cross-platform compatibility**: Works on Unix, macOS, and Windows
|
|
55
|
+
- **Command aliases**: Create alternative names for commands (e.g., `greet` and `hello`)
|
|
56
|
+
- **Command abbreviations**: Type partial commands like `demo u` instead of `demo update` when unambiguous
|
|
57
|
+
- **Automatic return value handling**: Command return values are automatically displayed
|
|
58
|
+
- **Full compatibility**: Supports all features of Click and RichClick
|
|
59
|
+
|
|
60
|
+
## Installation
|
|
61
|
+
|
|
62
|
+
To install and run the demo after cloning the repository:
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
# Clone the repository
|
|
66
|
+
git clone https://github.com/ronny-rentner/ultraclick.git
|
|
67
|
+
cd ultraclick
|
|
68
|
+
|
|
69
|
+
# Create and activate a virtual environment (recommended)
|
|
70
|
+
python -m venv venv
|
|
71
|
+
source venv/bin/activate # On Windows: venv\Scripts\activate
|
|
72
|
+
|
|
73
|
+
# Install the package in development mode (will install dependencies automatically)
|
|
74
|
+
pip install -e .
|
|
75
|
+
|
|
76
|
+
# Run the demo
|
|
77
|
+
python demo.py --help
|
|
78
|
+
# Using global options
|
|
79
|
+
python demo.py --profile production --verbose status # top-level options affect all commands
|
|
80
|
+
# Try different behaviors with command groups
|
|
81
|
+
python demo.py config # shows help by default
|
|
82
|
+
python demo.py resource # executes custom behavior without showing help
|
|
83
|
+
# Command-specific options
|
|
84
|
+
python demo.py resource --resource-type database create mydb --size large --region eu-west
|
|
85
|
+
# Try command aliases
|
|
86
|
+
python demo.py config set debug true
|
|
87
|
+
python demo.py config update debug false # alias for 'set'
|
|
88
|
+
# Try command abbreviations
|
|
89
|
+
python demo.py r l # shorthand for 'resource list'
|
|
90
|
+
# Combine options, aliases, and abbreviations
|
|
91
|
+
python demo.py --profile staging r --resource-type storage l
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
## Help Output
|
|
95
|
+
|
|
96
|
+
Sample help outputs from the demo application:
|
|
97
|
+
|
|
98
|
+
### Main Help
|
|
99
|
+
```
|
|
100
|
+
Usage: demo [OPTIONS] COMMAND [ARGS]...
|
|
101
|
+
|
|
102
|
+
Main demo application showcasing ultraclick's features.
|
|
103
|
+
|
|
104
|
+
╭─ Options ────────────────────────────────────────────────────────────────────╮
|
|
105
|
+
│ --verbose Enable verbose output │
|
|
106
|
+
│ --profile TEXT Configuration profile to use │
|
|
107
|
+
│ --env [development|staging|productio Environment to run in │
|
|
108
|
+
│ n] │
|
|
109
|
+
│ --help Show this message and exit. │
|
|
110
|
+
╰──────────────────────────────────────────────────────────────────────────────╯
|
|
111
|
+
╭─ Commands ───────────────────────────────────────────────────────────────────╮
|
|
112
|
+
│ config Configuration commands for the application. Demonstrates context │
|
|
113
|
+
│ sharing between subcommands. │
|
|
114
|
+
│ resource Resource management commands. Demonstrates parameter handling and │
|
|
115
|
+
│ nested command structure. │
|
|
116
|
+
│ status Show application status. │
|
|
117
|
+
│ version Show application version. │
|
|
118
|
+
╰──────────────────────────────────────────────────────────────────────────────╯
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### Config Command Help
|
|
122
|
+
```
|
|
123
|
+
Usage: demo config [OPTIONS] COMMAND [ARGS]...
|
|
124
|
+
|
|
125
|
+
Configuration commands for the application. Demonstrates context sharing
|
|
126
|
+
between subcommands.
|
|
127
|
+
This command group shows help when called directly (default behavior).
|
|
128
|
+
|
|
129
|
+
╭─ Options ────────────────────────────────────────────────────────────────────╮
|
|
130
|
+
│ --config-dir PATH Configuration directory │
|
|
131
|
+
│ --help Show this message and exit. │
|
|
132
|
+
╰──────────────────────────────────────────────────────────────────────────────╯
|
|
133
|
+
╭─ Commands ───────────────────────────────────────────────────────────────────╮
|
|
134
|
+
│ get Get a configuration value. │
|
|
135
|
+
│ set Set a configuration value. │
|
|
136
|
+
│ show Display current configuration settings. │
|
|
137
|
+
╰──────────────────────────────────────────────────────────────────────────────╯
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
## Demo Code
|
|
141
|
+
|
|
142
|
+
Check out [gwctl](https://github.com/ronny-rentner/gwctl) for a real-world application built with ultraclick.
|
|
143
|
+
|
|
144
|
+
```python
|
|
145
|
+
#!/usr/bin/env python
|
|
146
|
+
"""
|
|
147
|
+
ultraclick Demo Application
|
|
148
|
+
|
|
149
|
+
This demo systematically showcases ultraclick's main features:
|
|
150
|
+
1. Class-based CLI structure
|
|
151
|
+
2. Nested command groups
|
|
152
|
+
3. Automatic context sharing
|
|
153
|
+
4. Command aliases
|
|
154
|
+
5. Command abbreviations
|
|
155
|
+
6. Automatic return value handling
|
|
156
|
+
"""
|
|
157
|
+
|
|
158
|
+
import pathlib
|
|
159
|
+
|
|
160
|
+
import ultraclick as click
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
class ConfigCommand:
|
|
164
|
+
"""
|
|
165
|
+
Configuration commands for the application.
|
|
166
|
+
Demonstrates context sharing between subcommands.
|
|
167
|
+
|
|
168
|
+
This command group shows help when called directly (default behavior).
|
|
169
|
+
"""
|
|
170
|
+
@click.option("--config-dir", type=pathlib.Path, default="./config", help="Configuration directory")
|
|
171
|
+
def __init__(self, config_dir):
|
|
172
|
+
# Store parameters as instance variables
|
|
173
|
+
self.config_dir = config_dir
|
|
174
|
+
|
|
175
|
+
# Access shared data from parent command
|
|
176
|
+
self.profile = click.ctx.meta["profile"]
|
|
177
|
+
|
|
178
|
+
# Share this command's data with child commands
|
|
179
|
+
click.ctx.meta["config_dir"] = config_dir
|
|
180
|
+
|
|
181
|
+
@click.command()
|
|
182
|
+
def show(self):
|
|
183
|
+
"""Display current configuration settings."""
|
|
184
|
+
path_prefix = './' if not self.config_dir.is_absolute() else ''
|
|
185
|
+
return (
|
|
186
|
+
f"Active Profile: {self.profile}\n"
|
|
187
|
+
f"Config Directory: {path_prefix}{self.config_dir}"
|
|
188
|
+
)
|
|
189
|
+
|
|
190
|
+
@click.command()
|
|
191
|
+
@click.argument("name")
|
|
192
|
+
@click.argument("value")
|
|
193
|
+
def set(self, name, value):
|
|
194
|
+
"""Set a configuration value."""
|
|
195
|
+
return f"Setting {name}={value} in profile '{self.profile}'"
|
|
196
|
+
|
|
197
|
+
# Command alias demonstration - simple approach
|
|
198
|
+
update = set
|
|
199
|
+
|
|
200
|
+
@click.command()
|
|
201
|
+
@click.argument("name")
|
|
202
|
+
def get(self, name):
|
|
203
|
+
"""Get a configuration value."""
|
|
204
|
+
return f"Getting '{name}' from profile '{self.profile}'"
|
|
205
|
+
|
|
206
|
+
# Another command alias - simple approach
|
|
207
|
+
fetch = get
|
|
208
|
+
|
|
209
|
+
|
|
210
|
+
class ResourceCommand:
|
|
211
|
+
"""
|
|
212
|
+
Resource management commands.
|
|
213
|
+
Demonstrates parameter handling and nested command structure.
|
|
214
|
+
|
|
215
|
+
This command group performs an action when called directly (no help shown).
|
|
216
|
+
"""
|
|
217
|
+
@click.option("--resource-type", type=click.Choice(['server', 'database', 'storage']),
|
|
218
|
+
default="server", help="Type of resource to manage")
|
|
219
|
+
def __init__(self, resource_type):
|
|
220
|
+
self.resource_type = resource_type
|
|
221
|
+
|
|
222
|
+
# Access shared data from parent command
|
|
223
|
+
self.profile = click.ctx.meta["profile"]
|
|
224
|
+
|
|
225
|
+
# Custom behavior when no subcommand is provided
|
|
226
|
+
if click.ctx.invoked_subcommand is None:
|
|
227
|
+
# Prevent automatic help display
|
|
228
|
+
click.ctx.meta['show_help_on_no_command'] = False
|
|
229
|
+
|
|
230
|
+
# Show custom summary instead
|
|
231
|
+
click.echo(
|
|
232
|
+
f"Resource Management Summary:\n"
|
|
233
|
+
f"• Current Resource Type: {self.resource_type}\n"
|
|
234
|
+
f"• Available Types: server, database, storage\n"
|
|
235
|
+
f"• Active Profile: {self.profile}"
|
|
236
|
+
)
|
|
237
|
+
|
|
238
|
+
@click.command()
|
|
239
|
+
@click.argument("name")
|
|
240
|
+
@click.option("--size", default="medium", help="Resource size (small, medium, large)")
|
|
241
|
+
@click.option("--region", default="us-east", help="Deployment region")
|
|
242
|
+
def create(self, name, size, region):
|
|
243
|
+
"""Create a new resource."""
|
|
244
|
+
return (
|
|
245
|
+
f"Creating {self.resource_type} '{name}'\n"
|
|
246
|
+
f"Size: {size}\n"
|
|
247
|
+
f"Region: {region}\n"
|
|
248
|
+
f"Using profile: {self.profile}"
|
|
249
|
+
)
|
|
250
|
+
|
|
251
|
+
@click.command()
|
|
252
|
+
@click.argument("name")
|
|
253
|
+
def delete(self, name):
|
|
254
|
+
"""Delete a resource."""
|
|
255
|
+
return f"Deleting {self.resource_type} '{name}'"
|
|
256
|
+
|
|
257
|
+
@click.command()
|
|
258
|
+
@click.argument("names", nargs=-1)
|
|
259
|
+
def list(self, names):
|
|
260
|
+
"""List resources, optionally filtered by name."""
|
|
261
|
+
if not names:
|
|
262
|
+
return f"Listing all {self.resource_type}s (Profile: {self.profile})"
|
|
263
|
+
else:
|
|
264
|
+
return f"Filtered {self.resource_type} list: {', '.join(names)} (Profile: {self.profile})"
|
|
265
|
+
|
|
266
|
+
|
|
267
|
+
class MainApp:
|
|
268
|
+
"""
|
|
269
|
+
Main demo application showcasing ultraclick's features.
|
|
270
|
+
"""
|
|
271
|
+
# Define nested command groups
|
|
272
|
+
config = ConfigCommand
|
|
273
|
+
resource = ResourceCommand
|
|
274
|
+
|
|
275
|
+
@click.option("--verbose", is_flag=True, help="Enable verbose output")
|
|
276
|
+
@click.option("--profile", default="default", help="Configuration profile to use")
|
|
277
|
+
@click.option("--env", default="development",
|
|
278
|
+
type=click.Choice(['development', 'staging', 'production']),
|
|
279
|
+
help="Environment to run in")
|
|
280
|
+
def __init__(self, verbose, profile, env):
|
|
281
|
+
# Store options as instance variables
|
|
282
|
+
self.verbose = verbose
|
|
283
|
+
self.profile = profile
|
|
284
|
+
self.env = env
|
|
285
|
+
|
|
286
|
+
# Share data with child commands
|
|
287
|
+
click.ctx.meta["verbose"] = verbose
|
|
288
|
+
click.ctx.meta["profile"] = profile
|
|
289
|
+
click.ctx.meta["env"] = env
|
|
290
|
+
|
|
291
|
+
if verbose:
|
|
292
|
+
click.echo(f"Verbose mode enabled in {env} environment")
|
|
293
|
+
|
|
294
|
+
@click.command()
|
|
295
|
+
def status(self):
|
|
296
|
+
"""Show application status."""
|
|
297
|
+
return (
|
|
298
|
+
f"Status: Running\n"
|
|
299
|
+
f"Environment: {self.env}\n"
|
|
300
|
+
f"Verbose: {self.verbose}\n"
|
|
301
|
+
f"Profile: {self.profile}"
|
|
302
|
+
)
|
|
303
|
+
|
|
304
|
+
# Command alias using the decorator approach
|
|
305
|
+
info=click.alias(status)
|
|
306
|
+
|
|
307
|
+
@click.command()
|
|
308
|
+
def version(self):
|
|
309
|
+
"""Show application version."""
|
|
310
|
+
return "ultraclick demo v0.1.0"
|
|
311
|
+
|
|
312
|
+
if __name__ == "__main__":
|
|
313
|
+
click.group_from_class(MainApp, name="demo")(prog_name="demo")
|
|
314
|
+
```
|