arca 0.3.3
A library for running Python functions (callables) from git repositories in various states of isolation with integrating caching.
License: MIT
Keywords: sandboxing,git,docker,vagrant

Arca
====

.. image:: https://img.shields.io/travis/pyvec/arca.svg
   :target: https://travis-ci.org/pyvec/arca

.. image:: https://img.shields.io/codecov/c/github/pyvec/arca.svg
   :target: https://codecov.io/gh/pyvec/arca

.. image:: https://img.shields.io/pypi/v/arca.svg
   :target: https://pypi.org/project/arca/

.. image:: https://img.shields.io/github/license/pyvec/arca.svg?style=flat
   :target: https://github.com/pyvec/arca/blob/master/LICENSE

.. image:: https://img.shields.io/readthedocs/arca.svg
   :target: https://arca.readthedocs.io/

Arca is a library for running Python functions (callables) from git repositories in various states of isolation.
Arca can also cache the results of these callables using `dogpile.cache <https://dogpilecache.readthedocs.io/en/latest/>`_.

Getting started
***************

Glossary
++++++++

* **Arca** - name of the library. When written as ``Arca``, the main interface class is being referenced.
* **Task** - definition of the function (callable), consists of a reference to the object and arguments.
* **Backend** - a way of running tasks.

Installation
++++++++++++

Requirements
------------

* Python >= 3.6

Requirements for certain backends:

* `Pipenv <https://docs.pipenv.org/>`_ (for certain usecases in `Virtualenv Backend <https://arca.readthedocs.io/en/latest/backends.html#virtual-environment>`_)
* `Docker <https://www.docker.com/>`_ (for `Docker Backend <https://arca.readthedocs.io/en/latest/backends.html#docker>`_
  and `Vagrant Backend <https://arca.readthedocs.io/en/latest/backends.html#vagrant>`_)
* `Vagrant <https://www.vagrantup.com/>`_ (for the `Vagrant Backend <https://arca.readthedocs.io/en/latest/backends.html#vagrant>`_)

Installation
------------

To install the last stable version:

.. code-block:: bash

  python -m pip install arca

If you want to use the Docker backend:

.. code-block:: bash

  python -m  pip install arca[docker]

Or if you want to use the Vagrant backend:

.. code-block:: bash

  python -m pip install arca[vagrant]

Or if you wish to install the upstream version:

.. code-block:: bash

  python -m pip install git+https://github.com/pyvec/arca.git#egg=arca
  python -m pip install git+https://github.com/pyvec/arca.git#egg=arca[docker]
  python -m pip install git+https://github.com/pyvec/arca.git#egg=arca[vagrant]

Example
+++++++

To run a Hello World example you'll only need the ``arca.Arca`` and ``arca.Task`` classes.
``Task`` is used for defining the task that's supposed to be run in the repositories.
``Arca`` takes care of all the settings and provides the basic API for running the tasks.

Let's say we have the following file, called ``hello_world.py``,
in a repository ``https://example.com/hello_word.git``, on branch ``master``.

.. code-block:: python

  def say_hello():
     return "Hello World!"

To call the function using Arca, the following example would do so:

.. code-block:: python

  from arca import Arca, Task

  task = Task("hello_world:say_hello")
  arca = Arca()

  result = arca.run("https://example.com/hello_word.git", "master", task)
  print(result.output)

The code would print ``Hello World!``.
``result`` would be a ``arca.Result`` instance. ``arca.Result`` has three attributes,
``output`` with the return value of the function call, ``stdout`` and ``stderr`` contain things printed to the standard outputs
(see the section about `Result <http://arca.readthedocs.io/en/latest/tasks.html#result>`_ for more info about the capture of the standard outputs).
If the task fails, ``arca.exceptions.BuildError`` would be raised.

By default, the `Current Environment Backend <https://arca.readthedocs.io/en/latest/backends.html#current-environment>`_ is used to run tasks,
which uses the current Python, launching the code in a subprocess. You can learn about backends `here <https://arca.readthedocs.io/en/latest/backends.html>`_.

Further reading
***************

You can read the full documentation on `Read The Docs <https://arca.readthedocs.io/>`_.

Running tests
**************

To run tests you'll need the optional requirements, Docker and Vagrant. Once you have them and they can be used by
the current user you just need to run:

.. code-block:: bash

  python setup.py test

This will launch the tests and a PEP8 check. The tests will take some time since building the custom
docker images is also tested and vagrant, in general, takes a long time to set up.

Contributing
************

Contributions are welcomed! Feel free to open a issue or submit a pull request on `GitHub <https://github.com/pyvec/arca>`_!



Changes
=======

0.3.3 (2019-12-10)
******************

Changes:
  * Updated dependencies
  * Allowed branches with slashes  (`#79 <https://github.com/pyvec/arca/issues/79>`_)

0.3.2 (2019-11-23)
******************

Changes:
  * Moved the project under organisation Pyvec.
  * Changed the Docker registry for the base images to `arcaoss/arca`.
  * Fixed unicode paths to repositories (`#60 <https://github.com/pyvec/arca/issues/60>`_)

0.3.1 (2018-11-16)
******************

Raising a Arca exception when building of a Docker image fails. (`#56 <https://github.com/mikicz/arca/issues/56>`_, `#57 <https://github.com/mikicz/arca/pull/57>`_)

0.3.0 (2018-08-25)
******************

Changes:
  * Removed CurrentEnvironmentBackend's capability to process requirements - all requirements are ignored. (**BACKWARDS INCOMPATIBLE**)
  * Added support for installing requirements using `Pipenv <https://docs.pipenv.org/>`_.
    The directory containing ``Pipfile`` and ``Pipfile.lock`` is set by the backend option **pipfile_location**, by default the root of the repository is selected.
    The Pipenv files take precedence over regular requirement files.
  * The ``Result`` class now has two more attributes, ``stdout`` and ``stderr`` with the outputs of launched tasks to standard output and error.
    Priting is therefore now allowed in the endpoints.
  * Using UTF-8 locale in Docker images used in ``DockerBackend``.
  * Supporting Python 3.7.

0.2.1 (2018-06-11)
******************

Updated dogpile.cache to 0.6.5, enabling compatability with Python 3.7.
Updated the Docker backend to be able to run on Python betas.

0.2.0 (2018-05-09)
******************

This release has multiple backwards incompatible changes against the previous release.

Changes:
  * Using extras to install Docker and Vagrant dependencies

    * ``pip install arca[docker]`` or ``pip install arca[vagrant]`` has to be used

  * Automatically using cloned repositories as reference for newly cloned branches
  * Using Debian as the default base image in the Docker backend:

    * **apk_dependencies** changed to **apt_dependencies**, now installing using `apt-get`

  * Vagrant backend only creates one VM, instead of multiple -- see its documentation
  * Added timeout to tasks, 5 seconds by default. Can be set using the argument **timeout** for ``Task``.
  * Added timeout to installing requirements, 300 seconds by default. Can be set using the **requirements_timeout** configuration option for backends.

0.1.1 (2018-04-23)
******************

Updated gitpython to 2.1.9

0.1.0 (2018-04-18)
******************

Initial release

Changes:
 * Updated PyPI description and metadata

0.1.0a0 (2018-04-13)
********************

Initial alfa release