magicli 2.1.4__tar.gz → 2.1.6__tar.gz

{magicli-2.1.4 → magicli-2.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: magicli
-Version: 2.1.4
+Version: 2.1.6
 Summary: Automatically generates a CLI from functions.
 Author-email: Patrick Elmer <patrick@elmer.ws>
 License-Expression: GPL-3.0-or-later
@@ -13,9 +13,20 @@ Dynamic: license-file
 
 # magiᴄʟɪ✨
 
-Automatically turns a file into a CLI without any boilerplate by introspecting its functions.
+```bash
+magicli
+```
 
-**`hello world` example**
+automatically turns a file into a CLI by introspecting its functions.
+
+- no boilerplate
+- automatic help message
+- type casting included
+- supports sub-commands
+- complete `pyproject.toml` setup
+- ready for upload to `pypi`
+
+Create a full CLI in only 2 lines of code:
 
 ```python
 # hello.py
@@ -23,15 +34,11 @@ def hello(name, greeting="hello"):
     print(greeting, name)
 ```
 
-becomes
-
-<img src="docs/img/hello.svg"/>
+calling `magicli` creates this CLI:
 
-with only 3 commands
+![hello world example](https://raw.githubusercontent.com/PatrickElmer/magicli/refs/heads/main/docs/img/hello.svg)
 
-1. `pip install magicli`
-1. `magicli`
-1. `pip install .`
+(animated terminal created with [clivio](patrickelmer.github.io/clivio))
 
 ## Quick start
 
@@ -69,12 +76,18 @@ _Make sure the name of your CLI, the module name and the name of the function ha
 pip install .
 ```
 
+or after uploading to `pypi`:
+
+```bash
+pip install <package_name>
+```
+
 ## Advanced use
 
 ### Using subcommands
 
 ```python
-# module.py
+# hello.py
 def hello(): ...
 
 def world(times=1):

{magicli-2.1.4 → magicli-2.1.6}/README.md

@@ -1,8 +1,19 @@
 # magiᴄʟɪ✨
 
-Automatically turns a file into a CLI without any boilerplate by introspecting its functions.
+```bash
+magicli
+```
 
-**`hello world` example**
+automatically turns a file into a CLI by introspecting its functions.
+
+- no boilerplate
+- automatic help message
+- type casting included
+- supports sub-commands
+- complete `pyproject.toml` setup
+- ready for upload to `pypi`
+
+Create a full CLI in only 2 lines of code:
 
 ```python
 # hello.py
@@ -10,15 +21,11 @@ def hello(name, greeting="hello"):
     print(greeting, name)
 ```
 
-becomes
-
-<img src="docs/img/hello.svg"/>
+calling `magicli` creates this CLI:
 
-with only 3 commands
+![hello world example](https://raw.githubusercontent.com/PatrickElmer/magicli/refs/heads/main/docs/img/hello.svg)
 
-1. `pip install magicli`
-1. `magicli`
-1. `pip install .`
+(animated terminal created with [clivio](patrickelmer.github.io/clivio))
 
 ## Quick start
 
@@ -56,12 +63,18 @@ _Make sure the name of your CLI, the module name and the name of the function ha
 pip install .
 ```
 
+or after uploading to `pypi`:
+
+```bash
+pip install <package_name>
+```
+
 ## Advanced use
 
 ### Using subcommands
 
 ```python
-# module.py
+# hello.py
 def hello(): ...
 
 def world(times=1):

{magicli-2.1.4 → magicli-2.1.6}/magicli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: magicli
-Version: 2.1.4
+Version: 2.1.6
 Summary: Automatically generates a CLI from functions.
 Author-email: Patrick Elmer <patrick@elmer.ws>
 License-Expression: GPL-3.0-or-later
@@ -13,9 +13,20 @@ Dynamic: license-file
 
 # magiᴄʟɪ✨
 
-Automatically turns a file into a CLI without any boilerplate by introspecting its functions.
+```bash
+magicli
+```
 
-**`hello world` example**
+automatically turns a file into a CLI by introspecting its functions.
+
+- no boilerplate
+- automatic help message
+- type casting included
+- supports sub-commands
+- complete `pyproject.toml` setup
+- ready for upload to `pypi`
+
+Create a full CLI in only 2 lines of code:
 
 ```python
 # hello.py
@@ -23,15 +34,11 @@ def hello(name, greeting="hello"):
     print(greeting, name)
 ```
 
-becomes
-
-<img src="docs/img/hello.svg"/>
+calling `magicli` creates this CLI:
 
-with only 3 commands
+![hello world example](https://raw.githubusercontent.com/PatrickElmer/magicli/refs/heads/main/docs/img/hello.svg)
 
-1. `pip install magicli`
-1. `magicli`
-1. `pip install .`
+(animated terminal created with [clivio](patrickelmer.github.io/clivio))
 
 ## Quick start
 
@@ -69,12 +76,18 @@ _Make sure the name of your CLI, the module name and the name of the function ha
 pip install .
 ```
 
+or after uploading to `pypi`:
+
+```bash
+pip install <package_name>
+```
+
 ## Advanced use
 
 ### Using subcommands
 
 ```python
-# module.py
+# hello.py
 def hello(): ...
 
 def world(times=1):

{magicli-2.1.4 → magicli-2.1.6}/magicli.egg-info/SOURCES.txt

@@ -12,6 +12,8 @@ magicli.egg-info/SOURCES.txt
 magicli.egg-info/dependency_links.txt
 magicli.egg-info/entry_points.txt
 magicli.egg-info/requires.txt
+magicli.egg-info/scm_file_list.json
+magicli.egg-info/scm_version.json
 magicli.egg-info/top_level.txt
 tests/fixtures.py
 tests/test_cli.py

magicli-2.1.6/magicli.egg-info/scm_file_list.json

@@ -0,0 +1,19 @@
+{
+  "files": [
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+    "magicli.py",
+    ".gitignore",
+    "docs/img/hello.svg",
+    "tests/fixtures.py",
+    "tests/test_magicli.py",
+    "tests/test_parse_kwarg.py",
+    "tests/test_parse_short_options.py",
+    "tests/test_help.py",
+    "tests/test_cli.py",
+    ".github/workflows/release.yml",
+    ".github/workflows/lint.yml",
+    ".github/workflows/pytest.yml"
+  ]
+}

magicli-2.1.6/magicli.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "2.1.6",
+  "distance": 0,
+  "node": "g7e30827f02d07921c90e83b73547295a32bd9915",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-06-23"
+}

{magicli-2.1.4 → magicli-2.1.6}/magicli.py

@@ -1,5 +1,5 @@
 """
-Magicli generates command-line interfaces from Python modules
+`magicli` generates command-line interfaces from Python modules
 by introspecting its functions and automatically parsing command-
 line arguments based on function signatures.
 """
@@ -75,9 +75,9 @@ def call(function, argv, module=None, name=None):
     try:
         args, kwargs = parse_argv(argv, parameters, docstring)
     except ParseArgvError as exc:
-        message = exc.args[0] + "\n\n" if exc.args else ""
-        message += help_message(help_from_function, function, name)
-        raise SystemExit(message)
+        raise SystemExit(
+            help_message(help_from_function, function, name, module, error=exc.args[0])
+        )
 
     function(*args, **kwargs)
 
@@ -93,9 +93,9 @@ def parse_argv(argv, parameters, docstring):
             kwargs[left] = right
         elif key.startswith("-"):
             parse_short_options(key[1:], docstring, iter_argv, parameters, kwargs)
+        elif (index := len(args)) >= len(parameter_list):
+            raise ParseArgvError(f"{key}: unknown command")
         else:
-            if (index := len(args)) >= len(parameter_list):
-                raise ParseArgvError(f"{key}: unknown command")
             args.append(cast_value(key, get_type(parameter_list[index])))
 
     check_all_args_present(len(args), parameter_list)
@@ -125,14 +125,14 @@ def parse_kwarg(key, argv, parameters):
     key, value = key.split("=", 1) if "=" in key else (key, None)
     key = key.replace("-", "_")
 
-    if key not in parameters:
+    if (parameter := parameters.get(key)) is None:
         raise ParseArgvError(f"--{key}: unknown long option")
 
-    cast_to = get_type(parameters[key])
+    cast_to = get_type(parameter)
 
     if value is None:
         if cast_to is bool:
-            return key, not parameters[key].default
+            return key, not parameter.default
         if cast_to is type(None):
             return key, True
         value = next_arg(argv)
@@ -161,13 +161,13 @@ def parse_short_options(short_options, docstring, iter_argv, parameters, kwargs)
     for i, short in enumerate(short_options):
         long = short_to_long_option(short, docstring)
 
-        if long not in parameters:
+        if (parameter := parameters.get(long)) is None:
             raise ParseArgvError(f"--{long}: invalid long option")
 
-        cast_to = get_type(parameters[long])
+        cast_to = get_type(parameter)
 
         if cast_to is bool:
-            kwargs[long] = not parameters[long].default
+            kwargs[long] = not parameter.default
         elif cast_to is type(None):
             kwargs[long] = True
         elif i == len(short_options) - 1:
@@ -214,16 +214,17 @@ def check_for_version(argv, parameters, docstring, module):
         raise SystemExit
 
 
-def help_message(help_function, obj, *args):
+def help_message(help_function, obj, *args, error=None):
     """
     Generates a help message for a function or module.
     Returns the object's docstring if available, otherwise generates the help message
     using the provided `help_function`.
     """
-    return inspect.getdoc(obj) or help_function(obj, *args) or 1
+    message = inspect.getdoc(obj) or help_function(obj, *args)
+    return (error + "\n\n" if error else "") + message if message else 1
 
 
-def help_from_function(function, name=None):
+def help_from_function(function, name=None, module=None):
     """
     Generates a help message for a function based on its signature.
     Displays the function name, required positional arguments, and
@@ -232,7 +233,11 @@ def help_from_function(function, name=None):
     message = [name] if name else []
     message.append(function.__name__)
     message.extend(map(format_kwarg, inspect.signature(function).parameters.values()))
-    return format_blocks([["usage:", " ".join(message)]])
+    blocks = [["usage:", " ".join(message)]]
+    if module and (commands := get_commands(module)):
+        blocks[0].append(f"{module.__name__} <command>")
+        blocks.append(["commands:", *commands])
+    return format_blocks(blocks)
 
 
 def format_kwarg(kwarg):
@@ -245,16 +250,11 @@ def help_from_module(module):
     Generates a help message for a module and lists available commands.
     Lists all public functions that are not excluded in `__all__`.
     """
-    blocks = []
-
-    if version := get_version(module):
-        blocks.append([f"{module.__name__} {version}"])
-
-    blocks.append(["usage:", f"{module.__name__} command"])
-
+    version = get_version(module)
+    blocks = [[f"{module.__name__} {version}"]] if version else []
     if commands := get_commands(module):
+        blocks.append(["usage:", f"{module.__name__} command"])
         blocks.append(["commands:", *commands])
-
     return format_blocks(blocks)
 
 
@@ -276,7 +276,9 @@ def get_commands(module):
     return [
         name
         for name, _ in inspect.getmembers(module, inspect.isfunction)
-        if not name.startswith("_") and name in module.__dict__.get("__all__", [name])
+        if not name.startswith("_")
+        and name in module.__dict__.get("__all__", [name])
+        and name != module.__name__
     ]
 
 

{magicli-2.1.4 → magicli-2.1.6}/tests/test_cli.py

@@ -1,4 +1,3 @@
-import logging
 from pathlib import Path
 from unittest import mock
 

{magicli-2.1.4 → magicli-2.1.6}/tests/test_magicli.py

@@ -33,6 +33,14 @@ module_version = partial(module, version="1.2.3")
 module_empty = partial(create_module, functions=None)
 
 
+def module_with_two_commands(name):
+    module = type(sys)(name)
+    setattr(module, "name", lambda: None)
+    setattr(module, "command", lambda: None)
+    setattr(module, "command_2", lambda: None)
+    return module
+
+
 @mock.patch("importlib.import_module", side_effect=module)
 def test_module_imported(mocked):
     sys.argv = ["name"]
@@ -115,3 +123,21 @@ def test_version_with_command(mocked, caplog):
         magicli()
     assert error.value.code is None
     assert caplog.messages[0] == "1.2.3"
+
+
+@mock.patch("importlib.import_module", side_effect=module_with_two_commands)
+def test_help_message_for_unknown_command(mocked):
+    sys.argv = ["name", "unknown_command"]
+    with pytest.raises(SystemExit) as error:
+        magicli()
+    assert error.value.code == """\
+unknown_command: unknown command
+
+usage:
+  <lambda>
+  name <command>
+
+commands:
+  command
+  command_2\
+"""