Metadata-Version: 2.1
Name: arca
Version: 0.3.3
Summary: A library for running Python functions (callables) from git repositories in various states of isolation with integrating caching.
Home-page: https://github.com/pyvec/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/pyvec/arca
Project-URL: Test coverage, https://codecov.io/gh/pyvec/arca
Description: 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
        
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: Programming Language :: Python :: 3.8
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
