A small package to run external command lines.

pip install pyxtern==2.0.0



This package provides decorators and methods to run any external command line in a proper maner. It allows the creation of any command line python interface with ease.

How to install

Since pyxtern is hosted on PyPI, it can be installed using:

pip install pyxtern

How to use

The package offers two different ways to run a command line through python script:

  1. Use the run() function:
from pyxtern import run
# To run the following command:
# $ find . -name *.py
# Use either:
exit, stdout, stderr = run("find . -name *.py")
# Or:
exit, stdout, stderr = run(["find", ".", "-name", "*.py"])
  1. Use the @xtern decorator:
from pyxtern import xtern, format_arg
# To wrap the 'find' command:
# $ find . -name *.py
def cmd_find(*args, **kwargs):
        cmd = ["find"]
        cmd.append(kwargs.get("path", "."))
                val=kwargs.get("expr", None),
                fmt="- "))
        return cmd
# Now to use it simply write:

The more complete example for the find command is available here.


The run() function accepts some arguments:

  • dir: The directory where you want to create the temporary directory in which the external command will be ran. If None, the system default temporary directory is used.
  • tee: If set to True, the stdout and stderr streams of the external command are rederected to the current stdout and stderr.
  • log: A tuple givind (stdout, stderr) for the caller. If they are provided, the stdout and stderr streams of the external command are rederected to these.

Both tee and log can be used at the same time.
When you use the @xtern decorator, these arguments can be passed to the function through **kwargs.


As shown before, the run() function has 3 return values:

  • exit: The exit code of the external command.
  • stdo: The stdout of the external command.
  • stde: The stderr of the external command.