Welcome to Commandeer’s documentation!¶
DEPRECATION NOTICE: This project is deprecated and will not be maintained. Please refer to the excellent click for a similar tool.
Commandeer is a command-line generator library that you can use to add a nice command line interface to your python programs.
It will take care of parsing all command line options as well as calling the right command functions in your script. And it will generate a nice-looking help for the program and for each of the commands.
- We’ve written Commandeer in such a way that it should work just like you expect it to. There are only two things you need to do:
name the functions you want to expose on the command line to end in
_command
.Add the following code snippet to the end of your command line module:
import commandeer if __name__ == '__main__': commandeer.cli()
You should try it out!
However, if you you’re new to Commandeer, you can also continue with our tutorial.
Or have a look at the example containing everything.
Or, if you’re looking for specific information, have a look at the feature documentation.
As a quick start, here’s how a sample script could look like [1]:
"""This is a sample script that shows two commands and how to call them from Commandeer."""
import commandeer
import datetime
def log_command(logcode, logmessage, timestamp=True, indent=0):
"""Outputs the input, with an optional timestamp and some indenting.
All of the input arguments are simply output on the standard out. If you specify indenting,
the output will be prepended by that number of spaces. If you set timestamp to True, the
output will be prepended by '[timestamp]'.
@param logcode The topic or code that this log will be added to.
@param logmessage The message that will get logged
@param timestamp Add a timestamp to the output. A real timestamp.
@param indent The number of spaces the output should be indented by.
"""
echo_str = "[{}] {}".format(logcode, logmessage)
if timestamp:
echo_str = "[{}] {}".format(str(datetime.datetime.now()), echo_str)
echo_str = " " * indent + echo_str
print(echo_str)
if __name__ == '__main__':
commandeer.cli()
And what does that give us? Have a look at the following session to get a feeling for the result:
$ python sample.py
This is a sample script that shows two commands and how to call them from Commandeer.
Usage: sample.py command [options]
Here are the commands you can try:
help Show this help screen.
log Outputs the input, with an optional timestamp and some indenting.
If you need help on any of them, try "sample.py help command" for any of them.
$ python sample.py log info "Hello World"
[2012-09-06 12:41:00.157822] [info] Hello World
$ python sample.py log warn "ions destabilized" --indent 2
[2012-09-06 12:41:15.924351] [warn] ions destabilized
$ python sample.py log warn "ions destabilized" --indent 2 --notimestamp
[warn] ions destabilized
- In short, it will give you:
- a help message that is output when you call your program without arguments or with the single argument help
- command matching: the first argument that does not start with
-
selects the function you want to call - argument matching: all arguments that do not start with - get passed to your program as arguments
- keyword matching: all arugments that start with - get passed to your program as switches. The number of dashes is ignored.
License¶
Copyright (C) 2012 Johannes Spielmann
Commandeer is licensed under the terms of the GNU General Public Licenses as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.
For a full description of the license, please see the file
LICENSE
as included with the source distribution of Commandeer.