pyxcute 0.4.1

Basic

Create a cute.py file like this:

from xcute import cute

cute(
        hello = 'echo hello xcute!'
)

then run:

>cute hello
hello...
hello xcute!

“hello” is the task to run. If cute.py is executed without a task name, it will run “default” task.

(If you get a “not a command” error, see How do I make Python scripts executable?)

Provide additional arguments:

>cute hello 123
hello...
hello xcute! 123

The arguments will be passed into the runner, which is xcute.Cmd.__call__ in this case.

Tasks

It can be a str:

from xcute import cute

cute(
        hello = 'echo hello'
)

If it match the name of another task, pyxcute will execute that task:

from xcute import cute

cute(
        hello = 'world',
        world = 'echo execute world task'
)

Use a list:

from xcute import cute

cute(
        hello = ['echo task1', 'echo task2']
)

Or anything that is callable:

from xcute import cute

cute(
        hello = lambda: print('say hello')
)

Actually, when you assign a non-callable as a task, pyxcute converts it into a callable according to its type. See xcute.Cmd, xcute.Chain, xcute.Throw., and xcute.Task

Task chain

Define the workflow with _pre, _err, _post, _fin suffix:

from xcute import cute

cute(
        hello_pre = 'echo _pre runs before the task',
        hello = 'echo say hello',
        hello_err = 'echo _err runs if there is an error in task, i.e, an uncaught exception or non-zero return code',
        hello_post = 'echo _post runs after the task if task successfully returned',
        hello_fin = 'echo _fin always runs after _post, _err just like finally'
)

When a task is involved, it will firstly try to execute _pre task, then the task itself, then the _post task. If the task raised an exception, then it goes to _err task. And finally the _fin task.

Pseudo code:

run(name + "_pre")
try:
        run(name, args)
except Exception:
        if run(name + "_err") not exist:
                raise
else:
        run(name + "_post")
finally:
        run(name + "_fin")

Format string

pyXcute expands format string with xcute.conf dictionary when the task is executed:

from xcute import conf, cute

conf["my_name"] = "world"

def edit_conf():
  conf["my_name"] = "bad world"

cute(
  hello_pre = edit_conf,
  hello = "echo hello {my_name}"
)

> cute hello
hello_pre...
hello...
hello bad world

xcute.conf

A dictionary used to format string. By the default, it has following keys:

• pkg_name - package name. See xcute.cute.

• date - datetime.datetime.now().

• tty - a boolean shows if the output is a terminal.

• version - version number. Available after Bump task. Also see pkg_name section in xcute.cute.

• old_version - version number before bump. Only available after Bump task.

• tasks - a dictionary. This is what you send to cute().

• curr_task - str. The name of current task.

xcute.cute

cute(**tasks)

The entry point.

Here are some special tasks:

• pkg_name - when this key is found in tasks, the key is removed and inserted into the conf dictionary.

  Then, cute() tries to find version number from {pkg_name}/__init__.py, {pkg_name}/__pkginfo__.py. If found, the filename is added to conf["version_file"], and the version is added to conf["version"].

  The regex used to match version number is decribed at xcute.split_version.

• version - if not provided, pyxcute uses Log("{version}") as default.

• bump - if not provided, pyxcute uses Bump("{version_file}") as default.

xcute.exc

exc(message=None)

Raise an exception. It reraises the last error if message is not provided.

from xcute import cute, exc

cute(
  ...
  task_err = ["handle error...", exc]
)

xcute.f

f(string)

Expand string with xcute.conf dictionary.

xcute.log

log(items)

A print function, but only works if conf["tty"] == False.

xcute.noop

noop(*args, **kwargs)

A noop.

xcute.split_version

split_version(text)

Split text into a (left, verion, right) tuple.

The regex pattern used to find version:

"__version__ = ['\"]([^'\"]+)"

xcute.Bump

Bump task can bump version number in a file, using xcute.split_version and semver.

from xcute import cute, Bump

cute(
        bump = Bump('path/to/target/file')
)

then run

cute bump [major|minor|patch|prerelease|build]

the argument is optional, default to patch.

xcute.Chain

This task would run each task inside a task list.

Chain(*task_list)

Tasks are converted to Chain if they are iterable.

xcute.Cmd

This task is used to run shell command.

Cmd(*shell_command)

Tasks are converted to Cmd if they are str.

xcute.Log

A wrapper to print. It is useless if you can just "echo something".

Log(*text)

xcute.Task

This task executes another task.

Task(task_name)

Tasks are converted to Task if they are keys of tasks dictionary.

xcute.Throw

This task throws error.

Throw()
Throw(error)
Throw(exc_cls, message=None)

1. Reraise last error.

2. Raise the error.

3. Raise exc_cls(message)

Tasks are converted to Throw if they are subclass or instance of BaseException.

xcute.Try

This task suppress exception.

Try(*task)