Basic I/O
=========

Stdout and stderr
-----------------
Stdout and stderr in your running program will be sent back to the stdout and stderr of your ``lager python`` process.

.. code-block:: python
   :caption: stdio.py
   :name: Script that prints to stdout and stderr

   import sys
   print('This is stdout')
   print('This is stderr', file=sys.stderr)

Save this as ``stdio.py``. Then, we'll run it and redirect the output streams to files: ``lager python stdio.py > stdout 2> stderr``

.. code-block:: console

    ➜  lager python stdio.py > stdout 2> stderr
    ➜  cat stdout
    This is stdout
    ➜  cat stderr
    This is stderr

Setting exit codes
------------------

The exit code of ``lager python`` will be set to the exit code of your script. This can be used to check success or failure, which is particularly useful in a headless or automated environment such as `Continuous Integration <https://docs.lagerdata.com/ci/>`_.

.. code-block:: python
   :caption: failure.py
   :name: Script that sets non-zero exit status

   print('Hello, world!')
   raise SystemExit('Failed!')

Save this as ``failure.py``. Then, we'll run it using ``lager python failure.py``

.. code-block:: console

    ➜  lager python failure.py
    Hello, world!
    Failed!
    ➜  echo $?
    1

``$?`` is a special shell environment variable that holds the exit status of the most recent command. Since it is non-zero, that means the program exited with an error.

Command line arguments
----------------------

Command-line arguments can be sent to your ``lager python`` program. Use a ``--`` to demarcate the end of the ``lager python`` arguments and the arguments for your program.

.. code-block:: python
   :caption: arguments.py
   :name: Script that prints command line arguments

   import sys
   print(sys.argv[1:])

Save this as ``arguments.py``. Then, we'll run it using ``lager python arguments.py -- arg1 arg2 arg3 --option 4 'foo bar'``

.. code-block:: console

    ➜  lager python arguments.py -- arg1 arg2 arg3 --option 4 'foo bar'
    ['arg1', 'arg2', 'arg3', '--option', '4', 'foo bar']


Environment variables
---------------------

You can also set environment variables that will be accessible within your ``lager python`` program. There are two different ways to set environment variables - ``--env VAR=VALUE`` syntax is used to directly set a variable named ``VAR`` to ``VALUE``. ``--passenv FOO`` can be used to pass the value of an environment variable named ``FOO`` that is already defined. This is especially useful with `Continuous Integration <https://docs.lagerdata.com/ci/>`_, when you may have secrets that exist in your environment that you do not wish to expose on the command line

.. code-block:: python
   :caption: env.py
   :name: Script that prints environment variables.

   import os
   print(f'FOO = {os.environ["FOO"]}')
   print(f'BAZ = {os.environ["BAZ"]}')

Save this as ``env.py``. Then, we'll run it using ``FOO=BAR lager python env.py --passenv FOO --env BAZ=qux``. 

.. code-block:: console

    ➜  FOO=BAR lager python env.py --passenv FOO --env BAZ=qux
    FOO = BAR
    BAZ = qux