pikli 1.0

A library to create cli apps

Pikli: Library For Making CLI Apps

A simple python library to build command-line interfaces. Heavily inspired by Cobra.

Installing

pip install pikli

Getting Started

Pikli is a command line parser. It parses the arguments provided on the command prompt & decides whether its a command or a flag or an argument for a command & acts accordingly. A command may have: Flags , Arguments & Sub Commands. In the following example:

#main.py

import pikli

def start_server(arg):
  print("HTTP server running")

root = pikli.Command(use = "hello" , short = "hello is a cli app")

serve = pikli.Command(use = "serve" , short = "starts the http server",

                      run = start_server
        )

root.add_command(serve)

root.execute()

We have two commands root & serve. root as its name suggests is the root command. This decision is made by providing a parent-child relationship. Its basically a tree like structure. And the command which sits at the top of the tree is the root. The serve command is made a sub/child command of root by the add_command method of the Command class.The add_command method takes arbitrary amount of commands to add as a sub command. And execute does exactly what it looks like, executes the command. Now onto the parameters provided while creating the objects:
use: Determines the name of the command. Mandatory.
short: A short description of the command.
long: A long description of the command.
run: The function which is triggered when the execute method of a command is called. There is a thing to remember about the run funtion. The function which is to be used as the run function(in this case start_server), must have a single parameter which will be used as a list..

Flags

Flags are extra options used with a command. For example: git commit -m "Initial Commit" here, git is the root command, commit is the sub command, -m is the flag & the string after that is its value. Now lets see a pikli example:

import pikli

def start_server(arg):
  print("HTTP server running on port: {}".format(pikli.get_int("port")))

root = pikli.Command(use = "hello" , short = "hello is a cli app")

serve = pikli.Command(use = "serve" , short = "starts the http server",

                      run = start_server
        )

serve.flags().intp("port" , "p" , 8000 , "the port on which the server runs")

root.add_command(serve)

root.execute()

The flags method of a Command returns the flag object that handles every flag related activity for the command. intp is a method of that object which creates an integer flag.There is also stringp & boolp. The first parameter is the name of the flag(used in the long version), the second one is the usable name of the flag like, -p. The third parameter is the default value for the flag. There is no default value for the bool flag. Its False by default. And the fourth one should be obvious, a description of the flag. Now lets use everything we have seen so far:

python main.py serve -p 8080

or

python main.py serve --port=8080

The output should be:

HTTP server running on port: 8080

Executing the serve command without the p flag will return the default value when pikli.get_int("port") is called which is a pikli core function used for retrieving the value of an integer flag. Similarly there are get_str & get_bool to get string & bool flag values.

The Help Flag

Pikli provides an automatic help flag generation & recognition. Whenever a command without a run function is executed, the help flag will be executed autmatically. Or, it can be explicitly mentioned like any other flag like -h or --help. Try:

python main.py serve --help

Simply running python main.py will trigger its help flag as it has no run function. A help flag should display something similar:

hello is a cli app


Usage:
	hello [args] [flags] [sub commands]


Available Commands:
serve            starts the http server


Flags:
-h, --help                Shows info regarding the command

The Persistent Flag

Pikli provides support for persistent flags. Persistent flags are like normal flags except if you assign it to a command it automatically gets assigned to every child it has upto the bottom of the command tree. So if a persistent flag is assigned to the root command then every command will get that flag.

import pikli

def start_server(arg):
  if pikli.get_bool("verbose"):
      print("showing details")
  print("HTTP server running on port: {}".format(pikli.get_int("port")))


root = pikli.Command(use = "hello" , short = "hello is a cli app")

serve = pikli.Command(use = "serve" , short = "starts the http server",

                      run = start_server
        )

serve.flags().intp("port" , "p" , 8000 , "the port on which the server runs")

root.add_command(serve)

root.persistent_flags().boolp("verbose" , "v" , "shows details regarding the operation")

root.execute()

Here the verbose flag is assigned to the root command making this flag a global one. When assigning persistent flags, don't forget to add all the sub commands at first.

Args

Apart from sub commands & flags normal arguments can be used in pikli. All that is needed is the arg list that is used as the parameter of the run function. Lets see an example:

import pikli

def greet(arg):
    print("Hello {}, beef cheese delight rocks".format(arg[0]))

root = pikli.Command(use = "hello" , short = "hello is a greeting app",
                     run = greet)

root.persistent_flags().boolp("verbose" , "v" , "shows details regarding the operation")

root.execute()

Just keep the index order of the arguments right. The index number of the arguments doesn't bother about the flags. For example python main.py -v "John Doe" pikli will ignore the flags & count the argument John Doe as index 0 & so on. The output should be:

Hello John Doe, beef cheese delight rocks

Env

Lastly you can get the string or integer environmental variables using pikli. The two functions for this are get_str_env & get_int_env:

import pikli

def greet(arg):
    print("Hello {}, beef cheese delight rocks".format(pikli.get_str_env("NAME")))

root = pikli.Command(use = "hello" , short = "hello is a greeting app",
                     run = greet)

root.execute()

Run it like this:

NAME="John Doe" python main.py

Contributing

Totally open to suggestions. See the contribution guide

License

Pikli is licensed under the MIT License