Update docs for PopenSpawn and Windows support

8 files changed, 71 insertions, 15 deletions

diff --git a/doc/api/fdpexpect.rst b/doc/api/fdpexpect.rst
index 8321454..3ddf2cd 100644
--- a/doc/api/fdpexpect.rst
+++ b/doc/api/fdpexpect.rst
@@ -13,10 +13,8 @@ fdspawn class
    .. automethod:: isalive
    .. automethod:: close
 
-   .. note::
-      :class:`fdspawn` inherits all of the methods of :class:`~pexpect.spawn`, 
-      but not all of them can be used, especially if the file descriptor is not
-      a terminal. Some methods may do nothing (e.g. :meth:`~fdspawn.kill`), while
-      others will raise an exception (e.g. :meth:`~fdspawn.terminate`).
-      This behaviour might be made more consistent in the future, so try to
-      avoid relying on it.
\ No newline at end of file
+   .. method:: expect
+               expect_exact
+               expect_list
+
+      As :class:`pexpect.spawn`.
diff --git a/doc/api/index.rst b/doc/api/index.rst
index fd017a5..5277d1c 100644
--- a/doc/api/index.rst
+++ b/doc/api/index.rst
@@ -6,6 +6,7 @@ API documentation
 
    pexpect
    fdpexpect
+   popen_spawn
    replwrap
    pxssh
 
diff --git a/doc/api/popen_spawn.rst b/doc/api/popen_spawn.rst
new file mode 100644
index 0000000..64cae15
--- /dev/null
+++ b/doc/api/popen_spawn.rst
@@ -0,0 +1,24 @@
+popen_spawn - use pexpect with a piped subprocess
+=================================================
+
+.. automodule:: pexpect.popen_spawn
+
+PopenSpawn class
+----------------
+
+.. autoclass:: PopenSpawn
+
+   .. automethod:: __init__
+   .. automethod:: send
+   .. automethod:: sendline
+   .. automethod:: write
+   .. automethod:: writelines
+   .. automethod:: kill
+   .. automethod:: sendeof
+   .. automethod:: wait
+   
+   .. method:: expect
+               expect_exact
+               expect_list
+
+      As :class:`pexpect.spawn`.
diff --git a/doc/history.rst b/doc/history.rst
index b33e4d9..1167865 100644
--- a/doc/history.rst
+++ b/doc/history.rst
@@ -7,14 +7,15 @@ Releases
 Version 4.0
 ```````````
 
-* Integration with :mod:`asyncio`: passing ``async=True`` to :meth:`~.expect`,
-  :meth:`~.expect_exact` or :meth:`~.expect_list` will make them return a
+* Integration with :mod:`asyncio`: passing ``async=True`` to :meth:`~.spawn.expect`,
+  :meth:`~.spawn.expect_exact` or :meth:`~.spawn.expect_list` will make them return a
   coroutine. You can get the result using ``yield from``, or wrap it in an
   :class:`asyncio.Task`. This allows the event loop to do other things while
   waiting for output that matches a pattern.
+* Experimental support for Windows (with some caveats)—see :ref:`windows`.
 * Enhancement: allow method as callbacks of argument ``events`` for
   :func:`pexpect.run` (:ghissue:`176`).
-* It is now possible to call :meth:`~.wait` multiple times, or after a process
+* It is now possible to call :meth:`~.spawn.wait` multiple times, or after a process
   is already determined to be terminated without raising an exception
   (:ghpull:`211`).
 * New :class:`pexpect.spawn` keyword argument, ``dimensions=(rows, columns)``
diff --git a/doc/install.rst b/doc/install.rst
index 297acf3..d310871 100644
--- a/doc/install.rst
+++ b/doc/install.rst
@@ -15,6 +15,7 @@ Requirements
 This version of Pexpect requires Python 2.6 or 3.2 or above. For older
 versions of Python, continue using Pexpect 2.4.
 
-Pexpect only works on POSIX systems, where the :mod:`pty` module
-is present in the standard library. It may be possible to run it on Windows
-using `Cygwin <http://www.cygwin.com/>`_.
+As of version 4.0, Pexpect can be used on Windows and POSIX systems. However,
+:class:`pexpect.spawn` and :func:`pexpect.run` are only available on POSIX,
+where the :mod:`pty` module is present in the standard library. See
+:ref:`windows` for more information.
diff --git a/doc/overview.rst b/doc/overview.rst
index c5bcb05..d394ef1 100644
--- a/doc/overview.rst
+++ b/doc/overview.rst
@@ -238,3 +238,20 @@ You can have these methods ignore timeout and block indefinitely by passing
 ``None`` for the timeout parameter::
 
     child.expect(pexpect.EOF, timeout=None)
+
+.. _windows:
+
+Pexpect on Windows
+------------------
+
+.. versionadded:: 4.0
+   Windows support
+
+Pexpect can be used on Windows to wait for a pattern to be produced by a child
+process, using :class:`pexpect.popen_spawn.PopenSpawn`, or a file descriptor,
+using :class:`pexpect.fdpexpect.fdspawn`. This should be considered experimental
+for now.
+
+:class:`pexpect.spawn` and :func:`pexpect.run` are *not* available on Windows,
+as they rely on Unix pseudoterminals (ptys). Cross platform code must not use
+these.
diff --git a/pexpect/fdpexpect.py b/pexpect/fdpexpect.py
index ca8cf07..dd1b492 100644
--- a/pexpect/fdpexpect.py
+++ b/pexpect/fdpexpect.py
@@ -85,10 +85,11 @@ class fdspawn(SpawnBase):
             return False
 
     def terminate (self, force=False):  # pragma: no cover
+        '''Deprecated and invalid. Just raises an exception.'''
         raise ExceptionPexpect('This method is not valid for file descriptors.')
     
     # These four methods are left around for backwards compatibility, but not
-    # documented as part of fdpexpect. You're encouraged to use os.write#
+    # documented as part of fdpexpect. You're encouraged to use os.write
     # directly.
     def send(self, s):
         "Write to fd, return number of bytes written"
diff --git a/pexpect/popen_spawn.py b/pexpect/popen_spawn.py
index ab51499..680dd8a 100644
--- a/pexpect/popen_spawn.py
+++ b/pexpect/popen_spawn.py
@@ -1,4 +1,4 @@
-"""Spawn interface using subprocess.Popen
+"""Provides an interface like pexpect.spawn interface using subprocess.Popen
 """
 import os
 import threading
@@ -121,6 +121,10 @@ class PopenSpawn(SpawnBase):
             self.send(s)
 
     def send(self, s):
+        '''Send data to the subprocess' stdin.
+        
+        Returns the number of bytes written.
+        '''
         s = self._coerce_send_string(s)
         self._log(s, 'send')
 
@@ -141,6 +145,10 @@ class PopenSpawn(SpawnBase):
         return n + self.send(self.linesep)
 
     def wait(self):
+        '''Wait for the subprocess to finish.
+        
+        Returns the exit code.
+        '''
         status = self.proc.wait()
         if status >= 0:
             self.exitstatus = status
@@ -152,6 +160,10 @@ class PopenSpawn(SpawnBase):
         return status
 
     def kill(self, sig):
+        '''Sends a Unix signal to the subprocess.
+        
+        Use constants from the :mod:`signal` module to specify which signal.
+        '''
         if sys.platform == 'win32':
             if sig in [signal.SIGINT, signal.CTRL_C_EVENT]:
                 sig = signal.CTRL_C_EVENT
@@ -163,4 +175,5 @@ class PopenSpawn(SpawnBase):
         os.kill(self.proc.pid, sig)
 
     def sendeof(self):
+        '''Closes the stdin pipe from the writing end.'''
         self.proc.stdin.close()