fabric and help
After discovering how cool Capistrano is for use with Rails, I went looking for a python equivalent for django. While it’s not specifically focusing on django, that equivalent is fabric. It’s decent though it a bit rudimentary in comparison to Capistrano. Things like only having a single namespace and how you pass arguments to verbs are my biggest complaints.
One of the neat things about python is it’s use of doc strings for generating documentation. Fabric makes some use of docs strings for outputting help but it again feels a bit clunky. For example, when you use the -l option on fabric, it lists the command verbs (implemented as functions) along with the first line of the doc string associated with a command.
So:
[host:~/Projects/server] user% fab -l
Available commands: clean_db Deletes existing db, runs syncdb, adds user. NO... clean_up Clean up byte compiled files and emacs backups. dump_data Dumps the existing data to a file.
And if you wanted more detail, you’d need to add the -d option for a specific command:
[host:~/Projects/server] user% fab -d clean_db Displaying detailed information for command 'clean_db': Deletes existing db, runs syncdb, adds user. NOTE: DATA LOSS
def help(command): from fabric.main import display_command
display_command(command)
Which allows me to do this and get the same results by asking for help:
[host:~/Projects/server] user% fab help:clean_db Displaying detailed information for command 'clean_db': Deletes existing db, runs syncdb, adds user. NOTE: DATA LOSS
While still a little clunky, it feels more natural to just ask fabric for help this way.
So to sum up, users interfaces are extremely important. I think we all need to remember that when writing software. Verbs feel easier to use than command line flags. Granted, it’s nice for me to be able to hack my own interface for use the way I like, but it’s always just simpler to lead the user down the right path.
I’m impressed, I must say. Actually rarely must i encounter a blog that’s both educative and entertaining, and without a doubt, you may have hit the nail within the head. Your thought is outstanding; the catch is something that insufficient folks are speaking intelligently about. I’m very happy i always came across this around my hunt for something about it.