{"id":17132113,"url":"https://github.com/perdy/clinner","last_synced_at":"2025-04-13T07:55:54.592Z","repository":{"id":62562686,"uuid":"83491566","full_name":"perdy/clinner","owner":"perdy","description":"Command Line Interface builder that helps creating an entry point for your application.","archived":false,"fork":false,"pushed_at":"2022-03-09T22:29:07.000Z","size":183,"stargazers_count":8,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-26T23:51:11.434Z","etag":null,"topics":["cli","command","command-line","command-line-tool","main"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/perdy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-03-01T00:00:21.000Z","updated_at":"2022-03-09T21:50:12.000Z","dependencies_parsed_at":"2022-11-03T15:30:49.375Z","dependency_job_id":null,"html_url":"https://github.com/perdy/clinner","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perdy%2Fclinner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perdy%2Fclinner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perdy%2Fclinner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perdy%2Fclinner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/perdy","download_url":"https://codeload.github.com/perdy/clinner/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248378987,"owners_count":21094091,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","command","command-line","command-line-tool","main"],"created_at":"2024-10-14T19:26:04.080Z","updated_at":"2025-04-13T07:55:54.566Z","avatar_url":"https://github.com/perdy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Clinner\n[![Build Status](https://travis-ci.org/PeRDy/clinner.svg?branch=master)](https://travis-ci.org/PeRDy/clinner)\n[![codecov](https://codecov.io/gh/PeRDy/clinner/branch/master/graph/badge.svg)](https://codecov.io/gh/PeRDy/clinner)\n[![PyPI version](https://badge.fury.io/py/clinner.svg)](https://badge.fury.io/py/clinner)\n\n* **Version:** 1.12.3\n* **Status:** Production/Stable\n* **Author:** José Antonio Perdiguero López\n\nClinner is a library that provides some useful tools to create command line interfaces for your application\n\nCheck [Clinner docs].\n\n## Features\nCan **define commands** in multiple way:\n* List of shell commands such as `[\"docker build\", \"docker push\"]`.\n* Python functions.\n* Python async functions.\n\nClinner provides a set of **commands ready to use** like:\n* Black.\n* Flake8.\n* Isort.\n* Nosetest.\n* Prospector.\n* Pytest.\n* Sphinx.\n* Tox.\n\nHooks for **injecting variables** or **add global arguments** to your script.\n\n## Quick start\nInstall this package using pip:\n\n```bash\npip install clinner\n```\n\nCreate a command\n\n```python\nfrom clinner.command import command\n\n@command\ndef foo(*args, **kwargs):\n    return True\n```\n\nCreate a main file:\n\n```python\nfrom clinner.run.main import Main\n\nif __name__ == '__main__':\n    sys.exit(Main().run())\n```\n\n## Commands\nCommands are declared using a decorator to register given functions. Commands are functions with the follow parameters:\n\n1. `func`: Function that will be called when command would be executed.\n2. `command_type`: Type of the command, could be a *bash* or *python* command.\n3. `args`: Parser arguments for this command.\n4. `parser_opts`: Command subparser's keywords, such as description.\n\nThis decorator allows to be used as a common decorator without arguments, where default type (*python*) will be used:\n\n```python\n@command\ndef foobar(*args, **kwargs):\n    pass\n```\n\nOr specifying the type:\n\n```python\n@command(command_type=CommandType.PYTHON)\ndef foobar(*args, **kwargs):\n    pass\n```\n\nBut also is possible to provide command line arguments, as expected by argparse.ArgumentParser.add_argument:\n\n```python\n@command(args=((('-f', '--foo'), {'help': 'Foo argument that does nothing'}),                   # Command argument\n               (('--bar',), {'action': 'store_true', 'help': 'Bar argument stored as True'})),  # Another argument\n         parser_opts={'title': 'foobar_command', 'help': 'Help for foobar_command'})            # Parser parameters\ndef foobar(*args, **kwargs):\n    pass\n```\n\nAll commands will be registered in a command register that can be accessed through ``command.register``. Each entry in\nthis register is a dictionary with the fields declared at the beginning of this section.\n\n### Shell command\nExample of running `ls -la` shell command.\n\n```python\n@command(command_type=CommandType.SHELL)\ndef lsla(*args, **kwargs):\n    return [shlex.split(\"ls -la\")]\n```\n\n### Python function\nRun a python function.\n\n```python\n@command\ndef foo(*args, **kwargs):\n    return \"foo\"\n```\n\n### Python async function\nRun a python async function.\n\n```python\n@command\nasync def bar(*args, **kwargs):\n    await asyncio.sleep(1)\n    return \"bar\"\n```\n\n## Main\nA main class is defined to ease the creation of command line applications. This class follows the process:\n\n1. Create a parser using ``argparse.ArgumentParser`` for the application:\n    \n    a) Calling all ``add_arguments(parser)`` methods from all super classes, e.g: ``clinner.mixins.HealthCheckMixin``.\n    \n    b) Addding a subparser for each command with their specific arguments.\n\n2. Parse arguments using the argument parser created previously.\n\n3. Inject variables into environment calling all super classes methods whose name starts with ``inject_``.\n\n## Examples\nSome Clinner examples.\n\n### Simple Main\nExample of a simple main with two defined commands `foo` and `bar`.\n\n```python\n#!/usr/bin/env python\nimport shlex\nimport sys\n\nfrom clinner.command import command, Type as CommandType\nfrom clinner.run.main import Main\n\n\n@command(command_type=CommandType.SHELL,\n         args=(('-i', '--input'),\n               ('-o', '--output')),\n         parser_opts={'help': 'Foo command'})\ndef foo(*args, **kwargs):\n    \"\"\"List of foo commands\"\"\"\n    ls_cmd = shlex.split('ls')\n    wc_cmd = shlex.split('wc')\n    wc_cmd += [kwargs['input'], kwargs['output']]\n\n    return [ls_cmd, wc_cmd]\n\n\n@command(command_type=CommandType.PYTHON,\n         parser_opts={'help': 'Bar command'})\ndef bar(*args, **kwargs):\n    \"\"\"Do a bar.\"\"\"\n    return True\n\n\nif __name__ == '__main__':\n    sys.exit(Main().run())\n```\n\n### Builder Main\nExample of main module with build utilities such as unit tests, lint, sphinx doc, tox and dist packaging:\n\n```python\n#!/usr/bin/env python\nimport sys\n\nfrom clinner.run import Main\n\n\nclass Build(Main):\n    commands = (\n        'clinner.run.commands.black.black',\n        'clinner.run.commands.flake8.flake8',\n        'clinner.run.commands.isort.isort',\n        'clinner.run.commands.pytest.pytest',\n        'clinner.run.commands.sphinx.sphinx',\n        'clinner.run.commands.tox.tox',\n    )\n\n\nif __name__ == '__main__':\n    sys.exit(Build().run())\n```\n\nCheck [Clinner docs] to see more advanced examples.\n\n[Clinner docs]: http://clinner.readthedocs.io\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperdy%2Fclinner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fperdy%2Fclinner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperdy%2Fclinner/lists"}