Commandlines Library Documentation
==================================
commandlines |Build Status| |Build status| |codecov.io| |Code Health|
---------------------------------------------------------------------
Source Repository: `chrissimpkins/commandlines <https://github.com/chrissimpkins/commandlines>`__
Documentation: `commandlines.github.io <https://commandlines.github.io>`__
What is Commandlines?
---------------------
`Commandlines <https://github.com/chrissimpkins/commandlines>`__ is a Python library for command line application
development that supports command line argument parsing, command string
validation testing, & application logic. It has no external dependencies
and provides broad Python interpreter support for Python 2.6+, Python
3.3+, pypy, and pypy3 across OS X, Linux, and Windows platforms.
The library supports application development with `POSIX guideline compliant <https://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html#Argument-Syntax>`__ [*]_ command argument styles, the `GNU argument style extensions
to the POSIX guidelines <https://www.gnu.org/prep/standards/standards.html#Command_002dLine-Interfaces>`__
(including long option syntax and variable position of options among arguments), and command suite style application arguments that include one or more sub-commands to the executable.
.. [*] with the exception of the short single option-argument definition syntax that does not include an intervening space character (e.g. ``-ofile``)
How Do I Use It?
----------------
The command line string to your executable script is parsed to multiple
objects that are derived from builtin Python types.
The Command Object
~~~~~~~~~~~~~~~~~~
Instantiate a ``commandlines`` Command object:
.. code:: python
from commandlines import Command
c = Command()
and use the following instance attributes and methods to develop your application:
Arguments
^^^^^^^^^
+-----------------+-----------------------------------+-------------------------------------+
| Command Line | Command Example | Accessed/Tested |
| Arguments | | With |
+=================+===================================+=====================================+
| Length of arg | ``$ spam eggs -t --out file`` | ``c.argc == 4`` |
| list | | |
+-----------------+-----------------------------------+-------------------------------------+
| Command suite | ``$ spam eggs`` | ``c.subcmd == "eggs"`` |
| sub-commands | | |
+-----------------+-----------------------------------+-------------------------------------+
| Command suite | ``$ spam eggs overeasy`` | ``c.subsubcmd == "overeasy"`` |
| sub-sub-commands| | |
| | | |
+-----------------+-----------------------------------+-------------------------------------+
| Short switch | ``$ spam -e`` | ``c.contains_switches('e')`` |
| syntax | | |
+-----------------+-----------------------------------+-------------------------------------+
| Long switch | ``$ spam --eggs`` | ``c.contains_switches('eggs')`` |
| syntax | | |
+-----------------+-----------------------------------+-------------------------------------+
| Multiple | ``$ spam -e --eggs`` | ``c.contains_switches('e', 'eggs')``|
| switches | | |
| | | |
+-----------------+-----------------------------------+-------------------------------------+
| Short opt-arg | ``$ spam -o eggs`` | ``c.get_definition('o')`` |
| definition | | |
| syntax | | |
+-----------------+-----------------------------------+-------------------------------------+
| Long opt-arg | ``$ spam --out eggs`` | ``c.get_definition('out')`` |
| definition | | |
| syntax | | |
+-----------------+-----------------------------------+-------------------------------------+
| Alt long | ``$ spam --out=eggs`` | ``c.get_definition('out')`` |
| opt-arg | | |
| definition | | |
| syntax | | |
+-----------------+-----------------------------------+-------------------------------------+
| Multiple same | ``$ spam -o eggs -o omelets`` | ``c.get_multiple_definitions('o')`` |
| option | | |
| definitions | | |
+-----------------+-----------------------------------+-------------------------------------+
| Multi-option | ``$ spam -mpns eggs`` | ``c.contains_mops('m')`` |
| short syntax | | |
| switches | | |
+-----------------+-----------------------------------+-------------------------------------+
| Next positional | ``$ spam eggs test/path`` | ``c.get_arg_after('eggs')`` |
| argument | | |
+-----------------+-----------------------------------+-------------------------------------+
Positional Arguments
^^^^^^^^^^^^^^^^^^^^
Positional arguments use a 0 based index starting at the first argument
to the executable (i.e. ``sys.argv[1:]``) and are maintained as
attributes in the Command object. Individual attribute support is
provided for the first five positional arguments and the last positional
argument. An ordered list of all positional arguments is available in
the ``arguments`` attribute.
+-----------------+----------------------------------------+--------------------+
| Positional | Command Example | Accessed/Tested |
| Argument | | With |
+=================+========================================+====================+
| Positional | ``$ spam eggs`` | ``c.arg0`` |
| argument at | | |
| index 0 | | |
+-----------------+----------------------------------------+--------------------+
| Positional | ``$ spam eggs bacon`` | ``c.arg1`` |
| argument at | | |
| index 1 | | |
+-----------------+----------------------------------------+--------------------+
| Positional | ``$ spam eggs bacon toast`` | ``c.arg2`` |
| argument at | | |
| index 2 | | |
+-----------------+----------------------------------------+--------------------+
| Positional | ``$ spam eggs bacon toast cereal`` | ``c.arg3`` |
| argument at | | |
| index 3 | | |
+-----------------+----------------------------------------+--------------------+
| Positional | ``$ spam eggs bacon toast cereal milk``| ``c.arg4`` |
| argument at | | |
| index 4 | | |
+-----------------+----------------------------------------+--------------------+
| Last positional | ``$ spam eggs -b --toast filepath`` | ``c.arglp`` |
| argument | | |
+-----------------+----------------------------------------+--------------------+
| All positional | ``$ spam eggs -b - -toast filepath`` | ``c.arguments`` |
| arguments | | |
+-----------------+----------------------------------------+--------------------+
Default Option-Argument Definitions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Define option-argument defaults in a ``defaults`` Command instance
attribute. This attribute is defined as an empty Python dictionary upon
instantiation of the Command object. Use standard key index-based Python
dictionary assignments or the ``set_defaults`` assignment method in the
Command class to define default values. Default values can take any type
that is permissible as a Python dictionary value.
Here are examples of each approach that define defaults for ``output``
and ``level`` options:
Key Index-Based Default Assignments
'''''''''''''''''''''''''''''''''''
.. code:: python
from commandlines import Command
c = Command()
c.defaults['output'] = "test.txt"
c.defaults['level'] = 10
Method-Based Default Assignments
''''''''''''''''''''''''''''''''
.. code:: python
from commandlines import Command
c = Command()
default_options = {
'output' : 'test.txt',
'level' : 10
}
c.set_defaults(default_options)
To test for the presence of a default option definition and obtain its
value, use the ``contains_defaults`` and ``get_default`` methods,
respectively:
.. code:: python
# continued from code examples above
if c.contains_definitions('output'):
dosomething(c.get_definition('output'))
elif c.contains_defaults('output'):
dosomething(c.get_default('output'))
else:
dosomethingelse()
Help, Usage, and Version Request Testing Methods
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Help, usage, and version command line requests are tested with methods:
+--------------------------+------------------------+------------------------------+
| Test Type | Command Example | Tested With |
+==========================+========================+==============================+
| Help request, short | ``$ spam -h`` | ``c.is_help_request()`` |
+--------------------------+------------------------+------------------------------+
| Help request, long | ``$ spam --help`` | ``c.is_help_request()`` |
+--------------------------+------------------------+------------------------------+
| Usage request | ``$ spam --usage`` | ``c.is_usage_request()`` |
+--------------------------+------------------------+------------------------------+
| Version request, short | ``$ spam -v`` | ``c.is_version_request()`` |
+--------------------------+------------------------+------------------------------+
| Version request, long | ``$ spam --version`` | ``c.is_version_request()`` |
+--------------------------+------------------------+------------------------------+
Testing Methods for Other Commonly Used Switches
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------+-----------------------------+------------------------------+
| Test Type | Command Example | Tested With |
+===========================+=============================+==============================+
| Verbose standard output | ``$ spam eggs --verbose`` | ``c.is_verbose_request()`` |
+---------------------------+-----------------------------+------------------------------+
| Quiet standard output | ``$ spam eggs --quiet`` | ``c.is_quiet_request()`` |
+---------------------------+-----------------------------+------------------------------+
Special Command Line Idioms
^^^^^^^^^^^^^^^^^^^^^^^^^^^
The double dash idiom escapes all subsequent tokens from option/argument
parsing. Methods are available to determine whether a double dash token
is present in a command and obtain an ordered list of all command line
arguments that follow this idiom:
+-----------------+----------------------------------------+----------------------------------------+
| Command Line | Command Example | Accessed/Tested |
| Idioms | | With |
+=================+========================================+========================================+
| Double dash | ``$ spam eggs -- -badfile`` | ``c.has_double_dash()`` |
| idiom | | |
+-----------------+----------------------------------------+----------------------------------------+
| Double dash | ``$ spam eggs -- -badfile -badfile2`` | ``c.get_double_dash_args()`` |
| arguments | | |
| | | |
+-----------------+----------------------------------------+----------------------------------------+
Application Logic Testing Methods
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-----------------+----------------------------------------+--------------------------------------------------------+
| Test Type | Command Example | Tested With |
+=================+========================================+========================================================+
| Positional | ``$ spam eggs doit`` | ``c.has_command_sequence('eggs', 'doit')`` |
| command | | |
| sequence | | |
+-----------------+----------------------------------------+--------------------------------------------------------+
| Single switch | ``$ spam -s`` | ``c.contains_switches('s')`` |
| | | |
+-----------------+----------------------------------------+--------------------------------------------------------+
| Multiple switch | ``$ spam -s --eggs`` | ``c.contains_switches('s', 'eggs')`` |
| | | |
+-----------------+----------------------------------------+--------------------------------------------------------+
| Single | ``$ spam -o eggs`` | ``c.contains_definitions('o')`` |
| definition | | |
+-----------------+----------------------------------------+--------------------------------------------------------+
| Multiple | ``$ spam -o eggs --with bacon`` | ``c.contains_definitions('o', 'with')`` |
| different | | |
| definitions | | |
+-----------------+----------------------------------------+--------------------------------------------------------+
| Multiple same | ``$ spam -o eggs -o bacon`` | ``c.contains_multi_definitions('o')`` |
| definitions | | |
| | | |
+-----------------+----------------------------------------+--------------------------------------------------------+
| Positional | ``$ spam eggs --coffee`` | ``c.has_args_after('eggs')`` |
| argument | | |
+-----------------+----------------------------------------+--------------------------------------------------------+
| Acceptable | ``$ spam eggs toaster`` | ``c.next_arg_is_in('eggs', ['toaster', 'coffeepot'])`` |
| positional arg | | |
| | | |
+-----------------+----------------------------------------+--------------------------------------------------------+
Command String Validation Methods
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-----------------+-------------------------+----------------------------------------------+
| Test Type | Failure Example | Tested With |
+=================+=========================+==============================================+
| Missing | ``$ spam`` | ``c.does_not_validate_missing_args()`` |
| arguments | | |
| | | |
+-----------------+-------------------------+----------------------------------------------+
| Expected | ``$ spam eggs`` | ``c.does_not_validate_n_args(2)`` |
| argument number | | |
+-----------------+-------------------------+----------------------------------------------+
| Missing opt-arg | ``$ spam -o --eggs`` | ``c.does_not_validate_missing_defs()`` |
| definitions | | |
| | | |
+-----------------+-------------------------+----------------------------------------------+
| Missing | ``$ spam eggs`` | ``c.does_not_validate_missing_switches()`` |
| switches | | |
| | | |
+-----------------+-------------------------+----------------------------------------------+
| Missing | ``$ spam -o eggs`` | ``c.does_not_validate_missing_mops()`` |
| multi-option | | |
| short syntax | | |
| switches | | |
+-----------------+-------------------------+----------------------------------------------+
Development with Commandlines
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To facilitate development with Commandlines, you can print the string
returned by the Command ``obj_string()`` method to view a list of the
parsed arguments from example commands:
.. code:: python
from commandlines import Command
c = Command()
print(c.obj_string())
sys.exit(0)
For example, if you execute your script with the command
``spam eggs --toast -b --drink=milk filepath`` and include the above
print statement in your source, you will see the following in your
terminal emulator:
.. code:: shell
$ spam eggs --toast -b --drink=milk filepath
obj.argc = 5
obj.arguments = ['eggs', '--toast', '-b', '--drink=milk', 'filepath']
obj.defaults = {}
obj.switches = {'toast', 'b'}
obj.defs = {'drink': 'milk'}
obj.mdefs = {}
obj.mops = {}
obj.arg0 = 'eggs'
obj.arg1 = '--toast'
obj.arg2 = '-b'
obj.arg3 = '--drink=milk'
obj.arg4 = 'filepath'
obj.arglp = 'filepath'
obj.subcmd = 'eggs'
obj.subsubcmd = '--toast'
API Documentation
~~~~~~~~~~~~~~~~~
You can view full documentation of the Command class `here <https://commandlines.github.io/commandlines.library.html#commandlines.library.Command>`__.
If you would like to dig into lower level objects in the commandlines
package, you can view the `library API
documentation <https://commandlines.github.io/commandlines.library.html>`__.
Exceptions that are used in the commandlines package are documented
`here <https://commandlines.github.io/commandlines.exceptions.html>`__.
How to Include Commandlines in Your Project
-------------------------------------------
For Projects That Will Be Distributed to Others
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Add the ``commandlines`` package dependency to your project ``setup.py``
file in the ``install_requires`` field like so:
.. code:: python
setup(
...
install_requires=["commandlines"],
...
)
Then, enter the following command to test your project locally:
::
$ python setup.py develop
Import the ``commandlines`` package in your project and instantiate a
Command object by adding the following lines to your Python script:
.. code:: python
from commandlines import Command
c = Command()
And away you go...
The Commandlines package will be installed automatically for users who
install your releases via ``pip`` or your project ``setup.py`` file
(i.e. with the command ``$ python setup.py install``).
For Local Projects That Are Not Intended for Redistribution
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Install the Commandlines package with the command:
::
$ pip install commandlines
Import the ``commandlines`` package in your project and instantiate a
Command object by adding the following lines to your Python script:
.. code:: python
from commandlines import Command
c = Command()
License
-------
Commandlines is licensed under the `MIT license <https://github.com/chrissimpkins/commandlines/blob/master/docs/LICENSE>`__.
.. |Build Status| image:: https://travis-ci.org/chrissimpkins/commandlines.svg?branch=master
:target: https://travis-ci.org/chrissimpkins/commandlines
.. |Build status| image:: https://ci.appveyor.com/api/projects/status/nabadxorf9s8n0h5/branch/master?svg=true
:target: https://ci.appveyor.com/project/chrissimpkins/commandlines/branch/master
.. |codecov.io| image:: https://codecov.io/github/chrissimpkins/commandlines/coverage.svg?branch=master
:target: https://codecov.io/github/chrissimpkins/commandlines?branch=master
.. |Code Health| image:: https://landscape.io/github/chrissimpkins/commandlines/master/landscape.svg?style=flat
:target: https://landscape.io/github/chrissimpkins/commandlines/master
Raw data
{
"_id": null,
"home_page": "https://github.com/chrissimpkins/commandlines",
"name": "commandlines",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "CLI,command line,parser,shell,application,command line application,argument,argument parser",
"author": "Christopher Simpkins",
"author_email": "chris@sourcefoundry.org",
"download_url": "https://files.pythonhosted.org/packages/b9/4c/d380f7f9aaa12175b189cfe087e823cd9aa2a99afc95a8d6e028142311c9/commandlines-0.4.1.tar.gz",
"platform": "any",
"description": "Commandlines Library Documentation\n==================================\n\ncommandlines |Build Status| |Build status| |codecov.io| |Code Health|\n---------------------------------------------------------------------\n\nSource Repository: `chrissimpkins/commandlines <https://github.com/chrissimpkins/commandlines>`__\n\nDocumentation: `commandlines.github.io <https://commandlines.github.io>`__\n\nWhat is Commandlines?\n---------------------\n\n`Commandlines <https://github.com/chrissimpkins/commandlines>`__ is a Python library for command line application\ndevelopment that supports command line argument parsing, command string\nvalidation testing, & application logic. It has no external dependencies\nand provides broad Python interpreter support for Python 2.6+, Python\n3.3+, pypy, and pypy3 across OS X, Linux, and Windows platforms.\n\nThe library supports application development with `POSIX guideline compliant <https://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html#Argument-Syntax>`__ [*]_ command argument styles, the `GNU argument style extensions\nto the POSIX guidelines <https://www.gnu.org/prep/standards/standards.html#Command_002dLine-Interfaces>`__\n(including long option syntax and variable position of options among arguments), and command suite style application arguments that include one or more sub-commands to the executable.\n\n.. [*] with the exception of the short single option-argument definition syntax that does not include an intervening space character (e.g. ``-ofile``)\n\nHow Do I Use It?\n----------------\n\nThe command line string to your executable script is parsed to multiple\nobjects that are derived from builtin Python types.\n\nThe Command Object\n~~~~~~~~~~~~~~~~~~\n\nInstantiate a ``commandlines`` Command object:\n\n.. code:: python\n\n from commandlines import Command\n\n c = Command()\n\nand use the following instance attributes and methods to develop your application:\n\nArguments\n^^^^^^^^^\n\n+-----------------+-----------------------------------+-------------------------------------+\n| Command Line | Command Example | Accessed/Tested |\n| Arguments | | With |\n+=================+===================================+=====================================+\n| Length of arg | ``$ spam eggs -t --out file`` | ``c.argc == 4`` |\n| list | | |\n+-----------------+-----------------------------------+-------------------------------------+\n| Command suite | ``$ spam eggs`` | ``c.subcmd == \"eggs\"`` |\n| sub-commands | | |\n+-----------------+-----------------------------------+-------------------------------------+\n| Command suite | ``$ spam eggs overeasy`` | ``c.subsubcmd == \"overeasy\"`` |\n| sub-sub-commands| | |\n| | | |\n+-----------------+-----------------------------------+-------------------------------------+\n| Short switch | ``$ spam -e`` | ``c.contains_switches('e')`` |\n| syntax | | |\n+-----------------+-----------------------------------+-------------------------------------+\n| Long switch | ``$ spam --eggs`` | ``c.contains_switches('eggs')`` |\n| syntax | | |\n+-----------------+-----------------------------------+-------------------------------------+\n| Multiple | ``$ spam -e --eggs`` | ``c.contains_switches('e', 'eggs')``|\n| switches | | |\n| | | |\n+-----------------+-----------------------------------+-------------------------------------+\n| Short opt-arg | ``$ spam -o eggs`` | ``c.get_definition('o')`` |\n| definition | | |\n| syntax | | |\n+-----------------+-----------------------------------+-------------------------------------+\n| Long opt-arg | ``$ spam --out eggs`` | ``c.get_definition('out')`` |\n| definition | | |\n| syntax | | |\n+-----------------+-----------------------------------+-------------------------------------+\n| Alt long | ``$ spam --out=eggs`` | ``c.get_definition('out')`` |\n| opt-arg | | |\n| definition | | |\n| syntax | | |\n+-----------------+-----------------------------------+-------------------------------------+\n| Multiple same | ``$ spam -o eggs -o omelets`` | ``c.get_multiple_definitions('o')`` |\n| option | | |\n| definitions | | |\n+-----------------+-----------------------------------+-------------------------------------+\n| Multi-option | ``$ spam -mpns eggs`` | ``c.contains_mops('m')`` |\n| short syntax | | |\n| switches | | |\n+-----------------+-----------------------------------+-------------------------------------+\n| Next positional | ``$ spam eggs test/path`` | ``c.get_arg_after('eggs')`` |\n| argument | | |\n+-----------------+-----------------------------------+-------------------------------------+\n\nPositional Arguments\n^^^^^^^^^^^^^^^^^^^^\n\nPositional arguments use a 0 based index starting at the first argument\nto the executable (i.e. ``sys.argv[1:]``) and are maintained as\nattributes in the Command object. Individual attribute support is\nprovided for the first five positional arguments and the last positional\nargument. An ordered list of all positional arguments is available in\nthe ``arguments`` attribute.\n\n+-----------------+----------------------------------------+--------------------+\n| Positional | Command Example | Accessed/Tested |\n| Argument | | With |\n+=================+========================================+====================+\n| Positional | ``$ spam eggs`` | ``c.arg0`` |\n| argument at | | |\n| index 0 | | |\n+-----------------+----------------------------------------+--------------------+\n| Positional | ``$ spam eggs bacon`` | ``c.arg1`` |\n| argument at | | |\n| index 1 | | |\n+-----------------+----------------------------------------+--------------------+\n| Positional | ``$ spam eggs bacon toast`` | ``c.arg2`` |\n| argument at | | |\n| index 2 | | |\n+-----------------+----------------------------------------+--------------------+\n| Positional | ``$ spam eggs bacon toast cereal`` | ``c.arg3`` |\n| argument at | | |\n| index 3 | | |\n+-----------------+----------------------------------------+--------------------+\n| Positional | ``$ spam eggs bacon toast cereal milk``| ``c.arg4`` |\n| argument at | | |\n| index 4 | | |\n+-----------------+----------------------------------------+--------------------+\n| Last positional | ``$ spam eggs -b --toast filepath`` | ``c.arglp`` |\n| argument | | |\n+-----------------+----------------------------------------+--------------------+\n| All positional | ``$ spam eggs -b - -toast filepath`` | ``c.arguments`` |\n| arguments | | |\n+-----------------+----------------------------------------+--------------------+\n\n\nDefault Option-Argument Definitions\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nDefine option-argument defaults in a ``defaults`` Command instance\nattribute. This attribute is defined as an empty Python dictionary upon\ninstantiation of the Command object. Use standard key index-based Python\ndictionary assignments or the ``set_defaults`` assignment method in the\nCommand class to define default values. Default values can take any type\nthat is permissible as a Python dictionary value.\n\nHere are examples of each approach that define defaults for ``output``\nand ``level`` options:\n\nKey Index-Based Default Assignments\n'''''''''''''''''''''''''''''''''''\n\n.. code:: python\n\n from commandlines import Command\n\n c = Command()\n\n c.defaults['output'] = \"test.txt\"\n c.defaults['level'] = 10\n\nMethod-Based Default Assignments\n''''''''''''''''''''''''''''''''\n\n.. code:: python\n\n from commandlines import Command\n\n c = Command()\n\n default_options = {\n 'output' : 'test.txt',\n 'level' : 10\n }\n c.set_defaults(default_options)\n\nTo test for the presence of a default option definition and obtain its\nvalue, use the ``contains_defaults`` and ``get_default`` methods,\nrespectively:\n\n.. code:: python\n\n # continued from code examples above\n\n if c.contains_definitions('output'):\n dosomething(c.get_definition('output'))\n elif c.contains_defaults('output'):\n dosomething(c.get_default('output'))\n else:\n dosomethingelse()\n\n\nHelp, Usage, and Version Request Testing Methods\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nHelp, usage, and version command line requests are tested with methods:\n\n+--------------------------+------------------------+------------------------------+\n| Test Type | Command Example | Tested With |\n+==========================+========================+==============================+\n| Help request, short | ``$ spam -h`` | ``c.is_help_request()`` |\n+--------------------------+------------------------+------------------------------+\n| Help request, long | ``$ spam --help`` | ``c.is_help_request()`` |\n+--------------------------+------------------------+------------------------------+\n| Usage request | ``$ spam --usage`` | ``c.is_usage_request()`` |\n+--------------------------+------------------------+------------------------------+\n| Version request, short | ``$ spam -v`` | ``c.is_version_request()`` |\n+--------------------------+------------------------+------------------------------+\n| Version request, long | ``$ spam --version`` | ``c.is_version_request()`` |\n+--------------------------+------------------------+------------------------------+\n\nTesting Methods for Other Commonly Used Switches\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n+---------------------------+-----------------------------+------------------------------+\n| Test Type | Command Example | Tested With |\n+===========================+=============================+==============================+\n| Verbose standard output | ``$ spam eggs --verbose`` | ``c.is_verbose_request()`` |\n+---------------------------+-----------------------------+------------------------------+\n| Quiet standard output | ``$ spam eggs --quiet`` | ``c.is_quiet_request()`` |\n+---------------------------+-----------------------------+------------------------------+\n\nSpecial Command Line Idioms\n^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nThe double dash idiom escapes all subsequent tokens from option/argument\nparsing. Methods are available to determine whether a double dash token\nis present in a command and obtain an ordered list of all command line\narguments that follow this idiom:\n\n+-----------------+----------------------------------------+----------------------------------------+\n| Command Line | Command Example | Accessed/Tested |\n| Idioms | | With |\n+=================+========================================+========================================+\n| Double dash | ``$ spam eggs -- -badfile`` | ``c.has_double_dash()`` |\n| idiom | | |\n+-----------------+----------------------------------------+----------------------------------------+\n| Double dash | ``$ spam eggs -- -badfile -badfile2`` | ``c.get_double_dash_args()`` |\n| arguments | | |\n| | | |\n+-----------------+----------------------------------------+----------------------------------------+\n\nApplication Logic Testing Methods\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n+-----------------+----------------------------------------+--------------------------------------------------------+\n| Test Type | Command Example | Tested With |\n+=================+========================================+========================================================+\n| Positional | ``$ spam eggs doit`` | ``c.has_command_sequence('eggs', 'doit')`` |\n| command | | |\n| sequence | | |\n+-----------------+----------------------------------------+--------------------------------------------------------+\n| Single switch | ``$ spam -s`` | ``c.contains_switches('s')`` |\n| | | |\n+-----------------+----------------------------------------+--------------------------------------------------------+\n| Multiple switch | ``$ spam -s --eggs`` | ``c.contains_switches('s', 'eggs')`` |\n| | | |\n+-----------------+----------------------------------------+--------------------------------------------------------+\n| Single | ``$ spam -o eggs`` | ``c.contains_definitions('o')`` |\n| definition | | |\n+-----------------+----------------------------------------+--------------------------------------------------------+\n| Multiple | ``$ spam -o eggs --with bacon`` | ``c.contains_definitions('o', 'with')`` |\n| different | | |\n| definitions | | |\n+-----------------+----------------------------------------+--------------------------------------------------------+\n| Multiple same | ``$ spam -o eggs -o bacon`` | ``c.contains_multi_definitions('o')`` |\n| definitions | | |\n| | | |\n+-----------------+----------------------------------------+--------------------------------------------------------+\n| Positional | ``$ spam eggs --coffee`` | ``c.has_args_after('eggs')`` |\n| argument | | |\n+-----------------+----------------------------------------+--------------------------------------------------------+\n| Acceptable | ``$ spam eggs toaster`` | ``c.next_arg_is_in('eggs', ['toaster', 'coffeepot'])`` |\n| positional arg | | |\n| | | |\n+-----------------+----------------------------------------+--------------------------------------------------------+\n\nCommand String Validation Methods\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n+-----------------+-------------------------+----------------------------------------------+\n| Test Type | Failure Example | Tested With |\n+=================+=========================+==============================================+\n| Missing | ``$ spam`` | ``c.does_not_validate_missing_args()`` |\n| arguments | | |\n| | | |\n+-----------------+-------------------------+----------------------------------------------+\n| Expected | ``$ spam eggs`` | ``c.does_not_validate_n_args(2)`` |\n| argument number | | |\n+-----------------+-------------------------+----------------------------------------------+\n| Missing opt-arg | ``$ spam -o --eggs`` | ``c.does_not_validate_missing_defs()`` |\n| definitions | | |\n| | | |\n+-----------------+-------------------------+----------------------------------------------+\n| Missing | ``$ spam eggs`` | ``c.does_not_validate_missing_switches()`` |\n| switches | | |\n| | | |\n+-----------------+-------------------------+----------------------------------------------+\n| Missing | ``$ spam -o eggs`` | ``c.does_not_validate_missing_mops()`` |\n| multi-option | | |\n| short syntax | | |\n| switches | | |\n+-----------------+-------------------------+----------------------------------------------+\n\n\nDevelopment with Commandlines\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nTo facilitate development with Commandlines, you can print the string\nreturned by the Command ``obj_string()`` method to view a list of the\nparsed arguments from example commands:\n\n.. code:: python\n\n from commandlines import Command\n\n c = Command()\n\n print(c.obj_string())\n sys.exit(0)\n\nFor example, if you execute your script with the command\n``spam eggs --toast -b --drink=milk filepath`` and include the above\nprint statement in your source, you will see the following in your\nterminal emulator:\n\n.. code:: shell\n\n $ spam eggs --toast -b --drink=milk filepath\n obj.argc = 5\n obj.arguments = ['eggs', '--toast', '-b', '--drink=milk', 'filepath']\n obj.defaults = {}\n obj.switches = {'toast', 'b'}\n obj.defs = {'drink': 'milk'}\n obj.mdefs = {}\n obj.mops = {}\n obj.arg0 = 'eggs'\n obj.arg1 = '--toast'\n obj.arg2 = '-b'\n obj.arg3 = '--drink=milk'\n obj.arg4 = 'filepath'\n obj.arglp = 'filepath'\n obj.subcmd = 'eggs'\n obj.subsubcmd = '--toast'\n\n\nAPI Documentation\n~~~~~~~~~~~~~~~~~\n\nYou can view full documentation of the Command class `here <https://commandlines.github.io/commandlines.library.html#commandlines.library.Command>`__.\n\nIf you would like to dig into lower level objects in the commandlines\npackage, you can view the `library API\ndocumentation <https://commandlines.github.io/commandlines.library.html>`__.\n\nExceptions that are used in the commandlines package are documented\n`here <https://commandlines.github.io/commandlines.exceptions.html>`__.\n\nHow to Include Commandlines in Your Project\n-------------------------------------------\n\nFor Projects That Will Be Distributed to Others\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nAdd the ``commandlines`` package dependency to your project ``setup.py``\nfile in the ``install_requires`` field like so:\n\n.. code:: python\n\n setup(\n ...\n install_requires=[\"commandlines\"],\n ...\n )\n\n\nThen, enter the following command to test your project locally:\n\n::\n\n $ python setup.py develop\n\nImport the ``commandlines`` package in your project and instantiate a\nCommand object by adding the following lines to your Python script:\n\n.. code:: python\n\n from commandlines import Command\n\n c = Command()\n\nAnd away you go...\n\nThe Commandlines package will be installed automatically for users who\ninstall your releases via ``pip`` or your project ``setup.py`` file\n(i.e. with the command ``$ python setup.py install``).\n\nFor Local Projects That Are Not Intended for Redistribution\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nInstall the Commandlines package with the command:\n\n::\n\n $ pip install commandlines\n\nImport the ``commandlines`` package in your project and instantiate a\nCommand object by adding the following lines to your Python script:\n\n.. code:: python\n\n from commandlines import Command\n\n c = Command()\n\nLicense\n-------\n\nCommandlines is licensed under the `MIT license <https://github.com/chrissimpkins/commandlines/blob/master/docs/LICENSE>`__.\n\n\n\n\n.. |Build Status| image:: https://travis-ci.org/chrissimpkins/commandlines.svg?branch=master\n :target: https://travis-ci.org/chrissimpkins/commandlines\n.. |Build status| image:: https://ci.appveyor.com/api/projects/status/nabadxorf9s8n0h5/branch/master?svg=true\n :target: https://ci.appveyor.com/project/chrissimpkins/commandlines/branch/master\n.. |codecov.io| image:: https://codecov.io/github/chrissimpkins/commandlines/coverage.svg?branch=master\n :target: https://codecov.io/github/chrissimpkins/commandlines?branch=master\n.. |Code Health| image:: https://landscape.io/github/chrissimpkins/commandlines/master/landscape.svg?style=flat\n :target: https://landscape.io/github/chrissimpkins/commandlines/master",
"bugtrack_url": null,
"license": "MIT license",
"summary": "Command line argument to object parsing library for command line application development",
"version": "0.4.1",
"split_keywords": [
"cli",
"command line",
"parser",
"shell",
"application",
"command line application",
"argument",
"argument parser"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "150b5f3f836614729f2e73f77f6d9342",
"sha256": "b7dbf71b8dec42c16e9694b87e0e121d288e5a40d5d4f0dd1c0651ab7af06837"
},
"downloads": -1,
"filename": "commandlines-0.4.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "150b5f3f836614729f2e73f77f6d9342",
"packagetype": "bdist_wheel",
"python_version": "2.7",
"requires_python": null,
"size": 18515,
"upload_time": "2016-02-27T00:17:17",
"upload_time_iso_8601": "2016-02-27T00:17:17.886612Z",
"url": "https://files.pythonhosted.org/packages/92/20/9fdf2c639119447ac03246ed3a04beb3c24aaf88d38f348e8c24375ec4aa/commandlines-0.4.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "01dbe2cdceadb62ec11bb2f12e9e5ab3",
"sha256": "86b650b78470ac95966d7b1a9d215c16591bccb34b28ae2bb9026c3b4166fd64"
},
"downloads": -1,
"filename": "commandlines-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "01dbe2cdceadb62ec11bb2f12e9e5ab3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 17434,
"upload_time": "2016-02-27T00:17:11",
"upload_time_iso_8601": "2016-02-27T00:17:11.352556Z",
"url": "https://files.pythonhosted.org/packages/b9/4c/d380f7f9aaa12175b189cfe087e823cd9aa2a99afc95a8d6e028142311c9/commandlines-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2016-02-27 00:17:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "chrissimpkins",
"github_project": "commandlines",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"landscape": true,
"appveyor": true,
"tox": true,
"lcname": "commandlines"
}
JSON
