{ "info": { "author": "Stepan Anokhin", "author_email": "stepan.anokhin@gmail.com", "bugtrack_url": null, "classifiers": [ "Intended Audience :: Developers", "Intended Audience :: System Administrators", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", "Programming Language :: Python", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3.4", "Programming Language :: Python :: 3.5", "Programming Language :: Python :: 3.6", "Programming Language :: Python :: 3.7", "Topic :: Software Development :: Libraries" ], "description": "\n

\n \"Comandante\n

\n\nComandante is a toolkit for building command-line interfaces in Python.\n\n[![Build Status](https://travis-ci.org/stepan-anokhin/comandante.svg?branch=master)](https://travis-ci.org/stepan-anokhin/comandante)\n[![Coverage Status](https://coveralls.io/repos/github/stepan-anokhin/comandante/badge.svg?branch=master)](https://coveralls.io/github/stepan-anokhin/comandante?branch=master)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/stepan-anokhin/comandante/blob/master/LICENSE)\n\n## Table of Contents\n- [Installation](#installation)\n- [Getting Started](#getting-started)\n - [Example](#Example)\n - [Just a Normal Classes and Methods!](#just-a-normal-classes-and-methods)\n- [Options](#options)\n - [Command Options](#command-options)\n - [Class Options](#class-options)\n- [Subcommands](#subcommands)\n- [Arguments](#arguments)\n - [Type Library](#type-library)\n - [Python 2](#python-2)\n- [Printing Help](#printing-help)\n- [Error Handling](#error-handling)\n- [Testing Your CLI](#testing-your-cli)\n\n## Installation\n\nTo get the latest release simply install it with a `pip`:\n\n```shell\npip3 install --upgrade comandante\n```\n\n## Getting Started\n\nSome command-line interfaces (like `pip`, `git`, `go`, etc.) \nhave a rich hierarchy of subcommands. Each subcommand may have\nits own set of arguments and options. Consider for example \n`git commit`, `git remote add `, `git remote rename `\netc. *Comandante* is a Python library that makes building\nrich command-line interfaces (CLI) in Python extremely simple \nand straightforward. \n\n### Example\nHere is a simple example:\n```python\n#!/usr/bin/env python3\nimport sys, comandante as cli\n\n# Define a new CLI handler as a `cli.Handler` subclass\nclass CliTool(cli.Handler):\n\n # define CLI commands as methods decorated with `@cli.command()` \n @cli.command()\n def repeat(self, message, times: int):\n for i in range(times):\n print(message)\n\n @cli.command() \n def sum(self, a: int, b: int):\n result = a + b\n print(result)\n return result\n\n# Then simply pass command-line arguments to the CliTool#invoke\nCliTool().invoke(sys.argv[1:])\n```\n\nThat's it! \n\nTo execute `repeat` command simply run `./tool repeat` with its required arguments:\n```shell\n$ ./tool repeat \"Hello world\" 2\nHello world\nHello world\n```\n\nThe same goes for any defined command-methods: \n```shell\n$ ./tool sum 21 21\n42\n```\nSo in other words to create a command-line interface you simply:\n * define a normal Python class (inherited from the `comandante.Handler`)\n * equip your class methods with a minimal amount of metadata (via decorators)\n * call `invoke(sys.argv[1:])` method on your class instance\n * **comandante** will inspect metadata and decide how to parse \n command-line arguments and which method to call. \n\n\n### Just a Normal Classes and Methods\nNo surprises! Handlers and commands are just a normal classes and methods.\n\n## Options\nCommand options are declared with `@comandante.option(...)` decorator. \n\nEach command-method receives options as `**kwargs` parameters (if present). \n\nEach command-method has a convenience method `Command#options(kwargs)` to \nmerge default values with specified command-line options.\n\n### Command Options\n\nExample below demonstrates how to define command option:\n\n```python\n#!/usr/bin/env python3\nimport sys, comandante as cli\n\n\nclass DatabaseCli(cli.Handler):\n\n @cli.option(name='force', short='f', type=bool, default=False)\n @cli.command()\n def drop(self, database_name, **specified_options):\n # merge specified options with default values\n options = self.drop.options(specified_options)\n\n # merged options provides attribute-like element access\n if options.force or self.confirm():\n print(\"Database '{name}' was deleted\".format(name=database_name))\n else: \n print(\"Aborted\")\n\n @staticmethod \n def confirm():\n question = 'Are you sure? [y/N]: '\n value = input(question).lower()\n while value not in ['', 'n', 'y']:\n print(\"Please answer 'y' or 'n'\")\n value = input(question)\n return value == 'y'\n\n\ndatabase_cli = DatabaseCli()\ndatabase_cli.invoke(sys.argv[1:])\n```\nThen in shell:\n```shell\n$ ./database drop production\nAre you sure? [y/N]: y\nDatabase 'production' was deleted\n```\nThe following two examples are identical:\n```shell\n$ ./database drop -f production\nDatabase 'production' was deleted\n```\n```shell\n$ ./database drop --force production\nDatabase 'production' was deleted\n```\n\n### Class Options\n\nOptions could be declared on handler itself with `Handler#declare_option` method. \n\nOptions declared on handler will be declared on each of its command and subcommand recursively. \n```python\n#!/usr/bin/env python3\nimport sys, comandante as cli\n\nclass CliTool(cli.Handler):\n def __init__(self):\n super().__init__()\n\n # define options\n self.declare_option('verbose', 'v', bool, False)\n\n @cli.command()\n def first(self, **specified_options):\n if 'verbose' in specified_options:\n print(\"Hello from the first!\")\n\n @cli.command()\n def second(self, **specified_options):\n if 'verbose' in specified_options:\n print(\"Hello from the second!\")\n\n\ntool = CliTool()\ntool.invoke(sys.argv[1:])\n```\nThen in shell:\n```shell\n$ ./tool first --verbose\nHello from the first!\n```\n```shell\n$ ./tool second -v\nHello from the second!\n```\n\n## Subcommands\n\nAs your CLI becomes more complex and harder to maintain, you might want to \nhave commands that have its own set of commands handled by separate class. \nIn Comandante to compose handlers into hierarchy you may simply \nuse `Handler#declare_command` method. \n\nHere is a simple example:\n```python\n#!/usr/bin/env python3\n\nimport sys, comandante as cli\n\nclass Remote(cli.Handler):\n @cli.command()\n def add(self, name, uri):\n print(\"Adding repository\", name, uri)\n\n @cli.command()\n def rename(self, old, new):\n print(\"Renaming repository\", old, new) \n\nclass Git(cli.Handler):\n def __init__(self):\n super().__init__() \n\n # define subcommands\n self.declare_command(name='remote', handler=Remote())\n\n @cli.option('message', 'm', str, '')\n @cli.command()\n def commit(self, **specified_options):\n options = self.commit.options(specified_options)\n print(\"Committing changes with message '{}'\".format(options.message))\n\ngit = Git()\ngit.invoke(sys.argv[1:])\n```\n\nThen in shell\n```shell\n$ ./git commit -m \"Initial commit\"\nCommitting changes with message 'Initial commit' \n```\n```shell\n$ ./git remote add origin git@github.com:stepan-anokhin/comandante.git\nAdding repository origin git@github.com:stepan-anokhin/comandante.git\n```\n```shell\n$ ./git remote rename origin destination\nRenaming repository origin destination\n```\n## Arguments\n\nIn python3 command argument types are declared using annotations:\n```python\nimport comandante as cli\n\nclass CliTool(cli.Handler):\n\n @cli.command()\n def do_something(self, a: int, b: float, c: str):\n print(a + b, c)\n```\nType could be any callable. This callable will be simply called with \na command-line string as the only argument. A result will be passed\nto the *command-method* as argument. The same is true for option types. \n\nThe only exception is `bool` arguments and options. Bool option doesn't \nreceive any value, if specified it is considered to be `True` otherwise \ndefault value is used. \n\nIf no argument type is specified, then `str` is assumed by default. \nType's `__name__` attribute is used in automatic help output to \nrepresent argument/option type. \n\nComandante honors default argument values and varargs:\n```python\n#!/usr/bin/env python3\nimport sys, comandante as cli\n\nclass CliTool(cli.Handler):\n\n @cli.command()\n def sum(self, *values: int):\n print(sum(values))\n\n @cli.command()\n def repeat(self, message, times: int = 2):\n for i in range(times):\n print(message)\n\nCliTool().invoke(sys.argv[1:])\n```\n```shell\n$ ./tool sum 1 2 3 4 5\n15\n```\n```shell\n$ ./tool repeat \"Hello world!\"\nHello world!\nHello world!\n```\n### Type Library\n\nComandante also provides several higher-order types:\n * `comandante.types.choice` - to make sure argument value is one of the specified options\n * `comandante.types.listof` - to parse comma-separated lists (e.g. `listof(int)` will parse `\"1,2,3,4\"` into `[1, 2, 3, 4]`)\n\nYou may take a look into the\n[comandante.types](https://github.com/stepan-anokhin/comandante/blob/master/comandante/types.py)\nto get some additional insights. \n\n### Python 2\n\nPython 2 doesn't support parameter annotations. \nTo specify argument types use `@comandante.signature()`\n```python\nimport comandante as cli\n\nclass CliTool(cli.Handler):\n\n @cli.signature(a=int, b=float)\n @cli.command()\n def do_something(self, a, b, c):\n print(a + b, c)\n```\n\n## Printing Help\n\nComandante provides predefined `help` command for you which will print\nformatted help information to the stdout. Command and handler descriptions\nare taken from the corresponding docstrings. \n\nExample:\n```python\nimport sys\nimport comandante as cli\n\n\nclass Git(cli.Handler):\n \"\"\"The stupid content tracker.\n\n Git is a fast, scalable, distributed revision control system with\n an unusually *rich command* set that provides both high-level operations\n and full access to internals.\n\n See *gittutorial*(7) to get started, then see *giteveryday*(7) for a useful\n minimum set of commands. The *Git User\u2019s Manual*[1] has a more in-depth\n introduction.\n \"\"\"\n\n @cli.option(name='message', short='m', type=str, default='', descr=\"\"\"\n Use the given as the commit message. If multiple *-m* options are \n given, their values are concatenated as separate paragraphs.\n \"\"\")\n @cli.command()\n def commit(self):\n \"\"\"Record changes to the repository\n\n Create a new commit containing the current contents\n of the index and the given log message describing\n the changes. The new commit is a direct child of HEAD,\n usually the tip of the current branch, and the branch\n is updated to point to it (unless no branch is associated\n with the working tree, in which case HEAD is \"detached\"\n as described in *git-checkout*(1)).\n \"\"\"\n print(\"Committing...\")\n\n @cli.command()\n def clone(self, repository, directory=None):\n \"\"\"Clone a repository into a new directory\n\n Clones a repository into a newly created directory, creates\n remote-tracking branches for each branch in the cloned\n repository (visible using git branch *-r*), and creates and\n checks out an initial branch that is forked from the cloned\n repository\u2019s currently active branch.\n \"\"\"\n print(\"Cloning...\")\n\nGit().invoke(sys.argv[1:])\n``` \n`./git` output:\n

\n \"git\"\n

\n\n`./git help clone` output:\n

\n \"git\n

\n\n`./git help commit` output:\n

\n \"git\n

\n\n\n## Error Handling\n\nSuccessful calls to `Handler#invoke` and `Command#invoke` methods return \nthe same value as the corresponding *command-method*. \n\nBy design Comandante doesn't hide any exceptions raised in the course of \n`invoke` call. The only special case is subclasses of \n`comandnate.errors.CliSyntaxException` which results in help printing \nbefore being re-raised.\n\nSo it is up to the caller to decide how to handle exceptions. \n\nA reasonable error handling may look like this:\n```python\nimport sys, logging, comandante as cli\n\n# ... initialize handler and logger ... \n\ntry: \n handler.invoke(sys.argv[1:])\nexcept cli.errors.CliSyntaxException:\n sys.exit(1)\nexcept:\n logger.exception('Unexpected exception')\n sys.exit(1)\n\n``` \n\n## Testing Your CLI\n\nHandlers and commands could be tested just like \n[any other](#just-a-normal-classes-and-methods) classes and methods. \n\nExample cli:\n```python\nimport comandante as cli\n\n\nclass DatabaseCli(cli.Handler):\n def __init__(self, database):\n super().__init__()\n self._database = database\n\n @cli.option('force', 'f', bool, False)\n @cli.command()\n def drop(self, database_name, **specified_options):\n options = self.drop.options(specified_options)\n if options.force or self.confirm():\n self._database.drop(database_name)\n\n def confirm(self):\n question = 'Are you sure? [y/N]: '\n value = input(question).lower()\n while value not in ['', 'n', 'y']:\n print(\"Please answer 'y' or 'n'\")\n value = input(question)\n return value == 'y'\n\n``` \nExample tests:\n```python\nfrom unittest import TestCase\nfrom unittest.mock import MagicMock as Mock\n\n\nclass DatabaseCliTests(TestCase):\n def test_forced_database_drop(self):\n fake_database = Mock()\n database_cli = DatabaseCli(database=fake_database)\n\n database_cli.drop('production', force=True)\n\n fake_database.drop.assert_called_with('production')\n\n def test_database_drop(self):\n fake_database = Mock()\n database_cli = DatabaseCli(database=fake_database)\n database_cli.confirm = Mock(return_value=True) # confirm\n\n database_cli.drop('production')\n\n fake_database.drop.assert_called_with('production')\n\n def test_rejected_database_drop(self):\n fake_database = Mock()\n database_cli = DatabaseCli(database=fake_database)\n database_cli.confirm = Mock(return_value=False) # reject\n\n database_cli.drop('production')\n\n fake_database.drop.assert_not_called()\n```\n\n\n", "description_content_type": "text/markdown", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/stepan-anokhin/comandante", "keywords": "", "license": "", "maintainer": "", "maintainer_email": "", "name": "comandante", "package_url": "https://pypi.org/project/comandante/", "platform": "", "project_url": "https://pypi.org/project/comandante/", "project_urls": { "Homepage": "https://github.com/stepan-anokhin/comandante" }, "release_url": "https://pypi.org/project/comandante/0.0.3/", "requires_dist": null, "requires_python": ">=2.7", "summary": "A toolkit for building command-line interfaces", "version": "0.0.3" }, "last_serial": 5963892, "releases": { "0.0.3": [ { "comment_text": "", "digests": { "md5": "3442ab62adc3765faa004e6cf57bc04d", "sha256": "662392fa2a872e8f72831a41e9600d738d0ed49475e509578a07489999b683a5" }, "downloads": -1, "filename": "comandante-0.0.3-py3-none-any.whl", "has_sig": false, "md5_digest": "3442ab62adc3765faa004e6cf57bc04d", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">=2.7", "size": 25330, "upload_time": "2019-10-12T10:51:24", "url": "https://files.pythonhosted.org/packages/da/ad/1b93710a37204e9e7ee52292477d04c17fa7d9b795a5c6b02243bf47c70d/comandante-0.0.3-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "cbdfe366c28393ca746596e42baad075", "sha256": "cf279c36c70053360acc6b12cfec5b18d03beb6c1fb7f6ab219f037103495298" }, "downloads": -1, "filename": "comandante-0.0.3.tar.gz", "has_sig": false, "md5_digest": "cbdfe366c28393ca746596e42baad075", "packagetype": "sdist", "python_version": "source", "requires_python": ">=2.7", "size": 19348, "upload_time": "2019-10-12T10:51:26", "url": "https://files.pythonhosted.org/packages/27/0f/3dd4a6968af46413dfb2b044d55fa7b20ce89ec1b4d3f790ab9eeee517b8/comandante-0.0.3.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "3442ab62adc3765faa004e6cf57bc04d", "sha256": "662392fa2a872e8f72831a41e9600d738d0ed49475e509578a07489999b683a5" }, "downloads": -1, "filename": "comandante-0.0.3-py3-none-any.whl", "has_sig": false, "md5_digest": "3442ab62adc3765faa004e6cf57bc04d", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">=2.7", "size": 25330, "upload_time": "2019-10-12T10:51:24", "url": "https://files.pythonhosted.org/packages/da/ad/1b93710a37204e9e7ee52292477d04c17fa7d9b795a5c6b02243bf47c70d/comandante-0.0.3-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "cbdfe366c28393ca746596e42baad075", "sha256": "cf279c36c70053360acc6b12cfec5b18d03beb6c1fb7f6ab219f037103495298" }, "downloads": -1, "filename": "comandante-0.0.3.tar.gz", "has_sig": false, "md5_digest": "cbdfe366c28393ca746596e42baad075", "packagetype": "sdist", "python_version": "source", "requires_python": ">=2.7", "size": 19348, "upload_time": "2019-10-12T10:51:26", "url": "https://files.pythonhosted.org/packages/27/0f/3dd4a6968af46413dfb2b044d55fa7b20ce89ec1b4d3f790ab9eeee517b8/comandante-0.0.3.tar.gz" } ] }