Python Forum
pydoc3 server and browser - Printable Version

+- Python Forum (
+-- Forum: Python Coding (
+--- Forum: General Coding Help (
+--- Thread: pydoc3 server and browser (/Thread-pydoc3-server-and-browser)

pydoc3 server and browser - fmouse - Sep-18-2019

For some time I've been starting a pydoc server (Python 2.7) from my desktop startup scripts and using it to document a server directory containing a collection of Python scripts. This script is simple:

cd [NFS-mounted directory containing Python scripts]
sudo pydoc -p 789 & > /dev/null 2>&1

This works as expected and I can access the documentation with http://localhost:789

Pursuant to moving toward pyton3, I want to do the same thing with pydoc3, however pydoc3 insists on opening a "server>" interactive prompt which I don't need and can't suppress. The purpose of the prompt is apparently to allow CLI opening of a browser (so I have to use a non-privileged port) however in my case this is spurious since I have the URL bookmarked in my development browser.

Regular Unix job control commands don't work to background the pydoc3 server process, so it's effectively blocking at a shell level, making scripting difficult or impossible.

This looks like a bug, although I can't find any documentation on it. Is there a workaround?

RE: pydoc3 server and browser - fmouse - Sep-19-2019

This is more of an omission than a bug, it seems. The following diff (patch) adds a -d option which allows pydoc3 to operate purely in server mode so it can be used in a shell script and backgrounded with "&":

--- /usr/lib/python3.6/	2019-09-18 18:18:03.214625729 -0500
+++ /usr/lib/python3.6/	2019-09-18 19:27:06.761990792 -0500
@@ -2550,7 +2550,7 @@
     raise TypeError('unknown content type %r for url %s' % (content_type, url))
-def browse(port=0, *, open_browser=True):
+def browse(port=0, *, open_browser=True, allow_detach=False):
     """Start the enhanced pydoc Web server and open a Web browser.
     Use port '0' to start the server on an arbitrary port.
@@ -2561,6 +2561,8 @@
     if serverthread.error:
+    if allow_detach == True and open_browser == False:
+        return
     if serverthread.serving:
         server_help_msg = 'Server commands: [b]rowser, [q]uit'
         if open_browser:
@@ -2604,10 +2606,11 @@
         sys.path.insert(0, '.')
-        opts, args = getopt.getopt(sys.argv[1:], 'bk:p:w')
+        opts, args = getopt.getopt(sys.argv[1:], 'bdk:p:w')
         writing = False
         start_server = False
         open_browser = False
+        allow_detach = False
         port = None
         for opt, val in opts:
             if opt == '-b':
@@ -2621,11 +2624,13 @@
                 port = val
             if opt == '-w':
                 writing = True
+            if opt == '-d':
+                allow_detach = True
         if start_server:
             if port is None:
                 port = 0
-            browse(port, open_browser=open_browser)
+            browse(port, open_browser=open_browser, allow_detach=allow_detach)
         if not args: raise BadUsage
@@ -2670,6 +2675,11 @@
     to interactively browse documentation.  The -p option can be used with
     the -b option to explicitly specify the server port.
+{cmd} -d
+    Start the HTTP server but don't prompt for browser or attempt to start
+    one unless the -b option is specified. Allows backgrounding of 
+    documentation server in a shell scripting context.
 {cmd} -w <name> ...
     Write out the HTML documentation for a module to a file in the current
     directory.  If <name> contains a '{sep}', it is treated as a filename; if
Apply this as a patch to /usr/lib/python3.x/ with /usr/bin/patch.