# Python Job Connector

## Overview

Zuar Runner can automate Python scripts via the Python job type.

.. image:: assets/python-1.png
   :alt: Zuar Runner Python Job

## Python Considerations

- **Python Version**: Scripts must be written using Python 3.
- **Logging**: Anything your Python script sends to `stdout` or `stderr` (e.g. via a `print()` statement) will be added to the job's log. This is extremely helpful for debugging and displaying progess while the job runs and after it completes.
- **Libraries**: See the *Python Virtual Environments and Requirements* section below if your script imports libraries not included in Python itself.

## Upload a Python Script to Zuar Runner

Python scripts must exist on Zuar Runner's file system. There are two options for uploading scripts:

1. Copy/paste the script into the **Python File Body** field in the Python job wizard while creating the job.
2. Use Zuar Runner's :ref:`files` to first upload the script. Then point the job to the uploaded script using the **Python File Path** field in the Python job wizard.

## Python Virtual Environments and Requirements

Your Python job will run in an isolated Python virtual environment. We use [Python's venv module](https://docs.python.org/3/library/venv.html) to create virtual environments. Virutal environments allow installing Python libraries not included in Python's standard libraries. A `requirements.txt` file is used to specifiy which libraries to include and optionally specify library exact or miniumum versions.

When creating a job via the Python job wizard, you can create a *new* virtual environment and `requirements.txt` file or specify an *existing* environment/file. If you have multiple jobs that can use the same enviroment, specify the existing environment and corresponding `requirements.txt` file to prevent maintaining multiple instances.

> Any libraries that are imported into your script *not* listed in the [Python standard library ](https://docs.python.org/3/library/index.html) must be included in `requirements.txt`.

## Create a Python Job

Click **+Add Job** in the lower-left corner of Runner's admin interface:

.. image:: assets/command-line__add_job.png
  :alt: Add Job Button

Choose "**Python**" job:

.. image:: assets/python_job.png
  :alt: Python Job Icon

Complete the wizard:

.. image:: assets/python_wizard_1.png
  :alt: Python Wizard One of Three

- **Title** - Provide a title that describes the purpose of the job.
- **Python File Path** - Path to the Python script. If your Python script hasn't been uploaded to Runner's filesystem, leave the auto-generated file path as-is **or** replace the timestamp-based path. The code entered in the **Python File Body** field below will be stored at this file path. If your script *already exists within the Runner filesystem*, specify its file path here and leave **Python File Body** *blank*.
- **Python File Body** - Can be empty. In this case, the contents of the **Python File Path** file will be read. Otherwise, the file will be created or overwritten with the code placed in this field.

.. image:: assets/python_wizard_2.png
  :alt: Python Wizard Two of Three

- **Venv Dir** -  Path to the virtual environment directory. Will be created if it does not exist. If the job should use an existing environment, enter the directory here.
- **Requirements File Path** - Path to the `requirements.txt` file. Will be created with the code in the **Requirements Body** field below, if the file does not exist. If the job should use an existing environment, enter the path to the `requirements.txt` file here.
- **Requirements Body** - The environment's `requirements.txt` file content, if being created. Can be empty. In this case, the contents of the `requirements_file_path` file will be read. Otherwise, the file will be created or overwritten with the libraries listed here. [Format reference](https://pip.pypa.io/en/stable/user_guide/#requirements-files)
- **Use pip cache?** - Enable/disable [pip's cache](https://pip.pypa.io/en/stable/topics/caching/).

.. image:: assets/python_wizard_3.png
  :alt: Python Wizard Three of Three

- **Environment Variables** - Add/Delete environmental variables that should be loaded into the virual environment when the job runs.
- **Timeout** - The duration, in seconds, to wait before terminating the job if it has not finished.

Optionally check **Start job on save** and then click the **Save** button to create the job.