Skip to main content

Simple CLI entrypoint and argument parsing.

Project description

CLIEP Python Console Entrypoint Library

CLIEP (CLI Entrypoint) is a small, no dependency system to streamline interfacing with TTYs and consoles, using a primary entrypoint function via decorators with optional automatic argument parsing.

Installation:

pip install cliep

It is recommended you use a virtualenv for individual project's dependencies. You can also add cliep to your requirements.txt for larger projects.

Documentation:

The cliep namespace contains two important elements: entrypoint, and Argument.

entrypoint:
	arg_map - the list of arguments to parse and send to the entrypoint.
	help_func - function to handle printing the help page on err/trigger. Uses builtin help generator by default.
	help_trigger - The flag to trigger help off of, defaults to '-h'. NOTE: this overrides any arguments that share the same name.

Entrypoints are also required to type hint that they return either int or None, otherwise the entrypoint will not be allowed to run.

Argument:
	shortname: str - Required, specifies the shorthand command name ('-a', '-b', etc).
	longname: str - Optional, allows for a second proper command name ('--append').
	is_flag: bool - Specifies whether or not the argument is expecting a value, defaults False.
	is_required: bool - Specifies whether or not this argument must be found, defaults False.
	default: any - Specifies a default value for optional arguments that are not supplied.

These two elements make up the entirety of the use case CLIEP hopes to solve. This allows for auto-parsing of arguments and feeding them into the specified entrypoint.

An important note: When using Arguments the values of each Argument are passed into the entrypoint in the order they are added. e.g. arguments a, b, c will be sent to the entrypoint as a, b, c. Furthermore, arguments use the type hinting of the entrypoints parameters to typecast before sending. So type hints are required for custom argument parsing.

An example of this is as follows:

@entrypoint([Argument('-a')])
def main(a: int) -> int:
	return a

This example will only work as long as the a parameter is type hinted.

This extensive use of type hinting is present in order to remove a guessing game of what is being passed back and forth, and to lower possible points of failure.

If bad data is supplied to a type casted argument (e.g. str -> int), then the value will be set to the ValueError thrown, and forwarded to the entrypoint. This is so that the proper entrypoint can handle informing the user of bad input, or manually setting a default value. Although this may not be the most elegant solution, this allows for proper error handling in cases where the type cast is wanted or required.

If a type hint in the entrypoint is list or dict (or the generic counterparts), CLIEP will raise a NotImplementedError due to complications with Pythons preprocessing or argv.

In cases where you want to override the default help output, help_func should expect:

error: str = Error text in case of missing required field.
args: List[Argument] - The list of argument objects.
trigger: str - The trigger phrase that is used to trigger the help screen.

Examples:

In it's most basic form, an entrypoint looks like this:

from cliep import entrypoint

@entrypoint
def main(argv, argc) -> int:
    return 0

You see without custom argument parsing, the entrypoint will just forward the argv and len(argv) to the entrypoint. Another important thing to notice is the use of type hinting. CLIEP uses type hinting to enforce returns to the TTY. As such, an entrypoint function must either type hint a return of type "int" or type "None".

A more complicated example could look like this:

from cliep import entrypoint, Argument

@entrypoint([
    Argument('-f', '--flag', is_flag=True),
    Argument('-i', '--input', required=True),
])
def main(flag: bool, user_input: int) -> int:
    print(flag, user_input)
    return user_input or 0

In this example we further the use of type hinting, as the Arguments in the list are passed to the entrypoint function in order of their place in the list, and as the values of each Argument are gathered, they use the type hints in the main function declaration to know what to type cast too. Because of this, in an entrypoint function all arguments must have a type hint.

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

cliep-1.0.1.tar.gz (4.8 kB view details)

Uploaded Source

Built Distribution

cliep-1.0.1-py3-none-any.whl (17.5 kB view details)

Uploaded Python 3

File details

Details for the file cliep-1.0.1.tar.gz.

File metadata

  • Download URL: cliep-1.0.1.tar.gz
  • Upload date:
  • Size: 4.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.13.0 pkginfo/1.5.0.1 requests/2.21.0 setuptools/40.8.0 requests-toolbelt/0.9.1 tqdm/4.31.1 CPython/3.7.2

File hashes

Hashes for cliep-1.0.1.tar.gz
Algorithm Hash digest
SHA256 dc62cbbc462a6cba16382e98dab786a1f0ee7b6d1711b90ba1e62da227621274
MD5 ca77c8a8cda7a75be45e09fdfc9152fa
BLAKE2b-256 af10a40227978b1e3e7545565df39ce7506410d8a41206de5ee68c0ed1b1860b

See more details on using hashes here.

File details

Details for the file cliep-1.0.1-py3-none-any.whl.

File metadata

  • Download URL: cliep-1.0.1-py3-none-any.whl
  • Upload date:
  • Size: 17.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.13.0 pkginfo/1.5.0.1 requests/2.21.0 setuptools/40.8.0 requests-toolbelt/0.9.1 tqdm/4.31.1 CPython/3.7.2

File hashes

Hashes for cliep-1.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 c3a48434a687947d7683bc7964a5874b24fd9cbeee89cb8622112b9f19a1adc3
MD5 60f1598ebf53cb549030abe6ea9c228d
BLAKE2b-256 494f59d3a818f06afd76818de31c2a96b3b80f1f3960e64c3168167ce37c5fba

See more details on using hashes here.

Supported by

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