Set the wrap width for python docs in a terminal

Question

I am using the python shell in a TTY terminal, and it is extremely irritating that all the documentation wraps at such a narrow width. My screen is 1600 by 900 pixels, with my terminal at 200 by 56 characters, but the python documentation from the shell insists on wrapping at a much narrower width. (Lines that I enter at the prompt are not limited; it allows them to run the full screen width.)

I am aware that PEP-8 Maximum Line Length specifies that docstrings be limited to 72 characters per line, but is there a way to get it to use the whole terminal anyway? I know javadoc removes extra line wrapping from javadoc comments; I am after something that works somewhat like that.

The biggest problem with this is the module list: instead of using the whole width of my screen when it lists all the module names, it only uses the narrow wrap width, displaying the modules in four columns only, and so it can't actually fit the whole list on my screen (although it fits perfectly on other monitors). I can't just pipe it through less either, like I do with oversized --help text in bash.

Answer 1

== Edit == Updated

So the problem you'll run into is that for the CLI based help, the doc string width really is only limited by the newlines in the original documentation. That is to say, when you run 'help(future)', it just prints out the doc string and pages it. Nothing fancy, no formatting done on the fly. This is why if you render the doc to HTML you can modify the browser width and it'll wrap differently.

The only way I found to modify this behavior is if you actually modify the docstring itself.

Here's a quick example of how to monkey-patch doc strings. Essentially in a docstring, the newlines are hard-coded to the end of the line, such that

a = """
one
two

three
"""

Encodes into

'\none\ntwo\n\nthree\n'

If you wanted 'wrap' line automatically, you just need to replace \n[^\n] (any newline + character that isn't a newline) with the captured character.

re.sub('\n([^\n])', ' \g<1>', a)

a then becomes

' one two\n three\n'

This is a super hacky way of doing things, but the only way I can think of to reformat things so that they wrap.

A better example would be:

#!/usr/bin/python

import pydoc
import re

t = re.sub('\n([^\n])', ' \g<1>', pydoc.__doc__)
pydoc.__doc__ = t
help(pydoc)

== Edit ==

This may or may not suit your needs, but I had a similar gripe that I solved a little differently. I wrote a 'help' wrapper that loads stdlib docs in a browser in the background. It may or may not help you - one nice thing is that the HTML output of pydoc stuff allows for variable widths on paragraphs.

You can take the attached script, import it from site.py and then when you run help() from the CLI on any stdlib stuff, it'll open the corresponding webpage automatically. This doesn't do anything for your own local stuff (I don't think, it's been a while), but could be modified to do so.

If you're hardcore CLI guy, apologies. But when faced with a similar gripe with regards to the output of stuff this is what I initially tried.

#!/usr/bin/python

import inspect
import os
import sys
import webbrowser
from pydoc import Helper

__all__ = ['MyHelper', 'old_help', 'help']


class MyHelper(Helper):

    def __init__(self):
        Helper.__init__(self)

    def getdocloc(self, object):
        global old_help
        """Return the location of module docs or None"""
        try:
            file = inspect.getabsfile(object)
        except TypeError:
            file = '(built-in)'

        docloc = os.environ.get("PYTHONDOCS", "http://docs.python.org/library")
        basedir = os.path.join(sys.exec_prefix, "lib", "python"+sys.version[0:3])
        BUILTINS_LIST = ( 'errno', 'exceptions', 'gc', 'imp', 'marshal', 'posix', 'signal', 'sys', 'thread', 'zipimport')
        if (isinstance(object, type(os)) and (object.__name__ in BUILTINS_LIST or file.startswith(basedir)) and object.__name__ not in ('xml.etree', 'test.pydoc_mod')):
            if docloc.startswith("http://"):
                docloc = "%s/%s" % (docloc.rstrip("/"), object.__name__)
            else:
                docloc = os.path.join(docloc, object.__name__ + ".html")
        else:
            docloc = None
        return docloc

    def __repr__(self):
        global old_help
        if inspect.stack()[1][3] == '?':
            return self()
            return ''
        else:
            return '<HHhelp instance>'

    def help(self, *args):
        print args
        global old_help
        if isinstance(args[0], object):
            docloc = self.getdocloc(args[0])
            print '********',docloc,type(docloc)
            if isinstance(docloc, str):
                if docloc.find('http://') == 0:
                    webbrowser.open(docloc)
        else: 
            old_help(args)

global old_help, help
old_help = help
help = MyHelper()

The second solution I use for getting pretty Python docs is using Sphinx's sphinx-apidoc to automatically generate API documents for Python modules. The standard Python doc output stuff is really limiting (as you're experiencing).

However, with that said - I bet that the width for docs is configurable somehow but will require monkey patching... I'll poke around a bit and see what I can find.