work on Text and Edit docstrings

--HG--
branch : feature-sphinx

1 files changed, 129 insertions, 68 deletions

diff --git a/urwid/widget.py b/urwid/widget.py
index 2f210fc..3549fd0 100644
--- a/urwid/widget.py
+++ b/urwid/widget.py
@@ -732,13 +732,21 @@ class Text(Widget):
 
     def __init__(self, markup, align=LEFT, wrap=SPACE, layout=None):
         """
-        markup -- content of text widget, one of:
-            plain string -- string is displayed
-            ( attr, markup2 ) -- markup2 is given attribute attr
-            [ markupA, markupB, ... ] -- list items joined together
-        align -- align mode for text layout
-        wrap -- wrap mode for text layout
-        layout -- layout object to use, defaults to StandardTextLayout
+        :param markup: content of text widget, one of:
+
+            * bytes or unicode -- text to be displayed
+            * ``(attr, text markup)`` -- text markup with display
+              attribute ``attr`` applied to it
+            * ``[text markup, text markup, ... ]`` -- all text
+              markup in the list joined together
+
+        :type markup: text markup
+        :param align: typically 'left', 'center' or 'right'
+        :type align: text alignment mode
+        :param wrap: typically 'space', 'any' or 'clip'
+        :type wrap: text wrapping mode
+        :param layout: defaults to a shared :class:`StandardTextLayout` instance
+        :type layout: text layout instance
 
         >>> Text(u"Hello")
         <Text flow widget 'Hello'>
@@ -782,7 +790,8 @@ class Text(Widget):
         """
         Set content of text widget.
 
-        markup -- see __init__() for description.
+        :param markup: see :meth:`Text.__init__` for description.
+        :type markup: text markup
 
         >>> t = Text(u"foo")
         >>> print t.text
@@ -799,10 +808,14 @@ class Text(Widget):
 
     def get_text(self):
         """
-        Returns (text, attributes).
+        Returns ``(text, display attributes)``.
 
-        text -- complete string content (unicode) of text widget
-        attributes -- run length encoded attributes for text
+        text
+          complete bytes/unicode content of text widget
+
+        display attributes
+          run length encoded attributes for text, eg.
+          ``[('attr1', 10), ('attr2', 5)]``
 
         >>> Text(u"Hello").get_text() # ... = u in Python 2
         (...'Hello', [])
@@ -818,10 +831,11 @@ class Text(Widget):
 
     def set_align_mode(self, mode):
         """
-        Set text alignment / justification.
+        Set text alignment mode. Supported modes depend on text layout
+        object in use but defaults to a :class:`StandardTextLayout` instance
 
-        Valid modes for StandardTextLayout are:
-            'left', 'center' and 'right'
+        :param align: typically 'left', 'center' or 'right'
+        :type align: text alignment mode
 
         >>> t = Text(u"word")
         >>> t.set_align_mode('right')
@@ -844,12 +858,11 @@ class Text(Widget):
 
     def set_wrap_mode(self, mode):
         """
-        Set wrap mode.
+        Set text wrapping mode. Supported modes depend on text layout
+        object in use but defaults to a :class:`StandardTextLayout` instance
 
-        Valid modes for StandardTextLayout are :
-            'any'    : wrap at any character
-            'space'    : wrap on space character
-            'clip'    : truncate lines instead of wrapping
+        :param wrap: typically 'space', 'any' or 'clip'
+        :type wrap: text wrapping mode
 
         >>> t = Text(u"some words")
         >>> t.render((6,)).text # ... = b in Python 3
@@ -873,11 +886,14 @@ class Text(Widget):
 
     def set_layout(self, align, wrap, layout=None):
         """
-        Set layout object, align and wrap modes.
+        Set the text layout object, alignment and wrapping modes at
+        the same time.
 
-        align -- align mode for text layout
-        wrap -- wrap mode for text layout
-        layout -- layout object to use, defaults to StandardTextLayout
+        :type align: text alignment mode
+        :param wrap: typically 'space', 'any' or 'clip'
+        :type wrap: text wrapping mode
+        :param layout: defaults to a shared :class:`StandardTextLayout` instance
+        :type layout: text layout instance
 
         >>> t = Text(u"hi")
         >>> t.set_layout('right', 'clip')
@@ -911,7 +927,7 @@ class Text(Widget):
 
     def rows(self, size, focus=False):
         """
-        Return the number of rows the rendered text spans.
+        Return the number of rows the rendered text requires.
 
         >>> Text(u"important things").rows((18,))
         1
@@ -927,9 +943,11 @@ class Text(Widget):
         This method is used internally, but may be useful for
         debugging custom layout classes.
 
-        maxcol -- columns available for display
-        ta -- None or the (text, attr) tuple returned from
-              self.get_text()
+        :param maxcol: columns available for display
+        :type maxcol: int
+        :param ta: ``None`` or the ``(text, display attributes)`` tuple
+                   returned from :meth:``.get_text``
+        :type ta: text and display attributes
         """
         if not self._cache_maxcol or self._cache_maxcol != maxcol:
             self._update_cache_translation(maxcol, ta)
@@ -946,17 +964,18 @@ class Text(Widget):
 
     def _calc_line_translation(self, text, maxcol ):
         return self.layout.layout(
-            text, self._cache_maxcol, 
+            text, self._cache_maxcol,
             self._align_mode, self._wrap_mode )
 
     def pack(self, size=None, focus=False):
         """
         Return the number of screen columns and rows required for
-        this Text widget to be displayed without wrapping or 
+        this Text widget to be displayed without wrapping or
         clipping, as a single element tuple.
 
-        size -- None for unlimited screen columns or (maxcol,) to
-                specify a maximum column size
+        :param size: ``None`` for unlimited screen columns or ``(maxcol,)`` to
+                     specify a maximum column size
+        :type size: widget size
 
         >>> Text(u"important things").pack()
         (16, 1)
@@ -997,15 +1016,22 @@ class Edit(Text):
     Text editing widget implements cursor movement, text insertion and
     deletion.  A caption may prefix the editing area.  Uses text class
     for text layout.
-    """
 
-    # allow users of this class to listen for change events
-    # sent when the value of edit_text changes
+    Users of this class to listen for ``"change"`` events
+    sent when the value of edit_text changes.  See :func:``connect_signal``.
+    """
     # (this variable is picked up by the MetaSignals metaclass)
     signals = ["change"]
 
     def valid_char(self, ch):
-        """Return true for printable characters."""
+        """
+        Filter for text that may be entered into this widget by the user
+
+        :param ch: character to be inserted
+        :type ch: bytes or unicode
+
+        This implementation returns True for all printable characters.
+        """
         return is_wide_char(ch,0) or (len(ch)==1 and ord(ch) >= 32)
 
     def selectable(self): return True
@@ -1014,15 +1040,26 @@ class Edit(Text):
             align=LEFT, wrap=SPACE, allow_tab=False,
             edit_pos=None, layout=None, mask=None):
         """
-        caption -- markup for caption preceeding edit_text
-        edit_text -- text string for editing
-        multiline -- True: 'enter' inserts newline  False: return it
-        align -- align mode
-        wrap -- wrap mode
-        allow_tab -- True: 'tab' inserts 1-8 spaces  False: return it
-        edit_pos -- initial position for cursor, None:at end
-        layout -- layout object
-        mask -- character to mask away text with, None means no masking
+        :param caption: markup for caption preceeding edit_text, see
+                        :meth:`Text.__init__` for description of text markup.
+        :type caption: text markup
+        :param edit_text: initial text for editing, type (bytes or unicode)
+                          must match the text in the caption
+        :type edit_text: bytes or unicode
+        :param multiline: True: 'enter' inserts newline  False: return it
+        :type multiline: bool
+        :param align: typically 'left', 'center' or 'right'
+        :type align: text alignment mode
+        :param wrap: typically 'space', 'any' or 'clip'
+        :type wrap: text wrapping mode
+        :param allow_tab: True: 'tab' inserts 1-8 spaces  False: return it
+        :type allow_tab: bool
+        :param edit_pos: initial position for cursor, None:end of edit_text
+        :type edit_pos: int
+        :param layout: defaults to a shared :class:`StandardTextLayout` instance
+        :type layout: text layout instance
+        :param mask: hide text entered with this character, None:disable mask
+        :type mask: bytes or unicode
 
         >>> Edit()
         <Edit selectable flow widget '' edit_pos=0>
@@ -1059,15 +1096,17 @@ class Edit(Text):
 
     def get_text(self):
         """
-        Returns (text, attributes).
+        Returns ``(text, display attributes)``. See :meth:`Text.get_text`
+        for details.
 
-        text -- complete text of caption and edit_text, maybe masked away
-        attributes -- run length encoded attributes for text
+        Text returned includes the caption and edit_text, possibly masked.
 
-        >>> Edit("What? ","oh, nothing.").get_text() # ... = u in Python 2
+        >>> Edit(u"What? ","oh, nothing.").get_text() # ... = u in Python 2
         (...'What? oh, nothing.', [])
-        >>> Edit(('bright',"user@host:~$ "),"ls").get_text()
+        >>> Edit(('bright',u"user@host:~$ "),"ls").get_text()
         (...'user@host:~$ ls', [('bright', 13)])
+        >>> Edit(u"password:", u"seekrit", mask=u"*").get_text()
+        (...'password:******', [])
         """
 
         if self._mask is None:
@@ -1083,6 +1122,9 @@ class Edit(Text):
         Traceback (most recent call last):
         EditError: set_text() not supported.  Use set_caption() or set_edit_text() instead.
         """
+        # FIXME: this smells. reimplement Edit as a WidgetWrap subclass to
+        # clean this up
+
         # hack to let Text.__init__() work
         if not hasattr(self, '_text') and markup == "":
             self._text = None
@@ -1098,7 +1140,7 @@ class Edit(Text):
         to indicate the leftmost or rightmost column available.
 
         This method is used internally and by other widgets when
-        moving the cursor up or down between widgets so that the 
+        moving the cursor up or down between widgets so that the
         column selected is one that the user would expect.
 
         >>> size = (10,)
@@ -1128,11 +1170,11 @@ class Edit(Text):
             return self.get_cursor_coords((maxcol,))[0]
         else:
             return pref_col
-    
+
     def update_text(self):
         """
         No longer supported.
-        
+
         >>> Edit().update_text()
         Traceback (most recent call last):
         EditError: update_text() has been removed.  Use set_caption() or set_edit_text() instead.
@@ -1144,7 +1186,8 @@ class Edit(Text):
         """
         Set the caption markup for this widget.
 
-        caption -- see Text.__init__() for description of markup
+        :param caption: markup for caption preceeding edit_text, see
+                        :meth:`Text.__init__` for description of text markup.
 
         >>> e = Edit("")
         >>> e.set_caption("cap1")
@@ -1166,9 +1209,12 @@ class Edit(Text):
 
     def set_edit_pos(self, pos):
         """
-        Set the cursor position with a self.edit_text offset.  
+        Set the cursor position with a self.edit_text offset.
         Clips pos to [0, len(edit_text)].
 
+        :param pos: cursor position
+        :type pos: int
+
         >>> e = Edit(u"", u"word")
         >>> e.edit_pos
         4
@@ -1190,12 +1236,15 @@ class Edit(Text):
         self.pref_col_maxcol = None, None
         self._edit_pos = pos
         self._invalidate()
-    
+
     edit_pos = property(lambda self:self._edit_pos, set_edit_pos)
 
     def set_mask(self, mask):
         """
-        Set the character for masking text away. Empty means no masking.
+        Set the character for masking text away.
+
+        :param mask: hide text entered with this character, None:disable mask
+        :type mask: bytes or unicode
         """
 
         self._mask = mask
@@ -1205,6 +1254,10 @@ class Edit(Text):
         """
         Set the edit text for this widget.
 
+        :param text: text for editing, type (bytes or unicode)
+                     must match the text in the caption
+        :type text: bytes or unicode
+
         >>> e = Edit()
         >>> e.set_edit_text(u"yes")
         >>> print e.edit_text
@@ -1243,6 +1296,10 @@ class Edit(Text):
         This method is used by the keypress() method when inserting
         one or more characters into edit_text.
 
+        :param text: text for inserting, type (bytes or unicode)
+                     must match the text in the caption
+        :type text: bytes or unicode
+
         >>> e = Edit(u"", u"42")
         >>> e.insert_text(u".5")
         >>> e
@@ -1275,6 +1332,10 @@ class Edit(Text):
         """
         Return result of insert_text(text) without actually performing the
         insertion.  Handy for pre-validation.
+
+        :param text: text for inserting, type (bytes or unicode)
+                     must match the text in the caption
+        :type text: bytes or unicode
         """
 
         # if there's highlighted text, it'll get replaced by the new text
@@ -1397,7 +1458,7 @@ class Edit(Text):
         """
         Set the cursor position with (x,y) coordinates.
         Returns True if move succeeded, False otherwise.
-        
+
         >>> size = (10,)
         >>> e = Edit("","edit\\ntext")
         >>> e.move_cursor_to_coords(size, 5, 0)
@@ -1481,30 +1542,30 @@ class Edit(Text):
         #    d.coords['highlight'] = [ hstart, hstop ]
         return canv
 
-    
+
     def get_line_translation(self, maxcol, ta=None ):
         trans = Text.get_line_translation(self, maxcol, ta)
-        if not self._shift_view_to_cursor: 
+        if not self._shift_view_to_cursor:
             return trans
-        
+
         text, ignore = self.get_text()
-        x,y = calc_coords( text, trans, 
+        x,y = calc_coords( text, trans,
             self.edit_pos + len(self.caption) )
         if x < 0:
             return ( trans[:y]
                 + [shift_line(trans[y],-x)]
                 + trans[y+1:] )
         elif x >= maxcol:
-            return ( trans[:y] 
+            return ( trans[:y]
                 + [shift_line(trans[y],-(x-maxcol+1))]
                 + trans[y+1:] )
         return trans
-            
+
 
     def get_cursor_coords(self, size):
         """
         Return the (x,y) coordinates of cursor within widget.
-        
+
         >>> Edit("? ","yes").get_cursor_coords((10,))
         (5, 0)
         """
@@ -1512,19 +1573,19 @@ class Edit(Text):
 
         self._shift_view_to_cursor = True
         return self.position_coords(maxcol,self.edit_pos)
-    
-    
+
+
     def position_coords(self,maxcol,pos):
         """
         Return (x,y) coordinates for an offset into self.edit_text.
         """
-        
+
         p = pos + len(self.caption)
         trans = self.get_line_translation(maxcol)
         x,y = calc_coords(self.get_text()[0], trans,p)
         return x,y
 
-        
+