slashed 1.2.0__tar.gz → 1.3.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.
Files changed (36) hide show
  1. {slashed-1.2.0 → slashed-1.3.0}/PKG-INFO +111 -56
  2. {slashed-1.2.0 → slashed-1.3.0}/README.md +96 -51
  3. slashed-1.3.0/pyproject.toml +304 -0
  4. slashed-1.2.0/pyproject.toml → slashed-1.3.0/pyproject.toml.orig +41 -15
  5. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/__init__.py +10 -1
  6. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/base.py +2 -2
  7. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/builtin/help_cmd.py +1 -1
  8. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/builtin/system.py +10 -6
  9. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/completers.py +2 -2
  10. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/context.py +16 -5
  11. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/prompt_toolkit_completer.py +2 -2
  12. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/registry.py +1 -1
  13. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/router.py +5 -5
  14. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/shell_executor.py +33 -39
  15. slashed-1.3.0/src/slashed/slashed_types.py +24 -0
  16. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/store.py +4 -8
  17. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/textual_adapter/app.py +4 -2
  18. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/textual_adapter/command_input.py +1 -1
  19. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/textual_adapter/command_textarea.py +1 -1
  20. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/textual_adapter/suggester.py +1 -1
  21. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/utils.py +6 -3
  22. slashed-1.2.0/src/slashed/slashed_types.py +0 -8
  23. {slashed-1.2.0 → slashed-1.3.0}/LICENSE +0 -0
  24. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/annotations.py +0 -0
  25. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/builtin/__init__.py +0 -0
  26. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/commands.py +0 -0
  27. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/completion.py +0 -0
  28. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/events.py +0 -0
  29. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/exceptions.py +0 -0
  30. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/log.py +0 -0
  31. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/output.py +0 -0
  32. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/py.typed +0 -0
  33. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/textual_adapter/__init__.py +0 -0
  34. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/textual_adapter/command_base.py +0 -0
  35. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/textual_adapter/dropdown.py +0 -0
  36. {slashed-1.2.0 → slashed-1.3.0}/src/slashed/textual_adapter/log.py +0 -0
@@ -1,35 +1,45 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: slashed
3
- Version: 1.2.0
4
- Summary: Slash commands and autocompletions
5
- Keywords:
3
+ Version: 1.3.0
4
+ Summary: Async slash commands with typed arguments and autocompletion for Textual and prompt_toolkit
5
+ Keywords: async,autocompletion,cli,command-parser,commands,prompt-toolkit,repl,slash-commands,textual,tui
6
6
  Author: Philipp Temminghoff
7
7
  Author-email: Philipp Temminghoff <philipptemminghoff@googlemail.com>
8
8
  License-Expression: MIT
9
9
  License-File: LICENSE
10
10
  Classifier: Development Status :: 4 - Beta
11
+ Classifier: Environment :: Console
12
+ Classifier: Framework :: AsyncIO
11
13
  Classifier: Intended Audience :: Developers
12
14
  Classifier: Operating System :: OS Independent
13
15
  Classifier: Programming Language :: Python :: 3
14
16
  Classifier: Programming Language :: Python :: 3 :: Only
15
- Classifier: Programming Language :: Python :: 3.12
16
17
  Classifier: Programming Language :: Python :: 3.13
17
18
  Classifier: Programming Language :: Python :: 3.14
18
- Classifier: Topic :: Documentation
19
19
  Classifier: Topic :: Software Development
20
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
21
+ Classifier: Topic :: Software Development :: User Interfaces
22
+ Classifier: Topic :: Terminals
20
23
  Classifier: Topic :: Utilities
21
24
  Classifier: Typing :: Typed
22
25
  Requires-Dist: bashlex>=0.18
23
26
  Requires-Dist: psygnal>=0.11.1
24
27
  Requires-Dist: universal-pathlib>=0.3.4
28
+ Requires-Dist: prompt-toolkit>=3.0.48 ; extra == 'prompt-toolkit'
25
29
  Requires-Dist: psutil>=6.1.1 ; extra == 'system-commands'
30
+ Requires-Dist: prompt-toolkit>=3.0.48 ; extra == 'textual'
31
+ Requires-Dist: rich>=13.9.4 ; extra == 'textual'
32
+ Requires-Dist: textual>=1.0.0 ; extra == 'textual'
26
33
  Requires-Python: >=3.13
27
34
  Project-URL: Code coverage, https://app.codecov.io/gh/phil65/slashed
28
35
  Project-URL: Discussions, https://github.com/phil65/slashed/discussions
29
36
  Project-URL: Documentation, https://phil65.github.io/slashed/
37
+ Project-URL: Homepage, https://github.com/phil65/slashed
30
38
  Project-URL: Issues, https://github.com/phil65/slashed/issues
31
39
  Project-URL: Source, https://github.com/phil65/slashed
40
+ Provides-Extra: prompt-toolkit
32
41
  Provides-Extra: system-commands
42
+ Provides-Extra: textual
33
43
  Description-Content-Type: text/markdown
34
44
 
35
45
  # Slashed
@@ -77,7 +87,8 @@ A Python library for implementing slash commands with rich autocompletion suppor
77
87
  - Callback based lists
78
88
  - Environment variables
79
89
  - Extensible completion provider system
80
- - Modern Python features (requires Python 3.12+)
90
+ - Shell-style chaining of commands (`&&`, `||`, `;`, pipes)
91
+ - Modern Python features (requires Python 3.13+)
81
92
  - UI framework integration:
82
93
  - Textual support
83
94
  - prompt_toolkit support
@@ -94,12 +105,18 @@ making it more adaptable to different application needs while maintaining a clea
94
105
 
95
106
  ```bash
96
107
  pip install slashed
108
+ # optional integrations
109
+ pip install "slashed[textual]" # Textual widgets and SlashedApp
110
+ pip install "slashed[prompt-toolkit]" # prompt_toolkit completer
111
+ pip install "slashed[system_commands]" # /exec, /run, /processes, ... (psutil)
97
112
  ```
98
113
 
99
114
  ## Quick Example
100
115
 
101
116
  ```python
117
+ import asyncio
102
118
  from dataclasses import dataclass
119
+
103
120
  from slashed import SlashedCommand, CommandStore, CommandContext
104
121
  from slashed.completers import ChoiceCompleter
105
122
 
@@ -132,28 +149,30 @@ class GreetCommand(SlashedCommand):
132
149
  """
133
150
  state = ctx.get_data() # Type-safe access to app state
134
151
  state.greeting_count += 1
135
- await ctx.print(
136
- f"{greeting}, {name}! "
137
- f"(Greeted {state.greeting_count} times)"
138
- )
152
+ await ctx.print(f"{greeting}, {name}! (Greeted {state.greeting_count} times)")
139
153
 
140
154
  def get_completer(self) -> ChoiceCompleter:
141
155
  """Provide name suggestions."""
142
156
  return ChoiceCompleter({
143
157
  "World": "Default greeting target",
144
158
  "Everyone": "Greet all users",
145
- "Team": "Greet the team"
159
+ "Team": "Greet the team",
146
160
  })
147
161
 
148
- # Create store and register the command
149
- store = CommandStore()
150
- store.register_command(GreetCommand)
151
162
 
152
- # Create context with app state
153
- ctx = store.create_context(data=AppState())
163
+ async def main():
164
+ # Create store and register the command
165
+ store = CommandStore()
166
+ store.register_command(GreetCommand)
167
+
168
+ # Create context with app state
169
+ ctx = store.create_context(data=AppState())
170
+
171
+ # Execute a command (no leading slash)
172
+ await store.execute_command("greet Phil --greeting Hi", ctx) # Hi, Phil! (Greeted 1 times)
154
173
 
155
- # Execute a command
156
- await store.execute_command("greet Phil --greeting Hi", ctx)
174
+
175
+ asyncio.run(main())
157
176
  ```
158
177
 
159
178
  ## Command Definition Styles
@@ -165,10 +184,12 @@ Slashed offers two different styles for defining commands, each with its own adv
165
184
  ```python
166
185
  from slashed import Command, CommandContext
167
186
 
187
+
168
188
  def add_worker(ctx: CommandContext, worker_id: str, host: str = "localhost", port: int = 8080):
169
189
  """Add a worker to the pool."""
170
190
  print(f"Adding worker {worker_id} at {host}:{port}")
171
191
 
192
+
172
193
  # Usage string is auto-generated from function signature
173
194
  cmd = Command(
174
195
  add_worker,
@@ -194,6 +215,7 @@ cmd = Command(
194
215
  ```python
195
216
  from slashed import SlashedCommand, CommandContext
196
217
 
218
+
197
219
  class AddWorkerCommand(SlashedCommand):
198
220
  """Add a worker to the pool."""
199
221
 
@@ -203,9 +225,9 @@ class AddWorkerCommand(SlashedCommand):
203
225
  async def execute_command(
204
226
  self,
205
227
  ctx: CommandContext,
206
- worker_id: str, # required parameter
207
- host: str = "localhost", # optional with default
208
- port: int = 8080, # optional with default
228
+ worker_id: str, # required parameter
229
+ host: str = "localhost", # optional with default
230
+ port: int = 8080, # optional with default
209
231
  ):
210
232
  """Add a new worker to the pool.
211
233
 
@@ -251,6 +273,14 @@ Use the **SlashedCommand style** when:
251
273
  #### Using the Command Decorator
252
274
 
253
275
  ```python
276
+ from importlib.util import find_spec
277
+
278
+ from slashed import CommandContext, CommandStore
279
+ from slashed.completers import PathCompleter
280
+
281
+ store = CommandStore()
282
+
283
+
254
284
  @store.command(
255
285
  category="tools",
256
286
  usage="<pattern> [--type type]",
@@ -289,27 +319,26 @@ you can use `CommandRegistry` to collect commands and register them later:
289
319
 
290
320
  ```python
291
321
  # commands.py
292
- from slashed import CommandRegistry
322
+ from importlib.util import find_spec
323
+
324
+ from slashed import CommandContext, CommandRegistry
293
325
  from slashed.completers import PathCompleter
294
326
 
295
327
  registry = CommandRegistry()
296
328
 
297
- @registry.command(
298
- category="tools",
299
- completer=PathCompleter(files=True)
300
- )
329
+
330
+ @registry.command(category="tools", completer=PathCompleter(files=True))
301
331
  async def search(ctx: CommandContext, pattern: str):
302
332
  """Search for files in current directory."""
303
333
  await ctx.print(f"Searching for {pattern}")
304
334
 
305
- @registry.command(
306
- category="tools",
307
- condition=lambda: find_spec("sqlalchemy") is not None
308
- )
335
+
336
+ @registry.command(category="tools", condition=lambda: find_spec("sqlalchemy") is not None)
309
337
  async def query(ctx: CommandContext, sql: str):
310
338
  """Execute database query."""
311
339
  await ctx.print(f"Running query: {sql}")
312
340
 
341
+
313
342
  # app.py
314
343
  from slashed import CommandStore
315
344
  from .commands import registry
@@ -334,24 +363,20 @@ class AppContext:
334
363
 
335
364
 
336
365
  # Command that uses the typed context
337
- async def admin_cmd(
338
- ctx: CommandContext[AppContext],
339
- args: list[str],
340
- kwargs: dict[str, str],
341
- ):
366
+ async def admin_cmd(ctx: CommandContext[AppContext], action: str = "status"):
342
367
  """Admin-only command."""
343
368
  state = ctx.get_data() # Type-safe access to context data
344
369
  if not state.is_admin:
345
370
  await ctx.print("Sorry, admin access required!")
346
371
  return
347
- await ctx.print(f"Welcome admin {state.user_name}!")
372
+ await ctx.print(f"Welcome admin {state.user_name}! Running {action}")
348
373
 
349
374
 
350
375
  # Create and register the command
351
376
  admin_command = Command(
377
+ admin_cmd,
352
378
  name="admin",
353
379
  description="Admin-only command",
354
- execute_func=admin_cmd,
355
380
  category="admin",
356
381
  )
357
382
 
@@ -360,12 +385,10 @@ store = CommandStore()
360
385
  store.register_command(admin_command)
361
386
 
362
387
  # Create context with your custom data
363
- ctx = store.create_context(
364
- data=AppContext(user_name="Alice", is_admin=True)
365
- )
388
+ ctx = store.create_context(data=AppContext(user_name="Alice", is_admin=True))
366
389
 
367
- # Execute command with typed context
368
- await store.execute_command("admin", ctx)
390
+ # Execute command with typed context (inside an async function)
391
+ await store.execute_command("admin restart", ctx)
369
392
  ```
370
393
 
371
394
  ## Signal-Based Event System
@@ -377,6 +400,7 @@ from slashed import CommandStore
377
400
 
378
401
  store = CommandStore()
379
402
 
403
+
380
404
  # Monitor command execution
381
405
  @store.command_executed.connect
382
406
  def on_command_executed(event):
@@ -386,29 +410,26 @@ def on_command_executed(event):
386
410
  else:
387
411
  print(f"Command '{event.command}' failed: {event.error}")
388
412
 
413
+
389
414
  # Monitor command output
390
415
  @store.output.connect
391
416
  def on_output(message: str):
392
417
  """Handle command output."""
393
418
  print(f"Output: {message}")
394
419
 
420
+
395
421
  # Monitor command registry changes
396
- @store.command_events.adding.connect
422
+ @store.command_events.added.connect
397
423
  def on_command_added(name: str, command):
398
424
  print(f"New command registered: {name}")
399
-
400
- # Monitor context registry changes
401
- @store.context_events.adding.connect
402
- def on_context_added(type_: type, context):
403
- print(f"New context registered: {type_.__name__}")
404
425
  ```
405
426
 
406
427
  ### Available Signals
407
428
 
408
429
  - `command_executed`: Emitted after command execution (success/failure)
409
430
  - `output`: Emitted for all command output
410
- - `command_events`: EventedDict signals for command registry changes
411
- - `context_events`: EventedDict signals for context registry changes
431
+ - `command_events`: psygnal `EventedDict` signals for command registry changes
432
+ (`adding`, `added`, `removed`, `changed`, ...)
412
433
 
413
434
  The signal system provides a clean way to handle events without tight coupling, making it ideal for UI integration and logging.
414
435
 
@@ -445,8 +466,10 @@ async def main():
445
466
  except EOFError: # Ctrl+D
446
467
  break
447
468
 
469
+
448
470
  if __name__ == "__main__":
449
471
  import asyncio
472
+
450
473
  asyncio.run(main())
451
474
  ```
452
475
 
@@ -460,21 +483,27 @@ Slashed provides a powerful context system that automatically matches commands w
460
483
  from dataclasses import dataclass
461
484
  from slashed import SlashedCommand, CommandStore, CommandContext
462
485
 
486
+
463
487
  # Define your contexts
464
488
  @dataclass
465
489
  class DatabaseContext:
466
490
  """Database connection context."""
491
+
467
492
  connection: str
468
493
  timeout: int = 30
469
494
 
495
+
470
496
  @dataclass
471
497
  class UIContext:
472
498
  """UI context."""
499
+
473
500
  theme: str = "dark"
474
501
 
502
+
475
503
  # Commands specify their required context type
476
504
  class QueryCommand(SlashedCommand):
477
505
  """Execute a database query."""
506
+
478
507
  name = "query"
479
508
 
480
509
  async def execute_command(
@@ -485,13 +514,28 @@ class QueryCommand(SlashedCommand):
485
514
  db = ctx.get_data() # Properly typed as DatabaseContext
486
515
  await ctx.print(f"Executing {query} with timeout {db.timeout}")
487
516
 
517
+
488
518
  # Register contexts and commands
489
519
  store = CommandStore()
490
520
  store.register_context(DatabaseContext("mysql://localhost"))
491
521
  store.register_context(UIContext("light"))
492
522
 
493
- # Commands automatically get their matching context
494
- await store.execute_command_auto("/query select * from users")
523
+ # Commands automatically get their matching context (inside an async function)
524
+ await store.execute_command_auto("query 'select * from users'")
525
+ ```
526
+
527
+ Context matching reads the `ctx` annotation at runtime, so the context classes must be
528
+ importable from the command's module (not defined inside a function).
529
+
530
+ ## Shell-Style Command Lines
531
+
532
+ `execute_shell` parses a command line with bashlex and runs the slash commands it contains,
533
+ supporting `&&`, `||`, `;` and pipes:
534
+
535
+ ```python
536
+ ctx = store.create_context(data=AppState())
537
+ result = await store.execute_shell("greet Alice && greet Bob", ctx)
538
+ print(result.exit_code)
495
539
  ```
496
540
 
497
541
 
@@ -501,8 +545,9 @@ await store.execute_command_auto("/query select * from users")
501
545
  ```python
502
546
  from dataclasses import dataclass
503
547
 
504
- from slashed import ChoiceCompleter, SlashedCommand
548
+ from slashed import ChoiceCompleter, CommandContext, SlashedCommand
505
549
  from slashed.textual_adapter import SlashedApp
550
+ from textual.app import ComposeResult
506
551
  from textual.containers import Container, VerticalScroll
507
552
  from textual.widgets import Input, Label
508
553
 
@@ -510,11 +555,13 @@ from textual.widgets import Input, Label
510
555
  @dataclass
511
556
  class AppState:
512
557
  """Application state available to commands."""
558
+
513
559
  user_name: str
514
560
 
515
561
 
516
562
  class GreetCommand(SlashedCommand):
517
563
  """Greet someone."""
564
+
518
565
  name = "greet"
519
566
  category = "demo"
520
567
 
@@ -561,22 +608,30 @@ Slashed provides a flexible routing system that allows organizing commands into
561
608
 
562
609
  ```python
563
610
  from dataclasses import dataclass
564
- from slashed import CommandRouter, CommandStore, SlashedCommand
611
+ from slashed import CommandRouter, CommandStore, DefaultOutputWriter
612
+
565
613
 
566
614
  # Define contexts for different subsystems
567
615
  @dataclass
568
616
  class GlobalContext:
569
617
  """Global application context."""
618
+
570
619
  env: str = "production"
571
620
 
621
+
572
622
  @dataclass
573
623
  class DatabaseContext:
574
624
  """Database connection context."""
625
+
575
626
  connection: str
576
627
  timeout: int = 30
577
628
 
629
+
578
630
  # Create store and router
579
631
  store = CommandStore()
632
+ await store.initialize() # registers builtin commands like help
633
+ output = DefaultOutputWriter()
634
+ db_context = DatabaseContext("mysql://localhost")
580
635
  router = CommandRouter[GlobalContext, DatabaseContext](
581
636
  global_context=GlobalContext(),
582
637
  commands=store,
@@ -585,7 +640,7 @@ router = CommandRouter[GlobalContext, DatabaseContext](
585
640
  # Add route with restricted commands
586
641
  router.add_route(
587
642
  "db",
588
- DatabaseContext("mysql://localhost"),
643
+ db_context,
589
644
  description="Database operations",
590
645
  allowed_commands={"query", "migrate"}, # Only allow specific commands
591
646
  )
@@ -616,7 +671,7 @@ For full documentation including advanced usage and API reference, visit [phil65
616
671
 
617
672
  ## Contributing
618
673
 
619
- Contributions are welcome! Please feel free to submit a Pull Request. Make sure to read our contributing guidelines first.
674
+ Contributions are welcome! Please feel free to submit a Pull Request.
620
675
 
621
676
  ## License
622
677