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.
@@ -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
+ ```