# pox scripts documentation

## pox script

run any of the pox commands from the command shell prompt

Notes

- To get help, type `$ pox` at a shell terminal prompt.

- For a list of available functions, type `$ pox "help('pox')"`.

- Incorrect function invocation will print the function’s documentation.

Examples:

    $ pox "which('python')"
    /usr/bin/python

citation()

  print the citation

convert(files, platform=None, pathsep=None, verbose=True)

  convert text files to given platform type

  Ensure given files use the appropriate `os.linesep` and other formatting.

  Parameters:

    - files (list(str)) – a list of filenames.

    - platform (str, default=None) – platform name as in `os.name`.

    - pathsep (str, default=None) – the path separator string.

    - verbose (bool, default=True) – if True, print debug statements..

  Returns:

    0 if converted, otherwise return 1.

disk_used(path)

  get the disk usage for the given directory

  Parameters:

    path (str) – path string.

  Returns:

    int corresponding to disk usage in blocks.

env(variable, all=True, minimal=False)

  get dict of environment variables of the form `{variable:value}`

  Parameters:

    - variable (str) – name or partial name for environment variable.

    - all (bool, default=True) – if False, only return the first match.

    - minimal (bool, default=False) – if True, remove all duplicate paths.

  Returns:

    dict of strings of environment variables.

  Warning

  selecting all=False can lead to unexpected matches of variable.

  Examples

      >>> env('*PATH')
      {'PYTHONPATH': '.', 'PATH': '.:/usr/bin:/bin:/usr/sbin:/sbin'}

expandvars(string, ref=None, secondref={})

  expand shell variables in string

  Expand shell variables of form `$var` and `${var}`. Unknown variables are left unchanged. If a reference dictionary (ref) is provided, restrict lookups to ref. A second reference dictionary (secondref) can also be provided for failover searches. If ref is not provided, lookup variables are defined by the user’s environment variables.

  Parameters:

    - string (str) – a string with shell variables.

    - ref (dict(str), default=None) – a dict of lookup variables.

    - secondref (dict(str), default={}) – a failover reference dict.

  Returns:

    string with the selected shell variables substituted.

  Examples

      >>> expandvars('found:: $PYTHONPATH')
      'found:: .:/Users/foo/lib/python3.4/site-packages'
      >>>
      >>> expandvars('found:: $PYTHONPATH', ref={})
      'found:: $PYTHONPATH'

find(patterns, root=None, recurse=True, type=None, verbose=False)

  get the path to a file or directory

  Parameters:

    - patterns (str) – name or partial name of items to search for.

    - root (str, default=None) – path of top-level directory to search.

    - recurse (bool, default=True) – if True, recurse downward from root.

    - type (str, default=None) – a search filter.

    - verbose (bool, default=False) – if True, be verbose about the search.

  Returns:

    a list of string paths.

  Notes

  on some OS, recursion can be specified by recursion depth (int), and patterns can be specified with basic pattern matching. Also, multiple patterns can be specified by splitting patterns with a `;`. The type can be one of `{file, dir, link, socket, block, char}`.

  Examples

      >>> find('pox*', root='..')
      ['/Users/foo/pox/pox', '/Users/foo/pox/scripts/pox_launcher.py']
      >>>
      >>> find('*shutils*;*init*')
      ['/Users/foo/pox/pox/shutils.py', '/Users/foo/pox/pox/__init__.py']

findpackage(package, root=None, all=False, verbose=True, recurse=True)

  retrieve the path(s) for a package

  Parameters:

    - package (str) – name of the package to search for.

    - root (str, default=None) – path string of top-level directory to search.

    - all (bool, defualt=False) – if True, return everywhere package is found.

    - verbose (bool, default=True) – if True, print messages about the search.

    - recurse (bool, default=True) – if True, recurse down the root directory.

  Returns:

    string path (or list of paths) where package is found.

  Notes

  On some OS, recursion can be specified by recursion depth (an integer). `findpackage` will do standard pattern matching for package names, attempting to match the head directory of the distribution.

getvars(path, ref=None, sep=None)

  get a dictionary of all variables defined in path

  Extract shell variables of form `$var` and `${var}`. Unknown variables will raise an exception. If a reference dictionary (ref) is provided, first try the lookup in ref. Failover from ref will lookup variables defined in the user’s environment variables. Use sep to override the path separator (`os.sep`).

  Parameters:

    - path (str) – a path string with shell variables.

    - ref (dict(str), default=None) – a dict of lookup variables.

    - sep (str, default=None) – the path separator string.

  Returns:

    dict of shell variables found in the given path string.

  Examples

      >>> getvars('$HOME/stuff')
      {'HOME': '/Users/foo'}

help(function=None)

homedir()

  get the full path of the user’s home directory

  Parameters:

    None

  Returns:

    string path of the directory, or None if home can not be determined.

index_join(sequence, start, stop, step=1, sequential=True, inclusive=True)

  slice a list of strings, then join the remaining strings

  If start is not found in the sequence, slice from the beginning. If stop is not found in the sequence, slice to the end.

  Parameters:

    - sequence (list) – an ordered sequence of elements.

    - start (int) – index for start of the slice.

    - stop (int) – index for stop position in the sequence.

    - step (int, default=1) – indices until next member of the slice.

    - sequential (bool, default=True) – if True, start must preceed stop.

    - inclusive (bool, default=True) – if True, include stop in the slice.

  Returns:

    string produced by slicing the given sequence and joining the elements.

index_slice(sequence, start, stop, step=1, sequential=False, inclusive=False)

  get the slice for a given sequence

  Slice indicies are determined by the positions of start and stop. If start is not found in the sequence, slice from the beginning. If stop is not found in the sequence, slice to the end.

  Parameters:

    - sequence (list) – an ordered sequence of elements.

    - start (int) – index for start of the slice.

    - stop (int) – index for stop position in the sequence.

    - step (int, default=1) – indices until next member of the slice.

    - sequential (bool, default=False) – if True, start must preceed stop.

    - inclusive (bool, default=False) – if True, include stop in the slice.

  Returns:

    slice corresponding to given start, stop, and step.

isfunction(object)

  Return true if the object is a user-defined function.

  Function objects provide these attributes:

    __doc__ documentation string __name__ name with which this function was defined __code__ code object containing compiled function bytecode __defaults__ tuple of any default values for arguments __globals__ global namespace in which this function was defined __annotations__ dict of parameter annotations __kwdefaults__ dict of keyword only parameters with defaults

kbytes(text)

  convert memory text to the corresponding value in kilobytes

  Parameters:

    text (str) – string corresponding to an abbreviation of size.

  Returns:

    int representation of text.

  Examples

      >>> kbytes('10K')
      10
      >>>
      >>> kbytes('10G')
      10485760

license()

  print the license

minpath(path, pathsep=None)

  remove duplicate paths from given set of paths

  Parameters:

    - path (str) – path string (e.g. ‘/Users/foo/bin:/bin:/sbin:/usr/bin’).

    - pathsep (str, default=None) – path separator (e.g. `:`).

  Returns:

    string composed of one or more paths, with duplicates removed.

  Examples

      >>> minpath('.:/Users/foo/bin:.:/Users/foo/bar/bin:/Users/foo/bin')
      '.:/Users/foo/bin:/Users/foo/bar/bin'

mkdir(path, root=None, mode=None)

  create a new directory in the root directory

  create a directory at path and any necessary parents (i.e. `mkdir -p`). Default mode is read/write/execute for ‘user’ and ‘group’, and then read/execute otherwise.

  Parameters:

    - path (str) – string name of the new directory.

    - root (str, default=None) – path at which to build the new directory.

    - mode (str, default=None) – octal read/write permission [default: 0o775].

  Returns:

    string absolute path for new directory.

parse_remote(path, loopback=False, login_flag=False)

  parse remote connection string of the form `[[user@]host:]path`

  Parameters:

    - path (str) – remote connection string.

    - loopback (bool, default=False) – if True, ensure host is used.

    - login_flag (bool, default=False) – if True, prepend user with `-l`.

  Returns:

    a tuple of the form `(user, host, path)`.

  Notes

  if loopback=True and host=None, then host will be set to localhost.

pattern(list=[], separator=';')

  generate a filter pattern from list of strings

  Parameters:

    - list (list(str), default=[]) – a list of filter elements.

    - separator (str, default=';') – the separator string.

  Returns:

    a string composed of filter elements joined by the separator.

remote(path, host=None, user=None, loopback=False)

  build string for a remote connection of the form `[[user@]host:]path`

  Parameters:

    - path (str) – path string for location of target on (remote) filesystem.

    - host (str, default=None) – string name/ip address of (remote) host.

    - user (str, default=None) – user name on (remote) host.

    - loopback (bool, default=False) – if True, ensure host is used.

  Returns:

    a remote connection string.

  Notes

  if loopback=True and host=None, then host will be set to localhost.

replace(file, sub={}, outfile=None)

  make text substitutions given by sub in the given file

  Parameters:

    - file (str) – path to original file.

    - sub (dict(str) – dict of string replacements `{old:new}`.

    - outfile (str, default=None) – if given, don’t overwrite original file.

  Returns:

    None

  Notes

  `replace` uses regular expressions, thus a pattern may be used as old text. `replace` can fail if order of substitution is important.

rmtree(path, self=True, ignore_errors=False, onerror=None)

  remove directories in the given path

  Parameters:

    - path (str) – path string of root of directories to delete.

    - self (bool, default=True) – if False, delete subdirectories, not path.

    - ignore_errors (bool, default=False) – if True, silently ignore errors.

    - onerror (function, default=None) – custom error handler.

  Returns:

    None

  Notes

  If self=False, the directory indicated by path is left in place, and its subdirectories are erased. If self=True, path is also removed.

  If ignore_errors=True, errors are ignored. Otherwise, onerror is called to handle the error with arguments `(func, path, exc_info)`, where func is `os.listdir`, `os.remove`, or `os.rmdir`; path is the argument to the function that caused it to fail; and exc_info is a tuple returned by `sys.exc_info()`. If ignore_errors=False and onerror=None, an exception is raised.

rootdir()

  get the path corresponding to the root of the current drive

  Parameters:

    None

  Returns:

    string path of the directory.

select(iterable, counter='', minimum=False, reverse=False, all=True)

  find items in iterable with the max (or min) count of the given counter.

  Find the items in an iterable that have the maximum number of counter (e.g. counter=’3’ counts occurances of ‘3’). Use `minimum=True` to search for the minimum number of occurances of the counter.

  Parameters:

    - iterable (list) – an iterable of iterables (e.g. lists, strings, etc).

    - counter (str, default='') – the item to count.

    - minimum (bool, default=False) – if True, find min count (else, max).

    - reverse (bool, default=False) – if True, reverse order of the results.

    - all (bool, default=True) – if False, only return the first result.

  Returns:

    list of items in the iterable with the min (or max) count.

  Examples

      >>> z = ['zero','one','two','three','4','five','six','seven','8','9/81']
      >>> select(z, counter='e')
      ['three', 'seven']
      >>> select(z, counter='e', minimum=True)
      ['two', '4', 'six', '8', '9/81']
      >>>
      >>> y = [[1,2,3],[4,5,6],[1,3,5]]
      >>> select(y, counter=3)
      [[1, 2, 3], [1, 3, 5]]
      >>> select(y, counter=3, minumim=True, all=False)
      [4, 5, 6]

selectdict(dict, counter='', minimum=False, all=True)

  return a dict of items with the max (or min) count of the given counter.

  Get the items from a dict that have the maximum number of the counter (e.g. counter=’3’ counts occurances of ‘3’) in the values. Use `minimum=True` to search for minimum number of occurances of counter.

  Parameters:

    - dict (dict) – dict with iterables as values (e.g. lists, strings, etc).

    - counter (str, default='') – the item to count.

    - minimum (bool, default=False) – if True, find min count (else, max).

    - all (bool, default=True) – if False, only return the first result.

  Returns:

    dict of items composed of the entries with the min (or max) count.

  Examples

      >>> z = ['zero','one','two','three','4','five','six','seven','8','9/81']
      >>> z = dict(enumerate(z))
      >>> selectdict(z, counter='e')
      {3: 'three', 7: 'seven'}
      >>> selectdict(z, counter='e', minimum=True)
      {8: '8', 9: '9/81', 2: 'two', 4: '4', 6: 'six'}
      >>>
      >>> y = {1: [1,2,3], 2: [4,5,6], 3: [1,3,5]}
      >>> selectdict(y, counter=3)
      {1: [1, 2, 3], 3: [1, 3, 5]}
      >>> selectdict(y, counter=3, minumim=True)
      {2: [4, 5, 6]}

sep(type='')

  get the separator string for the given type of separator

  Parameters:

    type (str, default='') – one of `{sep,line,path,ext,alt}`.

  Returns:

    separator string.

shellsub(command)

  parse the given command to be formatted for remote shell invocation

  secure shell (`ssh`) can be used to send and execute commands to remote machines (using `ssh <hostname> <command>`). Additional escape characters are needed to enable the command to be correctly formed and executed remotely. shellsub attemps to parse the given command string correctly so that it can be executed remotely with ssh.

  Parameters:

    command (str) – the command to be executed remotely.

  Returns:

    the parsed command string.

shelltype()

  get the name (e.g. `bash`) of the current command shell

  Parameters:

    None

  Returns:

    string name of the shell, or None if name can not be determined.

username()

  get the login name of the current user

  Parameters:

    None

  Returns:

    string name of the user.

wait_for(path, sleep=1, tries=150, ignore_errors=False)

  block execution by waiting for a file to appear at the given path

  Parameters:

    - path (str) – the path string to watch for the file.

    - sleep (float, default=1) – the time between checking results.

    - tries (int, default=150) – the number of times to try.

    - ignore_errors (bool, default=False) – if True, ignore timeout error.

  Returns:

    None

  Notes

  if the file is not found after the given number of tries, an error will be thrown unless `ignore_error=True`.

  using `subproc = Popen(...)` and `subproc.wait()` is usually a better approach. However, when a handle to the subprocess is unavailable, waiting for a file to appear at a given path is a decent last resort.

walk(root, patterns='*', recurse=True, folders=False, files=True, links=True)

  walk directory tree and return a list matching the requested pattern

  Parameters:

    - root (str) – path of top-level directory to search.

    - patterns (str, default='*') – (partial) name of items to search for.

    - recurse (bool, default=True) – if True, recurse downward from root.

    - folders (bool, default=False) – if True, include folders in the results.

    - files (bool, default=True) – if True, include files in results.

    - links (bool, default=True) – if True, include links in results.

  Returns:

    a list of string paths.

  Notes

  patterns can be specified with basic pattern matching. Additionally, multiple patterns can be specified by splitting patterns with a `;`.

  Examples

      >>> walk('..', patterns='pox*')
      ['/Users/foo/pox/pox', '/Users/foo/pox/scripts/pox_launcher.py']
      >>>
      >>> walk('.', patterns='*shutils*;*init*')
      ['/Users/foo/pox/pox/shutils.py', '/Users/foo/pox/pox/__init__.py']

where(name, path, pathsep=None)

  get the full path for the given name string on the given search path.

  Parameters:

    - name (str) – name of file, folder, etc to find.

    - path (str) – path string (e.g. ‘/Users/foo/bin:/bin:/sbin:/usr/bin’).

    - pathsep (str, default=None) – path separator (e.g. `:`)

  Returns:

    the full path string.

  Notes

  if pathsep is not provided, the OS default will be used.

whereis(prog, all=False)

  get path to the given program

  search the standard binary install locations for the given executable.

  Parameters:

    - prog (str) – name of an executable to search for (e.g. `python`).

    - all (bool, default=True) – if True, return a list of paths found.

  Returns:

    string path of the executable, or list of path strings.

which(prog, allow_links=True, ignore_errors=True, all=False)

  get the path of the given program

  search the user’s paths for the given executable.

  Parameters:

    - prog (str) – name of an executable to search for (e.g. `python`).

    - allow_links (bool, default=True) – if False, replace link with fullpath.

    - ignore_errors (bool, default=True) – if True, ignore search errors.

    - all (bool, default=False) – if True, get list of paths for executable.

  Returns:

    if all=True, get a list of string paths, else return a string path.

which_python(version=False, lazy=False, fullpath=True, ignore_errors=True)

  get the command to launch the selected version of python

  `which_python` composes a command string that can be used to launch the desired python executable. The user’s path is searched for the executable, unless `lazy=True` and thus only a lazy-evaluating command (e.g. `which python`) is produced.

  Parameters:

    - version (bool, default=False) – if True, include the version of python.

    - lazy (bool, default=False) – if True, build a lazy-evaluating command.

    - fullpath (bool, default=True) – if True, provide the full path.

    - ignore_errors (bool, default=True) – if True, ignore path search errors.

  Returns:

    string of the implicit or explicit location of the python executable.

  Notes

  if version is given as an int or float, include the version number in the command string.

  if the executable is not found, an error will be thrown unless `ignore_error=True`.