zparser2 0.0.18

ZParser Cli Argument Library. Nothing comes after Z

ZParser2 Cli Argument Parsing Library

zparser2 is probably the simplest most opinionated argument parsing library in python. Lot's of conventions, zero configuration!

All you have to do is add the @z.task notation to a function and it automatically become available to the CLI.

Perks:

• If a function contains annotations, it's variable types will be enforced and proper help will be displayed to the user.
• If a function contains a docstring, it will show up as the function's comment in the CLI.
• The file in which the function is located will be the module in which the function will be available.
• If a module contains a docstring, it will show as the module's documentation in the CLI
• If a function is in the main python script (__main__), it will be directly accessible, without needing to provide the module name.
• You can access it using the cli or a web browser

The downside is that you can only have up to two layers in your cli (either app.py FUNCITON_NAME or app.py MODULE_NAME FUNCTION_NAME). If you need somethig more complex than that, please use something like https://pypi.org/project/click/ .

Instalation

pip3 install zparser2

Example

Let's say you have 3 files:

math_functions.py

"""here we do math"""
from zparser2 import z

@z.task
def duplicate_number(x: float):
    """returns twice the value of x"""
    return 2*x

@z.task
def triple_number(x: float):
    """returns 3 times the value of x"""
    return 3*x

string_functions.py

"""string processing"""
from zparser2 import z

@z.task
def add_square_brackets_to_string(x: str):
    """x -> [x]"""
    return f"[{x}]"

@z.task
def first_word(x: str):
    """returns the first word of a string"""
    return x.split(" ")[0]

@z.task
def last_word(x: str):
    """returns the last word of a string"""
    return x.split(" ")[-1]

@z.task
def another_task(somestring: str, some_int: int, workdir=None, root_url=None):
    """description of the task"""
    z.print(f"somestring={somestring}")
    z.print(f"some_int={some_int}")
    z.print(f"workdir={workdir}")
    z.print(f"root_url={root_url}")

mycli.py

#!/usr/bin/env python3
"""description of the __main__ module"""
from zparser2 import z, zparser2_init, __version__ as zparser2_version
import math_functions
import string_functions


@z.task
def say_hello(name: str):
    """this is a function on the main file"""
    z.print(f"Hello {name}, welcome to zparser2 {zparser2_version} !")

if __name__ == "__main__":
    zparser2_init()

Output

(env2) mdiez@batman:~/code/zparser2/example$ ./mycli.py
./mycli.py <task>
./mycli.py <plugin_name> <task>
Plugin list:
  math_functions       - here we do math
  string_functions     - string processing
Task list:
  say_hello            - this is a function on the main file

(env2) mdiez@batman:~/code/zparser2/example$ ./mycli.py string_functions
You need to specify a task
--------------------------------------------------------------------------------
string processing
./mycli.py string_functions <task>
Plugin alias: []
Tasks:
  add_square_brackets_to_string - x -> [x]
  another_task         - description of the task
  first_word           - returns the first word of a string
  last_word            - returns the last word of a string

(env2) mdiez@batman:~/code/zparser2/example$ ./mycli.py string_functions another_task
You need to specify the required arguments [somestring, some_int]
--------------------------------------------------------------------------------
description of the task
Usage:
  ./mycli.py string_functions another_task somestring some_int [--workdir workdir] [--root_url root_url]
Positional arguments:
  somestring -  <class 'str'>
  some_int -  <class 'int'>
Optional arguments:
  --workdir (Default: None)  -
  --root_url (Default: None)  -

(env2) mdiez@batman:~/code/zparser2/example$ ./mycli.py string_functions another_task blah 42 --root_url https://blah.com
somestring=blah
some_int=42
workdir=None
root_url=https://blah.com

(env2) mdiez@batman:~/code/zparser2/example$ ./mycli.py say_hello Bob
Hello Bob, welcome to zparser 2!

Using the Web Browser

For very simple tools, in very specific circunstances, you may want to run your zparser2 scripts via a web browser. Fear not. We've got you covered!

With some small modifications to mycli.py, we created zparser2_web.py which makes zparser2 a runs a Flask website.

To run the website in development mode, type:

• flask --app zparser2_web run --host 0.0.0.0 --reload

Please check the official Flask to run it in production.

Some technical notes on this topic:

• zparser2 generates a Flask compatible output, which means although you do need Flask to run and host your website, Flask is not a dependency to zparser2

• For you to use this feature, you need to use z.print() instead of print() in your functions, else the output will go to stdout instead of to the zparser2 flask website. If you are just using zparser2 for the cli, it does not matter.

• Lines are sent from the server to the browser one at a time (streamed), instead of all at once, just like in the cli.

Calling Functions from Flask

Sometimes, when using Flask, you want to call a function from a module that is using zparser2.

Theoretically, you could call the function directly, but then you would loose all output. Actually the output would be sent to stdout, which is usually to the logs and not to the browser.

If you create your function using z.print() instead of print (regardless of it having a @z.task on top or not, you can easily invoke it using Flask, like this:

# this is your normal flask file

import zparser2.web
import string_functions # that is from the zparser2 example

@app.route("/test_calling_a_zparser2_function")
def test_calling_a_zparser2_function():
    parameters = ["somestring", 42]
    title = "my page"

    return Response(parser2.web.flask_runner(string_functions.another_task, parameters, page_title=title))

WebSite Output

Main Website

---

Function say_hello, with input forms

---

Function output

How to build & publish

• python3 -m build
• python3 -m twine upload --repository testpypi dist/*
• python3 -m twine upload --repository pypi dist/*

Link

• https://pypi.org/project/zparser2/
• https://github.com/marcosdiez/zparser2/