Application Programming Interface (API)
=======================================

.. py:module:: pushy

.. py:function:: connect(target, [python="python", [\*\*kwargs]])

   Create a Pushy connection.

   :param target: Identifies which transport to use, and the endpoint to connect to. The argument must be formatted as: *transport*:[*transport-specific-address*].

      >>> pushy.connect("local:")
      <pushy.client.PushyClient object at ...>

      >>> pushy.connect("ssh:remotehost")
      <pushy.client.PushyClient object at ...>

   :type target: string
   :param python: Specifies the path to the Python executable to invoke on the remote host which is being connected to. By default it is simply "python", in which case standard PATH lookup will be used.
   :type python: string

   Some transports will require additional information to create a connection,
   such as a username and password. To support this, all keyword arguments are
   passed through to the transport's :py:func:`pushy.transport.Popen` function.
   The address component of ``target`` is passed to the Popen function with the
   name ``address``. For details on the keyword arguments expected by the
   builtin transports, see :py:mod:`pushy.transport`.


.. py:class:: PushyClient

    This class is instantiated by :py:func:`pushy.connect`, and is the primary
    interface for interacting with the remote interpreter. It provides methods
    for evaluating Python expressions, copying files between local and remote
    hosts, and for obtaining references to Python modules in the remote
    interpreter.

    .. py:attribute:: modules

       Provides access to the remote interpreter's modules. Accessing an
       attribute of ``modules`` is equivalent to importing a module.

          >>> conn = pushy.connect("local:")
          >>> conn.modules.os
          <module 'os' from 'C:\Python26\lib\os.pyc'>
          >>> os.getpid()
          4772
          >>> conn.modules.os.getpid()
          5564


    .. py:attribute:: gc_enabled

       Boolean flag to specify whether proxies should be garbage collected or
       not. Disabling garbage collection may improve the speed of Pushy, at the
       cost of memory growth as new objects are proxied. Garbage collection is
       enabled by default.


    .. py:attribute:: gc_interval

       Time in seconds between reconciliation of garbage collected objects.

       If :py:attr:`gc_enabled` is set to True, then object proxies may be
       garbage collected. When object proxies are garbage collected, their
       remote counterpart must be also be deleted (reconciled). The garbage
       collection process will enqueue deletions and, after gc_interval seconds
       have elapsed since the previous remote-deletion, send a message to the
       peer to delete the objects enqueued by the garbage collector. The
       default garbage collection interval is five seconds.


    .. py:method:: close()

       Close the connection.

         >>> conn = pushy.connect("local:")
         >>> conn.close()


    .. py:method:: compile(code, [mode="exec"])

       Compiles Python source or function objects in the remote Python
       interpreter, returning proxied code objects or function objects
       respectively.

       :param code: A string representing a Python expression, or a function
                    object to be recompiled in the remote interpreter.
       :type code: string or function
       :param mode: The compilation mode for compiling Python source (ignored
                    for function compilation).
       :type mode: string

       >>> conn = pushy.connect("local:")
       >>> conn.compile("1+2", "eval")      # Returns a code object.
       >>> conn.compile(lambda a, b: a + b) # Returns a function object.


    .. py:method:: eval(code, [globals=None, [locals=None]])

       Evaluate an expression or code object in the remote Python interpreter.

       :param code: A string representing a Python expression, or a code object
                    as returned by compile().
       :type code: string or code
       :param globals: A dictionary for global variables. If ``locals`` is not
                       specified, then ``globals`` will be used for both global
                       and local variables.
       :type globals: dict
       :param locals: A dictionary for local variables.
       :type locals: any mapping type

       >>> conn = pushy.connect("local:")
       >>> assert conn.eval("1+2") == 3
       >>> remote_str_type = conn.eval("str")


    .. py:method:: execute(source, [globals=None, [locals=None]])

       Executes Python source code in the remote interpreter. This is a
       shortcut to ``eval(compile(source), globals, locals)``.

       :param source: A stirng representing a Python statement.
       :type source: string
       :param globals: A dictionary for global variables. If ``locals`` is not
                       specified, then ``globals`` will be used for both global
                       and local variables.
       :type globals: dict
       :param locals: A dictionary for local variables.
       :type locals: any mapping type

       >>> conn = pushy.connect("local:")
       >>> locals_ = {}
       >>> conn.execute("def abc():\n\tprint 123", locals=locals_)
       >>> locals_["abc"]()
       123


    .. py:method:: getfile(remote_path, local_path)

       Copy a file from the remote host to the local host. If the transport
       class defines a ``getfile`` method, that will be used to perform the
       transfer. Otherwise, Pushy will fall back to a relatively inefficient,
       transport-independent method.

         >>> conn = pushy.connect("local:")
         >>> conn.getfile("/remote/path/to/foo.txt", "/local/path/to/bar.txt")


    .. py:method:: putfile(local_path, remote_path)

       Copy a file from the local host to the remote host. If the transport
       class defines a ``putfile`` method, that will be used to perform the
       transfer. Otherwise, Pushy will fall back to a relatively inefficient,
       transport-independent method.

         >>> conn = pushy.connect("local:")
         >>> conn.putfile("/local/path/to/foo.txt", "/remote/path/to/bar.txt")


    .. py::method:: remote_import(name)

       Import a remote Python module.

         >>> conn = pushy.connect("local:")
         >>> os_path = conn.remote_import("os.path")
         >>> remote_home = os_path.expanduser("~")