barim 0.1.1

Description:

barim 0.1.1

Barim






Barim is a Python library that helps building CLI applications.
The Barim API makes it easy to build terminal app that have one or more commands.
Requirements

Python (3.7.X or later)

Dev requirements

Git (latest version)
Python (3.7.X or later)
Poetry (latest version)

Installing
Install with pip.
python -m pip install barim

Install with poetry.
poetry add barim

Quickstart
This following section is dedicated to explain how barim can be used to
create a simple CLI application. We will see how to make a terminal application
with a default command and how we can update it to allow multiple subcommand.
Create your first command
The first step will be to create a class that inherit from barim.Command and
provide some values to the class attributes.
# File name: example.py
from types import SimpleNamespace

from barim import Command


class MyCommand(Command):

name = "example.py"
description = "Print 'Hello, World!'"
version = "0.1.0"

def handle(self, argv: SimpleNamespace, opts: SimpleNamespace) -> None:
print("Hello, World!")

Take note that the class attributes 'description' and 'version' aren't mandatory.
Only 'name' is.

The handle() method must be override has it will be the entry point for your
software. The argv and opts parameters are two SimpleNamespace that contain
all the arguments (argv) and all the options (opts) declared in the
command class. To see how to use them check out the Barim API or just continue
the quickstart guide.

The next logical step now is just to tell barim to run the command when the
script is run. This can be done like the following.
from types import SimpleNamespace

from barim import Application, Command


class MyCommand(Command):

name = "my_command"
description = "Print 'Hello, World!'"
version = "0.1.0"

def handle(self, argv: SimpleNamespace, opts: SimpleNamespace) -> None:
print("Hello, World!")


# Notice we add a main method to be called once the script is runned
def main() -> None:
application = Application(name="example.py")
application.register(MyCommand)
application.run(default=True)


if __name__ == "__main__":
main()

That should be all ! You can now test your CLI application by running the
following command.
python example.py --help

The output of the command should be:
example.py version 0.1.0

DESCRIPTION
Print 'Hello, World!'

USAGE
example.py [-h] [-V] [-v]

GLOBAL OPTIONS
-h (--help) Display help message
-V (--version) Display version number
-v (--verbose) Display more log message


Something to notice here is that the output doesn't show any colors (in this README)
which will not be the case on the terminal.

Add arguments and options to the command
Let's say now that we want to take a string as an argument to print 'Hello, {input}!'.
For this we need to declare another class variable named 'arguments' that
is a list of barim.Argument.
from types import SimpleNamespace

from barim import Application, Argument, Command


class MyCommand(Command):
name = "my_command"
description = "Print 'Hello, {input}!'"
version = "0.1.0"

arguments = [
Argument(
name="input",
description="Use input string in print statement"
),
]

def handle(self, argv: SimpleNamespace, opts: SimpleNamespace) -> None:
# Make use of the newly added argument
print(f"Hello, {argv.input}")


def main() -> None:
application = Application(name="example.py")
application.register(MyCommand)
application.run(default=True)


if __name__ == "__main__":
main()


Note that you can declare a barim.Argument or by providing the needed data
during initialization like in the example above or by subclassing it and declaring the data as class variable.

You should now be able to run your script like the following.
python example.py Demo

Expected output:
Hello, Demo!

Now when it comes to options, it doesn't change that much. Instead of declaring
arguments you declare options and provide a list of barim.Option.
In our example let's say we want to turn all the letter uppercase.
from types import SimpleNamespace

from barim import Application, Argument, Command, Option


class MyCommand(Command):
name = "my_command"
description = "Print 'Hello, {input}!'"
version = "0.1.0"

arguments = [
Argument(
name="input",
description="Use input string in print statement"
),
]
options = [
Option(
short="u",
long="upper",
description="Turn all the letter uppercase",
),
]

def handle(self, argv: SimpleNamespace, opts: SimpleNamespace) -> None:
# Make use of newly added option
input_ = argv.input
if opts.upper:
input_ = input_.upper()

print(f"Hello, {input_}")


def main() -> None:
application = Application(name="example.py")
application.register(MyCommand)
application.run(default=True)


if __name__ == "__main__":
main()

Now run your script as below.
python example.py demo --upper

Expected output:
Hello, DEMO!

Create subcommands
The default parameter declare earlier in application.run(default=True) indicate that we only have one registered
command and that we want to use it as the default one. By removing this parameter we can now register multiple command
to act as multiple sub command.
from types import SimpleNamespace

from barim import Application, Argument, Command, Option


class MyCommand(Command):
name = "my_command"
description = "Print 'Hello, {input}!'"
version = "0.1.0"

arguments = [
Argument(
name="input",
description="Use input string in print statement"
),
]
options = [
Option(
short="u",
long="upper",
description="Turn all the letter uppercase",
),
]

def handle(self, argv: SimpleNamespace, opts: SimpleNamespace) -> None:
input_ = argv.input
if opts.upper:
input_ = input_.upper()

print(f"Hello, {input_}")


class MyOtherCommand(Command):
name = "my_other_command"
description = "Print 'Hello, World!'"
version = "0.1.0"

def handle(self, argv: SimpleNamespace, opts: SimpleNamespace) -> None:
print("Hello, World")


def main() -> None:
application = Application(name="example.py")
application.register(MyCommand)
application.register(MyOtherCommand)
application.run()


if __name__ == "__main__":
main()

Create command dynamically
As seen before, to create a command, we have to subclass barim.Command.
But this is not the only way we can create them. In any case you need to create them,
for example on the fly, you could do it like in the following example.
from types import SimpleNamespace

from barim import Application, Command


def my_command_handle(argv: SimpleNamespace, opts: SimpleNamespace) -> None:
print("Hello, World")


def main() -> None:
my_command = Command(name="my_command", description="Print 'Hello, World!'", handle=my_command_handle)

application = Application(name="example.py")
application.register(my_command)
application.run(default=True)


if __name__ == "__main__":
main()

The output of the command should look like the following:
example.py version 0.1.0

DESCRIPTION
Print 'Hello, World!'

USAGE
example.py [-h] [-V] [-v]

GLOBAL OPTIONS
-h (--help) Display help message
-V (--version) Display version number
-v (--verbose) Display more log message