| 1 |
.TH FADES 1 |
| 2 |
.SH NAME |
| 3 |
fades - A system that automatically handles the virtualenvs in the cases normally found when writing scripts and simple programs, and even helps to administer big projects. |
| 4 |
|
| 5 |
|
| 6 |
.SH SYNOPSIS |
| 7 |
.B fades |
| 8 |
[\fB-h\fR][\fB--help\fR] |
| 9 |
[\fB-V\fR][\fB--version\fR] |
| 10 |
[\fB-v\fR][\fB--verbose\fR] |
| 11 |
[\fB-q\fR][\fB--quiet\fR] |
| 12 |
[\fB-i\fR][\fB--ipython\fR] |
| 13 |
[\fB-d\fR][\fB--dependency\fR] |
| 14 |
[\fB-r\fR][\fB--requirement\fR] |
| 15 |
[\fB-x\fR][\fB--exec\fR] |
| 16 |
[\fB-p\fR \fIversion\fR][\fB--python\fR=\fIversion\fR] |
| 17 |
[\fB--rm\fR=\fIUUID\fR] |
| 18 |
[\fB--system-site-packages\fR] |
| 19 |
[\fB--virtualenv-options\fR=\fIoptions\fR] |
| 20 |
[\fB--pip-options\fR=\fIoptions\fR] |
| 21 |
[\fB--python-options\fR=\fIoptions\fR] |
| 22 |
[\fB--check-updates\fR] |
| 23 |
[\fB--clean-unused-venvs\fR=\fImax_days_to_keep\fR] |
| 24 |
[\fB--get-venv-dir\fR] |
| 25 |
[\fB--no-precheck-availability\fR] |
| 26 |
[\fB-a\fR][\fB--autoimport\fR] |
| 27 |
[\fB--freeze\fR] |
| 28 |
[\fB-m\fR][\fB--module\fR] |
| 29 |
[\fB--avoid-pip-upgrade\fR] |
| 30 |
[child_program [child_options]] |
| 31 |
|
| 32 |
\fBfades\fR can be used to execute directly your script, or put it with a #! at your script's beginning. |
| 33 |
|
| 34 |
|
| 35 |
.SH DESCRIPTION |
| 36 |
|
| 37 |
\fBfades\fR will automagically create a new virtualenv (or reuse a previous created one), installing the necessary dependencies, and execute your script inside that virtualenv, with the only requirement of executing the script with \fBfades\fR and also marking the required dependencies. |
| 38 |
|
| 39 |
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. |
| 40 |
|
| 41 |
\fBfades\fR 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 virtualenv (taking dependencies from \fI--dependency\fR or \fI--requirement\fR options). If \fI--autoimport\fR is given, it will automatically import all the installed dependencies. |
| 42 |
|
| 43 |
If the \fIchild_program\fR parameter is really an URL, the script will be automatically downloaded from there (supporting also the most common pastebins URLs: pastebin.com, linkode.org, gist, etc.). |
| 44 |
|
| 45 |
.SH OPTIONS |
| 46 |
|
| 47 |
.TP |
| 48 |
.BR -h ", "--help |
| 49 |
Show help about all the parameters and options, and quit. |
| 50 |
|
| 51 |
.TP |
| 52 |
.BR -V ", "--version |
| 53 |
Show the program version and info about the system, and quit. |
| 54 |
|
| 55 |
.TP |
| 56 |
.BR -v ", "--verbose |
| 57 |
Send all internal debugging lines to stderr, which may be very useful if any problem arises. |
| 58 |
|
| 59 |
.TP |
| 60 |
.BR -q ", " --quiet |
| 61 |
Don't show anything (unless it has a real problem), so the original script stderr is not polluted at all. |
| 62 |
|
| 63 |
.TP |
| 64 |
.BR -i ", " --ipython |
| 65 |
Runs IPython shell instead of python ones. |
| 66 |
|
| 67 |
.TP |
| 68 |
.BR -d ", " --dependency |
| 69 |
Specify dependencies through command line. This option can be specified multiple times (once per dependency), and each time the format is \fBrepository::dependency\fR. The dependency may have versions specifications, and the repository is optional (it will infer it). Examples: |
| 70 |
|
| 71 |
requests |
| 72 |
pypi::requests > 2.3 |
| 73 |
requests<=3 |
| 74 |
git+https://github.com/kennethreitz/requests.git#egg=requests |
| 75 |
vcs::git+https://github.com/kennethreitz/requests.git#egg=requests |
| 76 |
|
| 77 |
See more examples below for real command line usage explanations. |
| 78 |
|
| 79 |
.TP |
| 80 |
.BR -r ", " --requirement |
| 81 |
Read the dependencies from a file. Format in each line is the same than dependencies specified with \fI--dependency\fR. This option can be specified multiple times. |
| 82 |
|
| 83 |
.TP |
| 84 |
.BR -p " " \fIversion\fR ", " --python=\fIversion\fR |
| 85 |
Select which Python version to be used; the argument can be just the number (2.7), the whole name (python2.7) or the whole path (/usr/bin/python2.7). Of course, the corresponding version of Python needs to be installed in your system. |
| 86 |
|
| 87 |
The dependencies can be indicated in multiple places (in the Python source file, with a comment besides the import, in a \fIrequirements\fRfile, and/or through command line. 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. |
| 88 |
|
| 89 |
.TP |
| 90 |
.BR -x ", " --exec |
| 91 |
Execute the \fIchild_program\fR in the context of the virtualenv. The child_program, which in this case becomes a mandatory parameter, can be just the executable name (relative to the venv's bin directory) or an absolute path. |
| 92 |
|
| 93 |
.TP |
| 94 |
.BR --rm " " \fIUUID\fR |
| 95 |
Remove a virtualenv by UUID. See \fB--get-venv-dir\fR option to easily find out the UUID. |
| 96 |
|
| 97 |
.TP |
| 98 |
.BR --system-site-packages "" |
| 99 |
Give the virtual environment access to thesystem site-packages dir |
| 100 |
|
| 101 |
.TP |
| 102 |
.BR --virtualenv-options=\fIVIRTUALENV_OPTION\fR |
| 103 |
Extra options to be supplied to virtualenv. (this option can be used multiple times) |
| 104 |
|
| 105 |
.TP |
| 106 |
.BR --pip-options=\fIPIP_OPTION\fR |
| 107 |
Extra options to be supplied to pip. (this option can be used multiple times) |
| 108 |
|
| 109 |
.TP |
| 110 |
.BR --python-options=\fIPYTHON_OPTION\fR |
| 111 |
Extra options to be supplied to python. (this option can be used multiple times) |
| 112 |
|
| 113 |
.TP |
| 114 |
.BR --check-updates |
| 115 |
Will check for updates in PyPI to verify if there are new versions for the requested dependencies. If a new version is available for a dependency, it will use it (if the dependency was requested without version) or just inform which new version is available (if the dependency was requested with a specific version). |
| 116 |
|
| 117 |
.TP |
| 118 |
.BR --clean-unused-venvs=\fIMAX_DAYS_TO_KEEP\fR |
| 119 |
Will remove all virtualenvs that haven't been used for more than MAX_DAYS_TO_KEEP days. |
| 120 |
|
| 121 |
.TP |
| 122 |
.BR --get-venv-dir |
| 123 |
Show the virtualenv base directory (which includes the virtualenv UUID) and quit. |
| 124 |
|
| 125 |
.TP |
| 126 |
.BR --no-precheck-availability |
| 127 |
Don't check if the packages exists in PyPI before actually try to install them. |
| 128 |
|
| 129 |
.TP |
| 130 |
.BR -a ", " --autoimport |
| 131 |
Automatically import the dependencies when in interactive interpreter mode (ignored otherwise). |
| 132 |
|
| 133 |
.TP |
| 134 |
.BR --freeze " " \fIFILEPATH\fR |
| 135 |
Will operate exactly as without the command, but also it will dump the revisions of installed dependencies to the given \fBfilepath\fR. |
| 136 |
|
| 137 |
.TP |
| 138 |
.BR -m ", " --module |
| 139 |
Run library module as a script (same behaviour than Python's \fB-m\fR parameter). |
| 140 |
|
| 141 |
.TP |
| 142 |
.BR --avoid-pip-upgrade |
| 143 |
Disable the automatic \fBpip\fR upgrade that happens after the virtualenv is created and before the dependencies begin to be installed. |
| 144 |
|
| 145 |
|
| 146 |
.SH EXAMPLES |
| 147 |
|
| 148 |
.TP |
| 149 |
fades foo.py --bar |
| 150 |
|
| 151 |
Executes foo.py under fades, passing the --bar parameter to the child program, in a virtualenv with the dependencies indicated in the source code. |
| 152 |
|
| 153 |
.TP |
| 154 |
fades -v foo.py |
| 155 |
|
| 156 |
Executes foo.py under fades, showing all the fades messages (verbose mode). |
| 157 |
|
| 158 |
.TP |
| 159 |
fades -d dependency1 -d dependency2>3.2 foo.py --bar |
| 160 |
|
| 161 |
Executes foo.py under fades (passing the --bar parameter to it), in a virtualenv with the dependencies indicated in the source code and also dependency1 and dependency2 (any version > 3.2). |
| 162 |
|
| 163 |
.TP |
| 164 |
fades -d dependency1 |
| 165 |
|
| 166 |
Executes the Python interactive interpreter in a virtualenv with dependency1 installed. |
| 167 |
|
| 168 |
.TP |
| 169 |
fades -r requirements.txt |
| 170 |
|
| 171 |
Executes the Python interactive interpreter in a virtualenv after installing there all dependencies taken from the requirements.txt file. |
| 172 |
|
| 173 |
.TP |
| 174 |
fades -r requirements.txt -r requirements_devel.txt |
| 175 |
|
| 176 |
Executes the Python interactive interpreter in a virtualenv after installing there all dependencies taken from files requirements.txt and requirements_devel.txt. |
| 177 |
|
| 178 |
.SH USING CONFIGURATION FILES |
| 179 |
|
| 180 |
You can also configure fades using \fB.ini\fR config files. fades will search config files in |
| 181 |
\fB/etc/fades/fades.ini\fR, the path indicated by \fBxdg\fR for your system |
| 182 |
(for example ~/config/fades/fades.ini) and .fades.ini. |
| 183 |
So you can have different settings at system, user and project level. |
| 184 |
|
| 185 |
The config files are in .ini format. (configparser) and fades will search for a [fades] section. |
| 186 |
You have to use the same configurations that in the CLI. The only difference is with the config |
| 187 |
options with a dash, it has to be replaced with a underscore. |
| 188 |
|
| 189 |
Check http://fades.readthedocs.org/en/latest/readme.html#setting-options-using-config-files for full examples. |
| 190 |
|
| 191 |
|
| 192 |
.SH SEE ALSO |
| 193 |
Development is centralized in https://github.com/PyAr/fades |
| 194 |
|
| 195 |
Check that site for a better explanation of \fBfades\fR usage. |
| 196 |
|
| 197 |
.SH AUTHORS |
| 198 |
Facundo Batista, Nicolás Demarchi (see development page for contact info). |
| 199 |
|
| 200 |
.SH LICENSING |
| 201 |
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 3, as published by the Free Software Foundation. |