seisflows.tools.unix
====================

.. py:module:: seisflows.tools.unix

.. autoapi-nested-parse::

   Unix functions wrapped in Python3. Used to simplify function calling and
   provide a uniform look to SeisFlows source code. These Python functions
   are meant to mimic commonly-used shell commands.



Functions
---------

.. autoapisummary::

   seisflows.tools.unix._iterable
   seisflows.tools.unix.cat
   seisflows.tools.unix.cd
   seisflows.tools.unix.cp
   seisflows.tools.unix.hostname
   seisflows.tools.unix.ln
   seisflows.tools.unix.ls
   seisflows.tools.unix.mkdir
   seisflows.tools.unix.mv
   seisflows.tools.unix.rename
   seisflows.tools.unix.rm
   seisflows.tools.unix.select
   seisflows.tools.unix.touch
   seisflows.tools.unix.which
   seisflows.tools.unix.nproc


Module Contents
---------------

.. py:function:: _iterable(arg)

   Make an argument iterable. Allows for more generalized inputs to these
   unix-style functions.

   :type arg: anything
   :param arg: an argument to make iterable
   :rtype: list
   :return: iterable argument


.. py:function:: cat(src, dst=None)

   Concatenate files and print to standard output or write to file

   :type src: str
   :param src: file to read
   :type dst: str
   :param dst: file to write contents to


.. py:function:: cd(path)

   Change directory to `path`

   :type path: str
   :param path: path to change directory to


.. py:function:: cp(src, dst)

   Copy files

   :type src: str or list or tuple
   :param src: source to copy from
   :type dst: str
   :param dst: destination to copy to


.. py:function:: hostname()

   Check the system's hostname

   :rtype: str
   :return: system hostname


.. py:function:: ln(src, dst)

   Make a symbolic link between files

   .. rubric::
       >>> from seisflows.tools.unix import ln
       >>> ln("example_file", "path/to/sylink/new_filename")
       >>> # OR
       >>> ln("example_file", "path/to/sylink/")

   :type src: str
   :param src: path to file or directory to symlink
   :type dst: str
   :param dst: path or file to symlink `src` to


.. py:function:: ls(path=os.getcwd(), show_all=False)

   List directory contents, option to show hidden files

   :type path: str
   :param path: path to list directory contents
   :type show_all: bool
   :param: if True, shows hidden files (starting with '.'), same as the
       -a or --all in shell ls command


.. py:function:: mkdir(dirs)

   Make directory or directories

   .. note::
       Random wait times to prevent overloading disk when multiple subprocesses
       are running mkdir
       
   :type dirs: str or list
   :param dirs: pathnames to make


.. py:function:: mv(src, dst)

   Move contents from `src` to `dst`

   :type src: str or list or tuple
   :param src: input file(s) to move
   :type dst: str
   :param dst: location to move path to


.. py:function:: rename(old, new, names)

   Rename multiple files

   :type old: str
   :param old: expression to replace
   :type new: str
   :param new: replacement expression
   :type names: list
   :param names: files to replace expressions in


.. py:function:: rm(path)

   Remove files or directories


.. py:function:: select(items, prompt='')

   Monitor file descriptors, waiting for one or more descriptor to be "ready"


.. py:function:: touch(filename, times=None)

   Update timestamps on files

   :type filename: str
   :param filename: file to touch
   :type times: None or (atime, mtime)
   :param times: if None, set time to current time, otherwise
       (accesstime, modifiedtime) need to be set


.. py:function:: which(name)

   Shows the full path of shell commands and executables

   :type name: str
   :param name: name of shell command to check


.. py:function:: nproc()

   Get the number of processors available. Same as calling 'nproc' from
   Linux command line.

   TODO replace all instances of nproc() with os.cpu_count()


   :rtype: int
   :return: number of processors
   :raises EnvironmentError: if nproc cannot be determined