Welcome to pyxtern’s documentation!

Introduction

pyxtern is a lightweight package that provides different useful tools to call any external command from python script in a clean and secure way.

Built around standard libraries, it has no external dependencies hence it is very easy to include it to any of your project.

It also makes it easy to create a custom API for any of your favorite command line based softwares.

Install

pyxtern can be installed either by using pip or by downloading the sources from the Gitlab.

Using pip
pip install pyxtern
Installing from sources
git clone https://gitlab.com/mar-grignard/pyxtern.git
cd pyxtern
python3 setup.py install

Example

The following example shows the different options pyxtern provides for runninn an external command:

import os
import pyxtern as px

# run() #
cmd = ["find", "./pyxtern", "-name", "*.py"]

# The run() function synchronously
exit, out, err = px.run(cmd, tee=True)

# The run() function asynchronously
find_runner = px.run(cmd, tee=True, sync=False)
# Do some stuff
exit, out, err = find_runner.end()

# Cmd() #
cmd = px.Cmd("find").append("./pyxtern").add_arg(arg="name", val="*.py", prefix="-")

# The Cmd() class synchronously
exit, out, err = px.run(cmd, tee=True)  # Using the run function
exit, out, err = cmd.run(tee=True)      # Using the run method

#The Cmd() class asynchronously
find_runner = px.run(cmd, tee=True, sync=False) # Using the run function
find_runner = cmd.run(tee=True, sync=False)     # Using the run method
# Do some stuff
exit, out, err = find_runner.end()

# @xtern #
@px.xtern
def find_external(*args, **kwargs):
        cmd = Cmd("find")
        dir = kwargs.pop("dir", ".")
        cmd.append(os.path.abspath(dir))
        cmd.add_arg(kwargs=kwargs, arg="name", prefix="-", default=None)
        return cmd

# The @xtern decorator synchronously
exit, out, err = find_external(dir="./pyxtern", name="*.py", tee=True)

# The @xtern decorator asynchronously
find_runner = find_external(dir="./pyxtern", name="*.py", tee=True, sync=False)
# Do some stuff
exit, out, err = find_runner.end()

All those examples will print:

./pyxtern/xtern.py
./pyxtern/__init__.py
./pyxtern/utils.py