{"id":15914406,"url":"https://github.com/bbengfort/commis","last_synced_at":"2025-03-22T21:31:23.545Z","repository":{"id":62563977,"uuid":"50044091","full_name":"bbengfort/commis","owner":"bbengfort","description":"Create command line applications like Django management commands.","archived":false,"fork":false,"pushed_at":"2019-07-11T19:03:06.000Z","size":309,"stargazers_count":3,"open_issues_count":2,"forks_count":4,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-18T14:53:33.787Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bbengfort.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-01-20T16:42:26.000Z","updated_at":"2020-01-30T19:31:46.000Z","dependencies_parsed_at":"2022-11-03T16:45:38.201Z","dependency_job_id":null,"html_url":"https://github.com/bbengfort/commis","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbengfort%2Fcommis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbengfort%2Fcommis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbengfort%2Fcommis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbengfort%2Fcommis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bbengfort","download_url":"https://codeload.github.com/bbengfort/commis/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245022455,"owners_count":20548542,"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":[],"created_at":"2024-10-06T17:02:21.433Z","updated_at":"2025-03-22T21:31:23.110Z","avatar_url":"https://github.com/bbengfort.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Commis\n\n**Create command line applications like Django management commands.**\n\n[![Build Status](https://travis-ci.org/bbengfort/commis.svg?branch=master)](https://travis-ci.org/bbengfort/commis)\n[![Coverage Status](https://coveralls.io/repos/github/bbengfort/commis/badge.svg?branch=master)](https://coveralls.io/github/bbengfort/commis?branch=master)\n[![PyPI version](https://badge.fury.io/py/commis.svg)](https://badge.fury.io/py/commis)\n[![Documentation Status](https://readthedocs.org/projects/commis/badge/?version=latest)](http://commis.readthedocs.org/en/latest/?badge=latest)\n\n[![Pâte de fruit (gominolas) de laranxa sanguina][gominolas.jpg]][gominolas_flickr]\n\nRead the full documentation at [http://commis.readthedocs.org/](http://commis.readthedocs.org/).\n\n## Getting Started\n\nTo install the Commis library, the simplest thing to do is use `pip` as follows:\n\n    $ pip install commis\n\nAlternatively, you can download the latest (development) version or clone directly from Github and install it using the `setup.py` script:\n\n    $ git clone https://github.com/bbengfort/commis.git\n    $ cd commis\n    $ python setup.py install\n\n### Writing Commands\n\nThere is a bit more detail in the full documentation, but basically the way you create commands is to subclass the `Command` class, define its `name`, `help`, and `args` attributes, then implement a `handle` method. This more or less looks as follows:\n\n```python\nclass GreetingCommand(Command):\n\n    name    = \"greeting\"\n    help    = \"an example command, delivers a greeting\"\n\n    args    = {\n        # Language selection option\n        ('-l', '--lang'): {\n            'type': str,\n            'default': 'english',\n            'metavar': 'LANG',\n            'choices': ['english', 'french', 'spanish'],\n            'help': 'the language of the greeting',\n        },\n\n        # List of one or more name arguments\n        'name': {\n            'nargs': \"+\",\n            'type': str,\n            'help': 'the name to greet you by'\n        }\n    }\n\n    def handle(self, args):\n        \"\"\"\n        Greet each person by name.\n        \"\"\"\n        salutation = {\n            'french': 'Bonjour',\n            'spanish': 'Hola',\n            'english': 'Hello',\n        }[args.lang.lower()]\n\n        output = []\n        for name in args.name:\n            output.append(\"{} {}!\".format(salutation, name))\n        return \"\\n\".join(output)\n```\n\nThe `args` is a Python dictionary of keyword arguments to be passed to `argparse.add_argument` and uses the same syntax. See [the add_argument method](https://argparse.googlecode.com/svn/trunk/doc/add_argument.html) for more details.\n\nThe `handle` method should accept args as its only argument, and should return a string to be printed to the command line.\n\n### Writing a Console Program\n\nOnce you have your commands, you need to create and define a console utility to execute them. Simply subclass `ConsoleProgram` with your definition as follows:\n\n```python\nVERSION     = \"1.0\"\nDESCRIPTION = \"Inspects the mimetype distribution of a directory.\"\nEPILOG      = \"Created for scientific purposes and not diagnostic ones.\"\nCOMMANDS    = [\n    GreetingCommand,\n]\n\nclass ExampleUtility(ConsoleProgram):\n\n    description = DESCRIPTION\n    epilog      = EPILOG\n    version     = VERSION\n\n    @classmethod\n    def load(klass, commands=COMMANDS):\n        utility = klass()\n        for command in commands:\n            utility.register(command)\n        return utility\n```\n\nThe `ConsoleProgram` has a `register` method which allows you to register various commands. You can do this at run time, creating dynamic utilities with different commands, or you can explore a directory and load all commands from it. Here I just simply add a simple `load` static method to load the commands and instantiate the utility. Using the utility is then as simple as creating a script as follows:\n\n```python\nfrom example import ExampleUtility\n\nif __name__ == '__main__':\n    utility = ExampleUtility.load()\n    utility.execute()\n```\n\nFor more on writing console utilities and programs, check out the documentation at [http://commis.readthedocs.org/](http://commis.readthedocs.org/).\n\n## About\n\nI'm not sure why this doesn't exist yet, but I needed a library for creating command line utilities that wrapped the `argparse` library. Most of the ones I found used a decorator based syntax; but I really do like the Django management commands style of creating applications. Therefore, this library serves to give you the ability to do so!\n\n### Contributing\n\nCommis is open source, and I would be happy to have you contribute! You can contribute in the following ways:\n\n1. Create a pull request in Github: [https://github.com/bbengfort/commis](https://github.com/bbengfort/commis)\n2. Add issues or bugs on the bug tracker: [https://github.com/bbengfort/commis/issues](https://github.com/bbengfort/commis/issues)\n3. Checkout the current dev board on waffle.io: [https://waffle.io/bbengfort/commis](https://waffle.io/bbengfort/commis)\n\nNote that labels in the Github issues are defined in the blog post: [How we use labels on GitHub Issues at Mediocre Laboratories](https://mediocre.com/forum/topics/how-we-use-labels-on-github-issues-at-mediocre-laboratories).\n\nIf you've contributed a fair amount, I'll give you direct access to the repository, which is set up in a typical production/release/development cycle as described in _[A Successful Git Branching Model](http://nvie.com/posts/a-successful-git-branching-model/)_. A typical workflow is as follows:\n\n1. Select a card from the [dev board](https://waffle.io/bbengfort/commis) - preferably one that is \"ready\" then move it to \"in-progress\".\n\n2. Create a branch off of develop called \"feature-[feature name]\", work and commit into that branch.\n\n        ~$ git checkout -b feature-myfeature develop\n\n3. Once you are done working (and everything is tested) merge your feature into develop.\n\n        ~$ git checkout develop\n        ~$ git merge --no-ff feature-myfeature\n        ~$ git branch -d feature-myfeature\n        ~$ git push origin develop\n\n4. Repeat. Releases will be routinely pushed into master via release branches, then deployed to the server.\n\nNote that pull requests will be reviewed when the Travis-CI tests pass, so including tests with your pull request is ideal!\n\nYou can contact me on Twitter if needed: [@bbengfort](https://twitter.com/bbengfort)\n\n### Name Origin\n\u003cbig\u003ecom \u0026middot; mis\u003c/big\u003e\u003cbr /\u003e\n/ˈkämē,kô-/\u003cbr/\u003e\n*noun* a junior chef.\n\nOrigin\u003cbr /\u003e\n[Latin] *committere*: 1930s: from French, 'deputy, clerk', past participle of commettre 'entrust', from Latin.\u003cbr \\\u003e\n\nA commis is a basic chef in larger kitchens who works under a chef de partie to learn the station's or range's responsibilities and operation.[3] This may be a chef who has recently completed formal culinary training or is still undergoing training. \u0026mdash; [Wikipedia](https://en.wikipedia.org/wiki/Chef#Commis_.28Chef.29_.2F_Range_chef)\n\nThis package is closely related to the [Confire](https://github.com/bbengfort/confire) configuration tool, hence the name in the same vein \u0026mdash; French cooking words. In this case, a commis is someone to whom orders are given (commands) and seemed an appropriate term for a package whose function is accept and execute commands.\n\n### Attribution\n\nThe photo used in this README, \u0026ldquo;[Pâte de fruit (gominolas) de laranxa sanguina][gominolas_flickr]\u0026rdquo; by [Receitasparatodososdias](https://www.flickr.com/photos/100127130@N05/) is used under a [CC BY-NC-ND 2.0](https://creativecommons.org/licenses/by-nc-nd/2.0/) creative commons license.\n\n## Releases\n\nThe release versions that are sent to the Python package index are also tagged in Github. You can see the tags through the Github web application and download the tarball of the version you'd like. Additionally PyPI will host the various releases of commis.\n\nThe versioning uses a three part version system, \"a.b.c\" - \"a\" represents a major release that may not be backwards compatible. \"b\" is incremented on minor releases that may contain extra features, but are backwards compatible. \"c\" releases are bug fixes or other micro changes that developers should feel free to immediately update to.\n\n- [Version 0.5](https://github.com/bbengfort/commis/releases/tag/v0.5)\n- [Version 0.4](https://github.com/bbengfort/commis/releases/tag/v0.4)\n- [Version 0.3](https://github.com/bbengfort/commis/releases/tag/v0.3)\n- [Version 0.2](https://github.com/bbengfort/commis/releases/tag/v0.2)\n- [Version 0.1](https://github.com/bbengfort/commis/releases/tag/v0.1)\n\n\u003c!-- References --\u003e\n[gominolas.jpg]: docs/img/gominolas.jpg\n[gominolas_flickr]: https://flic.kr/p/mcSxAK\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbengfort%2Fcommis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbbengfort%2Fcommis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbengfort%2Fcommis/lists"}