Reference¶
Special variables¶
There are a set of special variables in ayrton
. Most of them are inherited
from shell like languages.
-
argv
¶ This variable holds a list of the arguments passed to the script, with the script’s path in the first position. In Python-speak, this is
sys.argv
.It’s not quite a list: len(argv), iter(argv) and argv.pop() don’t take in account argv[0].
Exceptions¶
Functions¶
-
cd
(path) | chdir (path)¶ Changes the current working directory for the script process. If used as a context manager, it restores the original path when the context finishes, efectively working more or less like pushd/popd or ( cd path; ... ).
-
export
(key=value, ...)¶ For each key and value pair, set the variable key to the string representation of value, and register the variable as to be exported to subproceses.
-
o
(name=value)¶ Creates a positional option that will be expanded as an option/value when running a command. See
foo()
. This is mostly used internally.
-
option
(opt, value=True)¶ Works more or less like bash‘s set builtin command. opt can be in its long form, in which case you can pass the new value, or in the set/unset short form. So far only the following options are recognized:
- errexit/-e/+e
- If set, any command that exits with a code which is not 0 will raise a
CommandFailed
exception.
It raises a ValueError if the option is malformed, and KeyError if the option is not recognized.
-
remote
(...)¶ This function is better used as a context manager:
with remote (): ...
The function accepts the same arguments as
paramiko
‘s SSHClient.connect() method. The body of the construct is executed in the remote machine.For the moment imports are weeded out from the remote environment, so you will need to reimport them.
-
run
(rel_or_abs_path[, *args[, **kwargs]])¶ Executes an arbitrary binary that is not in
path
. rel_or_abs_path must be a relative or absolute path.
-
shift
(n=1)¶ Pops the first n elements from
argv
and return them. If n is 1, the value returned is just the first element; if it’s bigger than 1, it returns a list with those n elements.
-
unset
(*args)¶ For each variable name in *args, unset the variable and remove it from the environment to be exported to subprocesses. Notice that it must be a list of strings, not the variables themselves. Unknown variables will be silently ignored.
-
foo
(...)¶ Executes the binary foo, searching the binary using
path
. Arguments are used as positional arguments for the command, except for the special keyword arguments listed below. This returns aCommand
.The syntaxis for Commands departs a little from pure Python. Python expressions are allowed as keyword names, so -o and –long-option are valid. Also, keywords and positional arguments can be mixed, as in find (-L=True, ‘/’, -name=’*.so’).
Iterable arguments that are not
str
orbytes
are expanded in situ, so foo(..., i, ...) is expanded to foo (..., i[0], i[1], ... and foo(..., k=i, ...) is expanded to foo (..., k=i[0], k=i[1], ....
-
_in
¶ Establishes what or where does the contents of stdin come from, depending on its value or type:
- If it’s None, it’s connected to
/dev/null
. - If it’s a file object [1], it uses its contents.
- If its type is
int
, it’s considered a file descriptor from where the input is read. - If its type is str or bytes, it’s considered the name of the file
from where the input is read. It could also be a tuple (str or bytes, int);
the int is passed as flags to
os.open()
. - If it’s an iterable, then it’s the str() of each of the elements.
- Else, it’s the
str()
of it.
- If it’s None, it’s connected to
-
_out
¶ Defines where the stdout goes to, depending on its value or type:
- If it’s None, it goes to
/dev/null
. - If it’s Capture, the output is read by the object.
- If it’s a file object [1], the output is written on it.
- If its type is int, it’s considered a file descriptor to where the output is written.
- It its type is str or bytes, it’s the filename where the output
goes. It could also be a tuple (str or bytes, int);
the int is passed as flags to
os.open()
.
- If it’s None, it goes to
-
_err
¶ Similar to _out, but for stderr.
[1] | (1, 2) For the moment it only includes io.IOBase instances and
its fileno() is used; this does not include objects that duck-type a file. |
[2] | This is inconsistent on what happens in _out and
_err . This might be deprecated in the future. |
Tests¶
The following functions are based on bash
‘s tests for file attributes.
For string and arithmetic operations and comparison use Python’s int
and
str
methods.
Note: -t, -G, -O and -ef are not implemented yet.
-
-a (file)
True if file exists.
-
-b (file)
True if file is a block device.
-
-c (file)
True if file is a char device.
-
-d (file)
True if file is a directory.
-
-e (file)
See
-a()
.
-
-f (file)
True if file is a regular file.
-
-g (file)
True if file‘s setgid bit is on.
-
-h (file)
True if file‘ is a symlink.
-
-k (file)
True if file‘s sticky bit is on.
-
-p (file)
True if file is a FIFO/named pipe.
-
-r (file)
True if file is readable.
-
-s (file)
True if file‘s size is >0.
-
-u (file)
True if file‘s setuid attribute is on.
-
-w (file)
True if file is writable.
-
-x (file)
True if file is executable.
-
-L (file)
See
-h()
.
-
-N (file)
True if file‘s modification time (mtime) is newer than its access time (atime).
-
-S (file)
True if file is a socket.
-
-nt (file1, file2)
True if file1 exists and file2 does not, or if file1‘s mtime is newer than file2‘s.
-
-ot (file1, file2)
True if file2 exists and file1 does not, or if file1‘s mtime is older than file2‘s.
Python functions¶
Some Python functions from the standard library are available as global functions
in ayrton
, some of them under a different, more shell-like name. Notice that
these function most probably hide an executable of the same name.
-
exit
([exit_code])¶ Finish the script with an exit code equal to exit_code. By default it’s 0. For more details, see http://docs.python.org/3/library/sys.html#sys.exit .
-
pwd
()¶ Returns the process’ current working directory. For more details, see For more details, see http://docs.python.org/3/library/os.html#os.getcwd .
-
sleep
()¶ Suspend execution for the given number of seconds. The argument may be a floating point number to indicate a more precise sleep time. For more details, see http://docs.python.org/3/library/time.html#time.sleep
-
uname
()¶ For more details, see http://docs.python.org/3/library/os.html#os.uname .
More functions might be already exported as builtins, but are not yet documented.
Please check ayrton/__init__.py
‘s polute()
function for more details.
There are some Python functions that would seem to also make sense to include here.
Most of them are C-based functions that have the same name as a more powerful
executable, like chmod
, mkdir
, etc. If you think we oversaw an useful
function, drop us a line.