What is fades?

.. image:: https://github.com/PyAr/fades/actions/workflows/test.uaml/badge.svg :target: https://github.com/PyAr/fades/actions/workflows/test.uaml/badge.svg .. image:: https://readthedocs.org/projects/fades/badge/?version=latest :target: http://fades.readthedocs.org/en/latest/?badge=latest :alt: Documentation Status .. image:: https://badge.fury.io/py/fades.svg :target: https://badge.fury.io/py/fades .. image:: https://coveralls.io/repos/PyAr/fades/badge.svg?branch=master&service=github :target: https://coveralls.io/github/PyAr/fades?branch=master .. image:: https://build.snapcraft.io/badge/PyAr/fades.svg :target: https://build.snapcraft.io/user/PyAr/fades :alt: Snap Status .. image:: https://ci.appveyor.com/api/projects/status/crkqv82t1l731fms/branch/master?svg=true :target: https://ci.appveyor.com/project/facundobatista/fades :alt: Appveyor Status

fades is a system that automatically handles the virtual environments in the cases normally found when writing scripts and simple programs, and even helps to administer big projects.

.. image:: resources/logo256.png

fades will automagically create a new virtual environment (or reuse a previous created one), installing the necessary dependencies, and execute your script inside that virtual environment, with the only requirement of executing the script with fades and also marking the required dependencies.

(If you don't have a clue why this is necessary or useful, I'd recommend you to read this small text about Python and the Management of Dependencies <https://github.com/PyAr/fades/blob/master/docs/pydepmanag.rst>_ .)

The first non-option parameter (if any) would be then the child program to execute, and any other parameters after that are passed as is to that child script.

fades can also be executed without passing a child script to execute: in this mode it will open a Python interactive interpreter inside the created/reused virtual environment (taking dependencies from --dependency or --requirement options).

.. contents::

How to use it?

Click in the following image to see a video/screencast that shows most of fades features in just 5'...

.. image:: resources/video/screenshot.png :target: https://www.youtube.com/watch?v=BCTd_TyCm98

...or inspect these several small GIFs <resources/gifs/gifs.rst>_ that show each a particular fades functionality, but please keep also reading for more detailed information...

Yes, please, I want to read

When you write an script, you have to take two special measures:

• need to execute it with fades (not python)

• need to mark those dependencies

At the moment you execute the script, fades will search a virtual environment with the marked dependencies, if it doesn't exists fades will create it, and execute the script in that environment.

How to execute the script with fades?

You can always call your script directly with fades::

fades myscript.py

However, for you to not forget about fades and to not execute it directly with python, it's better if you put at the beggining of the script the indication for the operating system that it should be executed with fades... ::

#!/usr/bin/env fades

...and also set the executable bit in the script::

chmod +x yourscript.py

You can also execute scripts directly from the web, passing directly the URL of the pastebin where the script is pasted (most common pastebines are supported, pastebin.com, gist, linkode.org, but also it's supported if the URL points to the script directly)::

fades http://myserver.com/myscript.py

How to mark the dependencies to be installed?

The procedure to mark a module imported by the script as a dependency to be installed by fades is by using a comment.

This comment will normally be in the same line of the import (recommended, less confusing and less error prone in the future), but it also can be in the previous one.

The simplest comment is like::

import somemodule   # fades
from somepackage import othermodule    # fades

The fades is mandatory, in this examples the repository is PyPI, see About different repositories_ below for other examples.

With that comment, fades will install automatically in the virtual environment the somemodule or somepackage from PyPI.

Also, you can indicate a particular version condition, examples::

import somemodule   # fades == 3
import somemodule   # fades >= 2.1
import somemodule   # fades >=2.1,<2.8,!=2.6.5

Sometimes, the project itself doesn't match the name of the module; in these cases you can specify the project name (optionally, before the version)::

import bs4   # fades beautifulsoup4
import bs4   # fades beautifulsoup4 == 4.2

What if no script is given to execute?

If no script or program is passed to execute, fades will provide a virtual environment with all the indicated dependencies, and then open an interactive interpreter in the context of that virtual environment.

Here is where it comes very handy the -i/--ipython option, if that REPL is preferred over the standard one.

In the case of using an interactive interpreter, it's also very useful to make fades to automatically import all the indicated dependencies, passing the --autoimport parameter.

Other ways to specify dependencies

Apart of marking the imports in the source file, there are other ways to tell fades which dependencies to install in the virtual environment.

One way is through command line, passing the --dependency parameter. This option can be specified multiple times (once per dependency), and each time the format is repository::dependency. The dependency may have versions specifications, and the repository is optional (defaults to 'pypi').

Another way is to specify the dependencies in a text file, one dependency per line, with each line having the format previously described for the --dependency parameter. This file is then indicated to fades through the --requirement parameter. This option can be specified multiple times.

In case of multiple definitions of the same dependency, command line overrides everything else, and requirements file overrides what is specified in the source code.

Finally, you can include package names in the script docstring, after a line where "fades" is written, until the end of the docstring; for example::

"""Script to do stuff.

It's a very important script.

We need some dependencies to run ok, installed by fades:
    request
    otherpackage
"""

About different repositories

fades supports installing the required dependencies from multiples repositories: besides PyPI, you can specify URLs that can point to projects from GitHub, Launchpad, etc. (basically, everything that is supported by pip itself).

When a dependency is specified, fades deduces the proper repository. For example, in the following examples fades will install requests from the latest revision from PyPI in the first case, and in the second case the latest revision from the project itself from GitHub::

-d requests
-d git+https://github.com/kennethreitz/requests.git#egg=requests

If you prefer, you can be explicit about which kind of repository fades should use, prefixing the dependency with the special token double colon (::)::

-d pypi::requests
-d vcs::git+https://github.com/kennethreitz/requests.git#egg=requests

There are two basic repositories: pypi which will make fades to install the desired dependency from PyPI, and vcs, which will make fades to treat the dependency as a URL for a version control system site. In the first case, for PyPI, a full range of version comparators can be specified, as usual. For vcs repositories, though, the comparison is always exact: if the very same dependency is specified, a virtual environment is reused, otherwise a new one will be created and populated.

In both cases (specifying the repository explicitly or implicitly) there is no difference if the dependency is specified in the command line, in a requirements.txt file, in the script's docstring, etc. In the case of marking the import directly in the script, it slightly different.

When marking the import it normally happens that the package itself to be installed has the name of the imported module, and because of that it can only be found in PyPI. So, in the following cases the pypi repository is not only deduced, but unavoidable::

import requests  # fades
from foo import bar  # fades
import requests  # fades <= 3

But if the package is specified (normally needed because it's different than the module name), or if a version control system URL is specified, the same possibilities stated above are available: let fades to deduce the proper repository or mark it explicitly::

import bs4  # fades beautifulsoup
import bs4  # fades pypi::beautifulsoup
import requests  # fades git+https://github.com/kennethreitz/requests.git#egg=requests
import requests  # fades vcs::git+https://github.com/kennethreitz/requests.git#egg=requests

One last detail about the vcs repository: the format to write the URLs is the same (as it's passed without modifications) than what pip itself supports (see pip docs <https://pip.readthedocs.io/en/stable/reference/pip_install/#vcs-support>_ for more details).

Furthermore, you can install from local projects. It's just fine to use a dependency that starts with file:. E.g. (please note the triple slash, because we're mixing the protocol indication with the path)::

fades -d file:///home/crazyuser/myproject/allstars/

How to control the virtual environment creatio