magicli 2.0.2__tar.gz → 2.1.0__tar.gz

{magicli-2.0.2 → magicli-2.1.0}/.github/workflows/lint.yml

@@ -13,7 +13,7 @@ jobs:
       - uses: astral-sh/setup-uv@v5
         with:
           cache-dependency-glob: ""
-      - run: uv run --with flake8 flake8 magicli.py --extend-ignore=E501
+      - run: uv run --with flake8 flake8 magicli.py --extend-ignore=E203,E501
 
   pylint:
     runs-on: ubuntu-latest
@@ -22,7 +22,7 @@ jobs:
       - uses: astral-sh/setup-uv@v5
         with:
           cache-dependency-glob: ""
-      - run: uv run --with pylint pylint --disable=unidiomatic-typecheck,raise-missing-from magicli.py
+      - run: uv run --with pylint pylint magicli.py
 
   ruff:
     runs-on: ubuntu-latest

{magicli-2.0.2 → magicli-2.1.0}/.gitignore

@@ -1,5 +1,5 @@
 _*
-.pytest_cache
+.*_cache
 .vscode
 .venv
 build

{magicli-2.0.2 → magicli-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: magicli
-Version: 2.0.2
+Version: 2.1.0
 Summary: Automatically generates a CLI from functions.
 Author-email: Patrick Elmer <patrick@elmer.ws>
 License-Expression: GPL-3.0-or-later

{magicli-2.0.2 → magicli-2.1.0}/magicli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: magicli
-Version: 2.0.2
+Version: 2.1.0
 Summary: Automatically generates a CLI from functions.
 Author-email: Patrick Elmer <patrick@elmer.ws>
 License-Expression: GPL-3.0-or-later

magicli-2.1.0/magicli.py

@@ -0,0 +1,397 @@
+"""
+Magicli generates command-line interfaces from Python modules
+by introspecting its functions and automatically parsing command-
+line arguments based on function signatures.
+"""
+
+import importlib
+import inspect
+import logging
+import os
+import subprocess
+import sys
+from functools import partial
+from importlib import metadata
+from pathlib import Path
+
+logging.basicConfig(level=os.getenv("MAGICLI_LOG_LEVEL", "DEBUG"), format="%(message)s")
+
+
+class ParseArgvError(Exception):
+    """Failure to parse argv into args and kwargs based on function parameters and docstring."""
+
+
+def magicli():
+    """Parses command-line arguments and calls the appropriate function."""
+    name = Path(sys.argv[0]).name
+    argv = sys.argv[1:]
+
+    if name == "magicli":
+        raise SystemExit(call(cli, argv, sys.modules["magicli"]))
+
+    module = load_module(name)
+
+    if function := get_function_from_argv(argv, module, name.replace("-", "_")):
+        function()
+    else:
+        raise SystemExit(help_message(help_from_module, module))
+
+
+def get_function_from_argv(argv, module, name):
+    """Returns the module's function to call based on argv."""
+    if function := is_command(argv, module):
+        return partial(call, function, argv[1:], module, name)
+    if inspect.isfunction(function := module.__dict__.get(name)):
+        return partial(call, function, argv, module)
+    return None
+
+
+def is_command(argv, module):
+    """
+    Checks if the first argument is a valid command in the module and returns
+    the function to call if `argv[0]` is public and not excluded in `__all__`.
+    """
+    if (
+        argv
+        and not (command := argv[0].replace("-", "_")).startswith("_")
+        and command in module.__dict__.get("__all__", [command])
+        and inspect.isfunction(function := module.__dict__.get(command))
+    ):
+        return function
+    return None
+
+
+def call(function, argv, module=None, name=None):
+    """
+    Converts arguments to function parameters and calls the function.
+    Displays a help message if an exception occurs.
+    """
+    docstring = inspect.getdoc(function) or ""
+    parameters = inspect.signature(function).parameters
+
+    check_for_version(argv, parameters, docstring, module)
+
+    try:
+        args, kwargs = parse_argv(argv, parameters, docstring)
+    except ParseArgvError as exc:
+        raise SystemExit(help_message(help_from_function, function, name)) from exc
+
+    function(*args, **kwargs)
+
+
+def parse_argv(argv, parameters, docstring):
+    """Convert argv into args and kwargs."""
+    parameter_list = list(parameters.values())
+    args, kwargs = [], {}
+
+    for key in (iter_argv := iter(argv)):
+        if key.startswith("--"):
+            left, right = parse_kwarg(key[2:], iter_argv, parameters)
+            kwargs[left] = right
+        elif key.startswith("-"):
+            parse_short_options(key[1:], docstring, iter_argv, parameters, kwargs)
+        else:
+            if (index := len(args)) >= len(parameter_list):
+                raise ParseArgvError
+            args.append(get_type(parameter_list[index])(key))
+
+    return args, kwargs
+
+
+def parse_kwarg(key, argv, parameters):
+    """
+    Parses a single keyword argument from command-line arguments.
+    Handles '=' syntax for inline values. Casts `NoneType` values to `True`
+    and boolean values to `not default`.
+    """
+    key, value = key.split("=", 1) if "=" in key else (key, None)
+    key = key.replace("-", "_")
+    cast_to = get_type(parameters.get(key))
+
+    if value is None:
+        if cast_to is bool:
+            return key, not parameters[key].default
+        if cast_to is type(None):
+            return key, True
+        value = next(argv)
+
+    return key, value if cast_to is str else cast_to(value)
+
+
+def parse_short_options(short_options, docstring, iter_argv, parameters, kwargs):
+    """Converts short options into long options and casts into correct types."""
+    for i, short in enumerate(short_options):
+        long = short_to_long_option(short, docstring)
+
+        if long not in parameters:
+            raise SystemExit(f"--{long}: invalid long option")
+
+        cast_to = get_type(parameters[long])
+
+        if cast_to is bool:
+            kwargs[long] = not parameters[long].default
+        elif cast_to is type(None):
+            kwargs[long] = True
+        elif i == len(short_options) - 1:
+            kwargs[long] = cast_to(next(iter_argv))
+        else:
+            raise SystemExit(f"-{short}: invalid type")
+
+
+def short_to_long_option(short, docstring):
+    """Converts a one character short option to a long option according to the help message."""
+    template = f"-{short}, --"
+    if (start := docstring.find(template)) != -1:
+        start += len(template)
+        if len(docstring) - start > 1:
+            chars = [" ", "\n", "]"]
+            indices = (i for char in chars if (i := docstring.find(char, start)) != -1)
+            return docstring[start : min(indices, default=None)]
+    raise SystemExit(f"-{short}: invalid short option")
+
+
+def get_type(parameter):
+    """
+    Determines the type based on function signature annotations or defaults.
+    Falls back to `str` if neither is available.
+    """
+    if parameter.annotation is not parameter.empty:
+        return parameter.annotation
+    if parameter.default is not parameter.empty:
+        return type(parameter.default)
+    return str
+
+
+def check_for_version(argv, parameters, docstring, module):
+    """Displays version information if --version is specified in the docstring."""
+    if "version" in parameters or not module or len(argv) != 1:
+        return
+    args = {
+        "--version": "--version",
+        "-v": "-v, --version",
+        "-V": "-V, --version",
+    }
+    if (doc := args.get(argv[0])) and doc in docstring:
+        logging.info(get_version(module))
+        raise SystemExit
+
+
+def help_message(help_function, obj, *args):
+    """
+    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
+
+
+def help_from_function(function, name=None):
+    """
+    Generates a help message for a function based on its signature.
+    Displays the function name, required positional arguments, and
+    optional keyword arguments with their default values.
+    """
+    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)]])
+
+
+def format_kwarg(kwarg):
+    """Formats a parameter as positional or optional argument."""
+    return kwarg.name if kwarg.default is kwarg.empty else f"[--{kwarg.name}]"
+
+
+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"])
+
+    if commands := get_commands(module):
+        blocks.append(["commands:", *commands])
+
+    return format_blocks(blocks)
+
+
+def format_blocks(blocks, sep="\n  "):
+    """Formats blocks of text with proper indentation."""
+    return "\n\n".join(sep.join(block) for block in blocks)
+
+
+def load_module(name):
+    """Load module from name"""
+    try:
+        return importlib.import_module(name)
+    except ModuleNotFoundError as exc:
+        raise SystemExit(f"{name}: command not found") from exc
+
+
+def get_commands(module):
+    """Returns list of public commands that are not excluded by `__all__`."""
+    return [
+        name
+        for name, _ in inspect.getmembers(module, inspect.isfunction)
+        if not name.startswith("_") and name in module.__dict__.get("__all__", [name])
+    ]
+
+
+def get_version(module):
+    """Returns the version of a module from its metadata or `__version__` attribute."""
+    try:
+        return metadata.version(module.__name__)
+    except metadata.PackageNotFoundError:
+        return module.__dict__.get("__version__")
+
+
+def get_project_name():
+    """Detect project name from project structure."""
+    single_file_layout = [path.stem for path in Path().glob("*.py")]
+    flat_layout = [
+        path.parent.name
+        for path in Path().glob("*/__init__.py")
+        if path.parent.name != "tests"
+    ]
+    src_layout = [path.parent.name for path in Path().glob("src/*/__init__.py")]
+
+    if len(names := single_file_layout + flat_layout + src_layout) == 1:
+        return names[0]
+
+    if name := input("CLI name: "):
+        return name
+
+    raise SystemExit(1)
+
+
+def get_output(command):
+    """Return the stdout of a shell command or None on failure."""
+    try:
+        output = subprocess.run(
+            command.split(), capture_output=True, text=True, check=False
+        ).stdout
+    except FileNotFoundError:
+        return None
+    return output.removesuffix("\n") or None
+
+
+def get_homepage(url=None):
+    """Return a homepage url from a git remote url."""
+    url = url or get_output("git remote get-url origin") or ""
+    if url.startswith("git@"):
+        url = "https://" + url.removeprefix("git@").replace(":", "/")
+    return url.removesuffix(".git")
+
+
+def get_description(name):
+    """Return the first paragraph of a module's docstring if available."""
+    try:
+        module = importlib.import_module(name)
+    except ModuleNotFoundError:
+        return None
+    doc = (module.__doc__ or "").split("\n\n")[0]
+    return " ".join(stripped for line in doc.splitlines() if (stripped := line.strip()))
+
+
+def get_license_expression(content):
+    """Returns the license expression used in pyproject.toml."""
+    return {
+        "Apache License": "Apache-2.0",
+        "BSD 2-Clause License": "BSD-2-Clause",
+        "BSD 3-Clause License": "BSD-3-Clause",
+        "GNU AFFERO GENERAL PUBLIC LICENSE": "AGPL-3.0-or-later",
+        "GNU GENERAL PUBLIC LICENSE": "GPL-3.0-or-later",
+        "GNU LESSER GENERAL PUBLIC LICENSE": "LGPL-3.0-or-later",
+        "MIT License": "MIT",
+        "Mozilla Public License Version 2.0": "MPL-2.0",
+        "Public domain statement": "Unlicense",
+    }.get(content.split("\n")[0].strip())
+
+
+def detect_path(glob, extensions):
+    """Returns only a single path of a glob if it ends with one of the provided extensions."""
+    paths = [path for path in Path().glob(glob) if path.suffix in extensions]
+    return paths[0] if len(paths) == 1 else None
+
+
+def cli(name="", author="", email="", description="", homepage=""):
+    """
+    magiCLI✨
+
+    Generates a "pyproject.toml" configuration file for a module and sets up the project script.
+    The CLI name must be the same as the module name.
+
+    usage:
+      magicli [option]
+
+    options:
+      --name
+      --author
+      --email
+      --description
+      --homepage
+      -v, --version
+    """
+    pyproject = Path("pyproject.toml")
+    if (
+        pyproject.exists()
+        and input("Overwrite existing pyproject.toml? (yN) ").strip().lower() != "y"
+    ):
+        raise SystemExit(1)
+
+    name = name or get_project_name()
+
+    if Path(".git").exists():
+        author = author or get_output("git config --get user.name")
+        email = email or get_output("git config --get user.email")
+        if not get_output("git tag"):
+            logging.debug("Specify the version with `git tag`")
+    else:
+        logging.debug("Not a git repo. Run `git init`")
+
+    authors = [f'{k}="{v}"' for k, v in {"name": author, "email": email}.items() if v]
+
+    project = [
+        "[project]",
+        f'name = "{name}"',
+        'dynamic = ["version"]',
+        'dependencies = ["magicli<3"]',
+    ]
+
+    if authors:
+        project.append(f"authors = [{{{', '.join(authors)}}}]")
+
+    if readme := detect_path("README*", {".md", ".rst", ".txt"}):
+        project.append(f'readme = "{readme.name}"')
+
+    if license_file := detect_path("LICENSE*", {"", ".txt"}):
+        license_content = license_file.read_text(encoding="utf-8")
+        if license_expression := get_license_expression(license_content):
+            project.append(f'license = "{license_expression}"')
+        else:
+            logging.debug("Unknown license: %s", license_file.name)
+        project.append(f'license-files = ["{license_file.name}"]')
+
+    if description or (description := get_description(name)):
+        project.append(f'description = "{description}"')
+
+    blocks = [project, ["[project.scripts]", f'{name} = "magicli:magicli"']]
+
+    if homepage or (homepage := get_homepage()):
+        blocks.append(["[project.urls]", f'Home = "{homepage}"'])
+
+    blocks.append(
+        [
+            "[build-system]",
+            'requires = ["setuptools>=80", "setuptools-scm[simple]>=8"]',
+            'build-backend = "setuptools.build_meta"',
+        ]
+    )
+
+    pyproject.write_text(format_blocks(blocks, sep="\n") + "\n", encoding="utf-8")
+    logging.debug("Created pyproject.toml ✨")

{magicli-2.0.2 → magicli-2.1.0}/pyproject.toml

@@ -19,3 +19,12 @@ dev = ["pytest"]
 
 [project.urls]
 Home = "https://github.com/PatrickElmer/magicli"
+
+[tool.pylint."messages control"]
+disable = [
+    "unidiomatic-typecheck",
+    "raise-missing-from",
+]
+
+[tool.pytest]
+log_level = "DEBUG"

magicli-2.1.0/tests/fixtures.py

@@ -0,0 +1,72 @@
+import os
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+import pytest
+
+
+def _setup(filenames, dirname=None):
+    cwd = Path.cwd()
+    directory = TemporaryDirectory()
+    if dirname:
+        Path(directory.name, dirname).mkdir()
+        os.chdir(directory.name)
+    else:
+        os.chdir(directory.name)
+    for filename in filenames:
+        Path(directory.name, filename).touch()
+    return directory, cwd
+
+
+def _teardown(directory, cwd):
+    directory.cleanup()
+    os.chdir(cwd)
+
+
+@pytest.fixture
+def with_tempdir():
+    directory, cwd = _setup(["module.py"])
+    yield directory.name
+    _teardown(directory, cwd)
+
+
+@pytest.fixture
+def with_license():
+    directory, cwd = _setup(["LICENSE"])
+    yield directory.name
+    _teardown(directory, cwd)
+
+
+@pytest.fixture
+def with_readme_and_license():
+    directory, cwd = _setup(["README.md", "LICENSE"])
+    yield directory.name
+    _teardown(directory, cwd)
+
+
+@pytest.fixture
+def with_two_files():
+    directory, cwd = _setup(["module.py", "two.py"])
+    yield
+    _teardown(directory, cwd)
+
+
+@pytest.fixture
+def pyproject():
+    directory, cwd = _setup(["pyproject.toml", "module.py"])
+    yield Path(directory.name, "pyproject.toml")
+    _teardown(directory, cwd)
+
+
+@pytest.fixture
+def with_git():
+    directory, cwd = _setup([], dirname=".git")
+    yield
+    _teardown(directory, cwd)
+
+
+@pytest.fixture
+def empty_directory():
+    directory, cwd = _setup([])
+    yield
+    _teardown(directory, cwd)

magicli-2.1.0/tests/test_cli.py

@@ -0,0 +1,135 @@
+import logging
+from pathlib import Path
+from unittest import mock
+
+import pytest
+from fixtures import (
+    empty_directory,
+    pyproject,
+    with_git,
+    with_license,
+    with_readme_and_license,
+    with_tempdir,
+    with_two_files,
+)
+
+from magicli import (
+    cli,
+    get_description,
+    get_homepage,
+    get_license_expression,
+    get_output,
+    get_project_name,
+)
+
+
+def module(name):
+    module = type(pytest)(name)
+    module.__doc__ = "docstring"
+    return module
+
+
+@mock.patch("builtins.input", lambda _: "two")
+def test_correct_name_input(with_two_files):
+    cli()
+
+    path = Path("pyproject.toml")
+    assert path.exists()
+    with path.open(encoding="utf-8") as f:
+        assert 'name = "two"' in f.read()
+
+
+@mock.patch("builtins.input", lambda *_: "y")
+def test_automatic_name(pyproject):
+    cli()
+
+    assert 'name = "module"' in pyproject.read_text()
+
+
+@mock.patch("builtins.input", lambda *_: "y")
+def test_overwrite_pyproject_toml(pyproject):
+    cli()
+
+    assert 'name = "module"' in pyproject.read_text()
+
+
+@mock.patch("builtins.input", lambda *_: "")
+def test_empty_cli_name_failure(with_two_files):
+    with pytest.raises(SystemExit) as error:
+        get_project_name()
+    assert error.value.code == 1
+
+
+def test_with_git_repo(caplog, with_git):
+    cli(name="_")
+    assert "Specify the version with `git tag`" in caplog.messages
+
+
+def test_without_git_repo(caplog, empty_directory):
+    cli(name="_")
+    assert "Not a git repo. Run `git init`" in caplog.messages
+
+
+def test_get_output():
+    assert get_output("ls") is not None
+    assert get_output("-") is None
+
+
+def test_get_homepage():
+    for url in [
+        "https://github.com/PatrickElmer/magicli.git",
+        "git@github.com:PatrickElmer/magicli.git",
+    ]:
+        assert get_homepage(url) == "https://github.com/PatrickElmer/magicli"
+
+
+def test_get_description():
+    assert get_description("magicli") is not None
+
+
+def test_get_license_expression():
+    assert get_license_expression("Apache License") == "Apache-2.0"
+    assert get_license_expression(" GNU GENERAL PUBLIC LICENSE ") == "GPL-3.0-or-later"
+    assert get_license_expression("") is None
+
+
+def test_cli_with_license(with_license):
+    Path(with_license, "LICENSE").write_text("MIT License", encoding="utf-8")
+    cli(name="name", author="Patrick Elmer", email="patrick@elmer.ws")
+    pyproject = Path("pyproject.toml").read_text(encoding="utf-8")
+    assert 'license = "MIT"' in pyproject
+    assert 'license-files = ["LICENSE"]' in pyproject
+
+
+def test_cli_with_kwargs(caplog, with_readme_and_license):
+    cli(
+        name="name",
+        author="Patrick Elmer",
+        email="patrick@elmer.ws",
+        description="docstring",
+        homepage="https://github.com/PatrickElmer/magicli",
+    )
+    assert any(msg == "Unknown license: LICENSE" for msg in caplog.messages)
+    assert (
+        Path("pyproject.toml").read_text(encoding="utf-8")
+        == """\
+[project]
+name = "name"
+dynamic = ["version"]
+dependencies = ["magicli<3"]
+authors = [{name="Patrick Elmer", email="patrick@elmer.ws"}]
+readme = "README.md"
+license-files = ["LICENSE"]
+description = "docstring"
+
+[project.scripts]
+name = "magicli:magicli"
+
+[project.urls]
+Home = "https://github.com/PatrickElmer/magicli"
+
+[build-system]
+requires = ["setuptools>=80", "setuptools-scm[simple]>=8"]
+build-backend = "setuptools.build_meta"
+"""
+    )

{magicli-2.0.2 → magicli-2.1.0}/tests/test_magicli.py

@@ -1,24 +1,22 @@
+import logging
 import sys
-from unittest import mock
 from functools import partial
+from unittest import mock
 
 import pytest
+from fixtures import pyproject
 
 from magicli import magicli
 
-ANSWER = None
-
 
 def name():
-    "--version"
-    global ANSWER
-    ANSWER = 1
+    "-V, --version"
+    logging.info("name")
 
 
 def command():
     "-v, --version"
-    global ANSWER
-    ANSWER = 2
+    logging.info("command")
 
 
 def create_module(name, version=None, functions=None):
@@ -43,19 +41,19 @@ def test_module_imported(mocked):
 
 
 @mock.patch("importlib.import_module", side_effect=module)
-def test_first_function_called(mocked):
+def test_first_function_called(mocked, caplog):
     sys.argv = ["name"]
     magicli()
     mocked.assert_called_once_with("name")
-    assert ANSWER == 1
+    assert caplog.messages[0] == "name"
 
 
 @mock.patch("importlib.import_module", side_effect=module)
-def test_command_called(mocked):
+def test_command_called(mocked, caplog):
     sys.argv = ["name", "command"]
     magicli()
     mocked.assert_called_once_with("name")
-    assert ANSWER == 2
+    assert caplog.messages[0] == "command"
 
 
 @mock.patch("importlib.import_module", side_effect=module)
@@ -65,12 +63,6 @@ def test_wrong_command_not_called(mocked):
         magicli()
 
 
-def test_empty_sys_argv():
-    sys.argv = []
-    with pytest.raises(SystemExit):
-        magicli()
-
-
 @mock.patch("importlib.import_module", side_effect=module_empty)
 def test_module_without_functions(mocked):
     sys.argv = ["name"]
@@ -84,8 +76,8 @@ def test_module_not_found():
         magicli()
 
 
-@mock.patch("builtins.input", lambda *args: "n")
-def test_module_is_magicli():
+@mock.patch("builtins.input", return_value="n")
+def test_module_is_magicli(pyproject):
     sys.argv = ["magicli"]
     with pytest.raises(SystemExit) as error:
         magicli()
@@ -100,12 +92,13 @@ def test_short_option_with_wrong_type(mocked):
 
 
 @mock.patch("importlib.import_module", side_effect=module_version)
-def test_version(mocked, capsys):
-    sys.argv = ["name", "--version"]
-    with pytest.raises(SystemExit) as error:
-        magicli()
-    assert error.value.code is None
-    assert capsys.readouterr()[0] == "1.2.3\n"
+def test_version(mocked, caplog):
+    for version in ["--version", "-V"]:
+        sys.argv = ["name", version]
+        with pytest.raises(SystemExit) as error:
+            magicli()
+        assert error.value.code is None
+        assert caplog.messages[0] == "1.2.3"
 
     sys.argv = ["name", "-v"]
     with pytest.raises(SystemExit) as error:
@@ -114,9 +107,9 @@ def test_version(mocked, capsys):
 
 
 @mock.patch("importlib.import_module", side_effect=module_version)
-def test_version_with_command(mocked, capsys):
+def test_version_with_command(mocked, caplog):
     sys.argv = ["name", "command", "-v"]
     with pytest.raises(SystemExit) as error:
         magicli()
     assert error.value.code is None
-    assert capsys.readouterr()[0] == "1.2.3\n"
+    assert caplog.messages[0] == "1.2.3"

{magicli-2.0.2 → magicli-2.1.0}/tests/test_parse_kwarg.py

@@ -3,7 +3,7 @@ from inspect import Parameter, _ParameterKind
 
 import pytest
 
-from magicli import args_and_kwargs, get_type, parse_kwarg
+from magicli import get_type, parse_argv, parse_kwarg
 
 PK = _ParameterKind.POSITIONAL_OR_KEYWORD
 
@@ -29,30 +29,30 @@ def test_parse_kwarg_bool_and_none(default, result):
 
 
 def test_get_type():
-    assert get_type(Parameter("a", PK, annotation=int)) == int
-    assert get_type(Parameter("b", PK, default=1)) == int
-    assert get_type(Parameter("c", PK)) == str
+    assert get_type(Parameter("a", PK, annotation=int)) is int
+    assert get_type(Parameter("b", PK, default=1)) is int
+    assert get_type(Parameter("c", PK)) is str
 
 
-def test_args_and_kwargs():
+def test_parse_argv():
     parameters = inspect.signature(lambda arg, kwarg=1: None).parameters
-    assert args_and_kwargs(["a", "--kwarg=2"], parameters, docstring="") == (
+    assert parse_argv(["a", "--kwarg=2"], parameters, docstring="") == (
         ["a"],
         {"kwarg": 2},
     )
-    assert args_and_kwargs(["a", "--kwarg", "2"], parameters, docstring="") == (
+    assert parse_argv(["a", "--kwarg", "2"], parameters, docstring="") == (
         ["a"],
         {"kwarg": 2},
     )
 
 
-def test_args_and_kwargs_with_underscore():
+def test_parse_argv_with_underscore():
     parameters = inspect.signature(lambda arg, kwarg_1=1: None).parameters
-    assert args_and_kwargs(["a", "--kwarg-1=2"], parameters, docstring="") == (
+    assert parse_argv(["a", "--kwarg-1=2"], parameters, docstring="") == (
         ["a"],
         {"kwarg_1": 2},
     )
-    assert args_and_kwargs(["a", "--kwarg-1", "2"], parameters, docstring="") == (
+    assert parse_argv(["a", "--kwarg-1", "2"], parameters, docstring="") == (
         ["a"],
         {"kwarg_1": 2},
     )

{magicli-2.0.2 → magicli-2.1.0}/tests/test_parse_short_options.py

@@ -1,4 +1,3 @@
-from functools import partial
 from inspect import Parameter, _ParameterKind
 
 import pytest
@@ -7,7 +6,7 @@ from magicli import parse_short_options, short_to_long_option
 
 
 @pytest.mark.parametrize(
-    ["default", "result"],
+    ("default", "result"),
     [
         (None, True),
         (True, False),

magicli-2.0.2/magicli.py

@@ -1,314 +0,0 @@
-"""
-Magicli generates command-line interfaces from Python modules
-by introspecting its functions and automatically parsing command-
-line arguments based on function signatures.
-"""
-
-import importlib
-import inspect
-import sys
-from importlib import metadata
-from pathlib import Path
-
-
-def magicli():
-    """
-    Parses command-line arguments and calls the appropriate function.
-    """
-    if not sys.argv:
-        raise SystemExit(1)
-
-    name = Path(sys.argv[0]).name
-    argv = sys.argv[1:]
-
-    if name == "magicli":
-        raise SystemExit(call(cli, argv))
-
-    module = load_module(name)
-    name = name.replace("-", "_")
-
-    if function := is_command(argv, module):
-        call(function, argv[1:], module, name)
-    elif inspect.isfunction(function := module.__dict__.get(name)):
-        call(function, argv, module)
-    else:
-        raise SystemExit(help_message(help_from_module, module))
-
-
-def is_command(argv, module):
-    """
-    Checks if the first argument is a valid command in the module and returns
-    the function to call if `argv[0]` is public and not excluded in `__all__`,
-    """
-    if (
-        argv
-        and not (command := argv[0].replace("-", "_")).startswith("_")
-        and command in module.__dict__.get("__all__", [command])
-        and inspect.isfunction(function := module.__dict__.get(command))
-    ):
-        return function
-    return None
-
-
-def call(function, argv, module=None, name=None):
-    """
-    Converts arguments to function parameters and calls the function.
-    Displays a help message if an exception occurs.
-    """
-    try:
-        docstring = get_docstring(function)
-        parameters = inspect.signature(function).parameters
-
-        check_for_version(argv, parameters, docstring, module)
-
-        args, kwargs = args_and_kwargs(argv, parameters, docstring)
-        function(*args, **kwargs)
-    except Exception:
-        raise SystemExit(help_message(help_from_function, function, name))
-
-
-def args_and_kwargs(argv, parameters, docstring):
-    """
-    Parses command-line arguments into positional and keyword arguments.
-    """
-    parameter_list = list(parameters.values())
-    args, kwargs = [], {}
-
-    for key in (iter_argv := iter(argv)):
-        if key.startswith("--"):
-            left, right = parse_kwarg(key[2:], iter_argv, parameters)
-            kwargs[left] = right
-        elif key.startswith("-"):
-            parse_short_options(key[1:], docstring, iter_argv, parameters, kwargs)
-        else:
-            args.append(get_type(parameter_list[len(args)])(key))
-
-    return args, kwargs
-
-
-def parse_short_options(short_options, docstring, iter_argv, parameters, kwargs):
-    """
-    Converts short options into long options and casts into correct types.
-    """
-    for i, short in enumerate(short_options):
-        long = short_to_long_option(short, docstring)
-
-        if long not in parameters:
-            raise SystemExit(f"--{long}: invalid long option")
-
-        cast_to = get_type(parameters[long])
-
-        if cast_to is bool:
-            kwargs[long] = not parameters[long].default
-        elif cast_to is type(None):
-            kwargs[long] = True
-        elif i == len(short_options) - 1:
-            kwargs[long] = cast_to(next(iter_argv))
-        else:
-            raise SystemExit(f"-{short}: invalid type")
-
-
-def short_to_long_option(short, docstring):
-    """
-    Converts a one character short option to a long option accoring to the help message.
-    """
-    template = f"-{short}, --"
-    if (start := docstring.find(template)) != -1:
-        start += len(template)
-        chars = (" ", "\n", "]")
-
-        try:
-            end = min(i for ws in chars if (i := docstring.find(ws, start)) != -1)
-            return docstring[start:end]
-
-        except ValueError:
-            if len(docstring) - start > 1:
-                return docstring[start:]
-
-    raise SystemExit(f"-{short}: invalid short option")
-
-
-def parse_kwarg(key, argv, parameters):
-    """
-    Parses a single keyword argument from command-line arguments.
-    Handles '=' syntax for inline values. Casts `NoneType` values to `True`
-    and boolean values to `not default`.
-    """
-    key, value = key.split("=", 1) if "=" in key else (key, None)
-    key = key.replace("-", "_")
-    cast_to = get_type(parameters.get(key))
-
-    if value is None:
-        if cast_to is bool:
-            return key, not parameters[key].default
-        if cast_to is type(None):
-            return key, True
-        value = next(argv)
-
-    return key, value if cast_to is str else cast_to(value)
-
-
-def get_type(parameter):
-    """
-    Determines the type based on function signature annotations or defaults.
-    Falls back to `str` if neither is available.
-    """
-    if parameter.annotation is not parameter.empty:
-        return parameter.annotation
-    if parameter.default is not parameter.empty:
-        return type(parameter.default)
-    return str
-
-
-def check_for_version(argv, parameters, docstring, module):
-    """
-    Displays version information if --version is specified in the docstring.
-    """
-    if (
-        "version" not in parameters
-        and any(
-            (argv == [arg] and string in docstring)
-            for arg, string in [("--version", "--version"), ("-v", "-v, --version")]
-        )
-        and module
-    ):
-        print(get_version(module))
-        raise SystemExit
-
-
-def help_message(help_function, obj, *args):
-    """
-    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
-
-
-def help_from_function(function, name=None):
-    """
-    Generates a help message for a function based on its signature.
-    Displays the function name, required positional arguments, and
-    optional keyword arguments with their default values.
-    """
-    message = [name] if name else []
-    message.append(function.__name__)
-    message.extend(map(format_kwarg, inspect.signature(function).parameters.values()))
-    return format_message([["usage:", " ".join(message)]])
-
-
-def format_kwarg(kwarg):
-    """Formats a parameter as positional or optional argument."""
-    return kwarg.name if kwarg.default is kwarg.empty else f"[--{kwarg.name}]"
-
-
-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__`.
-    """
-    message = []
-
-    if version := get_version(module):
-        message.append([f"{module.__name__} {version}"])
-
-    message.append(["usage:", f"{module.__name__} command"])
-
-    if commands := get_commands(module):
-        message.append(["commands:", *commands])
-
-    return format_message(message)
-
-
-def format_message(blocks):
-    """Formats blocks of text with proper indentation."""
-    return "\n\n".join("\n  ".join(block) for block in blocks)
-
-
-def load_module(name):
-    """Load module from name"""
-    try:
-        return importlib.import_module(name)
-    except ModuleNotFoundError:
-        raise SystemExit(f"{name}: command not found")
-
-
-def get_commands(module):
-    """Returns list of public commands, unless not present in `__all__`."""
-    return [
-        name
-        for name, _ in inspect.getmembers(module, inspect.isfunction)
-        if not name.startswith("_") and name in module.__dict__.get("__all__", [name])
-    ]
-
-
-def get_docstring(function):
-    """
-    Returns the cleaned up docstring of a function or an empty string.
-    """
-    return inspect.getdoc(function) or ""
-
-
-def get_version(module):
-    """
-    Returns the version of a module from its metadata or `__version__` attribute.
-    """
-    try:
-        return metadata.version(module.__name__)
-    except metadata.PackageNotFoundError:
-        return module.__dict__.get("__version__")
-
-
-def get_project_name():
-    """
-    Detect project name from project structure.
-    """
-    flat_layout = [path.stem for path in Path().glob("*.py")]
-    src_layout = [path.parent.name for path in Path().glob("*/__init__.py")]
-
-    if len(names := flat_layout + src_layout) == 1:
-        return names[0]
-
-    if name := input("CLI name: "):
-        return name
-
-    raise SystemExit(1)
-
-
-def cli():
-    """
-    Generates a "pyproject.toml" configuration file for a module and sets up the project script.
-    The CLI name must be the same as the module name.
-    """
-    pyproject = Path("pyproject.toml")
-    if (
-        pyproject.exists()
-        and input("Overwrite existing pyproject.toml? (yN) ").strip().lower() != "y"
-    ):
-        raise SystemExit(1)
-
-    name = get_project_name()
-    pyproject.write_text(
-        f"""\
-[build-system]
-requires = ["setuptools>=80", "setuptools-scm[simple]>=8"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "{name}"
-dynamic = ["version"]
-dependencies = ["magicli<3"]
-
-[project.scripts]
-{name} = "magicli:magicli"
-"""
-    )
-
-    message = ["pyproject.toml created! ✨"]
-    if Path(".git").exists():
-        message.append("You can specify the version with `git tag`")
-    else:
-        message.append(
-            "Error: Not a git repo. Run `git init`. Specify version with `git tag`."
-        )
-    print(*message, sep="\n")

magicli-2.0.2/tests/fixtures.py

@@ -1,54 +0,0 @@
-import os
-import shutil
-from pathlib import Path
-
-import pytest
-
-
-@pytest.fixture()
-def setup():
-    cwd = Path.cwd()
-    path = Path("tests", "tmp")
-
-    # Make sure the directory does not exist
-    if path.exists():
-        shutil.rmtree(path)
-
-    path.mkdir(exist_ok=True)
-    Path(path, "module.py").touch()
-    os.chdir(path)
-
-    yield path
-
-    os.chdir(cwd)
-    shutil.rmtree(path)
-
-
-@pytest.fixture()
-def two_py():
-    file = Path("two.py")
-    file.touch()
-
-    yield file
-
-    file.unlink()
-
-
-@pytest.fixture()
-def pyproject_toml():
-    file = Path("pyproject.toml")
-    file.touch()
-
-    yield file
-
-    file.unlink()
-
-
-@pytest.fixture()
-def dotgit():
-    dir = Path(".git")
-    dir.mkdir(exist_ok=True)
-
-    yield dir
-
-    shutil.rmtree(dir)

magicli-2.0.2/tests/test_cli.py

@@ -1,62 +0,0 @@
-from pathlib import Path
-from unittest import mock
-
-import pytest
-from fixtures import pyproject_toml, setup, two_py, dotgit
-
-from magicli import cli, get_project_name
-
-
-@mock.patch("builtins.input", lambda _: "two")
-def test_correct_name_input(setup, two_py):
-    cli()
-
-    path = Path("pyproject.toml")
-    assert path.exists()
-    with path.open() as f:
-        assert 'name = "two"' in f.read()
-
-
-@mock.patch("builtins.input", lambda *args: "n")
-def test_automatic_name(setup):
-    cli()
-    with Path("pyproject.toml").open() as f:
-        assert 'name = "module"' in f.read()
-
-
-@mock.patch("builtins.input", lambda *args: "y")
-def test_overwrite_pyproject_toml(setup, pyproject_toml):
-    cli()
-    with pyproject_toml.open() as f:
-        assert 'name = "module"' in f.read()
-
-
-@mock.patch("builtins.input", lambda *args: "")
-def test_empty_cli_name_failure(setup, two_py):
-    with pytest.raises(SystemExit) as error:
-        get_project_name()
-    assert error.value.code == 1
-
-
-def test_on_git_repo(capsys, setup):
-    cli()
-    out, _ = capsys.readouterr()
-
-    with_git = (
-        "Error: Not a git repo. Run `git init`. Specify version with `git tag`.\n"
-    )
-    without_git = "You can specify the version with `git tag`\n"
-    assert out.endswith(with_git)
-    assert without_git not in out
-
-
-def test_git_repo(capsys, setup, dotgit):
-    cli()
-    out, _ = capsys.readouterr()
-
-    with_git = (
-        "Error: Not a git repo. Run `git init`. Specify version with `git tag`.\n"
-    )
-    without_git = "You can specify the version with `git tag`\n"
-    assert out.endswith(without_git)
-    assert with_git not in out