Metadata-Version: 2.1
Name: arca
Version: 0.2.0
Summary: A library for running Python functions (callables) from git repositories in various states of isolation with integrating caching.
Home-page: https://github.com/mikicz/arca
Author: Mikuláš Poul
Author-email: mikulaspoul@gmail.com
License: MIT
Project-URL: Documentation, https://arca.readthedocs.io/
Project-URL: CI, https://travis-ci.org/mikicz/arca
Project-URL: Test coverage, https://codecov.io/gh/mikicz/arca
Keywords: sandboxing,git,docker,vagrant
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Security
Classifier: Topic :: Utilities
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Version Control :: Git
Provides-Extra: docker
Provides-Extra: vagrant
Requires-Dist: gitpython (==2.1.9)
Requires-Dist: dogpile.cache (==0.6.4)
Requires-Dist: requests
Requires-Dist: entrypoints (>=0.2.3)
Requires-Dist: cached-property
Provides-Extra: docker
Requires-Dist: docker (~=3.2.1); extra == 'docker'
Provides-Extra: vagrant
Requires-Dist: docker (~=3.2.1); extra == 'vagrant'
Requires-Dist: python-vagrant; extra == 'vagrant'
Requires-Dist: fabric3; extra == 'vagrant'

Arca
====

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

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

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

.. image:: https://img.shields.io/github/license/mikicz/arca.svg?style=flat
   :target: https://github.com/mikicz/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:

* `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/mikicz/arca.git#egg=arca
  python -m pip install git+https://github.com/mikicz/arca.git#egg=arca[docker]
  python -m pip install git+https://github.com/mikicz/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 which currently only has one attribute,
``output``, with the output of the function call.
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
************

I am developing this library as my bachelor thesis and will be not accepting any PRs at the moment.



Changes
=======

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


