Metadata-Version: 2.1
Name: arca
Version: 0.2.1
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
Description: 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.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
        
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: vagrant
Provides-Extra: docker
