Skip to content
Back to top
View this page
Edit this page

# xonsh.procs.proxies

Interface for running Python functions as subprocess-mode commands.

Code for several helper methods in the ProcProxy class have been reproduced without modification from subprocess.py in the Python 3.4.2 standard library. The contents of subprocess.py (and, thus, the reproduced methods) are Copyright (c) 2003-2005 by Peter Astrand <astrand@lysator.liu.se> and were licensed to the Python Software foundation under a Contributor Agreement.

class xonsh.procs.proxies.FileThreadDispatcher(default=None)

  Dispatches to different file handles depending on the current thread. Useful if you want file operation to go to different places for different threads.

  Parameters:
    default file-like or None, optional

      The file handle to write to if a thread cannot be found in the registry. If None, a new in-memory instance.

  Attributes:
    registry dict

      Maps thread idents to file handles.

  close()

    Closes the current thread’s handle.

  deregister()

    Removes the current thread from the registry.

  detach()

    Detaches the buffer for the current thread.

  fileno()

    Returns the file descriptor for the current thread.

  flush()

    Flushes the file descriptor for the current thread.

  isatty()

    Returns if the file descriptor for the current thread is a tty.

  read(size=None)

    Reads from the handle for the current thread.

  readable()

    Returns if file descriptor for the current thread is readable.

  readline(size=-1)

    Reads a line from the handle for the current thread.

  readlines(hint=-1)

    Reads lines from the handle for the current thread.

  register(handle)

    Registers a file handle for the current thread. Returns self so that this method can be used in a with-statement.

  seek(offset, whence=0)

    Seeks the current file.

  seekable()

    Returns if file descriptor for the current thread is seekable.

  tell()

    Reports the current position in the handle for the current thread.

  truncate(size=None)

    Truncates the file for for the current thread.

  writable(size=None)

    Returns if file descriptor for the current thread is writable.

  write(s)

    Writes to this thread’s handle. This also flushes, just to be extra sure the string was written.

  writelines()

    Writes lines for the file descriptor for the current thread.

  property available

    True if the thread is available in the registry.

  property buffer

    Gets the buffer for this thread’s handle.

  property closed

    Is the thread’s handle closed.

  property encoding

    Gets the encoding for this thread’s handle.

  property errors

    Gets the errors for this thread’s handle.

  property handle

    Gets the current handle for the thread.

  property line_buffering

    Gets if line buffering for this thread’s handle enabled.

  property newlines

    Gets the newlines for this thread’s handle.

class xonsh.procs.proxies.Handle
  classmethod from_bytes(/, bytes, byteorder='big', *, signed=False)

    Return the integer represented by the given array of bytes.

    bytes

      Holds the array of bytes to convert. The argument must either support the buffer protocol or be an iterable object producing bytes. Bytes and bytearray are examples of built-in objects that support the buffer protocol.

    byteorder

      The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use sys.byteorder as the byte order value. Default is to use ‘big’.

    signed

      Indicates whether two’s complement is used to represent the integer.

  Close(CloseHandle=None)
  Detach()
  as_integer_ratio(/)

    Return a pair of integers, whose ratio is equal to the original int.

    The ratio is in lowest terms and has a positive denominator.

        >>> (10).as_integer_ratio()
        (10, 1)
        >>> (-10).as_integer_ratio()
        (-10, 1)
        >>> (0).as_integer_ratio()
        (0, 1)

  bit_count(/)

    Number of ones in the binary representation of the absolute value of self.

    Also known as the population count.

        >>> bin(13)
        '0b1101'
        >>> (13).bit_count()
        3

  bit_length(/)

    Number of bits necessary to represent self in binary.

        >>> bin(37)
        '0b100101'
        >>> (37).bit_length()
        6

  conjugate(/)

    Returns self, the complex conjugate of any int.

  is_integer(/)

    Returns True. Exists for duck type compatibility with float.is_integer.

  to_bytes(/, length=1, byteorder='big', *, signed=False)

    Return an array of bytes representing an integer.

    length

      Length of bytes object to use. An OverflowError is raised if the integer is not representable with the given number of bytes. Default is length 1.

    byteorder

      The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use sys.byteorder as the byte order value. Default is to use ‘big’.

    signed

      Determines whether two’s complement is used to represent the integer. If signed is False and a negative integer is given, an OverflowError is raised.

  closed = False
  denominator

    the denominator of a rational number in lowest terms

  imag

    the imaginary part of a complex number

  numerator

    the numerator of a rational number in lowest terms

  real

    the real part of a complex number

class xonsh.procs.proxies.ProcProxy(f, args, stdin=None, stdout=None, stderr=None, universal_newlines=False, close_fds=False, env=None)

  This is process proxy class that runs its alias functions on the same thread that it was called from, which is typically the main thread. This prevents the process from running on a background thread, but enables debugger and profiler tools (functions) be run on the same thread that they are attempting to debug.

  poll()

    Check if the function has completed via the returncode or None.

  wait(timeout=None)

    Runs the function and returns the result. Timeout argument only present for API compatibility.

class xonsh.procs.proxies.ProcProxyThread(f, args, stdin=None, stdout=None, stderr=None, universal_newlines=False, close_fds=False, env=None)

  Class representing a function to be run as a subprocess-mode command.

  Parameters:
    f function

      The function to be executed.

    args list

      A (possibly empty) list containing the arguments that were given on the command line

    stdin file-like, optional

      A file-like object representing stdin (input can be read from here). If stdin is not provided or if it is explicitly set to None, then an instance of io.StringIO representing an empty file is used.

    stdout file-like, optional

      A file-like object representing stdout (normal output can be written here). If stdout is not provided or if it is explicitly set to None, then sys.stdout is used.

    stderr file-like, optional

      A file-like object representing stderr (error output can be written here). If stderr is not provided or if it is explicitly set to None, then sys.stderr is used.

    universal_newlines bool, optional

      Whether or not to use universal newlines.

    close_fds bool, optional

      Whether or not to close file descriptors. This is here for Popen compatability and currently does nothing.

    env Mapping, optional

      Environment mapping.

  getName()

    Return a string used for identification purposes only.

    This method is deprecated, use the name attribute instead.

  isDaemon()

    Return whether this thread is a daemon.

    This method is deprecated, use the daemon attribute instead.

  is_alive()

    Return whether the thread is alive.

    This method returns True just before the run() method starts until just after the run() method terminates. See also the module function enumerate().

  join(timeout=None)

    Wait until the thread terminates.

    This blocks the calling thread until the thread whose join() method is called terminates – either normally or through an unhandled exception or until the optional timeout occurs.

    When the timeout argument is present and not None, it should be a floating-point number specifying a timeout for the operation in seconds (or fractions thereof). As join() always returns None, you must call is_alive() after join() to decide whether a timeout happened – if the thread is still alive, the join() call timed out.

    When the timeout argument is not present or None, the operation will block until the thread terminates.

    A thread can be join()ed many times.

    join() raises a RuntimeError if an attempt is made to join the current thread as that would cause a deadlock. It is also an error to join() a thread before it has been started and attempts to do so raises the same exception.

  poll()

    Check if the function has completed.

    Returns:
      None if the function is still executing, and the returncode otherwise
  run()

    Set up input/output streams and execute the child function in a new thread. This is part of the threading.Thread interface and should not be called directly.

  setDaemon(daemonic)

    Set whether this thread is a daemon.

    This method is deprecated, use the .daemon property instead.

  setName(name)

    Set the name string for this thread.

    This method is deprecated, use the name attribute instead.

  start()

    Start the thread’s activity.

    It must be called at most once per thread object. It arranges for the object’s run() method to be invoked in a separate thread of control.

    This method will raise a RuntimeError if called more than once on the same thread object.

  wait(timeout=None)

    Waits for the process to finish and returns the return code.

  property daemon

    A boolean value indicating whether this thread is a daemon thread.

    This must be set before start() is called, otherwise RuntimeError is raised. Its initial value is inherited from the creating thread; the main thread is not a daemon thread and therefore all threads created in the main thread default to daemon = False.

    The entire Python program exits when only daemon threads are left.

  property ident

    Thread identifier of this thread or None if it has not been started.

    This is a nonzero integer. See the get_ident() function. Thread identifiers may be recycled when a thread exits and another thread is created. The identifier is available even after the thread has exited.

  property name

    A string used for identification purposes only.

    It has no semantics. Multiple threads may be given the same name. The initial name is set by the constructor.

  property native_id

    Native integral thread ID of this thread, or None if it has not been started.

    This is a non-negative integer. See the get_native_id() function. This represents the Thread ID as reported by the kernel.

xonsh.procs.proxies.get_proc_proxy_name(cls)

xonsh.procs.proxies.parse_proxy_return(r, stdout, stderr)

  Proxies may return a variety of outputs. This handles them generally.

  Parameters:
    r tuple, str, int, or None

      Return from proxy function

    stdout file-like

      Current stdout stream

    stdout file-like

      Current stderr stream

  Returns:
    cmd_result int

      The return code of the proxy

xonsh.procs.proxies.safe_flush(handle)

  Attempts to safely flush a file handle, returns success bool.

xonsh.procs.proxies.still_writable(fd)

  Determines whether a file descriptor is still writable by trying to write an empty string and seeing if it fails.