Skip to main content

Command line argument to object parsing library for command line application development

Project description

commandlines Build Status Build status Code Health

Source Repository: chrissimpkins/commandlines


What is Commandlines?

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 [*] command argument styles, the GNU argument style extensions to the POSIX guidelines (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.

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:

from commandlines import Command

c = Command()

and use the following instance attributes and methods to develop your application:


Command Line Arguments

Command Example

Accessed/Tested With

Length of arg list

$ spam eggs -t --out file

c.argc == 4

Command suite sub-commands

$ spam eggs

c.subcmd == "eggs"

Command suite sub-sub-commands

$ spam eggs overeasy

c.subsubcmd == "overeasy"

Short switch syntax

$ spam -e


Long switch syntax

$ spam --eggs


Multiple switches

$ spam -e --eggs

c.contains_switches('e', 'eggs')

Short opt-arg definition syntax

$ spam -o eggs


Long opt-arg definition syntax

$ spam --out eggs


Alt long opt-arg definition syntax

$ spam --out=eggs


Multiple same option definitions

$ spam -o eggs -o omelets


Multi-option short syntax switches

$ spam -mpns eggs


Next positional argument

$ spam eggs test/path


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 Argument

Command Example

Accessed/Tested With

Positional argument at index 0

$ spam eggs


Positional argument at index 1

$ spam eggs bacon


Positional argument at index 2

$ spam eggs bacon toast


Positional argument at index 3

$ spam eggs bacon toast cereal


Positional argument at index 4

$ spam eggs bacon toast cereal milk


Last positional argument

$ spam eggs -b --toast filepath


All positional arguments

$ spam eggs -b - -toast filepath


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
from commandlines import Command

c = Command()

c.defaults['output'] = "test.txt"
c.defaults['level'] = 10
Method-Based Default Assignments
from commandlines import Command

c = Command()

default_options = {
    'output' : 'test.txt',
    'level'  : 10

To test for the presence of a default option definition and obtain its value, use the contains_defaults and get_default methods, respectively:

# continued from code examples above

if c.contains_definitions('output'):
elif c.contains_defaults('output'):

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


Help request, long

$ spam --help


Usage request

$ spam --usage


Version request, short

$ spam -v


Version request, long

$ spam --version


Testing Methods for Other Commonly Used Switches

Test Type

Command Example

Tested With

Verbose standard output

$ spam eggs --verbose


Quiet standard output

$ spam eggs --quiet


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 Idioms

Command Example

Accessed/Tested With

Double dash idiom

$ spam eggs -- -badfile


Double dash arguments

$ spam eggs -- -badfile -badfile2


Application Logic Testing Methods

Test Type

Command Example

Tested With

Positional command sequence

$ spam eggs doit

c.has_command_sequence('eggs', 'doit')

Single switch

$ spam -s


Multiple switch

$ spam -s --eggs

c.contains_switches('s', 'eggs')

Single definition

$ spam -o eggs


Multiple different definitions

$ spam -o eggs --with bacon

c.contains_definitions('o', 'with')

Multiple same definitions

$ spam -o eggs -o bacon


Positional argument

$ spam eggs --coffee


Acceptable positional arg

$ spam eggs toaster

c.next_arg_is_in('eggs', ['toaster', 'coffeepot'])

Command String Validation Methods

Test Type

Failure Example

Tested With

Missing arguments

$ spam


Expected argument number

$ spam eggs


Missing opt-arg definitions

$ spam -o --eggs


Missing switches

$ spam eggs


Missing multi-option short syntax switches

$ spam -o eggs


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:

from commandlines import Command

c = Command()


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:

$ 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.

If you would like to dig into lower level objects in the commandlines package, you can view the library API documentation.

Exceptions that are used in the commandlines package are documented here.

How to Include Commandlines in Your Project

For Projects That Will Be Distributed to Others

Add the commandlines package dependency to your project file in the install_requires field like so:


Then, enter the following command to test your project locally:

$ python develop

Import the commandlines package in your project and instantiate a Command object by adding the following lines to your Python script:

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 file (i.e. with the command $ python 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:

from commandlines import Command

c = Command()


Commandlines is licensed under the MIT license.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

commandlines-0.4.1.tar.gz (17.4 kB view hashes)

Uploaded source

Built Distribution

commandlines-0.4.1-py2.py3-none-any.whl (18.5 kB view hashes)

Uploaded 2 7

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page