turbolaunch 0.1.0__tar.gz

turbolaunch-0.1.0/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright 2025 Sam Vervaeck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

turbolaunch-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: turbolaunch
+Version: 0.1.0
+Summary: The definitive command-line arguments parser
+Author-email: Sam Vervaeck <samvv@pm.me>
+Maintainer-email: Sam Vervaeck <samvv@pm.me>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/samvv/turbolaunch
+Project-URL: Bug Reports, https://github.com/samvv/turbolaunch/issues
+Project-URL: Source, https://github.com/samvv/turbolaunch/
+Keywords: cli,argparse,library
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Provides-Extra: dev
+Requires-Dist: check-manifest; extra == "dev"
+Provides-Extra: test
+Requires-Dist: coverage; extra == "test"
+Dynamic: license-file
+
+TurboLaunch
+===========
+
+TurboLaunch is a CLI parser for Python programs that requires almost no setup.
+
+ - ✅ Run Python functions directly as CLI commands
+ - ✅ Support for enums and other built-in types
+ - 🚧 Help messages derived from docstrings
+ - 🚧 Plugins to extend the functionality of this library
+ - 🚧 Fuzzing of as much code paths as possible to ensure quality
+
+TurboLaunch was initially written as part of the [Mage project](https://github.com/samvv/mage).
+
+## Quick Start
+
+Simply create or edit a module with the following code:
+
+```py
+def main() -> int:
+    import turbolaunch
+    turbolaunch.launch(__name__)
+```
+
+In your `pyproject.toml`-file, you'd have something like this:
+
+```toml
+[project.scripts]
+mycommand = "mylibrary:main"
+```
+
+That's it!
+
+Now if you would like to have command `test` which e.g. takes a filename and an optional `foo` flag:
+
+```py
+def test(filename: str, foo: bool = False) -> int:
+    if foo:
+        print("'foo' is enabled")
+    print(f"Reading {filename}")
+    return 0
+```
+
+The above code would be run like this:
+
+```
+mycommand test loremipsum.txt --foo
+```
+
+More options, such as programmatic usage and plugins will come soon.
+
+## License
+
+This software is licensed under the MIT license.

turbolaunch-0.1.0/README.md

@@ -0,0 +1,53 @@
+TurboLaunch
+===========
+
+TurboLaunch is a CLI parser for Python programs that requires almost no setup.
+
+ - ✅ Run Python functions directly as CLI commands
+ - ✅ Support for enums and other built-in types
+ - 🚧 Help messages derived from docstrings
+ - 🚧 Plugins to extend the functionality of this library
+ - 🚧 Fuzzing of as much code paths as possible to ensure quality
+
+TurboLaunch was initially written as part of the [Mage project](https://github.com/samvv/mage).
+
+## Quick Start
+
+Simply create or edit a module with the following code:
+
+```py
+def main() -> int:
+    import turbolaunch
+    turbolaunch.launch(__name__)
+```
+
+In your `pyproject.toml`-file, you'd have something like this:
+
+```toml
+[project.scripts]
+mycommand = "mylibrary:main"
+```
+
+That's it!
+
+Now if you would like to have command `test` which e.g. takes a filename and an optional `foo` flag:
+
+```py
+def test(filename: str, foo: bool = False) -> int:
+    if foo:
+        print("'foo' is enabled")
+    print(f"Reading {filename}")
+    return 0
+```
+
+The above code would be run like this:
+
+```
+mycommand test loremipsum.txt --foo
+```
+
+More options, such as programmatic usage and plugins will come soon.
+
+## License
+
+This software is licensed under the MIT license.

turbolaunch-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "turbolaunch"
+version = "0.1.0"
+description = "The definitive command-line arguments parser"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+keywords = ["cli", "argparse", "library"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+
+  # Indicate who your project is intended for
+  "Intended Audience :: Developers",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+
+  # Specify the Python versions you support here. In particular, ensure
+  # that you indicate you support Python 3. These classifiers are *not*
+  # checked by "pip install". See instead "requires-python" key in this file.
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3 :: Only",
+]
+
+[[project.authors]]
+name = "Sam Vervaeck"
+email = "samvv@pm.me"
+
+[[project.maintainers]]
+name = "Sam Vervaeck"
+email = "samvv@pm.me"
+
+[project.optional-dependencies]
+dev = ["check-manifest"]
+test = ["coverage"]
+
+[project.urls]
+"Homepage" = "https://github.com/samvv/turbolaunch"
+"Bug Reports" = "https://github.com/samvv/turbolaunch/issues"
+"Source" = "https://github.com/samvv/turbolaunch/"
+
+[tool.setuptools]
+# If there are data files included in your packages that need to be
+# installed, specify them here.
+#package-data = { "sample" = ["*.dat"] }

turbolaunch-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

turbolaunch-0.1.0/src/turbolaunch/__init__.py

@@ -0,0 +1,33 @@
+
+from types import ModuleType
+
+from .program import *
+from .parse import parse
+from .convert import convert, convert_command
+
+class App:
+
+    def __init__(self, name) -> None:
+        self.program = Program(name)
+
+    def command[F: Callable[..., int | None]](self, name: str | None = None) -> Callable[[F], F]:
+        def decorator(f: F) -> F:
+            self.program.add_subcommand(convert_command(f, name))
+            return f
+        return decorator
+
+    def __call__(self, argv: list[str]) -> int | None:
+        cmd, posargs, kwargs = parse(self.program, argv[1:])
+        assert(cmd.callback is not None)
+        return cmd.callback(*posargs, **kwargs)
+
+def launch(mod: ModuleType | str, name: str | None = None) -> int:
+
+    cmd, posargs, kwargs = parse(convert(mod, name=name))
+
+    if cmd.callback is None:
+        print('Command could not be executed. Perhaps you specified the wrong arguments?')
+        return 1
+
+    # Call the function in user-space
+    return cmd.callback(*posargs, **kwargs)

turbolaunch-0.1.0/src/turbolaunch/constants.py

@@ -0,0 +1,6 @@
+
+TRUE_MEMBER_NAME = '_true'
+
+FALSE_MEMBER_NAME = '_false'
+
+DEFAULT_MEMBER_NAME = '_default'

turbolaunch-0.1.0/src/turbolaunch/convert.py

@@ -0,0 +1,237 @@
+
+import inspect
+from pathlib import Path
+import sys
+from types import ModuleType
+import typing
+
+from turbolaunch.constants import FALSE_MEMBER_NAME, TRUE_MEMBER_NAME
+from turbolaunch.types import describe_type
+
+from .program import *
+from .util import IndentWriter, ident, is_boolish, to_kebab_case
+
+def _inserter(name: str) -> ArgFn:
+    def func(key: str, value: Any, out: ArgValues) -> None:
+        if name not in out:
+            m = {}
+            out[name] = m
+        else:
+            m = out[name]
+        m[key] = value
+    return func
+
+def _append(name: str, value: Any, out: ArgValues) -> None:
+    if not name in out:
+        out[name] = []
+    out[name].append(value)
+
+def _print_help_loop(cmd: Command, out: IndentWriter, depth: int) -> None:
+    out.write(f'{cmd.name}')
+    if cmd.description is not None:
+        out.write('    ')
+        out.write(cmd.description)
+    out.writeln()
+    out.indent()
+    if cmd.count_arguments() > 0 and depth == 0:
+        out.writeln('Arguments and flags:')
+        for arg in cmd.arguments():
+            if arg.is_flag:
+                if len(arg.name) == 1:
+                    out.write(f'-{arg.name}')
+                else:
+                    out.write(f'--{arg.name}')
+            elif arg.min_count == 0:
+                if arg.max_count == 1:
+                    out.write(f'[{arg.name}]')
+                else:
+                    out.write(f'[{arg.name}..]')
+            else:
+                if arg.max_count == 1:
+                    out.write(f'<{arg.name}>')
+                else:
+                    out.write(f'<{arg.name}..>')
+            out.write('    ')
+            out.write(describe_type(arg.ty))
+            out.writeln()
+    if cmd.count_subcommands() > 0:
+        out.writeln('\nSubcommands:')
+        out.indent()
+        for sub in cmd.subcommands():
+            _print_help_loop(sub, out, depth+1)
+        out.dedent()
+    out.dedent()
+
+def _print_help(cmd: Command) -> None:
+    out = IndentWriter(sys.stderr)
+    _print_help_loop(cmd, out, 0)
+    exit(1)
+
+def convert_command(proc, name: str | None = None):
+
+    sig = inspect.signature(proc)
+
+    cmd = Command(to_kebab_case(name or proc.__name__))
+
+    types = typing.get_type_hints(proc)
+
+    for name, param in sig.parameters.items():
+
+        ty = types[param.name]
+
+        arg = Argument(name)
+
+        arg.set_type(ty)
+
+        if param.default is not param.empty:
+            arg.set_default(param.default)
+            arg.set_optional()
+
+        if param.kind == param.POSITIONAL_ONLY or param.kind == param.POSITIONAL_OR_KEYWORD or param.kind == param.VAR_POSITIONAL:
+            arg.set_positional()
+        if param.kind == param.KEYWORD_ONLY or param.kind == param.POSITIONAL_OR_KEYWORD or param.kind == param.VAR_KEYWORD:
+            arg.set_flag()
+
+        if param.kind == param.VAR_KEYWORD:
+            if typing.get_origin(ty) is typing.Unpack:
+                args = typing.get_args(ty)
+                total = args[0].__total__
+                for k, v in typing.get_type_hints(args[0]).items():
+                    arg = Argument(k)
+                    arg.set_flag()
+                    required = True
+                    if typing.get_origin(v) is typing.NotRequired:
+                        required = False
+                        v = typing.get_args(v)[0]
+                    arg.set_type(v)
+                    if not total or not required:
+                        arg.set_optional()
+                    cmd.add_argument(arg)
+                continue
+            else:
+                arg.set_rest()
+                arg.set_callback(_inserter(name))
+        if param.kind == param.VAR_POSITIONAL:
+            arg.set_rest()
+            arg.set_no_max_count()
+            arg.set_callback(_append)
+
+        cmd.add_argument(arg)
+
+    cmd.set_callback(proc)
+
+    help_arg = Argument('help')
+    help_arg.set_flag()
+    help_arg.set_type(bool)
+    help_arg.set_callback(lambda key, value, out, cmd=cmd: _print_help(cmd))
+    cmd.add_argument(help_arg)
+
+    return cmd
+
+def convert(mod: ModuleType | str, name: str | None = None) -> Program:
+
+    if name is None:
+        name = Path(sys.argv[0]).stem
+
+    if isinstance(mod, str):
+        import importlib
+        mod = importlib.import_module(mod)
+
+    prog = Program(name)
+
+    for name, proc in mod.__dict__.items():
+        if not name.startswith('_') and callable(proc) and proc.__module__ == mod.__name__:
+            prog.add_subcommand(convert_command(proc))
+
+    help_arg = Argument('help')
+    help_arg.set_flag()
+    help_arg.set_type(bool)
+    help_arg.set_callback(lambda key, value, out: _print_help(prog))
+    prog.add_argument(help_arg)
+
+    add_complements(prog)
+
+    return prog
+
+def _boolish_setter(map: Callable[[Any], bool], name: str, inverted: bool = False) -> ArgFn:
+    def func(_: str, value: Any, out: ArgValues) -> None:
+        out[name] = map(value != inverted)
+    return func
+
+def _bool_to_boolish_fn(ty: Any) -> Callable[[Any], bool]:
+    if ty is bool:
+        return ident
+    if hasattr(ty, TRUE_MEMBER_NAME) and hasattr(ty, FALSE_MEMBER_NAME):
+        return lambda x: getattr(ty, TRUE_MEMBER_NAME) if x else getattr(ty, FALSE_MEMBER_NAME)
+    raise ValueError(f'{ty} is not a valid boolean-like type')
+
+def add_complements(prog: Program) -> None:
+    """
+    Generates additional arguments that are the inverse of existing arguments.
+
+    Example: `--enable-foo` will ackquire `--disable-foo` and both will work.
+
+    Two additional flags can also be enabled that enable/disable all flags at once.
+
+    Example: `--enable-all` and `--disable-all`
+    """
+
+    def visit(cmd: Command) -> None:
+
+        enable_flags = list[tuple[str, Callable[[Any], bool]]]()
+        disable_flags = list[tuple[str, Callable[[Any], bool]]]()
+
+        for arg in list(cmd.arguments()):
+            if not arg.is_rest and is_boolish(arg.ty):
+                if arg.name.startswith('enable_'):
+                    suffix = arg.name[7:]
+                    map = _bool_to_boolish_fn(arg.ty)
+                    enable_flags.append((arg.name, map))
+                    arg.set_callback(_boolish_setter(map, arg.name))
+                    inv_arg = Argument('disable_' + suffix)
+                    inv_arg.set_callback(_boolish_setter(map, arg.name, inverted=True))
+                    inv_arg.set_optional()
+                    inv_arg.set_type(arg.ty)
+                    inv_arg.set_flag()
+                    cmd.add_argument(inv_arg)
+                elif arg.name.startswith('disable_'):
+                    suffix = arg.name[8:]
+                    map = _bool_to_boolish_fn(arg.ty)
+                    disable_flags.append((arg.name, map))
+                    arg.set_callback(_boolish_setter(map, arg.name))
+                    inv_arg = Argument('enable_' + suffix)
+                    inv_arg.set_optional()
+                    inv_arg.set_flag()
+                    inv_arg.set_type(arg.ty)
+                    inv_arg.set_callback(_boolish_setter(map, arg.name, inverted=True))
+                    cmd.add_argument(inv_arg)
+
+        if enable_flags or disable_flags:
+            enable_all = Argument('enable_all')
+            enable_all.set_flag()
+            enable_all.set_optional()
+            enable_all.set_type(bool)
+            def enable_all_cb(_: str, value: bool, out: ArgValues) -> None:
+                for name, map in enable_flags:
+                    out[name] = map(value)
+                for name, map in disable_flags:
+                    out[name] = map(not value)
+            enable_all.set_callback(enable_all_cb)
+            cmd.add_argument(enable_all)
+            disable_all = Argument('disable_all')
+            disable_all.set_flag()
+            disable_all.set_optional()
+            disable_all.set_type(bool)
+            def disble_all_cb(_: str, value: bool, out: ArgValues) -> None:
+                for name, map in enable_flags:
+                    out[name] = map(not value)
+                for name, map in disable_flags:
+                    out[name] = map(value)
+            disable_all.set_callback(disble_all_cb)
+            cmd.add_argument(disable_all)
+
+        for subcmd in cmd.subcommands():
+            visit(subcmd)
+
+    visit(prog)
+

turbolaunch-0.1.0/src/turbolaunch/parse.py

@@ -0,0 +1,225 @@
+"""
+Convert a list of arguments to a function that is ready to be invoked
+"""
+from enum import Enum, IntEnum, StrEnum
+from collections.abc import Iterable
+from pathlib import Path
+import sys
+from types import UnionType
+from typing import Any, Literal, TypeAliasType
+import typing
+
+from turbolaunch.constants import DEFAULT_MEMBER_NAME
+
+from .program import ArgValues, Command, Program
+from .types import get_cls, has_type
+from .util import Peek, find, is_boolish, to_snake_case
+
+class CLIError(RuntimeError):
+    pass
+
+class ValueParseError(CLIError):
+
+    def __init__(self, text: str) -> None:
+        super().__init__(f"failed to parse {repr(text)} as a value")
+
+class ValueMissingError(CLIError):
+
+    def __init__(self, name: str) -> None:
+        super().__init__(f"value missing for argument '{name}'")
+
+class UnknownArgError(CLIError):
+
+    def __init__(self, arg: str) -> None:
+        super().__init__(f"unknown argument received: '{arg}'")
+
+def _try_parse_value(text: str, types: Iterable[Any]) -> Any:
+    for ty_2 in types:
+        try:
+            return _parse_value(text, ty_2)
+        except ValueParseError:
+            pass
+    raise ValueParseError(f'unable to parse as any of {types}')
+
+def _parse_value(text: str, ty: Any) -> Any:
+    if isinstance(ty, TypeAliasType):
+        assert(not ty.__type_params__)
+        ty = ty.__value__
+    origin = typing.get_origin(ty)
+    if origin is UnionType or origin is typing.Union:
+        args = typing.get_args(ty)
+        return _try_parse_value(text, args)
+    if origin is Literal:
+        args = typing.get_args(ty)
+        for arg in args:
+            try:
+                value = _parse_value(text, get_cls(arg))
+            except ValueParseError:
+                continue
+            if value != arg:
+                return value
+        raise ValueParseError(f"no literal types matched")
+    if ty is Path:
+        return Path(text)
+    if ty is float:
+        try:
+            return float(text)
+        except ValueError:
+            raise ValueParseError(text)
+    if ty is str:
+        return text
+    if ty is Any:
+        return _try_parse_value(text, [ bool, int, float, str ])
+    if ty is bool:
+        if text in [ 'on', 'true', '1' ]:
+            return True
+        if text in [ 'off', 'false', '0' ]:
+            return False
+        raise ValueParseError(text)
+    if ty is int:
+        try:
+            return int(text)
+        except ValueError:
+            raise ValueParseError(text)
+    if issubclass(ty, StrEnum):
+        try:
+            return ty(text)
+        except ValueError:
+            raise ValueParseError(text)
+    if issubclass(ty, IntEnum):
+        try:
+            return ty(int(text)) # type: ignore
+        except ValueError:
+            raise ValueParseError(text)
+    raise RuntimeError(f'parsing the given value according to {ty} is not supported')
+
+def _get_type_default(ty: Any) -> Any:
+    if isinstance(ty, Enum):
+        if hasattr(ty, DEFAULT_MEMBER_NAME):
+            return getattr(ty, DEFAULT_MEMBER_NAME)
+
+def parse(prog: Program, argv: list[str] | None = None) -> tuple[Command, list[Any], dict[str, Any]]:
+
+    if argv is None:
+        argv = sys.argv[1:]
+
+    # Variables used during processing of the arguments
+    cmd = prog
+    args = Peek(argv)
+    mapping: ArgValues = {}
+    pos_index = 0
+    pos_arg_count = 0
+
+    # Process arguments one by one
+    while True:
+
+        arg = args.get()
+
+        if arg is None:
+            break # We're at the end of the arguments list
+
+        if arg.startswith('-'): # We're dealing with a flag
+
+            i = find(arg, lambda ch: ch != '-')
+
+            if i is None:
+                raise UnknownArgError(arg)
+
+            try:
+                j = arg.index('=', i)
+                name = to_snake_case(arg[i:j])
+                value_str = arg[j+1:]
+            except ValueError:
+                name = to_snake_case(arg[i:])
+                value_str = None
+
+            arg_desc = cmd.get_flag(name)
+
+            if arg_desc is None:
+                arg_desc = cmd.rest_flags_argument
+                if arg_desc is None:
+                    raise UnknownArgError(arg)
+
+            ty = arg_desc.ty
+
+            value = None
+
+            if value_str is not None:
+                value = _parse_value(value_str, ty)
+            else:
+                # `value` is still `None` here
+                next_arg = args.peek()
+                if next_arg is not None and not next_arg.startswith('-'):
+                    try:
+                        value = _parse_value(next_arg, ty)
+                        args.get()
+                    except ValueParseError:
+                        pass # `value` remains `None` and lookahead is discarded
+
+            if value is None:
+                if is_boolish(arg_desc.ty) or arg_desc.is_rest_flags:
+                    # Assume `True` in the cases where a boolean-like value is
+                    # expected or when it could potentially be a boolean but we
+                    # don't know for sure
+                    value = True
+                elif arg_desc.default is not None:
+                    # For all types except bool, attempt to assign the default
+                    # value of the flag.
+                    value = arg_desc.default
+                else:
+                    # If the user didn't explicitly specify a default, maybe we
+                    # can derive a default from the type.
+                    default = _get_type_default(arg_desc.ty)
+                    if default is not None:
+                        value = default
+                    elif arg_desc.min_count > 0: # If the flag was required
+                        raise ValueMissingError(name)
+
+            arg_desc.parse_callback(name, value, mapping)
+
+        else: # We're dealing with a positional argument
+
+            # Try to parse the argument as a subcommand first
+            subcmd = cmd.get_subcommand(arg)
+            if subcmd is not None:
+                cmd = subcmd
+                pos_index = 0
+                pos_arg_count = 0
+                continue
+
+            # If that fails, process it as a plain positional argument
+
+            while True:
+                if pos_index >= len(cmd._pos_args):
+                    raise UnknownArgError(arg)
+                arg_desc = cmd._pos_args[pos_index]
+                if pos_arg_count >= arg_desc.max_count:
+                    pos_index += 1
+                    pos_arg_count = 0
+                    continue
+                value = _parse_value(arg, arg_desc.ty)
+                arg_desc.parse_callback(arg_desc.name, value, mapping)
+                pos_arg_count += 1
+                break
+
+    # TODO check that required arguments have been set
+
+    # Build positional arguments and keyword arguments from the mapping
+    posargs = []
+    kwargs = {}
+    for name, value in mapping.items():
+        arg_desc = cmd.get_argument(name)
+        assert(arg_desc is not None)
+        if arg_desc.is_positional:
+            if arg_desc.is_rest_pos:
+                posargs.extend(value)
+            else:
+                posargs.append(value)
+        else:
+            if arg_desc.is_rest_flags:
+                kwargs.update(value)
+            else:
+                kwargs[name] = value
+
+    return cmd, posargs, kwargs
+

turbolaunch-0.1.0/src/turbolaunch/program.py

@@ -0,0 +1,158 @@
+
+from collections.abc import Callable, Iterable
+from typing import Any
+import math
+
+type ArgValue = Any
+
+type ArgValues = dict[str, ArgValue]
+
+type ArgFn = Callable[[str, ArgValue, ArgValues], None]
+
+ARGFLAGS_FLAG = 1
+ARGFLAGS_POSITIONAL = 2
+ARGFLAGS_REST = 4
+
+def _set_arg_value(name: str, value: Any, out: ArgValues) -> None:
+    out[name] = value
+
+def _are_bits_set(mask: int, bit: int) -> bool:
+    return mask & bit == bit
+
+def _set_bit(mask: int, bit: int, enable: bool) -> int:
+    if enable:
+        return mask | bit
+    else:
+        return mask & ~bit
+
+class Argument:
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+        self.flags = 0
+        self.ty: Any = None
+        self.min_count = 1
+        self.max_count = 1
+        self.default: ArgValue | None = None
+        self.parse_callback: ArgFn = _set_arg_value
+
+    @property
+    def is_positional(self) -> bool:
+        return (self.flags & ARGFLAGS_POSITIONAL) > 0
+
+    @property
+    def is_flag(self) -> bool:
+        return (self.flags & ARGFLAGS_FLAG) > 0
+
+    @property
+    def is_rest(self) -> bool:
+        return _are_bits_set(self.flags, ARGFLAGS_REST)
+
+    @property
+    def is_rest_flags(self) -> bool:
+        return _are_bits_set(self.flags, ARGFLAGS_FLAG | ARGFLAGS_REST)
+
+    @property
+    def is_rest_pos(self) -> bool:
+        return _are_bits_set(self.flags, ARGFLAGS_POSITIONAL | ARGFLAGS_REST)
+
+    @property
+    def is_optional(self) -> bool:
+        return self.min_count == 0
+
+    def set_flag(self, enable = True) -> None:
+        self.flags = _set_bit(self.flags, ARGFLAGS_FLAG, enable)
+
+    def set_rest(self, enable = True) -> None:
+        self.flags = _set_bit(self.flags, ARGFLAGS_REST, enable)
+
+    def set_positional(self, enable = True) -> None:
+        self.flags = _set_bit(self.flags, ARGFLAGS_POSITIONAL, enable)
+
+    def set_default(self, value: ArgValue) -> None:
+        self.default = value
+
+    def set_no_max_count(self) -> None:
+        self.max_count = math.inf
+
+    def set_type(self, ty: Any) -> None:
+        self.ty = ty
+
+    def set_optional(self) -> None:
+        self.min_count = 0
+
+    def set_required(self) -> None:
+        if self.min_count == 0:
+            self.min_count = 1
+
+    def set_callback(self, cb: ArgFn) -> None:
+        self.parse_callback = cb
+
+class Command:
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+        self.description: str | None = None
+        self.callback: Callable[..., int] | None = None
+        self._subcommands = dict[str, Command]()
+        self._arguments = dict[str, Argument]()
+        self._pos_args: list[Argument] = []
+        self._rest_flags_argument = None
+        # self._arguments_by_flag = dict[str, Argument]()
+
+    def arguments(self) -> Iterable[Argument]:
+        return self._arguments.values()
+
+    def subcommands(self) -> 'Iterable[Command]':
+        return self._subcommands.values()
+
+    def add_subcommand(self, cmd: 'Command') -> None:
+        """
+        Add a subcommand to this command.
+
+        This class expects the command to not be mutated anymore after it has been added.
+        """
+        assert(cmd.name not in self._subcommands)
+        self._subcommands[cmd.name] = cmd
+
+    def count_arguments(self) -> int:
+        return len(self._arguments)
+
+    def add_argument(self, arg: Argument) -> None:
+        """
+        Add an argument to this command.
+
+        This class expects the argument to not be mutated anymore after it has been added.
+        """
+        assert(arg.name not in self._arguments)
+        self._arguments[arg.name] = arg
+        if arg.is_positional:
+            self._pos_args.append(arg)
+        if arg.is_rest_flags:
+            assert(self._rest_flags_argument is None)
+            self._rest_flags_argument = arg
+
+    @property
+    def rest_flags_argument(self) -> Argument | None:
+        return self._rest_flags_argument
+
+    def set_callback(self, callback: Callable[..., Any]) -> None:
+        self.callback = callback
+
+    def get_argument(self, name: str) -> Argument | None:
+        return self._arguments.get(name)
+
+    def count_subcommands(self) -> int:
+        return len(self._subcommands)
+
+    def get_flag(self, name: str) -> Argument | None:
+        arg = self.get_argument(name)
+        if arg is not None and arg.is_flag:
+            return arg
+
+    def get_subcommand(self, name: str) -> 'Command | None':
+        return self._subcommands.get(name)
+
+class Program(Command):
+    pass
+

turbolaunch-0.1.0/src/turbolaunch/test_all.py

@@ -0,0 +1,25 @@
+
+import pytest
+from turbolaunch import App
+
+def test_simple_arg():
+    app = App('myprog')
+    _bla = None
+    @app.command()
+    def foo(bla: str) -> None:
+        nonlocal _bla
+        _bla = bla
+    app([ 'myprog', 'foo', 'hello' ])
+    assert(_bla == 'hello')
+
+def test_simple_arg_2():
+    app = App('myprog')
+    _bla = None
+    @app.command(name='bar')
+    def foo(bla: str) -> None:
+        nonlocal _bla
+        _bla = bla
+    with pytest.raises(RuntimeError):
+        app([ 'myprog', 'foo', 'hello' ])
+    app([ 'myprog', 'bar', 'hello' ])
+    assert(_bla == 'hello')

turbolaunch-0.1.0/src/turbolaunch/types.py

@@ -0,0 +1,62 @@
+
+from collections.abc import Generator
+import types
+import typing
+from typing import Any, Union
+
+
+def describe_type(ty: Any) -> str:
+    if type(ty) is typing.TypeAliasType:
+        return describe_type(ty.__value__)
+    origin = typing.get_origin(ty)
+    if origin is None:
+        return ty.__name__
+    elif origin is typing.Union or origin is types.UnionType:
+        return ' | '.join(describe_type(arg) for arg in typing.get_args(ty))
+    elif origin is typing.Literal:
+        return ' | '.join(repr(lit) for lit in typing.get_args(ty))
+    else:
+        raise NotImplementedError(f"{ty} cannot be printed yet")
+
+
+def is_optional(ty: Any) -> bool:
+    origin = typing.get_origin(ty)
+    if origin is types.UnionType:
+        args = typing.get_args(ty)
+        for arg in args:
+            if arg is None:
+                return True
+    return False
+
+
+def unwrap_optional(ty: Any) -> Any:
+    origin = typing.get_origin(ty)
+    if origin is types.UnionType:
+        args = typing.get_args(ty)
+        return Union[*(arg for arg in args if arg is not None)]
+    return ty
+
+
+def get_cls(value: Any) -> Any:
+    return value.__class__
+
+
+def flatten_union_type(ty: Any) -> Generator[Any]:
+    origin = typing.get_origin(ty)
+    if origin is typing.Union or origin is types.UnionType:
+        for arg in typing.get_args(ty):
+            yield from flatten_union_type(arg)
+    else:
+        yield ty
+
+
+def has_type(left: Any, right: Any) -> bool:
+    """
+    Check whether `right` occurs somewhere in `left`.
+
+    For instance:
+    has_type(int | bool | str, bool) == True
+    has_type(int | bool | str, float) == False
+    """
+    return right in flatten_union_type(left)
+

turbolaunch-0.1.0/src/turbolaunch/util.py

@@ -0,0 +1,83 @@
+
+from collections.abc import Callable, Iterable, Sequence
+import re
+from typing import Any, Generic, TextIO, TypeVar
+from io import StringIO
+
+from turbolaunch.constants import FALSE_MEMBER_NAME, TRUE_MEMBER_NAME
+
+def to_kebab_case(name: str) -> str:
+    return name.replace('_', '-')
+
+
+def to_snake_case(name: str) -> str:
+    return name.replace('-', '_')
+
+
+_T = TypeVar('_T')
+
+
+class Peek(Generic[_T]):
+
+    def __init__(self, iter: Iterable[_T]) -> None:
+        self._elements = list(iter)
+        self._offset = 0
+
+    def get(self) -> _T | None:
+        if self._offset >= len(self._elements):
+            return None
+        element = self._elements[self._offset]
+        self._offset += 1
+        return element
+
+    def peek(self) -> _T | None:
+        return self._elements[self._offset] if self._offset < len(self._elements) else None
+
+
+def find(l: Sequence[_T], pred: Callable[[_T], bool]) -> int | None:
+    for i, element in enumerate(l):
+        if pred(element):
+            return i
+
+
+class IndentWriter:
+
+    def __init__(self, out: TextIO | None = None, indentation='  '):
+        if out is None:
+            out = StringIO()
+        self.output = out
+        self.at_blank_line = True
+        self.newline_count = 0
+        self.indent_level = 0
+        self.indentation = indentation
+        self._re_whitespace = re.compile('[\n\r\t ]')
+
+    def indent(self):
+        self.indent_level += 1
+
+    def dedent(self):
+        self.indent_level -= 1
+
+    def ensure_trailing_lines(self, count):
+        self.write('\n' * max(0, count - self.newline_count))
+
+    def write(self, text: str) -> None:
+        for ch in text:
+            if ch == '\n':
+                self.newline_count = self.newline_count + 1 if self.at_blank_line else 1
+                self.at_blank_line = True
+            elif self.at_blank_line and not self._re_whitespace.match(ch):
+                self.newline_count = 0
+                self.output.write(self.indentation * self.indent_level)
+                self.at_blank_line = False
+            self.output.write(ch)
+
+    def writeln(self, text: str = '') -> None:
+        self.write(text)
+        self.write('\n')
+
+def ident(value: _T) -> _T:
+    return value
+
+def is_boolish(ty: Any) -> bool:
+    return ty is bool or (hasattr(ty, TRUE_MEMBER_NAME) and hasattr(ty, FALSE_MEMBER_NAME))

turbolaunch-0.1.0/src/turbolaunch.egg-info/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: turbolaunch
+Version: 0.1.0
+Summary: The definitive command-line arguments parser
+Author-email: Sam Vervaeck <samvv@pm.me>
+Maintainer-email: Sam Vervaeck <samvv@pm.me>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/samvv/turbolaunch
+Project-URL: Bug Reports, https://github.com/samvv/turbolaunch/issues
+Project-URL: Source, https://github.com/samvv/turbolaunch/
+Keywords: cli,argparse,library
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Provides-Extra: dev
+Requires-Dist: check-manifest; extra == "dev"
+Provides-Extra: test
+Requires-Dist: coverage; extra == "test"
+Dynamic: license-file
+
+TurboLaunch
+===========
+
+TurboLaunch is a CLI parser for Python programs that requires almost no setup.
+
+ - ✅ Run Python functions directly as CLI commands
+ - ✅ Support for enums and other built-in types
+ - 🚧 Help messages derived from docstrings
+ - 🚧 Plugins to extend the functionality of this library
+ - 🚧 Fuzzing of as much code paths as possible to ensure quality
+
+TurboLaunch was initially written as part of the [Mage project](https://github.com/samvv/mage).
+
+## Quick Start
+
+Simply create or edit a module with the following code:
+
+```py
+def main() -> int:
+    import turbolaunch
+    turbolaunch.launch(__name__)
+```
+
+In your `pyproject.toml`-file, you'd have something like this:
+
+```toml
+[project.scripts]
+mycommand = "mylibrary:main"
+```
+
+That's it!
+
+Now if you would like to have command `test` which e.g. takes a filename and an optional `foo` flag:
+
+```py
+def test(filename: str, foo: bool = False) -> int:
+    if foo:
+        print("'foo' is enabled")
+    print(f"Reading {filename}")
+    return 0
+```
+
+The above code would be run like this:
+
+```
+mycommand test loremipsum.txt --foo
+```
+
+More options, such as programmatic usage and plugins will come soon.
+
+## License
+
+This software is licensed under the MIT license.

turbolaunch-0.1.0/src/turbolaunch.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE.txt
+README.md
+pyproject.toml
+src/turbolaunch/__init__.py
+src/turbolaunch/constants.py
+src/turbolaunch/convert.py
+src/turbolaunch/parse.py
+src/turbolaunch/program.py
+src/turbolaunch/test_all.py
+src/turbolaunch/types.py
+src/turbolaunch/util.py
+src/turbolaunch.egg-info/PKG-INFO
+src/turbolaunch.egg-info/SOURCES.txt
+src/turbolaunch.egg-info/dependency_links.txt
+src/turbolaunch.egg-info/requires.txt
+src/turbolaunch.egg-info/top_level.txt

turbolaunch-0.1.0/src/turbolaunch.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

turbolaunch-0.1.0/src/turbolaunch.egg-info/requires.txt

@@ -0,0 +1,6 @@
+
+[dev]
+check-manifest
+
+[test]
+coverage

turbolaunch-0.1.0/src/turbolaunch.egg-info/top_level.txt

@@ -0,0 +1 @@
+turbolaunch