subc


Namesubc JSON
Version 0.6.0 PyPI version JSON
download
home_pagehttps://git.sr.ht/~brenns10/subc
SummaryCLI sub-command library
upload_time2021-04-26 17:05:30
maintainer
docs_urlNone
authorStephen Brennan
requires_python
licenseRevised BSD
keywords arguments sub-command command
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            subc
====

This is a tiny library to help you write CLI applications with many
sub-commands.

Installation
------------

``pip install subc``

Use
---

Create your own command subclass for your application:


.. code:: python

    class MyCmd(subc.Command):
        pass

Then, write commands in your application which sub-class this:

.. code:: python

    class HelloWorld(MyCmd):
        name = 'hello-world'
        description = 'say hello'
        def run(self):
            print('hello world')

Finally, use your application-level subclass for creating the argument parser
and running your application:

.. code:: python

    if __name__ == '__main__':
        MyCmd.main('description of app')

Advanced Use
------------

Intermediate Base Classes
^^^^^^^^^^^^^^^^^^^^^^^^^

You may find yourself wanting to create intermediate subclasses for your
application, in order to share common functionality. For example, you might
create a class for all commands which handle a single file as an argument:

.. code:: python

    class FileCmd(MyCmd):
        def add_args(self, parser):
            parser.add_args('file', help='the single file')

You can do that, so long as your intermediate subclasses are not executable. For
example, given the following class hierarchy:

.. code::

    MyCmd*
    |- FileCmd*
    |  |- AppendLineCmd
    |  |- RemoveLineCmd
    |- DoSomethingElseCmd

The non-leaf commands (marked with an asterisk) will not be included as
executable commands. Only leaf classes will be executable.

Default Command
^^^^^^^^^^^^^^^

When the user does not provide any argument on the command-line, the default
action is to raise an Exception which states "you must select a sub-command".
You can provide a default command to run instead, via the ``default`` argument
to ``main()`` (or ``add_subcommands()``). For example:

.. code:: python

    if __name__ == '__main__':
        MyCmd.main('description', default='help')

The above code will run the ``help`` subcommand when no subcommand is specified.
Note that in this case, the default sub-command may not receive all of its
expected arguments.

Shortest Prefix Aliasing
^^^^^^^^^^^^^^^^^^^^^^^^

``subc`` has an optional feature which allows the user to specify a subcommand
by the shortest prefix which uniquely identifies the subcommand, or any longer
prefix thereof. As an example, imagine a git command with the following
sub-commands: clone, checkout, commit, cherry-pick. The shortest prefix aliasing
would allow you to run "git clone" by executing ``git cl``, since only "clone"
begins with "cl". You could also execute "git clone" with a longer prefix like
``git clo``. The feature can be enabled by setting ``shortest_prefix`` to true
in ``main()`` or ``add_subcommands()``.

License
-------

This project is released under the Revised BSD license.  See ``LICENSE.txt`` for
details.



            

Raw data

            {
    "_id": null,
    "home_page": "https://git.sr.ht/~brenns10/subc",
    "name": "subc",
    "maintainer": "",
    "docs_url": null,
    "requires_python": "",
    "maintainer_email": "",
    "keywords": "arguments sub-command command",
    "author": "Stephen Brennan",
    "author_email": "stephen@brennan.io",
    "download_url": "https://files.pythonhosted.org/packages/28/fb/3432c2ffb0d5f539878bf578e5f55be156c805af7659d2d6349eafa855f8/subc-0.6.0.tar.gz",
    "platform": "",
    "description": "subc\n====\n\nThis is a tiny library to help you write CLI applications with many\nsub-commands.\n\nInstallation\n------------\n\n``pip install subc``\n\nUse\n---\n\nCreate your own command subclass for your application:\n\n\n.. code:: python\n\n    class MyCmd(subc.Command):\n        pass\n\nThen, write commands in your application which sub-class this:\n\n.. code:: python\n\n    class HelloWorld(MyCmd):\n        name = 'hello-world'\n        description = 'say hello'\n        def run(self):\n            print('hello world')\n\nFinally, use your application-level subclass for creating the argument parser\nand running your application:\n\n.. code:: python\n\n    if __name__ == '__main__':\n        MyCmd.main('description of app')\n\nAdvanced Use\n------------\n\nIntermediate Base Classes\n^^^^^^^^^^^^^^^^^^^^^^^^^\n\nYou may find yourself wanting to create intermediate subclasses for your\napplication, in order to share common functionality. For example, you might\ncreate a class for all commands which handle a single file as an argument:\n\n.. code:: python\n\n    class FileCmd(MyCmd):\n        def add_args(self, parser):\n            parser.add_args('file', help='the single file')\n\nYou can do that, so long as your intermediate subclasses are not executable. For\nexample, given the following class hierarchy:\n\n.. code::\n\n    MyCmd*\n    |- FileCmd*\n    |  |- AppendLineCmd\n    |  |- RemoveLineCmd\n    |- DoSomethingElseCmd\n\nThe non-leaf commands (marked with an asterisk) will not be included as\nexecutable commands. Only leaf classes will be executable.\n\nDefault Command\n^^^^^^^^^^^^^^^\n\nWhen the user does not provide any argument on the command-line, the default\naction is to raise an Exception which states \"you must select a sub-command\".\nYou can provide a default command to run instead, via the ``default`` argument\nto ``main()`` (or ``add_subcommands()``). For example:\n\n.. code:: python\n\n    if __name__ == '__main__':\n        MyCmd.main('description', default='help')\n\nThe above code will run the ``help`` subcommand when no subcommand is specified.\nNote that in this case, the default sub-command may not receive all of its\nexpected arguments.\n\nShortest Prefix Aliasing\n^^^^^^^^^^^^^^^^^^^^^^^^\n\n``subc`` has an optional feature which allows the user to specify a subcommand\nby the shortest prefix which uniquely identifies the subcommand, or any longer\nprefix thereof. As an example, imagine a git command with the following\nsub-commands: clone, checkout, commit, cherry-pick. The shortest prefix aliasing\nwould allow you to run \"git clone\" by executing ``git cl``, since only \"clone\"\nbegins with \"cl\". You could also execute \"git clone\" with a longer prefix like\n``git clo``. The feature can be enabled by setting ``shortest_prefix`` to true\nin ``main()`` or ``add_subcommands()``.\n\nLicense\n-------\n\nThis project is released under the Revised BSD license.  See ``LICENSE.txt`` for\ndetails.\n\n\n",
    "bugtrack_url": null,
    "license": "Revised BSD",
    "summary": "CLI sub-command library",
    "version": "0.6.0",
    "split_keywords": [
        "arguments",
        "sub-command",
        "command"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "cac714561563304066f7f08697a56237",
                "sha256": "028e58671ad8a777a7ddcea88af4a2cd9815e74f93bf78cd0b69cb7ab0b9098d"
            },
            "downloads": -1,
            "filename": "subc-0.6.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "cac714561563304066f7f08697a56237",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": null,
            "size": 5845,
            "upload_time": "2021-04-26T17:05:28",
            "upload_time_iso_8601": "2021-04-26T17:05:28.656647Z",
            "url": "https://files.pythonhosted.org/packages/7d/73/235991a1f733d7b401dc387f00ae5bfb98a2d8be496798a51405db991fb5/subc-0.6.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "925013b05b213ca4f5ae22814cc4e87c",
                "sha256": "59aeb25ed1821fd17e29daa63bcd87ae528c28da06ee8321ee1e5295c3282cb1"
            },
            "downloads": -1,
            "filename": "subc-0.6.0.tar.gz",
            "has_sig": false,
            "md5_digest": "925013b05b213ca4f5ae22814cc4e87c",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 5854,
            "upload_time": "2021-04-26T17:05:30",
            "upload_time_iso_8601": "2021-04-26T17:05:30.126783Z",
            "url": "https://files.pythonhosted.org/packages/28/fb/3432c2ffb0d5f539878bf578e5f55be156c805af7659d2d6349eafa855f8/subc-0.6.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2021-04-26 17:05:30",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "lcname": "subc"
}
        
Elapsed time: 0.24267s