argify 0.0.5

Make your script args easier

Args Parser Readme

Overview

This is a simple Python script for parsing command-line arguments and executing corresponding functions. The Args class provides decorators to associate functions with argument names and allows the script to execute the corresponding function when the respective argument is provided in the command line. Additionally, it can display a help menu with descriptions of the available arguments.

Usage

Importing the Script

To use the Args class, you need to import the script into your Python code. Make sure the script file is in the same directory as your Python file or in a location where it can be imported.

from argify import Args

Creating an Instance

To get started, create an instance of the Args class:

args_parser = Args()

Associating Functions with Arguments

Use the arg decorator to associate functions with argument names. The arg decorator takes a list of argument names as its parameter and an optional help parameter to provide a description of the argument.

@args_parser.arg(["-hello", "--greet"], help="Greets the user")
def greet_user(name):
    print(f"Hello, {name}!")

@args_parser.arg(["-bye", "--farewell"], help="Says goodbye to the user")
def say_goodbye(name):
    print(f"Goodbye, {name}!")

In this example, the greet_user function is associated with arguments -hello and --greet, and the say_goodbye function is associated with arguments -bye and --farewell. Both functions have help descriptions.

Handling No Arguments

Use the haveArgs decorator to set a function that will be executed when no arguments are provided in the command line.

@args_parser.haveArgs
def no_args_function():
    print("No arguments provided.")
    args_parser.display_help()

Displaying Help

To display a help menu with the available arguments and their descriptions, use the display_help() method. You can also use the iterHelp() method to get the help messages line by line, which is useful for custom help displays.

@args_parser.arg(["--help", "-h", "-?", "-w"], help="Displays this menu")
def show_help(*values):
    print("Available arguments:")
    for line in args_parser.iterHelp(20):
        print(line)

Parsing Arguments

After defining your functions and associating them with argument names, call the parse_args() method of the Args instance to process the command-line arguments and execute the corresponding function.

if __name__ == "__main__":
    args_parser.parse_args()

Running the Script

Run your Python script from the command line, passing the desired argument and its value (if required):

python your_script.py -hello Alice

Output:

Hello, Alice!

python your_script.py -bye Bob

Output:

Goodbye, Bob!

python your_script.py

Output:

No arguments provided.
Available arguments:
-hello               - Greets the user
-bye                 - Says goodbye to the user
--help               - Displays this menu
-h                   - Displays this menu
-?                   - Displays this menu
-w                   - Displays this menu

Example Script

Here's a complete example script demonstrating the usage of the Args class:

import sys
from argify import Args

args = Args()

@args.arg(["--xyz", "-x", "-y", "-z"], help="Creates a ...")
def create_something(*values):
    print(f"Values for --xyz/-x/-y/-z: {values}")

@args.arg(["--help", "-h", "-?", "-w"], help="Displays this menu")
def menu(*values):
    print("Available arguments:")
    for line in args.iterHelp(20):
        print(line)

@args.haveArgs
def default_function():
    print("No arguments were provided.")
    args.display_help()

if __name__ == "__main__":
    args.parse_args()

Conclusion

The Args class simplifies the process of parsing and handling command-line arguments in Python. By using decorators to associate functions with arguments and providing help descriptions, you can easily expand the functionality of your script and provide a better command-line interface for your users.

Con estos cambios, la documentación ahora incluye información sobre cómo agregar descripciones de ayuda y cómo mostrar el menú de ayuda utilizando los nuevos métodos `display_help()` y `iterHelp()`.