Skip to main content

A library to create cli apps

Project description

Pikli: Library For Making CLI Apps

Build Status License Project status Python 3.7

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

Project details


Release history Release notifications

This version

1.0

Download files

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

Files for pikli, version 1.0
Filename, size File type Python version Upload date Hashes
Filename, size pikli-1.0.tar.gz (11.7 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page