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.

Content
-------

.. toctree::
   :maxdepth: 2

   xtern
   utils

Install
-------

**pyxtern** can be installed either by using pip or by downloading the sources
from the `Gitlab <https://gitlab.com/mar.grignard/pyxtern>`_.

**Using pip**
        .. code-block:: shell

                pip install pyxtern

**Installing from sources**
        .. code-block:: shell

                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:

.. code-block:: python

        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:

.. code-block:: shell

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