From 0d8f07305d7ddcf684c3db5680263c98cf70c067 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 5 Apr 2009 22:20:44 +0000 Subject: Update signature style of optional arguments, part two. --- Doc/library/binhex.rst | 5 ++--- Doc/library/bisect.rst | 47 +++++++++++++++++++---------------------------- Doc/library/builtins.rst | 1 - Doc/library/bz2.rst | 12 +++++------- Doc/library/calendar.rst | 48 +++++++++++++++++++++++------------------------- Doc/library/cgi.rst | 15 +++++++-------- Doc/library/cgitb.rst | 5 ++--- Doc/library/chunk.rst | 7 +++---- Doc/library/cmath.rst | 1 - Doc/library/cmd.rst | 5 ++--- Doc/library/code.rst | 16 ++++++++-------- Doc/library/codecs.rst | 23 ++++++++++++----------- 12 files changed, 83 insertions(+), 102 deletions(-) diff --git a/Doc/library/binhex.rst b/Doc/library/binhex.rst index 7f3fe81..43c7823 100644 --- a/Doc/library/binhex.rst +++ b/Doc/library/binhex.rst @@ -1,4 +1,3 @@ - :mod:`binhex` --- Encode and decode binhex4 files ================================================= @@ -19,11 +18,11 @@ The :mod:`binhex` module defines the following functions: supporting a :meth:`write` and :meth:`close` method). -.. function:: hexbin(input[, output]) +.. function:: hexbin(input, output) Decode a binhex file *input*. *input* may be a filename or a file-like object supporting :meth:`read` and :meth:`close` methods. The resulting file is written - to a file named *output*, unless the argument is omitted in which case the + to a file named *output*, unless the argument is ``None`` in which case the output filename is read from the binhex file. The following exception is also defined: diff --git a/Doc/library/bisect.rst b/Doc/library/bisect.rst index 9e77699..61b470b 100644 --- a/Doc/library/bisect.rst +++ b/Doc/library/bisect.rst @@ -1,4 +1,3 @@ - :mod:`bisect` --- Array bisection algorithm =========================================== @@ -17,43 +16,35 @@ example of the algorithm (the boundary conditions are already right!). The following functions are provided: -.. function:: bisect_left(list, item[, lo[, hi]]) - - Locate the proper insertion point for *item* in *list* to maintain sorted order. - The parameters *lo* and *hi* may be used to specify a subset of the list which - should be considered; by default the entire list is used. If *item* is already - present in *list*, the insertion point will be before (to the left of) any - existing entries. The return value is suitable for use as the first parameter - to ``list.insert()``. This assumes that *list* is already sorted. - - -.. function:: bisect_right(list, item[, lo[, hi]]) - - Similar to :func:`bisect_left`, but returns an insertion point which comes after - (to the right of) any existing entries of *item* in *list*. - - -.. function:: bisect(...) +.. function:: bisect_left(a, x, lo=0, hi=len(a)) - Alias for :func:`bisect_right`. + Locate the proper insertion point for *x* in *a* to maintain sorted order. + The parameters *lo* and *hi* may be used to specify a subset of the list + which should be considered; by default the entire list is used. If *x* is + already present in *a*, the insertion point will be before (to the left of) + any existing entries. The return value is suitable for use as the first + parameter to ``list.insert()``. This assumes that *a* is already sorted. -.. function:: insort_left(list, item[, lo[, hi]]) +.. function:: bisect_right(a, x, lo=0, hi=len(a)) + bisect(a, x, lo=0, hi=len(a)) - Insert *item* in *list* in sorted order. This is equivalent to - ``list.insert(bisect.bisect_left(list, item, lo, hi), item)``. This assumes - that *list* is already sorted. + Similar to :func:`bisect_left`, but returns an insertion point which comes + after (to the right of) any existing entries of *x* in *a*. -.. function:: insort_right(list, item[, lo[, hi]]) +.. function:: insort_left(a, x, lo=0, hi=len(a)) - Similar to :func:`insort_left`, but inserting *item* in *list* after any - existing entries of *item*. + Insert *x* in *a* in sorted order. This is equivalent to + ``a.insert(bisect.bisect_left(a, x, lo, hi), x)``. This assumes that *a* is + already sorted. -.. function:: insort(...) +.. function:: insort_right(a, x, lo=0, hi=len(a)) + insort(a, x, lo=0, hi=len(a)) - Alias for :func:`insort_right`. + Similar to :func:`insort_left`, but inserting *x* in *a* after any existing + entries of *x*. Examples diff --git a/Doc/library/builtins.rst b/Doc/library/builtins.rst index 2a5c7f5..217b161 100644 --- a/Doc/library/builtins.rst +++ b/Doc/library/builtins.rst @@ -1,4 +1,3 @@ - :mod:`builtins` --- Built-in objects ==================================== diff --git a/Doc/library/bz2.rst b/Doc/library/bz2.rst index ee79edc..a2272e6 100644 --- a/Doc/library/bz2.rst +++ b/Doc/library/bz2.rst @@ -1,9 +1,9 @@ - :mod:`bz2` --- Compression compatible with :program:`bzip2` =========================================================== .. module:: bz2 - :synopsis: Interface to compression and decompression routines compatible with bzip2. + :synopsis: Interface to compression and decompression routines + compatible with bzip2. .. moduleauthor:: Gustavo Niemeyer .. sectionauthor:: Gustavo Niemeyer @@ -42,7 +42,7 @@ Here is a summary of the features offered by the bz2 module: Handling of compressed files is offered by the :class:`BZ2File` class. -.. class:: BZ2File(filename[, mode[, buffering[, compresslevel]]]) +.. class:: BZ2File(filename, mode='r', buffering=0, compresslevel=9) Open a bz2 file. Mode can be either ``'r'`` or ``'w'``, for reading (default) or writing. When opened for writing, the file will be created if it doesn't @@ -129,14 +129,13 @@ Sequential compression and decompression is done using the classes :class:`BZ2Compressor` and :class:`BZ2Decompressor`. -.. class:: BZ2Compressor([compresslevel]) +.. class:: BZ2Compressor(compresslevel=9) Create a new compressor object. This object may be used to compress data sequentially. If you want to compress data in one shot, use the :func:`compress` function instead. The *compresslevel* parameter, if given, must be a number between ``1`` and ``9``; the default is ``9``. - .. method:: compress(data) Provide more data to the compressor object. It will return chunks of @@ -157,7 +156,6 @@ Sequential compression and decompression is done using the classes sequentially. If you want to decompress data in one shot, use the :func:`decompress` function instead. - .. method:: decompress(data) Provide more data to the decompressor object. It will return chunks of @@ -174,7 +172,7 @@ One-shot compression and decompression is provided through the :func:`compress` and :func:`decompress` functions. -.. function:: compress(data[, compresslevel]) +.. function:: compress(data, compresslevel=9) Compress *data* in one shot. If you want to compress data sequentially, use an instance of :class:`BZ2Compressor` instead. The *compresslevel* parameter, diff --git a/Doc/library/calendar.rst b/Doc/library/calendar.rst index d575228..1cf958c 100644 --- a/Doc/library/calendar.rst +++ b/Doc/library/calendar.rst @@ -1,10 +1,9 @@ - :mod:`calendar` --- General calendar-related functions ====================================================== .. module:: calendar - :synopsis: Functions for working with calendars, including some emulation of the Unix cal - program. + :synopsis: Functions for working with calendars, including some emulation + of the Unix cal program. .. sectionauthor:: Drew Csillag @@ -23,7 +22,7 @@ calendar in Dershowitz and Reingold's book "Calendrical Calculations", where it's the base calendar for all computations. -.. class:: Calendar([firstweekday]) +.. class:: Calendar(firstweekday=0) Creates a :class:`Calendar` object. *firstweekday* is an integer specifying the first day of the week. ``0`` is Monday (the default), ``6`` is Sunday. @@ -82,7 +81,7 @@ it's the base calendar for all computations. weeks. Weeks are lists of seven day numbers. - .. method:: yeardatescalendar(year[, width]) + .. method:: yeardatescalendar(year, width=3) Return the data for the specified year ready for formatting. The return value is a list of month rows. Each month row contains up to *width* @@ -90,28 +89,27 @@ it's the base calendar for all computations. each week contains 1--7 days. Days are :class:`datetime.date` objects. - .. method:: yeardays2calendar(year[, width]) + .. method:: yeardays2calendar(year, width=3) Return the data for the specified year ready for formatting (similar to :meth:`yeardatescalendar`). Entries in the week lists are tuples of day numbers and weekday numbers. Day numbers outside this month are zero. - .. method:: yeardayscalendar(year[, width]) + .. method:: yeardayscalendar(year, width=3) Return the data for the specified year ready for formatting (similar to :meth:`yeardatescalendar`). Entries in the week lists are day numbers. Day numbers outside this month are zero. -.. class:: TextCalendar([firstweekday]) +.. class:: TextCalendar(firstweekday=0) This class can be used to generate plain text calendars. - :class:`TextCalendar` instances have the following methods: - .. method:: formatmonth(theyear, themonth[, w[, l]]) + .. method:: formatmonth(theyear, themonth, w=0, l=0) Return a month's calendar in a multi-line string. If *w* is provided, it specifies the width of the date columns, which are centered. If *l* is @@ -120,12 +118,12 @@ it's the base calendar for all computations. :meth:`setfirstweekday` method. - .. method:: prmonth(theyear, themonth[, w[, l]]) + .. method:: prmonth(theyear, themonth, w=0, l=0) Print a month's calendar as returned by :meth:`formatmonth`. - .. method:: formatyear(theyear, themonth[, w[, l[, c[, m]]]]) + .. method:: formatyear(theyear, themonth, w=2, l=1, c=6, m=3) Return a *m*-column calendar for an entire year as a multi-line string. Optional parameters *w*, *l*, and *c* are for date column width, lines per @@ -135,32 +133,32 @@ it's the base calendar for all computations. can be generated is platform-dependent. - .. method:: pryear(theyear[, w[, l[, c[, m]]]]) + .. method:: pryear(theyear, w=2, l=1, c=6, m=3) Print the calendar for an entire year as returned by :meth:`formatyear`. -.. class:: HTMLCalendar([firstweekday]) +.. class:: HTMLCalendar(firstweekday=0) This class can be used to generate HTML calendars. :class:`HTMLCalendar` instances have the following methods: - .. method:: formatmonth(theyear, themonth[, withyear]) + .. method:: formatmonth(theyear, themonth, withyear=True) Return a month's calendar as an HTML table. If *withyear* is true the year will be included in the header, otherwise just the month name will be used. - .. method:: formatyear(theyear, themonth[, width]) + .. method:: formatyear(theyear, themonth, width=3) Return a year's calendar as an HTML table. *width* (defaulting to 3) specifies the number of months per row. - .. method:: formatyearpage(theyear[, width[, css[, encoding]]]) + .. method:: formatyearpage(theyear, width=3, css='calendar.css', encoding=None) Return a year's calendar as a complete HTML page. *width* (defaulting to 3) specifies the number of months per row. *css* is the name for the @@ -169,7 +167,7 @@ it's the base calendar for all computations. output (defaulting to the system default encoding). -.. class:: LocaleTextCalendar([firstweekday[, locale]]) +.. class:: LocaleTextCalendar(firstweekday=0, locale=None) This subclass of :class:`TextCalendar` can be passed a locale name in the constructor and will return month and weekday names in the specified @@ -177,7 +175,7 @@ it's the base calendar for all computations. weekday names will be returned as unicode. -.. class:: LocaleHTMLCalendar([firstweekday[, locale]]) +.. class:: LocaleHTMLCalendar(firstweekday=0, locale=None) This subclass of :class:`HTMLCalendar` can be passed a locale name in the constructor and will return month and weekday names in the specified @@ -241,26 +239,26 @@ For simple text calendars this module provides the following functions. unless set by :func:`setfirstweekday`. -.. function:: prmonth(theyear, themonth[, w[, l]]) +.. function:: prmonth(theyear, themonth, w=0, l=0) Prints a month's calendar as returned by :func:`month`. -.. function:: month(theyear, themonth[, w[, l]]) +.. function:: month(theyear, themonth, w=0, l=0) Returns a month's calendar in a multi-line string using the :meth:`formatmonth` of the :class:`TextCalendar` class. -.. function:: prcal(year[, w[, l[c]]]) +.. function:: prcal(year, w=0, l=0, c=6, m=3) Prints the calendar for an entire year as returned by :func:`calendar`. -.. function:: calendar(year[, w[, l[c]]]) +.. function:: calendar(year, w=2, l=1, c=6, m=3) - Returns a 3-column calendar for an entire year as a multi-line string using the - :meth:`formatyear` of the :class:`TextCalendar` class. + Returns a 3-column calendar for an entire year as a multi-line string using + the :meth:`formatyear` of the :class:`TextCalendar` class. .. function:: timegm(tuple) diff --git a/Doc/library/cgi.rst b/Doc/library/cgi.rst index ad7d348..42acdcf 100644 --- a/Doc/library/cgi.rst +++ b/Doc/library/cgi.rst @@ -1,6 +1,5 @@ - -:mod:`cgi` --- Common Gateway Interface support. -================================================ +:mod:`cgi` --- Common Gateway Interface support +=============================================== .. module:: cgi :synopsis: Helpers for running Python scripts via the Common Gateway Interface. @@ -220,7 +219,7 @@ A more convenient approach is to use the methods :meth:`getfirst` and :meth:`getlist` provided by this higher level interface. -.. method:: FieldStorage.getfirst(name[, default]) +.. method:: FieldStorage.getfirst(name, default=None) This method always returns only one value associated with form field *name*. The method returns only the first value in case that more values were posted @@ -255,19 +254,19 @@ These are useful if you want more control, or if you want to employ some of the algorithms implemented in this module in other circumstances. -.. function:: parse(fp[, keep_blank_values[, strict_parsing]]) +.. function:: parse(fp=None, environ=os.environ, keep_blank_values=False, strict_parsing=False) Parse a query in the environment or from a file (the file defaults to ``sys.stdin``). The *keep_blank_values* and *strict_parsing* parameters are passed to :func:`urllib.parse.parse_qs` unchanged. -.. function:: parse_qs(qs[, keep_blank_values[, strict_parsing]]) +.. function:: parse_qs(qs, keep_blank_values=False, strict_parsing=False) This function is deprecated in this module. Use :func:`urllib.parse.parse_qs` instead. It is maintained here only for backward compatibility. -.. function:: parse_qsl(qs[, keep_blank_values[, strict_parsing]]) +.. function:: parse_qsl(qs, keep_blank_values=False, strict_parsing=False) This function is deprecated in this module. Use :func:`urllib.parse.parse_qs` instead. It is maintained here only for backward compatibility. @@ -319,7 +318,7 @@ algorithms implemented in this module in other circumstances. Print a list of useful (used by CGI) environment variables in HTML. -.. function:: escape(s[, quote]) +.. function:: escape(s, quote=False) Convert the characters ``'&'``, ``'<'`` and ``'>'`` in string *s* to HTML-safe sequences. Use this if you need to display text that might contain such diff --git a/Doc/library/cgitb.rst b/Doc/library/cgitb.rst index 854ea95..6827c8e 100644 --- a/Doc/library/cgitb.rst +++ b/Doc/library/cgitb.rst @@ -1,4 +1,3 @@ - :mod:`cgitb` --- Traceback manager for CGI scripts ================================================== @@ -34,7 +33,7 @@ displayed in the browser and whether the report is logged to a file for later analysis. -.. function:: enable([display[, logdir[, context[, format]]]]) +.. function:: enable(display=1, logdir=None, context=5, format="html") .. index:: single: excepthook() (in module sys) @@ -51,7 +50,7 @@ analysis. value forces plain text output. The default value is ``"html"``. -.. function:: handler([info]) +.. function:: handler(info=None) This function handles an exception using the default settings (that is, show a report in the browser, but don't log to a file). This can be used when you've diff --git a/Doc/library/chunk.rst b/Doc/library/chunk.rst index 64ce4e2..d3558a4 100644 --- a/Doc/library/chunk.rst +++ b/Doc/library/chunk.rst @@ -1,4 +1,3 @@ - :mod:`chunk` --- Read IFF chunked data ====================================== @@ -51,7 +50,7 @@ new instance can be instantiated. At the end of the file, creating a new instance will fail with a :exc:`EOFError` exception. -.. class:: Chunk(file[, align, bigendian, inclheader]) +.. class:: Chunk(file, align=True, bigendian=True, inclheader=False) Class which represents a chunk. The *file* argument is expected to be a file-like object. An instance of this class is specifically allowed. The @@ -94,7 +93,7 @@ instance will fail with a :exc:`EOFError` exception. Returns ``False``. - .. method:: seek(pos[, whence]) + .. method:: seek(pos, whence=0) Set the chunk's current position. The *whence* argument is optional and defaults to ``0`` (absolute file positioning); other values are ``1`` @@ -108,7 +107,7 @@ instance will fail with a :exc:`EOFError` exception. Return the current position into the chunk. - .. method:: read([size]) + .. method:: read(size=-1) Read at most *size* bytes from the chunk (less if the read hits the end of the chunk before obtaining *size* bytes). If the *size* argument is diff --git a/Doc/library/cmath.rst b/Doc/library/cmath.rst index 682e6db..8761c88 100644 --- a/Doc/library/cmath.rst +++ b/Doc/library/cmath.rst @@ -1,4 +1,3 @@ - :mod:`cmath` --- Mathematical functions for complex numbers =========================================================== diff --git a/Doc/library/cmd.rst b/Doc/library/cmd.rst index c31c9a2..d27dbae 100644 --- a/Doc/library/cmd.rst +++ b/Doc/library/cmd.rst @@ -1,4 +1,3 @@ - :mod:`cmd` --- Support for line-oriented command interpreters ============================================================= @@ -13,7 +12,7 @@ tools, and prototypes that will later be wrapped in a more sophisticated interface. -.. class:: Cmd([completekey[, stdin[, stdout]]]) +.. class:: Cmd(completekey='tab', stdin=None, stdout=None) A :class:`Cmd` instance or subclass instance is a line-oriented interpreter framework. There is no good reason to instantiate :class:`Cmd` itself; rather, @@ -42,7 +41,7 @@ Cmd Objects A :class:`Cmd` instance has the following methods: -.. method:: Cmd.cmdloop([intro]) +.. method:: Cmd.cmdloop(intro=None) Repeatedly issue a prompt, accept input, parse an initial prefix off the received input, and dispatch to action methods, passing them the remainder of diff --git a/Doc/library/code.rst b/Doc/library/code.rst index 4e00639..4219e9e 100644 --- a/Doc/library/code.rst +++ b/Doc/library/code.rst @@ -12,7 +12,7 @@ Python. Two classes and convenience functions are included which can be used to build applications which provide an interactive interpreter prompt. -.. class:: InteractiveInterpreter([locals]) +.. class:: InteractiveInterpreter(locals=None) This class deals with parsing and interpreter state (the user's namespace); it does not deal with input buffering or prompting or input file naming (the @@ -22,14 +22,14 @@ build applications which provide an interactive interpreter prompt. ``'__doc__'`` set to ``None``. -.. class:: InteractiveConsole([locals[, filename]]) +.. class:: InteractiveConsole(locals=None, filename="") Closely emulate the behavior of the interactive Python interpreter. This class builds on :class:`InteractiveInterpreter` and adds prompting using the familiar ``sys.ps1`` and ``sys.ps2``, and input buffering. -.. function:: interact([banner[, readfunc[, local]]]) +.. function:: interact(banner=None, readfunc=None, local=None) Convenience function to run a read-eval-print loop. This creates a new instance of :class:`InteractiveConsole` and sets *readfunc* to be used as the @@ -40,7 +40,7 @@ build applications which provide an interactive interpreter prompt. discarded after use. -.. function:: compile_command(source[, filename[, symbol]]) +.. function:: compile_command(source, filename="", symbol="single") This function is useful for programs that want to emulate Python's interpreter main loop (a.k.a. the read-eval-print loop). The tricky part is to determine @@ -67,7 +67,7 @@ Interactive Interpreter Objects ------------------------------- -.. method:: InteractiveInterpreter.runsource(source[, filename[, symbol]]) +.. method:: InteractiveInterpreter.runsource(source, filename="", symbol="single") Compile and run some source in the interpreter. Arguments are the same as for :func:`compile_command`; the default for *filename* is ``''``, and for @@ -100,7 +100,7 @@ Interactive Interpreter Objects with it. -.. method:: InteractiveInterpreter.showsyntaxerror([filename]) +.. method:: InteractiveInterpreter.showsyntaxerror(filename=None) Display the syntax error that just occurred. This does not display a stack trace because there isn't one for syntax errors. If *filename* is given, it is @@ -132,7 +132,7 @@ The :class:`InteractiveConsole` class is a subclass of interpreter objects as well as the following additions. -.. method:: InteractiveConsole.interact([banner]) +.. method:: InteractiveConsole.interact(banner=None) Closely emulate the interactive Python console. The optional banner argument specify the banner to print before the first interaction; by default it prints a @@ -158,7 +158,7 @@ interpreter objects as well as the following additions. Remove any unhandled source text from the input buffer. -.. method:: InteractiveConsole.raw_input([prompt]) +.. method:: InteractiveConsole.raw_input(prompt="") Write a prompt and read a line. The returned line does not include the trailing newline. When the user enters the EOF key sequence, :exc:`EOFError` is raised. diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst index bc8bc7d..4b6c7e5 100644 --- a/Doc/library/codecs.rst +++ b/Doc/library/codecs.rst @@ -1,4 +1,3 @@ - :mod:`codecs` --- Codec registry and base classes ================================================= @@ -226,34 +225,36 @@ utility functions: defaults to line buffered. -.. function:: EncodedFile(file, input[, output[, errors]]) +.. function:: EncodedFile(file, data_encoding, file_encoding=None, errors='strict') Return a wrapped version of file which provides transparent encoding translation. Bytes written to the wrapped file are interpreted according to the given - *input* encoding and then written to the original file as bytes using the - *output* encoding. + *data_encoding* and then written to the original file as bytes using the + *file_encoding*. - If *output* is not given, it defaults to *input*. + If *file_encoding* is not given, it defaults to *data_encoding*. - *errors* may be given to define the error handling. It defaults to ``'strict'``, - which causes :exc:`ValueError` to be raised in case an encoding error occurs. + *errors* may be given to define the error handling. It defaults to + ``'strict'``, which causes :exc:`ValueError` to be raised in case an encoding + error occurs. -.. function:: iterencode(iterable, encoding[, errors]) +.. function:: iterencode(iterator, encoding, errors='strict', **kwargs) Uses an incremental encoder to iteratively encode the input provided by - *iterable*. This function is a :term:`generator`. *errors* (as well as any + *iterator*. This function is a :term:`generator`. *errors* (as well as any other keyword argument) is passed through to the incremental encoder. -.. function:: iterdecode(iterable, encoding[, errors]) +.. function:: iterdecode(iterator, encoding, errors='strict', **kwargs) Uses an incremental decoder to iteratively decode the input provided by - *iterable*. This function is a :term:`generator`. *errors* (as well as any + *iterator*. This function is a :term:`generator`. *errors* (as well as any other keyword argument) is passed through to the incremental decoder. + The module also provides the following constants which are useful for reading and writing to platform dependent files: -- cgit v0.12