From python-checkins at python.org Wed Aug 1 14:03:27 2007 From: python-checkins at python.org (georg.brandl) Date: Wed, 1 Aug 2007 14:03:27 +0200 (CEST) Subject: [Python-checkins] r56640 - in doctools/trunk/converter: filenamemap.py newfiles/ACKS newfiles/about.rst Message-ID: <20070801120327.367BD1E4009@bag.python.org> Author: georg.brandl Date: Wed Aug 1 14:03:25 2007 New Revision: 56640 Added: doctools/trunk/converter/newfiles/ACKS Modified: doctools/trunk/converter/filenamemap.py doctools/trunk/converter/newfiles/about.rst Log: Add the ACKS file and include it in the "About" document. Modified: doctools/trunk/converter/filenamemap.py ============================================================================== --- doctools/trunk/converter/filenamemap.py (original) +++ doctools/trunk/converter/filenamemap.py Wed Aug 1 14:03:25 2007 @@ -454,6 +454,8 @@ 'reference', 'tutorial', 'whatsnew', + 'lib', + 'tools', ] # includefiles for \verbatiminput and \input @@ -476,6 +478,7 @@ newfiles_mapping = { 'conf.py': 'conf.py', 'TODO': 'TODO', + 'ACKS': 'ACKS', 'ref_index.rst': 'reference/index.rst', 'tutorial_index.rst': 'tutorial/index.rst', Added: doctools/trunk/converter/newfiles/ACKS ============================================================================== --- (empty file) +++ doctools/trunk/converter/newfiles/ACKS Wed Aug 1 14:03:25 2007 @@ -0,0 +1,197 @@ +Contributors to the Python Documentation +---------------------------------------- + +This file lists people who have contributed in some way to the Python +documentation. It is probably not complete -- if you feel that you or +anyone else should be on this list, please let us know (send email to +docs at python.org), and we'll be glad to correct the problem. + +It is only with the input and contributions of the Python community +that Python has such wonderful documentation -- Thank You! + + +* Aahz +* Michael Abbott +* Steve Alexander +* Jim Ahlstrom +* Fred Allen +* A. Amoroso +* Pehr Anderson +* Oliver Andrich +* Jes?s Cea Avi?n +* Daniel Barclay +* Chris Barker +* Don Bashford +* Anthony Baxter +* Bennett Benson +* Jonathan Black +* Robin Boerdijk +* Michal Bozon +* Aaron Brancotti +* Keith Briggs +* Lee Busby +* Lorenzo M. Catucci +* Mauro Cicognini +* Gilles Civario +* Mike Clarkson +* Steve Clift +* Dave Cole +* Matthew Cowles +* Jeremy Craven +* Andrew Dalke +* Ben Darnell +* L. Peter Deutsch +* Robert Donohue +* Fred L. Drake, Jr. +* Jeff Epler +* Michael Ernst +* Blame Andy Eskilsson +* Carey Evans +* Martijn Faassen +* Carl Feynman +* Hern?n Mart?nez Foffani +* Stefan Franke +* Jim Fulton +* Peter Funk +* Lele Gaifax +* Matthew Gallagher +* Ben Gertzfield +* Nadim Ghaznavi +* Jonathan Giddy +* Shelley Gooch +* Nathaniel Gray +* Grant Griffin +* Thomas Guettler +* Anders Hammarquist +* Mark Hammond +* Harald Hanche-Olsen +* Manus Hand +* Gerhard H?ring +* Travis B. Hartwell +* Janko Hauser +* Bernhard Herzog +* Magnus L. Hetland +* Konrad Hinsen +* Stefan Hoffmeister +* Albert Hofkamp +* Gregor Hoffleit +* Steve Holden +* Thomas Holenstein +* Gerrit Holl +* Rob Hooft +* Brian Hooper +* Randall Hopper +* Michael Hudson +* Eric Huss +* Jeremy Hylton +* Roger Irwin +* Jack Jansen +* Philip H. Jensen +* Pedro Diaz Jimenez +* Kent Johnson +* Lucas de Jonge +* Andreas Jung +* Robert Kern +* Jim Kerr +* Jan Kim +* Greg Kochanski +* Guido Kollerie +* Peter A. Koren +* Daniel Kozan +* Andrew M. Kuchling +* Dave Kuhlman +* Erno Kuusela +* Detlef Lannert +* Piers Lauder +* Glyph Lefkowitz +* Marc-Andr? Lemburg +* Ulf A. Lindgren +* Everett Lipman +* Mirko Liss +* Martin von L?wis +* Fredrik Lundh +* Jeff MacDonald +* John Machin +* Andrew MacIntyre +* Vladimir Marangozov +* Vincent Marchetti +* Laura Matson +* Daniel May +* Doug Mennella +* Paolo Milani +* Skip Montanaro +* Paul Moore +* Ross Moore +* Sjoerd Mullender +* Dale Nagata +* Ng Pheng Siong +* Koray Oner +* Tomas Oppelstrup +* Denis S. Otkidach +* Zooko O'Whielacronx +* William Park +* Joonas Paalasmaa +* Harri Pasanen +* Bo Peng +* Tim Peters +* Christopher Petrilli +* Justin D. Pettit +* Chris Phoenix +* Fran?ois Pinard +* Paul Prescod +* Eric S. Raymond +* Edward K. Ream +* Sean Reifschneider +* Bernhard Reiter +* Armin Rigo +* Wes Rishel +* Jim Roskind +* Guido van Rossum +* Donald Wallace Rouse II +* Nick Russo +* Chris Ryland +* Constantina S. +* Hugh Sasse +* Bob Savage +* Scott Schram +* Neil Schemenauer +* Barry Scott +* Joakim Sernbrant +* Justin Sheehy +* Michael Simcich +* Ionel Simionescu +* Gregory P. Smith +* Roy Smith +* Clay Spence +* Nicholas Spies +* Tage Stabell-Kulo +* Frank Stajano +* Anthony Starks +* Greg Stein +* Peter Stoehr +* Mark Summerfield +* Reuben Sumner +* Kalle Svensson +* Jim Tittsler +* Ville Vainio +* Martijn Vries +* Charles G. Waldman +* Greg Ward +* Barry Warsaw +* Corran Webster +* Glyn Webster +* Bob Weiner +* Eddy Welbourne +* Mats Wichmann +* Gerry Wiener +* Timothy Wild +* Collin Winter +* Blake Winton +* Dan Wolfe +* Steven Work +* Thomas Wouters +* Ka-Ping Yee +* Rory Yorke +* Moshe Zadka +* Milan Zamazal +* Cheng Zhang Modified: doctools/trunk/converter/newfiles/about.rst ============================================================================== --- doctools/trunk/converter/newfiles/about.rst (original) +++ doctools/trunk/converter/newfiles/about.rst Wed Aug 1 14:03:25 2007 @@ -13,4 +13,6 @@ docs at python.org mailing list. We're always looking for volunteers wanting to help with the docs, so feel free to send a mail there! -See :ref:`reporting-bugs` for information how to report bugs in Python itself. \ No newline at end of file +See :ref:`reporting-bugs` for information how to report bugs in Python itself. + +.. include:: ACKS \ No newline at end of file From python-checkins at python.org Wed Aug 1 14:46:17 2007 From: python-checkins at python.org (georg.brandl) Date: Wed, 1 Aug 2007 14:46:17 +0200 (CEST) Subject: [Python-checkins] r56641 - in doctools/trunk/converter: filenamemap.py newfiles/TODO newfiles/doc_markup.rst restwriter.py Message-ID: <20070801124617.1B04E1E4003@bag.python.org> Author: georg.brandl Date: Wed Aug 1 14:46:16 2007 New Revision: 56641 Modified: doctools/trunk/converter/filenamemap.py doctools/trunk/converter/newfiles/TODO doctools/trunk/converter/newfiles/doc_markup.rst doctools/trunk/converter/restwriter.py Log: Get rid of the remaining warnings in the conversion. Modified: doctools/trunk/converter/filenamemap.py ============================================================================== --- doctools/trunk/converter/filenamemap.py (original) +++ doctools/trunk/converter/filenamemap.py Wed Aug 1 14:46:16 2007 @@ -546,6 +546,7 @@ toctree_mapping = { 'mac/scripting': ['gensuitemodule', 'aetools', 'aepack', 'aetypes', 'miniae'], 'mac/toolbox': ['colorpicker'], + 'mac/undoc': [], 'lib/libstrings': ['string', 're', 'struct', 'difflib', 'stringio', 'textwrap', 'codecs', 'unicodedata', 'stringprep', 'fpformat'], 'lib/datatypes': ['datetime', 'calendar', 'collections', 'heapq', 'bisect', @@ -601,6 +602,7 @@ 'lib/libsgi': ['al', 'cd', 'fl', 'fm', 'gl', 'imgfile', 'jpeg'], 'lib/libsun': ['sunaudio'], 'lib/windows': ['msilib', 'msvcrt', '_winreg', 'winsound'], + 'lib/tkinter': [], } # map sourcefilename to [pre, post] Modified: doctools/trunk/converter/newfiles/TODO ============================================================================== --- doctools/trunk/converter/newfiles/TODO (original) +++ doctools/trunk/converter/newfiles/TODO Wed Aug 1 14:46:16 2007 @@ -14,5 +14,5 @@ * write "About these documents" * finish "Documenting Python" * extend copyright.rst -* merge ACKS into about.rst * fix the "quadruple" index term +* fix :file: and |version| in install \ No newline at end of file Modified: doctools/trunk/converter/newfiles/doc_markup.rst ============================================================================== --- doctools/trunk/converter/newfiles/doc_markup.rst (original) +++ doctools/trunk/converter/newfiles/doc_markup.rst Wed Aug 1 14:46:16 2007 @@ -368,8 +368,6 @@ The name of a file or directory. -.. XXX: filenq, filevar - .. describe:: guilabel Labels presented as part of an interactive user interface should be marked Modified: doctools/trunk/converter/restwriter.py ============================================================================== --- doctools/trunk/converter/restwriter.py (original) +++ doctools/trunk/converter/restwriter.py Wed Aug 1 14:46:16 2007 @@ -332,6 +332,8 @@ # loses comments, but huh return EmptyNode() if isinstance(subnode, InlineNode): + if subnode.cmdname in ('filevar', 'envvar'): + return NodeList([TextNode('{'), do(subnode.args[0]), TextNode('}')]) if subnode.cmdname == 'optional': # this is not mapped to ReST markup return subnode @@ -639,7 +641,7 @@ self.write_directive('deprecated', text(node.args[0]), node.args[1], spbelow=False) elif cmdname == 'localmoduletable': - if self.toctree: + if self.toctree is not None: self.write_directive('toctree', '', spbelow=True, spabove=True) with self.indented(): for entry in self.toctree: @@ -830,7 +832,7 @@ # maps argumentless commands to text simplecmd_mapping = { - 'NULL': '`NULL`', + 'NULL': '*NULL*', 'shortversion': '|version|', 'version': '|release|', 'today': '|today|', @@ -848,6 +850,7 @@ 'method': 'meth', 'module': 'mod', 'programopt': 'option', + 'filenq': 'file', # these mean: no change 'cdata': '', 'class': '', @@ -857,8 +860,6 @@ 'dfn': '', 'envvar': '', 'file': '', - 'filenq': '', - 'filevar': '', 'guilabel': '', 'kbd': '', 'keyword': '', @@ -890,7 +891,7 @@ if cmdname in ('code', 'bfcode', 'samp', 'texttt', 'regexp'): self.visit_wrapped('``', self.get_textonly_node(content, 'code', warn=1), '``', noescape=True) - elif cmdname in ('emph', 'textit'): + elif cmdname in ('emph', 'textit', 'var'): self.visit_wrapped('*', self.get_textonly_node(content, 'emph', warn=1), '*') elif cmdname in ('strong', 'textbf'): @@ -898,7 +899,7 @@ warn=1), '**') elif cmdname in ('b', 'textrm', 'email'): self.visit_node(content) - elif cmdname in ('var', 'token'): + elif cmdname == 'token': # \token appears in productionlists only self.visit_wrapped('`', self.get_textonly_node(content, 'var', warn=1), '`') @@ -948,11 +949,13 @@ self.visit_wrapped('(', node.args[1], ')') elif cmdname == 'longprogramopt': self.visit_wrapped(':option:`--', content, '`') + elif cmdname == 'filevar': + self.visit_wrapped(':file:`{', content, '}`') elif cmdname == '': self.visit_node(content) # stray commands from distutils elif cmdname in ('argument name', 'value', 'attribute', 'option name'): - self.visit_wrapped('`', content, '`') + self.visit_wrapped('*', content, '*') else: self.visit_wrapped(':%s:`' % (self.role_mapping[cmdname] or cmdname), self.get_textonly_node( From python-checkins at python.org Wed Aug 1 16:09:19 2007 From: python-checkins at python.org (georg.brandl) Date: Wed, 1 Aug 2007 16:09:19 +0200 (CEST) Subject: [Python-checkins] r56642 - in doctools/trunk: TODO converter/newfiles/doc_markup.rst sphinx/roles.py sphinx/style/default.css Message-ID: <20070801140919.081851E4003@bag.python.org> Author: georg.brandl Date: Wed Aug 1 16:09:18 2007 New Revision: 56642 Modified: doctools/trunk/TODO doctools/trunk/converter/newfiles/doc_markup.rst doctools/trunk/sphinx/roles.py doctools/trunk/sphinx/style/default.css Log: Make system messages stand out in HTML output. Modified: doctools/trunk/TODO ============================================================================== --- doctools/trunk/TODO (original) +++ doctools/trunk/TODO Wed Aug 1 16:09:18 2007 @@ -1,6 +1,7 @@ Global TODO =========== +- "often used" combo box in sidebar - discuss and debug comments system - navigation links at the bottom too - write new Makefile, handle automatic version info and checkout @@ -11,4 +12,3 @@ - look at the old tools/ scripts, what functionality should be rewritten - add search via Xapian? - optionally have a contents tree view in the sidebar (AJAX based)? - Modified: doctools/trunk/converter/newfiles/doc_markup.rst ============================================================================== --- doctools/trunk/converter/newfiles/doc_markup.rst (original) +++ doctools/trunk/converter/newfiles/doc_markup.rst Wed Aug 1 16:09:18 2007 @@ -362,11 +362,17 @@ .. describe:: envvar - An environment variable. Index entries are generated. + An environment variable. Index entries are generated. .. describe:: file - The name of a file or directory. + The name of a file or directory. Within the contents, you can use curly + braces to indicate a "variable" part, for example:: + + ... is installed in :file:`/usr/lib/python2.{x}/site-packages` ... + + In the built documentation, the ``x`` will be displayed differently to + indicate that it is to be replaced by the Python minor version. .. describe:: guilabel Modified: doctools/trunk/sphinx/roles.py ============================================================================== --- doctools/trunk/sphinx/roles.py (original) +++ doctools/trunk/sphinx/roles.py Wed Aug 1 16:09:18 2007 @@ -21,9 +21,6 @@ generic_docroles = { 'command' : nodes.strong, 'dfn' : nodes.emphasis, - 'file' : nodes.emphasis, - 'filenq' : nodes.emphasis, - 'filevar' : nodes.emphasis, 'guilabel' : nodes.strong, 'kbd' : nodes.literal, 'keyword' : nodes.literal, @@ -114,7 +111,25 @@ def menusel_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): - return [nodes.emphasis(rawtext, text.replace('-->', u'\N{TRIANGULAR BULLET}'))], [] + return [nodes.emphasis( + rawtext, utils.unescape(text).replace('-->', u'\N{TRIANGULAR BULLET}'))], [] + + +_filevar_re = re.compile('{([^}]+)}') + +def file_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): + text = utils.unescape(text) + retnodes = [] + pos = 0 + for m in _filevar_re.finditer(text): + if m.start() > pos: + txt = text[pos:m.start()] + retnodes.append(nodes.literal(txt, txt)) + retnodes.append(nodes.emphasis('', '', nodes.literal(m.group(1), m.group(1)))) + pos = m.end() + if pos < len(text): + retnodes.append(nodes.literal(text[pos:], text[pos:])) + return retnodes, [] specific_docroles = { @@ -137,6 +152,7 @@ 'token' : xfileref_role, 'menuselection' : menusel_role, + 'file' : file_role, } for rolename, func in specific_docroles.iteritems(): Modified: doctools/trunk/sphinx/style/default.css ============================================================================== --- doctools/trunk/sphinx/style/default.css (original) +++ doctools/trunk/sphinx/style/default.css Wed Aug 1 16:09:18 2007 @@ -744,6 +744,12 @@ margin-bottom: 10px; } +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + /* :::: PRINT :::: */ @media print { div.documentwrapper { From python-checkins at python.org Wed Aug 1 17:31:11 2007 From: python-checkins at python.org (georg.brandl) Date: Wed, 1 Aug 2007 17:31:11 +0200 (CEST) Subject: [Python-checkins] r56643 - in doctools/trunk: converter/newfiles/conf.py converter/newfiles/doc_sphinx.rst converter/util.py sphinx/roles.py Message-ID: <20070801153111.7314B1E4008@bag.python.org> Author: georg.brandl Date: Wed Aug 1 17:31:10 2007 New Revision: 56643 Modified: doctools/trunk/converter/newfiles/conf.py doctools/trunk/converter/newfiles/doc_sphinx.rst doctools/trunk/converter/util.py doctools/trunk/sphinx/roles.py Log: Strip parentheses during conversion, add them during build. Modified: doctools/trunk/converter/newfiles/conf.py ============================================================================== --- doctools/trunk/converter/newfiles/conf.py (original) +++ doctools/trunk/converter/newfiles/conf.py Wed Aug 1 17:31:10 2007 @@ -37,5 +37,5 @@ # typographically correct entities. use_smartypants = True -# If true, trailing '()' will be stripped from :func: etc. cross-references. -strip_trailing_parentheses = False +# If true, '()' will be appended to :func: etc. cross-reference text. +add_function_parentheses = True Modified: doctools/trunk/converter/newfiles/doc_sphinx.rst ============================================================================== --- doctools/trunk/converter/newfiles/doc_sphinx.rst (original) +++ doctools/trunk/converter/newfiles/doc_sphinx.rst Wed Aug 1 17:31:10 2007 @@ -50,6 +50,6 @@ If true, use SmartyPants to convert quotes and dashes to the typographically correct entities. -strip_trailing_parentheses : bool - If true, trailing parentheses will be stripped from ``:func:`` etc. - crossreferences. \ No newline at end of file +add_function_parentheses : bool + If true, ``()`` will be appended to the content of ``:func:``, ``:meth:`` and + ``:cfunc:`` cross-references. \ No newline at end of file Modified: doctools/trunk/converter/util.py ============================================================================== --- doctools/trunk/converter/util.py (original) +++ doctools/trunk/converter/util.py Wed Aug 1 17:31:10 2007 @@ -70,6 +70,7 @@ wordchars_e = alphanum + u'+`(-' bad_markup_re = re.compile(r'(:[a-zA-Z0-9_-]+:)?(`{1,2})[ ]*(.+?)[ ]*(\2)') quoted_code_re = re.compile(r'\\`(``.+?``)\'') +paren_re = re.compile(r':(func|meth|cfunc):`(.*?)\(\)`') def repair_bad_inline_markup(text): # remove quoting from `\code{x}' @@ -80,6 +81,9 @@ # special: literal backquotes xtext = xtext.replace('``````', '\x02') + # remove () from function markup + xtext = paren_re.sub(r':\1:`\2`', xtext) + ntext = [] lasti = 0 l = len(xtext) Modified: doctools/trunk/sphinx/roles.py ============================================================================== --- doctools/trunk/sphinx/roles.py (original) +++ doctools/trunk/sphinx/roles.py Wed Aug 1 17:31:10 2007 @@ -98,9 +98,9 @@ # 'token' is the default role inside 'productionlist' directives if typ == '': typ = 'token' - if env.config.get('strip_trailing_parentheses', False): - if text[-2:] == '()': - text = text[:-2] + if typ in ('func', 'meth', 'cfunc') and \ + env.config.get('add_function_parentheses', True): + text += '()' pnode = addnodes.pending_xref(rawtext) pnode['reftype'] = typ pnode['reftarget'] = ws_re.sub('', text) From python-checkins at python.org Wed Aug 1 17:36:53 2007 From: python-checkins at python.org (georg.brandl) Date: Wed, 1 Aug 2007 17:36:53 +0200 (CEST) Subject: [Python-checkins] r56644 - in doctools/trunk: TODO sphinx/templates/layout.html Message-ID: <20070801153653.0F2DE1E4009@bag.python.org> Author: georg.brandl Date: Wed Aug 1 17:36:52 2007 New Revision: 56644 Modified: doctools/trunk/TODO doctools/trunk/sphinx/templates/layout.html Log: Add a navbar at the bottom too. Modified: doctools/trunk/TODO ============================================================================== --- doctools/trunk/TODO (original) +++ doctools/trunk/TODO Wed Aug 1 17:36:52 2007 @@ -3,10 +3,8 @@ - "often used" combo box in sidebar - discuss and debug comments system -- navigation links at the bottom too - write new Makefile, handle automatic version info and checkout - write a "printable" builder (export to latex, most probably) -- discuss the default role - discuss lib -> ref section move - prepare for databases other than sqlite for comments - look at the old tools/ scripts, what functionality should be rewritten Modified: doctools/trunk/sphinx/templates/layout.html ============================================================================== --- doctools/trunk/sphinx/templates/layout.html (original) +++ doctools/trunk/sphinx/templates/layout.html Wed Aug 1 17:36:52 2007 @@ -42,6 +42,7 @@ {% block head %}{% endblock %} +{% filter capture('relbar') %}

Navigation

+{% endfilter %}
{%- if builder != 'htmlhelp' %} @@ -80,6 +82,7 @@ {%- endif %}
+{{ relbar }}
© Copyright 1990-2007, Python Software Foundation. From python-checkins at python.org Wed Aug 1 18:06:46 2007 From: python-checkins at python.org (georg.brandl) Date: Wed, 1 Aug 2007 18:06:46 +0200 (CEST) Subject: [Python-checkins] r56645 - in doctools/trunk: TODO converter/newfiles/conf.py converter/newfiles/doc_sphinx.rst sphinx/builder.py sphinx/patchlevel.py sphinx/templates/sidebar.html Message-ID: <20070801160646.1997F1E4012@bag.python.org> Author: georg.brandl Date: Wed Aug 1 18:06:45 2007 New Revision: 56645 Added: doctools/trunk/sphinx/patchlevel.py Modified: doctools/trunk/TODO doctools/trunk/converter/newfiles/conf.py doctools/trunk/converter/newfiles/doc_sphinx.rst doctools/trunk/sphinx/builder.py doctools/trunk/sphinx/templates/sidebar.html Log: Automatically get version info from the patchlevel.h file. Modified: doctools/trunk/TODO ============================================================================== --- doctools/trunk/TODO (original) +++ doctools/trunk/TODO Wed Aug 1 18:06:45 2007 @@ -3,7 +3,7 @@ - "often used" combo box in sidebar - discuss and debug comments system -- write new Makefile, handle automatic version info and checkout +- write new Makefile, handle automatic checkout - write a "printable" builder (export to latex, most probably) - discuss lib -> ref section move - prepare for databases other than sqlite for comments Modified: doctools/trunk/converter/newfiles/conf.py ============================================================================== --- doctools/trunk/converter/newfiles/conf.py (original) +++ doctools/trunk/converter/newfiles/conf.py Wed Aug 1 18:06:45 2007 @@ -6,11 +6,17 @@ # that aren't pickleable (module imports are okay, they're removed automatically). # -# The default replacements for |version| and |release|: +# The default replacements for |version| and |release|. +# If 'auto', Sphinx looks for the Include/patchlevel.h file in the current Python +# source tree and replaces the values accordingly. +# # The short X.Y version. -version = '2.6' +# version = '2.6' +version = 'auto' # The full version, including alpha/beta/rc tags. -release = '2.6a0' +# release = '2.6a0' +release = 'auto' + # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: today = '' Modified: doctools/trunk/converter/newfiles/doc_sphinx.rst ============================================================================== --- doctools/trunk/converter/newfiles/doc_sphinx.rst (original) +++ doctools/trunk/converter/newfiles/doc_sphinx.rst Wed Aug 1 18:06:45 2007 @@ -17,17 +17,22 @@ These variables are: -release : string - A string that is used as a replacement for the ``|release|`` reST - substitution. It should be the full version string including - alpha/beta/release candidate tags, e.g. ``2.5.2b3``. - version : string A string that is used as a replacement for the ``|version|`` reST substitution. It should be the Python version the documentation refers to. This consists only of the major and minor version parts, e.g. ``2.5``, even for version 2.5.1. +release : string + A string that is used as a replacement for the ``|release|`` reST + substitution. It should be the full version string including + alpha/beta/release candidate tags, e.g. ``2.5.2b3``. + +Both ``release`` and ``version`` can be ``'auto'``, which means that they are +determined at runtime from the ``Include/patchlevel.h`` file, if a complete +Python source distribution can be found, or else from the interpreter running +Sphinx. + today_fmt : string A ``strftime`` format that is used to format a replacement for the ``|today|`` reST substitution. @@ -37,7 +42,7 @@ output literally. If this is nonzero, it is used instead of ``strftime(today_fmt)``. -unused_file : list of strings +unused_files : list of strings A list of reST filenames that are to be disregarded during building. This could be docs for temporarily disabled modules or documentation that's not yet ready for public consumption. Modified: doctools/trunk/sphinx/builder.py ============================================================================== --- doctools/trunk/sphinx/builder.py (original) +++ doctools/trunk/sphinx/builder.py Wed Aug 1 18:06:45 2007 @@ -31,6 +31,7 @@ from .writer import HTMLWriter from .util.console import bold, purple, green from .htmlhelp import build_hhx +from .patchlevel import get_version_info, get_sys_version_info from .environment import BuildEnvironment from .highlighting import pygments, get_stylesheet @@ -96,6 +97,18 @@ for key, val in self.config.items(): if isinstance(val, types.ModuleType): del self.config[key] + # replace version info if 'auto' + if self.config['version'] == 'auto' or self.config['revision'] == 'auto': + try: + version, release = get_version_info(srcdirname) + except (IOError, OSError): + print >>warning_stream, 'WARNING: Can\'t get version info from ' \ + 'Include/patchlevel.h, using version of this interpreter.' + version, release = get_sys_version_info() + if self.config['version'] == 'auto': + self.config['version'] = version + if self.config['release'] == 'auto': + self.config['release'] = release if confoverrides: self.config.update(confoverrides) Added: doctools/trunk/sphinx/patchlevel.py ============================================================================== --- (empty file) +++ doctools/trunk/sphinx/patchlevel.py Wed Aug 1 18:06:45 2007 @@ -0,0 +1,56 @@ +# -*- coding: utf-8 -*- +""" + sphinx.patchlevel + ~~~~~~~~~~~~~~~~~ + + Extract version info from Include/patchlevel.h. + Adapted from Doc/tools/getversioninfo. + + :copyright: 2007 by Georg Brandl. + :license: Python license. +""" +from __future__ import with_statement + +import os +import re +import sys + +def get_version_info(srcdir): + patchlevel_h = os.path.join(srcdir, '..', "Include", "patchlevel.h") + + # This won't pick out all #defines, but it will pick up the ones we + # care about. + rx = re.compile(r"\s*#define\s+([a-zA-Z][a-zA-Z_0-9]*)\s+([a-zA-Z_0-9]+)") + + d = {} + with open(patchlevel_h) as f: + for line in f: + m = rx.match(line) + if m is not None: + name, value = m.group(1, 2) + d[name] = value + + release = version = "%s.%s" % (d["PY_MAJOR_VERSION"], d["PY_MINOR_VERSION"]) + micro = int(d["PY_MICRO_VERSION"]) + if micro != 0: + release += "." + str(micro) + + level = d["PY_RELEASE_LEVEL"] + suffixes = { + "PY_RELEASE_LEVEL_ALPHA": "a", + "PY_RELEASE_LEVEL_BETA": "b", + "PY_RELEASE_LEVEL_GAMMA": "c", + } + if level != "PY_RELEASE_LEVEL_FINAL": + release += suffixes[level] + str(int(d["PY_RELEASE_SERIAL"])) + return version, release + + +def get_sys_version_info(): + major, minor, micro, level, serial = sys.version_info + release = version = '%s.%s' % (major, minor) + if micro: + release += '.%s' % micro + if level != 'final': + release += '%s%s' % (level[0], serial) + return version, release Modified: doctools/trunk/sphinx/templates/sidebar.html ============================================================================== --- doctools/trunk/sphinx/templates/sidebar.html (original) +++ doctools/trunk/sphinx/templates/sidebar.html Wed Aug 1 18:06:45 2007 @@ -23,7 +23,7 @@ {% elif builder == 'html' %}
  • Show Source
    • {% endif %} -
  • Report Bug
    • + {#
  • Report Bug
    • #} {% endif %} {% if current_page_name == "index" %} From python-checkins at python.org Wed Aug 1 19:11:57 2007 From: python-checkins at python.org (guido.van.rossum) Date: Wed, 1 Aug 2007 19:11:57 +0200 (CEST) Subject: [Python-checkins] r56646 - peps/trunk/pep-3141.txt Message-ID: <20070801171157.1D30E1E4017@bag.python.org> Author: guido.van.rossum Date: Wed Aug 1 19:11:55 2007 New Revision: 56646 Modified: peps/trunk/pep-3141.txt Log: New version from Jeffrey. Cut NaN. Add __r*__ methods. Other stuff. Modified: peps/trunk/pep-3141.txt ============================================================================== --- peps/trunk/pep-3141.txt (original) +++ peps/trunk/pep-3141.txt Wed Aug 1 19:11:55 2007 @@ -45,30 +45,11 @@ We begin with a Number class to make it easy for people to be fuzzy about what kind of number they expect. This class only helps with -overloading; it doesn't provide any operations. +overloading; it doesn't provide any operations. :: - class Number(metaclass=MetaABC): pass + class Number(metaclass=ABCMeta): pass -Some types (primarily ``float``) define "Not a Number" (NaN) values -that return false for any comparison, including equality with -themselves, and are maintained through operations. That is, ``nan + x --> nan`` and ``nan == nan -> False`` Because this doesn't work well -with the Reals (which are otherwise totally ordered by ``<``), Guido -suggested we might put NaN in its own type. It is conceivable that -this can still be represented by C doubles but be included in a -different ABC at runtime. **Open issue:** Is this a good idea?:: - - class UndefinedNumber(Number): - """Implement IEEE 754 semantics.""" - def __lt__(self, other): return false - def __eq__(self, other): return false - ... - def __add__(self, other): return self - def __radd__(self, other): return self - ... - # Should we demand a conversion to float? - Most implementations of complex numbers will be hashable, but if you need to rely on that, you'll have to check it explicitly: mutable numbers are supported by this hierarchy. :: @@ -76,28 +57,36 @@ class Complex(Number): """Complex defines the operations that work on the builtin complex type. - In short, those are: a conversion to complex, .real, .imag, +, - -, *, /, abs(), .conjugate, ==, and !=. + In short, those are: a conversion to complex, .real, .imag, +, -, + *, /, abs(), .conjugate, ==, and !=. - If it is given heterogenous arguments, and doesn't have - special knowledge about them, it should fall back to the - builtin complex type as described below. + If it is given heterogenous arguments, and doesn't have special + knowledge about them, it should fall back to the builtin complex + type as described below. """ @abstractmethod def __complex__(self): """Return a builtin complex instance.""" - @abstractmethod - @property + def __bool__(self): + """True if self != 0.""" + return self != 0 + + @abstractproperty def real(self): - """Retrieve the real component of this number, which should subclass Real.""" + """Retrieve the real component of this number. + + This should subclass Real. + """ raise NotImplementedError - @abstractmethod - @property + @abstractproperty def imag(self): - """Retrieve the real component of this number, which should subclass Real.""" + """Retrieve the real component of this number. + + This should subclass Real. + """ raise NotImplementedError @abstractmethod @@ -105,22 +94,48 @@ raise NotImplementedError @abstractmethod - def __sub__(self, other): + def __radd__(self, other): raise NotImplementedError @abstractmethod def __neg__(self): raise NotImplementedError + def __pos__(self): + return self + + def __sub__(self, other): + return self + -other + + def __rsub__(self, other): + return -self + other + @abstractmethod def __mul__(self, other): raise NotImplementedError @abstractmethod + def __rmul__(self, other): + raise NotImplementedError + + @abstractmethod def __div__(self, other): raise NotImplementedError @abstractmethod + def __rdiv__(self, other): + raise NotImplementedError + + @abstractmethod + def __pow__(self, exponent): + """Like division, a**b should promote to complex when necessary.""" + raise NotImplementedError + + @abstractmethod + def __rpow__(self, base): + raise NotImplementedError + + @abstractmethod def __abs__(self): """Returns the Real distance from 0.""" raise NotImplementedError @@ -140,7 +155,7 @@ The ``Real`` ABC indicates that the value is on the real line, and supports the operations of the ``float`` builtin. Real numbers are -totally ordered. (NaNs were handled above).:: +totally ordered except for NaNs (which this PEP basically ignores). :: class Real(Complex): """To Complex, Real adds the operations that work on real numbers. @@ -152,38 +167,61 @@ """ @abstractmethod - def __float__(self): - """Any Real can be converted to a native float object.""" + def __float__(self): + """Any Real can be converted to a native float object.""" raise NotImplementedError - + @abstractmethod - def __trunc__(self): - """Returns an Integral of the same sign as self whose abs is <= self's abs.""" + def __trunc__(self): + """Truncates self to an Integral. + + Returns an Integral i such that: + * i>0 iff self>0 + * abs(i) <= abs(self). + """ raise NotImplementedError def __divmod__(self, other): - """The pair (self // other, self % other).""" + """The pair (self // other, self % other). + + Sometimes this can be computed faster than the pair of + operations. + """ return (self // other, self % other) + def __rdivmod__(self, other): + """The pair (self // other, self % other). + + Sometimes this can be computed faster than the pair of + operations. + """ + return (other // self, other % self) + @abstractmethod def __floordiv__(self, other): """The floor() of self/other.""" raise NotImplementedError @abstractmethod + def __rfloordiv__(self, other): + """The floor() of other/self.""" + raise NotImplementedError + + @abstractmethod def __mod__(self, other): - """.""" + raise NotImplementedError + + @abstractmethod + def __rmod__(self, other): raise NotImplementedError @abstractmethod def __lt__(self, other): + """< on Reals defines a total ordering, except perhaps for NaN.""" raise NotImplementedError def __le__(self, other): - # Assume that if other is Real, it defines an ordering - # consistent with this class, or returns NotImplemented. - if isinstance(other, Real): - return not (other < self) + raise NotImplementedError # Concrete implementations of Complex abstract methods. @@ -198,25 +236,28 @@ def imag(self): return 0 + def conjugate(self): + """Conjugate is a no-op for Reals.""" + return self + There is no built-in rational type, but it's straightforward to write, -so we provide an ABC for it. *Open issue*: Add Demo/classes/Rat.py to -the stdlib?:: +so we provide an ABC for it. **Open issue**: Add Demo/classes/Rat.py +to the stdlib? :: class Rational(Real, Exact): """.numerator and .denominator should be in lowest terms.""" - @abstractmethod - @property + @abstractproperty def numerator(self): raise NotImplementedError - @abstractmethod - @property + @abstractproperty def denominator(self): raise NotImplementedError # Concrete implementation of Real's conversion to float. + def __float__(self): return self.numerator / self.denominator @@ -230,26 +271,64 @@ def __int__(self): raise NotImplementedError + def __index__(self): + return int(self) + + @abstractmethod + def __pow__(self, exponent, modulus): + """self ** exponent % modulus, but maybe faster. + + Implement this if you want to support the 3-argument version + of pow(). Otherwise, just implement the 2-argument version + described in Complex. Raise a TypeError if exponent < 0 or any + argument isn't Integral. + """ + raise NotImplementedError + @abstractmethod def __lshift__(self, other): raise NotImplementedError @abstractmethod + def __rlshift__(self, other): + raise NotImplementedError + + @abstractmethod def __rshift__(self, other): raise NotImplementedError @abstractmethod + def __rrshift__(self, other): + raise NotImplementedError + + @abstractmethod def __and__(self, other): raise NotImplementedError @abstractmethod + def __rand__(self, other): + raise NotImplementedError + + @abstractmethod def __xor__(self, other): raise NotImplementedError @abstractmethod + def __rxor__(self, other): + raise NotImplementedError + + @abstractmethod def __or__(self, other): raise NotImplementedError + @abstractmethod + def __ror__(self, other): + raise NotImplementedError + + @abstractmethod + def __invert__(self): + raise NotImplementedError + # Concrete implementations of Rational and Real abstract methods. def __float__(self): @@ -277,12 +356,51 @@ types have this problem. Every instance of ``Integral`` and ``Rational`` should be Exact, but ``Reals`` and ``Complexes`` may or may not be. (Do we really only need one of these, and the other is -defined as ``not`` the first?):: +defined as ``not`` the first?) :: class Exact(Number): pass class Inexact(Number): pass +Changes to operations and __magic__ methods +------------------------------------------- + +To support more precise narrowing from float to int (and more +generally, from Real to Integral), I'm proposing the following new +__magic__ methods, to be called from the corresponding library +functions. All of these return Integrals rather than Reals. + +1. ``__trunc__(self)``, called from a new builtin ``trunc(x)``, which + returns the Integral closest to ``x`` between 0 and ``x``. + +2. ``__floor__(self)``, called from ``math.floor(x)``, which returns + the greatest Integral ``<= x``. + +3. ``__ceil__(self)``, called from ``math.ceil(x)``, which returns the + least Integral ``>= x``. + +4. ``__round__(self)``, called from ``round(x)``, with returns the + Integral closest to ``x``, rounding half toward even. We could + support the 2-argument version, but then we'd only return an + Integral if the second argument were ``<= 0``. + +5. ``__properfraction__(self)``, called from a new function, + ``math.properfraction(x)``, which resembles C's ``modf()``: returns + a pair ``(n:Integral, r:Real)`` where ``x == n + r``, both ``n`` + and ``r`` have the same sign as ``x``, and ``abs(r) < 1``. **Open + issue:** Oh, we already have ``math.modf``. Do we want to keep the + bad name? + +Because the ``int()`` conversion from ``float`` is equivalent to but +less explicit than ``trunc()``, let's remove it. + +``complex.__{divmod,mod,floordiv,int,float}__`` should also go +away. These should continue to raise ``TypeError`` to help confused +porters, but should not appear in ``help(complex)`` to avoid confusing +more people. **Open issue:** This is difficult to do with the +``PyNumberMethods`` struct. What's the best way to accomplish it? + + Notes for type implementors --------------------------- @@ -298,7 +416,7 @@ complex's range or precision. Adding More Numeric ABCs ------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~ There are, of course, more possible ABCs for numbers, and this would be a poor hierarchy if it precluded the possibility of adding @@ -308,7 +426,7 @@ MyFoo.register(Real) Implementing the arithmetic operations --------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ We want to implement the arithmetic operations so that mixed-mode operations either call an implementation whose author knew about the From python-checkins at python.org Wed Aug 1 19:29:38 2007 From: python-checkins at python.org (guido.van.rossum) Date: Wed, 1 Aug 2007 19:29:38 +0200 (CEST) Subject: [Python-checkins] r56647 - peps/trunk/pep-3119.txt Message-ID: <20070801172938.E0D5C1E4012@bag.python.org> Author: guido.van.rossum Date: Wed Aug 1 19:29:38 2007 New Revision: 56647 Modified: peps/trunk/pep-3119.txt Log: Add @abstractproperty. PEP 3141 needs it for .real, .imag. Modified: peps/trunk/pep-3119.txt ============================================================================== --- peps/trunk/pep-3119.txt (original) +++ peps/trunk/pep-3119.txt Wed Aug 1 19:29:38 2007 @@ -237,8 +237,8 @@ The new standard library module ``abc``, written in pure Python, serves as an ABC support framework. It defines a metaclass -``ABCMeta`` and a decorator ``@abstractmethod``. A sample -implementation is given by [13]_. +``ABCMeta`` and decorators ``@abstractmethod`` and +``@abstractproperty``. A sample implementation is given by [13]_. The ``ABCMeta`` class overrides ``__instancecheck__`` and ``__subclasscheck__`` and defines a ``register`` method. The @@ -340,11 +340,6 @@ affects subclasses derived using regular inheritance; "virtual subclasses" registered with the ``register()`` method are not affected. -It has been suggested that we should also provide a way to define -abstract data attributes. As it is easy to add these in a later -stage, and as the use case is considerably less common (apart from -pure documentation), we punt on this for now. - **Implementation:** The ``@abstractmethod`` decorator sets the function attribute ``__isabstractmethod__`` to the value ``True``. The ``ABCMeta.__new__`` method computes the type attribute @@ -366,6 +361,36 @@ useful as an end-point for a super-call in framework using a cooperative multiple-inheritance [7]_, [8]_. +A second decorator, ``@abstractproperty``, is defined in order to +define abstract data attributes. Its implementation is a subclass of +the built-in ``property`` class that adds an ``__isabstractmethod__`` +attribute:: + + class abstractproperty(property): + __isabstractmethod__ = True + +It can be used in two ways:: + + class C(metaclass=ABCMeta): + + # A read-only property: + + @abstractproperty + def readonly(self): + return self.__x + + # A read-write property (cannot use decorator syntax): + + def getx(self): + return self.__x + def setx(self, value): + self.__x = value + x = abstractproperty(getx, setx) + +A subclass inheriting an abstract property (declared using either the +decorator syntax or the longer form) cannot be instantiated unless it +overrides that abstract property with a concrete property. + ABCs for Containers and Iterators --------------------------------- From python-checkins at python.org Thu Aug 2 01:18:37 2007 From: python-checkins at python.org (facundo.batista) Date: Thu, 2 Aug 2007 01:18:37 +0200 (CEST) Subject: [Python-checkins] r56653 - python/trunk/Lib/test/test_smtplib.py Message-ID: <20070801231837.24A511E400B@bag.python.org> Author: facundo.batista Date: Thu Aug 2 01:18:36 2007 New Revision: 56653 Modified: python/trunk/Lib/test/test_smtplib.py Log: Allow the OS to select a free port for each test server. For DebuggingServerTests, construct SMTP objects with a localhost argument to avoid abysmally long FQDN lookups (not relevant to items under test) on some machines that would cause the test to fail. Moved server setup code in the server function inside the try block to avoid the possibility of setup failure hanging the test. Minor edits to conform to PEP 8. [GSoC - Alan McIntyre] Modified: python/trunk/Lib/test/test_smtplib.py ============================================================================== --- python/trunk/Lib/test/test_smtplib.py (original) +++ python/trunk/Lib/test/test_smtplib.py Thu Aug 2 01:18:36 2007 @@ -11,21 +11,25 @@ from unittest import TestCase from test import test_support +# PORT is used to communicate the port number assigned to the server +# to the test client HOST = "localhost" -PORT = 54328 +PORT = None def server(evt, buf): - serv = socket.socket(socket.AF_INET, socket.SOCK_STREAM) - serv.settimeout(3) - serv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) - serv.bind(("", PORT)) - serv.listen(5) try: + serv = socket.socket(socket.AF_INET, socket.SOCK_STREAM) + serv.settimeout(3) + serv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) + serv.bind(("", 0)) + global PORT + PORT = serv.getsockname()[1] + serv.listen(5) conn, addr = serv.accept() except socket.timeout: pass else: - n = 200 + n = 500 while buf and n > 0: r, w, e = select.select([], [conn], []) if w: @@ -38,6 +42,7 @@ conn.close() finally: serv.close() + PORT = None evt.set() class GeneralTests(TestCase): @@ -46,7 +51,16 @@ self.evt = threading.Event() servargs = (self.evt, "220 Hola mundo\n") threading.Thread(target=server, args=servargs).start() - time.sleep(.1) + + # wait until server thread has assigned a port number + n = 500 + while PORT is None and n > 0: + time.sleep(0.01) + n -= 1 + + # wait a little longer (sometimes connections are refused + # on slow machines without this additional wait) + time.sleep(0.5) def tearDown(self): self.evt.wait() @@ -69,7 +83,8 @@ def testNonnumericPort(self): # check that non-numeric port raises ValueError - self.assertRaises(socket.error, smtplib.SMTP, "localhost", "bogus") + self.assertRaises(socket.error, smtplib.SMTP, + "localhost", "bogus") def testTimeoutDefault(self): # default @@ -96,61 +111,104 @@ # Test server using smtpd.DebuggingServer -def debugging_server(evt): - serv = smtpd.DebuggingServer(("", PORT), ('nowhere', -1)) +def debugging_server(serv_evt, client_evt): + serv = smtpd.DebuggingServer(("", 0), ('nowhere', -1)) + global PORT + PORT = serv.getsockname()[1] try: - asyncore.loop(timeout=.01, count=300) + if hasattr(select, 'poll'): + poll_fun = asyncore.poll2 + else: + poll_fun = asyncore.poll + + n = 1000 + while asyncore.socket_map and n > 0: + poll_fun(0.01, asyncore.socket_map) + + # when the client conversation is finished, it will + # set client_evt, and it's then ok to kill the server + if client_evt.isSet(): + serv.close() + break + + n -= 1 + except socket.timeout: pass finally: # allow some time for the client to read the result time.sleep(0.5) + serv.close() asyncore.close_all() - evt.set() + PORT = None + time.sleep(0.5) + serv_evt.set() MSG_BEGIN = '---------- MESSAGE FOLLOWS ----------\n' MSG_END = '------------ END MESSAGE ------------\n' # Test behavior of smtpd.DebuggingServer +# NOTE: the SMTP objects are created with a non-default local_hostname +# argument to the constructor, since (on some systems) the FQDN lookup +# caused by the default local_hostname sometimes takes so long that the +# test server times out, causing the test to fail. class DebuggingServerTests(TestCase): def setUp(self): + # temporarily replace sys.stdout to capture DebuggingServer output self.old_stdout = sys.stdout self.output = StringIO.StringIO() sys.stdout = self.output - self.evt = threading.Event() - threading.Thread(target=debugging_server, args=(self.evt,)).start() - time.sleep(.5) + self.serv_evt = threading.Event() + self.client_evt = threading.Event() + serv_args = (self.serv_evt, self.client_evt) + threading.Thread(target=debugging_server, args=serv_args).start() + + # wait until server thread has assigned a port number + n = 500 + while PORT is None and n > 0: + time.sleep(0.01) + n -= 1 + + # wait a little longer (sometimes connections are refused + # on slow machines without this additional wait) + time.sleep(0.5) def tearDown(self): - self.evt.wait() + # indicate that the client is finished + self.client_evt.set() + # wait for the server thread to terminate + self.serv_evt.wait() + # restore sys.stdout sys.stdout = self.old_stdout def testBasic(self): # connect - smtp = smtplib.SMTP(HOST, PORT) - smtp.sock.close() + smtp = smtplib.SMTP(HOST, PORT, local_hostname='localhost', timeout=3) + smtp.quit() def testEHLO(self): - smtp = smtplib.SMTP(HOST, PORT) - self.assertEqual(smtp.ehlo(), (502, 'Error: command "EHLO" not implemented')) - smtp.sock.close() + smtp = smtplib.SMTP(HOST, PORT, local_hostname='localhost', timeout=3) + expected = (502, 'Error: command "EHLO" not implemented') + self.assertEqual(smtp.ehlo(), expected) + smtp.quit() def testHELP(self): - smtp = smtplib.SMTP(HOST, PORT) + smtp = smtplib.SMTP(HOST, PORT, local_hostname='localhost', timeout=3) self.assertEqual(smtp.help(), 'Error: command "HELP" not implemented') - smtp.sock.close() + smtp.quit() def testSend(self): # connect and send mail m = 'A test message' - smtp = smtplib.SMTP(HOST, PORT) + smtp = smtplib.SMTP(HOST, PORT, local_hostname='localhost', timeout=3) smtp.sendmail('John', 'Sally', m) - smtp.sock.close() + smtp.quit() - self.evt.wait() + self.client_evt.set() + self.serv_evt.wait() self.output.flush() mexpect = '%s%s\n%s' % (MSG_BEGIN, m, MSG_END) self.assertEqual(self.output.getvalue(), mexpect) @@ -166,17 +224,28 @@ self.evt = threading.Event() servargs = (self.evt, "199 no hello for you!\n") threading.Thread(target=server, args=servargs).start() - time.sleep(.5) + + # wait until server thread has assigned a port number + n = 500 + while PORT is None and n > 0: + time.sleep(0.01) + n -= 1 + + # wait a little longer (sometimes connections are refused + # on slow machines without this additional wait) + time.sleep(0.5) def tearDown(self): self.evt.wait() sys.stdout = self.old_stdout def testFailingHELO(self): - self.assertRaises(smtplib.SMTPConnectError, smtplib.SMTP, HOST, PORT) + self.assertRaises(smtplib.SMTPConnectError, smtplib.SMTP, + HOST, PORT, 'localhost', 3) def test_main(verbose=None): - test_support.run_unittest(GeneralTests, DebuggingServerTests, BadHELOServerTests) + test_support.run_unittest(GeneralTests, DebuggingServerTests, + BadHELOServerTests) if __name__ == '__main__': test_main() From buildbot at python.org Thu Aug 2 01:34:41 2007 From: buildbot at python.org (buildbot at python.org) Date: Wed, 01 Aug 2007 23:34:41 +0000 Subject: [Python-checkins] buildbot warnings in PPC64 Debian trunk Message-ID: <20070801233442.28F631E4007@bag.python.org> The Buildbot has detected a new failure of PPC64 Debian trunk. Full details are available at: http://www.python.org/dev/buildbot/all/PPC64%2520Debian%2520trunk/builds/86 Buildbot URL: http://www.python.org/dev/buildbot/all/ Build Reason: Build Source Stamp: [branch trunk] HEAD Blamelist: facundo.batista Build had warnings: warnings test Excerpt from the test logfile: make: *** [buildbottest] Segmentation fault sincerely, -The Buildbot From buildbot at python.org Thu Aug 2 01:47:01 2007 From: buildbot at python.org (buildbot at python.org) Date: Wed, 01 Aug 2007 23:47:01 +0000 Subject: [Python-checkins] buildbot warnings in amd64 XP trunk Message-ID: <20070801234701.AF02D1E4009@bag.python.org> The Buildbot has detected a new failure of amd64 XP trunk. Full details are available at: http://www.python.org/dev/buildbot/all/amd64%2520XP%2520trunk/builds/81 Buildbot URL: http://www.python.org/dev/buildbot/all/ Build Reason: Build Source Stamp: [branch trunk] HEAD Blamelist: facundo.batista Build had warnings: warnings test Excerpt from the test logfile: 2 tests failed: test_ctypes test_winsound ====================================================================== ERROR: test_extremes (test.test_winsound.BeepTest) ---------------------------------------------------------------------- Traceback (most recent call last): File "C:\buildbot\trunk.heller-windows-amd64\build\lib\test\test_winsound.py", line 18, in test_extremes winsound.Beep(37, 75) RuntimeError: Failed to beep ====================================================================== ERROR: test_increasingfrequency (test.test_winsound.BeepTest) ---------------------------------------------------------------------- Traceback (most recent call last): File "C:\buildbot\trunk.heller-windows-amd64\build\lib\test\test_winsound.py", line 23, in test_increasingfrequency winsound.Beep(i, 75) RuntimeError: Failed to beep ====================================================================== ERROR: test_alias_asterisk (test.test_winsound.PlaySoundTest) ---------------------------------------------------------------------- Traceback (most recent call last): File "C:\buildbot\trunk.heller-windows-amd64\build\lib\test\test_winsound.py", line 64, in test_alias_asterisk winsound.PlaySound('SystemAsterisk', winsound.SND_ALIAS) RuntimeError: Failed to play sound ====================================================================== ERROR: test_alias_exclamation (test.test_winsound.PlaySoundTest) ---------------------------------------------------------------------- Traceback (most recent call last): File "C:\buildbot\trunk.heller-windows-amd64\build\lib\test\test_winsound.py", line 74, in test_alias_exclamation winsound.PlaySound('SystemExclamation', winsound.SND_ALIAS) RuntimeError: Failed to play sound ====================================================================== ERROR: test_alias_exit (test.test_winsound.PlaySoundTest) ---------------------------------------------------------------------- Traceback (most recent call last): File "C:\buildbot\trunk.heller-windows-amd64\build\lib\test\test_winsound.py", line 84, in test_alias_exit winsound.PlaySound('SystemExit', winsound.SND_ALIAS) RuntimeError: Failed to play sound ====================================================================== ERROR: test_alias_hand (test.test_winsound.PlaySoundTest) ---------------------------------------------------------------------- Traceback (most recent call last): File "C:\buildbot\trunk.heller-windows-amd64\build\lib\test\test_winsound.py", line 94, in test_alias_hand winsound.PlaySound('SystemHand', winsound.SND_ALIAS) RuntimeError: Failed to play sound ====================================================================== ERROR: test_alias_question (test.test_winsound.PlaySoundTest) ---------------------------------------------------------------------- Traceback (most recent call last): File "C:\buildbot\trunk.heller-windows-amd64\build\lib\test\test_winsound.py", line 104, in test_alias_question winsound.PlaySound('SystemQuestion', winsound.SND_ALIAS) RuntimeError: Failed to play sound sincerely, -The Buildbot From buildbot at python.org Thu Aug 2 03:14:08 2007 From: buildbot at python.org (buildbot at python.org) Date: Thu, 02 Aug 2007 01:14:08 +0000 Subject: [Python-checkins] buildbot warnings in alpha Debian trunk Message-ID: <20070802011408.E603C1E4003@bag.python.org> The Buildbot has detected a new failure of alpha Debian trunk. Full details are available at: http://www.python.org/dev/buildbot/all/alpha%2520Debian%2520trunk/builds/78 Buildbot URL: http://www.python.org/dev/buildbot/all/ Build Reason: Build Source Stamp: [branch trunk] HEAD Blamelist: facundo.batista Build had warnings: warnings test Excerpt from the test logfile: 2 tests failed: test_math test_pow ====================================================================== FAIL: testFloor (test.test_math.MathTests) ---------------------------------------------------------------------- Traceback (most recent call last): File "/home/pybot/buildarea/trunk.klose-debian-alpha/build/Lib/test/test_math.py", line 101, in testFloor self.ftest('floor(1.23e167)', math.floor(1.23e167), 1.23e167) File "/home/pybot/buildarea/trunk.klose-debian-alpha/build/Lib/test/test_math.py", line 20, in ftest (name, value, expected)) AssertionError: floor(1.23e167) returned 1.2299999999999997e+167, expected 1.2299999999999999e+167 ====================================================================== ERROR: test_bug705231 (test.test_pow.PowTest) ---------------------------------------------------------------------- Traceback (most recent call last): File "/home/pybot/buildarea/trunk.klose-debian-alpha/build/Lib/test/test_pow.py", line 112, in test_bug705231 eq(pow(a, 1.23e167), 1.0) ValueError: negative number cannot be raised to a fractional power make: *** [buildbottest] Error 1 sincerely, -The Buildbot From python-checkins at python.org Thu Aug 2 04:14:37 2007 From: python-checkins at python.org (facundo.batista) Date: Thu, 2 Aug 2007 04:14:37 +0200 (CEST) Subject: [Python-checkins] r56654 - python/branches/decimal-branch/Lib/test/decimaltestdata/extra.decTest Message-ID: <20070802021437.E20181E4007@bag.python.org> Author: facundo.batista Date: Thu Aug 2 04:14:37 2007 New Revision: 56654 Added: python/branches/decimal-branch/Lib/test/decimaltestdata/extra.decTest Log: Extra tests for folddown and clamping, to fix some subtle errors that weren't discovered before. The idea is to use always this file for this ours-only not-Cowlishaw tests. Thanks to Mark Dickinson Added: python/branches/decimal-branch/Lib/test/decimaltestdata/extra.decTest ============================================================================== --- (empty file) +++ python/branches/decimal-branch/Lib/test/decimaltestdata/extra.decTest Thu Aug 2 04:14:37 2007 @@ -0,0 +1,94 @@ +version: ?.?? + +extended: 1 +rounding: half_even + +-- testing folddown and clamping +maxexponent: 9 +minexponent: -9 +precision: 6 +clamp: 1 +extr0000 apply 1E+11 -> Infinity Overflow Inexact Rounded +extr0001 apply 1E+10 -> Infinity Overflow Inexact Rounded +extr0002 apply 1E+9 -> 1.00000E+9 Clamped +extr0003 apply 1E+8 -> 1.0000E+8 Clamped +extr0004 apply 1E+7 -> 1.000E+7 Clamped +extr0005 apply 1E+6 -> 1.00E+6 Clamped +extr0006 apply 1E+5 -> 1.0E+5 Clamped +extr0007 apply 1E+4 -> 1E+4 +extr0008 apply 1E+3 -> 1E+3 +extr0009 apply 1E+2 -> 1E+2 +extr0010 apply 1E+1 -> 1E+1 +extr0011 apply 1 -> 1 +extr0012 apply 1E-1 -> 0.1 +extr0013 apply 1E-2 -> 0.01 +extr0014 apply 1E-3 -> 0.001 +extr0015 apply 1E-4 -> 0.0001 +extr0016 apply 1E-5 -> 0.00001 +extr0017 apply 1E-6 -> 0.000001 +extr0018 apply 1E-7 -> 1E-7 +extr0019 apply 1E-8 -> 1E-8 +extr0020 apply 1E-9 -> 1E-9 +extr0021 apply 1E-10 -> 1E-10 Subnormal +extr0022 apply 1E-11 -> 1E-11 Subnormal +extr0023 apply 1E-12 -> 1E-12 Subnormal +extr0024 apply 1E-13 -> 1E-13 Subnormal +extr0025 apply 1E-14 -> 1E-14 Subnormal +extr0026 apply 1E-15 -> 0E-14 Inexact Rounded Subnormal Underflow Clamped +extr0027 apply 1E-16 -> 0E-14 Inexact Rounded Subnormal Underflow Clamped +clamp: 0 + +-- large precision, small minimum and maximum exponent; in this case +-- it's possible that folddown is required on a subnormal result +maxexponent: 9 +minexponent: -9 +precision: 24 +clamp: 1 +extr0100 apply 1E+11 -> Infinity Overflow Inexact Rounded +extr0101 apply 1E+10 -> Infinity Overflow Inexact Rounded +extr0102 apply 1E+9 -> 1000000000.00000000000000 Clamped +extr0103 apply 1E+8 -> 100000000.00000000000000 Clamped +extr0104 apply 1E+7 -> 10000000.00000000000000 Clamped +extr0105 apply 1E+6 -> 1000000.00000000000000 Clamped +extr0106 apply 1E+5 -> 100000.00000000000000 Clamped +extr0107 apply 1E+4 -> 10000.00000000000000 Clamped +extr0108 apply 1E+3 -> 1000.00000000000000 Clamped +extr0109 apply 1E+2 -> 100.00000000000000 Clamped +extr0110 apply 1E+1 -> 10.00000000000000 Clamped +extr0111 apply 1 -> 1.00000000000000 Clamped +extr0112 apply 1E-1 -> 0.10000000000000 Clamped +extr0113 apply 1E-2 -> 0.01000000000000 Clamped +extr0114 apply 1E-3 -> 0.00100000000000 Clamped +extr0115 apply 1E-4 -> 0.00010000000000 Clamped +extr0116 apply 1E-5 -> 0.00001000000000 Clamped +extr0117 apply 1E-6 -> 0.00000100000000 Clamped +extr0118 apply 1E-7 -> 1.0000000E-7 Clamped +extr0119 apply 1E-8 -> 1.000000E-8 Clamped +extr0120 apply 1E-9 -> 1.00000E-9 Clamped +extr0121 apply 1E-10 -> 1.0000E-10 Subnormal Clamped +extr0122 apply 1E-11 -> 1.000E-11 Subnormal Clamped +extr0123 apply 1E-12 -> 1.00E-12 Subnormal Clamped +extr0124 apply 1E-13 -> 1.0E-13 Subnormal Clamped +extr0125 apply 1E-14 -> 1E-14 Subnormal +extr0126 apply 1E-15 -> 1E-15 Subnormal +extr0127 apply 1E-16 -> 1E-16 Subnormal +extr0128 apply 1E-17 -> 1E-17 Subnormal +extr0129 apply 1E-18 -> 1E-18 Subnormal +extr0130 apply 1E-19 -> 1E-19 Subnormal +extr0131 apply 1E-20 -> 1E-20 Subnormal +extr0132 apply 1E-21 -> 1E-21 Subnormal +extr0133 apply 1E-22 -> 1E-22 Subnormal +extr0134 apply 1E-23 -> 1E-23 Subnormal +extr0135 apply 1E-24 -> 1E-24 Subnormal +extr0136 apply 1E-25 -> 1E-25 Subnormal +extr0137 apply 1E-26 -> 1E-26 Subnormal +extr0138 apply 1E-27 -> 1E-27 Subnormal +extr0139 apply 1E-28 -> 1E-28 Subnormal +extr0140 apply 1E-29 -> 1E-29 Subnormal +extr0141 apply 1E-30 -> 1E-30 Subnormal +extr0142 apply 1E-31 -> 1E-31 Subnormal +extr0143 apply 1E-32 -> 1E-32 Subnormal +extr0144 apply 1E-33 -> 0E-32 Inexact Rounded Subnormal Underflow Clamped +extr0145 apply 1E-34 -> 0E-32 Inexact Rounded Subnormal Underflow Clamped +clamp: 0 + From python-checkins at python.org Thu Aug 2 04:16:25 2007 From: python-checkins at python.org (facundo.batista) Date: Thu, 2 Aug 2007 04:16:25 +0200 (CEST) Subject: [Python-checkins] r56655 - python/branches/decimal-branch/Lib/test/decimaltestdata/squareroot_extra.decTest Message-ID: <20070802021625.014B61E4003@bag.python.org> Author: facundo.batista Date: Thu Aug 2 04:16:24 2007 New Revision: 56655 Added: python/branches/decimal-branch/Lib/test/decimaltestdata/squareroot_extra.decTest Log: New tests for squareroot, coordinate with Cowlishaw, maybe he'll keep this as a separated file or integrate these tests in the standard squareroot.decTest file in a later version. Thanks to Mark Dickinson. Added: python/branches/decimal-branch/Lib/test/decimaltestdata/squareroot_extra.decTest ============================================================================== --- (empty file) +++ python/branches/decimal-branch/Lib/test/decimaltestdata/squareroot_extra.decTest Thu Aug 2 04:16:24 2007 @@ -0,0 +1,800 @@ +------------------------------------------------------------------------ +-- +-- Special thanks to Mark Dickinson for tests in the range 1000-1999. +-- +-- Extra tests for the square root function, dealing with a variety of +-- corner cases. In particular, these tests concentrate on +-- (1) cases where the input precision exceeds the context precision, and +-- (2) cases where the input exponent is outside the current context, +-- and in particular when the result is subnormal +-- +-- maxexponent and minexponent are set to 9 and -9 throughout these +-- cases; only the precision changes. The rounding also does not +-- change, and should be irrelevant. Ideally these tests could be +-- run with all rounding modes to check that the rounding mode does +-- not affect any of the results. + +version: 2.xx + +extended: 1 +rounding: down +maxexponent: 9 +minexponent: -9 + +-- exact results, input precision > context precision +precision: 1 +sqtx1000 squareroot 0 -> 0 +sqtx1001 squareroot 1 -> 1 +sqtx1002 squareroot 4 -> 2 +sqtx1003 squareroot 9 -> 3 +sqtx1004 squareroot 16 -> 4 +sqtx1005 squareroot 25 -> 5 +sqtx1006 squareroot 36 -> 6 +sqtx1007 squareroot 49 -> 7 +sqtx1008 squareroot 64 -> 8 +sqtx1009 squareroot 81 -> 9 +sqtx1010 squareroot 100 -> 1E+1 Rounded +sqtx1011 squareroot 121 -> 1E+1 Inexact Rounded + +precision: 2 +sqtx1012 squareroot 0 -> 0 +sqtx1013 squareroot 1 -> 1 +sqtx1014 squareroot 4 -> 2 +sqtx1015 squareroot 9 -> 3 +sqtx1016 squareroot 16 -> 4 +sqtx1017 squareroot 25 -> 5 +sqtx1018 squareroot 36 -> 6 +sqtx1019 squareroot 49 -> 7 +sqtx1020 squareroot 64 -> 8 +sqtx1021 squareroot 81 -> 9 +sqtx1022 squareroot 100 -> 10 +sqtx1023 squareroot 121 -> 11 +sqtx1024 squareroot 144 -> 12 +sqtx1025 squareroot 169 -> 13 +sqtx1026 squareroot 196 -> 14 +sqtx1027 squareroot 225 -> 15 +sqtx1028 squareroot 256 -> 16 +sqtx1029 squareroot 289 -> 17 +sqtx1030 squareroot 324 -> 18 +sqtx1031 squareroot 361 -> 19 +sqtx1032 squareroot 400 -> 20 +sqtx1033 squareroot 441 -> 21 +sqtx1034 squareroot 484 -> 22 +sqtx1035 squareroot 529 -> 23 +sqtx1036 squareroot 576 -> 24 +sqtx1037 squareroot 625 -> 25 +sqtx1038 squareroot 676 -> 26 +sqtx1039 squareroot 729 -> 27 +sqtx1040 squareroot 784 -> 28 +sqtx1041 squareroot 841 -> 29 +sqtx1042 squareroot 900 -> 30 +sqtx1043 squareroot 961 -> 31 +sqtx1044 squareroot 1024 -> 32 +sqtx1045 squareroot 1089 -> 33 +sqtx1046 squareroot 1156 -> 34 +sqtx1047 squareroot 1225 -> 35 +sqtx1048 squareroot 1296 -> 36 +sqtx1049 squareroot 1369 -> 37 +sqtx1050 squareroot 1444 -> 38 +sqtx1051 squareroot 1521 -> 39 +sqtx1052 squareroot 1600 -> 40 +sqtx1053 squareroot 1681 -> 41 +sqtx1054 squareroot 1764 -> 42 +sqtx1055 squareroot 1849 -> 43 +sqtx1056 squareroot 1936 -> 44 +sqtx1057 squareroot 2025 -> 45 +sqtx1058 squareroot 2116 -> 46 +sqtx1059 squareroot 2209 -> 47 +sqtx1060 squareroot 2304 -> 48 +sqtx1061 squareroot 2401 -> 49 +sqtx1062 squareroot 2500 -> 50 +sqtx1063 squareroot 2601 -> 51 +sqtx1064 squareroot 2704 -> 52 +sqtx1065 squareroot 2809 -> 53 +sqtx1066 squareroot 2916 -> 54 +sqtx1067 squareroot 3025 -> 55 +sqtx1068 squareroot 3136 -> 56 +sqtx1069 squareroot 3249 -> 57 +sqtx1070 squareroot 3364 -> 58 +sqtx1071 squareroot 3481 -> 59 +sqtx1072 squareroot 3600 -> 60 +sqtx1073 squareroot 3721 -> 61 +sqtx1074 squareroot 3844 -> 62 +sqtx1075 squareroot 3969 -> 63 +sqtx1076 squareroot 4096 -> 64 +sqtx1077 squareroot 4225 -> 65 +sqtx1078 squareroot 4356 -> 66 +sqtx1079 squareroot 4489 -> 67 +sqtx1080 squareroot 4624 -> 68 +sqtx1081 squareroot 4761 -> 69 +sqtx1082 squareroot 4900 -> 70 +sqtx1083 squareroot 5041 -> 71 +sqtx1084 squareroot 5184 -> 72 +sqtx1085 squareroot 5329 -> 73 +sqtx1086 squareroot 5476 -> 74 +sqtx1087 squareroot 5625 -> 75 +sqtx1088 squareroot 5776 -> 76 +sqtx1089 squareroot 5929 -> 77 +sqtx1090 squareroot 6084 -> 78 +sqtx1091 squareroot 6241 -> 79 +sqtx1092 squareroot 6400 -> 80 +sqtx1093 squareroot 6561 -> 81 +sqtx1094 squareroot 6724 -> 82 +sqtx1095 squareroot 6889 -> 83 +sqtx1096 squareroot 7056 -> 84 +sqtx1097 squareroot 7225 -> 85 +sqtx1098 squareroot 7396 -> 86 +sqtx1099 squareroot 7569 -> 87 +sqtx1100 squareroot 7744 -> 88 +sqtx1101 squareroot 7921 -> 89 +sqtx1102 squareroot 8100 -> 90 +sqtx1103 squareroot 8281 -> 91 +sqtx1104 squareroot 8464 -> 92 +sqtx1105 squareroot 8649 -> 93 +sqtx1106 squareroot 8836 -> 94 +sqtx1107 squareroot 9025 -> 95 +sqtx1108 squareroot 9216 -> 96 +sqtx1109 squareroot 9409 -> 97 +sqtx1110 squareroot 9604 -> 98 +sqtx1111 squareroot 9801 -> 99 +sqtx1112 squareroot 10000 -> 1.0E+2 Rounded +sqtx1113 squareroot 10201 -> 1.0E+2 Inexact Rounded + +precision: 3 +sqtx1114 squareroot 841 -> 29 +sqtx1115 squareroot 1600 -> 40 +sqtx1116 squareroot 2209 -> 47 +sqtx1117 squareroot 9604 -> 98 +sqtx1118 squareroot 21316 -> 146 +sqtx1119 squareroot 52441 -> 229 +sqtx1120 squareroot 68644 -> 262 +sqtx1121 squareroot 69696 -> 264 +sqtx1122 squareroot 70225 -> 265 +sqtx1123 squareroot 76729 -> 277 +sqtx1124 squareroot 130321 -> 361 +sqtx1125 squareroot 171396 -> 414 +sqtx1126 squareroot 270400 -> 520 +sqtx1127 squareroot 279841 -> 529 +sqtx1128 squareroot 407044 -> 638 +sqtx1129 squareroot 408321 -> 639 +sqtx1130 squareroot 480249 -> 693 +sqtx1131 squareroot 516961 -> 719 +sqtx1132 squareroot 692224 -> 832 +sqtx1133 squareroot 829921 -> 911 + +-- selection of random exact results +precision: 6 +sqtx1134 squareroot 2.25E-12 -> 0.0000015 +sqtx1135 squareroot 8.41E-14 -> 2.9E-7 +sqtx1136 squareroot 6.241E-15 -> 7.9E-8 +sqtx1137 squareroot 5.041E+13 -> 7.1E+6 +sqtx1138 squareroot 4761 -> 69 +sqtx1139 squareroot 1.369E+17 -> 3.7E+8 +sqtx1140 squareroot 0.00002116 -> 0.0046 +sqtx1141 squareroot 7.29E+4 -> 2.7E+2 +sqtx1142 squareroot 4.624E-13 -> 6.8E-7 +sqtx1143 squareroot 3.969E+5 -> 6.3E+2 +sqtx1144 squareroot 3.73321E-11 -> 0.00000611 +sqtx1145 squareroot 5.61001E+17 -> 7.49E+8 +sqtx1146 squareroot 2.30400E-11 -> 0.00000480 +sqtx1147 squareroot 4.30336E+17 -> 6.56E+8 +sqtx1148 squareroot 0.057121 -> 0.239 +sqtx1149 squareroot 7.225E+17 -> 8.5E+8 +sqtx1150 squareroot 3.14721E+13 -> 5.61E+6 +sqtx1151 squareroot 4.61041E+17 -> 6.79E+8 +sqtx1152 squareroot 1.39876E-15 -> 3.74E-8 +sqtx1153 squareroot 6.19369E-9 -> 0.0000787 +sqtx1154 squareroot 1.620529E-10 -> 0.00001273 +sqtx1155 squareroot 1177.1761 -> 34.31 +sqtx1156 squareroot 67043344 -> 8188 +sqtx1157 squareroot 4.84E+6 -> 2.2E+3 +sqtx1158 squareroot 1.23904E+11 -> 3.52E+5 +sqtx1159 squareroot 32604100 -> 5710 +sqtx1160 squareroot 2.9757025E-11 -> 0.000005455 +sqtx1161 squareroot 6.3760225E-9 -> 0.00007985 +sqtx1162 squareroot 4.5198729E-11 -> 0.000006723 +sqtx1163 squareroot 1.4745600E-11 -> 0.000003840 +sqtx1164 squareroot 18964283.04 -> 4354.8 +sqtx1165 squareroot 3.308895529E+13 -> 5.7523E+6 +sqtx1166 squareroot 0.0028590409 -> 0.05347 +sqtx1167 squareroot 3572.213824 -> 59.768 +sqtx1168 squareroot 4.274021376E+15 -> 6.5376E+7 +sqtx1169 squareroot 4455476.64 -> 2110.8 +sqtx1170 squareroot 38.44 -> 6.2 +sqtx1171 squareroot 68.558400 -> 8.280 +sqtx1172 squareroot 715402009 -> 26747 +sqtx1173 squareroot 93.373569 -> 9.663 +sqtx1174 squareroot 2.62144000000E+15 -> 5.12000E+7 +sqtx1175 squareroot 7.48225000000E+15 -> 8.65000E+7 +sqtx1176 squareroot 3.38724000000E-9 -> 0.0000582000 +sqtx1177 squareroot 5.64001000000E-13 -> 7.51000E-7 +sqtx1178 squareroot 5.06944000000E-15 -> 7.12000E-8 +sqtx1179 squareroot 4.95616000000E+17 -> 7.04000E+8 +sqtx1180 squareroot 0.0000242064000000 -> 0.00492000 +sqtx1181 squareroot 1.48996000000E-15 -> 3.86000E-8 +sqtx1182 squareroot 9.37024000000E+17 -> 9.68000E+8 +sqtx1183 squareroot 7128900.0000 -> 2670.00 +sqtx1184 squareroot 8.2311610000E-10 -> 0.0000286900 +sqtx1185 squareroot 482747040000 -> 694800 +sqtx1186 squareroot 4.14478440000E+17 -> 6.43800E+8 +sqtx1187 squareroot 5.10510250000E-7 -> 0.000714500 +sqtx1188 squareroot 355096.810000 -> 595.900 +sqtx1189 squareroot 14288400.0000 -> 3780.00 +sqtx1190 squareroot 3.36168040000E-15 -> 5.79800E-8 +sqtx1191 squareroot 1.70899560000E-13 -> 4.13400E-7 +sqtx1192 squareroot 0.0000378348010000 -> 0.00615100 +sqtx1193 squareroot 2.00972890000E-13 -> 4.48300E-7 +sqtx1194 squareroot 4.07222659600E-13 -> 6.38140E-7 +sqtx1195 squareroot 131486012100 -> 362610 +sqtx1196 squareroot 818192611600 -> 904540 +sqtx1197 squareroot 9.8558323600E+16 -> 3.13940E+8 +sqtx1198 squareroot 5641.06144900 -> 75.1070 +sqtx1199 squareroot 4.58789475600E+17 -> 6.77340E+8 +sqtx1200 squareroot 3.21386948100E-9 -> 0.0000566910 +sqtx1201 squareroot 3.9441960000E-8 -> 0.000198600 +sqtx1202 squareroot 242723.728900 -> 492.670 +sqtx1203 squareroot 1874.89000000 -> 43.3000 +sqtx1204 squareroot 2.56722595684E+15 -> 5.06678E+7 +sqtx1205 squareroot 3.96437714689E-17 -> 6.29633E-9 +sqtx1206 squareroot 3.80106774784E-17 -> 6.16528E-9 +sqtx1207 squareroot 1.42403588496E-13 -> 3.77364E-7 +sqtx1208 squareroot 4604.84388100 -> 67.8590 +sqtx1209 squareroot 2157100869.16 -> 46444.6 +sqtx1210 squareroot 355288570.81 -> 18849.1 +sqtx1211 squareroot 4.69775901604E-11 -> 0.00000685402 +sqtx1212 squareroot 8.22115770436E+17 -> 9.06706E+8 +sqtx1213 squareroot 7.16443744900E+15 -> 8.46430E+7 +sqtx1214 squareroot 9.48995498896E+15 -> 9.74164E+7 +sqtx1215 squareroot 0.0000419091801129 -> 0.00647373 +sqtx1216 squareroot 5862627996.84 -> 76567.8 +sqtx1217 squareroot 9369537.3409 -> 3060.97 +sqtx1218 squareroot 7.74792529729E+17 -> 8.80223E+8 +sqtx1219 squareroot 1.08626931396E+17 -> 3.29586E+8 +sqtx1220 squareroot 8.89584739684E-7 -> 0.000943178 +sqtx1221 squareroot 4.0266040896E-18 -> 2.00664E-9 +sqtx1222 squareroot 9.27669480336E-7 -> 0.000963156 +sqtx1223 squareroot 0.00225497717956 -> 0.0474866 + +-- test use of round-half-even for ties +precision: 1 +sqtx1224 squareroot 225 -> 2E+1 Inexact Rounded +sqtx1225 squareroot 625 -> 2E+1 Inexact Rounded +sqtx1226 squareroot 1225 -> 4E+1 Inexact Rounded +sqtx1227 squareroot 2025 -> 4E+1 Inexact Rounded +sqtx1228 squareroot 3025 -> 6E+1 Inexact Rounded +sqtx1229 squareroot 4225 -> 6E+1 Inexact Rounded +sqtx1230 squareroot 5625 -> 8E+1 Inexact Rounded +sqtx1231 squareroot 7225 -> 8E+1 Inexact Rounded +sqtx1232 squareroot 9025 -> 1E+2 Inexact Rounded + +precision: 2 +sqtx1233 squareroot 11025 -> 1.0E+2 Inexact Rounded +sqtx1234 squareroot 13225 -> 1.2E+2 Inexact Rounded +sqtx1235 squareroot 15625 -> 1.2E+2 Inexact Rounded +sqtx1236 squareroot 18225 -> 1.4E+2 Inexact Rounded +sqtx1237 squareroot 21025 -> 1.4E+2 Inexact Rounded +sqtx1238 squareroot 24025 -> 1.6E+2 Inexact Rounded +sqtx1239 squareroot 27225 -> 1.6E+2 Inexact Rounded +sqtx1240 squareroot 30625 -> 1.8E+2 Inexact Rounded +sqtx1241 squareroot 34225 -> 1.8E+2 Inexact Rounded +sqtx1242 squareroot 38025 -> 2.0E+2 Inexact Rounded +sqtx1243 squareroot 42025 -> 2.0E+2 Inexact Rounded +sqtx1244 squareroot 46225 -> 2.2E+2 Inexact Rounded +sqtx1245 squareroot 50625 -> 2.2E+2 Inexact Rounded +sqtx1246 squareroot 55225 -> 2.4E+2 Inexact Rounded +sqtx1247 squareroot 60025 -> 2.4E+2 Inexact Rounded +sqtx1248 squareroot 65025 -> 2.6E+2 Inexact Rounded +sqtx1249 squareroot 70225 -> 2.6E+2 Inexact Rounded +sqtx1250 squareroot 75625 -> 2.8E+2 Inexact Rounded +sqtx1251 squareroot 81225 -> 2.8E+2 Inexact Rounded +sqtx1252 squareroot 87025 -> 3.0E+2 Inexact Rounded +sqtx1253 squareroot 93025 -> 3.0E+2 Inexact Rounded +sqtx1254 squareroot 99225 -> 3.2E+2 Inexact Rounded +sqtx1255 squareroot 105625 -> 3.2E+2 Inexact Rounded +sqtx1256 squareroot 112225 -> 3.4E+2 Inexact Rounded +sqtx1257 squareroot 119025 -> 3.4E+2 Inexact Rounded +sqtx1258 squareroot 126025 -> 3.6E+2 Inexact Rounded +sqtx1259 squareroot 133225 -> 3.6E+2 Inexact Rounded +sqtx1260 squareroot 140625 -> 3.8E+2 Inexact Rounded +sqtx1261 squareroot 148225 -> 3.8E+2 Inexact Rounded +sqtx1262 squareroot 156025 -> 4.0E+2 Inexact Rounded +sqtx1263 squareroot 164025 -> 4.0E+2 Inexact Rounded +sqtx1264 squareroot 172225 -> 4.2E+2 Inexact Rounded +sqtx1265 squareroot 180625 -> 4.2E+2 Inexact Rounded +sqtx1266 squareroot 189225 -> 4.4E+2 Inexact Rounded +sqtx1267 squareroot 198025 -> 4.4E+2 Inexact Rounded +sqtx1268 squareroot 207025 -> 4.6E+2 Inexact Rounded +sqtx1269 squareroot 216225 -> 4.6E+2 Inexact Rounded +sqtx1270 squareroot 225625 -> 4.8E+2 Inexact Rounded +sqtx1271 squareroot 235225 -> 4.8E+2 Inexact Rounded +sqtx1272 squareroot 245025 -> 5.0E+2 Inexact Rounded +sqtx1273 squareroot 255025 -> 5.0E+2 Inexact Rounded +sqtx1274 squareroot 265225 -> 5.2E+2 Inexact Rounded +sqtx1275 squareroot 275625 -> 5.2E+2 Inexact Rounded +sqtx1276 squareroot 286225 -> 5.4E+2 Inexact Rounded +sqtx1277 squareroot 297025 -> 5.4E+2 Inexact Rounded +sqtx1278 squareroot 308025 -> 5.6E+2 Inexact Rounded +sqtx1279 squareroot 319225 -> 5.6E+2 Inexact Rounded +sqtx1280 squareroot 330625 -> 5.8E+2 Inexact Rounded +sqtx1281 squareroot 342225 -> 5.8E+2 Inexact Rounded +sqtx1282 squareroot 354025 -> 6.0E+2 Inexact Rounded +sqtx1283 squareroot 366025 -> 6.0E+2 Inexact Rounded +sqtx1284 squareroot 378225 -> 6.2E+2 Inexact Rounded +sqtx1285 squareroot 390625 -> 6.2E+2 Inexact Rounded +sqtx1286 squareroot 403225 -> 6.4E+2 Inexact Rounded +sqtx1287 squareroot 416025 -> 6.4E+2 Inexact Rounded +sqtx1288 squareroot 429025 -> 6.6E+2 Inexact Rounded +sqtx1289 squareroot 442225 -> 6.6E+2 Inexact Rounded +sqtx1290 squareroot 455625 -> 6.8E+2 Inexact Rounded +sqtx1291 squareroot 469225 -> 6.8E+2 Inexact Rounded +sqtx1292 squareroot 483025 -> 7.0E+2 Inexact Rounded +sqtx1293 squareroot 497025 -> 7.0E+2 Inexact Rounded +sqtx1294 squareroot 511225 -> 7.2E+2 Inexact Rounded +sqtx1295 squareroot 525625 -> 7.2E+2 Inexact Rounded +sqtx1296 squareroot 540225 -> 7.4E+2 Inexact Rounded +sqtx1297 squareroot 555025 -> 7.4E+2 Inexact Rounded +sqtx1298 squareroot 570025 -> 7.6E+2 Inexact Rounded +sqtx1299 squareroot 585225 -> 7.6E+2 Inexact Rounded +sqtx1300 squareroot 600625 -> 7.8E+2 Inexact Rounded +sqtx1301 squareroot 616225 -> 7.8E+2 Inexact Rounded +sqtx1302 squareroot 632025 -> 8.0E+2 Inexact Rounded +sqtx1303 squareroot 648025 -> 8.0E+2 Inexact Rounded +sqtx1304 squareroot 664225 -> 8.2E+2 Inexact Rounded +sqtx1305 squareroot 680625 -> 8.2E+2 Inexact Rounded +sqtx1306 squareroot 697225 -> 8.4E+2 Inexact Rounded +sqtx1307 squareroot 714025 -> 8.4E+2 Inexact Rounded +sqtx1308 squareroot 731025 -> 8.6E+2 Inexact Rounded +sqtx1309 squareroot 748225 -> 8.6E+2 Inexact Rounded +sqtx1310 squareroot 765625 -> 8.8E+2 Inexact Rounded +sqtx1311 squareroot 783225 -> 8.8E+2 Inexact Rounded +sqtx1312 squareroot 801025 -> 9.0E+2 Inexact Rounded +sqtx1313 squareroot 819025 -> 9.0E+2 Inexact Rounded +sqtx1314 squareroot 837225 -> 9.2E+2 Inexact Rounded +sqtx1315 squareroot 855625 -> 9.2E+2 Inexact Rounded +sqtx1316 squareroot 874225 -> 9.4E+2 Inexact Rounded +sqtx1317 squareroot 893025 -> 9.4E+2 Inexact Rounded +sqtx1318 squareroot 912025 -> 9.6E+2 Inexact Rounded +sqtx1319 squareroot 931225 -> 9.6E+2 Inexact Rounded +sqtx1320 squareroot 950625 -> 9.8E+2 Inexact Rounded +sqtx1321 squareroot 970225 -> 9.8E+2 Inexact Rounded +sqtx1322 squareroot 990025 -> 1.0E+3 Inexact Rounded + +precision: 6 +sqtx1323 squareroot 88975734963025 -> 9.43270E+6 Inexact Rounded +sqtx1324 squareroot 71085555000625 -> 8.43122E+6 Inexact Rounded +sqtx1325 squareroot 39994304.051025 -> 6324.10 Inexact Rounded +sqtx1326 squareroot 0.000007327172265625 -> 0.00270688 Inexact Rounded +sqtx1327 squareroot 1.0258600439025E-13 -> 3.20290E-7 Inexact Rounded +sqtx1328 squareroot 0.0034580574275625 -> 0.0588052 Inexact Rounded +sqtx1329 squareroot 7.6842317700625E-7 -> 0.000876598 Inexact Rounded +sqtx1330 squareroot 1263834495.2025 -> 35550.4 Inexact Rounded +sqtx1331 squareroot 433970666460.25 -> 658764 Inexact Rounded +sqtx1332 squareroot 4.5879286230625E-7 -> 0.000677342 Inexact Rounded +sqtx1333 squareroot 0.0029305603306225 -> 0.0541346 Inexact Rounded +sqtx1334 squareroot 70218282.733225 -> 8379.64 Inexact Rounded +sqtx1335 squareroot 11942519.082025 -> 3455.80 Inexact Rounded +sqtx1336 squareroot 0.0021230668905625 -> 0.0460768 Inexact Rounded +sqtx1337 squareroot 0.90081833411025 -> 0.949114 Inexact Rounded +sqtx1338 squareroot 5.5104120936225E-17 -> 7.42322E-9 Inexact Rounded +sqtx1339 squareroot 0.10530446854225 -> 0.324506 Inexact Rounded +sqtx1340 squareroot 8.706069866025E-14 -> 2.95060E-7 Inexact Rounded +sqtx1341 squareroot 23838.58800625 -> 154.398 Inexact Rounded +sqtx1342 squareroot 0.0013426911275625 -> 0.0366428 Inexact Rounded + +-- test use of round-half-even in underflow situations + +-- precisions 2; all cases where result is both subnormal and a tie +precision: 2 +sqtx1343 squareroot 2.5E-21 -> 0E-10 Underflow Subnormal Inexact Rounded Clamped +sqtx1344 squareroot 2.25E-20 -> 2E-10 Underflow Subnormal Inexact Rounded +sqtx1345 squareroot 6.25E-20 -> 2E-10 Underflow Subnormal Inexact Rounded +sqtx1346 squareroot 1.225E-19 -> 4E-10 Underflow Subnormal Inexact Rounded +sqtx1347 squareroot 2.025E-19 -> 4E-10 Underflow Subnormal Inexact Rounded +sqtx1348 squareroot 3.025E-19 -> 6E-10 Underflow Subnormal Inexact Rounded +sqtx1349 squareroot 4.225E-19 -> 6E-10 Underflow Subnormal Inexact Rounded +sqtx1350 squareroot 5.625E-19 -> 8E-10 Underflow Subnormal Inexact Rounded +sqtx1351 squareroot 7.225E-19 -> 8E-10 Underflow Subnormal Inexact Rounded +sqtx1352 squareroot 9.025E-19 -> 1.0E-9 Underflow Subnormal Inexact Rounded + +-- precision 3, input precision <= 5 +precision: 3 +sqtx1353 squareroot 2.5E-23 -> 0E-11 Underflow Subnormal Inexact Rounded Clamped +sqtx1354 squareroot 2.25E-22 -> 2E-11 Underflow Subnormal Inexact Rounded +sqtx1355 squareroot 6.25E-22 -> 2E-11 Underflow Subnormal Inexact Rounded +sqtx1356 squareroot 1.225E-21 -> 4E-11 Underflow Subnormal Inexact Rounded +sqtx1357 squareroot 2.025E-21 -> 4E-11 Underflow Subnormal Inexact Rounded +sqtx1358 squareroot 3.025E-21 -> 6E-11 Underflow Subnormal Inexact Rounded +sqtx1359 squareroot 4.225E-21 -> 6E-11 Underflow Subnormal Inexact Rounded +sqtx1360 squareroot 5.625E-21 -> 8E-11 Underflow Subnormal Inexact Rounded +sqtx1361 squareroot 7.225E-21 -> 8E-11 Underflow Subnormal Inexact Rounded +sqtx1362 squareroot 9.025E-21 -> 1.0E-10 Underflow Subnormal Inexact Rounded +sqtx1363 squareroot 1.1025E-20 -> 1.0E-10 Underflow Subnormal Inexact Rounded +sqtx1364 squareroot 1.3225E-20 -> 1.2E-10 Underflow Subnormal Inexact Rounded +sqtx1365 squareroot 1.5625E-20 -> 1.2E-10 Underflow Subnormal Inexact Rounded +sqtx1366 squareroot 1.8225E-20 -> 1.4E-10 Underflow Subnormal Inexact Rounded +sqtx1367 squareroot 2.1025E-20 -> 1.4E-10 Underflow Subnormal Inexact Rounded +sqtx1368 squareroot 2.4025E-20 -> 1.6E-10 Underflow Subnormal Inexact Rounded +sqtx1369 squareroot 2.7225E-20 -> 1.6E-10 Underflow Subnormal Inexact Rounded +sqtx1370 squareroot 3.0625E-20 -> 1.8E-10 Underflow Subnormal Inexact Rounded +sqtx1371 squareroot 3.4225E-20 -> 1.8E-10 Underflow Subnormal Inexact Rounded +sqtx1372 squareroot 3.8025E-20 -> 2.0E-10 Underflow Subnormal Inexact Rounded +sqtx1373 squareroot 4.2025E-20 -> 2.0E-10 Underflow Subnormal Inexact Rounded +sqtx1374 squareroot 4.6225E-20 -> 2.2E-10 Underflow Subnormal Inexact Rounded +sqtx1375 squareroot 5.0625E-20 -> 2.2E-10 Underflow Subnormal Inexact Rounded +sqtx1376 squareroot 5.5225E-20 -> 2.4E-10 Underflow Subnormal Inexact Rounded +sqtx1377 squareroot 6.0025E-20 -> 2.4E-10 Underflow Subnormal Inexact Rounded +sqtx1378 squareroot 6.5025E-20 -> 2.6E-10 Underflow Subnormal Inexact Rounded +sqtx1379 squareroot 7.0225E-20 -> 2.6E-10 Underflow Subnormal Inexact Rounded +sqtx1380 squareroot 7.5625E-20 -> 2.8E-10 Underflow Subnormal Inexact Rounded +sqtx1381 squareroot 8.1225E-20 -> 2.8E-10 Underflow Subnormal Inexact Rounded +sqtx1382 squareroot 8.7025E-20 -> 3.0E-10 Underflow Subnormal Inexact Rounded +sqtx1383 squareroot 9.3025E-20 -> 3.0E-10 Underflow Subnormal Inexact Rounded +sqtx1384 squareroot 9.9225E-20 -> 3.2E-10 Underflow Subnormal Inexact Rounded + +--precision 4, input precision <= 4 +precision: 4 +sqtx1385 squareroot 2.5E-25 -> 0E-12 Underflow Subnormal Inexact Rounded Clamped +sqtx1386 squareroot 2.25E-24 -> 2E-12 Underflow Subnormal Inexact Rounded +sqtx1387 squareroot 6.25E-24 -> 2E-12 Underflow Subnormal Inexact Rounded +sqtx1388 squareroot 1.225E-23 -> 4E-12 Underflow Subnormal Inexact Rounded +sqtx1389 squareroot 2.025E-23 -> 4E-12 Underflow Subnormal Inexact Rounded +sqtx1390 squareroot 3.025E-23 -> 6E-12 Underflow Subnormal Inexact Rounded +sqtx1391 squareroot 4.225E-23 -> 6E-12 Underflow Subnormal Inexact Rounded +sqtx1392 squareroot 5.625E-23 -> 8E-12 Underflow Subnormal Inexact Rounded +sqtx1393 squareroot 7.225E-23 -> 8E-12 Underflow Subnormal Inexact Rounded +sqtx1394 squareroot 9.025E-23 -> 1.0E-11 Underflow Subnormal Inexact Rounded + +--precision 5, input precision <= 5 +precision: 5 +sqtx1395 squareroot 2.5E-27 -> 0E-13 Underflow Subnormal Inexact Rounded Clamped +sqtx1396 squareroot 2.25E-26 -> 2E-13 Underflow Subnormal Inexact Rounded +sqtx1397 squareroot 6.25E-26 -> 2E-13 Underflow Subnormal Inexact Rounded +sqtx1398 squareroot 1.225E-25 -> 4E-13 Underflow Subnormal Inexact Rounded +sqtx1399 squareroot 2.025E-25 -> 4E-13 Underflow Subnormal Inexact Rounded +sqtx1400 squareroot 3.025E-25 -> 6E-13 Underflow Subnormal Inexact Rounded +sqtx1401 squareroot 4.225E-25 -> 6E-13 Underflow Subnormal Inexact Rounded +sqtx1402 squareroot 5.625E-25 -> 8E-13 Underflow Subnormal Inexact Rounded +sqtx1403 squareroot 7.225E-25 -> 8E-13 Underflow Subnormal Inexact Rounded +sqtx1404 squareroot 9.025E-25 -> 1.0E-12 Underflow Subnormal Inexact Rounded +sqtx1405 squareroot 1.1025E-24 -> 1.0E-12 Underflow Subnormal Inexact Rounded +sqtx1406 squareroot 1.3225E-24 -> 1.2E-12 Underflow Subnormal Inexact Rounded +sqtx1407 squareroot 1.5625E-24 -> 1.2E-12 Underflow Subnormal Inexact Rounded +sqtx1408 squareroot 1.8225E-24 -> 1.4E-12 Underflow Subnormal Inexact Rounded +sqtx1409 squareroot 2.1025E-24 -> 1.4E-12 Underflow Subnormal Inexact Rounded +sqtx1410 squareroot 2.4025E-24 -> 1.6E-12 Underflow Subnormal Inexact Rounded +sqtx1411 squareroot 2.7225E-24 -> 1.6E-12 Underflow Subnormal Inexact Rounded +sqtx1412 squareroot 3.0625E-24 -> 1.8E-12 Underflow Subnormal Inexact Rounded +sqtx1413 squareroot 3.4225E-24 -> 1.8E-12 Underflow Subnormal Inexact Rounded +sqtx1414 squareroot 3.8025E-24 -> 2.0E-12 Underflow Subnormal Inexact Rounded +sqtx1415 squareroot 4.2025E-24 -> 2.0E-12 Underflow Subnormal Inexact Rounded +sqtx1416 squareroot 4.6225E-24 -> 2.2E-12 Underflow Subnormal Inexact Rounded +sqtx1417 squareroot 5.0625E-24 -> 2.2E-12 Underflow Subnormal Inexact Rounded +sqtx1418 squareroot 5.5225E-24 -> 2.4E-12 Underflow Subnormal Inexact Rounded +sqtx1419 squareroot 6.0025E-24 -> 2.4E-12 Underflow Subnormal Inexact Rounded +sqtx1420 squareroot 6.5025E-24 -> 2.6E-12 Underflow Subnormal Inexact Rounded +sqtx1421 squareroot 7.0225E-24 -> 2.6E-12 Underflow Subnormal Inexact Rounded +sqtx1422 squareroot 7.5625E-24 -> 2.8E-12 Underflow Subnormal Inexact Rounded +sqtx1423 squareroot 8.1225E-24 -> 2.8E-12 Underflow Subnormal Inexact Rounded +sqtx1424 squareroot 8.7025E-24 -> 3.0E-12 Underflow Subnormal Inexact Rounded +sqtx1425 squareroot 9.3025E-24 -> 3.0E-12 Underflow Subnormal Inexact Rounded +sqtx1426 squareroot 9.9225E-24 -> 3.2E-12 Underflow Subnormal Inexact Rounded + +-- a random selection of values that Python2.5.1 rounds incorrectly +precision: 1 +sqtx1427 squareroot 227 -> 2E+1 Inexact Rounded +sqtx1428 squareroot 625 -> 2E+1 Inexact Rounded +sqtx1429 squareroot 1215 -> 3E+1 Inexact Rounded +sqtx1430 squareroot 2008 -> 4E+1 Inexact Rounded +sqtx1431 squareroot 2020 -> 4E+1 Inexact Rounded +sqtx1432 squareroot 2026 -> 5E+1 Inexact Rounded +sqtx1433 squareroot 2027 -> 5E+1 Inexact Rounded +sqtx1434 squareroot 2065 -> 5E+1 Inexact Rounded +sqtx1435 squareroot 2075 -> 5E+1 Inexact Rounded +sqtx1436 squareroot 2088 -> 5E+1 Inexact Rounded +sqtx1437 squareroot 3049 -> 6E+1 Inexact Rounded +sqtx1438 squareroot 3057 -> 6E+1 Inexact Rounded +sqtx1439 squareroot 3061 -> 6E+1 Inexact Rounded +sqtx1440 squareroot 3092 -> 6E+1 Inexact Rounded +sqtx1441 squareroot 4222 -> 6E+1 Inexact Rounded +sqtx1442 squareroot 5676 -> 8E+1 Inexact Rounded +sqtx1443 squareroot 5686 -> 8E+1 Inexact Rounded +sqtx1444 squareroot 7215 -> 8E+1 Inexact Rounded +sqtx1445 squareroot 9086 -> 1E+2 Inexact Rounded +sqtx1446 squareroot 9095 -> 1E+2 Inexact Rounded + +precision: 2 +sqtx1447 squareroot 1266 -> 36 Inexact Rounded +sqtx1448 squareroot 2552 -> 51 Inexact Rounded +sqtx1449 squareroot 5554 -> 75 Inexact Rounded +sqtx1450 squareroot 7832 -> 88 Inexact Rounded +sqtx1451 squareroot 13201 -> 1.1E+2 Inexact Rounded +sqtx1452 squareroot 15695 -> 1.3E+2 Inexact Rounded +sqtx1453 squareroot 18272 -> 1.4E+2 Inexact Rounded +sqtx1454 squareroot 21026 -> 1.5E+2 Inexact Rounded +sqtx1455 squareroot 24069 -> 1.6E+2 Inexact Rounded +sqtx1456 squareroot 34277 -> 1.9E+2 Inexact Rounded +sqtx1457 squareroot 46233 -> 2.2E+2 Inexact Rounded +sqtx1458 squareroot 46251 -> 2.2E+2 Inexact Rounded +sqtx1459 squareroot 46276 -> 2.2E+2 Inexact Rounded +sqtx1460 squareroot 70214 -> 2.6E+2 Inexact Rounded +sqtx1461 squareroot 81249 -> 2.9E+2 Inexact Rounded +sqtx1462 squareroot 81266 -> 2.9E+2 Inexact Rounded +sqtx1463 squareroot 93065 -> 3.1E+2 Inexact Rounded +sqtx1464 squareroot 93083 -> 3.1E+2 Inexact Rounded +sqtx1465 squareroot 99230 -> 3.2E+2 Inexact Rounded +sqtx1466 squareroot 99271 -> 3.2E+2 Inexact Rounded + +precision: 3 +sqtx1467 squareroot 11349 -> 107 Inexact Rounded +sqtx1468 squareroot 26738 -> 164 Inexact Rounded +sqtx1469 squareroot 31508 -> 178 Inexact Rounded +sqtx1470 squareroot 44734 -> 212 Inexact Rounded +sqtx1471 squareroot 44738 -> 212 Inexact Rounded +sqtx1472 squareroot 51307 -> 227 Inexact Rounded +sqtx1473 squareroot 62259 -> 250 Inexact Rounded +sqtx1474 squareroot 75901 -> 276 Inexact Rounded +sqtx1475 squareroot 76457 -> 277 Inexact Rounded +sqtx1476 squareroot 180287 -> 425 Inexact Rounded +sqtx1477 squareroot 202053 -> 450 Inexact Rounded +sqtx1478 squareroot 235747 -> 486 Inexact Rounded +sqtx1479 squareroot 256537 -> 506 Inexact Rounded +sqtx1480 squareroot 299772 -> 548 Inexact Rounded +sqtx1481 squareroot 415337 -> 644 Inexact Rounded +sqtx1482 squareroot 617067 -> 786 Inexact Rounded +sqtx1483 squareroot 628022 -> 792 Inexact Rounded +sqtx1484 squareroot 645629 -> 804 Inexact Rounded +sqtx1485 squareroot 785836 -> 886 Inexact Rounded +sqtx1486 squareroot 993066 -> 997 Inexact Rounded + +precision: 6 +sqtx1487 squareroot 14917781 -> 3862.35 Inexact Rounded +sqtx1488 squareroot 17237238 -> 4151.78 Inexact Rounded +sqtx1489 squareroot 18054463 -> 4249.05 Inexact Rounded +sqtx1490 squareroot 19990694 -> 4471.10 Inexact Rounded +sqtx1491 squareroot 29061855 -> 5390.90 Inexact Rounded +sqtx1492 squareroot 49166257 -> 7011.87 Inexact Rounded +sqtx1493 squareroot 53082086 -> 7285.75 Inexact Rounded +sqtx1494 squareroot 56787909 -> 7535.78 Inexact Rounded +sqtx1495 squareroot 81140019 -> 9007.78 Inexact Rounded +sqtx1496 squareroot 87977554 -> 9379.64 Inexact Rounded +sqtx1497 squareroot 93624683 -> 9675.98 Inexact Rounded +sqtx1498 squareroot 98732747 -> 9936.44 Inexact Rounded +sqtx1499 squareroot 99222813 -> 9961.06 Inexact Rounded +sqtx1500 squareroot 143883626 -> 11995.2 Inexact Rounded +sqtx1501 squareroot 180433301 -> 13432.5 Inexact Rounded +sqtx1502 squareroot 227034020 -> 15067.6 Inexact Rounded +sqtx1503 squareroot 283253992 -> 16830.2 Inexact Rounded +sqtx1504 squareroot 617047954 -> 24840.4 Inexact Rounded +sqtx1505 squareroot 736870094 -> 27145.4 Inexact Rounded +sqtx1506 squareroot 897322915 -> 29955.3 Inexact Rounded + +-- results close to minimum normal +precision: 1 +sqtx1507 squareroot 1E-20 -> 0E-9 Underflow Subnormal Inexact Rounded Clamped +sqtx1508 squareroot 1E-19 -> 0E-9 Underflow Subnormal Inexact Rounded Clamped +sqtx1509 squareroot 1E-18 -> 1E-9 + +precision: 2 +sqtx1510 squareroot 8.1E-19 -> 9E-10 Subnormal +sqtx1511 squareroot 8.10E-19 -> 9E-10 Subnormal Rounded +sqtx1512 squareroot 9.0E-19 -> 9E-10 Underflow Subnormal Inexact Rounded +sqtx1513 squareroot 9.02E-19 -> 9E-10 Underflow Subnormal Inexact Rounded +sqtx1514 squareroot 9.03E-19 -> 1.0E-9 Underflow Subnormal Inexact Rounded +sqtx1515 squareroot 9.1E-19 -> 1.0E-9 Underflow Subnormal Inexact Rounded +sqtx1516 squareroot 9.9E-19 -> 1.0E-9 Underflow Subnormal Inexact Rounded +sqtx1517 squareroot 9.91E-19 -> 1.0E-9 Underflow Subnormal Inexact Rounded +sqtx1518 squareroot 9.92E-19 -> 1.0E-9 Underflow Subnormal Inexact Rounded +sqtx1519 squareroot 9.95E-19 -> 1.0E-9 Underflow Subnormal Inexact Rounded +sqtx1520 squareroot 9.98E-19 -> 1.0E-9 Underflow Subnormal Inexact Rounded +sqtx1521 squareroot 9.99E-19 -> 1.0E-9 Underflow Subnormal Inexact Rounded +sqtx1522 squareroot 1E-18 -> 1E-9 +sqtx1523 squareroot 1.0E-18 -> 1.0E-9 +sqtx1524 squareroot 1.00E-18 -> 1.0E-9 +sqtx1525 squareroot 1.000E-18 -> 1.0E-9 Rounded +sqtx1526 squareroot 1.0000E-18 -> 1.0E-9 Rounded +sqtx1527 squareroot 1.01E-18 -> 1.0E-9 Inexact Rounded +sqtx1528 squareroot 1.02E-18 -> 1.0E-9 Inexact Rounded +sqtx1529 squareroot 1.1E-18 -> 1.0E-9 Inexact Rounded + +precision: 3 +sqtx1530 squareroot 8.1E-19 -> 9E-10 Subnormal +sqtx1531 squareroot 8.10E-19 -> 9.0E-10 Subnormal +sqtx1532 squareroot 8.100E-19 -> 9.0E-10 Subnormal +sqtx1533 squareroot 8.1000E-19 -> 9.0E-10 Subnormal Rounded +sqtx1534 squareroot 9.9E-19 -> 9.9E-10 Underflow Subnormal Inexact Rounded +sqtx1535 squareroot 9.91E-19 -> 1.00E-9 Underflow Subnormal Inexact Rounded +sqtx1536 squareroot 9.99E-19 -> 1.00E-9 Underflow Subnormal Inexact Rounded +sqtx1537 squareroot 9.998E-19 -> 1.00E-9 Underflow Subnormal Inexact Rounded +sqtx1538 squareroot 1E-18 -> 1E-9 +sqtx1539 squareroot 1.0E-18 -> 1.0E-9 +sqtx1540 squareroot 1.00E-18 -> 1.0E-9 +sqtx1541 squareroot 1.000E-18 -> 1.00E-9 +sqtx1542 squareroot 1.0000E-18 -> 1.00E-9 +sqtx1543 squareroot 1.00000E-18 -> 1.00E-9 Rounded +sqtx1544 squareroot 1.000000E-18 -> 1.00E-9 Rounded +sqtx1545 squareroot 1.01E-18 -> 1.00E-9 Inexact Rounded +sqtx1546 squareroot 1.02E-18 -> 1.01E-9 Inexact Rounded + +-- result exactly representable with precision p, but not necessarily +-- exactly representable as a subnormal; check the correct flags are raised +precision: 2 +sqtx1547 squareroot 1.21E-20 -> 1E-10 Underflow Subnormal Inexact Rounded +sqtx1548 squareroot 1.44E-20 -> 1E-10 Underflow Subnormal Inexact Rounded +sqtx1549 squareroot 9.61E-20 -> 3E-10 Underflow Subnormal Inexact Rounded +sqtx1550 squareroot 8.836E-19 -> 9E-10 Underflow Subnormal Inexact Rounded +sqtx1551 squareroot 9.216E-19 -> 1.0E-9 Underflow Subnormal Inexact Rounded + +precision: 3 +sqtx1552 squareroot 1.21E-22 -> 1E-11 Underflow Subnormal Inexact Rounded +sqtx1553 squareroot 1.21E-20 -> 1.1E-10 Subnormal +sqtx1554 squareroot 1.96E-22 -> 1E-11 Underflow Subnormal Inexact Rounded +sqtx1555 squareroot 1.96E-20 -> 1.4E-10 Subnormal +sqtx1556 squareroot 2.56E-22 -> 2E-11 Underflow Subnormal Inexact Rounded +sqtx1557 squareroot 4.00E-22 -> 2E-11 Subnormal Rounded +sqtx1558 squareroot 7.84E-22 -> 3E-11 Underflow Subnormal Inexact Rounded +sqtx1559 squareroot 9.801E-21 -> 1.0E-10 Underflow Subnormal Inexact Rounded +sqtx1560 squareroot 9.801E-19 -> 9.9E-10 Subnormal +sqtx1561 squareroot 1.0201E-20 -> 1.0E-10 Underflow Subnormal Inexact Rounded +sqtx1562 squareroot 1.1025E-20 -> 1.0E-10 Underflow Subnormal Inexact Rounded +sqtx1563 squareroot 1.1236E-20 -> 1.1E-10 Underflow Subnormal Inexact Rounded +sqtx1564 squareroot 1.2996E-20 -> 1.1E-10 Underflow Subnormal Inexact Rounded +sqtx1565 squareroot 1.3225E-20 -> 1.2E-10 Underflow Subnormal Inexact Rounded + +-- A selection of subnormal results prone to double rounding errors +precision: 2 +sqtx1566 squareroot 2.3E-21 -> 0E-10 Underflow Subnormal Inexact Rounded Clamped +sqtx1567 squareroot 2.4E-21 -> 0E-10 Underflow Subnormal Inexact Rounded Clamped +sqtx1568 squareroot 2.5E-21 -> 0E-10 Underflow Subnormal Inexact Rounded Clamped +sqtx1569 squareroot 2.6E-21 -> 1E-10 Underflow Subnormal Inexact Rounded +sqtx1570 squareroot 2.7E-21 -> 1E-10 Underflow Subnormal Inexact Rounded +sqtx1571 squareroot 2.8E-21 -> 1E-10 Underflow Subnormal Inexact Rounded +sqtx1572 squareroot 2.2E-20 -> 1E-10 Underflow Subnormal Inexact Rounded +sqtx1573 squareroot 2.3E-20 -> 2E-10 Underflow Subnormal Inexact Rounded +sqtx1574 squareroot 2.4E-20 -> 2E-10 Underflow Subnormal Inexact Rounded +sqtx1575 squareroot 6.2E-20 -> 2E-10 Underflow Subnormal Inexact Rounded +sqtx1576 squareroot 6.3E-20 -> 3E-10 Underflow Subnormal Inexact Rounded +sqtx1577 squareroot 6.4E-20 -> 3E-10 Underflow Subnormal Inexact Rounded +sqtx1578 squareroot 6.5E-20 -> 3E-10 Underflow Subnormal Inexact Rounded +sqtx1579 squareroot 1.2E-19 -> 3E-10 Underflow Subnormal Inexact Rounded +sqtx1580 squareroot 2.0E-19 -> 4E-10 Underflow Subnormal Inexact Rounded +sqtx1581 squareroot 4.2E-19 -> 6E-10 Underflow Subnormal Inexact Rounded +sqtx1582 squareroot 5.6E-19 -> 7E-10 Underflow Subnormal Inexact Rounded +sqtx1583 squareroot 5.7E-19 -> 8E-10 Underflow Subnormal Inexact Rounded +sqtx1584 squareroot 9.0E-19 -> 9E-10 Underflow Subnormal Inexact Rounded +sqtx1585 squareroot 9.1E-19 -> 1.0E-9 Underflow Subnormal Inexact Rounded +precision: 3 +sqtx1586 squareroot 2.6E-23 -> 1E-11 Underflow Subnormal Inexact Rounded +sqtx1587 squareroot 2.22E-22 -> 1E-11 Underflow Subnormal Inexact Rounded +sqtx1588 squareroot 6.07E-22 -> 2E-11 Underflow Subnormal Inexact Rounded +sqtx1589 squareroot 6.25E-22 -> 2E-11 Underflow Subnormal Inexact Rounded +sqtx1590 squareroot 6.45E-22 -> 3E-11 Underflow Subnormal Inexact Rounded +sqtx1591 squareroot 6.50E-22 -> 3E-11 Underflow Subnormal Inexact Rounded +sqtx1592 squareroot 1.22E-21 -> 3E-11 Underflow Subnormal Inexact Rounded +sqtx1593 squareroot 1.24E-21 -> 4E-11 Underflow Subnormal Inexact Rounded +sqtx1594 squareroot 4.18E-21 -> 6E-11 Underflow Subnormal Inexact Rounded +sqtx1595 squareroot 7.19E-21 -> 8E-11 Underflow Subnormal Inexact Rounded +sqtx1596 squareroot 8.94E-21 -> 9E-11 Underflow Subnormal Inexact Rounded +sqtx1597 squareroot 1.81E-20 -> 1.3E-10 Underflow Subnormal Inexact Rounded +sqtx1598 squareroot 4.64E-20 -> 2.2E-10 Underflow Subnormal Inexact Rounded +sqtx1599 squareroot 5.06E-20 -> 2.2E-10 Underflow Subnormal Inexact Rounded +sqtx1600 squareroot 5.08E-20 -> 2.3E-10 Underflow Subnormal Inexact Rounded +sqtx1601 squareroot 7.00E-20 -> 2.6E-10 Underflow Subnormal Inexact Rounded +sqtx1602 squareroot 1.81E-19 -> 4.3E-10 Underflow Subnormal Inexact Rounded +sqtx1603 squareroot 6.64E-19 -> 8.1E-10 Underflow Subnormal Inexact Rounded +sqtx1604 squareroot 7.48E-19 -> 8.6E-10 Underflow Subnormal Inexact Rounded +sqtx1605 squareroot 9.91E-19 -> 1.00E-9 Underflow Subnormal Inexact Rounded +precision: 4 +sqtx1606 squareroot 6.24E-24 -> 2E-12 Underflow Subnormal Inexact Rounded +sqtx1607 squareroot 7.162E-23 -> 8E-12 Underflow Subnormal Inexact Rounded +sqtx1608 squareroot 7.243E-23 -> 9E-12 Underflow Subnormal Inexact Rounded +sqtx1609 squareroot 8.961E-23 -> 9E-12 Underflow Subnormal Inexact Rounded +sqtx1610 squareroot 9.029E-23 -> 1.0E-11 Underflow Subnormal Inexact Rounded +sqtx1611 squareroot 4.624E-22 -> 2.2E-11 Underflow Subnormal Inexact Rounded +sqtx1612 squareroot 5.980E-22 -> 2.4E-11 Underflow Subnormal Inexact Rounded +sqtx1613 squareroot 6.507E-22 -> 2.6E-11 Underflow Subnormal Inexact Rounded +sqtx1614 squareroot 1.483E-21 -> 3.9E-11 Underflow Subnormal Inexact Rounded +sqtx1615 squareroot 3.903E-21 -> 6.2E-11 Underflow Subnormal Inexact Rounded +sqtx1616 squareroot 8.733E-21 -> 9.3E-11 Underflow Subnormal Inexact Rounded +sqtx1617 squareroot 1.781E-20 -> 1.33E-10 Underflow Subnormal Inexact Rounded +sqtx1618 squareroot 6.426E-20 -> 2.53E-10 Underflow Subnormal Inexact Rounded +sqtx1619 squareroot 7.102E-20 -> 2.66E-10 Underflow Subnormal Inexact Rounded +sqtx1620 squareroot 7.535E-20 -> 2.74E-10 Underflow Subnormal Inexact Rounded +sqtx1621 squareroot 9.892E-20 -> 3.15E-10 Underflow Subnormal Inexact Rounded +sqtx1622 squareroot 1.612E-19 -> 4.01E-10 Underflow Subnormal Inexact Rounded +sqtx1623 squareroot 1.726E-19 -> 4.15E-10 Underflow Subnormal Inexact Rounded +sqtx1624 squareroot 1.853E-19 -> 4.30E-10 Underflow Subnormal Inexact Rounded +sqtx1625 squareroot 4.245E-19 -> 6.52E-10 Underflow Subnormal Inexact Rounded + +-- clamping and overflow for large exponents +precision: 1 +sqtx1626 squareroot 1E+18 -> 1E+9 +sqtx1627 squareroot 1E+19 -> 3E+9 Inexact Rounded +sqtx1628 squareroot 9E+19 -> 9E+9 Inexact Rounded +sqtx1629 squareroot 9.1E+19 -> Infinity Overflow Inexact Rounded +sqtx1630 squareroot 1E+20 -> Infinity Overflow Inexact Rounded + +precision: 2 +sqtx1631 squareroot 1E+18 -> 1E+9 +sqtx1632 squareroot 1.0E+18 -> 1.0E+9 +sqtx1633 squareroot 1.00E+18 -> 1.0E+9 +sqtx1634 squareroot 1.000E+18 -> 1.0E+9 Rounded +sqtx1635 squareroot 1E+20 -> Infinity Overflow Inexact Rounded +clamp: 1 +sqtx1636 squareroot 1E+18 -> 1.0E+9 Clamped +sqtx1637 squareroot 1.0E+18 -> 1.0E+9 +sqtx1638 squareroot 1E+20 -> Infinity Overflow Inexact Rounded +clamp: 0 + +precision: 6 +sqtx1639 squareroot 1E+18 -> 1E+9 +sqtx1640 squareroot 1.0000000000E+18 -> 1.00000E+9 +sqtx1641 squareroot 1.00000000000E+18 -> 1.00000E+9 Rounded +sqtx1642 squareroot 1E+20 -> Infinity Overflow Inexact Rounded +clamp: 1 +sqtx1643 squareroot 1E+8 -> 1E+4 +sqtx1644 squareroot 1E+10 -> 1.0E+5 Clamped +sqtx1645 squareroot 1.0E+10 -> 1.0E+5 +sqtx1646 squareroot 1E+12 -> 1.00E+6 Clamped +sqtx1647 squareroot 1.0E+12 -> 1.00E+6 Clamped +sqtx1648 squareroot 1.00E+12 -> 1.00E+6 Clamped +sqtx1649 squareroot 1.000E+12 -> 1.00E+6 +sqtx1650 squareroot 1E+18 -> 1.00000E+9 Clamped +sqtx1651 squareroot 1.00000000E+18 -> 1.00000E+9 Clamped +sqtx1652 squareroot 1.000000000E+18 -> 1.00000E+9 +sqtx1653 squareroot 1E+20 -> Infinity Overflow Inexact Rounded +clamp: 0 + +-- The following example causes a TypeError in Python 2.5.1 +precision: 3 +maxexponent: 9 +minexponent: -9 +sqtx1654 squareroot 10000000000 -> 1.00E+5 Rounded + + +-- Some additional edge cases +precision: 2 +sqtx2000 squareroot 9980.01 -> 1.0E+2 Inexact Rounded +precision: 3 +sqtx2001 squareroot 9980.01 -> 99.9 +precision: 4 +sqtx2002 squareroot 9980.01 -> 99.9 + +-- Exact from over-precise +precision: 4 +sqtx2003 squareroot 11025 -> 105 +precision: 3 +sqtx2004 squareroot 11025 -> 105 +precision: 2 +sqtx2005 squareroot 11025 -> 1.0E+2 Inexact Rounded +precision: 1 +sqtx2006 squareroot 11025 -> 1E+2 Inexact Rounded + +-- Out-of-bounds zeros +precision: 4 +sqtx2010 squareroot 0E-9 -> 0.00000 +sqtx2011 squareroot 0E-10 -> 0.00000 +sqtx2012 squareroot 0E-11 -> 0.000000 +sqtx2013 squareroot 0E-12 -> 0.000000 +sqtx2014 squareroot 0E-13 -> 0E-7 +sqtx2015 squareroot 0E-14 -> 0E-7 +sqtx2020 squareroot 0E-17 -> 0E-9 +sqtx2021 squareroot 0E-20 -> 0E-10 +sqtx2022 squareroot 0E-22 -> 0E-11 +sqtx2023 squareroot 0E-24 -> 0E-12 +sqtx2024 squareroot 0E-25 -> 0E-12 Clamped +sqtx2025 squareroot 0E-26 -> 0E-12 Clamped +sqtx2026 squareroot 0E-27 -> 0E-12 Clamped +sqtx2027 squareroot 0E-28 -> 0E-12 Clamped + +sqtx2030 squareroot 0E+8 -> 0E+4 +sqtx2031 squareroot 0E+10 -> 0E+5 +sqtx2032 squareroot 0E+12 -> 0E+6 +sqtx2033 squareroot 0E+14 -> 0E+7 +sqtx2034 squareroot 0E+15 -> 0E+7 +sqtx2035 squareroot 0E+16 -> 0E+8 +sqtx2036 squareroot 0E+18 -> 0E+9 +sqtx2037 squareroot 0E+19 -> 0E+9 +sqtx2038 squareroot 0E+20 -> 0E+9 Clamped +sqtx2039 squareroot 0E+21 -> 0E+9 Clamped +sqtx2040 squareroot 0E+22 -> 0E+9 Clamped + From python-checkins at python.org Thu Aug 2 04:17:55 2007 From: python-checkins at python.org (facundo.batista) Date: Thu, 2 Aug 2007 04:17:55 +0200 (CEST) Subject: [Python-checkins] r56656 - python/branches/decimal-branch/Lib/decimal.py Message-ID: <20070802021755.138AF1E4003@bag.python.org> Author: facundo.batista Date: Thu Aug 2 04:17:54 2007 New Revision: 56656 Modified: python/branches/decimal-branch/Lib/decimal.py Log: sqrt() function was written brand new, now is around 10x faster and does not have some subtle errors. Also _fixexponents() was, well, fixed for small details. Thanks Mark Dickinson. Modified: python/branches/decimal-branch/Lib/decimal.py ============================================================================== --- python/branches/decimal-branch/Lib/decimal.py (original) +++ python/branches/decimal-branch/Lib/decimal.py Thu Aug 2 04:17:54 2007 @@ -1559,46 +1559,58 @@ """Fix the exponents and return a copy with the exponent in bounds. Only call if known to not be a special value. """ - folddown = context._clamp - Emin = context.Emin + ans = self - ans_adjusted = ans.adjusted() - if ans_adjusted < Emin: + # deal with zeros first + if not ans: Etiny = context.Etiny() if ans._exp < Etiny: - if not ans: + ans = Decimal(self) + ans._exp = Etiny + context._raise_error(Clamped) + else: + if context._clamp: + exp_max = context.Etop() + else: + exp_max = context.Emax + if ans._exp > exp_max: ans = Decimal(self) - ans._exp = Etiny - context._raise_error(Clamped) - return ans - ans = ans._rescale(Etiny, context=context) - # It isn't zero, and exp < Emin => subnormal - context._raise_error(Subnormal) - if not ans: + ans._exp = exp_max context._raise_error(Clamped) - if context.flags[Inexact]: - context._raise_error(Underflow) - else: - if ans: - # Only raise subnormal if non-zero. - context._raise_error(Subnormal) - else: + return ans + + # self is nonzero; if adjusted exponent is > Emax, overflow + ans_adjusted = ans.adjusted() + if ans_adjusted > context.Emax: + context._raise_error(Inexact) + context._raise_error(Rounded) + c = context._raise_error(Overflow, 'above Emax', ans._sign) + return c + + # Now check for subnormal results, and for the need to fold + # down. These two conditions are *not* mutually + # exclusive---when the precision is large and Emin and Emax + # are small it's quite possible to have Emin > Etop. + # (Actually, the specification requires Emin and Emax to be at + # least 5*precision, so this shouldn't happen, but it never + # hurts to be careful.) + if context._clamp: Etop = context.Etop() - if folddown and ans._exp > Etop: + if ans._exp > Etop: context._raise_error(Clamped) ans = ans._rescale(Etop, context=context) - else: - Emax = context.Emax - if ans_adjusted > Emax: + + if ans_adjusted < context.Emin: + context._raise_error(Subnormal) + Etiny = context.Etiny() + if ans._exp < Etiny: + ans_before_rescale = ans + ans = ans._rescale(Etiny, context=context) + if ans != ans_before_rescale: + context._raise_error(Underflow) if not ans: - ans = Decimal(self) - ans._exp = Emax context._raise_error(Clamped) - return ans - context._raise_error(Inexact) - context._raise_error(Rounded) - c = context._raise_error(Overflow, 'above Emax', ans._sign) - return c + return ans def _round(self, prec=None, rounding=None, context=None, forceExp=None, fromQuantize=False): @@ -2068,11 +2080,7 @@ to_integral = to_integral_value def sqrt(self, context=None): - """Return the square root of self. - - Uses a converging algorithm (Xn+1 = 0.5*(Xn + self / Xn)) - Should quadratically approach the right answer. - """ + """Return the square root of self.""" if self._is_special: ans = self._check_nans(context=context) if ans: @@ -2082,16 +2090,9 @@ return Decimal(self) if not self: - # exponent = self._exp / 2, using round_down. - # if self._exp < 0: - # exp = (self._exp+1) // 2 - # else: - exp = (self._exp) // 2 - if self._sign == 1: - # sqrt(-0) = -0 - return Decimal( (1, (0,), exp)) - else: - return Decimal( (0, (0,), exp)) + # exponent = self._exp // 2. sqrt(-0) = -0 + ans = Decimal((self._sign, (0,), self._exp // 2)) + return ans._fix(context) if context is None: context = getcontext() @@ -2099,94 +2100,83 @@ if self._sign == 1: return context._raise_error(InvalidOperation, 'sqrt(-x), x > 0') - tmp = Decimal(self) - - expadd = tmp._exp // 2 - if tmp._exp & 1: - tmp._int += (0,) - tmp._exp = 0 - else: - tmp._exp = 0 - - context = context._shallow_copy() - flags = context._ignore_all_flags() - firstprec = context.prec - context.prec = 3 - if tmp.adjusted() & 1 == 0: - ans = Decimal( (0, (8,1,9), tmp.adjusted() - 2) ) - ans = ans.__add__(tmp.__mul__(Decimal((0, (2,5,9), -2)), - context=context), context=context) - ans._exp -= 1 + tmp.adjusted() // 2 - else: - ans = Decimal( (0, (2,5,9), tmp._exp + len(tmp._int)- 3) ) - ans = ans.__add__(tmp.__mul__(Decimal((0, (8,1,9), -3)), - context=context), context=context) - ans._exp -= 1 + tmp.adjusted() // 2 - - # ans is now a linear approximation. - Emax, Emin = context.Emax, context.Emin - context.Emax, context.Emin = DefaultContext.Emax, DefaultContext.Emin - - half = Decimal('0.5') - - maxp = firstprec + 2 - rounding = context._set_rounding(ROUND_HALF_EVEN) - while 1: - context.prec = min(2*context.prec - 2, maxp) - ans = half.__mul__(ans.__add__(tmp.__div__(ans, context=context), - context=context), context=context) - if context.prec == maxp: + # At this point self represents a positive number. Let p be + # the desired precision and express self in the form c*100**e + # with c a positive real number and e an integer, c and e + # being chosen so that 100**(p-1) <= c < 100**p. Then the + # (exact) square root of self is sqrt(c)*10**e, and 10**(p-1) + # <= sqrt(c) < 10**p, so the closest representable Decimal at + # precision p is n*10**e where n = round_half_even(sqrt(c)), + # the closest integer to sqrt(c) with the even integer chosen + # in the case of a tie. + # + # To ensure correct rounding in all cases, we use the + # following trick: we compute the square root to an extra + # place (precision p+1 instead of precision p), rounding down. + # Then, if the result is inexact and its last digit is 0 or 5, + # we increase the last digit to 1 or 6 respectively; if it's + # exact we leave the last digit alone. Now the final round to + # p places (or fewer in the case of underflow) will round + # correctly and raise the appropriate flags. + + # use an extra digit of precision + prec = context.prec+1 + + # write argument in the form c*100**e where e = self._exp//2 + # is the 'ideal' exponent, to be used if the square root is + # exactly representable. l is the number of 'digits' of c in + # base 100, so that 100**(l-1) <= c < 100**l. + op = _WorkRep(self) + e = op.exp >> 1 + if op.exp & 1: + c = op.int * 10 + l = (len(self._int) >> 1) + 1 + else: + c = op.int + l = len(self._int)+1 >> 1 + + # rescale so that c has exactly prec base 100 'digits' + shift = prec-l + if shift >= 0: + c *= 100**shift + exact = True + else: + c, remainder = divmod(c, 100**-shift) + exact = not remainder + e -= shift + + # find n = floor(sqrt(c)) using Newton's method + n = 10**prec + while True: + q = c//n + if n <= q: break + else: + n = n + q >> 1 + exact = exact and n*n == c - # Round to the answer's precision-- the only error can be 1 ulp. - context.prec = firstprec - prevexp = ans.adjusted() - ans = ans._round(context=context) - - # Now, check if the other last digits are better. - context.prec = firstprec + 1 - # In case we rounded up another digit and we should actually go lower. - if prevexp != ans.adjusted(): - ans._int += (0,) - ans._exp -= 1 - - - lower = ans.__sub__(Decimal((0, (5,), ans._exp-1)), context=context) - context._set_rounding(ROUND_UP) - if lower.__mul__(lower, context=context) > (tmp): - ans = ans.__sub__(Decimal((0, (1,), ans._exp)), context=context) - + if exact: + # result is exact; rescale to use ideal exponent e + if shift >= 0: + # assert n % 10**shift == 0 + n //= 10**shift + else: + n *= 10**-shift + e += shift else: - upper = ans.__add__(Decimal((0, (5,), ans._exp-1)),context=context) - context._set_rounding(ROUND_DOWN) - if upper.__mul__(upper, context=context) < tmp: - ans = ans.__add__(Decimal((0, (1,), ans._exp)),context=context) + # result is not exact; fix last digit as described above + if n % 5 == 0: + n += 1 - ans._exp += expadd + ans = Decimal((0, map(int, str(n)), e)) - context.prec = firstprec - context.rounding = rounding + # round, and fit to current context + context = context._shallow_copy() + rounding = context._set_rounding(ROUND_HALF_EVEN) ans = ans._fix(context) + context.rounding = rounding - rounding = context._set_rounding_decision(NEVER_ROUND) - if not ans.__mul__(ans, context=context) == self: - # Only rounded/inexact if here. - context._regard_flags(flags) - context._raise_error(Rounded) - context._raise_error(Inexact) - else: - # Exact answer, so let's set the exponent right. - # if self._exp < 0: - # exp = (self._exp +1)// 2 - # else: - exp = self._exp // 2 - context.prec += ans._exp - exp - ans = ans._rescale(exp, context=context) - context.prec = firstprec - context._regard_flags(flags) - context.Emax, context.Emin = Emax, Emin - - return ans._fix(context) + return ans def max(self, other, context=None): """Returns the larger value. From python-checkins at python.org Thu Aug 2 05:18:47 2007 From: python-checkins at python.org (brett.cannon) Date: Thu, 2 Aug 2007 05:18:47 +0200 (CEST) Subject: [Python-checkins] r56657 - sandbox/trunk/import_in_py/_importlib.py sandbox/trunk/import_in_py/importlib.py Message-ID: <20070802031847.DB6471E4003@bag.python.org> Author: brett.cannon Date: Thu Aug 2 05:18:47 2007 New Revision: 56657 Modified: sandbox/trunk/import_in_py/_importlib.py sandbox/trunk/import_in_py/importlib.py Log: Change name of module used for posix stuff to _os instead of 'posix' as the name varies depending on what platform you are using. Modified: sandbox/trunk/import_in_py/_importlib.py ============================================================================== --- sandbox/trunk/import_in_py/_importlib.py (original) +++ sandbox/trunk/import_in_py/_importlib.py Thu Aug 2 05:18:47 2007 @@ -58,7 +58,8 @@ """ from __future__ import with_statement -# The injected modules are 'imp', 'sys', 'marshal', 'posix' (aka 'nt' & 'os2'). +# The injected modules are 'imp', 'sys', 'marshal', and '_os' (a.k.a. 'posix', +# 'nt' & 'os2'). # XXX Could also expose Modules/getpath.c:joinpath() def _path_join(*args): @@ -68,7 +69,7 @@ def _path_exists(path): """Replacement for os.path.exists to help remove dependency on 'os'.""" try: - posix.stat(path) + _os.stat(path) except OSError: return False else: @@ -78,7 +79,7 @@ def _path_is_mode_type(path, mode): """Test whether the path is the specified mode type.""" try: - stat_info = posix.stat(path) + stat_info = _os.stat(path) except OSError: return False return (stat_info.st_mode & 0170000) == mode @@ -96,12 +97,12 @@ def _path_absolute(path): """Replacement for os.path.abspath.""" try: - return posix._getfullpathname(path) + return _os._getfullpathname(path) except AttributeError: if path.startswith('/'): return path else: - return _path_join(posix.getcwd(), path) + return _path_join(_os.getcwd(), path) class _BuiltinFrozenBaseImporter(object): @@ -300,7 +301,7 @@ PyPycHandler. """ - return int(posix.stat(path).st_mtime) + return int(_os.stat(path).st_mtime) def split_path(self, path): """Split the specified path into a base path and the type of the Modified: sandbox/trunk/import_in_py/importlib.py ============================================================================== --- sandbox/trunk/import_in_py/importlib.py (original) +++ sandbox/trunk/import_in_py/importlib.py Thu Aug 2 05:18:47 2007 @@ -105,16 +105,16 @@ _importlib.sys = sys _importlib.marshal = marshal try: - import posix + import posix as _os except ImportError: try: - import nt as posix + import nt as _os except ImportError: try: - import os2 as posix + import os2 as _os except ImportError: raise ImportError('posix, nt, or os2 required for importlib') -_importlib.posix = posix +_importlib._os = _os # XXX These all need to either go away or become built-in modules # (Neal). From python-checkins at python.org Thu Aug 2 05:22:20 2007 From: python-checkins at python.org (brett.cannon) Date: Thu, 2 Aug 2007 05:22:20 +0200 (CEST) Subject: [Python-checkins] r56658 - sandbox/trunk/import_in_py/importlib.py Message-ID: <20070802032220.444291E4003@bag.python.org> Author: brett.cannon Date: Thu Aug 2 05:22:19 2007 New Revision: 56658 Modified: sandbox/trunk/import_in_py/importlib.py Log: Reorganize stuff to make it more clear what is left to be done. Modified: sandbox/trunk/import_in_py/importlib.py ============================================================================== --- sandbox/trunk/import_in_py/importlib.py (original) +++ sandbox/trunk/import_in_py/importlib.py Thu Aug 2 05:22:19 2007 @@ -100,10 +100,6 @@ # Required built-in modules. -import imp, sys, marshal -_importlib.imp = imp -_importlib.sys = sys -_importlib.marshal = marshal try: import posix as _os except ImportError: @@ -113,8 +109,13 @@ try: import os2 as _os except ImportError: - raise ImportError('posix, nt, or os2 required for importlib') + raise ImportError('posix, nt, or os2 module required for importlib') _importlib._os = _os +import imp, sys, marshal +_importlib.imp = imp +_importlib.sys = sys +_importlib.marshal = marshal + # XXX These all need to either go away or become built-in modules # (Neal). @@ -125,7 +126,8 @@ _importlib._r_long = _r_long #XXX Expose original from marshal. _importlib._w_long = _w_long #XXX Expose original from marshal. _importlib._case_ok = _case_ok #XXX Expose original from imp. -_importlib.path_sep = sep # For os.path.join replacement. +# For os.path.join replacement; pull from Include/osdefs.h:SEP . +_importlib.path_sep = sep # For allowing silent failure of .pyc creation when permission is denied. _importlib.EACCES = EACCES From python-checkins at python.org Thu Aug 2 10:24:23 2007 From: python-checkins at python.org (georg.brandl) Date: Thu, 2 Aug 2007 10:24:23 +0200 (CEST) Subject: [Python-checkins] r56660 - doctools/trunk/sphinx/__init__.py Message-ID: <20070802082423.65E7A1E4008@bag.python.org> Author: georg.brandl Date: Thu Aug 2 10:24:23 2007 New Revision: 56660 Modified: doctools/trunk/sphinx/__init__.py Log: Don't color output if stdout is not a tty. Modified: doctools/trunk/sphinx/__init__.py ============================================================================== --- doctools/trunk/sphinx/__init__.py (original) +++ doctools/trunk/sphinx/__init__.py Thu Aug 2 10:24:23 2007 @@ -99,7 +99,7 @@ elif opt == '-N': nocolor() - if sys.platform == 'win32': + if not sys.stdout.isatty() or sys.platform == 'win32': # Windows' cmd box doesn't understand ANSI sequences nocolor() From python-checkins at python.org Thu Aug 2 10:54:18 2007 From: python-checkins at python.org (georg.brandl) Date: Thu, 2 Aug 2007 10:54:18 +0200 (CEST) Subject: [Python-checkins] r56661 - in doctools/trunk: TODO converter/filenamemap.py converter/newfiles/conf.py converter/newfiles/contents.rst converter/newfiles/mac_index.rst converter/newfiles/modules_index.rst converter/newfiles/ref_index.rst sphinx/builder.py sphinx/style/searchtools.js sphinx/templates/index.html sphinx/templates/keyword_not_found.html sphinx/templates/search.html sphinx/web/application.py sphinx/web/oldurls.py Message-ID: <20070802085418.6B0F31E4003@bag.python.org> Author: georg.brandl Date: Thu Aug 2 10:54:17 2007 New Revision: 56661 Modified: doctools/trunk/TODO doctools/trunk/converter/filenamemap.py doctools/trunk/converter/newfiles/conf.py doctools/trunk/converter/newfiles/contents.rst doctools/trunk/converter/newfiles/mac_index.rst doctools/trunk/converter/newfiles/modules_index.rst doctools/trunk/converter/newfiles/ref_index.rst doctools/trunk/sphinx/builder.py doctools/trunk/sphinx/style/searchtools.js doctools/trunk/sphinx/templates/index.html doctools/trunk/sphinx/templates/keyword_not_found.html doctools/trunk/sphinx/templates/search.html doctools/trunk/sphinx/web/application.py doctools/trunk/sphinx/web/oldurls.py Log: Rename modules -> library, macmodules -> maclib. Use current version in index page whatsnew link. Modified: doctools/trunk/TODO ============================================================================== --- doctools/trunk/TODO (original) +++ doctools/trunk/TODO Thu Aug 2 10:54:17 2007 @@ -5,7 +5,6 @@ - discuss and debug comments system - write new Makefile, handle automatic checkout - write a "printable" builder (export to latex, most probably) -- discuss lib -> ref section move - prepare for databases other than sqlite for comments - look at the old tools/ scripts, what functionality should be rewritten - add search via Xapian? Modified: doctools/trunk/converter/filenamemap.py ============================================================================== --- doctools/trunk/converter/filenamemap.py (original) +++ doctools/trunk/converter/filenamemap.py Thu Aug 2 10:54:17 2007 @@ -12,7 +12,7 @@ _mapping = { 'lib': { - '__newname__' : 'modules', + '__newname__' : 'library', 'asttable': '', 'compiler': '', @@ -271,12 +271,11 @@ 'libundoc': '', 'libintro': '', - # -> ref - 'libconsts': 'reference/consts', - 'libexcs': 'reference/exceptions', - 'libfuncs': 'reference/functions', - 'libobjs': 'reference/objects', - 'libstdtypes': 'reference/stdtypes', + 'libconsts': 'constants', + 'libexcs': 'exceptions', + 'libfuncs': 'functions', + 'libobjs': 'objects', + 'libstdtypes': 'stdtypes', # mainfiles 'lib': None, @@ -374,7 +373,7 @@ }, 'mac': { - '__newname__': 'macmodules', + '__newname__': 'maclib', 'mac': None, 'libaepack': 'aepack', @@ -413,6 +412,7 @@ 'whatsnew24': '2.4', 'whatsnew25': '2.5', 'whatsnew26': '2.6', + 'whatsnew30': '3.0', }, 'commontex': { @@ -449,8 +449,8 @@ 'includes', 'includes/sqlite3', 'install', - 'macmodules', - 'modules', + 'maclib', + 'library', 'reference', 'tutorial', 'whatsnew', @@ -482,8 +482,8 @@ 'ref_index.rst': 'reference/index.rst', 'tutorial_index.rst': 'tutorial/index.rst', - 'modules_index.rst': 'modules/index.rst', - 'mac_index.rst': 'macmodules/index.rst', + 'modules_index.rst': 'library/index.rst', + 'mac_index.rst': 'maclib/index.rst', 'ext_index.rst': 'extending/index.rst', 'api_index.rst': 'c-api/index.rst', 'dist_index.rst': 'distutils/index.rst', Modified: doctools/trunk/converter/newfiles/conf.py ============================================================================== --- doctools/trunk/converter/newfiles/conf.py (original) +++ doctools/trunk/converter/newfiles/conf.py Thu Aug 2 10:54:17 2007 @@ -31,8 +31,8 @@ 'whatsnew/2.3.rst', 'whatsnew/2.4.rst', 'whatsnew/2.5.rst', - 'macmodules/scrap.rst', - 'modules/xmllib.rst', + 'maclib/scrap.rst', + 'library/xmllib.rst', ] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, Modified: doctools/trunk/converter/newfiles/contents.rst ============================================================================== --- doctools/trunk/converter/newfiles/contents.rst (original) +++ doctools/trunk/converter/newfiles/contents.rst Thu Aug 2 10:54:17 2007 @@ -7,8 +7,8 @@ whatsnew/2.6.rst tutorial/index.rst reference/index.rst - modules/index.rst - macmodules/index.rst + library/index.rst + maclib/index.rst extending/index.rst c-api/index.rst distutils/index.rst Modified: doctools/trunk/converter/newfiles/mac_index.rst ============================================================================== --- doctools/trunk/converter/newfiles/mac_index.rst (original) +++ doctools/trunk/converter/newfiles/mac_index.rst Thu Aug 2 10:54:17 2007 @@ -1,4 +1,4 @@ -.. _macmodules-index: +.. _maclib-index: ############################## Macintosh Library Modules @@ -8,7 +8,7 @@ :Date: |today| This library reference manual documents Python's extensions for the Macintosh. -It should be used in conjunction with :ref:`modules-index`, which documents the +It should be used in conjunction with :ref:`library-index`, which documents the standard library and built-in types. This manual assumes basic knowledge about the Python language. For an informal Modified: doctools/trunk/converter/newfiles/modules_index.rst ============================================================================== --- doctools/trunk/converter/newfiles/modules_index.rst (original) +++ doctools/trunk/converter/newfiles/modules_index.rst Thu Aug 2 10:54:17 2007 @@ -1,4 +1,4 @@ -.. _modules-index: +.. _library-index: ############################### The Python standard library @@ -29,6 +29,12 @@ :maxdepth: 2 intro.rst + functions.rst + constants.rst + objects.rst + stdtypes.rst + exceptions.rst + strings.rst datatypes.rst numeric.rst Modified: doctools/trunk/converter/newfiles/ref_index.rst ============================================================================== --- doctools/trunk/converter/newfiles/ref_index.rst (original) +++ doctools/trunk/converter/newfiles/ref_index.rst Thu Aug 2 10:54:17 2007 @@ -10,7 +10,7 @@ This reference manual describes the syntax and "core semantics" of the language. It is terse, but attempts to be exact and complete. The semantics of non-essential built-in object types and of the built-in functions and modules -are described in :ref:`modules-index`. For an informal introduction to the +are described in :ref:`library-index`. For an informal introduction to the language, see :ref:`tutorial-index`. For C or C++ programmers, two additional manuals exist: :ref:`extending-index` describes the high-level picture of how to write a Python extension module, and the :ref:`c-api-index` describes the @@ -27,8 +27,4 @@ simple_stmts.rst compound_stmts.rst toplevel_components.rst - functions.rst - consts.rst - objects.rst - stdtypes.rst - exceptions.rst + Modified: doctools/trunk/sphinx/builder.py ============================================================================== --- doctools/trunk/sphinx/builder.py (original) +++ doctools/trunk/sphinx/builder.py Thu Aug 2 10:54:17 2007 @@ -324,6 +324,7 @@ last_updated = self.last_updated, builder = self.name, release = self.config['release'], + version = self.config['version'], parents = [], len = len, titles = {}, Modified: doctools/trunk/sphinx/style/searchtools.js ============================================================================== --- doctools/trunk/sphinx/style/searchtools.js (original) +++ doctools/trunk/sphinx/style/searchtools.js Thu Aug 2 10:54:17 2007 @@ -232,7 +232,7 @@ // auto default if (areas.length == 1 && areas[0] == 'default') { - areas = ['tutorial', 'modules', 'install', 'distutils']; + areas = ['tutorial', 'library', 'install', 'distutils']; } // update input fields @@ -425,4 +425,4 @@ $(document).ready(function() { Documentation.Search.init(); - }); \ No newline at end of file + }); Modified: doctools/trunk/sphinx/templates/index.html ============================================================================== --- doctools/trunk/sphinx/templates/index.html (original) +++ doctools/trunk/sphinx/templates/index.html Thu Aug 2 10:54:17 2007 @@ -14,15 +14,15 @@

    Parts of the documentation:

    + + + + + + +<% + day = nil + end +-%> + + + + + + +<% @title = "Besetzung - #{@instrument.name}" %> + +

    +<%= pluralize(@members.size, 'Sch??ler spielt', 'Sch??ler spielen') %> <%= h @instrument.name %>: +

    + +
    -

    What's new in Python 2.6?
    +

    What's new in Python {{ version }}?
    changes since previous major release

    Tutorial
    start here

    Language Reference
    - describes syntax, language elements and builtins

    -

    Library Reference
    + describes syntax and language elements

    +

    Library Reference
    keep this under your pillow

    -

    Macintosh Library Modules
    +

    Macintosh Library Modules
    this too, if you use a Macintosh

    Extending and Embedding
    Modified: doctools/trunk/sphinx/templates/keyword_not_found.html ============================================================================== --- doctools/trunk/sphinx/templates/keyword_not_found.html (original) +++ doctools/trunk/sphinx/templates/keyword_not_found.html Thu Aug 2 10:54:17 2007 @@ -26,6 +26,6 @@

    For a quick overview over all documented modules, - click here. + click here.

    {% endblock %} Modified: doctools/trunk/sphinx/templates/search.html ============================================================================== --- doctools/trunk/sphinx/templates/search.html (original) +++ doctools/trunk/sphinx/templates/search.html Thu Aug 2 10:54:17 2007 @@ -24,8 +24,8 @@
      {% for id, name, checked in [ ('tutorial', 'Python Tutorial', true), - ('modules', 'Library Reference', true), - ('macmodules', 'Macintosh Library Modules', false), + ('library', 'Library Reference', true), + ('maclib', 'Macintosh Library Modules', false), ('extending', 'Extending and Embedding', false), ('c-api', 'Python/C API', false), ('install', 'Installing Python Modules', true), Modified: doctools/trunk/sphinx/web/application.py ============================================================================== --- doctools/trunk/sphinx/web/application.py (original) +++ doctools/trunk/sphinx/web/application.py Thu Aug 2 10:54:17 2007 @@ -590,7 +590,7 @@ """ Find keyword matches. If there is an exact match, just redirect: http://docs.python.org/os.path.exists would automatically - redirect to http://docs.python.org/modules/os.path/#os.path.exists. + redirect to http://docs.python.org/library/os.path/#os.path.exists. Else, show a page with close matches. Module references are processed first so that "os.path" is handled as Modified: doctools/trunk/sphinx/web/oldurls.py ============================================================================== --- doctools/trunk/sphinx/web/oldurls.py (original) +++ doctools/trunk/sphinx/web/oldurls.py Thu Aug 2 10:54:17 2007 @@ -60,18 +60,18 @@ return 'bugs/' if url == 'modindex.html' or url.endswith('/modindex.html'): return 'modindex/' - # modules, macmodules + # library, maclib if url[:4] in ('lib/', 'mac/'): - p = '' if url[0] == 'l' else 'mac' + p = 'library/' if url[0] == 'l' else 'maclib/' m = _module_re.match(url[4:]) if m: mn = m.group(1) - return p + 'modules/' + special_module_names.get(mn, mn) + return p + special_module_names.get(mn, mn) # module sub-pages m = _modsub_re.match(url[4:]) if m and not _modobj_re.match(url[4:]): mn = m.group(1) - return p + 'modules/' + special_module_names.get(mn, mn) + return p + special_module_names.get(mn, mn) # XXX: handle all others # tutorial elif url[:4] == 'tut/': From python-checkins at python.org Thu Aug 2 11:16:37 2007 From: python-checkins at python.org (georg.brandl) Date: Thu, 2 Aug 2007 11:16:37 +0200 (CEST) Subject: [Python-checkins] r56663 - in doctools/trunk: Doc-26/TODO Doc-26/library/datatypes.rst Doc-26/library/stdtypes.rst Doc-26/library/strings.rst Doc-3k/library/datatypes.rst Doc-3k/library/index.rst Doc-3k/library/stdtypes.rst Doc-3k/library/strings.rst sphinx/templates/modindex.html Message-ID: <20070802091637.1C0911E4008@bag.python.org> Author: georg.brandl Date: Thu Aug 2 11:16:36 2007 New Revision: 56663 Modified: doctools/trunk/Doc-26/TODO doctools/trunk/Doc-26/library/datatypes.rst doctools/trunk/Doc-26/library/stdtypes.rst doctools/trunk/Doc-26/library/strings.rst doctools/trunk/Doc-3k/library/datatypes.rst doctools/trunk/Doc-3k/library/index.rst doctools/trunk/Doc-3k/library/stdtypes.rst doctools/trunk/Doc-3k/library/strings.rst doctools/trunk/sphinx/templates/modindex.html Log: First few fixes in the new trees. Modified: doctools/trunk/Doc-26/TODO ============================================================================== --- doctools/trunk/Doc-26/TODO (original) +++ doctools/trunk/Doc-26/TODO Thu Aug 2 11:16:36 2007 @@ -14,5 +14,4 @@ * write "About these documents" * finish "Documenting Python" * extend copyright.rst -* fix the "quadruple" index term -* fix :file: and |version| in install \ No newline at end of file +* fix :file: and |version| in install Modified: doctools/trunk/Doc-26/library/datatypes.rst ============================================================================== --- doctools/trunk/Doc-26/library/datatypes.rst (original) +++ doctools/trunk/Doc-26/library/datatypes.rst Thu Aug 2 11:16:36 2007 @@ -9,6 +9,12 @@ types such as dates and times, fixed-type arrays, heap queues, synchronized queues, and sets. +Python also provides some built-in data types, in particular, +:class:`dict`, :class:`list`, :class:`set` (which along with +:class:`frozenset`, replaces the deprecated :mod:`sets` module), and +:class:`tuple`. The :class:`str` class can be used to handle binary data +and 8-bit text, and the :class:`unicode` class to handle Unicode text. + The following modules are documented in this chapter: Modified: doctools/trunk/Doc-26/library/stdtypes.rst ============================================================================== --- doctools/trunk/Doc-26/library/stdtypes.rst (original) +++ doctools/trunk/Doc-26/library/stdtypes.rst Thu Aug 2 11:16:36 2007 @@ -1307,7 +1307,6 @@ +------------------------------+--------------------------------+---------------------+ .. index:: - quadruple: operations on; mutable; sequence; types triple: operations on; sequence; types triple: operations on; list; type pair: subscript; assignment Modified: doctools/trunk/Doc-26/library/strings.rst ============================================================================== --- doctools/trunk/Doc-26/library/strings.rst (original) +++ doctools/trunk/Doc-26/library/strings.rst Thu Aug 2 11:16:36 2007 @@ -6,7 +6,13 @@ *************** The modules described in this chapter provide a wide range of string -manipulation operations. Here's an overview: +manipulation operations. + +In addition, Python's built-in string classes support the sequence type +methods described in the :ref:`typesseq` section, and also the +string-specific methods described in the :ref:`string-methods` section. +To output formatted strings use template strings or the ``%`` operator +described in the :ref:`typesseq-strings` section. .. toctree:: @@ -21,6 +27,4 @@ unicodedata.rst stringprep.rst fpformat.rst -Information on the methods of string objects can be found in section -:ref:`string-methods`, "String Methods." Modified: doctools/trunk/Doc-3k/library/datatypes.rst ============================================================================== --- doctools/trunk/Doc-3k/library/datatypes.rst (original) +++ doctools/trunk/Doc-3k/library/datatypes.rst Thu Aug 2 11:16:36 2007 @@ -9,6 +9,11 @@ types such as dates and times, fixed-type arrays, heap queues, synchronized queues, and sets. +Python also provides some built-in data types, in particular, +:class:`dict`, :class:`list`, :class:`set` and :class:`frozenset`, and +:class:`tuple`. The :class:`str` class can be used to handle binary data +and 8-bit text, and the :class:`unicode` class to handle Unicode text. + The following modules are documented in this chapter: Modified: doctools/trunk/Doc-3k/library/index.rst ============================================================================== --- doctools/trunk/Doc-3k/library/index.rst (original) +++ doctools/trunk/Doc-3k/library/index.rst Thu Aug 2 11:16:36 2007 @@ -29,11 +29,11 @@ :maxdepth: 2 intro.rst - constants.rst - exceptions.rst functions.rst + constants.rst objects.rst stdtypes.rst + exceptions.rst strings.rst datatypes.rst Modified: doctools/trunk/Doc-3k/library/stdtypes.rst ============================================================================== --- doctools/trunk/Doc-3k/library/stdtypes.rst (original) +++ doctools/trunk/Doc-3k/library/stdtypes.rst Thu Aug 2 11:16:36 2007 @@ -1299,7 +1299,6 @@ +------------------------------+--------------------------------+---------------------+ .. index:: - quadruple: operations on; mutable; sequence; types triple: operations on; sequence; types triple: operations on; list; type pair: subscript; assignment Modified: doctools/trunk/Doc-3k/library/strings.rst ============================================================================== --- doctools/trunk/Doc-3k/library/strings.rst (original) +++ doctools/trunk/Doc-3k/library/strings.rst Thu Aug 2 11:16:36 2007 @@ -6,7 +6,13 @@ *************** The modules described in this chapter provide a wide range of string -manipulation operations. Here's an overview: +manipulation operations. + +In addition, Python's built-in string classes support the sequence type +methods described in the :ref:`typesseq` section, and also the +string-specific methods described in the :ref:`string-methods` section. +To output formatted strings use template strings or the ``%`` operator +described in the :ref:`typesseq-strings` section. .. toctree:: @@ -21,6 +27,4 @@ unicodedata.rst stringprep.rst fpformat.rst -Information on the methods of string objects can be found in section -:ref:`string-methods`, "String Methods." Modified: doctools/trunk/sphinx/templates/modindex.html ============================================================================== --- doctools/trunk/sphinx/templates/modindex.html (original) +++ doctools/trunk/sphinx/templates/modindex.html Thu Aug 2 11:16:36 2007 @@ -11,6 +11,7 @@ {%- endfor %} {% endif %} +{% if builder == 'web' %}
      Show modules only available on these platforms:
      {% for pl in platforms -%} @@ -20,6 +21,7 @@ {% endfor %}
      +{% endif %} {%- for modname, collapse, cgroup, indent, fname, synops, pform in modindexentries %} From python-checkins at python.org Thu Aug 2 11:30:44 2007 From: python-checkins at python.org (georg.brandl) Date: Thu, 2 Aug 2007 11:30:44 +0200 (CEST) Subject: [Python-checkins] r56664 - in doctools/trunk: Doc-26/TODO Doc-26/library/email-examples.rst Doc-26/library/email.charset.rst Doc-26/library/email.encoders.rst Doc-26/library/email.errors.rst Doc-26/library/email.generator.rst Doc-26/library/email.header.rst Doc-26/library/email.iterators.rst Doc-26/library/email.message.rst Doc-26/library/email.mime.rst Doc-26/library/email.parser.rst Doc-26/library/email.rst Doc-26/library/email.util.rst Doc-3k/TODO Doc-3k/library/email.charset.rst Doc-3k/library/email.encoders.rst Doc-3k/library/email.errors.rst Doc-3k/library/email.generator.rst Doc-3k/library/email.header.rst Doc-3k/library/email.iterators.rst Doc-3k/library/email.message.rst Doc-3k/library/email.mime.rst Doc-3k/library/email.parser.rst Doc-3k/library/email.rst Doc-3k/library/email.util.rst Message-ID: <20070802093044.18D4D1E4007@bag.python.org> Author: georg.brandl Date: Thu Aug 2 11:30:42 2007 New Revision: 56664 Added: doctools/trunk/Doc-26/library/email-examples.rst Modified: doctools/trunk/Doc-26/TODO doctools/trunk/Doc-26/library/email.charset.rst doctools/trunk/Doc-26/library/email.encoders.rst doctools/trunk/Doc-26/library/email.errors.rst doctools/trunk/Doc-26/library/email.generator.rst doctools/trunk/Doc-26/library/email.header.rst doctools/trunk/Doc-26/library/email.iterators.rst doctools/trunk/Doc-26/library/email.message.rst doctools/trunk/Doc-26/library/email.mime.rst doctools/trunk/Doc-26/library/email.parser.rst doctools/trunk/Doc-26/library/email.rst doctools/trunk/Doc-26/library/email.util.rst doctools/trunk/Doc-3k/TODO doctools/trunk/Doc-3k/library/email.charset.rst doctools/trunk/Doc-3k/library/email.encoders.rst doctools/trunk/Doc-3k/library/email.errors.rst doctools/trunk/Doc-3k/library/email.generator.rst doctools/trunk/Doc-3k/library/email.header.rst doctools/trunk/Doc-3k/library/email.iterators.rst doctools/trunk/Doc-3k/library/email.message.rst doctools/trunk/Doc-3k/library/email.mime.rst doctools/trunk/Doc-3k/library/email.parser.rst doctools/trunk/Doc-3k/library/email.rst doctools/trunk/Doc-3k/library/email.util.rst Log: Add the email package toctree. Modified: doctools/trunk/Doc-26/TODO ============================================================================== --- doctools/trunk/Doc-26/TODO (original) +++ doctools/trunk/Doc-26/TODO Thu Aug 2 11:30:42 2007 @@ -5,7 +5,6 @@ * adjust all literal include paths * remove all non-literal includes * fix all duplicate labels and undefined label references -* fix the email package docs: add a toctree * split very large files and add toctrees * integrate standalone HOWTOs * find out which files get "comments disabled" metadata Added: doctools/trunk/Doc-26/library/email-examples.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-26/library/email-examples.rst Thu Aug 2 11:30:42 2007 @@ -0,0 +1,38 @@ +:mod:`email`: Examples +---------------------- + +Here are a few examples of how to use the :mod:`email` package to read, write, +and send simple email messages, as well as more complex MIME messages. + +First, let's see how to create and send a simple text message: + + +.. include:: ../includes/email-simple.py + :literal: + +Here's an example of how to send a MIME message containing a bunch of family +pictures that may be residing in a directory: + + +.. include:: ../includes/email-mime.py + :literal: + +Here's an example of how to send the entire contents of a directory as an email +message: [#]_ + + +.. include:: ../includes/email-dir.py + :literal: + +And finally, here's an example of how to unpack a MIME message like the one +above, into a directory of files: + + +.. include:: ../includes/email-unpack.py + :literal: + + +.. rubric:: Footnotes + +.. [#] Thanks to Matthew Dixon Cowles for the original inspiration and examples. + Modified: doctools/trunk/Doc-26/library/email.charset.rst ============================================================================== --- doctools/trunk/Doc-26/library/email.charset.rst (original) +++ doctools/trunk/Doc-26/library/email.charset.rst Thu Aug 2 11:30:42 2007 @@ -1,3 +1,6 @@ +:mod:`email`: Representing character sets +----------------------------------------- + .. module:: email.charset :synopsis: Character Sets Modified: doctools/trunk/Doc-26/library/email.encoders.rst ============================================================================== --- doctools/trunk/Doc-26/library/email.encoders.rst (original) +++ doctools/trunk/Doc-26/library/email.encoders.rst Thu Aug 2 11:30:42 2007 @@ -1,3 +1,6 @@ +:mod:`email`: Encoders +---------------------- + .. module:: email.encoders :synopsis: Encoders for email message payloads. Modified: doctools/trunk/Doc-26/library/email.errors.rst ============================================================================== --- doctools/trunk/Doc-26/library/email.errors.rst (original) +++ doctools/trunk/Doc-26/library/email.errors.rst Thu Aug 2 11:30:42 2007 @@ -1,3 +1,6 @@ +:mod:`email`: Exception and Defect classes +------------------------------------------ + .. module:: email.errors :synopsis: The exception classes used by the email package. Modified: doctools/trunk/Doc-26/library/email.generator.rst ============================================================================== --- doctools/trunk/Doc-26/library/email.generator.rst (original) +++ doctools/trunk/Doc-26/library/email.generator.rst Thu Aug 2 11:30:42 2007 @@ -1,3 +1,6 @@ +:mod:`email`: Generating MIME documents +--------------------------------------- + .. module:: email.generator :synopsis: Generate flat text email messages from a message structure. Modified: doctools/trunk/Doc-26/library/email.header.rst ============================================================================== --- doctools/trunk/Doc-26/library/email.header.rst (original) +++ doctools/trunk/Doc-26/library/email.header.rst Thu Aug 2 11:30:42 2007 @@ -1,3 +1,6 @@ +:mod:`email`: Internationalized headers +--------------------------------------- + .. module:: email.header :synopsis: Representing non-ASCII headers Modified: doctools/trunk/Doc-26/library/email.iterators.rst ============================================================================== --- doctools/trunk/Doc-26/library/email.iterators.rst (original) +++ doctools/trunk/Doc-26/library/email.iterators.rst Thu Aug 2 11:30:42 2007 @@ -1,3 +1,6 @@ +:mod:`email`: Iterators +----------------------- + .. module:: email.iterators :synopsis: Iterate over a message object tree. Modified: doctools/trunk/Doc-26/library/email.message.rst ============================================================================== --- doctools/trunk/Doc-26/library/email.message.rst (original) +++ doctools/trunk/Doc-26/library/email.message.rst Thu Aug 2 11:30:42 2007 @@ -1,3 +1,6 @@ +:mod:`email`: Representing an email message +------------------------------------------- + .. module:: email.message :synopsis: The base class representing email messages. Modified: doctools/trunk/Doc-26/library/email.mime.rst ============================================================================== --- doctools/trunk/Doc-26/library/email.mime.rst (original) +++ doctools/trunk/Doc-26/library/email.mime.rst Thu Aug 2 11:30:42 2007 @@ -1,3 +1,6 @@ +:mod:`email`: Creating email and MIME objects from scratch +---------------------------------------------------------- + .. module:: email.mime.text Modified: doctools/trunk/Doc-26/library/email.parser.rst ============================================================================== --- doctools/trunk/Doc-26/library/email.parser.rst (original) +++ doctools/trunk/Doc-26/library/email.parser.rst Thu Aug 2 11:30:42 2007 @@ -1,3 +1,6 @@ +:mod:`email`: Parsing email messages +------------------------------------ + .. module:: email.parser :synopsis: Parse flat text email messages to produce a message object structure. Modified: doctools/trunk/Doc-26/library/email.rst ============================================================================== --- doctools/trunk/Doc-26/library/email.rst (original) +++ doctools/trunk/Doc-26/library/email.rst Thu Aug 2 11:30:42 2007 @@ -52,6 +52,22 @@ examples. For users of the older :mod:`mimelib` package, or previous versions of the :mod:`email` package, a section on differences and porting is provided. +Contents of the :mod:`email` package documentation: + +.. toctree:: + + email.message.rst + email.parser.rst + email.generator.rst + email.mime.rst + email.header.rst + email.charset.rst + email.encoders.rst + email.errors.rst + email.util.rst + email.iterators.rst + email-examples.rst + .. seealso:: @@ -62,76 +78,6 @@ NNTP protocol client -Representing an email message ------------------------------ - - -.. include:: email.message.rst - - -Parsing email messages ----------------------- - - -.. include:: email.parser.rst - - -Generating MIME documents -------------------------- - - -.. include:: email.generator.rst - - -Creating email and MIME objects from scratch --------------------------------------------- - - -.. include:: email.mime.rst - - -Internationalized headers -------------------------- - - -.. include:: email.header.rst - - -Representing character sets ---------------------------- - - -.. include:: email.charset.rst - - -Encoders --------- - - -.. include:: email.encoders.rst - - -Exception and Defect classes ----------------------------- - - -.. include:: email.errors.rst - - -Miscellaneous utilities ------------------------ - - -.. include:: email.util.rst - - -Iterators ---------- - - -.. include:: email.iterators.rst - - .. _email-pkg-history: Package History @@ -373,43 +319,6 @@ closely supported in the :func:`body_line_iterator` function in the :mod:`email.iterators` module. - -Examples --------- - -Here are a few examples of how to use the :mod:`email` package to read, write, -and send simple email messages, as well as more complex MIME messages. - -First, let's see how to create and send a simple text message: - - -.. include:: ../includes/email-simple.py - :literal: - -Here's an example of how to send a MIME message containing a bunch of family -pictures that may be residing in a directory: - - -.. include:: ../includes/email-mime.py - :literal: - -Here's an example of how to send the entire contents of a directory as an email -message: [#]_ - - -.. include:: ../includes/email-dir.py - :literal: - -And finally, here's an example of how to unpack a MIME message like the one -above, into a directory of files: - - -.. include:: ../includes/email-unpack.py - :literal: - .. rubric:: Footnotes .. [#] Delivery Status Notifications (DSN) are defined in :rfc:`1894`. - -.. [#] Thanks to Matthew Dixon Cowles for the original inspiration and examples. - Modified: doctools/trunk/Doc-26/library/email.util.rst ============================================================================== --- doctools/trunk/Doc-26/library/email.util.rst (original) +++ doctools/trunk/Doc-26/library/email.util.rst Thu Aug 2 11:30:42 2007 @@ -1,3 +1,6 @@ +:mod:`email`: Miscellaneous utilities +------------------------------------- + .. module:: email.utils :synopsis: Miscellaneous email package utilities. Modified: doctools/trunk/Doc-3k/TODO ============================================================================== --- doctools/trunk/Doc-3k/TODO (original) +++ doctools/trunk/Doc-3k/TODO Thu Aug 2 11:30:42 2007 @@ -5,7 +5,6 @@ * adjust all literal include paths * remove all non-literal includes * fix all duplicate labels and undefined label references -* fix the email package docs: add a toctree * split very large files and add toctrees * integrate standalone HOWTOs * find out which files get "comments disabled" metadata @@ -14,5 +13,4 @@ * write "About these documents" * finish "Documenting Python" * extend copyright.rst -* fix the "quadruple" index term -* fix :file: and |version| in install \ No newline at end of file +* fix :file: and |version| in install Modified: doctools/trunk/Doc-3k/library/email.charset.rst ============================================================================== --- doctools/trunk/Doc-3k/library/email.charset.rst (original) +++ doctools/trunk/Doc-3k/library/email.charset.rst Thu Aug 2 11:30:42 2007 @@ -1,3 +1,6 @@ +:mod:`email`: Representing character sets +----------------------------------------- + .. module:: email.charset :synopsis: Character Sets Modified: doctools/trunk/Doc-3k/library/email.encoders.rst ============================================================================== --- doctools/trunk/Doc-3k/library/email.encoders.rst (original) +++ doctools/trunk/Doc-3k/library/email.encoders.rst Thu Aug 2 11:30:42 2007 @@ -1,3 +1,6 @@ +:mod:`email`: Encoders +---------------------- + .. module:: email.encoders :synopsis: Encoders for email message payloads. Modified: doctools/trunk/Doc-3k/library/email.errors.rst ============================================================================== --- doctools/trunk/Doc-3k/library/email.errors.rst (original) +++ doctools/trunk/Doc-3k/library/email.errors.rst Thu Aug 2 11:30:42 2007 @@ -1,3 +1,6 @@ +:mod:`email`: Exception and Defect classes +------------------------------------------ + .. module:: email.errors :synopsis: The exception classes used by the email package. Modified: doctools/trunk/Doc-3k/library/email.generator.rst ============================================================================== --- doctools/trunk/Doc-3k/library/email.generator.rst (original) +++ doctools/trunk/Doc-3k/library/email.generator.rst Thu Aug 2 11:30:42 2007 @@ -1,3 +1,6 @@ +:mod:`email`: Generating MIME documents +--------------------------------------- + .. module:: email.generator :synopsis: Generate flat text email messages from a message structure. Modified: doctools/trunk/Doc-3k/library/email.header.rst ============================================================================== --- doctools/trunk/Doc-3k/library/email.header.rst (original) +++ doctools/trunk/Doc-3k/library/email.header.rst Thu Aug 2 11:30:42 2007 @@ -1,3 +1,6 @@ +:mod:`email`: Internationalized headers +--------------------------------------- + .. module:: email.header :synopsis: Representing non-ASCII headers Modified: doctools/trunk/Doc-3k/library/email.iterators.rst ============================================================================== --- doctools/trunk/Doc-3k/library/email.iterators.rst (original) +++ doctools/trunk/Doc-3k/library/email.iterators.rst Thu Aug 2 11:30:42 2007 @@ -1,3 +1,6 @@ +:mod:`email`: Iterators +----------------------- + .. module:: email.iterators :synopsis: Iterate over a message object tree. Modified: doctools/trunk/Doc-3k/library/email.message.rst ============================================================================== --- doctools/trunk/Doc-3k/library/email.message.rst (original) +++ doctools/trunk/Doc-3k/library/email.message.rst Thu Aug 2 11:30:42 2007 @@ -1,3 +1,6 @@ +:mod:`email`: Representing an email message +------------------------------------------- + .. module:: email.message :synopsis: The base class representing email messages. Modified: doctools/trunk/Doc-3k/library/email.mime.rst ============================================================================== --- doctools/trunk/Doc-3k/library/email.mime.rst (original) +++ doctools/trunk/Doc-3k/library/email.mime.rst Thu Aug 2 11:30:42 2007 @@ -1,3 +1,6 @@ +:mod:`email`: Creating email and MIME objects from scratch +---------------------------------------------------------- + .. module:: email.mime.text Modified: doctools/trunk/Doc-3k/library/email.parser.rst ============================================================================== --- doctools/trunk/Doc-3k/library/email.parser.rst (original) +++ doctools/trunk/Doc-3k/library/email.parser.rst Thu Aug 2 11:30:42 2007 @@ -1,3 +1,6 @@ +:mod:`email`: Parsing email messages +------------------------------------ + .. module:: email.parser :synopsis: Parse flat text email messages to produce a message object structure. Modified: doctools/trunk/Doc-3k/library/email.rst ============================================================================== --- doctools/trunk/Doc-3k/library/email.rst (original) +++ doctools/trunk/Doc-3k/library/email.rst Thu Aug 2 11:30:42 2007 @@ -52,6 +52,22 @@ examples. For users of the older :mod:`mimelib` package, or previous versions of the :mod:`email` package, a section on differences and porting is provided. +Contents of the :mod:`email` package documentation: + +.. toctree:: + + email.message.rst + email.parser.rst + email.generator.rst + email.mime.rst + email.header.rst + email.charset.rst + email.encoders.rst + email.errors.rst + email.util.rst + email.iterators.rst + email-examples.rst + .. seealso:: @@ -62,76 +78,6 @@ NNTP protocol client -Representing an email message ------------------------------ - - -.. include:: email.message.rst - - -Parsing email messages ----------------------- - - -.. include:: email.parser.rst - - -Generating MIME documents -------------------------- - - -.. include:: email.generator.rst - - -Creating email and MIME objects from scratch --------------------------------------------- - - -.. include:: email.mime.rst - - -Internationalized headers -------------------------- - - -.. include:: email.header.rst - - -Representing character sets ---------------------------- - - -.. include:: email.charset.rst - - -Encoders --------- - - -.. include:: email.encoders.rst - - -Exception and Defect classes ----------------------------- - - -.. include:: email.errors.rst - - -Miscellaneous utilities ------------------------ - - -.. include:: email.util.rst - - -Iterators ---------- - - -.. include:: email.iterators.rst - - .. _email-pkg-history: Package History @@ -373,43 +319,6 @@ closely supported in the :func:`body_line_iterator` function in the :mod:`email.iterators` module. - -Examples --------- - -Here are a few examples of how to use the :mod:`email` package to read, write, -and send simple email messages, as well as more complex MIME messages. - -First, let's see how to create and send a simple text message: - - -.. include:: ../includes/email-simple.py - :literal: - -Here's an example of how to send a MIME message containing a bunch of family -pictures that may be residing in a directory: - - -.. include:: ../includes/email-mime.py - :literal: - -Here's an example of how to send the entire contents of a directory as an email -message: [#]_ - - -.. include:: ../includes/email-dir.py - :literal: - -And finally, here's an example of how to unpack a MIME message like the one -above, into a directory of files: - - -.. include:: ../includes/email-unpack.py - :literal: - .. rubric:: Footnotes .. [#] Delivery Status Notifications (DSN) are defined in :rfc:`1894`. - -.. [#] Thanks to Matthew Dixon Cowles for the original inspiration and examples. - Modified: doctools/trunk/Doc-3k/library/email.util.rst ============================================================================== --- doctools/trunk/Doc-3k/library/email.util.rst (original) +++ doctools/trunk/Doc-3k/library/email.util.rst Thu Aug 2 11:30:42 2007 @@ -1,3 +1,6 @@ +:mod:`email`: Miscellaneous utilities +------------------------------------- + .. module:: email.utils :synopsis: Miscellaneous email package utilities. From python-checkins at python.org Thu Aug 2 14:25:11 2007 From: python-checkins at python.org (georg.brandl) Date: Thu, 2 Aug 2007 14:25:11 +0200 (CEST) Subject: [Python-checkins] r56665 - doctools/trunk/sphinx/directives.py doctools/trunk/sphinx/roles.py Message-ID: <20070802122511.1F3FE1E4007@bag.python.org> Author: georg.brandl Date: Thu Aug 2 14:25:10 2007 New Revision: 56665 Modified: doctools/trunk/sphinx/directives.py doctools/trunk/sphinx/roles.py Log: Don't interpret markup in productionlists. Modified: doctools/trunk/sphinx/directives.py ============================================================================== --- doctools/trunk/sphinx/directives.py (original) +++ doctools/trunk/sphinx/directives.py Thu Aug 2 14:25:10 2007 @@ -397,6 +397,28 @@ # ------ production list (for the reference) --------------------------------------- +token_re = re.compile('`([a-z_]+)`') + +def token_xrefs(text, env): + retnodes = [] + pos = 0 + for m in token_re.finditer(text): + if m.start() > pos: + txt = text[pos:m.start()] + retnodes.append(nodes.Text(txt, txt)) + refnode = addnodes.pending_xref(m.group(1)) + refnode['reftype'] = 'token' + refnode['reftarget'] = m.group(1) + refnode['modname'] = env.currmodule + refnode['classname'] = env.currclass + refnode += nodes.literal(m.group(1), m.group(1), classes=['xref']) + retnodes.append(refnode) + pos = m.end() + if pos < len(text): + retnodes.append(nodes.Text(text[pos:], text[pos:])) + print retnodes + return retnodes + def productionlist_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): env = state.document.settings.env @@ -404,8 +426,6 @@ messages = [] i = 0 - # use token as the default role while in production list - roles._roles[''] = roles._role_registry['token'] for rule in arguments[0].split('\n'): if i == 0 and ':' not in rule: # production group @@ -423,11 +443,8 @@ subnode['ids'].append(idname) state.document.note_implicit_target(subnode, subnode) env.note_token(subnode['tokenname']) - inodes, imessages = state.inline_text(tokens, lineno+i) - subnode.extend(inodes) - messages.extend(imessages) + subnode.extend(token_xrefs(tokens, env)) node.append(subnode) - del roles._roles[''] return [node] + messages productionlist_directive.content = 0 Modified: doctools/trunk/sphinx/roles.py ============================================================================== --- doctools/trunk/sphinx/roles.py (original) +++ doctools/trunk/sphinx/roles.py Thu Aug 2 14:25:10 2007 @@ -95,9 +95,6 @@ def xfileref_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): env = inliner.document.settings.env text = utils.unescape(text) - # 'token' is the default role inside 'productionlist' directives - if typ == '': - typ = 'token' if typ in ('func', 'meth', 'cfunc') and \ env.config.get('add_function_parentheses', True): text += '()' From python-checkins at python.org Thu Aug 2 14:32:15 2007 From: python-checkins at python.org (georg.brandl) Date: Thu, 2 Aug 2007 14:32:15 +0200 (CEST) Subject: [Python-checkins] r56666 - in doctools/trunk: Doc-26/TODO Doc-26/documenting/markup.rst Doc-26/install/index.rst Doc-26/reference/compound_stmts.rst Doc-26/reference/expressions.rst Doc-26/reference/introduction.rst Doc-26/reference/lexical_analysis.rst Doc-26/reference/simple_stmts.rst Doc-26/reference/toplevel_components.rst Doc-3k/TODO Doc-3k/documenting/markup.rst Doc-3k/install/index.rst Doc-3k/reference/compound_stmts.rst Doc-3k/reference/expressions.rst Doc-3k/reference/introduction.rst Doc-3k/reference/lexical_analysis.rst Doc-3k/reference/simple_stmts.rst Doc-3k/reference/toplevel_components.rst Message-ID: <20070802123215.CF72E1E4012@bag.python.org> Author: georg.brandl Date: Thu Aug 2 14:32:13 2007 New Revision: 56666 Modified: doctools/trunk/Doc-26/TODO doctools/trunk/Doc-26/documenting/markup.rst doctools/trunk/Doc-26/install/index.rst doctools/trunk/Doc-26/reference/compound_stmts.rst doctools/trunk/Doc-26/reference/expressions.rst doctools/trunk/Doc-26/reference/introduction.rst doctools/trunk/Doc-26/reference/lexical_analysis.rst doctools/trunk/Doc-26/reference/simple_stmts.rst doctools/trunk/Doc-26/reference/toplevel_components.rst doctools/trunk/Doc-3k/TODO doctools/trunk/Doc-3k/documenting/markup.rst doctools/trunk/Doc-3k/install/index.rst doctools/trunk/Doc-3k/reference/compound_stmts.rst doctools/trunk/Doc-3k/reference/expressions.rst doctools/trunk/Doc-3k/reference/introduction.rst doctools/trunk/Doc-3k/reference/lexical_analysis.rst doctools/trunk/Doc-3k/reference/simple_stmts.rst doctools/trunk/Doc-3k/reference/toplevel_components.rst Log: Fix production list escaping. Modified: doctools/trunk/Doc-26/TODO ============================================================================== --- doctools/trunk/Doc-26/TODO (original) +++ doctools/trunk/Doc-26/TODO Thu Aug 2 14:32:13 2007 @@ -3,14 +3,11 @@ * fix all references and links marked with `XXX` * adjust all literal include paths -* remove all non-literal includes * fix all duplicate labels and undefined label references * split very large files and add toctrees * integrate standalone HOWTOs * find out which files get "comments disabled" metadata -* double backslashes in production lists * add synopses for each module * write "About these documents" * finish "Documenting Python" * extend copyright.rst -* fix :file: and |version| in install Modified: doctools/trunk/Doc-26/documenting/markup.rst ============================================================================== --- doctools/trunk/Doc-26/documenting/markup.rst (original) +++ doctools/trunk/Doc-26/documenting/markup.rst Thu Aug 2 14:32:13 2007 @@ -673,7 +673,7 @@ triple Likewise, ``triple: module; search; path`` is a shortcut that creates three index entries, which are ``module; search path``, ``search; path, module`` and - ``path; module search``. + ``path; module search``. module, keyword, operator, object, exception, statement, builtin These all create two index entries. For example, ``module: hashlib`` creates the entries ``module; hashlib`` and ``hashlib; module``. @@ -700,9 +700,10 @@ The definition can contain token names which are marked as interpreted text (e.g. ``sum ::= `integer` "+" `integer```) -- this generates cross-references - to the productions of these tokens. Note that vertical bars used to indicate - alternatives must be escaped with backslashes because otherwise they would - indicate a substitution reference to the reST parser. + to the productions of these tokens. + + Note that no further reST parsing is done in the production, so that you + don't have to escape ``*`` or ``|`` characters. .. XXX describe optional first parameter @@ -710,13 +711,13 @@ The following is an example taken from the Python Reference Manual:: .. productionlist:: - try_stmt: try1_stmt \| try2_stmt - try1_stmt: "try" ":" :token:`suite` - : ("except" [:token:`expression` ["," :token:`target`]] ":" :token:`suite`)+ - : ["else" ":" :token:`suite`] - : ["finally" ":" :token:`suite`] - try2_stmt: "try" ":" :token:`suite` - : "finally" ":" :token:`suite` + try_stmt: try1_stmt | try2_stmt + try1_stmt: "try" ":" `suite` + : ("except" [`expression` ["," `target`]] ":" `suite`)+ + : ["else" ":" `suite`] + : ["finally" ":" `suite`] + try2_stmt: "try" ":" `suite` + : "finally" ":" `suite` Substitutions Modified: doctools/trunk/Doc-26/install/index.rst ============================================================================== --- doctools/trunk/Doc-26/install/index.rst (original) +++ doctools/trunk/Doc-26/install/index.rst Thu Aug 2 14:32:13 2007 @@ -246,19 +246,15 @@ Unix-based), it also depends on whether the module distribution being installed is pure Python or contains extensions ("non-pure"): -+-----------------+------------------------------------+--------------------------------------+-------+ -| Platform | Standard installation | Default value | Notes | -| | location | | | -+=================+====================================+======================================+=======+ -| Unix (pure) | :file:`{prefix}/lib/python|version | :file:`/usr/local/lib/python|version | \(1) | -| | |/site-packages` | |/site-packages` | | -+-----------------+------------------------------------+--------------------------------------+-------+ -| Unix (non-pure) | :file:`{exec- | :file:`/usr/local/lib/python|version | \(1) | -| | prefix}/lib/python|version | |/site-packages` | | -| | |/site-packages` | | | -+-----------------+------------------------------------+--------------------------------------+-------+ -| Windows | :file:`{prefix}` | :file:`C:\\Python` | \(2) | -+-----------------+------------------------------------+--------------------------------------+-------+ ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ +| Platform | Standard installation location | Default value | Notes | ++=================+=====================================================+==================================================+=======+ +| Unix (pure) | :file:`{prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1) | ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ +| Unix (non-pure) | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1) | ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ +| Windows | :file:`{prefix}` | :file:`C:\\Python` | \(2) | ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ Notes: @@ -346,17 +342,17 @@ The :option:`--home` option defines the installation base directory. Files are installed to the following directories under the installation base as follows: -+------------------------------+-----------------------------------+-----------------------------+ -| Type of file | Installation Directory | Override option | -+==============================+===================================+=============================+ -| pure module distribution | :file:`{home}`:file:`/lib/python` | :option:`--install-purelib` | -+------------------------------+-----------------------------------+-----------------------------+ -| non-pure module distribution | :file:`{home}`:file:`/lib/python` | :option:`--install-platlib` | -+------------------------------+-----------------------------------+-----------------------------+ -| scripts | :file:`{home}`:file:`/bin` | :option:`--install-scripts` | -+------------------------------+-----------------------------------+-----------------------------+ -| data | :file:`{home}`:file:`/share` | :option:`--install-data` | -+------------------------------+-----------------------------------+-----------------------------+ ++------------------------------+---------------------------+-----------------------------+ +| Type of file | Installation Directory | Override option | ++==============================+===========================+=============================+ +| pure module distribution | :file:`{home}/lib/python` | :option:`--install-purelib` | ++------------------------------+---------------------------+-----------------------------+ +| non-pure module distribution | :file:`{home}/lib/python` | :option:`--install-platlib` | ++------------------------------+---------------------------+-----------------------------+ +| scripts | :file:`{home}/bin` | :option:`--install-scripts` | ++------------------------------+---------------------------+-----------------------------+ +| data | :file:`{home}/share` | :option:`--install-data` | ++------------------------------+---------------------------+-----------------------------+ .. versionchanged:: 2.4 The :option:`--home` option used to be supported only on Unix. @@ -399,20 +395,17 @@ executables, etc.) If :option:`--exec-prefix` is not supplied, it defaults to :option:`--prefix`. Files are installed as follows: -+------------------------------+----------------------------------------+-----------------------------+ -| Type of file | Installation Directory | Override option | -+==============================+========================================+=============================+ -| pure module distribution | :file:`{prefix}`:file:`/lib/python2.{X | :option:`--install-purelib` | -| | }/site-packages` | | -+------------------------------+----------------------------------------+-----------------------------+ -| non-pure module distribution | :file:`{exec- | :option:`--install-platlib` | -| | prefix}`:file:`/lib/python2.{X | | -| | }/site-packages` | | -+------------------------------+----------------------------------------+-----------------------------+ -| scripts | :file:`{prefix}`:file:`/bin` | :option:`--install-scripts` | -+------------------------------+----------------------------------------+-----------------------------+ -| data | :file:`{prefix}`:file:`/share` | :option:`--install-data` | -+------------------------------+----------------------------------------+-----------------------------+ ++------------------------------+-----------------------------------------------------+-----------------------------+ +| Type of file | Installation Directory | Override option | ++==============================+=====================================================+=============================+ +| pure module distribution | :file:`{prefix}/lib/python{X.Y}/site-packages` | :option:`--install-purelib` | ++------------------------------+-----------------------------------------------------+-----------------------------+ +| non-pure module distribution | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :option:`--install-platlib` | ++------------------------------+-----------------------------------------------------+-----------------------------+ +| scripts | :file:`{prefix}/bin` | :option:`--install-scripts` | ++------------------------------+-----------------------------------------------------+-----------------------------+ +| data | :file:`{prefix}/share` | :option:`--install-data` | ++------------------------------+-----------------------------------------------------+-----------------------------+ There is no requirement that :option:`--prefix` or :option:`--exec-prefix` actually point to an alternate Python installation; if the directories listed @@ -455,17 +448,17 @@ :option:`--exec-prefix` option is not supported under Windows. Files are installed as follows: -+------------------------------+-----------------------------------+-----------------------------+ -| Type of file | Installation Directory | Override option | -+==============================+===================================+=============================+ -| pure module distribution | :file:`{prefix}`:file:`` | :option:`--install-purelib` | -+------------------------------+-----------------------------------+-----------------------------+ -| non-pure module distribution | :file:`{prefix}`:file:`` | :option:`--install-platlib` | -+------------------------------+-----------------------------------+-----------------------------+ -| scripts | :file:`{prefix}`:file:`\\Scripts` | :option:`--install-scripts` | -+------------------------------+-----------------------------------+-----------------------------+ -| data | :file:`{prefix}`:file:`\\Data` | :option:`--install-data` | -+------------------------------+-----------------------------------+-----------------------------+ ++------------------------------+---------------------------+-----------------------------+ +| Type of file | Installation Directory | Override option | ++==============================+===========================+=============================+ +| pure module distribution | :file:`{prefix}` | :option:`--install-purelib` | ++------------------------------+---------------------------+-----------------------------+ +| non-pure module distribution | :file:`{prefix}` | :option:`--install-platlib` | ++------------------------------+---------------------------+-----------------------------+ +| scripts | :file:`{prefix}\\Scripts` | :option:`--install-scripts` | ++------------------------------+---------------------------+-----------------------------+ +| data | :file:`{prefix}\\Data` | :option:`--install-data` | ++------------------------------+---------------------------+-----------------------------+ .. _custom-install: @@ -625,12 +618,12 @@ .. % $ <-- bow to font-lock The expected convention for locally installed packages is to put them in the -:file:`.../site-packages/` directory, but you may want to install Python modules -into some arbitrary directory. For example, your site may have a convention of -keeping all software related to the web server under :file:`/www`. Add-on -Python modules might then belong in :file:`/www/python`, and in order to import -them, this directory must be added to ``sys.path``. There are several different -ways to add the directory. +:file:`{...}/site-packages/` directory, but you may want to install Python +modules into some arbitrary directory. For example, your site may have a +convention of keeping all software related to the web server under :file:`/www`. +Add-on Python modules might then belong in :file:`/www/python`, and in order to +import them, this directory must be added to ``sys.path``. There are several +different ways to add the directory. The most convenient way is to add a path configuration file to a directory that's already on Python's path, usually to the :file:`.../site-packages/` @@ -921,7 +914,7 @@ The :file:`coff2omf` program comes with the Borland compiler. The file :file:`python25.lib` is in the :file:`Libs` directory of your Python -installation. If your extension uses other libraries (zlib,...) you have to +installation. If your extension uses other libraries (zlib, ...) you have to convert them too. The converted files have to reside in the same directories as the normal Modified: doctools/trunk/Doc-26/reference/compound_stmts.rst ============================================================================== --- doctools/trunk/Doc-26/reference/compound_stmts.rst (original) +++ doctools/trunk/Doc-26/reference/compound_stmts.rst Thu Aug 2 14:32:13 2007 @@ -44,15 +44,15 @@ .. productionlist:: compound_stmt: `if_stmt` - : \| `while_stmt` - : \| `for_stmt` - : \| `try_stmt` - : \| `with_stmt` - : \| `funcdef` - : \| `classdef` - suite: `stmt_list` NEWLINE \| NEWLINE INDENT `statement`\ + DEDENT - statement: `stmt_list` NEWLINE \| `compound_stmt` - stmt_list: `simple_stmt` (";" `simple_stmt`)\* [";"] + : | `while_stmt` + : | `for_stmt` + : | `try_stmt` + : | `with_stmt` + : | `funcdef` + : | `classdef` + suite: `stmt_list` NEWLINE | NEWLINE INDENT `statement`+ DEDENT + statement: `stmt_list` NEWLINE | `compound_stmt` + stmt_list: `simple_stmt` (";" `simple_stmt`)* [";"] .. index:: single: NEWLINE token @@ -80,7 +80,7 @@ .. productionlist:: if_stmt: "if" `expression` ":" `suite` - : ( "elif" `expression` ":" `suite` )\* + : ( "elif" `expression` ":" `suite` )* : ["else" ":" `suite`] .. index:: @@ -216,7 +216,7 @@ for a group of statements: .. productionlist:: - try_stmt: try1_stmt \| try2_stmt + try_stmt: try1_stmt | try2_stmt try1_stmt: "try" ":" `suite` : ("except" [`expression` ["," `target`]] ":" `suite`)+ : ["else" ":" `suite`] @@ -403,16 +403,16 @@ .. productionlist:: funcdef: [`decorators`] "def" `funcname` "(" [`parameter_list`] ")" ":" `suite` - decorators: `decorator`\ + + decorators: `decorator`+ decorator: "@" `dotted_name` ["(" [`argument_list` [","]] ")"] NEWLINE - dotted_name: `identifier` ("." `identifier`)\* - parameter_list: (`defparameter` ",")\* - : ( "\*" `identifier` [, "\*\*" `identifier`] - : \| "\*\*" `identifier` - : \| `defparameter` [","] ) + dotted_name: `identifier` ("." `identifier`)* + parameter_list: (`defparameter` ",")* + : ( "*" `identifier` [, "**" `identifier`] + : | "**" `identifier` + : | `defparameter` [","] ) defparameter: `parameter` ["=" `expression`] - sublist: `parameter` ("," `parameter`)\* [","] - parameter: `identifier` \| "(" `sublist` ")" + sublist: `parameter` ("," `parameter`)* [","] + parameter: `identifier` | "(" `sublist` ")" funcname: `identifier` .. index:: Modified: doctools/trunk/Doc-26/reference/expressions.rst ============================================================================== --- doctools/trunk/Doc-26/reference/expressions.rst (original) +++ doctools/trunk/Doc-26/reference/expressions.rst Thu Aug 2 14:32:13 2007 @@ -63,10 +63,10 @@ atoms is: .. productionlist:: - atom: `identifier` \| `literal` \| `enclosure` - enclosure: `parenth_form` \| `list_display` - : \| `generator_expression` \| `dict_display` - : \| `string_conversion` \| `yield_atom` + atom: `identifier` | `literal` | `enclosure` + enclosure: `parenth_form` | `list_display` + : | `generator_expression` | `dict_display` + : | `string_conversion` | `yield_atom` .. _atom-identifiers: @@ -119,8 +119,8 @@ Python supports string literals and various numeric literals: .. productionlist:: - literal: `stringliteral` \| `integer` \| `longinteger` - : \| `floatnumber` \| `imagnumber` + literal: `stringliteral` | `integer` | `longinteger` + : | `floatnumber` | `imagnumber` Evaluation of a literal yields an object of the given type (string, integer, long integer, floating point number, complex number) with the given value. The @@ -183,11 +183,11 @@ brackets: .. productionlist:: - list_display: "[" [`expression_list` \| `list_comprehension`] "]" + list_display: "[" [`expression_list` | `list_comprehension`] "]" list_comprehension: `expression` `list_for` list_for: "for" `target_list` "in" `old_expression_list` [`list_iter`] old_expression_list: `old_expression` [("," `old_expression`)+ [","]] - list_iter: `list_for` \| `list_if` + list_iter: `list_for` | `list_if` list_if: "if" `old_expression` [`list_iter`] .. index:: @@ -219,7 +219,7 @@ .. productionlist:: generator_expression: "(" `expression` `genexpr_for` ")" genexpr_for: "for" `target_list` "in" `or_test` [`genexpr_iter`] - genexpr_iter: `genexpr_for` \| `genexpr_if` + genexpr_iter: `genexpr_for` | `genexpr_if` genexpr_if: "if" `old_expression` [`genexpr_iter`] .. index:: object: generator @@ -262,7 +262,7 @@ .. productionlist:: dict_display: "{" [`key_datum_list`] "}" - key_datum_list: `key_datum` ("," `key_datum`)\* [","] + key_datum_list: `key_datum` ("," `key_datum`)* [","] key_datum: `expression` ":" `expression` .. index:: object: dictionary @@ -470,7 +470,7 @@ syntax is: .. productionlist:: - primary: `atom` \| `attributeref` \| `subscription` \| `slicing` \| `call` + primary: `atom` | `attributeref` | `subscription` | `slicing` | `call` .. _attribute-references: @@ -562,12 +562,12 @@ :keyword:`del` statements. The syntax for a slicing: .. productionlist:: - slicing: `simple_slicing` \| `extended_slicing` + slicing: `simple_slicing` | `extended_slicing` simple_slicing: `primary` "[" `short_slice` "]" extended_slicing: `primary` "[" `slice_list` "]" - slice_list: `slice_item` ("," `slice_item`)\* [","] - slice_item: `expression` \| `proper_slice` \| `ellipsis` - proper_slice: `short_slice` \| `long_slice` + slice_list: `slice_item` ("," `slice_item`)* [","] + slice_item: `expression` | `proper_slice` | `ellipsis` + proper_slice: `short_slice` | `long_slice` short_slice: [`lower_bound`] ":" [`upper_bound`] long_slice: `short_slice` ":" [`stride`] lower_bound: `expression` @@ -627,16 +627,16 @@ .. productionlist:: call: `primary` "(" [`argument_list` [","] - : \| `expression` `genexpr_for`] ")" + : | `expression` `genexpr_for`] ")" argument_list: `positional_arguments` ["," `keyword_arguments`] - : ["," "\*" `expression`] - : ["," "\*\*" `expression`] - : \| `keyword_arguments` ["," "\*" `expression`] - : ["," "\*\*" `expression`] - : \| "\*" `expression` ["," "\*\*" `expression`] - : \| "\*\*" `expression` - positional_arguments: `expression` ("," `expression`)\* - keyword_arguments: `keyword_item` ("," `keyword_item`)\* + : ["," "*" `expression`] + : ["," "**" `expression`] + : | `keyword_arguments` ["," "*" `expression`] + : ["," "**" `expression`] + : | "*" `expression` ["," "**" `expression`] + : | "**" `expression` + positional_arguments: `expression` ("," `expression`)* + keyword_arguments: `keyword_item` ("," `keyword_item`)* keyword_item: `identifier` "=" `expression` A trailing comma may be present after the positional and keyword arguments but @@ -786,7 +786,7 @@ less tightly than unary operators on its right. The syntax is: .. productionlist:: - power: `primary` ["\*\*" `u_expr`] + power: `primary` ["**" `u_expr`] Thus, in an unparenthesized sequence of power and unary operators, the operators are evaluated from right to left (this does not constrain the evaluation order @@ -822,7 +822,7 @@ All unary arithmetic (and bit-wise) operations have the same priority: .. productionlist:: - u_expr: `power` \| "-" `u_expr` \| "+" `u_expr` \| "~" `u_expr` + u_expr: `power` | "-" `u_expr` | "+" `u_expr` | "~" `u_expr` .. index:: single: negation @@ -859,9 +859,9 @@ operators and one for additive operators: .. productionlist:: - m_expr: `u_expr` \| `m_expr` "\*" `u_expr` \| `m_expr` "//" `u_expr` \| `m_expr` "/" `u_expr` - : \| `m_expr` "%" `u_expr` - a_expr: `m_expr` \| `a_expr` "+" `m_expr` \| `a_expr` "-" `m_expr` + m_expr: `u_expr` | `m_expr` "*" `u_expr` | `m_expr` "//" `u_expr` | `m_expr` "/" `u_expr` + : | `m_expr` "%" `u_expr` + a_expr: `m_expr` | `a_expr` "+" `m_expr` | `a_expr` "-" `m_expr` .. index:: single: multiplication @@ -934,7 +934,7 @@ The shifting operations have lower priority than the arithmetic operations: .. productionlist:: - shift_expr: `a_expr` \| `shift_expr` ( "<<" \| ">>" ) `a_expr` + shift_expr: `a_expr` | `shift_expr` ( "<<" | ">>" ) `a_expr` These operators accept plain or long integers as arguments. The arguments are converted to a common type. They shift the first argument to the left or right @@ -959,9 +959,9 @@ Each of the three bitwise operations has a different priority level: .. productionlist:: - and_expr: `shift_expr` \| `and_expr` "&" `shift_expr` - xor_expr: `and_expr` \| `xor_expr` "^" `and_expr` - or_expr: `xor_expr` \| `or_expr` "\|" `xor_expr` + and_expr: `shift_expr` | `and_expr` "&" `shift_expr` + xor_expr: `and_expr` | `xor_expr` "^" `and_expr` + or_expr: `xor_expr` | `or_expr` "|" `xor_expr` .. index:: pair: bit-wise; and @@ -998,9 +998,9 @@ in mathematics: .. productionlist:: - comparison: `or_expr` ( `comp_operator` `or_expr` )\* - comp_operator: "<" \| ">" \| "==" \| ">=" \| "<=" \| "<>" \| "!=" - : \| "is" ["not"] \| ["not"] "in" + comparison: `or_expr` ( `comp_operator` `or_expr` )* + comp_operator: "<" | ">" | "==" | ">=" | "<=" | "<>" | "!=" + : | "is" ["not"] | ["not"] "in" Comparisons yield boolean values: ``True`` or ``False``. @@ -1124,12 +1124,12 @@ Boolean operations have the lowest priority of all Python operations: .. productionlist:: - expression: `conditional_expression` \| `lambda_form` - old_expression: `or_test` \| `old_lambda_form` + expression: `conditional_expression` | `lambda_form` + old_expression: `or_test` | `old_lambda_form` conditional_expression: `or_test` ["if" `or_test` "else" `expression`] - or_test: `and_test` \| `or_test` "or" `and_test` - and_test: `not_test` \| `and_test` "and" `not_test` - not_test: `comparison` \| "not" `not_test` + or_test: `and_test` | `or_test` "or" `and_test` + and_test: `not_test` | `and_test` "and" `not_test` + not_test: `comparison` | "not" `not_test` In the context of Boolean operations, and also when expressions are used by control flow statements, the following values are interpreted as false: @@ -1203,7 +1203,7 @@ .. index:: pair: expression; list .. productionlist:: - expression_list: `expression` ( "," `expression` )\* [","] + expression_list: `expression` ( "," `expression` )* [","] .. index:: object: tuple @@ -1306,7 +1306,7 @@ +-----------------------------------------------+-------------------------------------+ | ``{key:datum...}`` | Dictionary display | +-----------------------------------------------+-------------------------------------+ -| ```expressions...``\ ` | String conversion | +| ```expressions...``` | String conversion | +-----------------------------------------------+-------------------------------------+ .. rubric:: Footnotes Modified: doctools/trunk/Doc-26/reference/introduction.rst ============================================================================== --- doctools/trunk/Doc-26/reference/introduction.rst (original) +++ doctools/trunk/Doc-26/reference/introduction.rst Thu Aug 2 14:32:13 2007 @@ -98,7 +98,7 @@ notation. This uses the following style of definition: .. productionlist:: * - name: `lc_letter` (`lc_letter` \| "_")\* + name: `lc_letter` (`lc_letter` | "_")* lc_letter: "a"..."z" The first line says that a ``name`` is an ``lc_letter`` followed by a sequence Modified: doctools/trunk/Doc-26/reference/lexical_analysis.rst ============================================================================== --- doctools/trunk/Doc-26/reference/lexical_analysis.rst (original) +++ doctools/trunk/Doc-26/reference/lexical_analysis.rst Thu Aug 2 14:32:13 2007 @@ -323,8 +323,8 @@ definitions: .. productionlist:: - identifier: (`letter`\|"_") (`letter` \| `digit` \| "_")\* - letter: `lowercase` \| `uppercase` + identifier: (`letter`|"_") (`letter` | `digit` | "_")\* + letter: `lowercase` | `uppercase` lowercase: "a"..."z" uppercase: "A"..."Z" digit: "0"..."9" @@ -433,13 +433,13 @@ .. index:: single: ASCII at ASCII .. productionlist:: - stringliteral: [`stringprefix`](`shortstring` \| `longstring`) - stringprefix: "r" \| "u" \| "ur" \| "R" \| "U" \| "UR" \| "Ur" \| "uR" - shortstring: "'" `shortstringitem`\* "'" \| '"' `shortstringitem`\* '"' - longstring: ""'" `longstringitem`\* ""'" - : \| '"""' `longstringitem`\* '"""' - shortstringitem: `shortstringchar` \| `escapeseq` - longstringitem: `longstringchar` \| `escapeseq` + stringliteral: [`stringprefix`](`shortstring` | `longstring`) + stringprefix: "r" | "u" | "ur" | "R" | "U" | "UR" | "Ur" | "uR" + shortstring: "'" `shortstringitem`* "'" | '"' `shortstringitem`* '"' + longstring: ""'" `longstringitem`* ""'" + : | '"""' `longstringitem`* '"""' + shortstringitem: `shortstringchar` | `escapeseq` + longstringitem: `longstringchar` | `escapeseq` shortstringchar: longstringchar: escapeseq: "\" @@ -640,14 +640,14 @@ definitions: .. productionlist:: - longinteger: `integer` ("l" \| "L") - integer: `decimalinteger` \| `octinteger` \| `hexinteger` - decimalinteger: `nonzerodigit` `digit`\* \| "0" - octinteger: "0" `octdigit`\ + - hexinteger: "0" ("x" \| "X") `hexdigit`\ + + longinteger: `integer` ("l" | "L") + integer: `decimalinteger` | `octinteger` | `hexinteger` + decimalinteger: `nonzerodigit` `digit`* | "0" + octinteger: "0" `octdigit`+ + hexinteger: "0" ("x" | "X") `hexdigit`+ nonzerodigit: "1"..."9" octdigit: "0"..."7" - hexdigit: `digit` \| "a"..."f" \| "A"..."F" + hexdigit: `digit` | "a"..."f" | "A"..."F" Although both lower case ``'l'`` and upper case ``'L'`` are allowed as suffix for long integers, it is strongly recommended to always use ``'L'``, since the @@ -674,12 +674,12 @@ Floating point literals are described by the following lexical definitions: .. productionlist:: - floatnumber: `pointfloat` \| `exponentfloat` - pointfloat: [`intpart`] `fraction` \| `intpart` "." - exponentfloat: (`intpart` \| `pointfloat`) `exponent` - intpart: `digit`\ + - fraction: "." `digit`\ + - exponent: ("e" \| "E") ["+" \| "-"] `digit`\ + + floatnumber: `pointfloat` | `exponentfloat` + pointfloat: [`intpart`] `fraction` | `intpart` "." + exponentfloat: (`intpart` | `pointfloat`) `exponent` + intpart: `digit`+ + fraction: "." `digit`+ + exponent: ("e" | "E") ["+" | "-"] `digit`+ Note that the integer and exponent parts of floating point numbers can look like octal integers, but are interpreted using radix 10. For example, ``077e010`` is @@ -702,7 +702,7 @@ Imaginary literals are described by the following lexical definitions: .. productionlist:: - imagnumber: (`floatnumber` \| `intpart`) ("j" \| "J") + imagnumber: (`floatnumber` | `intpart`) ("j" | "J") An imaginary literal yields a complex number with a real part of 0.0. Complex numbers are represented as a pair of floating point numbers and have the same Modified: doctools/trunk/Doc-26/reference/simple_stmts.rst ============================================================================== --- doctools/trunk/Doc-26/reference/simple_stmts.rst (original) +++ doctools/trunk/Doc-26/reference/simple_stmts.rst Thu Aug 2 14:32:13 2007 @@ -13,20 +13,20 @@ .. productionlist:: simple_stmt: `expression_stmt` - : \| `assert_stmt` - : \| `assignment_stmt` - : \| `augmented_assignment_stmt` - : \| `pass_stmt` - : \| `del_stmt` - : \| `print_stmt` - : \| `return_stmt` - : \| `yield_stmt` - : \| `raise_stmt` - : \| `break_stmt` - : \| `continue_stmt` - : \| `import_stmt` - : \| `global_stmt` - : \| `exec_stmt` + : | `assert_stmt` + : | `assignment_stmt` + : | `augmented_assignment_stmt` + : | `pass_stmt` + : | `del_stmt` + : | `print_stmt` + : | `return_stmt` + : | `yield_stmt` + : | `raise_stmt` + : | `break_stmt` + : | `continue_stmt` + : | `import_stmt` + : | `global_stmt` + : | `exec_stmt` .. _exprstmts: @@ -124,14 +124,14 @@ attributes or items of mutable objects: .. productionlist:: - assignment_stmt: (`target_list` "=")+ (`expression_list` \| `yield_expression`) - target_list: `target` ("," `target`)\* [","] + assignment_stmt: (`target_list` "=")+ (`expression_list` | `yield_expression`) + target_list: `target` ("," `target`)* [","] target: `identifier` - : \| "(" `target_list` ")" - : \| "[" `target_list` "]" - : \| `attributeref` - : \| `subscription` - : \| `slicing` + : | "(" `target_list` ")" + : | "[" `target_list` "]" + : | `attributeref` + : | `subscription` + : | `slicing` (See section :ref:`primaries` for the syntax definitions for the last three symbols.) @@ -272,9 +272,9 @@ operation and an assignment statement: .. productionlist:: - augmented_assignment_stmt: `target` `augop` (`expression_list` \| `yield_expression`) - augop: "+=" \| "-=" \| "\*=" \| "/=" \| "%=" \| "\*\*=" - : \| ">>=" \| "<<=" \| "&=" \| "^=" \| "\|=" + augmented_assignment_stmt: `target` `augop` (`expression_list` | `yield_expression`) + augop: "+=" | "-=" | "*=" | "/=" | "%=" | "**=" + : | ">>=" | "<<=" | "&=" | "^=" | "|=" (See section :ref:`primaries` for the syntax definitions for the last three symbols.) @@ -378,8 +378,8 @@ .. index:: statement: print .. productionlist:: - print_stmt: "print" ([`expression` ("," `expression`)\* [","] - : \| ">>" `expression` [("," `expression`)+ [","]) + print_stmt: "print" ([`expression` ("," `expression`)* [","] + : | ">>" `expression` [("," `expression`)+ [","]) :keyword:`print` evaluates each expression in turn and writes the resulting object to standard output (see below). If an object is not a string, it is @@ -645,14 +645,14 @@ keyword: from .. productionlist:: - import_stmt: "import" `module` ["as" `name`] ( "," `module` ["as" `name`] )\* - : \| "from" `relative_module` "import" `identifier` ["as" `name`] - : ( "," `identifier` ["as" `name`] )\* - : \| "from" `relative_module` "import" "(" `identifier` ["as" `name`] - : ( "," `identifier` ["as" `name`] )\* [","] ")" - : \| "from" `module` "import" "\*" - module: (`identifier` ".")\* `identifier` - relative_module: "."\* `module` \| "."+ + import_stmt: "import" `module` ["as" `name`] ( "," `module` ["as" `name`] )* + : | "from" `relative_module` "import" `identifier` ["as" `name`] + : ( "," `identifier` ["as" `name`] )* + : | "from" `relative_module` "import" "(" `identifier` ["as" `name`] + : ( "," `identifier` ["as" `name`] )* [","] ")" + : | "from" `module` "import" "*" + module: (`identifier` ".")* `identifier` + relative_module: "."* `module` | "."+ name: `identifier` Import statements are executed in two steps: (1) find a module, and initialize @@ -781,9 +781,9 @@ .. productionlist:: * future_statement: "from" "__future__" "import" feature ["as" name] - : ("," feature ["as" name])\* - : \| "from" "__future__" "import" "(" feature ["as" name] - : ("," feature ["as" name])\* [","] ")" + : ("," feature ["as" name])* + : | "from" "__future__" "import" "(" feature ["as" name] + : ("," feature ["as" name])* [","] ")" feature: identifier name: identifier @@ -851,7 +851,7 @@ .. index:: statement: global .. productionlist:: - global_stmt: "global" `identifier` ("," `identifier`)\* + global_stmt: "global" `identifier` ("," `identifier`)* .. index:: triple: global; name; binding Modified: doctools/trunk/Doc-26/reference/toplevel_components.rst ============================================================================== --- doctools/trunk/Doc-26/reference/toplevel_components.rst (original) +++ doctools/trunk/Doc-26/reference/toplevel_components.rst Thu Aug 2 14:32:13 2007 @@ -66,7 +66,7 @@ All input read from non-interactive files has the same form: .. productionlist:: - file_input: (NEWLINE \| `statement`)\* + file_input: (NEWLINE | `statement`)* This syntax is used in the following situations: @@ -85,7 +85,7 @@ Input in interactive mode is parsed using the following grammar: .. productionlist:: - interactive_input: [`stmt_list`] NEWLINE \| `compound_stmt` NEWLINE + interactive_input: [`stmt_list`] NEWLINE | `compound_stmt` NEWLINE Note that a (top-level) compound statement must be followed by a blank line in interactive mode; this is needed to help the parser detect the end of the input. @@ -104,7 +104,7 @@ string argument to :func:`eval` must have the following form: .. productionlist:: - eval_input: `expression_list` NEWLINE\* + eval_input: `expression_list` NEWLINE* .. index:: builtin: input Modified: doctools/trunk/Doc-3k/TODO ============================================================================== --- doctools/trunk/Doc-3k/TODO (original) +++ doctools/trunk/Doc-3k/TODO Thu Aug 2 14:32:13 2007 @@ -3,14 +3,11 @@ * fix all references and links marked with `XXX` * adjust all literal include paths -* remove all non-literal includes * fix all duplicate labels and undefined label references * split very large files and add toctrees * integrate standalone HOWTOs * find out which files get "comments disabled" metadata -* double backslashes in production lists * add synopses for each module * write "About these documents" * finish "Documenting Python" * extend copyright.rst -* fix :file: and |version| in install Modified: doctools/trunk/Doc-3k/documenting/markup.rst ============================================================================== --- doctools/trunk/Doc-3k/documenting/markup.rst (original) +++ doctools/trunk/Doc-3k/documenting/markup.rst Thu Aug 2 14:32:13 2007 @@ -673,7 +673,7 @@ triple Likewise, ``triple: module; search; path`` is a shortcut that creates three index entries, which are ``module; search path``, ``search; path, module`` and - ``path; module search``. + ``path; module search``. module, keyword, operator, object, exception, statement, builtin These all create two index entries. For example, ``module: hashlib`` creates the entries ``module; hashlib`` and ``hashlib; module``. @@ -700,9 +700,10 @@ The definition can contain token names which are marked as interpreted text (e.g. ``sum ::= `integer` "+" `integer```) -- this generates cross-references - to the productions of these tokens. Note that vertical bars used to indicate - alternatives must be escaped with backslashes because otherwise they would - indicate a substitution reference to the reST parser. + to the productions of these tokens. + + Note that no further reST parsing is done in the production, so that you + don't have to escape ``*`` or ``|`` characters. .. XXX describe optional first parameter @@ -710,13 +711,13 @@ The following is an example taken from the Python Reference Manual:: .. productionlist:: - try_stmt: try1_stmt \| try2_stmt - try1_stmt: "try" ":" :token:`suite` - : ("except" [:token:`expression` ["," :token:`target`]] ":" :token:`suite`)+ - : ["else" ":" :token:`suite`] - : ["finally" ":" :token:`suite`] - try2_stmt: "try" ":" :token:`suite` - : "finally" ":" :token:`suite` + try_stmt: try1_stmt | try2_stmt + try1_stmt: "try" ":" `suite` + : ("except" [`expression` ["," `target`]] ":" `suite`)+ + : ["else" ":" `suite`] + : ["finally" ":" `suite`] + try2_stmt: "try" ":" `suite` + : "finally" ":" `suite` Substitutions Modified: doctools/trunk/Doc-3k/install/index.rst ============================================================================== --- doctools/trunk/Doc-3k/install/index.rst (original) +++ doctools/trunk/Doc-3k/install/index.rst Thu Aug 2 14:32:13 2007 @@ -246,19 +246,15 @@ Unix-based), it also depends on whether the module distribution being installed is pure Python or contains extensions ("non-pure"): -+-----------------+------------------------------------+--------------------------------------+-------+ -| Platform | Standard installation | Default value | Notes | -| | location | | | -+=================+====================================+======================================+=======+ -| Unix (pure) | :file:`{prefix}/lib/python|version | :file:`/usr/local/lib/python|version | \(1) | -| | |/site-packages` | |/site-packages` | | -+-----------------+------------------------------------+--------------------------------------+-------+ -| Unix (non-pure) | :file:`{exec- | :file:`/usr/local/lib/python|version | \(1) | -| | prefix}/lib/python|version | |/site-packages` | | -| | |/site-packages` | | | -+-----------------+------------------------------------+--------------------------------------+-------+ -| Windows | :file:`{prefix}` | :file:`C:\\Python` | \(2) | -+-----------------+------------------------------------+--------------------------------------+-------+ ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ +| Platform | Standard installation location | Default value | Notes | ++=================+=====================================================+==================================================+=======+ +| Unix (pure) | :file:`{prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1) | ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ +| Unix (non-pure) | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1) | ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ +| Windows | :file:`{prefix}` | :file:`C:\\Python` | \(2) | ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ Notes: @@ -346,17 +342,17 @@ The :option:`--home` option defines the installation base directory. Files are installed to the following directories under the installation base as follows: -+------------------------------+-----------------------------------+-----------------------------+ -| Type of file | Installation Directory | Override option | -+==============================+===================================+=============================+ -| pure module distribution | :file:`{home}`:file:`/lib/python` | :option:`--install-purelib` | -+------------------------------+-----------------------------------+-----------------------------+ -| non-pure module distribution | :file:`{home}`:file:`/lib/python` | :option:`--install-platlib` | -+------------------------------+-----------------------------------+-----------------------------+ -| scripts | :file:`{home}`:file:`/bin` | :option:`--install-scripts` | -+------------------------------+-----------------------------------+-----------------------------+ -| data | :file:`{home}`:file:`/share` | :option:`--install-data` | -+------------------------------+-----------------------------------+-----------------------------+ ++------------------------------+---------------------------+-----------------------------+ +| Type of file | Installation Directory | Override option | ++==============================+===========================+=============================+ +| pure module distribution | :file:`{home}/lib/python` | :option:`--install-purelib` | ++------------------------------+---------------------------+-----------------------------+ +| non-pure module distribution | :file:`{home}/lib/python` | :option:`--install-platlib` | ++------------------------------+---------------------------+-----------------------------+ +| scripts | :file:`{home}/bin` | :option:`--install-scripts` | ++------------------------------+---------------------------+-----------------------------+ +| data | :file:`{home}/share` | :option:`--install-data` | ++------------------------------+---------------------------+-----------------------------+ .. versionchanged:: 2.4 The :option:`--home` option used to be supported only on Unix. @@ -399,20 +395,17 @@ executables, etc.) If :option:`--exec-prefix` is not supplied, it defaults to :option:`--prefix`. Files are installed as follows: -+------------------------------+----------------------------------------+-----------------------------+ -| Type of file | Installation Directory | Override option | -+==============================+========================================+=============================+ -| pure module distribution | :file:`{prefix}`:file:`/lib/python2.{X | :option:`--install-purelib` | -| | }/site-packages` | | -+------------------------------+----------------------------------------+-----------------------------+ -| non-pure module distribution | :file:`{exec- | :option:`--install-platlib` | -| | prefix}`:file:`/lib/python2.{X | | -| | }/site-packages` | | -+------------------------------+----------------------------------------+-----------------------------+ -| scripts | :file:`{prefix}`:file:`/bin` | :option:`--install-scripts` | -+------------------------------+----------------------------------------+-----------------------------+ -| data | :file:`{prefix}`:file:`/share` | :option:`--install-data` | -+------------------------------+----------------------------------------+-----------------------------+ ++------------------------------+-----------------------------------------------------+-----------------------------+ +| Type of file | Installation Directory | Override option | ++==============================+=====================================================+=============================+ +| pure module distribution | :file:`{prefix}/lib/python{X.Y}/site-packages` | :option:`--install-purelib` | ++------------------------------+-----------------------------------------------------+-----------------------------+ +| non-pure module distribution | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :option:`--install-platlib` | ++------------------------------+-----------------------------------------------------+-----------------------------+ +| scripts | :file:`{prefix}/bin` | :option:`--install-scripts` | ++------------------------------+-----------------------------------------------------+-----------------------------+ +| data | :file:`{prefix}/share` | :option:`--install-data` | ++------------------------------+-----------------------------------------------------+-----------------------------+ There is no requirement that :option:`--prefix` or :option:`--exec-prefix` actually point to an alternate Python installation; if the directories listed @@ -455,17 +448,17 @@ :option:`--exec-prefix` option is not supported under Windows. Files are installed as follows: -+------------------------------+-----------------------------------+-----------------------------+ -| Type of file | Installation Directory | Override option | -+==============================+===================================+=============================+ -| pure module distribution | :file:`{prefix}`:file:`` | :option:`--install-purelib` | -+------------------------------+-----------------------------------+-----------------------------+ -| non-pure module distribution | :file:`{prefix}`:file:`` | :option:`--install-platlib` | -+------------------------------+-----------------------------------+-----------------------------+ -| scripts | :file:`{prefix}`:file:`\\Scripts` | :option:`--install-scripts` | -+------------------------------+-----------------------------------+-----------------------------+ -| data | :file:`{prefix}`:file:`\\Data` | :option:`--install-data` | -+------------------------------+-----------------------------------+-----------------------------+ ++------------------------------+---------------------------+-----------------------------+ +| Type of file | Installation Directory | Override option | ++==============================+===========================+=============================+ +| pure module distribution | :file:`{prefix}` | :option:`--install-purelib` | ++------------------------------+---------------------------+-----------------------------+ +| non-pure module distribution | :file:`{prefix}` | :option:`--install-platlib` | ++------------------------------+---------------------------+-----------------------------+ +| scripts | :file:`{prefix}\\Scripts` | :option:`--install-scripts` | ++------------------------------+---------------------------+-----------------------------+ +| data | :file:`{prefix}\\Data` | :option:`--install-data` | ++------------------------------+---------------------------+-----------------------------+ .. _custom-install: @@ -625,12 +618,12 @@ .. % $ <-- bow to font-lock The expected convention for locally installed packages is to put them in the -:file:`.../site-packages/` directory, but you may want to install Python modules -into some arbitrary directory. For example, your site may have a convention of -keeping all software related to the web server under :file:`/www`. Add-on -Python modules might then belong in :file:`/www/python`, and in order to import -them, this directory must be added to ``sys.path``. There are several different -ways to add the directory. +:file:`{...}/site-packages/` directory, but you may want to install Python +modules into some arbitrary directory. For example, your site may have a +convention of keeping all software related to the web server under :file:`/www`. +Add-on Python modules might then belong in :file:`/www/python`, and in order to +import them, this directory must be added to ``sys.path``. There are several +different ways to add the directory. The most convenient way is to add a path configuration file to a directory that's already on Python's path, usually to the :file:`.../site-packages/` @@ -921,7 +914,7 @@ The :file:`coff2omf` program comes with the Borland compiler. The file :file:`python25.lib` is in the :file:`Libs` directory of your Python -installation. If your extension uses other libraries (zlib,...) you have to +installation. If your extension uses other libraries (zlib, ...) you have to convert them too. The converted files have to reside in the same directories as the normal Modified: doctools/trunk/Doc-3k/reference/compound_stmts.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/compound_stmts.rst (original) +++ doctools/trunk/Doc-3k/reference/compound_stmts.rst Thu Aug 2 14:32:13 2007 @@ -44,15 +44,15 @@ .. productionlist:: compound_stmt: `if_stmt` - : \| `while_stmt` - : \| `for_stmt` - : \| `try_stmt` - : \| `with_stmt` - : \| `funcdef` - : \| `classdef` - suite: `stmt_list` NEWLINE \| NEWLINE INDENT `statement`\ + DEDENT - statement: `stmt_list` NEWLINE \| `compound_stmt` - stmt_list: `simple_stmt` (";" `simple_stmt`)\* [";"] + : | `while_stmt` + : | `for_stmt` + : | `try_stmt` + : | `with_stmt` + : | `funcdef` + : | `classdef` + suite: `stmt_list` NEWLINE | NEWLINE INDENT `statement`+ DEDENT + statement: `stmt_list` NEWLINE | `compound_stmt` + stmt_list: `simple_stmt` (";" `simple_stmt`)* [";"] .. index:: single: NEWLINE token @@ -80,7 +80,7 @@ .. productionlist:: if_stmt: "if" `expression` ":" `suite` - : ( "elif" `expression` ":" `suite` )\* + : ( "elif" `expression` ":" `suite` )* : ["else" ":" `suite`] .. index:: @@ -216,7 +216,7 @@ for a group of statements: .. productionlist:: - try_stmt: try1_stmt \| try2_stmt + try_stmt: try1_stmt | try2_stmt try1_stmt: "try" ":" `suite` : ("except" [`expression` ["," `target`]] ":" `suite`)+ : ["else" ":" `suite`] @@ -397,14 +397,14 @@ .. productionlist:: funcdef: [`decorators`] "def" `funcname` "(" [`parameter_list`] ")" ["->" `expression`]? ":" `suite` - decorators: `decorator`\ + + decorators: `decorator`+ decorator: "@" `dotted_name` ["(" [`argument_list` [","]] ")"] NEWLINE - dotted_name: `identifier` ("." `identifier`)\* - parameter_list: (`defparameter` ",")\* - : ( "\*" [`parameter`] ("," `defparameter`)\* - : [, "\*\*" `parameter`] - : \| "\*\*" `parameter` - : \| `defparameter` [","] ) + dotted_name: `identifier` ("." `identifier`)* + parameter_list: (`defparameter` ",")* + : ( "*" [`parameter`] ("," `defparameter`)* + : [, "**" `parameter`] + : | "**" `parameter` + : | `defparameter` [","] ) parameter: `identifier` [":" `expression`] defparameter: `parameter` ["=" `expression`] funcname: `identifier` Modified: doctools/trunk/Doc-3k/reference/expressions.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/expressions.rst (original) +++ doctools/trunk/Doc-3k/reference/expressions.rst Thu Aug 2 14:32:13 2007 @@ -63,10 +63,10 @@ atoms is: .. productionlist:: - atom: `identifier` \| `literal` \| `enclosure` - enclosure: `parenth_form` \| `list_display` - : \| `generator_expression` \| `dict_display` - : \| `string_conversion` \| `yield_atom` + atom: `identifier` | `literal` | `enclosure` + enclosure: `parenth_form` | `list_display` + : | `generator_expression` | `dict_display` + : | `string_conversion` | `yield_atom` .. _atom-identifiers: @@ -119,8 +119,8 @@ Python supports string literals and various numeric literals: .. productionlist:: - literal: `stringliteral` \| `integer` \| `longinteger` - : \| `floatnumber` \| `imagnumber` + literal: `stringliteral` | `integer` | `longinteger` + : | `floatnumber` | `imagnumber` Evaluation of a literal yields an object of the given type (string, integer, long integer, floating point number, complex number) with the given value. The @@ -183,11 +183,11 @@ brackets: .. productionlist:: - list_display: "[" [`expression_list` \| `list_comprehension`] "]" + list_display: "[" [`expression_list` | `list_comprehension`] "]" list_comprehension: `expression` `list_for` list_for: "for" `target_list` "in" `old_expression_list` [`list_iter`] old_expression_list: `old_expression` [("," `old_expression`)+ [","]] - list_iter: `list_for` \| `list_if` + list_iter: `list_for` | `list_if` list_if: "if" `old_expression` [`list_iter`] .. index:: @@ -219,7 +219,7 @@ .. productionlist:: generator_expression: "(" `expression` `genexpr_for` ")" genexpr_for: "for" `target_list` "in" `or_test` [`genexpr_iter`] - genexpr_iter: `genexpr_for` \| `genexpr_if` + genexpr_iter: `genexpr_for` | `genexpr_if` genexpr_if: "if" `old_expression` [`genexpr_iter`] .. index:: object: generator @@ -262,7 +262,7 @@ .. productionlist:: dict_display: "{" [`key_datum_list`] "}" - key_datum_list: `key_datum` ("," `key_datum`)\* [","] + key_datum_list: `key_datum` ("," `key_datum`)* [","] key_datum: `expression` ":" `expression` .. index:: object: dictionary @@ -425,7 +425,7 @@ syntax is: .. productionlist:: - primary: `atom` \| `attributeref` \| `subscription` \| `slicing` \| `call` + primary: `atom` | `attributeref` | `subscription` | `slicing` | `call` .. _attribute-references: @@ -517,12 +517,12 @@ :keyword:`del` statements. The syntax for a slicing: .. productionlist:: - slicing: `simple_slicing` \| `extended_slicing` + slicing: `simple_slicing` | `extended_slicing` simple_slicing: `primary` "[" `short_slice` "]" extended_slicing: `primary` "[" `slice_list` "]" - slice_list: `slice_item` ("," `slice_item`)\* [","] - slice_item: `expression` \| `proper_slice` \| `ellipsis` - proper_slice: `short_slice` \| `long_slice` + slice_list: `slice_item` ("," `slice_item`)* [","] + slice_item: `expression` | `proper_slice` | `ellipsis` + proper_slice: `short_slice` | `long_slice` short_slice: [`lower_bound`] ":" [`upper_bound`] long_slice: `short_slice` ":" [`stride`] lower_bound: `expression` @@ -581,16 +581,16 @@ .. productionlist:: call: `primary` "(" [`argument_list` [","] - : \| `expression` `genexpr_for`] ")" + : | `expression` `genexpr_for`] ")" argument_list: `positional_arguments` ["," `keyword_arguments`] - : ["," "\*" `expression`] - : ["," "\*\*" `expression`] - : \| `keyword_arguments` ["," "\*" `expression`] - : ["," "\*\*" `expression`] - : \| "\*" `expression` ["," "\*\*" `expression`] - : \| "\*\*" `expression` - positional_arguments: `expression` ("," `expression`)\* - keyword_arguments: `keyword_item` ("," `keyword_item`)\* + : ["," "*" `expression`] + : ["," "**" `expression`] + : | `keyword_arguments` ["," "*" `expression`] + : ["," "**" `expression`] + : | "*" `expression` ["," "**" `expression`] + : | "**" `expression` + positional_arguments: `expression` ("," `expression`)* + keyword_arguments: `keyword_item` ("," `keyword_item`)* keyword_item: `identifier` "=" `expression` A trailing comma may be present after the positional and keyword arguments but @@ -736,7 +736,7 @@ less tightly than unary operators on its right. The syntax is: .. productionlist:: - power: `primary` ["\*\*" `u_expr`] + power: `primary` ["**" `u_expr`] Thus, in an unparenthesized sequence of power and unary operators, the operators are evaluated from right to left (this does not constrain the evaluation order @@ -772,7 +772,7 @@ All unary arithmetic (and bit-wise) operations have the same priority: .. productionlist:: - u_expr: `power` \| "-" `u_expr` \| "+" `u_expr` \| "~" `u_expr` + u_expr: `power` | "-" `u_expr` | "+" `u_expr` | "~" `u_expr` .. index:: single: negation @@ -809,9 +809,9 @@ operators and one for additive operators: .. productionlist:: - m_expr: `u_expr` \| `m_expr` "\*" `u_expr` \| `m_expr` "//" `u_expr` \| `m_expr` "/" `u_expr` - : \| `m_expr` "%" `u_expr` - a_expr: `m_expr` \| `a_expr` "+" `m_expr` \| `a_expr` "-" `m_expr` + m_expr: `u_expr` | `m_expr` "*" `u_expr` | `m_expr` "//" `u_expr` | `m_expr` "/" `u_expr` + : | `m_expr` "%" `u_expr` + a_expr: `m_expr` | `a_expr` "+" `m_expr` | `a_expr` "-" `m_expr` .. index:: single: multiplication @@ -884,7 +884,7 @@ The shifting operations have lower priority than the arithmetic operations: .. productionlist:: - shift_expr: `a_expr` \| `shift_expr` ( "<<" \| ">>" ) `a_expr` + shift_expr: `a_expr` | `shift_expr` ( "<<" | ">>" ) `a_expr` These operators accept plain or long integers as arguments. The arguments are converted to a common type. They shift the first argument to the left or right @@ -909,9 +909,9 @@ Each of the three bitwise operations has a different priority level: .. productionlist:: - and_expr: `shift_expr` \| `and_expr` "&" `shift_expr` - xor_expr: `and_expr` \| `xor_expr` "^" `and_expr` - or_expr: `xor_expr` \| `or_expr` "\|" `xor_expr` + and_expr: `shift_expr` | `and_expr` "&" `shift_expr` + xor_expr: `and_expr` | `xor_expr` "^" `and_expr` + or_expr: `xor_expr` | `or_expr` "|" `xor_expr` .. index:: pair: bit-wise; and @@ -948,9 +948,9 @@ in mathematics: .. productionlist:: - comparison: `or_expr` ( `comp_operator` `or_expr` )\* - comp_operator: "<" \| ">" \| "==" \| ">=" \| "<=" \| "!=" - : \| "is" ["not"] \| ["not"] "in" + comparison: `or_expr` ( `comp_operator` `or_expr` )* + comp_operator: "<" | ">" | "==" | ">=" | "<=" | "!=" + : | "is" ["not"] | ["not"] "in" Comparisons yield boolean values: ``True`` or ``False``. @@ -1070,12 +1070,12 @@ Boolean operations have the lowest priority of all Python operations: .. productionlist:: - expression: `conditional_expression` \| `lambda_form` - old_expression: `or_test` \| `old_lambda_form` + expression: `conditional_expression` | `lambda_form` + old_expression: `or_test` | `old_lambda_form` conditional_expression: `or_test` ["if" `or_test` "else" `expression`] - or_test: `and_test` \| `or_test` "or" `and_test` - and_test: `not_test` \| `and_test` "and" `not_test` - not_test: `comparison` \| "not" `not_test` + or_test: `and_test` | `or_test` "or" `and_test` + and_test: `not_test` | `and_test` "and" `not_test` + not_test: `comparison` | "not" `not_test` In the context of Boolean operations, and also when expressions are used by control flow statements, the following values are interpreted as false: @@ -1149,7 +1149,7 @@ .. index:: pair: expression; list .. productionlist:: - expression_list: `expression` ( "," `expression` )\* [","] + expression_list: `expression` ( "," `expression` )* [","] .. index:: object: tuple @@ -1251,8 +1251,6 @@ +----------------------------------------------+-------------------------------------+ | ``{key:datum...}`` | Dictionary display | +----------------------------------------------+-------------------------------------+ -| ```expressions...``\ ` | String conversion | -+----------------------------------------------+-------------------------------------+ .. rubric:: Footnotes Modified: doctools/trunk/Doc-3k/reference/introduction.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/introduction.rst (original) +++ doctools/trunk/Doc-3k/reference/introduction.rst Thu Aug 2 14:32:13 2007 @@ -98,7 +98,7 @@ notation. This uses the following style of definition: .. productionlist:: * - name: `lc_letter` (`lc_letter` \| "_")\* + name: `lc_letter` (`lc_letter` | "_")* lc_letter: "a"..."z" The first line says that a ``name`` is an ``lc_letter`` followed by a sequence Modified: doctools/trunk/Doc-3k/reference/lexical_analysis.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/lexical_analysis.rst (original) +++ doctools/trunk/Doc-3k/reference/lexical_analysis.rst Thu Aug 2 14:32:13 2007 @@ -323,8 +323,8 @@ definitions: .. productionlist:: - identifier: (`letter`\|"_") (`letter` \| `digit` \| "_")\* - letter: `lowercase` \| `uppercase` + identifier: (`letter`|"_") (`letter` | `digit` | "_")\* + letter: `lowercase` | `uppercase` lowercase: "a"..."z" uppercase: "A"..."Z" digit: "0"..."9" @@ -432,13 +432,13 @@ .. index:: single: ASCII at ASCII .. productionlist:: - stringliteral: [`stringprefix`](`shortstring` \| `longstring`) - stringprefix: "r" \| "u" \| "ur" \| "R" \| "U" \| "UR" \| "Ur" \| "uR" - shortstring: "'" `shortstringitem`\* "'" \| '"' `shortstringitem`\* '"' - longstring: ""'" `longstringitem`\* ""'" - : \| '"""' `longstringitem`\* '"""' - shortstringitem: `shortstringchar` \| `escapeseq` - longstringitem: `longstringchar` \| `escapeseq` + stringliteral: [`stringprefix`](`shortstring` | `longstring`) + stringprefix: "r" | "u" | "ur" | "R" | "U" | "UR" | "Ur" | "uR" + shortstring: "'" `shortstringitem`* "'" | '"' `shortstringitem`* '"' + longstring: ""'" `longstringitem`* ""'" + : | '"""' `longstringitem`* '"""' + shortstringitem: `shortstringchar` | `escapeseq` + longstringitem: `longstringchar` | `escapeseq` shortstringchar: longstringchar: escapeseq: "\" @@ -639,14 +639,14 @@ Integer literals are described by the following lexical definitions: .. productionlist:: - integer: `decimalinteger` \| `octinteger` \| `hexinteger` - decimalinteger: `nonzerodigit` `digit`\* \| "0"+ - octinteger: "0" ("o" \| "O") `octdigit`\ + - hexinteger: "0" ("x" \| "X") `hexdigit`\ + - bininteger: "0" ("b" \| "B") `bindigit`\ + + integer: `decimalinteger` | `octinteger` | `hexinteger` + decimalinteger: `nonzerodigit` `digit`* | "0"+ + octinteger: "0" ("o" | "O") `octdigit`+ + hexinteger: "0" ("x" | "X") `hexdigit`+ + bininteger: "0" ("b" | "B") `bindigit`+ nonzerodigit: "1"..."9" octdigit: "0"..."7" - hexdigit: `digit` \| "a"..."f" \| "A"..."F" + hexdigit: `digit` | "a"..."f" | "A"..."F" bindigit: "0"..."1" Plain integer literals that are above the largest representable plain integer @@ -673,12 +673,12 @@ Floating point literals are described by the following lexical definitions: .. productionlist:: - floatnumber: `pointfloat` \| `exponentfloat` - pointfloat: [`intpart`] `fraction` \| `intpart` "." - exponentfloat: (`intpart` \| `pointfloat`) `exponent` - intpart: `digit`\ + - fraction: "." `digit`\ + - exponent: ("e" \| "E") ["+" \| "-"] `digit`\ + + floatnumber: `pointfloat` | `exponentfloat` + pointfloat: [`intpart`] `fraction` | `intpart` "." + exponentfloat: (`intpart` | `pointfloat`) `exponent` + intpart: `digit`+ + fraction: "." `digit`+ + exponent: ("e" | "E") ["+" | "-"] `digit`+ Note that the integer and exponent parts are always interpreted using radix 10. For example, ``077e010`` is legal, and denotes the same number as ``77e10``. The @@ -700,7 +700,7 @@ Imaginary literals are described by the following lexical definitions: .. productionlist:: - imagnumber: (`floatnumber` \| `intpart`) ("j" \| "J") + imagnumber: (`floatnumber` | `intpart`) ("j" | "J") An imaginary literal yields a complex number with a real part of 0.0. Complex numbers are represented as a pair of floating point numbers and have the same Modified: doctools/trunk/Doc-3k/reference/simple_stmts.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/simple_stmts.rst (original) +++ doctools/trunk/Doc-3k/reference/simple_stmts.rst Thu Aug 2 14:32:13 2007 @@ -13,18 +13,18 @@ .. productionlist:: simple_stmt: `expression_stmt` - : \| `assert_stmt` - : \| `assignment_stmt` - : \| `augmented_assignment_stmt` - : \| `pass_stmt` - : \| `del_stmt` - : \| `return_stmt` - : \| `yield_stmt` - : \| `raise_stmt` - : \| `break_stmt` - : \| `continue_stmt` - : \| `import_stmt` - : \| `global_stmt` + : | `assert_stmt` + : | `assignment_stmt` + : | `augmented_assignment_stmt` + : | `pass_stmt` + : | `del_stmt` + : | `return_stmt` + : | `yield_stmt` + : | `raise_stmt` + : | `break_stmt` + : | `continue_stmt` + : | `import_stmt` + : | `global_stmt` .. _exprstmts: @@ -122,14 +122,14 @@ attributes or items of mutable objects: .. productionlist:: - assignment_stmt: (`target_list` "=")+ (`expression_list` \| `yield_expression`) - target_list: `target` ("," `target`)\* [","] + assignment_stmt: (`target_list` "=")+ (`expression_list` | `yield_expression`) + target_list: `target` ("," `target`)* [","] target: `identifier` - : \| "(" `target_list` ")" - : \| "[" `target_list` "]" - : \| `attributeref` - : \| `subscription` - : \| `slicing` + : | "(" `target_list` ")" + : | "[" `target_list` "]" + : | `attributeref` + : | `subscription` + : | `slicing` (See section :ref:`primaries` for the syntax definitions for the last three symbols.) @@ -270,9 +270,9 @@ operation and an assignment statement: .. productionlist:: - augmented_assignment_stmt: `target` `augop` (`expression_list` \| `yield_expression`) - augop: "+=" \| "-=" \| "\*=" \| "/=" \| "%=" \| "\*\*=" - : \| ">>=" \| "<<=" \| "&=" \| "^=" \| "\|=" + augmented_assignment_stmt: `target` `augop` (`expression_list` | `yield_expression`) + augop: "+=" | "-=" | "*=" | "/=" | "%=" | "**=" + : | ">>=" | "<<=" | "&=" | "^=" | "|=" (See section :ref:`primaries` for the syntax definitions for the last three symbols.) @@ -582,14 +582,14 @@ keyword: from .. productionlist:: - import_stmt: "import" `module` ["as" `name`] ( "," `module` ["as" `name`] )\* - : \| "from" `relative_module` "import" `identifier` ["as" `name`] - : ( "," `identifier` ["as" `name`] )\* - : \| "from" `relative_module` "import" "(" `identifier` ["as" `name`] - : ( "," `identifier` ["as" `name`] )\* [","] ")" - : \| "from" `module` "import" "\*" - module: (`identifier` ".")\* `identifier` - relative_module: "."\* `module` \| "."+ + import_stmt: "import" `module` ["as" `name`] ( "," `module` ["as" `name`] )* + : | "from" `relative_module` "import" `identifier` ["as" `name`] + : ( "," `identifier` ["as" `name`] )* + : | "from" `relative_module` "import" "(" `identifier` ["as" `name`] + : ( "," `identifier` ["as" `name`] )* [","] ")" + : | "from" `module` "import" "*" + module: (`identifier` ".")* `identifier` + relative_module: "."* `module` | "."+ name: `identifier` Import statements are executed in two steps: (1) find a module, and initialize @@ -718,9 +718,9 @@ .. productionlist:: * future_statement: "from" "__future__" "import" feature ["as" name] - : ("," feature ["as" name])\* - : \| "from" "__future__" "import" "(" feature ["as" name] - : ("," feature ["as" name])\* [","] ")" + : ("," feature ["as" name])* + : | "from" "__future__" "import" "(" feature ["as" name] + : ("," feature ["as" name])* [","] ")" feature: identifier name: identifier @@ -788,7 +788,7 @@ .. index:: statement: global .. productionlist:: - global_stmt: "global" `identifier` ("," `identifier`)\* + global_stmt: "global" `identifier` ("," `identifier`)* .. index:: triple: global; name; binding Modified: doctools/trunk/Doc-3k/reference/toplevel_components.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/toplevel_components.rst (original) +++ doctools/trunk/Doc-3k/reference/toplevel_components.rst Thu Aug 2 14:32:13 2007 @@ -66,7 +66,7 @@ All input read from non-interactive files has the same form: .. productionlist:: - file_input: (NEWLINE \| `statement`)\* + file_input: (NEWLINE | `statement`)* This syntax is used in the following situations: @@ -85,7 +85,7 @@ Input in interactive mode is parsed using the following grammar: .. productionlist:: - interactive_input: [`stmt_list`] NEWLINE \| `compound_stmt` NEWLINE + interactive_input: [`stmt_list`] NEWLINE | `compound_stmt` NEWLINE Note that a (top-level) compound statement must be followed by a blank line in interactive mode; this is needed to help the parser detect the end of the input. @@ -104,7 +104,7 @@ string argument to :func:`eval` must have the following form: .. productionlist:: - eval_input: `expression_list` NEWLINE\* + eval_input: `expression_list` NEWLINE* .. index:: builtin: input From python-checkins at python.org Thu Aug 2 15:06:26 2007 From: python-checkins at python.org (georg.brandl) Date: Thu, 2 Aug 2007 15:06:26 +0200 (CEST) Subject: [Python-checkins] r56667 - in doctools/trunk: Doc-26/TODO Doc-26/bugs.rst Doc-26/c-api/concrete.rst Doc-26/c-api/init.rst Doc-26/c-api/utilities.rst Doc-26/extending/windows.rst Doc-26/library/curses.rst Doc-26/library/decimal.rst Doc-26/library/dis.rst Doc-26/library/filesys.rst Doc-26/library/gl.rst Doc-26/library/operator.rst Doc-26/library/optparse.rst Doc-26/library/tkinter.rst Doc-26/library/urllib2.rst Doc-26/library/xml.etree.rst Doc-26/maclib/macui.rst Doc-26/maclib/scripting.rst Doc-3k/TODO Doc-3k/bugs.rst Doc-3k/c-api/concrete.rst Doc-3k/c-api/init.rst Doc-3k/c-api/utilities.rst Doc-3k/extending/windows.rst Doc-3k/library/curses.rst Doc-3k/library/decimal.rst Doc-3k/library/filesys.rst Doc-3k/library/operator.rst Doc-3k/library/optparse.rst Doc-3k/library/tkinter.rst Doc-3k/library/urllib2.rst Doc-3k/library/xml.etree.rst Doc-3k/maclib/macui.rst Doc-3k/maclib/scripting.rst sphinx/directives.py Message-ID: <20070802130626.F00E41E4007@bag.python.org> Author: georg.brandl Date: Thu Aug 2 15:06:23 2007 New Revision: 56667 Modified: doctools/trunk/Doc-26/TODO doctools/trunk/Doc-26/bugs.rst doctools/trunk/Doc-26/c-api/concrete.rst doctools/trunk/Doc-26/c-api/init.rst doctools/trunk/Doc-26/c-api/utilities.rst doctools/trunk/Doc-26/extending/windows.rst doctools/trunk/Doc-26/library/curses.rst doctools/trunk/Doc-26/library/decimal.rst doctools/trunk/Doc-26/library/dis.rst doctools/trunk/Doc-26/library/filesys.rst doctools/trunk/Doc-26/library/gl.rst doctools/trunk/Doc-26/library/operator.rst doctools/trunk/Doc-26/library/optparse.rst doctools/trunk/Doc-26/library/tkinter.rst doctools/trunk/Doc-26/library/urllib2.rst doctools/trunk/Doc-26/library/xml.etree.rst doctools/trunk/Doc-26/maclib/macui.rst doctools/trunk/Doc-26/maclib/scripting.rst doctools/trunk/Doc-3k/TODO doctools/trunk/Doc-3k/bugs.rst doctools/trunk/Doc-3k/c-api/concrete.rst doctools/trunk/Doc-3k/c-api/init.rst doctools/trunk/Doc-3k/c-api/utilities.rst doctools/trunk/Doc-3k/extending/windows.rst doctools/trunk/Doc-3k/library/curses.rst doctools/trunk/Doc-3k/library/decimal.rst doctools/trunk/Doc-3k/library/filesys.rst doctools/trunk/Doc-3k/library/operator.rst doctools/trunk/Doc-3k/library/optparse.rst doctools/trunk/Doc-3k/library/tkinter.rst doctools/trunk/Doc-3k/library/urllib2.rst doctools/trunk/Doc-3k/library/xml.etree.rst doctools/trunk/Doc-3k/maclib/macui.rst doctools/trunk/Doc-3k/maclib/scripting.rst doctools/trunk/sphinx/directives.py Log: Fix all instances of bad reST generated by the converter. Remove a debugging print. Modified: doctools/trunk/Doc-26/TODO ============================================================================== --- doctools/trunk/Doc-26/TODO (original) +++ doctools/trunk/Doc-26/TODO Thu Aug 2 15:06:23 2007 @@ -2,7 +2,6 @@ ====================== * fix all references and links marked with `XXX` -* adjust all literal include paths * fix all duplicate labels and undefined label references * split very large files and add toctrees * integrate standalone HOWTOs Modified: doctools/trunk/Doc-26/bugs.rst ============================================================================== --- doctools/trunk/Doc-26/bugs.rst (original) +++ doctools/trunk/Doc-26/bugs.rst Thu Aug 2 15:06:23 2007 @@ -1,9 +1,9 @@ +.. _reporting-bugs: + ************** Reporting Bugs ************** -.. _reporting-bugs: - Python is a mature programming language which has established a reputation for stability. In order to maintain this reputation, the developers would like to know of any deficiencies you find in Python or its documentation. Modified: doctools/trunk/Doc-26/c-api/concrete.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/concrete.rst (original) +++ doctools/trunk/Doc-26/c-api/concrete.rst Thu Aug 2 15:06:23 2007 @@ -3040,15 +3040,15 @@ .. cfunction:: PyObject* PyCObject_FromVoidPtr(void* cobj, void (*destr)(void *)) - Create a :ctype:`PyCObject` from the ``void *``*cobj*. The *destr* function + Create a :ctype:`PyCObject` from the ``void *`` *cobj*. The *destr* function will be called when the object is reclaimed, unless it is *NULL*. .. cfunction:: PyObject* PyCObject_FromVoidPtrAndDesc(void* cobj, void* desc, void (*destr)(void *, void *)) - Create a :ctype:`PyCObject` from the :ctype:`void \*`*cobj*. The *destr* - function will be called when the object is reclaimed. The *desc* argument can be - used to pass extra callback data for the destructor function. + Create a :ctype:`PyCObject` from the :ctype:`void \*` *cobj*. The *destr* + function will be called when the object is reclaimed. The *desc* argument can + be used to pass extra callback data for the destructor function. .. cfunction:: void* PyCObject_AsVoidPtr(PyObject* self) Modified: doctools/trunk/Doc-26/c-api/init.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/init.rst (original) +++ doctools/trunk/Doc-26/c-api/init.rst Thu Aug 2 15:06:23 2007 @@ -204,7 +204,7 @@ .. cfunction:: char* Py_GetExecPrefix() - Return the *exec-prefix* for installed platform-*de*pendent files. This is + Return the *exec-prefix* for installed platform-*dependent* files. This is derived through a number of complicated rules from the program name set with :cfunc:`Py_SetProgramName` and some environment variables; for example, if the program name is ``'/usr/local/bin/python'``, the exec-prefix is Modified: doctools/trunk/Doc-26/c-api/utilities.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/utilities.rst (original) +++ doctools/trunk/Doc-26/c-api/utilities.rst Thu Aug 2 15:06:23 2007 @@ -619,9 +619,9 @@ Convert a Python object to a C variable through a *converter* function. This takes two arguments: the first is a function, the second is the address of a C variable (of arbitrary type), converted to :ctype:`void \*`. The *converter* - function in turn is called as follows: + function in turn is called as follows:: - *status*``=``*converter*``(``*object*, *address*``);`` + status = converter(object, address); where *object* is the Python object to be converted and *address* is the :ctype:`void\*` argument that was passed to the :cfunc:`PyArg_Parse\*` function. Modified: doctools/trunk/Doc-26/extending/windows.rst ============================================================================== --- doctools/trunk/Doc-26/extending/windows.rst (original) +++ doctools/trunk/Doc-26/extending/windows.rst Thu Aug 2 15:06:23 2007 @@ -68,15 +68,15 @@ #. **Build the example DLL** --- In order to check that everything is set up right, try building: -#. Select a configuration. This step is optional. Choose :menuselection:`Build - --> Configuration Manager --> Active Solution Configuration` and select either - :guilabel:`Release` or\ :guilabel:`Debug`. If you skip this step, VC++ will - use the Debug configuration by default. +#. Select a configuration. This step is optional. Choose + :menuselection:`Build --> Configuration Manager --> Active Solution Configuration` + and select either :guilabel:`Release` or :guilabel:`Debug`. If you skip this + step, VC++ will use the Debug configuration by default. #. Build the DLL. Choose :menuselection:`Build --> Build Solution`. This - creates all intermediate and result files in a subdirectory called either - :file:`Debug` or :file:`Release`, depending on which configuration you selected - in the preceding step. + creates all intermediate and result files in a subdirectory called either + :file:`Debug` or :file:`Release`, depending on which configuration you selected + in the preceding step. #. **Testing the debug-mode DLL** --- Once the Debug build has succeeded, bring up a DOS box, and change to the :file:`example_nt\\Debug` directory. You should Modified: doctools/trunk/Doc-26/library/curses.rst ============================================================================== --- doctools/trunk/Doc-26/library/curses.rst (original) +++ doctools/trunk/Doc-26/library/curses.rst Thu Aug 2 15:06:23 2007 @@ -1103,7 +1103,7 @@ Pretend *count* lines have been changed, starting with line *start*. If *changed* is supplied, it specifies whether the affected lines are marked as - having been changed (*changed*=1) or unchanged (*changed*=0). + having been changed (*changed*\ =1) or unchanged (*changed*\ =0). .. method:: window.touchwin() Modified: doctools/trunk/Doc-26/library/decimal.rst ============================================================================== --- doctools/trunk/Doc-26/library/decimal.rst (original) +++ doctools/trunk/Doc-26/library/decimal.rst Thu Aug 2 15:06:23 2007 @@ -1160,20 +1160,20 @@ Decimal FAQ ----------- -Q. It is cumbersome to type ``decimal.Decimal('1234.5')``. Is there a way to +Q. It is cumbersome to type ``decimal.Decimal('1234.5')``. Is there a way to minimize typing when using the interactive interpreter? -A. Some users abbreviate the constructor to just a single letter:: +\A. Some users abbreviate the constructor to just a single letter:: >>> D = decimal.Decimal >>> D('1.23') + D('3.45') Decimal("4.68") -Q. In a fixed-point application with two decimal places, some inputs have many +Q. In a fixed-point application with two decimal places, some inputs have many places and need to be rounded. Others are not supposed to have excess digits and need to be validated. What methods should be used? -A. The :meth:`quantize` method rounds to a fixed number of decimal places. If +A. The :meth:`quantize` method rounds to a fixed number of decimal places. If the :const:`Inexact` trap is set, it is also useful for validation:: >>> TWOPLACES = Decimal(10) ** -2 # same as Decimal('0.01') @@ -1191,36 +1191,36 @@ ... Inexact: Changed in rounding -Q. Once I have valid two place inputs, how do I maintain that invariant +Q. Once I have valid two place inputs, how do I maintain that invariant throughout an application? -A. Some operations like addition and subtraction automatically preserve fixed +A. Some operations like addition and subtraction automatically preserve fixed point. Others, like multiplication and division, change the number of decimal places and need to be followed-up with a :meth:`quantize` step. -Q. There are many ways to express the same value. The numbers :const:`200`, +Q. There are many ways to express the same value. The numbers :const:`200`, :const:`200.000`, :const:`2E2`, and :const:`.02E+4` all have the same value at various precisions. Is there a way to transform them to a single recognizable canonical value? -A. The :meth:`normalize` method maps all equivalent values to a single +A. The :meth:`normalize` method maps all equivalent values to a single representative:: >>> values = map(Decimal, '200 200.000 2E2 .02E+4'.split()) >>> [v.normalize() for v in values] [Decimal("2E+2"), Decimal("2E+2"), Decimal("2E+2"), Decimal("2E+2")] -Q. Some decimal values always print with exponential notation. Is there a way +Q. Some decimal values always print with exponential notation. Is there a way to get a non-exponential representation? -A. For some values, exponential notation is the only way to express the number +A. For some values, exponential notation is the only way to express the number of significant places in the coefficient. For example, expressing :const:`5.0E+3` as :const:`5000` keeps the value constant but cannot show the original's two-place significance. -Q. Is there a way to convert a regular float to a :class:`Decimal`? +Q. Is there a way to convert a regular float to a :class:`Decimal`? -A. Yes, all binary floating point numbers can be exactly expressed as a +A. Yes, all binary floating point numbers can be exactly expressed as a Decimal. An exact conversion may take more precision than intuition would suggest, so trapping :const:`Inexact` will signal a need for more precision:: @@ -1248,28 +1248,28 @@ finally: setcontext(oldcontext) -Q. Why isn't the :func:`floatToDecimal` routine included in the module? +Q. Why isn't the :func:`floatToDecimal` routine included in the module? -A. There is some question about whether it is advisable to mix binary and +A. There is some question about whether it is advisable to mix binary and decimal floating point. Also, its use requires some care to avoid the representation issues associated with binary floating point:: >>> floatToDecimal(1.1) Decimal("1.100000000000000088817841970012523233890533447265625") -Q. Within a complex calculation, how can I make sure that I haven't gotten a +Q. Within a complex calculation, how can I make sure that I haven't gotten a spurious result because of insufficient precision or rounding anomalies. -A. The decimal module makes it easy to test results. A best practice is to re- +A. The decimal module makes it easy to test results. A best practice is to re- run calculations using greater precision and with various rounding modes. Widely differing results indicate insufficient precision, rounding mode issues, ill- conditioned inputs, or a numerically unstable algorithm. -Q. I noticed that context precision is applied to the results of operations but +Q. I noticed that context precision is applied to the results of operations but not to the inputs. Is there anything to watch out for when mixing values of different precisions? -A. Yes. The principle is that all values are considered to be exact and so is +A. Yes. The principle is that all values are considered to be exact and so is the arithmetic on those values. Only the results are rounded. The advantage for inputs is that "what you type is what you get". A disadvantage is that the results can look odd if you forget that the inputs haven't been rounded:: Modified: doctools/trunk/Doc-26/library/dis.rst ============================================================================== --- doctools/trunk/Doc-26/library/dis.rst (original) +++ doctools/trunk/Doc-26/library/dis.rst Thu Aug 2 15:06:23 2007 @@ -189,7 +189,7 @@ .. opcode:: UNARY_CONVERT () - Implements ``TOS = `TOS``\ `. + Implements ``TOS = `TOS```. .. opcode:: UNARY_INVERT () Modified: doctools/trunk/Doc-26/library/filesys.rst ============================================================================== --- doctools/trunk/Doc-26/library/filesys.rst (original) +++ doctools/trunk/Doc-26/library/filesys.rst Thu Aug 2 15:06:23 2007 @@ -24,14 +24,13 @@ linecache.rst shutil.rst dircache.rst -Also see section :ref:`bltin-file-objects` for a description of Python's built- -in file objects. - -.. % XXX can this be included in the seealso environment? --amk .. seealso:: + Section :ref:`bltin-file-objects` + A description of Python's built-in file objects. + Module :mod:`os` Operating system interfaces, including functions to work with files at a lower level than the built-in file object. Modified: doctools/trunk/Doc-26/library/gl.rst ============================================================================== --- doctools/trunk/Doc-26/library/gl.rst (original) +++ doctools/trunk/Doc-26/library/gl.rst Thu Aug 2 15:06:23 2007 @@ -28,7 +28,7 @@ * All arrays are represented by one-dimensional Python lists. In most cases, tuples are also allowed. -* All string and character arguments are represented by Python strings, for +* All string and character arguments are represented by Python strings, for instance, ``winopen('Hi There!')`` and ``rotate(900, 'z')``. * All (short, long, unsigned) integer arguments or return values that are only Modified: doctools/trunk/Doc-26/library/operator.rst ============================================================================== --- doctools/trunk/Doc-26/library/operator.rst (original) +++ doctools/trunk/Doc-26/library/operator.rst Thu Aug 2 15:06:23 2007 @@ -90,7 +90,7 @@ .. function:: add(a, b) __add__(a, b) - Return *a* ``+`` *b*, for *a* and *b* numbers. + Return ``a + b``, for *a* and *b* numbers. .. function:: and_(a, b) @@ -102,14 +102,14 @@ .. function:: div(a, b) __div__(a, b) - Return *a* ``/`` *b* when ``__future__.division`` is not in effect. This is + Return ``a / b`` when ``__future__.division`` is not in effect. This is also known as "classic" division. .. function:: floordiv(a, b) __floordiv__(a, b) - Return *a* ``//`` *b*. + Return ``a // b``. .. versionadded:: 2.2 @@ -119,7 +119,7 @@ __inv__(o) __invert__(o) - Return the bitwise inverse of the number *o*. This is equivalent to ``~``*o*. + Return the bitwise inverse of the number *o*. This is equivalent to ``~o``. The names :func:`invert` and :func:`__invert__` were added in Python 2.0. @@ -132,13 +132,13 @@ .. function:: mod(a, b) __mod__(a, b) - Return *a* ``%`` *b*. + Return ``a % b``. .. function:: mul(a, b) __mul__(a, b) - Return *a* ``*`` *b*, for *a* and *b* numbers. + Return ``a * b``, for *a* and *b* numbers. .. function:: neg(o) @@ -162,7 +162,7 @@ .. function:: pow(a, b) __pow__(a, b) - Return *a* ``**`` *b*, for *a* and *b* numbers. + Return ``a ** b``, for *a* and *b* numbers. .. versionadded:: 2.3 @@ -176,13 +176,13 @@ .. function:: sub(a, b) __sub__(a, b) - Return *a* ``-`` *b*. + Return ``a - b``. .. function:: truediv(a, b) __truediv__(a, b) - Return *a* ``/`` *b* when ``__future__.division`` is in effect. This is also + Return ``a / b`` when ``__future__.division`` is in effect. This is also known as "true" division. .. versionadded:: 2.2 @@ -197,7 +197,7 @@ .. function:: index(a) __index__(a) - Return *a* converted to an integer. Equivalent to *a*``.__index__()``. + Return *a* converted to an integer. Equivalent to ``a.__index__()``. .. versionadded:: 2.5 @@ -207,13 +207,13 @@ .. function:: concat(a, b) __concat__(a, b) - Return *a* ``+`` *b* for *a* and *b* sequences. + Return ``a + b`` for *a* and *b* sequences. .. function:: contains(a, b) __contains__(a, b) - Return the outcome of the test *b* ``in`` *a*. Note the reversed operands. The + Return the outcome of the test ``b in a``. Note the reversed operands. The name :func:`__contains__` was added in Python 2.0. @@ -231,7 +231,7 @@ .. function:: delslice(a, b, c) __delslice__(a, b, c) - Delete the slice of *a* from index *b* to index *c*``-1``. + Delete the slice of *a* from index *b* to index *c-1*. .. function:: getitem(a, b) @@ -243,7 +243,7 @@ .. function:: getslice(a, b, c) __getslice__(a, b, c) - Return the slice of *a* from index *b* to index *c*``-1``. + Return the slice of *a* from index *b* to index *c-1*. .. function:: indexOf(a, b) @@ -254,7 +254,7 @@ .. function:: repeat(a, b) __repeat__(a, b) - Return *a* ``*`` *b* where *a* is a sequence and *b* is an integer. + Return ``a * b`` where *a* is a sequence and *b* is an integer. .. function:: sequenceIncludes(...) @@ -274,7 +274,7 @@ .. function:: setslice(a, b, c, v) __setslice__(a, b, c, v) - Set the slice of *a* from index *b* to index *c*``-1`` to the sequence *v*. + Set the slice of *a* from index *b* to index *c-1* to the sequence *v*. Many operations have an "in-place" version. The following functions provide a more primitive access to in-place operators than the usual syntax does; for @@ -405,24 +405,23 @@ .. versionadded:: 2.5 + The :mod:`operator` module also defines a few predicates to test the type of objects. .. note:: Be careful not to misinterpret the results of these functions; only - :func:`isCallable` has any measure of reliability with instance objects. For - example: - -:: + :func:`isCallable` has any measure of reliability with instance objects. + For example:: - >>> class C: - ... pass - ... - >>> import operator - >>> o = C() - >>> operator.isMappingType(o) - True + >>> class C: + ... pass + ... + >>> import operator + >>> o = C() + >>> operator.isMappingType(o) + True .. function:: isCallable(o) Modified: doctools/trunk/Doc-26/library/optparse.rst ============================================================================== --- doctools/trunk/Doc-26/library/optparse.rst (original) +++ doctools/trunk/Doc-26/library/optparse.rst Thu Aug 2 15:06:23 2007 @@ -117,18 +117,18 @@ Some other option syntaxes that the world has seen include: -* a hyphen followed by a few letters, e.g. ``"-pf"`` (this is *not* the same - as multiple options merged into a single argument) +* a hyphen followed by a few letters, e.g. ``"-pf"`` (this is *not* the same + as multiple options merged into a single argument) -* a hyphen followed by a whole word, e.g. ``"-file"`` (this is technically - equivalent to the previous syntax, but they aren't usually seen in the same - program) +* a hyphen followed by a whole word, e.g. ``"-file"`` (this is technically + equivalent to the previous syntax, but they aren't usually seen in the same + program) -* a plus sign followed by a single letter, or a few letters, or a word, e.g. - ``"+f"``, ``"+rgb"`` +* a plus sign followed by a single letter, or a few letters, or a word, e.g. + ``"+f"``, ``"+rgb"`` -* a slash followed by a letter, or a few letters, or a word, e.g. ``"/f"``, - ``"/file"`` +* a slash followed by a letter, or a few letters, or a word, e.g. ``"/f"``, + ``"/file"`` These option syntaxes are not supported by :mod:`optparse`, and they never will be. This is deliberate: the first three are non-standard on any environment, @@ -289,12 +289,12 @@ :meth:`parse_args` returns two values: -* ``options``, an object containing values for all of your options---e.g. if +* ``options``, an object containing values for all of your options---e.g. if ``"--file"`` takes a single string argument, then ``options.file`` will be the filename supplied by the user, or ``None`` if the user did not supply that option -* ``args``, the list of positional arguments leftover after parsing options +* ``args``, the list of positional arguments leftover after parsing options This tutorial section only covers the four most important option attributes: :attr:`action`, :attr:`type`, :attr:`dest` (destination), and :attr:`help`. Of @@ -510,7 +510,7 @@ There's a lot going on here to help :mod:`optparse` generate the best possible help message: -* the script defines its own usage message:: +* the script defines its own usage message:: usage = "usage: %prog [options] arg1 arg2" @@ -522,11 +522,11 @@ default: ``"usage: %prog [options]"``, which is fine if your script doesn't take any positional arguments. -* every option defines a help string, and doesn't worry about line- +* every option defines a help string, and doesn't worry about line- wrapping---\ :mod:`optparse` takes care of wrapping lines and making the help output look good. -* options that take a value indicate this fact in their automatically- +* options that take a value indicate this fact in their automatically- generated help message, e.g. for the "mode" option:: -m MODE, --mode=MODE @@ -546,7 +546,7 @@ description "write output to FILE". This is a simple but effective way to make your help text a lot clearer and more useful for end users. -* options that have a default value can include ``%default`` in the help +* options that have a default value can include ``%default`` in the help string---\ :mod:`optparse` will replace it with :func:`str` of the option's default value. If an option has no default value (or the default value is ``None``), ``%default`` expands to ``none``. @@ -737,9 +737,9 @@ :ref:`optparse-tutorial`, the tutorial. :meth:`add_option` can be called in one of two ways: -* pass it an Option instance (as returned by :func:`make_option`) +* pass it an Option instance (as returned by :func:`make_option`) -* pass it any combination of positional and keyword arguments that are +* pass it any combination of positional and keyword arguments that are acceptable to :func:`make_option` (i.e., to the Option constructor), and it will create the Option instance for you @@ -866,7 +866,7 @@ guide :mod:`optparse`'s behaviour; a few have required attributes, which you must specify for any option using that action. -* ``store`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``] +* ``store`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``] The option must be followed by an argument, which is converted to a value according to :attr:`type` and stored in :attr:`dest`. If ``nargs`` > 1, @@ -899,7 +899,7 @@ options.point = (1.0, -3.5, 4.0) options.f = "bar.txt" -* ``store_const`` [required: ``const``; relevant: :attr:`dest`] +* ``store_const`` [required: ``const``; relevant: :attr:`dest`] The value ``const`` is stored in :attr:`dest`. @@ -916,11 +916,11 @@ options.verbose = 2 -* ``store_true`` [relevant: :attr:`dest`] +* ``store_true`` [relevant: :attr:`dest`] A special case of ``store_const`` that stores a true value to :attr:`dest`. -* ``store_false`` [relevant: :attr:`dest`] +* ``store_false`` [relevant: :attr:`dest`] Like ``store_true``, but stores a false value. @@ -929,7 +929,7 @@ parser.add_option("--clobber", action="store_true", dest="clobber") parser.add_option("--no-clobber", action="store_false", dest="clobber") -* ``append`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``] +* ``append`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``] The option must be followed by an argument, which is appended to the list in :attr:`dest`. If no default value for :attr:`dest` is supplied, an empty list @@ -954,13 +954,13 @@ options.tracks.append(int("4")) -* ``append_const`` [required: ``const``; relevant: :attr:`dest`] +* ``append_const`` [required: ``const``; relevant: :attr:`dest`] Like ``store_const``, but the value ``const`` is appended to :attr:`dest`; as with ``append``, :attr:`dest` defaults to ``None``, and an an empty list is automatically created the first time the option is encountered. -* ``count`` [relevant: :attr:`dest`] +* ``count`` [relevant: :attr:`dest`] Increment the integer stored at :attr:`dest`. If no default value is supplied, :attr:`dest` is set to zero before being incremented the first time. @@ -979,7 +979,7 @@ options.verbosity += 1 -* ``callback`` [required: ``callback``; relevant: :attr:`type`, ``nargs``, +* ``callback`` [required: ``callback``; relevant: :attr:`type`, ``nargs``, ``callback_args``, ``callback_kwargs``] Call the function specified by ``callback``, which is called as :: @@ -988,7 +988,7 @@ See section :ref:`optparse-option-callbacks`, Option Callbacks for more detail. -* :attr:`help` +* :attr:`help` Prints a complete help message for all the options in the current option parser. The help message is constructed from the ``usage`` string passed to @@ -1027,7 +1027,7 @@ After printing the help message, :mod:`optparse` terminates your process with ``sys.exit(0)``. -* ``version`` +* ``version`` Prints the version number supplied to the OptionParser to stdout and exits. The version number is actually formatted and printed by the ``print_version()`` @@ -1047,59 +1047,59 @@ to a particular option, or fail to pass a required option attribute, :mod:`optparse` raises OptionError. -* :attr:`action` (default: ``"store"``) +* :attr:`action` (default: ``"store"``) Determines :mod:`optparse`'s behaviour when this option is seen on the command line; the available options are documented above. -* :attr:`type` (default: ``"string"``) +* :attr:`type` (default: ``"string"``) The argument type expected by this option (e.g., ``"string"`` or ``"int"``); the available option types are documented below. -* :attr:`dest` (default: derived from option strings) +* :attr:`dest` (default: derived from option strings) If the option's action implies writing or modifying a value somewhere, this tells :mod:`optparse` where to write it: :attr:`dest` names an attribute of the ``options`` object that :mod:`optparse` builds as it parses the command line. -* ``default`` (deprecated) +* ``default`` (deprecated) The value to use for this option's destination if the option is not seen on the command line. Deprecated; use ``parser.set_defaults()`` instead. -* ``nargs`` (default: 1) +* ``nargs`` (default: 1) How many arguments of type :attr:`type` should be consumed when this option is seen. If > 1, :mod:`optparse` will store a tuple of values to :attr:`dest`. -* ``const`` +* ``const`` For actions that store a constant value, the constant value to store. -* ``choices`` +* ``choices`` For options of type ``"choice"``, the list of strings the user may choose from. -* ``callback`` +* ``callback`` For options with action ``"callback"``, the callable to call when this option is seen. See section :ref:`optparse-option-callbacks`, Option Callbacks for detail on the arguments passed to ``callable``. -* ``callback_args``, ``callback_kwargs`` +* ``callback_args``, ``callback_kwargs`` Additional positional and keyword arguments to pass to ``callback`` after the four standard callback arguments. -* :attr:`help` +* :attr:`help` Help text to print for this option when listing all available options after the user supplies a :attr:`help` option (such as ``"--help"``). If no help text is supplied, the option will be listed without help text. To hide this option, use the special value ``SUPPRESS_HELP``. -* ``metavar`` (default: derived from option strings) +* ``metavar`` (default: derived from option strings) Stand-in for the option argument(s) to use when printing help text. See section :ref:`optparse-tutorial`, the tutorial for an example. @@ -1119,13 +1119,13 @@ Integer arguments (type ``int`` or ``long``) are parsed as follows: -* if the number starts with ``0x``, it is parsed as a hexadecimal number +* if the number starts with ``0x``, it is parsed as a hexadecimal number -* if the number starts with ``0``, it is parsed as an octal number +* if the number starts with ``0``, it is parsed as an octal number -* if the number starts with ``0b``, is is parsed as a binary number +* if the number starts with ``0b``, is is parsed as a binary number -* otherwise, the number is parsed as a decimal number +* otherwise, the number is parsed as a decimal number The conversion is done by calling either ``int()`` or ``long()`` with the @@ -1290,13 +1290,13 @@ OptionParser supports several other public methods: -* ``set_usage(usage)`` +* ``set_usage(usage)`` Set the usage string according to the rules described above for the ``usage`` constructor keyword argument. Passing ``None`` sets the default usage string; use ``SUPPRESS_USAGE`` to suppress a usage message. -* ``enable_interspersed_args()``, ``disable_interspersed_args()`` +* ``enable_interspersed_args()``, ``disable_interspersed_args()`` Enable/disable positional arguments interspersed with options, similar to GNU getopt (enabled by default). For example, if ``"-a"`` and ``"-b"`` are both @@ -1313,7 +1313,7 @@ traditional Unix syntax, where option parsing stops with the first non-option argument. -* ``set_defaults(dest=value, ...)`` +* ``set_defaults(dest=value, ...)`` Set default values for several option destinations at once. Using :meth:`set_defaults` is the preferred way to set default values for options, @@ -1351,9 +1351,9 @@ There are two steps to defining a callback option: -* define the option itself using the ``callback`` action +* define the option itself using the ``callback`` action -* write the callback; this is a function (or method) that takes at least four +* write the callback; this is a function (or method) that takes at least four arguments, as described below @@ -1586,12 +1586,12 @@ you. In particular, callbacks should implement the conventional rules for bare ``"--"`` and ``"-"`` arguments: -* either ``"--"`` or ``"-"`` can be option arguments +* either ``"--"`` or ``"-"`` can be option arguments -* bare ``"--"`` (if not the argument to some option): halt command-line +* bare ``"--"`` (if not the argument to some option): halt command-line processing and discard the ``"--"`` -* bare ``"-"`` (if not the argument to some option): halt command-line +* bare ``"-"`` (if not the argument to some option): halt command-line processing but keep the ``"-"`` (append it to ``parser.largs``) If you want an option that takes a variable number of arguments, there are @@ -1799,18 +1799,18 @@ Features of note: -* ``extend`` both expects a value on the command-line and stores that value +* ``extend`` both expects a value on the command-line and stores that value somewhere, so it goes in both :attr:`STORE_ACTIONS` and :attr:`TYPED_ACTIONS` -* to ensure that :mod:`optparse` assigns the default type of ``string`` to +* to ensure that :mod:`optparse` assigns the default type of ``string`` to ``extend`` actions, we put the ``extend`` action in ``ALWAYS_TYPED_ACTIONS`` as well -* :meth:`MyOption.take_action` implements just this one new action, and passes +* :meth:`MyOption.take_action` implements just this one new action, and passes control back to :meth:`Option.take_action` for the standard :mod:`optparse` actions -* ``values`` is an instance of the optparse_parser.Values class, which +* ``values`` is an instance of the optparse_parser.Values class, which provides the very useful :meth:`ensure_value` method. :meth:`ensure_value` is essentially :func:`getattr` with a safety valve; it is called as :: Modified: doctools/trunk/Doc-26/library/tkinter.rst ============================================================================== --- doctools/trunk/Doc-26/library/tkinter.rst (original) +++ doctools/trunk/Doc-26/library/tkinter.rst Thu Aug 2 15:06:23 2007 @@ -766,10 +766,10 @@ are commonly known as *callbacks*.) add - is optional, either ```` or``\ +``. Passing an empty string denotes that this - binding is to replace any other bindings that this event is associated with. - Preceeding with a``\ +`` means that this function is to be added to the list of - functions bound to this event type. + is optional, either ``''`` or ``'+'``. Passing an empty string denotes that + this binding is to replace any other bindings that this event is associated + with. Passing a ``'+'`` means that this function is to be added to the list + of functions bound to this event type. For example:: Modified: doctools/trunk/Doc-26/library/urllib2.rst ============================================================================== --- doctools/trunk/Doc-26/library/urllib2.rst (original) +++ doctools/trunk/Doc-26/library/urllib2.rst Thu Aug 2 15:06:23 2007 @@ -62,10 +62,10 @@ .. function:: build_opener([handler, ...]) Return an :class:`OpenerDirector` instance, which chains the handlers in the - order given. *handler*s can be either instances of :class:`BaseHandler`, or + order given. *handler*\s can be either instances of :class:`BaseHandler`, or subclasses of :class:`BaseHandler` (in which case it must be possible to call the constructor without any parameters). Instances of the following classes - will be in front of the *handler*s, unless the *handler*s contain them, + will be in front of the *handler*\s, unless the *handler*\s contain them, instances of them or subclasses of them: :class:`ProxyHandler`, :class:`UnknownHandler`, :class:`HTTPHandler`, :class:`HTTPDefaultErrorHandler`, :class:`HTTPRedirectHandler`, :class:`FTPHandler`, :class:`FileHandler`, Modified: doctools/trunk/Doc-26/library/xml.etree.rst ============================================================================== --- doctools/trunk/Doc-26/library/xml.etree.rst (original) +++ doctools/trunk/Doc-26/library/xml.etree.rst Thu Aug 2 15:06:23 2007 @@ -1,6 +1,5 @@ - -:mod:`xml.etree` --- The ElementTree API for XML -================================================= +:mod:`xml.etree` --- The ElementTree API for XML +================================================ .. module:: xml.etree :synopsis: Package containing common ElementTree modules. @@ -23,4 +22,3 @@ `ElementTree Overview `_ The home page for :mod:`ElementTree`. This includes links to additional documentation, alternative implementations, and other add-ons. - Modified: doctools/trunk/Doc-26/maclib/macui.rst ============================================================================== --- doctools/trunk/Doc-26/maclib/macui.rst (original) +++ doctools/trunk/Doc-26/maclib/macui.rst Thu Aug 2 15:06:23 2007 @@ -77,7 +77,7 @@ options are selected. Its items can take one of two forms: *optstr* or ``(optstr, descr)``. When present, *descr* is a short descriptive string that is displayed in the dialog while this option is selected in the popup menu. The - correspondence between *optstr*s and command-line arguments is: + correspondence between *optstr*\s and command-line arguments is: +----------------------+------------------------------------------+ | *optstr* format | Command-line format | Modified: doctools/trunk/Doc-26/maclib/scripting.rst ============================================================================== --- doctools/trunk/Doc-26/maclib/scripting.rst (original) +++ doctools/trunk/Doc-26/maclib/scripting.rst Thu Aug 2 15:06:23 2007 @@ -86,12 +86,7 @@ aepack.rst aetypes.rst miniae.rst + In addition, support modules have been pre-generated for :mod:`Finder`, :mod:`Terminal`, :mod:`Explorer`, :mod:`Netscape`, :mod:`CodeWarrior`, :mod:`SystemEvents` and :mod:`StdSuites`. - -XXX: input{libgensuitemodule} :XXX -XXX: input{libaetools} :XXX -XXX: input{libaepack} :XXX -XXX: input{libaetypes} :XXX -XXX: input{libminiae} :XXX Modified: doctools/trunk/Doc-3k/TODO ============================================================================== --- doctools/trunk/Doc-3k/TODO (original) +++ doctools/trunk/Doc-3k/TODO Thu Aug 2 15:06:23 2007 @@ -2,7 +2,6 @@ ====================== * fix all references and links marked with `XXX` -* adjust all literal include paths * fix all duplicate labels and undefined label references * split very large files and add toctrees * integrate standalone HOWTOs Modified: doctools/trunk/Doc-3k/bugs.rst ============================================================================== --- doctools/trunk/Doc-3k/bugs.rst (original) +++ doctools/trunk/Doc-3k/bugs.rst Thu Aug 2 15:06:23 2007 @@ -1,9 +1,9 @@ +.. _reporting-bugs: + ************** Reporting Bugs ************** -.. _reporting-bugs: - Python is a mature programming language which has established a reputation for stability. In order to maintain this reputation, the developers would like to know of any deficiencies you find in Python or its documentation. Modified: doctools/trunk/Doc-3k/c-api/concrete.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/concrete.rst (original) +++ doctools/trunk/Doc-3k/c-api/concrete.rst Thu Aug 2 15:06:23 2007 @@ -3157,15 +3157,15 @@ .. cfunction:: PyObject* PyCObject_FromVoidPtr(void* cobj, void (*destr)(void *)) - Create a :ctype:`PyCObject` from the ``void *``*cobj*. The *destr* function + Create a :ctype:`PyCObject` from the ``void *`` *cobj*. The *destr* function will be called when the object is reclaimed, unless it is *NULL*. .. cfunction:: PyObject* PyCObject_FromVoidPtrAndDesc(void* cobj, void* desc, void (*destr)(void *, void *)) - Create a :ctype:`PyCObject` from the :ctype:`void \*`*cobj*. The *destr* - function will be called when the object is reclaimed. The *desc* argument can be - used to pass extra callback data for the destructor function. + Create a :ctype:`PyCObject` from the :ctype:`void \*` *cobj*. The *destr* + function will be called when the object is reclaimed. The *desc* argument can + be used to pass extra callback data for the destructor function. .. cfunction:: void* PyCObject_AsVoidPtr(PyObject* self) Modified: doctools/trunk/Doc-3k/c-api/init.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/init.rst (original) +++ doctools/trunk/Doc-3k/c-api/init.rst Thu Aug 2 15:06:23 2007 @@ -204,7 +204,7 @@ .. cfunction:: char* Py_GetExecPrefix() - Return the *exec-prefix* for installed platform-*de*pendent files. This is + Return the *exec-prefix* for installed platform-*dependent* files. This is derived through a number of complicated rules from the program name set with :cfunc:`Py_SetProgramName` and some environment variables; for example, if the program name is ``'/usr/local/bin/python'``, the exec-prefix is Modified: doctools/trunk/Doc-3k/c-api/utilities.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/utilities.rst (original) +++ doctools/trunk/Doc-3k/c-api/utilities.rst Thu Aug 2 15:06:23 2007 @@ -624,9 +624,9 @@ Convert a Python object to a C variable through a *converter* function. This takes two arguments: the first is a function, the second is the address of a C variable (of arbitrary type), converted to :ctype:`void \*`. The *converter* - function in turn is called as follows: + function in turn is called as follows:: - *status*``=``*converter*``(``*object*, *address*``);`` + status = converter(object, address); where *object* is the Python object to be converted and *address* is the :ctype:`void\*` argument that was passed to the :cfunc:`PyArg_Parse\*` function. Modified: doctools/trunk/Doc-3k/extending/windows.rst ============================================================================== --- doctools/trunk/Doc-3k/extending/windows.rst (original) +++ doctools/trunk/Doc-3k/extending/windows.rst Thu Aug 2 15:06:23 2007 @@ -68,15 +68,15 @@ #. **Build the example DLL** --- In order to check that everything is set up right, try building: -#. Select a configuration. This step is optional. Choose :menuselection:`Build - --> Configuration Manager --> Active Solution Configuration` and select either - :guilabel:`Release` or\ :guilabel:`Debug`. If you skip this step, VC++ will - use the Debug configuration by default. +#. Select a configuration. This step is optional. Choose + :menuselection:`Build --> Configuration Manager --> Active Solution Configuration` + and select either :guilabel:`Release` or :guilabel:`Debug`. If you skip this + step, VC++ will use the Debug configuration by default. #. Build the DLL. Choose :menuselection:`Build --> Build Solution`. This - creates all intermediate and result files in a subdirectory called either - :file:`Debug` or :file:`Release`, depending on which configuration you selected - in the preceding step. + creates all intermediate and result files in a subdirectory called either + :file:`Debug` or :file:`Release`, depending on which configuration you selected + in the preceding step. #. **Testing the debug-mode DLL** --- Once the Debug build has succeeded, bring up a DOS box, and change to the :file:`example_nt\\Debug` directory. You should Modified: doctools/trunk/Doc-3k/library/curses.rst ============================================================================== --- doctools/trunk/Doc-3k/library/curses.rst (original) +++ doctools/trunk/Doc-3k/library/curses.rst Thu Aug 2 15:06:23 2007 @@ -1103,7 +1103,7 @@ Pretend *count* lines have been changed, starting with line *start*. If *changed* is supplied, it specifies whether the affected lines are marked as - having been changed (*changed*=1) or unchanged (*changed*=0). + having been changed (*changed*\ =1) or unchanged (*changed*\ =0). .. method:: window.touchwin() Modified: doctools/trunk/Doc-3k/library/decimal.rst ============================================================================== --- doctools/trunk/Doc-3k/library/decimal.rst (original) +++ doctools/trunk/Doc-3k/library/decimal.rst Thu Aug 2 15:06:23 2007 @@ -1160,20 +1160,20 @@ Decimal FAQ ----------- -Q. It is cumbersome to type ``decimal.Decimal('1234.5')``. Is there a way to +Q. It is cumbersome to type ``decimal.Decimal('1234.5')``. Is there a way to minimize typing when using the interactive interpreter? -A. Some users abbreviate the constructor to just a single letter:: +\A. Some users abbreviate the constructor to just a single letter:: >>> D = decimal.Decimal >>> D('1.23') + D('3.45') Decimal("4.68") -Q. In a fixed-point application with two decimal places, some inputs have many +Q. In a fixed-point application with two decimal places, some inputs have many places and need to be rounded. Others are not supposed to have excess digits and need to be validated. What methods should be used? -A. The :meth:`quantize` method rounds to a fixed number of decimal places. If +A. The :meth:`quantize` method rounds to a fixed number of decimal places. If the :const:`Inexact` trap is set, it is also useful for validation:: >>> TWOPLACES = Decimal(10) ** -2 # same as Decimal('0.01') @@ -1191,36 +1191,36 @@ ... Inexact: Changed in rounding -Q. Once I have valid two place inputs, how do I maintain that invariant +Q. Once I have valid two place inputs, how do I maintain that invariant throughout an application? -A. Some operations like addition and subtraction automatically preserve fixed +A. Some operations like addition and subtraction automatically preserve fixed point. Others, like multiplication and division, change the number of decimal places and need to be followed-up with a :meth:`quantize` step. -Q. There are many ways to express the same value. The numbers :const:`200`, +Q. There are many ways to express the same value. The numbers :const:`200`, :const:`200.000`, :const:`2E2`, and :const:`.02E+4` all have the same value at various precisions. Is there a way to transform them to a single recognizable canonical value? -A. The :meth:`normalize` method maps all equivalent values to a single +A. The :meth:`normalize` method maps all equivalent values to a single representative:: >>> values = map(Decimal, '200 200.000 2E2 .02E+4'.split()) >>> [v.normalize() for v in values] [Decimal("2E+2"), Decimal("2E+2"), Decimal("2E+2"), Decimal("2E+2")] -Q. Some decimal values always print with exponential notation. Is there a way +Q. Some decimal values always print with exponential notation. Is there a way to get a non-exponential representation? -A. For some values, exponential notation is the only way to express the number +A. For some values, exponential notation is the only way to express the number of significant places in the coefficient. For example, expressing :const:`5.0E+3` as :const:`5000` keeps the value constant but cannot show the original's two-place significance. -Q. Is there a way to convert a regular float to a :class:`Decimal`? +Q. Is there a way to convert a regular float to a :class:`Decimal`? -A. Yes, all binary floating point numbers can be exactly expressed as a +A. Yes, all binary floating point numbers can be exactly expressed as a Decimal. An exact conversion may take more precision than intuition would suggest, so trapping :const:`Inexact` will signal a need for more precision:: @@ -1248,28 +1248,28 @@ finally: setcontext(oldcontext) -Q. Why isn't the :func:`floatToDecimal` routine included in the module? +Q. Why isn't the :func:`floatToDecimal` routine included in the module? -A. There is some question about whether it is advisable to mix binary and +A. There is some question about whether it is advisable to mix binary and decimal floating point. Also, its use requires some care to avoid the representation issues associated with binary floating point:: >>> floatToDecimal(1.1) Decimal("1.100000000000000088817841970012523233890533447265625") -Q. Within a complex calculation, how can I make sure that I haven't gotten a +Q. Within a complex calculation, how can I make sure that I haven't gotten a spurious result because of insufficient precision or rounding anomalies. -A. The decimal module makes it easy to test results. A best practice is to re- +A. The decimal module makes it easy to test results. A best practice is to re- run calculations using greater precision and with various rounding modes. Widely differing results indicate insufficient precision, rounding mode issues, ill- conditioned inputs, or a numerically unstable algorithm. -Q. I noticed that context precision is applied to the results of operations but +Q. I noticed that context precision is applied to the results of operations but not to the inputs. Is there anything to watch out for when mixing values of different precisions? -A. Yes. The principle is that all values are considered to be exact and so is +A. Yes. The principle is that all values are considered to be exact and so is the arithmetic on those values. Only the results are rounded. The advantage for inputs is that "what you type is what you get". A disadvantage is that the results can look odd if you forget that the inputs haven't been rounded:: Modified: doctools/trunk/Doc-3k/library/filesys.rst ============================================================================== --- doctools/trunk/Doc-3k/library/filesys.rst (original) +++ doctools/trunk/Doc-3k/library/filesys.rst Thu Aug 2 15:06:23 2007 @@ -24,14 +24,13 @@ linecache.rst shutil.rst dircache.rst -Also see section :ref:`bltin-file-objects` for a description of Python's built- -in file objects. - -.. % XXX can this be included in the seealso environment? --amk .. seealso:: + Section :ref:`bltin-file-objects` + A description of Python's built-in file objects. + Module :mod:`os` Operating system interfaces, including functions to work with files at a lower level than the built-in file object. Modified: doctools/trunk/Doc-3k/library/operator.rst ============================================================================== --- doctools/trunk/Doc-3k/library/operator.rst (original) +++ doctools/trunk/Doc-3k/library/operator.rst Thu Aug 2 15:06:23 2007 @@ -90,7 +90,7 @@ .. function:: add(a, b) __add__(a, b) - Return *a* ``+`` *b*, for *a* and *b* numbers. + Return ``a + b``, for *a* and *b* numbers. .. function:: and_(a, b) @@ -102,14 +102,14 @@ .. function:: div(a, b) __div__(a, b) - Return *a* ``/`` *b* when ``__future__.division`` is not in effect. This is + Return ``a / b`` when ``__future__.division`` is not in effect. This is also known as "classic" division. .. function:: floordiv(a, b) __floordiv__(a, b) - Return *a* ``//`` *b*. + Return ``a // b``. .. versionadded:: 2.2 @@ -119,7 +119,7 @@ __inv__(o) __invert__(o) - Return the bitwise inverse of the number *o*. This is equivalent to ``~``*o*. + Return the bitwise inverse of the number *o*. This is equivalent to ``~o``. The names :func:`invert` and :func:`__invert__` were added in Python 2.0. @@ -132,13 +132,13 @@ .. function:: mod(a, b) __mod__(a, b) - Return *a* ``%`` *b*. + Return ``a % b``. .. function:: mul(a, b) __mul__(a, b) - Return *a* ``*`` *b*, for *a* and *b* numbers. + Return ``a * b``, for *a* and *b* numbers. .. function:: neg(o) @@ -162,7 +162,7 @@ .. function:: pow(a, b) __pow__(a, b) - Return *a* ``**`` *b*, for *a* and *b* numbers. + Return ``a ** b``, for *a* and *b* numbers. .. versionadded:: 2.3 @@ -176,13 +176,13 @@ .. function:: sub(a, b) __sub__(a, b) - Return *a* ``-`` *b*. + Return ``a - b``. .. function:: truediv(a, b) __truediv__(a, b) - Return *a* ``/`` *b* when ``__future__.division`` is in effect. This is also + Return ``a / b`` when ``__future__.division`` is in effect. This is also known as "true" division. .. versionadded:: 2.2 @@ -197,7 +197,7 @@ .. function:: index(a) __index__(a) - Return *a* converted to an integer. Equivalent to *a*``.__index__()``. + Return *a* converted to an integer. Equivalent to ``a.__index__()``. .. versionadded:: 2.5 @@ -207,13 +207,13 @@ .. function:: concat(a, b) __concat__(a, b) - Return *a* ``+`` *b* for *a* and *b* sequences. + Return ``a + b`` for *a* and *b* sequences. .. function:: contains(a, b) __contains__(a, b) - Return the outcome of the test *b* ``in`` *a*. Note the reversed operands. The + Return the outcome of the test ``b in a``. Note the reversed operands. The name :func:`__contains__` was added in Python 2.0. @@ -231,7 +231,7 @@ .. function:: delslice(a, b, c) __delslice__(a, b, c) - Delete the slice of *a* from index *b* to index *c*``-1``. + Delete the slice of *a* from index *b* to index *c-1*. .. function:: getitem(a, b) @@ -243,7 +243,7 @@ .. function:: getslice(a, b, c) __getslice__(a, b, c) - Return the slice of *a* from index *b* to index *c*``-1``. + Return the slice of *a* from index *b* to index *c-1*. .. function:: indexOf(a, b) @@ -254,7 +254,7 @@ .. function:: repeat(a, b) __repeat__(a, b) - Return *a* ``*`` *b* where *a* is a sequence and *b* is an integer. + Return ``a * b`` where *a* is a sequence and *b* is an integer. .. function:: sequenceIncludes(...) @@ -274,7 +274,7 @@ .. function:: setslice(a, b, c, v) __setslice__(a, b, c, v) - Set the slice of *a* from index *b* to index *c*``-1`` to the sequence *v*. + Set the slice of *a* from index *b* to index *c-1* to the sequence *v*. Many operations have an "in-place" version. The following functions provide a more primitive access to in-place operators than the usual syntax does; for @@ -405,24 +405,23 @@ .. versionadded:: 2.5 + The :mod:`operator` module also defines a few predicates to test the type of objects. .. note:: Be careful not to misinterpret the results of these functions; only - :func:`isCallable` has any measure of reliability with instance objects. For - example: - -:: + :func:`isCallable` has any measure of reliability with instance objects. + For example:: - >>> class C: - ... pass - ... - >>> import operator - >>> o = C() - >>> operator.isMappingType(o) - True + >>> class C: + ... pass + ... + >>> import operator + >>> o = C() + >>> operator.isMappingType(o) + True .. function:: isCallable(o) Modified: doctools/trunk/Doc-3k/library/optparse.rst ============================================================================== --- doctools/trunk/Doc-3k/library/optparse.rst (original) +++ doctools/trunk/Doc-3k/library/optparse.rst Thu Aug 2 15:06:23 2007 @@ -117,18 +117,18 @@ Some other option syntaxes that the world has seen include: -* a hyphen followed by a few letters, e.g. ``"-pf"`` (this is *not* the same - as multiple options merged into a single argument) +* a hyphen followed by a few letters, e.g. ``"-pf"`` (this is *not* the same + as multiple options merged into a single argument) -* a hyphen followed by a whole word, e.g. ``"-file"`` (this is technically - equivalent to the previous syntax, but they aren't usually seen in the same - program) +* a hyphen followed by a whole word, e.g. ``"-file"`` (this is technically + equivalent to the previous syntax, but they aren't usually seen in the same + program) -* a plus sign followed by a single letter, or a few letters, or a word, e.g. - ``"+f"``, ``"+rgb"`` +* a plus sign followed by a single letter, or a few letters, or a word, e.g. + ``"+f"``, ``"+rgb"`` -* a slash followed by a letter, or a few letters, or a word, e.g. ``"/f"``, - ``"/file"`` +* a slash followed by a letter, or a few letters, or a word, e.g. ``"/f"``, + ``"/file"`` These option syntaxes are not supported by :mod:`optparse`, and they never will be. This is deliberate: the first three are non-standard on any environment, @@ -289,12 +289,12 @@ :meth:`parse_args` returns two values: -* ``options``, an object containing values for all of your options---e.g. if +* ``options``, an object containing values for all of your options---e.g. if ``"--file"`` takes a single string argument, then ``options.file`` will be the filename supplied by the user, or ``None`` if the user did not supply that option -* ``args``, the list of positional arguments leftover after parsing options +* ``args``, the list of positional arguments leftover after parsing options This tutorial section only covers the four most important option attributes: :attr:`action`, :attr:`type`, :attr:`dest` (destination), and :attr:`help`. Of @@ -510,7 +510,7 @@ There's a lot going on here to help :mod:`optparse` generate the best possible help message: -* the script defines its own usage message:: +* the script defines its own usage message:: usage = "usage: %prog [options] arg1 arg2" @@ -522,11 +522,11 @@ default: ``"usage: %prog [options]"``, which is fine if your script doesn't take any positional arguments. -* every option defines a help string, and doesn't worry about line- +* every option defines a help string, and doesn't worry about line- wrapping---\ :mod:`optparse` takes care of wrapping lines and making the help output look good. -* options that take a value indicate this fact in their automatically- +* options that take a value indicate this fact in their automatically- generated help message, e.g. for the "mode" option:: -m MODE, --mode=MODE @@ -546,7 +546,7 @@ description "write output to FILE". This is a simple but effective way to make your help text a lot clearer and more useful for end users. -* options that have a default value can include ``%default`` in the help +* options that have a default value can include ``%default`` in the help string---\ :mod:`optparse` will replace it with :func:`str` of the option's default value. If an option has no default value (or the default value is ``None``), ``%default`` expands to ``none``. @@ -737,9 +737,9 @@ :ref:`optparse-tutorial`, the tutorial. :meth:`add_option` can be called in one of two ways: -* pass it an Option instance (as returned by :func:`make_option`) +* pass it an Option instance (as returned by :func:`make_option`) -* pass it any combination of positional and keyword arguments that are +* pass it any combination of positional and keyword arguments that are acceptable to :func:`make_option` (i.e., to the Option constructor), and it will create the Option instance for you @@ -866,7 +866,7 @@ guide :mod:`optparse`'s behaviour; a few have required attributes, which you must specify for any option using that action. -* ``store`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``] +* ``store`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``] The option must be followed by an argument, which is converted to a value according to :attr:`type` and stored in :attr:`dest`. If ``nargs`` > 1, @@ -899,7 +899,7 @@ options.point = (1.0, -3.5, 4.0) options.f = "bar.txt" -* ``store_const`` [required: ``const``; relevant: :attr:`dest`] +* ``store_const`` [required: ``const``; relevant: :attr:`dest`] The value ``const`` is stored in :attr:`dest`. @@ -916,11 +916,11 @@ options.verbose = 2 -* ``store_true`` [relevant: :attr:`dest`] +* ``store_true`` [relevant: :attr:`dest`] A special case of ``store_const`` that stores a true value to :attr:`dest`. -* ``store_false`` [relevant: :attr:`dest`] +* ``store_false`` [relevant: :attr:`dest`] Like ``store_true``, but stores a false value. @@ -929,7 +929,7 @@ parser.add_option("--clobber", action="store_true", dest="clobber") parser.add_option("--no-clobber", action="store_false", dest="clobber") -* ``append`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``] +* ``append`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``] The option must be followed by an argument, which is appended to the list in :attr:`dest`. If no default value for :attr:`dest` is supplied, an empty list @@ -954,13 +954,13 @@ options.tracks.append(int("4")) -* ``append_const`` [required: ``const``; relevant: :attr:`dest`] +* ``append_const`` [required: ``const``; relevant: :attr:`dest`] Like ``store_const``, but the value ``const`` is appended to :attr:`dest`; as with ``append``, :attr:`dest` defaults to ``None``, and an an empty list is automatically created the first time the option is encountered. -* ``count`` [relevant: :attr:`dest`] +* ``count`` [relevant: :attr:`dest`] Increment the integer stored at :attr:`dest`. If no default value is supplied, :attr:`dest` is set to zero before being incremented the first time. @@ -979,7 +979,7 @@ options.verbosity += 1 -* ``callback`` [required: ``callback``; relevant: :attr:`type`, ``nargs``, +* ``callback`` [required: ``callback``; relevant: :attr:`type`, ``nargs``, ``callback_args``, ``callback_kwargs``] Call the function specified by ``callback``, which is called as :: @@ -988,7 +988,7 @@ See section :ref:`optparse-option-callbacks`, Option Callbacks for more detail. -* :attr:`help` +* :attr:`help` Prints a complete help message for all the options in the current option parser. The help message is constructed from the ``usage`` string passed to @@ -1027,7 +1027,7 @@ After printing the help message, :mod:`optparse` terminates your process with ``sys.exit(0)``. -* ``version`` +* ``version`` Prints the version number supplied to the OptionParser to stdout and exits. The version number is actually formatted and printed by the ``print_version()`` @@ -1047,59 +1047,59 @@ to a particular option, or fail to pass a required option attribute, :mod:`optparse` raises OptionError. -* :attr:`action` (default: ``"store"``) +* :attr:`action` (default: ``"store"``) Determines :mod:`optparse`'s behaviour when this option is seen on the command line; the available options are documented above. -* :attr:`type` (default: ``"string"``) +* :attr:`type` (default: ``"string"``) The argument type expected by this option (e.g., ``"string"`` or ``"int"``); the available option types are documented below. -* :attr:`dest` (default: derived from option strings) +* :attr:`dest` (default: derived from option strings) If the option's action implies writing or modifying a value somewhere, this tells :mod:`optparse` where to write it: :attr:`dest` names an attribute of the ``options`` object that :mod:`optparse` builds as it parses the command line. -* ``default`` (deprecated) +* ``default`` (deprecated) The value to use for this option's destination if the option is not seen on the command line. Deprecated; use ``parser.set_defaults()`` instead. -* ``nargs`` (default: 1) +* ``nargs`` (default: 1) How many arguments of type :attr:`type` should be consumed when this option is seen. If > 1, :mod:`optparse` will store a tuple of values to :attr:`dest`. -* ``const`` +* ``const`` For actions that store a constant value, the constant value to store. -* ``choices`` +* ``choices`` For options of type ``"choice"``, the list of strings the user may choose from. -* ``callback`` +* ``callback`` For options with action ``"callback"``, the callable to call when this option is seen. See section :ref:`optparse-option-callbacks`, Option Callbacks for detail on the arguments passed to ``callable``. -* ``callback_args``, ``callback_kwargs`` +* ``callback_args``, ``callback_kwargs`` Additional positional and keyword arguments to pass to ``callback`` after the four standard callback arguments. -* :attr:`help` +* :attr:`help` Help text to print for this option when listing all available options after the user supplies a :attr:`help` option (such as ``"--help"``). If no help text is supplied, the option will be listed without help text. To hide this option, use the special value ``SUPPRESS_HELP``. -* ``metavar`` (default: derived from option strings) +* ``metavar`` (default: derived from option strings) Stand-in for the option argument(s) to use when printing help text. See section :ref:`optparse-tutorial`, the tutorial for an example. @@ -1119,13 +1119,13 @@ Integer arguments (type ``int`` or ``long``) are parsed as follows: -* if the number starts with ``0x``, it is parsed as a hexadecimal number +* if the number starts with ``0x``, it is parsed as a hexadecimal number -* if the number starts with ``0``, it is parsed as an octal number +* if the number starts with ``0``, it is parsed as an octal number -* if the number starts with ``0b``, is is parsed as a binary number +* if the number starts with ``0b``, is is parsed as a binary number -* otherwise, the number is parsed as a decimal number +* otherwise, the number is parsed as a decimal number The conversion is done by calling either ``int()`` or ``long()`` with the @@ -1290,13 +1290,13 @@ OptionParser supports several other public methods: -* ``set_usage(usage)`` +* ``set_usage(usage)`` Set the usage string according to the rules described above for the ``usage`` constructor keyword argument. Passing ``None`` sets the default usage string; use ``SUPPRESS_USAGE`` to suppress a usage message. -* ``enable_interspersed_args()``, ``disable_interspersed_args()`` +* ``enable_interspersed_args()``, ``disable_interspersed_args()`` Enable/disable positional arguments interspersed with options, similar to GNU getopt (enabled by default). For example, if ``"-a"`` and ``"-b"`` are both @@ -1313,7 +1313,7 @@ traditional Unix syntax, where option parsing stops with the first non-option argument. -* ``set_defaults(dest=value, ...)`` +* ``set_defaults(dest=value, ...)`` Set default values for several option destinations at once. Using :meth:`set_defaults` is the preferred way to set default values for options, @@ -1351,9 +1351,9 @@ There are two steps to defining a callback option: -* define the option itself using the ``callback`` action +* define the option itself using the ``callback`` action -* write the callback; this is a function (or method) that takes at least four +* write the callback; this is a function (or method) that takes at least four arguments, as described below @@ -1586,12 +1586,12 @@ you. In particular, callbacks should implement the conventional rules for bare ``"--"`` and ``"-"`` arguments: -* either ``"--"`` or ``"-"`` can be option arguments +* either ``"--"`` or ``"-"`` can be option arguments -* bare ``"--"`` (if not the argument to some option): halt command-line +* bare ``"--"`` (if not the argument to some option): halt command-line processing and discard the ``"--"`` -* bare ``"-"`` (if not the argument to some option): halt command-line +* bare ``"-"`` (if not the argument to some option): halt command-line processing but keep the ``"-"`` (append it to ``parser.largs``) If you want an option that takes a variable number of arguments, there are @@ -1799,18 +1799,18 @@ Features of note: -* ``extend`` both expects a value on the command-line and stores that value +* ``extend`` both expects a value on the command-line and stores that value somewhere, so it goes in both :attr:`STORE_ACTIONS` and :attr:`TYPED_ACTIONS` -* to ensure that :mod:`optparse` assigns the default type of ``string`` to +* to ensure that :mod:`optparse` assigns the default type of ``string`` to ``extend`` actions, we put the ``extend`` action in ``ALWAYS_TYPED_ACTIONS`` as well -* :meth:`MyOption.take_action` implements just this one new action, and passes +* :meth:`MyOption.take_action` implements just this one new action, and passes control back to :meth:`Option.take_action` for the standard :mod:`optparse` actions -* ``values`` is an instance of the optparse_parser.Values class, which +* ``values`` is an instance of the optparse_parser.Values class, which provides the very useful :meth:`ensure_value` method. :meth:`ensure_value` is essentially :func:`getattr` with a safety valve; it is called as :: Modified: doctools/trunk/Doc-3k/library/tkinter.rst ============================================================================== --- doctools/trunk/Doc-3k/library/tkinter.rst (original) +++ doctools/trunk/Doc-3k/library/tkinter.rst Thu Aug 2 15:06:23 2007 @@ -766,10 +766,10 @@ are commonly known as *callbacks*.) add - is optional, either ```` or``\ +``. Passing an empty string denotes that this - binding is to replace any other bindings that this event is associated with. - Preceeding with a``\ +`` means that this function is to be added to the list of - functions bound to this event type. + is optional, either ``''`` or ``'+'``. Passing an empty string denotes that + this binding is to replace any other bindings that this event is associated + with. Passing a ``'+'`` means that this function is to be added to the list + of functions bound to this event type. For example:: Modified: doctools/trunk/Doc-3k/library/urllib2.rst ============================================================================== --- doctools/trunk/Doc-3k/library/urllib2.rst (original) +++ doctools/trunk/Doc-3k/library/urllib2.rst Thu Aug 2 15:06:23 2007 @@ -62,10 +62,10 @@ .. function:: build_opener([handler, ...]) Return an :class:`OpenerDirector` instance, which chains the handlers in the - order given. *handler*s can be either instances of :class:`BaseHandler`, or + order given. *handler*\s can be either instances of :class:`BaseHandler`, or subclasses of :class:`BaseHandler` (in which case it must be possible to call the constructor without any parameters). Instances of the following classes - will be in front of the *handler*s, unless the *handler*s contain them, + will be in front of the *handler*\s, unless the *handler*\s contain them, instances of them or subclasses of them: :class:`ProxyHandler`, :class:`UnknownHandler`, :class:`HTTPHandler`, :class:`HTTPDefaultErrorHandler`, :class:`HTTPRedirectHandler`, :class:`FTPHandler`, :class:`FileHandler`, Modified: doctools/trunk/Doc-3k/library/xml.etree.rst ============================================================================== --- doctools/trunk/Doc-3k/library/xml.etree.rst (original) +++ doctools/trunk/Doc-3k/library/xml.etree.rst Thu Aug 2 15:06:23 2007 @@ -1,6 +1,5 @@ - -:mod:`xml.etree` --- The ElementTree API for XML -================================================= +:mod:`xml.etree` --- The ElementTree API for XML +================================================ .. module:: xml.etree :synopsis: Package containing common ElementTree modules. Modified: doctools/trunk/Doc-3k/maclib/macui.rst ============================================================================== --- doctools/trunk/Doc-3k/maclib/macui.rst (original) +++ doctools/trunk/Doc-3k/maclib/macui.rst Thu Aug 2 15:06:23 2007 @@ -77,7 +77,7 @@ options are selected. Its items can take one of two forms: *optstr* or ``(optstr, descr)``. When present, *descr* is a short descriptive string that is displayed in the dialog while this option is selected in the popup menu. The - correspondence between *optstr*s and command-line arguments is: + correspondence between *optstr*\s and command-line arguments is: +----------------------+------------------------------------------+ | *optstr* format | Command-line format | Modified: doctools/trunk/Doc-3k/maclib/scripting.rst ============================================================================== --- doctools/trunk/Doc-3k/maclib/scripting.rst (original) +++ doctools/trunk/Doc-3k/maclib/scripting.rst Thu Aug 2 15:06:23 2007 @@ -86,12 +86,7 @@ aepack.rst aetypes.rst miniae.rst + In addition, support modules have been pre-generated for :mod:`Finder`, :mod:`Terminal`, :mod:`Explorer`, :mod:`Netscape`, :mod:`CodeWarrior`, :mod:`SystemEvents` and :mod:`StdSuites`. - -XXX: input{libgensuitemodule} :XXX -XXX: input{libaetools} :XXX -XXX: input{libaepack} :XXX -XXX: input{libaetypes} :XXX -XXX: input{libminiae} :XXX Modified: doctools/trunk/sphinx/directives.py ============================================================================== --- doctools/trunk/sphinx/directives.py (original) +++ doctools/trunk/sphinx/directives.py Thu Aug 2 15:06:23 2007 @@ -416,7 +416,6 @@ pos = m.end() if pos < len(text): retnodes.append(nodes.Text(text[pos:], text[pos:])) - print retnodes return retnodes def productionlist_directive(name, arguments, options, content, lineno, From python-checkins at python.org Thu Aug 2 15:08:36 2007 From: python-checkins at python.org (georg.brandl) Date: Thu, 2 Aug 2007 15:08:36 +0200 (CEST) Subject: [Python-checkins] r56668 - doctools/trunk/Doc-3k/library/email-examples.rst Message-ID: <20070802130836.430141E4010@bag.python.org> Author: georg.brandl Date: Thu Aug 2 15:08:35 2007 New Revision: 56668 Added: doctools/trunk/Doc-3k/library/email-examples.rst Log: Forgot to add new merged file. Added: doctools/trunk/Doc-3k/library/email-examples.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-3k/library/email-examples.rst Thu Aug 2 15:08:35 2007 @@ -0,0 +1,38 @@ +:mod:`email`: Examples +---------------------- + +Here are a few examples of how to use the :mod:`email` package to read, write, +and send simple email messages, as well as more complex MIME messages. + +First, let's see how to create and send a simple text message: + + +.. include:: ../includes/email-simple.py + :literal: + +Here's an example of how to send a MIME message containing a bunch of family +pictures that may be residing in a directory: + + +.. include:: ../includes/email-mime.py + :literal: + +Here's an example of how to send the entire contents of a directory as an email +message: [#]_ + + +.. include:: ../includes/email-dir.py + :literal: + +And finally, here's an example of how to unpack a MIME message like the one +above, into a directory of files: + + +.. include:: ../includes/email-unpack.py + :literal: + + +.. rubric:: Footnotes + +.. [#] Thanks to Matthew Dixon Cowles for the original inspiration and examples. + From python-checkins at python.org Thu Aug 2 16:49:12 2007 From: python-checkins at python.org (georg.brandl) Date: Thu, 2 Aug 2007 16:49:12 +0200 (CEST) Subject: [Python-checkins] r56669 - in doctools/trunk: Doc-26/c-api/concrete.rst Doc-26/c-api/newtypes.rst Doc-26/extending/extending.rst Doc-26/install/index.rst Doc-26/library/__builtin__.rst Doc-26/library/csv.rst Doc-26/library/ctypes.rst Doc-26/library/datetime.rst Doc-26/library/functions.rst Doc-26/library/intro.rst Doc-26/library/logging.rst Doc-26/library/optparse.rst Doc-26/library/os.rst Doc-26/library/pyexpat.rst Doc-26/library/shlex.rst Doc-26/library/socket.rst Doc-26/library/sqlite3.rst Doc-26/library/stdtypes.rst Doc-26/library/string.rst Doc-26/library/sys.rst Doc-26/library/tarfile.rst Doc-26/library/tkinter.rst Doc-26/library/urlparse.rst Doc-26/library/userdict.rst Doc-26/library/xml.dom.rst Doc-26/library/xml.sax.reader.rst Doc-26/library/zipfile.rst Doc-26/library/zipimport.rst Doc-26/maclib/using.rst Doc-26/reference/datamodel.rst Doc-26/reference/expressions.rst Doc-26/reference/lexical_analysis.rst Doc-26/reference/simple_stmts.rst Doc-26/tutorial/errors.rst Doc-26/tutorial/modules.rst Doc-3k/c-api/concrete.rst Doc-3k/c-api/newtypes.rst Doc-3k/extending/extending.rst Doc-3k/install/index.rst Doc-3k/library/__builtin__.rst Doc-3k/library/csv.rst Doc-3k/library/ctypes.rst Doc-3k/library/datetime.rst Doc-3k/library/functions.rst Doc-3k/library/intro.rst Doc-3k/library/logging.rst Doc-3k/library/optparse.rst Doc-3k/library/os.rst Doc-3k/library/pyexpat.rst Doc-3k/library/shlex.rst Doc-3k/library/socket.rst Doc-3k/library/sqlite3.rst Doc-3k/library/stdtypes.rst Doc-3k/library/string.rst Doc-3k/library/sys.rst Doc-3k/library/tarfile.rst Doc-3k/library/tkinter.rst Doc-3k/library/urlparse.rst Doc-3k/library/userdict.rst Doc-3k/library/xml.dom.rst Doc-3k/library/xml.sax.reader.rst Doc-3k/library/zipfile.rst Doc-3k/library/zipimport.rst Doc-3k/maclib/using.rst Doc-3k/reference/datamodel.rst Doc-3k/reference/expressions.rst Doc-3k/reference/lexical_analysis.rst Doc-3k/tutorial/errors.rst Doc-3k/tutorial/modules.rst Message-ID: <20070802144912.90EF51E4005@bag.python.org> Author: georg.brandl Date: Thu Aug 2 16:49:09 2007 New Revision: 56669 Modified: doctools/trunk/Doc-26/c-api/concrete.rst doctools/trunk/Doc-26/c-api/newtypes.rst doctools/trunk/Doc-26/extending/extending.rst doctools/trunk/Doc-26/install/index.rst doctools/trunk/Doc-26/library/__builtin__.rst doctools/trunk/Doc-26/library/csv.rst doctools/trunk/Doc-26/library/ctypes.rst doctools/trunk/Doc-26/library/datetime.rst doctools/trunk/Doc-26/library/functions.rst doctools/trunk/Doc-26/library/intro.rst doctools/trunk/Doc-26/library/logging.rst doctools/trunk/Doc-26/library/optparse.rst doctools/trunk/Doc-26/library/os.rst doctools/trunk/Doc-26/library/pyexpat.rst doctools/trunk/Doc-26/library/shlex.rst doctools/trunk/Doc-26/library/socket.rst doctools/trunk/Doc-26/library/sqlite3.rst doctools/trunk/Doc-26/library/stdtypes.rst doctools/trunk/Doc-26/library/string.rst doctools/trunk/Doc-26/library/sys.rst doctools/trunk/Doc-26/library/tarfile.rst doctools/trunk/Doc-26/library/tkinter.rst doctools/trunk/Doc-26/library/urlparse.rst doctools/trunk/Doc-26/library/userdict.rst doctools/trunk/Doc-26/library/xml.dom.rst doctools/trunk/Doc-26/library/xml.sax.reader.rst doctools/trunk/Doc-26/library/zipfile.rst doctools/trunk/Doc-26/library/zipimport.rst doctools/trunk/Doc-26/maclib/using.rst doctools/trunk/Doc-26/reference/datamodel.rst doctools/trunk/Doc-26/reference/expressions.rst doctools/trunk/Doc-26/reference/lexical_analysis.rst doctools/trunk/Doc-26/reference/simple_stmts.rst doctools/trunk/Doc-26/tutorial/errors.rst doctools/trunk/Doc-26/tutorial/modules.rst doctools/trunk/Doc-3k/c-api/concrete.rst doctools/trunk/Doc-3k/c-api/newtypes.rst doctools/trunk/Doc-3k/extending/extending.rst doctools/trunk/Doc-3k/install/index.rst doctools/trunk/Doc-3k/library/__builtin__.rst doctools/trunk/Doc-3k/library/csv.rst doctools/trunk/Doc-3k/library/ctypes.rst doctools/trunk/Doc-3k/library/datetime.rst doctools/trunk/Doc-3k/library/functions.rst doctools/trunk/Doc-3k/library/intro.rst doctools/trunk/Doc-3k/library/logging.rst doctools/trunk/Doc-3k/library/optparse.rst doctools/trunk/Doc-3k/library/os.rst doctools/trunk/Doc-3k/library/pyexpat.rst doctools/trunk/Doc-3k/library/shlex.rst doctools/trunk/Doc-3k/library/socket.rst doctools/trunk/Doc-3k/library/sqlite3.rst doctools/trunk/Doc-3k/library/stdtypes.rst doctools/trunk/Doc-3k/library/string.rst doctools/trunk/Doc-3k/library/sys.rst doctools/trunk/Doc-3k/library/tarfile.rst doctools/trunk/Doc-3k/library/tkinter.rst doctools/trunk/Doc-3k/library/urlparse.rst doctools/trunk/Doc-3k/library/userdict.rst doctools/trunk/Doc-3k/library/xml.dom.rst doctools/trunk/Doc-3k/library/xml.sax.reader.rst doctools/trunk/Doc-3k/library/zipfile.rst doctools/trunk/Doc-3k/library/zipimport.rst doctools/trunk/Doc-3k/maclib/using.rst doctools/trunk/Doc-3k/reference/datamodel.rst doctools/trunk/Doc-3k/reference/expressions.rst doctools/trunk/Doc-3k/reference/lexical_analysis.rst doctools/trunk/Doc-3k/tutorial/errors.rst doctools/trunk/Doc-3k/tutorial/modules.rst Log: Remove redundant section titles after :ref:s. Modified: doctools/trunk/Doc-26/c-api/concrete.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/concrete.rst (original) +++ doctools/trunk/Doc-26/c-api/concrete.rst Thu Aug 2 16:49:09 2007 @@ -1721,9 +1721,8 @@ .. index:: single: PyBufferProcs -More information on the buffer interface is provided in the section "Buffer -Object Structures" (section :ref:`buffer-structs`), under the description for -:ctype:`PyBufferProcs`. +More information on the buffer interface is provided in the section +:ref:`buffer-structs`, under the description for :ctype:`PyBufferProcs`. A "buffer object" is defined in the :file:`bufferobject.h` header (included by :file:`Python.h`). These objects look very similar to string objects at the Modified: doctools/trunk/Doc-26/c-api/newtypes.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/newtypes.rst (original) +++ doctools/trunk/Doc-26/c-api/newtypes.rst Thu Aug 2 16:49:09 2007 @@ -701,8 +701,8 @@ .. cmember:: PyBufferProcs* PyTypeObject.tp_as_buffer Pointer to an additional structure that contains fields relevant only to objects - which implement the buffer interface. These fields are documented in "Buffer - Object Structures" (section :ref:`buffer-structs`). + which implement the buffer interface. These fields are documented in + :ref:`buffer-structs`. The :attr:`tp_as_buffer` field is not inherited, but the contained fields are inherited individually. Modified: doctools/trunk/Doc-26/extending/extending.rst ============================================================================== --- doctools/trunk/Doc-26/extending/extending.rst (original) +++ doctools/trunk/Doc-26/extending/extending.rst Thu Aug 2 16:49:09 2007 @@ -457,15 +457,14 @@ } This function must be registered with the interpreter using the -:const:`METH_VARARGS` flag; this is described in section :ref:`methodtable`, -"The Module's Method Table and Initialization Function." The +:const:`METH_VARARGS` flag; this is described in section :ref:`methodtable`. The :cfunc:`PyArg_ParseTuple` function and its arguments are documented in section -:ref:`parsetuple`, "Extracting Parameters in Extension Functions." +:ref:`parsetuple`. The macros :cfunc:`Py_XINCREF` and :cfunc:`Py_XDECREF` increment/decrement the reference count of an object and are safe in the presence of *NULL* pointers (but note that *temp* will not be *NULL* in this context). More info on them -in section :ref:`refcounts`, "Reference Counts." +in section :ref:`refcounts`. .. index:: single: PyEval_CallObject() Modified: doctools/trunk/Doc-26/install/index.rst ============================================================================== --- doctools/trunk/Doc-26/install/index.rst (original) +++ doctools/trunk/Doc-26/install/index.rst Thu Aug 2 16:49:09 2007 @@ -42,7 +42,7 @@ .. % end{latexonly} -.. _intro: +.. _inst-intro: Introduction ============ @@ -67,7 +67,7 @@ the Distributing Python Modules (XXX reference: ../dist/dist.html) manual. -.. _trivial-install: +.. _inst-trivial-install: Best case: trivial installation ------------------------------- @@ -95,7 +95,7 @@ modules from standard source distributions. -.. _new-standard: +.. _inst-new-standard: The new standard: Distutils --------------------------- @@ -119,12 +119,12 @@ get out of this manual. -.. _standard-install: +.. _inst-standard-install: Standard Build and Install ========================== -As described in section :ref:`new-standard`, building and installing a module +As described in section :ref:`inst-new-standard`, building and installing a module distribution using the Distutils is usually one simple command:: python setup.py install @@ -134,7 +134,7 @@ a :command:`Terminal` window to get a shell prompt. -.. _platform-variations: +.. _inst-platform-variations: Platform variations ------------------- @@ -159,7 +159,7 @@ python setup.py install -.. _splitting-up: +.. _inst-splitting-up: Splitting the job up -------------------- @@ -189,7 +189,7 @@ you'll run lots of individual Distutils commands on their own. -.. _how-build-works: +.. _inst-how-build-works: How building works ------------------ @@ -203,7 +203,7 @@ python setup.py build --build-base=/tmp/pybuild/foo-1.0 (Or you could do this permanently with a directive in your system or personal -Distutils configuration file; see section :ref:`config-files`.) Normally, this +Distutils configuration file; see section :ref:`inst-config-files`.) Normally, this isn't necessary. The default layout for the build tree is as follows:: @@ -228,7 +228,7 @@ of installing Python modules and applications. -.. _how-install-works: +.. _inst-how-install-works: How installation works ---------------------- @@ -290,12 +290,12 @@ If you don't want to install modules to the standard location, or if you don't have permission to write there, then you need to read about alternate -installations in section :ref:`alt-install`. If you want to customize your -installation directories more heavily, see section :ref:`custom-install` on +installations in section :ref:`inst-alt-install`. If you want to customize your +installation directories more heavily, see section :ref:`inst-custom-install` on custom installations. -.. _alt-install: +.. _inst-alt-install: Alternate Installation ====================== @@ -317,7 +317,7 @@ you. -.. _alt-install-prefix: +.. _inst-alt-install-prefix: Alternate installation: the home scheme --------------------------------------- @@ -358,7 +358,7 @@ The :option:`--home` option used to be supported only on Unix. -.. _alt-install-home: +.. _inst-alt-install-home: Alternate installation: Unix (the prefix scheme) ------------------------------------------------ @@ -430,7 +430,7 @@ alternate Python installation, this is immaterial.) -.. _alt-install-windows: +.. _inst-alt-install-windows: Alternate installation: Windows (the prefix scheme) --------------------------------------------------- @@ -461,13 +461,13 @@ +------------------------------+---------------------------+-----------------------------+ -.. _custom-install: +.. _inst-custom-install: Custom Installation =================== Sometimes, the alternate installation schemes described in section -:ref:`alt-install` just don't do what you want. You might want to tweak just +:ref:`inst-alt-install` just don't do what you want. You might want to tweak just one or two directories while keeping everything under the same base directory, or you might want to completely redefine the installation scheme. In either case, you're creating a *custom installation scheme*. @@ -513,7 +513,7 @@ The specified installation directories are relative to :file:`{prefix}`. Of course, you also have to ensure that these directories are in Python's module search path, such as by putting a :file:`.pth` file in :file:`{prefix}`. See -section :ref:`search-path` to find out how to modify Python's search path. +section :ref:`inst-search-path` to find out how to modify Python's search path. If you want to define an entire installation scheme, you just have to supply all of the installation directory options. The recommended way to do this is to @@ -548,7 +548,7 @@ Obviously, specifying the entire installation scheme every time you install a new module distribution would be very tedious. Thus, you can put these options -into your Distutils config file (see section :ref:`config-files`):: +into your Distutils config file (see section :ref:`inst-config-files`):: [install] install-base=$HOME @@ -582,7 +582,7 @@ the Distutils additionally define a few extra variables that may not be in your environment, such as ``$PLAT``. (And of course, on systems that don't have environment variables, such as Mac OS 9, the configuration variables supplied by -the Distutils are the only ones you can use.) See section :ref:`config-files` +the Distutils are the only ones you can use.) See section :ref:`inst-config-files` for details. .. % XXX need some Windows examples---when would custom @@ -591,7 +591,7 @@ .. % XXX I'm not sure where this section should go. -.. _search-path: +.. _inst-search-path: Modifying Python's Search Path ------------------------------ @@ -670,7 +670,7 @@ can modify it by adding or removing entries. -.. _config-files: +.. _inst-config-files: Distutils Configuration Files ============================= @@ -685,7 +685,7 @@ by "later" files. -.. _config-filenames: +.. _inst-config-filenames: Location and names of config files ---------------------------------- @@ -748,7 +748,7 @@ Distutils make no attempt to guess your home directory on Windows.) -.. _config-syntax: +.. _inst-config-syntax: Syntax of config files ---------------------- @@ -802,7 +802,7 @@ See also the "Reference" section of the "Distributing Python Modules" manual. -.. _building-ext: +.. _inst-building-ext: Building Extensions: Tips and Tricks ==================================== @@ -815,7 +815,7 @@ to override the usual Distutils behaviour. -.. _tweak-flags: +.. _inst-tweak-flags: Tweaking compiler/linker flags ------------------------------ @@ -885,7 +885,7 @@ the compiler flags specified in the :file:`Setup` file. -.. _non-ms-compilers: +.. _inst-non-ms-compilers: Using non-Microsoft compilers on Windows ---------------------------------------- @@ -932,7 +932,7 @@ If you want to use the Borland C++ compiler as the default, you could specify this in your personal or system-wide configuration file for Distutils (see -section :ref:`config-files`.) +section :ref:`inst-config-files`.) .. seealso:: @@ -998,7 +998,7 @@ If you want to use any of these options/compilers as default, you should consider to write it in your personal or system-wide configuration file for -Distutils (see section :ref:`config-files`.) +Distutils (see section :ref:`inst-config-files`.) .. seealso:: Modified: doctools/trunk/Doc-26/library/__builtin__.rst ============================================================================== --- doctools/trunk/Doc-26/library/__builtin__.rst (original) +++ doctools/trunk/Doc-26/library/__builtin__.rst Thu Aug 2 16:49:09 2007 @@ -8,7 +8,7 @@ This module provides direct access to all 'built-in' identifiers of Python; for example, ``__builtin__.open`` is the full name for the built-in function -:func:`open`. See chapter :ref:`builtin`, "Built-in Objects." +:func:`open`. See chapter :ref:`builtin`. This module is not normally accessed explicitly by most applications, but can be useful in modules that provide objects with the same name as a built-in value, Modified: doctools/trunk/Doc-26/library/csv.rst ============================================================================== --- doctools/trunk/Doc-26/library/csv.rst (original) +++ doctools/trunk/Doc-26/library/csv.rst Thu Aug 2 16:49:09 2007 @@ -72,7 +72,7 @@ :func:`list_dialects` function. The other optional *fmtparam* keyword arguments can be given to override individual formatting parameters in the current dialect. For full details about the dialect and formatting parameters, see - section :ref:`csv-fmt-params`, "Dialects and Formatting Parameters". + section :ref:`csv-fmt-params`. All data read are returned as strings. No automatic data type conversion is performed. @@ -99,7 +99,7 @@ :func:`list_dialects` function. The other optional *fmtparam* keyword arguments can be given to override individual formatting parameters in the current dialect. For full details about the dialect and formatting parameters, see - section :ref:`csv-fmt-params`, "Dialects and Formatting Parameters". To make it + section :ref:`csv-fmt-params`. To make it as easy as possible to interface with modules which implement the DB API, the value :const:`None` is written as the empty string. While this isn't a reversible transformation, it makes it easier to dump SQL NULL data values to @@ -113,8 +113,7 @@ dialect can be specified either by passing a sub-class of :class:`Dialect`, or by *fmtparam* keyword arguments, or both, with keyword arguments overriding parameters of the dialect. For full details about the dialect and formatting - parameters, see section :ref:`csv-fmt-params`, "Dialects and Formatting - Parameters". + parameters, see section :ref:`csv-fmt-params`. .. function:: unregister_dialect(name) Modified: doctools/trunk/Doc-26/library/ctypes.rst ============================================================================== --- doctools/trunk/Doc-26/library/ctypes.rst (original) +++ doctools/trunk/Doc-26/library/ctypes.rst Thu Aug 2 16:49:09 2007 @@ -2359,6 +2359,6 @@ Arrays and pointers ^^^^^^^^^^^^^^^^^^^ -Not yet written - please see section :ref:`ctypes-pointers`, pointers and -section :ref:`ctypes-arrays`, arrays in the tutorial. +Not yet written - please see the sections :ref:`ctypes-pointers` and +section :ref:`ctypes-arrays` in the tutorial. Modified: doctools/trunk/Doc-26/library/datetime.rst ============================================================================== --- doctools/trunk/Doc-26/library/datetime.rst (original) +++ doctools/trunk/Doc-26/library/datetime.rst Thu Aug 2 16:49:09 2007 @@ -491,7 +491,7 @@ Return a string representing the date, controlled by an explicit format string. Format codes referring to hours, minutes or seconds will see 0 values. See - section :ref:`strftime-behavior` -- :meth:`strftime` behavior. + section :ref:`strftime-behavior`. .. _datetime-datetime: @@ -931,7 +931,7 @@ .. method:: datetime.strftime(format) Return a string representing the date and time, controlled by an explicit format - string. See section :ref:`strftime-behavior` -- :meth:`strftime` behavior. + string. See section :ref:`strftime-behavior`. .. _datetime-time: @@ -1056,7 +1056,7 @@ .. method:: time.strftime(format) Return a string representing the time, controlled by an explicit format string. - See section :ref:`strftime-behavior` -- :meth:`strftime` behavior. + See section :ref:`strftime-behavior`. .. method:: time.utcoffset() Modified: doctools/trunk/Doc-26/library/functions.rst ============================================================================== --- doctools/trunk/Doc-26/library/functions.rst (original) +++ doctools/trunk/Doc-26/library/functions.rst Thu Aug 2 16:49:09 2007 @@ -419,10 +419,9 @@ .. function:: file(filename[, mode[, bufsize]]) - Constructor function for the :class:`file` type, described further in section - :ref:`bltin-file-objects`, "File Objects (XXX reference: bltin-file- - objects.html)". The constructor's arguments are the same as those of the - :func:`open` built-in function described below. + Constructor function for the :class:`file` type, described further in section + :ref:`bltin-file-objects`. The constructor's arguments are the same as those + of the :func:`open` built-in function described below. When opening a file, it's preferable to use :func:`open` instead of invoking this constructor directly. :class:`file` is more suited to type testing (for @@ -721,11 +720,10 @@ .. function:: open(filename[, mode[, bufsize]]) - Open a file, returning an object of the :class:`file` type described in section - :ref:`bltin-file-objects`, "File Objects (XXX reference: bltin-file- - objects.html)". If the file cannot be opened, :exc:`IOError` is raised. When - opening a file, it's preferable to use :func:`open` instead of invoking the - :class:`file` constructor directly. + Open a file, returning an object of the :class:`file` type described in + section :ref:`bltin-file-objects`. If the file cannot be opened, + :exc:`IOError` is raised. When opening a file, it's preferable to use + :func:`open` instead of invoking the :class:`file` constructor directly. The first two arguments are the same as for ``stdio``'s :cfunc:`fopen`: *filename* is the file name to be opened, and *mode* is a string indicating how Modified: doctools/trunk/Doc-26/library/intro.rst ============================================================================== --- doctools/trunk/Doc-26/library/intro.rst (original) +++ doctools/trunk/Doc-26/library/intro.rst Thu Aug 2 16:49:09 2007 @@ -44,9 +44,8 @@ function, module or term in the index (in the back). And finally, if you enjoy learning about random subjects, you choose a random page number (see module :mod:`random`) and read a section or two. Regardless of the order in which you -read the sections of this manual, it helps to start with chapter -:ref:`builtin`, "Built-in Types, Exceptions and Functions," as the remainder of -the manual assumes familiarity with this material. +read the sections of this manual, it helps to start with chapter :ref:`builtin`, +as the remainder of the manual assumes familiarity with this material. Let the show begin! Modified: doctools/trunk/Doc-26/library/logging.rst ============================================================================== --- doctools/trunk/Doc-26/library/logging.rst (original) +++ doctools/trunk/Doc-26/library/logging.rst Thu Aug 2 16:49:09 2007 @@ -1483,8 +1483,8 @@ of the :class:`LogRecord` attributes - such as the default value mentioned above making use of the fact that the user's message and arguments are pre-formatted into a :class:`LogRecord`'s *message* attribute. This format string contains -standard python %-style mapping keys. See section :ref:`typesseq-strings`, -"String Formatting Operations," for more information on string formatting. +standard python %-style mapping keys. See section :ref:`typesseq-strings` +for more information on string formatting. Currently, the useful mapping keys in a :class:`LogRecord` are: Modified: doctools/trunk/Doc-26/library/optparse.rst ============================================================================== --- doctools/trunk/Doc-26/library/optparse.rst (original) +++ doctools/trunk/Doc-26/library/optparse.rst Thu Aug 2 16:49:09 2007 @@ -309,7 +309,7 @@ Actions tell :mod:`optparse` what to do when it encounters an option on the command line. There is a fixed set of actions hard-coded into :mod:`optparse`; adding new actions is an advanced topic covered in section -:ref:`optparse-extending-optparse`, Extending :mod:`optparse`. Most actions tell +:ref:`optparse-extending-optparse`. Most actions tell :mod:`optparse` to store a value in some variable---for example, take a string from the command line and store it in an attribute of ``options``. @@ -369,8 +369,7 @@ default destination for ``"-f"`` is ``f``. :mod:`optparse` also includes built-in ``long`` and ``complex`` types. Adding -types is covered in section :ref:`optparse-extending-optparse`, Extending -:mod:`optparse`. +types is covered in section :ref:`optparse-extending-optparse`. .. _optparse-handling-boolean-options: @@ -415,7 +414,7 @@ call a specified function These are covered in section :ref:`optparse-reference-guide`, Reference Guide -and section :ref:`optparse-option-callbacks`, Option Callbacks. +and section :ref:`optparse-option-callbacks`. .. _optparse-default-values: @@ -704,8 +703,7 @@ ``conflict_handler`` (default: ``"error"``) Specifies what to do when options with conflicting option strings are added to - the parser; see section :ref:`optparse-conflicts-between-options`, Conflicts - between options. + the parser; see section :ref:`optparse-conflicts-between-options`. ``description`` (default: ``None``) A paragraph of text giving a brief overview of your program. :mod:`optparse` @@ -734,8 +732,7 @@ There are several ways to populate the parser with options. The preferred way is by using ``OptionParser.add_option()``, as shown in section -:ref:`optparse-tutorial`, the tutorial. :meth:`add_option` can be called in one -of two ways: +:ref:`optparse-tutorial`. :meth:`add_option` can be called in one of two ways: * pass it an Option instance (as returned by :func:`make_option`) @@ -986,7 +983,7 @@ func(option, opt_str, value, parser, *args, **kwargs) - See section :ref:`optparse-option-callbacks`, Option Callbacks for more detail. + See section :ref:`optparse-option-callbacks` for more detail. * :attr:`help` @@ -1083,9 +1080,9 @@ * ``callback`` - For options with action ``"callback"``, the callable to call when this option is - seen. See section :ref:`optparse-option-callbacks`, Option Callbacks for detail - on the arguments passed to ``callable``. + For options with action ``"callback"``, the callable to call when this option + is seen. See section :ref:`optparse-option-callbacks` for detail on the + arguments passed to ``callable``. * ``callback_args``, ``callback_kwargs`` @@ -1102,7 +1099,7 @@ * ``metavar`` (default: derived from option strings) Stand-in for the option argument(s) to use when printing help text. See section - :ref:`optparse-tutorial`, the tutorial for an example. + :ref:`optparse-tutorial` for an example. .. _optparse-standard-option-types: @@ -1112,7 +1109,7 @@ :mod:`optparse` has six built-in option types: ``string``, ``int``, ``long``, ``choice``, ``float`` and ``complex``. If you need to add new option types, see -section :ref:`optparse-extending-optparse`, Extending :mod:`optparse`. +section :ref:`optparse-extending-optparse`. Arguments to string options are not checked or converted in any way: the text on the command line is stored in the destination (or passed to the callback) as-is. Modified: doctools/trunk/Doc-26/library/os.rst ============================================================================== --- doctools/trunk/Doc-26/library/os.rst (original) +++ doctools/trunk/Doc-26/library/os.rst Thu Aug 2 16:49:09 2007 @@ -122,8 +122,7 @@ getcwd() :noindex: - These functions are described in "Files and Directories" (section - :ref:`os-file-dir`). + These functions are described in :ref:`os-file-dir`. .. function:: ctermid() @@ -422,8 +421,7 @@ available on Unix. For a discussion of possible deadlock conditions related to the use of these -functions, see "Flow Control Issues (XXX reference: popen2-flow-control.html)" -(section :ref:`popen2-flow-control`). +functions, see :ref:`popen2-flow-control`. .. function:: popen2(cmd[, mode[, bufsize]]) Modified: doctools/trunk/Doc-26/library/pyexpat.rst ============================================================================== --- doctools/trunk/Doc-26/library/pyexpat.rst (original) +++ doctools/trunk/Doc-26/library/pyexpat.rst Thu Aug 2 16:49:09 2007 @@ -39,8 +39,7 @@ .. exception:: ExpatError The exception raised when Expat reports an error. See section - :ref:`expaterror-objects`, "ExpatError Exceptions," for more information on - interpreting Expat errors. + :ref:`expaterror-objects` for more information on interpreting Expat errors. .. exception:: error Modified: doctools/trunk/Doc-26/library/shlex.rst ============================================================================== --- doctools/trunk/Doc-26/library/shlex.rst (original) +++ doctools/trunk/Doc-26/library/shlex.rst Thu Aug 2 16:49:09 2007 @@ -58,7 +58,7 @@ was introduced in Python 2.3, and defines the operational mode. When *posix* is not true (default), the :class:`shlex` instance will operate in compatibility mode. When operating in POSIX mode, :class:`shlex` will try to be as close as - possible to the POSIX shell parsing rules. See section :ref:`shlex-objects`. + possible to the POSIX shell parsing rules. .. seealso:: Modified: doctools/trunk/Doc-26/library/socket.rst ============================================================================== --- doctools/trunk/Doc-26/library/socket.rst (original) +++ doctools/trunk/Doc-26/library/socket.rst Thu Aug 2 16:49:09 2007 @@ -571,13 +571,12 @@ .. index:: single: I/O control; buffering Return a :dfn:`file object` associated with the socket. (File objects are - described in :ref:`bltin-file-objects`, "File Objects.") The file object + described in :ref:`bltin-file-objects`.) The file object references a :cfunc:`dup`\ ped version of the socket file descriptor, so the file object and socket object may be closed or garbage-collected independently. The socket must be in blocking mode (it can not have a timeout). The optional *mode* and *bufsize* arguments are interpreted the same way as by the built-in - :func:`file` function; see "Built-in Functions" (section :ref:`built-in-funcs`) - for more information. + :func:`file` function; see :ref:`built-in-funcs` for more information. .. method:: socket.recv(bufsize[, flags]) Modified: doctools/trunk/Doc-26/library/sqlite3.rst ============================================================================== --- doctools/trunk/Doc-26/library/sqlite3.rst (original) +++ doctools/trunk/Doc-26/library/sqlite3.rst Thu Aug 2 16:49:09 2007 @@ -227,8 +227,8 @@ .. attribute:: Connection.isolation_level Get or set the current isolation level. None for autocommit mode or one of - "DEFERRED", "IMMEDIATE" or "EXLUSIVE". See "Controlling Transactions", section - :ref:`sqlite3-controlling-transactions`, for a more detailed explanation. + "DEFERRED", "IMMEDIATE" or "EXLUSIVE". See section + :ref:`sqlite3-controlling-transactions` for a more detailed explanation. .. method:: Connection.cursor([cursorClass]) @@ -629,9 +629,8 @@ * Explicitly via the column name -Both ways are described in "Module Constants", section -:ref:`sqlite3-module-contents`, in the entries for the constants -:const:`PARSE_DECLTYPES` and :const:`PARSE_COLNAMES`. +Both ways are described in section :ref:`sqlite3-module-contents`, in the entries +for the constants :const:`PARSE_DECLTYPES` and :const:`PARSE_COLNAMES`. The following example illustrates both approaches. Modified: doctools/trunk/Doc-26/library/stdtypes.rst ============================================================================== --- doctools/trunk/Doc-26/library/stdtypes.rst (original) +++ doctools/trunk/Doc-26/library/stdtypes.rst Thu Aug 2 16:49:09 2007 @@ -341,7 +341,7 @@ for well-defined conversions. (3) - See section :ref:`built-in-funcs`, "Built-in Functions," for a full description. + See :ref:`built-in-funcs` for a full description. (4) Complex floor division operator, modulo operator, and :func:`divmod`. @@ -1739,9 +1739,9 @@ File objects are implemented using C's ``stdio`` package and can be created with the built-in constructor :func:`file` described in section -:ref:`built-in-funcs`, "Built-in Functions." [#]_ File objects are also -returned by some other built-in functions and methods, such as :func:`os.popen` -and :func:`os.fdopen` and the :meth:`makefile` method of socket objects. +:ref:`built-in-funcs`. [#]_ File objects are also returned by some other +built-in functions and methods, such as :func:`os.popen` and :func:`os.fdopen` +and the :meth:`makefile` method of socket objects. When a file operation fails for an I/O-related reason, the exception :exc:`IOError` is raised. This includes situations where the operation is not @@ -2366,4 +2366,3 @@ might matter, for example, if you want to make an exact copy of a file while scanning its lines) to tell whether the last line of a file ended in a newline or not (yes this happens!). - Modified: doctools/trunk/Doc-26/library/string.rst ============================================================================== --- doctools/trunk/Doc-26/library/string.rst (original) +++ doctools/trunk/Doc-26/library/string.rst Thu Aug 2 16:49:09 2007 @@ -245,10 +245,9 @@ --------------------------- The following list of functions are also defined as methods of string and -Unicode objects; see "String Methods" (section :ref:`string-methods`) for more -information on those. You should consider these functions as deprecated, -although they will not be removed until Python 3.0. The functions defined in -this module are: +Unicode objects; see section :ref:`string-methods` for more information on +those. You should consider these functions as deprecated, although they will +not be removed until Python 3.0. The functions defined in this module are: .. function:: atof(s) Modified: doctools/trunk/Doc-26/library/sys.rst ============================================================================== --- doctools/trunk/Doc-26/library/sys.rst (original) +++ doctools/trunk/Doc-26/library/sys.rst Thu Aug 2 16:49:09 2007 @@ -365,7 +365,7 @@ Their intended use is to allow an interactive user to import a debugger module and engage in post-mortem debugging without having to re-execute the command that caused the error. (Typical use is ``import pdb; pdb.pm()`` to enter the - post-mortem debugger; see chapter :ref:`debugger`, "The Python Debugger," for + post-mortem debugger; see chapter :ref:`debugger` for more information.) The meaning of the variables is the same as that of the return values from @@ -528,9 +528,9 @@ single: trace function single: debugger - Set the system's trace function, which allows you to implement a Python source - code debugger in Python. See section :ref:`debugger-hooks`, "How It Works," in - the chapter on the Python debugger. The function is thread-specific; for a + Set the system's trace function, which allows you to implement a Python + source code debugger in Python. See section :ref:`debugger-hooks` in the + chapter on the Python debugger. The function is thread-specific; for a debugger to support multiple threads, it must be registered using :func:`settrace` for each thread being debugged. Modified: doctools/trunk/Doc-26/library/tarfile.rst ============================================================================== --- doctools/trunk/Doc-26/library/tarfile.rst (original) +++ doctools/trunk/Doc-26/library/tarfile.rst Thu Aug 2 16:49:09 2007 @@ -37,7 +37,7 @@ Return a :class:`TarFile` object for the pathname *name*. For detailed information on :class:`TarFile` objects and the keyword arguments that are - allowed, see TarFile Objects (section :ref:`tarfile-objects`). + allowed, see :ref:`tarfile-objects`. *mode* has to be a string of the form ``'filemode[:compression]'``, it defaults to ``'r'``. Here is a full list of mode combinations: @@ -75,14 +75,14 @@ For special purposes, there is a second format for *mode*: ``'filemode|[compression]'``. :func:`open` will return a :class:`TarFile` - object that processes its data as a stream of blocks. No random seeking will be - done on the file. If given, *fileobj* may be any object that has a :meth:`read` - or :meth:`write` method (depending on the *mode*). *bufsize* specifies the - blocksize and defaults to ``20 * 512`` bytes. Use this variant in combination - with e.g. ``sys.stdin``, a socket file object or a tape device. However, such a - :class:`TarFile` object is limited in that it does not allow to be accessed - randomly, see "Examples" (section :ref:`tar-examples`). The currently possible - modes: + object that processes its data as a stream of blocks. No random seeking will + be done on the file. If given, *fileobj* may be any object that has a + :meth:`read` or :meth:`write` method (depending on the *mode*). *bufsize* + specifies the blocksize and defaults to ``20 * 512`` bytes. Use this variant + in combination with e.g. ``sys.stdin``, a socket file object or a tape + device. However, such a :class:`TarFile` object is limited in that it does + not allow to be accessed randomly, see :ref:`tar-examples`. The currently + possible modes: +-------------+--------------------------------------------+ | Mode | Action | @@ -112,8 +112,7 @@ .. class:: TarFile Class for reading and writing tar archives. Do not use this class directly, - better use :func:`open` instead. See "TarFile Objects" (section - :ref:`tarfile-objects`). + better use :func:`open` instead. See :ref:`tarfile-objects`. .. function:: is_tarfile(name) @@ -221,7 +220,7 @@ archive is a sequence of blocks. An archive member (a stored file) is made up of a header block followed by data blocks. It is possible to store a file in a tar archive several times. Each archive member is represented by a :class:`TarInfo` -object, see TarInfo Objects (section :ref:`tarinfo-objects`) for details. +object, see :ref:`tarinfo-objects` for details. .. class:: TarFile(name=None, mode='r', fileobj=None, format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False, ignore_zeros=False, encoding=None, errors=None, pax_headers=None, debug=0, errorlevel=0) Modified: doctools/trunk/Doc-26/library/tkinter.rst ============================================================================== --- doctools/trunk/Doc-26/library/tkinter.rst (original) +++ doctools/trunk/Doc-26/library/tkinter.rst Thu Aug 2 16:49:09 2007 @@ -22,9 +22,8 @@ classes. In addition, the internal module :mod:`_tkinter` provides a threadsafe mechanism which allows Python and Tcl to interact. -Tk is not the only GUI for Python; see section :ref:`other-gui-packages`, "Other -User Interface Modules and Packages," for more information on other GUI toolkits -for Python. +Tk is not the only GUI for Python; see section :ref:`other-gui-packages` for +more information on other GUI toolkits for Python. .. % Other sections I have in mind are .. % Tkinter internals Modified: doctools/trunk/Doc-26/library/urlparse.rst ============================================================================== --- doctools/trunk/Doc-26/library/urlparse.rst (original) +++ doctools/trunk/Doc-26/library/urlparse.rst Thu Aug 2 16:49:09 2007 @@ -90,8 +90,8 @@ | | | if present | | +------------------+-------+--------------------------+----------------------+ - See section :ref:`urlparse-result-object`, "Results of :func:`urlparse` and - :func:`urlsplit`," for more information on the result object. + See section :ref:`urlparse-result-object` for more information on the result + object. .. versionchanged:: 2.5 Added attributes to return value. @@ -141,8 +141,8 @@ | | | if present | | +------------------+-------+-------------------------+----------------------+ - See section :ref:`urlparse-result-object`, "Results of :func:`urlparse` and - :func:`urlsplit`," for more information on the result object. + See section :ref:`urlparse-result-object` for more information on the result + object. .. versionadded:: 2.2 Modified: doctools/trunk/Doc-26/library/userdict.rst ============================================================================== --- doctools/trunk/Doc-26/library/userdict.rst (original) +++ doctools/trunk/Doc-26/library/userdict.rst Thu Aug 2 16:49:09 2007 @@ -177,8 +177,8 @@ hard to track down. In addition to supporting the methods and operations of string and Unicode -objects (see section :ref:`string-methods`, "String Methods"), -:class:`UserString` instances provide the following attribute: +objects (see section :ref:`string-methods`), :class:`UserString` instances +provide the following attribute: .. attribute:: MutableString.data Modified: doctools/trunk/Doc-26/library/xml.dom.rst ============================================================================== --- doctools/trunk/Doc-26/library/xml.dom.rst (original) +++ doctools/trunk/Doc-26/library/xml.dom.rst Thu Aug 2 16:49:09 2007 @@ -65,8 +65,7 @@ and OMG IDL. The Python mapping defined here is based in large part on the IDL version of the specification, but strict compliance is not required (though implementations are free to support the strict mapping from IDL). See section -:ref:`dom-conformance`, "Conformance," for a detailed discussion of mapping -requirements. +:ref:`dom-conformance` for a detailed discussion of mapping requirements. .. seealso:: @@ -173,40 +172,40 @@ strings. It is fairly rare that you must do this, however, so this usage is not yet documented. -+--------------------------------+---------------------------------+---------------------------------+ -| Interface | Section | Purpose | -+================================+=================================+=================================+ -| :class:`DOMImplementation` | :ref:`dom-implementation- | Interface to the underlying | -| | objects` | implementation. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`Node` | :ref:`dom-node-objects` | Base interface for most objects | -| | | in a document. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`NodeList` | :ref:`dom-nodelist-objects` | Interface for a sequence of | -| | | nodes. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`DocumentType` | :ref:`dom-documenttype-objects` | Information about the | -| | | declarations needed to process | -| | | a document. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`Document` | :ref:`dom-document-objects` | Object which represents an | -| | | entire document. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`Element` | :ref:`dom-element-objects` | Element nodes in the document | -| | | hierarchy. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`Attr` | :ref:`dom-attr-objects` | Attribute value nodes on | -| | | element nodes. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`Comment` | :ref:`dom-comment-objects` | Representation of comments in | -| | | the source document. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`Text` | :ref:`dom-text-objects` | Nodes containing textual | -| | | content from the document. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`ProcessingInstruction` | :ref:`dom-pi-objects` | Processing instruction | -| | | representation. | -+--------------------------------+---------------------------------+---------------------------------+ ++--------------------------------+-----------------------------------+---------------------------------+ +| Interface | Section | Purpose | ++================================+===================================+=================================+ +| :class:`DOMImplementation` | :ref:`dom-implementation-objects` | Interface to the underlying | +| | | implementation. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`Node` | :ref:`dom-node-objects` | Base interface for most objects | +| | | in a document. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`NodeList` | :ref:`dom-nodelist-objects` | Interface for a sequence of | +| | | nodes. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`DocumentType` | :ref:`dom-documenttype-objects` | Information about the | +| | | declarations needed to process | +| | | a document. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`Document` | :ref:`dom-document-objects` | Object which represents an | +| | | entire document. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`Element` | :ref:`dom-element-objects` | Element nodes in the document | +| | | hierarchy. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`Attr` | :ref:`dom-attr-objects` | Attribute value nodes on | +| | | element nodes. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`Comment` | :ref:`dom-comment-objects` | Representation of comments in | +| | | the source document. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`Text` | :ref:`dom-text-objects` | Nodes containing textual | +| | | content from the document. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`ProcessingInstruction` | :ref:`dom-pi-objects` | Processing instruction | +| | | representation. | ++--------------------------------+-----------------------------------+---------------------------------+ An additional section describes the exceptions defined for working with the DOM in Python. Modified: doctools/trunk/Doc-26/library/xml.sax.reader.rst ============================================================================== --- doctools/trunk/Doc-26/library/xml.sax.reader.rst (original) +++ doctools/trunk/Doc-26/library/xml.sax.reader.rst Thu Aug 2 16:49:09 2007 @@ -70,24 +70,23 @@ .. class:: AttributesImpl(attrs) - This is an implementation of the :class:`Attributes` interface (XXX reference: - attributes-objects.html) (see section :ref:`attributes-objects`). This is a - dictionary-like object which represents the element attributes in a - :meth:`startElement` call. In addition to the most useful dictionary operations, - it supports a number of other methods as described by the interface. Objects of - this class should be instantiated by readers; *attrs* must be a dictionary-like - object containing a mapping from attribute names to attribute values. + This is an implementation of the :class:`Attributes` interface (see section + :ref:`attributes-objects`). This is a dictionary-like object which + represents the element attributes in a :meth:`startElement` call. In addition + to the most useful dictionary operations, it supports a number of other + methods as described by the interface. Objects of this class should be + instantiated by readers; *attrs* must be a dictionary-like object containing + a mapping from attribute names to attribute values. .. class:: AttributesNSImpl(attrs, qnames) Namespace-aware variant of :class:`AttributesImpl`, which will be passed to :meth:`startElementNS`. It is derived from :class:`AttributesImpl`, but - understands attribute names as two-tuples of *namespaceURI* and *localname*. In - addition, it provides a number of methods expecting qualified names as they - appear in the original document. This class implements the - :class:`AttributesNS` interface (XXX reference: attributes-ns-objects.html) (see - section :ref:`attributes-ns-objects`). + understands attribute names as two-tuples of *namespaceURI* and + *localname*. In addition, it provides a number of methods expecting qualified + names as they appear in the original document. This class implements the + :class:`AttributesNS` interface (see section :ref:`attributes-ns-objects`). .. _xmlreader-objects: @@ -359,9 +358,9 @@ The :class:`AttributesNS` Interface ----------------------------------- -This interface is a subtype of the :class:`Attributes` interface (XXX reference: -attributes-objects.html) (see section :ref:`attributes-objects`). All methods -supported by that interface are also available on :class:`AttributesNS` objects. +This interface is a subtype of the :class:`Attributes` interface (see section +:ref:`attributes-objects`). All methods supported by that interface are also +available on :class:`AttributesNS` objects. The following methods are also available: Modified: doctools/trunk/Doc-26/library/zipfile.rst ============================================================================== --- doctools/trunk/Doc-26/library/zipfile.rst (original) +++ doctools/trunk/Doc-26/library/zipfile.rst Thu Aug 2 16:49:09 2007 @@ -40,8 +40,8 @@ .. class:: ZipFile - The class for reading and writing ZIP files. See "ZipFile Objects" (section - :ref:`zipfile-objects`) for constructor details. + The class for reading and writing ZIP files. See section + :ref:`zipfile-objects` for constructor details. .. class:: PyZipFile @@ -51,14 +51,14 @@ .. class:: ZipInfo([filename[, date_time]]) - Class used to represent information about a member of an archive. Instances of - this class are returned by the :meth:`getinfo` and :meth:`infolist` methods of - :class:`ZipFile` objects. Most users of the :mod:`zipfile` module will not need - to create these, but only use those created by this module. *filename* should be - the full name of the archive member, and *date_time* should be a tuple - containing six fields which describe the time of the last modification to the - file; the fields are described in section :ref:`zipinfo-objects`, "ZipInfo - Objects." + Class used to represent information about a member of an archive. Instances + of this class are returned by the :meth:`getinfo` and :meth:`infolist` + methods of :class:`ZipFile` objects. Most users of the :mod:`zipfile` module + will not need to create these, but only use those created by this + module. *filename* should be the full name of the archive member, and + *date_time* should be a tuple containing six fields which describe the time + of the last modification to the file; the fields are described in section + :ref:`zipinfo-objects`. .. function:: is_zipfile(filename) Modified: doctools/trunk/Doc-26/library/zipimport.rst ============================================================================== --- doctools/trunk/Doc-26/library/zipimport.rst (original) +++ doctools/trunk/Doc-26/library/zipimport.rst Thu Aug 2 16:49:09 2007 @@ -44,8 +44,8 @@ .. class:: zipimporter - The class for importing ZIP files. See "zipimporter Objects" (section - :ref:`zipimporter-objects`) for constructor details. + The class for importing ZIP files. See section :ref:`zipimporter-objects` + for constructor details. .. seealso:: Modified: doctools/trunk/Doc-26/maclib/using.rst ============================================================================== --- doctools/trunk/Doc-26/maclib/using.rst (original) +++ doctools/trunk/Doc-26/maclib/using.rst Thu Aug 2 16:49:09 2007 @@ -108,7 +108,7 @@ /.MacOSX/environment.plist`. See Apple's Technical Document QA1067 for details. For more information on installation Python packages in MacPython, see section -:ref:`mac-package-manager`, "Installing Additional Python Packages." +:ref:`mac-package-manager`. .. _ide: Modified: doctools/trunk/Doc-26/reference/datamodel.rst ============================================================================== --- doctools/trunk/Doc-26/reference/datamodel.rst (original) +++ doctools/trunk/Doc-26/reference/datamodel.rst Thu Aug 2 16:49:09 2007 @@ -442,7 +442,7 @@ the same dictionary entry. Dictionaries are mutable; they can be created by the ``{...}`` notation (see - section :ref:`dict`, "Dictionary Displays"). + section :ref:`dict`). .. index:: module: dbm @@ -462,7 +462,7 @@ pair: function; argument These are the types to which the function call operation (see section - :ref:`calls`, "Calls") can be applied: + :ref:`calls`) can be applied: User-defined functions .. index:: @@ -470,9 +470,9 @@ object: function object: user-defined function - A user-defined function object is created by a function definition (see section - :ref:`function`, "Function definitions"). It should be called with an argument - list containing the same number of items as the function's formal parameter + A user-defined function object is created by a function definition (see + section :ref:`function`). It should be called with an argument list + containing the same number of items as the function's formal parameter list. Special attributes: @@ -649,7 +649,7 @@ single: generator; iterator A function or method which uses the :keyword:`yield` statement (see section - :ref:`yield`, "The :keyword:`yield` statement") is called a :dfn:`generator + :ref:`yield`) is called a :dfn:`generator function`. Such a function, when called, always returns an iterator object which can be used to execute the body of the function: calling the iterator's :meth:`next` method will cause the function to execute until it provides a value @@ -717,7 +717,7 @@ object: module Modules are imported by the :keyword:`import` statement (see section - :ref:`import`, "The :keyword:`import` statement"). A module object has a + :ref:`import`). A module object has a namespace implemented by a dictionary object (this is the dictionary referenced by the func_globals attribute of functions defined in the module). Attribute references are translated to lookups in this dictionary, e.g., ``m.x`` is @@ -750,8 +750,8 @@ of the shared library file. Classes - Class objects are created by class definitions (see section :ref:`class`, "Class - definitions"). A class has a namespace implemented by a dictionary object. Class + Class objects are created by class definitions (see section :ref:`class`). + A class has a namespace implemented by a dictionary object. Class attribute references are translated to lookups in this dictionary, e.g., ``C.x`` is translated to ``C.__dict__["x"]``. When the attribute name is not found there, the attribute search continues in the base classes. The search is depth- @@ -838,8 +838,7 @@ object: mapping Class instances can pretend to be numbers, sequences, or mappings if they have - methods with certain special names. See section :ref:`specialnames`, "Special - method names." + methods with certain special names. See section :ref:`specialnames`. .. index:: single: __dict__ (instance attribute) @@ -1008,7 +1007,7 @@ unwinds the execution stack, at each unwound level a traceback object is inserted in front of the current traceback. When an exception handler is entered, the stack trace is made available to the program. (See section - :ref:`try`, "The ``try`` statement.") It is accessible as ``sys.exc_traceback``, + :ref:`try`.) It is accessible as ``sys.exc_traceback``, and also as the third item of the tuple returned by ``sys.exc_info()``. The latter is the preferred interface, since it works correctly when the program is using multiple threads. When the program contains no suitable handler, the stack Modified: doctools/trunk/Doc-26/reference/expressions.rst ============================================================================== --- doctools/trunk/Doc-26/reference/expressions.rst (original) +++ doctools/trunk/Doc-26/reference/expressions.rst Thu Aug 2 16:49:09 2007 @@ -1253,7 +1253,7 @@ the same box have the same precedence. Unless the syntax is explicitly given, operators are binary. Operators in the same box group left to right (except for comparisons, including tests, which all have the same precedence and chain from -left to right --- see section :ref:`comparisons` -- and exponentiation, which +left to right --- see section :ref:`comparisons` --- and exponentiation, which groups from right to left). +-----------------------------------------------+-------------------------------------+ Modified: doctools/trunk/Doc-26/reference/lexical_analysis.rst ============================================================================== --- doctools/trunk/Doc-26/reference/lexical_analysis.rst (original) +++ doctools/trunk/Doc-26/reference/lexical_analysis.rst Thu Aug 2 16:49:09 2007 @@ -386,8 +386,7 @@ Not imported by ``from module import *``. The special identifier ``_`` is used in the interactive interpreter to store the result of the last evaluation; it is stored in the :mod:`__builtin__` module. When not in interactive mode, ``_`` - has no special meaning and is not defined. See section :ref:`import`, "The - :keyword:`import` statement." + has no special meaning and is not defined. See section :ref:`import`. .. note:: @@ -400,13 +399,13 @@ implementation (including the standard library); applications should not expect to define additional names using this convention. The set of names of this class defined by Python may be extended in future versions. See section - :ref:`specialnames`, "Special method names." + :ref:`specialnames`. ``__*`` Class-private names. Names in this category, when used within the context of a class definition, are re-written to use a mangled form to help avoid name clashes between "private" attributes of base and derived classes. See section - :ref:`atom-identifiers`, "Identifiers (Names)." + :ref:`atom-identifiers`. .. _literals: Modified: doctools/trunk/Doc-26/reference/simple_stmts.rst ============================================================================== --- doctools/trunk/Doc-26/reference/simple_stmts.rst (original) +++ doctools/trunk/Doc-26/reference/simple_stmts.rst Thu Aug 2 16:49:09 2007 @@ -904,7 +904,7 @@ then executed (unless a syntax error occurs). If it is an open file, the file is parsed until EOF and executed. If it is a code object, it is simply executed. In all cases, the code that's executed is expected to be valid as -file input (see section :ref:`file-input`, "File input"). Be aware that the +file input (see section :ref:`file-input`). Be aware that the :keyword:`return` and :keyword:`yield` statements may not be used outside of function definitions even within the context of code passed to the :keyword:`exec` statement. Modified: doctools/trunk/Doc-26/tutorial/errors.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/errors.rst (original) +++ doctools/trunk/Doc-26/tutorial/errors.rst Thu Aug 2 16:49:09 2007 @@ -316,7 +316,7 @@ Many standard modules define their own exceptions to report errors that may occur in functions they define. More information on classes is presented in -chapter :ref:`tut-classes`, "Classes." +chapter :ref:`tut-classes`. .. _tut-cleanup: Modified: doctools/trunk/Doc-26/tutorial/modules.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/modules.rst (original) +++ doctools/trunk/Doc-26/tutorial/modules.rst Thu Aug 2 16:49:09 2007 @@ -152,16 +152,15 @@ found there, the search continues in an installation-dependent default path; on Unix, this is usually :file:`.:/usr/local/lib/python`. -Actually, modules are searched in the list of directories given by the variable -``sys.path`` which is initialized from the directory containing the input -script (or the current directory), :envvar:`PYTHONPATH` and the installation- -dependent default. This allows Python programs that know what they're doing to -modify or replace the module search path. Note that because the directory -containing the script being run is on the search path, it is important that the -script not have the same name as a standard module, or Python will attempt to -load the script as a module when that module is imported. This will generally be -an error. See section :ref:`tut-standardmodules`, "Standard Modules," for more -information. +Actually, modules are searched in the list of directories given by the variable +``sys.path`` which is initialized from the directory containing the input script +(or the current directory), :envvar:`PYTHONPATH` and the installation- dependent +default. This allows Python programs that know what they're doing to modify or +replace the module search path. Note that because the directory containing the +script being run is on the search path, it is important that the script not have +the same name as a standard module, or Python will attempt to load the script as +a module when that module is imported. This will generally be an error. See +section :ref:`tut-standardmodules` for more information. "Compiled" Python files Modified: doctools/trunk/Doc-3k/c-api/concrete.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/concrete.rst (original) +++ doctools/trunk/Doc-3k/c-api/concrete.rst Thu Aug 2 16:49:09 2007 @@ -1838,9 +1838,8 @@ .. index:: single: PyBufferProcs -More information on the buffer interface is provided in the section "Buffer -Object Structures" (section :ref:`buffer-structs`), under the description for -:ctype:`PyBufferProcs`. +More information on the buffer interface is provided in the section +:ref:`buffer-structs`, under the description for :ctype:`PyBufferProcs`. A "buffer object" is defined in the :file:`bufferobject.h` header (included by :file:`Python.h`). These objects look very similar to string objects at the Modified: doctools/trunk/Doc-3k/c-api/newtypes.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/newtypes.rst (original) +++ doctools/trunk/Doc-3k/c-api/newtypes.rst Thu Aug 2 16:49:09 2007 @@ -701,8 +701,8 @@ .. cmember:: PyBufferProcs* PyTypeObject.tp_as_buffer Pointer to an additional structure that contains fields relevant only to objects - which implement the buffer interface. These fields are documented in "Buffer - Object Structures" (section :ref:`buffer-structs`). + which implement the buffer interface. These fields are documented in + :ref:`buffer-structs`. The :attr:`tp_as_buffer` field is not inherited, but the contained fields are inherited individually. Modified: doctools/trunk/Doc-3k/extending/extending.rst ============================================================================== --- doctools/trunk/Doc-3k/extending/extending.rst (original) +++ doctools/trunk/Doc-3k/extending/extending.rst Thu Aug 2 16:49:09 2007 @@ -453,15 +453,14 @@ } This function must be registered with the interpreter using the -:const:`METH_VARARGS` flag; this is described in section :ref:`methodtable`, -"The Module's Method Table and Initialization Function." The +:const:`METH_VARARGS` flag; this is described in section :ref:`methodtable`. The :cfunc:`PyArg_ParseTuple` function and its arguments are documented in section -:ref:`parsetuple`, "Extracting Parameters in Extension Functions." +:ref:`parsetuple`. The macros :cfunc:`Py_XINCREF` and :cfunc:`Py_XDECREF` increment/decrement the reference count of an object and are safe in the presence of *NULL* pointers (but note that *temp* will not be *NULL* in this context). More info on them -in section :ref:`refcounts`, "Reference Counts." +in section :ref:`refcounts`. .. index:: single: PyEval_CallObject() Modified: doctools/trunk/Doc-3k/install/index.rst ============================================================================== --- doctools/trunk/Doc-3k/install/index.rst (original) +++ doctools/trunk/Doc-3k/install/index.rst Thu Aug 2 16:49:09 2007 @@ -42,7 +42,7 @@ .. % end{latexonly} -.. _intro: +.. _inst-intro: Introduction ============ @@ -67,7 +67,7 @@ the Distributing Python Modules (XXX reference: ../dist/dist.html) manual. -.. _trivial-install: +.. _inst-trivial-install: Best case: trivial installation ------------------------------- @@ -95,7 +95,7 @@ modules from standard source distributions. -.. _new-standard: +.. _inst-new-standard: The new standard: Distutils --------------------------- @@ -119,12 +119,12 @@ get out of this manual. -.. _standard-install: +.. _inst-standard-install: Standard Build and Install ========================== -As described in section :ref:`new-standard`, building and installing a module +As described in section :ref:`inst-new-standard`, building and installing a module distribution using the Distutils is usually one simple command:: python setup.py install @@ -134,7 +134,7 @@ a :command:`Terminal` window to get a shell prompt. -.. _platform-variations: +.. _inst-platform-variations: Platform variations ------------------- @@ -159,7 +159,7 @@ python setup.py install -.. _splitting-up: +.. _inst-splitting-up: Splitting the job up -------------------- @@ -189,7 +189,7 @@ you'll run lots of individual Distutils commands on their own. -.. _how-build-works: +.. _inst-how-build-works: How building works ------------------ @@ -203,7 +203,7 @@ python setup.py build --build-base=/tmp/pybuild/foo-1.0 (Or you could do this permanently with a directive in your system or personal -Distutils configuration file; see section :ref:`config-files`.) Normally, this +Distutils configuration file; see section :ref:`inst-config-files`.) Normally, this isn't necessary. The default layout for the build tree is as follows:: @@ -228,7 +228,7 @@ of installing Python modules and applications. -.. _how-install-works: +.. _inst-how-install-works: How installation works ---------------------- @@ -290,12 +290,12 @@ If you don't want to install modules to the standard location, or if you don't have permission to write there, then you need to read about alternate -installations in section :ref:`alt-install`. If you want to customize your -installation directories more heavily, see section :ref:`custom-install` on +installations in section :ref:`inst-alt-install`. If you want to customize your +installation directories more heavily, see section :ref:`inst-custom-install` on custom installations. -.. _alt-install: +.. _inst-alt-install: Alternate Installation ====================== @@ -317,7 +317,7 @@ you. -.. _alt-install-prefix: +.. _inst-alt-install-prefix: Alternate installation: the home scheme --------------------------------------- @@ -358,7 +358,7 @@ The :option:`--home` option used to be supported only on Unix. -.. _alt-install-home: +.. _inst-alt-install-home: Alternate installation: Unix (the prefix scheme) ------------------------------------------------ @@ -430,7 +430,7 @@ alternate Python installation, this is immaterial.) -.. _alt-install-windows: +.. _inst-alt-install-windows: Alternate installation: Windows (the prefix scheme) --------------------------------------------------- @@ -461,13 +461,13 @@ +------------------------------+---------------------------+-----------------------------+ -.. _custom-install: +.. _inst-custom-install: Custom Installation =================== Sometimes, the alternate installation schemes described in section -:ref:`alt-install` just don't do what you want. You might want to tweak just +:ref:`inst-alt-install` just don't do what you want. You might want to tweak just one or two directories while keeping everything under the same base directory, or you might want to completely redefine the installation scheme. In either case, you're creating a *custom installation scheme*. @@ -513,7 +513,7 @@ The specified installation directories are relative to :file:`{prefix}`. Of course, you also have to ensure that these directories are in Python's module search path, such as by putting a :file:`.pth` file in :file:`{prefix}`. See -section :ref:`search-path` to find out how to modify Python's search path. +section :ref:`inst-search-path` to find out how to modify Python's search path. If you want to define an entire installation scheme, you just have to supply all of the installation directory options. The recommended way to do this is to @@ -548,7 +548,7 @@ Obviously, specifying the entire installation scheme every time you install a new module distribution would be very tedious. Thus, you can put these options -into your Distutils config file (see section :ref:`config-files`):: +into your Distutils config file (see section :ref:`inst-config-files`):: [install] install-base=$HOME @@ -582,7 +582,7 @@ the Distutils additionally define a few extra variables that may not be in your environment, such as ``$PLAT``. (And of course, on systems that don't have environment variables, such as Mac OS 9, the configuration variables supplied by -the Distutils are the only ones you can use.) See section :ref:`config-files` +the Distutils are the only ones you can use.) See section :ref:`inst-config-files` for details. .. % XXX need some Windows examples---when would custom @@ -591,7 +591,7 @@ .. % XXX I'm not sure where this section should go. -.. _search-path: +.. _inst-search-path: Modifying Python's Search Path ------------------------------ @@ -670,7 +670,7 @@ can modify it by adding or removing entries. -.. _config-files: +.. _inst-config-files: Distutils Configuration Files ============================= @@ -685,7 +685,7 @@ by "later" files. -.. _config-filenames: +.. _inst-config-filenames: Location and names of config files ---------------------------------- @@ -748,7 +748,7 @@ Distutils make no attempt to guess your home directory on Windows.) -.. _config-syntax: +.. _inst-config-syntax: Syntax of config files ---------------------- @@ -802,7 +802,7 @@ See also the "Reference" section of the "Distributing Python Modules" manual. -.. _building-ext: +.. _inst-building-ext: Building Extensions: Tips and Tricks ==================================== @@ -815,7 +815,7 @@ to override the usual Distutils behaviour. -.. _tweak-flags: +.. _inst-tweak-flags: Tweaking compiler/linker flags ------------------------------ @@ -885,7 +885,7 @@ the compiler flags specified in the :file:`Setup` file. -.. _non-ms-compilers: +.. _inst-non-ms-compilers: Using non-Microsoft compilers on Windows ---------------------------------------- @@ -932,7 +932,7 @@ If you want to use the Borland C++ compiler as the default, you could specify this in your personal or system-wide configuration file for Distutils (see -section :ref:`config-files`.) +section :ref:`inst-config-files`.) .. seealso:: @@ -998,7 +998,7 @@ If you want to use any of these options/compilers as default, you should consider to write it in your personal or system-wide configuration file for -Distutils (see section :ref:`config-files`.) +Distutils (see section :ref:`inst-config-files`.) .. seealso:: Modified: doctools/trunk/Doc-3k/library/__builtin__.rst ============================================================================== --- doctools/trunk/Doc-3k/library/__builtin__.rst (original) +++ doctools/trunk/Doc-3k/library/__builtin__.rst Thu Aug 2 16:49:09 2007 @@ -8,7 +8,7 @@ This module provides direct access to all 'built-in' identifiers of Python; for example, ``__builtin__.open`` is the full name for the built-in function -:func:`open`. See chapter :ref:`builtin`, "Built-in Objects." +:func:`open`. See chapter :ref:`builtin`. This module is not normally accessed explicitly by most applications, but can be useful in modules that provide objects with the same name as a built-in value, Modified: doctools/trunk/Doc-3k/library/csv.rst ============================================================================== --- doctools/trunk/Doc-3k/library/csv.rst (original) +++ doctools/trunk/Doc-3k/library/csv.rst Thu Aug 2 16:49:09 2007 @@ -72,7 +72,7 @@ :func:`list_dialects` function. The other optional *fmtparam* keyword arguments can be given to override individual formatting parameters in the current dialect. For full details about the dialect and formatting parameters, see - section :ref:`csv-fmt-params`, "Dialects and Formatting Parameters". + section :ref:`csv-fmt-params`. All data read are returned as strings. No automatic data type conversion is performed. @@ -99,7 +99,7 @@ :func:`list_dialects` function. The other optional *fmtparam* keyword arguments can be given to override individual formatting parameters in the current dialect. For full details about the dialect and formatting parameters, see - section :ref:`csv-fmt-params`, "Dialects and Formatting Parameters". To make it + section :ref:`csv-fmt-params`. To make it as easy as possible to interface with modules which implement the DB API, the value :const:`None` is written as the empty string. While this isn't a reversible transformation, it makes it easier to dump SQL NULL data values to @@ -113,8 +113,7 @@ dialect can be specified either by passing a sub-class of :class:`Dialect`, or by *fmtparam* keyword arguments, or both, with keyword arguments overriding parameters of the dialect. For full details about the dialect and formatting - parameters, see section :ref:`csv-fmt-params`, "Dialects and Formatting - Parameters". + parameters, see section :ref:`csv-fmt-params`. .. function:: unregister_dialect(name) Modified: doctools/trunk/Doc-3k/library/ctypes.rst ============================================================================== --- doctools/trunk/Doc-3k/library/ctypes.rst (original) +++ doctools/trunk/Doc-3k/library/ctypes.rst Thu Aug 2 16:49:09 2007 @@ -2359,6 +2359,6 @@ Arrays and pointers ^^^^^^^^^^^^^^^^^^^ -Not yet written - please see section :ref:`ctypes-pointers`, pointers and -section :ref:`ctypes-arrays`, arrays in the tutorial. +Not yet written - please see the sections :ref:`ctypes-pointers` and +section :ref:`ctypes-arrays` in the tutorial. Modified: doctools/trunk/Doc-3k/library/datetime.rst ============================================================================== --- doctools/trunk/Doc-3k/library/datetime.rst (original) +++ doctools/trunk/Doc-3k/library/datetime.rst Thu Aug 2 16:49:09 2007 @@ -491,7 +491,7 @@ Return a string representing the date, controlled by an explicit format string. Format codes referring to hours, minutes or seconds will see 0 values. See - section :ref:`strftime-behavior` -- :meth:`strftime` behavior. + section :ref:`strftime-behavior`. .. _datetime-datetime: @@ -931,7 +931,7 @@ .. method:: datetime.strftime(format) Return a string representing the date and time, controlled by an explicit format - string. See section :ref:`strftime-behavior` -- :meth:`strftime` behavior. + string. See section :ref:`strftime-behavior`. .. _datetime-time: @@ -1056,7 +1056,7 @@ .. method:: time.strftime(format) Return a string representing the time, controlled by an explicit format string. - See section :ref:`strftime-behavior` -- :meth:`strftime` behavior. + See section :ref:`strftime-behavior`. .. method:: time.utcoffset() Modified: doctools/trunk/Doc-3k/library/functions.rst ============================================================================== --- doctools/trunk/Doc-3k/library/functions.rst (original) +++ doctools/trunk/Doc-3k/library/functions.rst Thu Aug 2 16:49:09 2007 @@ -451,10 +451,9 @@ .. function:: file(filename[, mode[, bufsize]]) - Constructor function for the :class:`file` type, described further in section - :ref:`bltin-file-objects`, "File Objects (XXX reference: bltin-file- - objects.html)". The constructor's arguments are the same as those of the - :func:`open` built-in function described below. + Constructor function for the :class:`file` type, described further in section + :ref:`bltin-file-objects`. The constructor's arguments are the same as those + of the :func:`open` built-in function described below. When opening a file, it's preferable to use :func:`open` instead of invoking this constructor directly. :class:`file` is more suited to type testing (for @@ -743,11 +742,10 @@ .. function:: open(filename[, mode[, bufsize]]) - Open a file, returning an object of the :class:`file` type described in section - :ref:`bltin-file-objects`, "File Objects (XXX reference: bltin-file- - objects.html)". If the file cannot be opened, :exc:`IOError` is raised. When - opening a file, it's preferable to use :func:`open` instead of invoking the - :class:`file` constructor directly. + Open a file, returning an object of the :class:`file` type described in + section :ref:`bltin-file-objects`. If the file cannot be opened, + :exc:`IOError` is raised. When opening a file, it's preferable to use + :func:`open` instead of invoking the :class:`file` constructor directly. The first two arguments are the same as for ``stdio``'s :cfunc:`fopen`: *filename* is the file name to be opened, and *mode* is a string indicating how Modified: doctools/trunk/Doc-3k/library/intro.rst ============================================================================== --- doctools/trunk/Doc-3k/library/intro.rst (original) +++ doctools/trunk/Doc-3k/library/intro.rst Thu Aug 2 16:49:09 2007 @@ -44,9 +44,8 @@ function, module or term in the index (in the back). And finally, if you enjoy learning about random subjects, you choose a random page number (see module :mod:`random`) and read a section or two. Regardless of the order in which you -read the sections of this manual, it helps to start with chapter -:ref:`builtin`, "Built-in Types, Exceptions and Functions," as the remainder of -the manual assumes familiarity with this material. +read the sections of this manual, it helps to start with chapter :ref:`builtin`, +as the remainder of the manual assumes familiarity with this material. Let the show begin! Modified: doctools/trunk/Doc-3k/library/logging.rst ============================================================================== --- doctools/trunk/Doc-3k/library/logging.rst (original) +++ doctools/trunk/Doc-3k/library/logging.rst Thu Aug 2 16:49:09 2007 @@ -1483,8 +1483,8 @@ of the :class:`LogRecord` attributes - such as the default value mentioned above making use of the fact that the user's message and arguments are pre-formatted into a :class:`LogRecord`'s *message* attribute. This format string contains -standard python %-style mapping keys. See section :ref:`typesseq-strings`, -"String Formatting Operations," for more information on string formatting. +standard python %-style mapping keys. See section :ref:`typesseq-strings` +for more information on string formatting. Currently, the useful mapping keys in a :class:`LogRecord` are: Modified: doctools/trunk/Doc-3k/library/optparse.rst ============================================================================== --- doctools/trunk/Doc-3k/library/optparse.rst (original) +++ doctools/trunk/Doc-3k/library/optparse.rst Thu Aug 2 16:49:09 2007 @@ -309,7 +309,7 @@ Actions tell :mod:`optparse` what to do when it encounters an option on the command line. There is a fixed set of actions hard-coded into :mod:`optparse`; adding new actions is an advanced topic covered in section -:ref:`optparse-extending-optparse`, Extending :mod:`optparse`. Most actions tell +:ref:`optparse-extending-optparse`. Most actions tell :mod:`optparse` to store a value in some variable---for example, take a string from the command line and store it in an attribute of ``options``. @@ -369,8 +369,7 @@ default destination for ``"-f"`` is ``f``. :mod:`optparse` also includes built-in ``long`` and ``complex`` types. Adding -types is covered in section :ref:`optparse-extending-optparse`, Extending -:mod:`optparse`. +types is covered in section :ref:`optparse-extending-optparse`. .. _optparse-handling-boolean-options: @@ -415,7 +414,7 @@ call a specified function These are covered in section :ref:`optparse-reference-guide`, Reference Guide -and section :ref:`optparse-option-callbacks`, Option Callbacks. +and section :ref:`optparse-option-callbacks`. .. _optparse-default-values: @@ -704,8 +703,7 @@ ``conflict_handler`` (default: ``"error"``) Specifies what to do when options with conflicting option strings are added to - the parser; see section :ref:`optparse-conflicts-between-options`, Conflicts - between options. + the parser; see section :ref:`optparse-conflicts-between-options`. ``description`` (default: ``None``) A paragraph of text giving a brief overview of your program. :mod:`optparse` @@ -734,8 +732,7 @@ There are several ways to populate the parser with options. The preferred way is by using ``OptionParser.add_option()``, as shown in section -:ref:`optparse-tutorial`, the tutorial. :meth:`add_option` can be called in one -of two ways: +:ref:`optparse-tutorial`. :meth:`add_option` can be called in one of two ways: * pass it an Option instance (as returned by :func:`make_option`) @@ -986,7 +983,7 @@ func(option, opt_str, value, parser, *args, **kwargs) - See section :ref:`optparse-option-callbacks`, Option Callbacks for more detail. + See section :ref:`optparse-option-callbacks` for more detail. * :attr:`help` @@ -1083,9 +1080,9 @@ * ``callback`` - For options with action ``"callback"``, the callable to call when this option is - seen. See section :ref:`optparse-option-callbacks`, Option Callbacks for detail - on the arguments passed to ``callable``. + For options with action ``"callback"``, the callable to call when this option + is seen. See section :ref:`optparse-option-callbacks` for detail on the + arguments passed to ``callable``. * ``callback_args``, ``callback_kwargs`` @@ -1102,7 +1099,7 @@ * ``metavar`` (default: derived from option strings) Stand-in for the option argument(s) to use when printing help text. See section - :ref:`optparse-tutorial`, the tutorial for an example. + :ref:`optparse-tutorial` for an example. .. _optparse-standard-option-types: @@ -1112,7 +1109,7 @@ :mod:`optparse` has six built-in option types: ``string``, ``int``, ``long``, ``choice``, ``float`` and ``complex``. If you need to add new option types, see -section :ref:`optparse-extending-optparse`, Extending :mod:`optparse`. +section :ref:`optparse-extending-optparse`. Arguments to string options are not checked or converted in any way: the text on the command line is stored in the destination (or passed to the callback) as-is. Modified: doctools/trunk/Doc-3k/library/os.rst ============================================================================== --- doctools/trunk/Doc-3k/library/os.rst (original) +++ doctools/trunk/Doc-3k/library/os.rst Thu Aug 2 16:49:09 2007 @@ -122,8 +122,7 @@ getcwd() :noindex: - These functions are described in "Files and Directories" (section - :ref:`os-file-dir`). + These functions are described in :ref:`os-file-dir`. .. function:: ctermid() Modified: doctools/trunk/Doc-3k/library/pyexpat.rst ============================================================================== --- doctools/trunk/Doc-3k/library/pyexpat.rst (original) +++ doctools/trunk/Doc-3k/library/pyexpat.rst Thu Aug 2 16:49:09 2007 @@ -39,8 +39,7 @@ .. exception:: ExpatError The exception raised when Expat reports an error. See section - :ref:`expaterror-objects`, "ExpatError Exceptions," for more information on - interpreting Expat errors. + :ref:`expaterror-objects` for more information on interpreting Expat errors. .. exception:: error Modified: doctools/trunk/Doc-3k/library/shlex.rst ============================================================================== --- doctools/trunk/Doc-3k/library/shlex.rst (original) +++ doctools/trunk/Doc-3k/library/shlex.rst Thu Aug 2 16:49:09 2007 @@ -58,7 +58,7 @@ was introduced in Python 2.3, and defines the operational mode. When *posix* is not true (default), the :class:`shlex` instance will operate in compatibility mode. When operating in POSIX mode, :class:`shlex` will try to be as close as - possible to the POSIX shell parsing rules. See section :ref:`shlex-objects`. + possible to the POSIX shell parsing rules. .. seealso:: Modified: doctools/trunk/Doc-3k/library/socket.rst ============================================================================== --- doctools/trunk/Doc-3k/library/socket.rst (original) +++ doctools/trunk/Doc-3k/library/socket.rst Thu Aug 2 16:49:09 2007 @@ -571,13 +571,12 @@ .. index:: single: I/O control; buffering Return a :dfn:`file object` associated with the socket. (File objects are - described in :ref:`bltin-file-objects`, "File Objects.") The file object + described in :ref:`bltin-file-objects`.) The file object references a :cfunc:`dup`\ ped version of the socket file descriptor, so the file object and socket object may be closed or garbage-collected independently. The socket must be in blocking mode (it can not have a timeout). The optional *mode* and *bufsize* arguments are interpreted the same way as by the built-in - :func:`file` function; see "Built-in Functions" (section :ref:`built-in-funcs`) - for more information. + :func:`file` function; see :ref:`built-in-funcs` for more information. .. method:: socket.recv(bufsize[, flags]) Modified: doctools/trunk/Doc-3k/library/sqlite3.rst ============================================================================== --- doctools/trunk/Doc-3k/library/sqlite3.rst (original) +++ doctools/trunk/Doc-3k/library/sqlite3.rst Thu Aug 2 16:49:09 2007 @@ -227,8 +227,8 @@ .. attribute:: Connection.isolation_level Get or set the current isolation level. None for autocommit mode or one of - "DEFERRED", "IMMEDIATE" or "EXLUSIVE". See "Controlling Transactions", section - :ref:`sqlite3-controlling-transactions`, for a more detailed explanation. + "DEFERRED", "IMMEDIATE" or "EXLUSIVE". See section + :ref:`sqlite3-controlling-transactions` for a more detailed explanation. .. method:: Connection.cursor([cursorClass]) @@ -629,9 +629,8 @@ * Explicitly via the column name -Both ways are described in "Module Constants", section -:ref:`sqlite3-module-contents`, in the entries for the constants -:const:`PARSE_DECLTYPES` and :const:`PARSE_COLNAMES`. +Both ways are described in section :ref:`sqlite3-module-contents`, in the entries +for the constants :const:`PARSE_DECLTYPES` and :const:`PARSE_COLNAMES`. The following example illustrates both approaches. Modified: doctools/trunk/Doc-3k/library/stdtypes.rst ============================================================================== --- doctools/trunk/Doc-3k/library/stdtypes.rst (original) +++ doctools/trunk/Doc-3k/library/stdtypes.rst Thu Aug 2 16:49:09 2007 @@ -333,7 +333,7 @@ for well-defined conversions. (3) - See section :ref:`built-in-funcs`, "Built-in Functions," for a full description. + See :ref:`built-in-funcs` for a full description. (4) Complex floor division operator, modulo operator, and :func:`divmod`. @@ -1722,9 +1722,9 @@ File objects are implemented using C's ``stdio`` package and can be created with the built-in constructor :func:`file` described in section -:ref:`built-in-funcs`, "Built-in Functions." [#]_ File objects are also -returned by some other built-in functions and methods, such as :func:`os.popen` -and :func:`os.fdopen` and the :meth:`makefile` method of socket objects. +:ref:`built-in-funcs`. [#]_ File objects are also returned by some other +built-in functions and methods, such as :func:`os.popen` and :func:`os.fdopen` +and the :meth:`makefile` method of socket objects. When a file operation fails for an I/O-related reason, the exception :exc:`IOError` is raised. This includes situations where the operation is not @@ -2339,4 +2339,3 @@ might matter, for example, if you want to make an exact copy of a file while scanning its lines) to tell whether the last line of a file ended in a newline or not (yes this happens!). - Modified: doctools/trunk/Doc-3k/library/string.rst ============================================================================== --- doctools/trunk/Doc-3k/library/string.rst (original) +++ doctools/trunk/Doc-3k/library/string.rst Thu Aug 2 16:49:09 2007 @@ -245,10 +245,9 @@ --------------------------- The following list of functions are also defined as methods of string and -Unicode objects; see "String Methods" (section :ref:`string-methods`) for more -information on those. You should consider these functions as deprecated, -although they will not be removed until Python 3.0. The functions defined in -this module are: +Unicode objects; see section :ref:`string-methods` for more information on +those. You should consider these functions as deprecated, although they will +not be removed until Python 3.0. The functions defined in this module are: .. function:: atof(s) Modified: doctools/trunk/Doc-3k/library/sys.rst ============================================================================== --- doctools/trunk/Doc-3k/library/sys.rst (original) +++ doctools/trunk/Doc-3k/library/sys.rst Thu Aug 2 16:49:09 2007 @@ -331,7 +331,7 @@ Their intended use is to allow an interactive user to import a debugger module and engage in post-mortem debugging without having to re-execute the command that caused the error. (Typical use is ``import pdb; pdb.pm()`` to enter the - post-mortem debugger; see chapter :ref:`debugger`, "The Python Debugger," for + post-mortem debugger; see chapter :ref:`debugger` for more information.) The meaning of the variables is the same as that of the return values from @@ -490,9 +490,9 @@ single: trace function single: debugger - Set the system's trace function, which allows you to implement a Python source - code debugger in Python. See section :ref:`debugger-hooks`, "How It Works," in - the chapter on the Python debugger. The function is thread-specific; for a + Set the system's trace function, which allows you to implement a Python + source code debugger in Python. See section :ref:`debugger-hooks` in the + chapter on the Python debugger. The function is thread-specific; for a debugger to support multiple threads, it must be registered using :func:`settrace` for each thread being debugged. Modified: doctools/trunk/Doc-3k/library/tarfile.rst ============================================================================== --- doctools/trunk/Doc-3k/library/tarfile.rst (original) +++ doctools/trunk/Doc-3k/library/tarfile.rst Thu Aug 2 16:49:09 2007 @@ -37,7 +37,7 @@ Return a :class:`TarFile` object for the pathname *name*. For detailed information on :class:`TarFile` objects and the keyword arguments that are - allowed, see TarFile Objects (section :ref:`tarfile-objects`). + allowed, see :ref:`tarfile-objects`. *mode* has to be a string of the form ``'filemode[:compression]'``, it defaults to ``'r'``. Here is a full list of mode combinations: @@ -75,14 +75,14 @@ For special purposes, there is a second format for *mode*: ``'filemode|[compression]'``. :func:`open` will return a :class:`TarFile` - object that processes its data as a stream of blocks. No random seeking will be - done on the file. If given, *fileobj* may be any object that has a :meth:`read` - or :meth:`write` method (depending on the *mode*). *bufsize* specifies the - blocksize and defaults to ``20 * 512`` bytes. Use this variant in combination - with e.g. ``sys.stdin``, a socket file object or a tape device. However, such a - :class:`TarFile` object is limited in that it does not allow to be accessed - randomly, see "Examples" (section :ref:`tar-examples`). The currently possible - modes: + object that processes its data as a stream of blocks. No random seeking will + be done on the file. If given, *fileobj* may be any object that has a + :meth:`read` or :meth:`write` method (depending on the *mode*). *bufsize* + specifies the blocksize and defaults to ``20 * 512`` bytes. Use this variant + in combination with e.g. ``sys.stdin``, a socket file object or a tape + device. However, such a :class:`TarFile` object is limited in that it does + not allow to be accessed randomly, see :ref:`tar-examples`. The currently + possible modes: +-------------+--------------------------------------------+ | Mode | Action | @@ -112,8 +112,7 @@ .. class:: TarFile Class for reading and writing tar archives. Do not use this class directly, - better use :func:`open` instead. See "TarFile Objects" (section - :ref:`tarfile-objects`). + better use :func:`open` instead. See :ref:`tarfile-objects`. .. function:: is_tarfile(name) @@ -221,7 +220,7 @@ archive is a sequence of blocks. An archive member (a stored file) is made up of a header block followed by data blocks. It is possible to store a file in a tar archive several times. Each archive member is represented by a :class:`TarInfo` -object, see TarInfo Objects (section :ref:`tarinfo-objects`) for details. +object, see :ref:`tarinfo-objects` for details. .. class:: TarFile(name=None, mode='r', fileobj=None, format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False, ignore_zeros=False, encoding=None, errors=None, pax_headers=None, debug=0, errorlevel=0) Modified: doctools/trunk/Doc-3k/library/tkinter.rst ============================================================================== --- doctools/trunk/Doc-3k/library/tkinter.rst (original) +++ doctools/trunk/Doc-3k/library/tkinter.rst Thu Aug 2 16:49:09 2007 @@ -22,9 +22,8 @@ classes. In addition, the internal module :mod:`_tkinter` provides a threadsafe mechanism which allows Python and Tcl to interact. -Tk is not the only GUI for Python; see section :ref:`other-gui-packages`, "Other -User Interface Modules and Packages," for more information on other GUI toolkits -for Python. +Tk is not the only GUI for Python; see section :ref:`other-gui-packages` for +more information on other GUI toolkits for Python. .. % Other sections I have in mind are .. % Tkinter internals Modified: doctools/trunk/Doc-3k/library/urlparse.rst ============================================================================== --- doctools/trunk/Doc-3k/library/urlparse.rst (original) +++ doctools/trunk/Doc-3k/library/urlparse.rst Thu Aug 2 16:49:09 2007 @@ -90,8 +90,8 @@ | | | if present | | +------------------+-------+--------------------------+----------------------+ - See section :ref:`urlparse-result-object`, "Results of :func:`urlparse` and - :func:`urlsplit`," for more information on the result object. + See section :ref:`urlparse-result-object` for more information on the result + object. .. versionchanged:: 2.5 Added attributes to return value. @@ -141,8 +141,8 @@ | | | if present | | +------------------+-------+-------------------------+----------------------+ - See section :ref:`urlparse-result-object`, "Results of :func:`urlparse` and - :func:`urlsplit`," for more information on the result object. + See section :ref:`urlparse-result-object` for more information on the result + object. .. versionadded:: 2.2 Modified: doctools/trunk/Doc-3k/library/userdict.rst ============================================================================== --- doctools/trunk/Doc-3k/library/userdict.rst (original) +++ doctools/trunk/Doc-3k/library/userdict.rst Thu Aug 2 16:49:09 2007 @@ -177,8 +177,8 @@ hard to track down. In addition to supporting the methods and operations of string and Unicode -objects (see section :ref:`string-methods`, "String Methods"), -:class:`UserString` instances provide the following attribute: +objects (see section :ref:`string-methods`), :class:`UserString` instances +provide the following attribute: .. attribute:: MutableString.data Modified: doctools/trunk/Doc-3k/library/xml.dom.rst ============================================================================== --- doctools/trunk/Doc-3k/library/xml.dom.rst (original) +++ doctools/trunk/Doc-3k/library/xml.dom.rst Thu Aug 2 16:49:09 2007 @@ -65,8 +65,7 @@ and OMG IDL. The Python mapping defined here is based in large part on the IDL version of the specification, but strict compliance is not required (though implementations are free to support the strict mapping from IDL). See section -:ref:`dom-conformance`, "Conformance," for a detailed discussion of mapping -requirements. +:ref:`dom-conformance` for a detailed discussion of mapping requirements. .. seealso:: @@ -173,40 +172,40 @@ strings. It is fairly rare that you must do this, however, so this usage is not yet documented. -+--------------------------------+---------------------------------+---------------------------------+ -| Interface | Section | Purpose | -+================================+=================================+=================================+ -| :class:`DOMImplementation` | :ref:`dom-implementation- | Interface to the underlying | -| | objects` | implementation. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`Node` | :ref:`dom-node-objects` | Base interface for most objects | -| | | in a document. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`NodeList` | :ref:`dom-nodelist-objects` | Interface for a sequence of | -| | | nodes. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`DocumentType` | :ref:`dom-documenttype-objects` | Information about the | -| | | declarations needed to process | -| | | a document. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`Document` | :ref:`dom-document-objects` | Object which represents an | -| | | entire document. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`Element` | :ref:`dom-element-objects` | Element nodes in the document | -| | | hierarchy. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`Attr` | :ref:`dom-attr-objects` | Attribute value nodes on | -| | | element nodes. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`Comment` | :ref:`dom-comment-objects` | Representation of comments in | -| | | the source document. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`Text` | :ref:`dom-text-objects` | Nodes containing textual | -| | | content from the document. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`ProcessingInstruction` | :ref:`dom-pi-objects` | Processing instruction | -| | | representation. | -+--------------------------------+---------------------------------+---------------------------------+ ++--------------------------------+-----------------------------------+---------------------------------+ +| Interface | Section | Purpose | ++================================+===================================+=================================+ +| :class:`DOMImplementation` | :ref:`dom-implementation-objects` | Interface to the underlying | +| | | implementation. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`Node` | :ref:`dom-node-objects` | Base interface for most objects | +| | | in a document. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`NodeList` | :ref:`dom-nodelist-objects` | Interface for a sequence of | +| | | nodes. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`DocumentType` | :ref:`dom-documenttype-objects` | Information about the | +| | | declarations needed to process | +| | | a document. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`Document` | :ref:`dom-document-objects` | Object which represents an | +| | | entire document. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`Element` | :ref:`dom-element-objects` | Element nodes in the document | +| | | hierarchy. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`Attr` | :ref:`dom-attr-objects` | Attribute value nodes on | +| | | element nodes. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`Comment` | :ref:`dom-comment-objects` | Representation of comments in | +| | | the source document. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`Text` | :ref:`dom-text-objects` | Nodes containing textual | +| | | content from the document. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`ProcessingInstruction` | :ref:`dom-pi-objects` | Processing instruction | +| | | representation. | ++--------------------------------+-----------------------------------+---------------------------------+ An additional section describes the exceptions defined for working with the DOM in Python. Modified: doctools/trunk/Doc-3k/library/xml.sax.reader.rst ============================================================================== --- doctools/trunk/Doc-3k/library/xml.sax.reader.rst (original) +++ doctools/trunk/Doc-3k/library/xml.sax.reader.rst Thu Aug 2 16:49:09 2007 @@ -70,24 +70,23 @@ .. class:: AttributesImpl(attrs) - This is an implementation of the :class:`Attributes` interface (XXX reference: - attributes-objects.html) (see section :ref:`attributes-objects`). This is a - dictionary-like object which represents the element attributes in a - :meth:`startElement` call. In addition to the most useful dictionary operations, - it supports a number of other methods as described by the interface. Objects of - this class should be instantiated by readers; *attrs* must be a dictionary-like - object containing a mapping from attribute names to attribute values. + This is an implementation of the :class:`Attributes` interface (see section + :ref:`attributes-objects`). This is a dictionary-like object which + represents the element attributes in a :meth:`startElement` call. In addition + to the most useful dictionary operations, it supports a number of other + methods as described by the interface. Objects of this class should be + instantiated by readers; *attrs* must be a dictionary-like object containing + a mapping from attribute names to attribute values. .. class:: AttributesNSImpl(attrs, qnames) Namespace-aware variant of :class:`AttributesImpl`, which will be passed to :meth:`startElementNS`. It is derived from :class:`AttributesImpl`, but - understands attribute names as two-tuples of *namespaceURI* and *localname*. In - addition, it provides a number of methods expecting qualified names as they - appear in the original document. This class implements the - :class:`AttributesNS` interface (XXX reference: attributes-ns-objects.html) (see - section :ref:`attributes-ns-objects`). + understands attribute names as two-tuples of *namespaceURI* and + *localname*. In addition, it provides a number of methods expecting qualified + names as they appear in the original document. This class implements the + :class:`AttributesNS` interface (see section :ref:`attributes-ns-objects`). .. _xmlreader-objects: @@ -359,9 +358,9 @@ The :class:`AttributesNS` Interface ----------------------------------- -This interface is a subtype of the :class:`Attributes` interface (XXX reference: -attributes-objects.html) (see section :ref:`attributes-objects`). All methods -supported by that interface are also available on :class:`AttributesNS` objects. +This interface is a subtype of the :class:`Attributes` interface (see section +:ref:`attributes-objects`). All methods supported by that interface are also +available on :class:`AttributesNS` objects. The following methods are also available: Modified: doctools/trunk/Doc-3k/library/zipfile.rst ============================================================================== --- doctools/trunk/Doc-3k/library/zipfile.rst (original) +++ doctools/trunk/Doc-3k/library/zipfile.rst Thu Aug 2 16:49:09 2007 @@ -40,8 +40,8 @@ .. class:: ZipFile - The class for reading and writing ZIP files. See "ZipFile Objects" (section - :ref:`zipfile-objects`) for constructor details. + The class for reading and writing ZIP files. See section + :ref:`zipfile-objects` for constructor details. .. class:: PyZipFile @@ -51,14 +51,14 @@ .. class:: ZipInfo([filename[, date_time]]) - Class used to represent information about a member of an archive. Instances of - this class are returned by the :meth:`getinfo` and :meth:`infolist` methods of - :class:`ZipFile` objects. Most users of the :mod:`zipfile` module will not need - to create these, but only use those created by this module. *filename* should be - the full name of the archive member, and *date_time* should be a tuple - containing six fields which describe the time of the last modification to the - file; the fields are described in section :ref:`zipinfo-objects`, "ZipInfo - Objects." + Class used to represent information about a member of an archive. Instances + of this class are returned by the :meth:`getinfo` and :meth:`infolist` + methods of :class:`ZipFile` objects. Most users of the :mod:`zipfile` module + will not need to create these, but only use those created by this + module. *filename* should be the full name of the archive member, and + *date_time* should be a tuple containing six fields which describe the time + of the last modification to the file; the fields are described in section + :ref:`zipinfo-objects`. .. function:: is_zipfile(filename) Modified: doctools/trunk/Doc-3k/library/zipimport.rst ============================================================================== --- doctools/trunk/Doc-3k/library/zipimport.rst (original) +++ doctools/trunk/Doc-3k/library/zipimport.rst Thu Aug 2 16:49:09 2007 @@ -40,8 +40,8 @@ .. class:: zipimporter - The class for importing ZIP files. See "zipimporter Objects" (section - :ref:`zipimporter-objects`) for constructor details. + The class for importing ZIP files. See section :ref:`zipimporter-objects` + for constructor details. .. seealso:: Modified: doctools/trunk/Doc-3k/maclib/using.rst ============================================================================== --- doctools/trunk/Doc-3k/maclib/using.rst (original) +++ doctools/trunk/Doc-3k/maclib/using.rst Thu Aug 2 16:49:09 2007 @@ -108,7 +108,7 @@ /.MacOSX/environment.plist`. See Apple's Technical Document QA1067 for details. For more information on installation Python packages in MacPython, see section -:ref:`mac-package-manager`, "Installing Additional Python Packages." +:ref:`mac-package-manager`. .. _ide: Modified: doctools/trunk/Doc-3k/reference/datamodel.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/datamodel.rst (original) +++ doctools/trunk/Doc-3k/reference/datamodel.rst Thu Aug 2 16:49:09 2007 @@ -441,7 +441,7 @@ the same dictionary entry. Dictionaries are mutable; they can be created by the ``{...}`` notation (see - section :ref:`dict`, "Dictionary Displays"). + section :ref:`dict`). .. index:: module: dbm @@ -461,7 +461,7 @@ pair: function; argument These are the types to which the function call operation (see section - :ref:`calls`, "Calls") can be applied: + :ref:`calls`) can be applied: User-defined functions .. index:: @@ -469,9 +469,9 @@ object: function object: user-defined function - A user-defined function object is created by a function definition (see section - :ref:`function`, "Function definitions"). It should be called with an argument - list containing the same number of items as the function's formal parameter + A user-defined function object is created by a function definition (see + section :ref:`function`). It should be called with an argument list + containing the same number of items as the function's formal parameter list. Special attributes: @@ -652,7 +652,7 @@ single: generator; iterator A function or method which uses the :keyword:`yield` statement (see section - :ref:`yield`, "The :keyword:`yield` statement") is called a :dfn:`generator + :ref:`yield`) is called a :dfn:`generator function`. Such a function, when called, always returns an iterator object which can be used to execute the body of the function: calling the iterator's :meth:`__next__` method will cause the function to execute until it provides a @@ -720,7 +720,7 @@ object: module Modules are imported by the :keyword:`import` statement (see section - :ref:`import`, "The :keyword:`import` statement"). A module object has a + :ref:`import`). A module object has a namespace implemented by a dictionary object (this is the dictionary referenced by the __globals__ attribute of functions defined in the module). Attribute references are translated to lookups in this dictionary, e.g., ``m.x`` is @@ -753,8 +753,8 @@ of the shared library file. Classes - Class objects are created by class definitions (see section :ref:`class`, "Class - definitions"). A class has a namespace implemented by a dictionary object. Class + Class objects are created by class definitions (see section :ref:`class`). + A class has a namespace implemented by a dictionary object. Class attribute references are translated to lookups in this dictionary, e.g., ``C.x`` is translated to ``C.__dict__["x"]``. When the attribute name is not found there, the attribute search continues in the base classes. The search is depth- @@ -841,8 +841,7 @@ object: mapping Class instances can pretend to be numbers, sequences, or mappings if they have - methods with certain special names. See section :ref:`specialnames`, "Special - method names." + methods with certain special names. See section :ref:`specialnames`. .. index:: single: __dict__ (instance attribute) @@ -1008,7 +1007,7 @@ unwinds the execution stack, at each unwound level a traceback object is inserted in front of the current traceback. When an exception handler is entered, the stack trace is made available to the program. (See section - :ref:`try`, "The ``try`` statement.") It is accessible as the third item of the + :ref:`try`.) It is accessible as the third item of the tuple returned by ``sys.exc_info()``. When the program contains no suitable handler, the stack trace is written (nicely formatted) to the standard error stream; if the interpreter is interactive, it is also made available to the user Modified: doctools/trunk/Doc-3k/reference/expressions.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/expressions.rst (original) +++ doctools/trunk/Doc-3k/reference/expressions.rst Thu Aug 2 16:49:09 2007 @@ -1199,7 +1199,7 @@ the same box have the same precedence. Unless the syntax is explicitly given, operators are binary. Operators in the same box group left to right (except for comparisons, including tests, which all have the same precedence and chain from -left to right --- see section :ref:`comparisons` -- and exponentiation, which +left to right --- see section :ref:`comparisons` --- and exponentiation, which groups from right to left). +----------------------------------------------+-------------------------------------+ Modified: doctools/trunk/Doc-3k/reference/lexical_analysis.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/lexical_analysis.rst (original) +++ doctools/trunk/Doc-3k/reference/lexical_analysis.rst Thu Aug 2 16:49:09 2007 @@ -385,8 +385,7 @@ Not imported by ``from module import *``. The special identifier ``_`` is used in the interactive interpreter to store the result of the last evaluation; it is stored in the :mod:`__builtin__` module. When not in interactive mode, ``_`` - has no special meaning and is not defined. See section :ref:`import`, "The - :keyword:`import` statement." + has no special meaning and is not defined. See section :ref:`import`. .. note:: @@ -399,13 +398,13 @@ implementation (including the standard library); applications should not expect to define additional names using this convention. The set of names of this class defined by Python may be extended in future versions. See section - :ref:`specialnames`, "Special method names." + :ref:`specialnames`. ``__*`` Class-private names. Names in this category, when used within the context of a class definition, are re-written to use a mangled form to help avoid name clashes between "private" attributes of base and derived classes. See section - :ref:`atom-identifiers`, "Identifiers (Names)." + :ref:`atom-identifiers`. .. _literals: Modified: doctools/trunk/Doc-3k/tutorial/errors.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/errors.rst (original) +++ doctools/trunk/Doc-3k/tutorial/errors.rst Thu Aug 2 16:49:09 2007 @@ -323,7 +323,7 @@ Many standard modules define their own exceptions to report errors that may occur in functions they define. More information on classes is presented in -chapter :ref:`tut-classes`, "Classes." +chapter :ref:`tut-classes`. .. _tut-cleanup: Modified: doctools/trunk/Doc-3k/tutorial/modules.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/modules.rst (original) +++ doctools/trunk/Doc-3k/tutorial/modules.rst Thu Aug 2 16:49:09 2007 @@ -152,16 +152,15 @@ found there, the search continues in an installation-dependent default path; on Unix, this is usually :file:`.:/usr/local/lib/python`. -Actually, modules are searched in the list of directories given by the variable -``sys.path`` which is initialized from the directory containing the input -script (or the current directory), :envvar:`PYTHONPATH` and the installation- -dependent default. This allows Python programs that know what they're doing to -modify or replace the module search path. Note that because the directory -containing the script being run is on the search path, it is important that the -script not have the same name as a standard module, or Python will attempt to -load the script as a module when that module is imported. This will generally be -an error. See section :ref:`tut-standardmodules`, "Standard Modules," for more -information. +Actually, modules are searched in the list of directories given by the variable +``sys.path`` which is initialized from the directory containing the input script +(or the current directory), :envvar:`PYTHONPATH` and the installation- dependent +default. This allows Python programs that know what they're doing to modify or +replace the module search path. Note that because the directory containing the +script being run is on the search path, it is important that the script not have +the same name as a standard module, or Python will attempt to load the script as +a module when that module is imported. This will generally be an error. See +section :ref:`tut-standardmodules` for more information. "Compiled" Python files From python-checkins at python.org Thu Aug 2 17:44:46 2007 From: python-checkins at python.org (georg.brandl) Date: Thu, 2 Aug 2007 17:44:46 +0200 (CEST) Subject: [Python-checkins] r56670 - in doctools/trunk: Doc-26/TODO Doc-26/c-api/concrete.rst Doc-26/c-api/intro.rst Doc-26/conf.py Doc-26/distutils/apiref.rst Doc-26/distutils/introduction.rst Doc-26/distutils/setupscript.rst Doc-26/distutils/sourcedist.rst Doc-26/distutils/sysconfig.rst Doc-26/extending/extending.rst Doc-26/extending/index.rst Doc-26/library/asttable.rst Doc-26/library/compiler.rst Doc-26/library/contextlib.rst Doc-26/library/cookielib.rst Doc-26/library/idle.rst Doc-26/library/index.rst Doc-26/library/intro.rst Doc-26/library/othergui.rst Doc-26/library/scrolledtext.rst Doc-26/library/sqlite3.rst Doc-26/library/stdtypes.rst Doc-26/library/strings.rst Doc-26/library/tarfile.rst Doc-26/library/tix.rst Doc-26/library/tk.rst Doc-26/library/tkinter.rst Doc-26/library/xml.dom.minidom.rst Doc-26/reference/compound_stmts.rst Doc-26/reference/datamodel.rst Doc-26/reference/simple_stmts.rst Doc-3k/TODO Doc-3k/c-api/concrete.rst Doc-3k/c-api/intro.rst Doc-3k/conf.py Doc-3k/distutils/apiref.rst Doc-3k/distutils/introduction.rst Doc-3k/distutils/setupscript.rst Doc-3k/distutils/sourcedist.rst Doc-3k/distutils/sysconfig.rst Doc-3k/extending/extending.rst Doc-3k/extending/index.rst Doc-3k/library/asttable.rst Doc-3k/library/contextlib.rst Doc-3k/library/cookielib.rst Doc-3k/library/idle.rst Doc-3k/library/index.rst Doc-3k/library/intro.rst Doc-3k/library/othergui.rst Doc-3k/library/scrolledtext.rst Doc-3k/library/sqlite3.rst Doc-3k/library/stdtypes.rst Doc-3k/library/strings.rst Doc-3k/library/tarfile.rst Doc-3k/library/tix.rst Doc-3k/library/tk.rst Doc-3k/library/tkinter.rst Doc-3k/library/xml.dom.minidom.rst Doc-3k/reference/compound_stmts.rst Doc-3k/reference/datamodel.rst Doc-3k/reference/simple_stmts.rst Message-ID: <20070802154446.3F7D91E4011@bag.python.org> Author: georg.brandl Date: Thu Aug 2 17:44:40 2007 New Revision: 56670 Added: doctools/trunk/Doc-26/library/idle.rst doctools/trunk/Doc-26/library/othergui.rst doctools/trunk/Doc-26/library/scrolledtext.rst doctools/trunk/Doc-26/library/tix.rst doctools/trunk/Doc-26/library/tk.rst doctools/trunk/Doc-3k/library/idle.rst doctools/trunk/Doc-3k/library/othergui.rst doctools/trunk/Doc-3k/library/scrolledtext.rst doctools/trunk/Doc-3k/library/tix.rst doctools/trunk/Doc-3k/library/tk.rst Removed: doctools/trunk/Doc-26/distutils/sysconfig.rst doctools/trunk/Doc-26/library/asttable.rst doctools/trunk/Doc-3k/distutils/sysconfig.rst doctools/trunk/Doc-3k/library/asttable.rst Modified: doctools/trunk/Doc-26/TODO doctools/trunk/Doc-26/c-api/concrete.rst doctools/trunk/Doc-26/c-api/intro.rst doctools/trunk/Doc-26/conf.py doctools/trunk/Doc-26/distutils/apiref.rst doctools/trunk/Doc-26/distutils/introduction.rst doctools/trunk/Doc-26/distutils/setupscript.rst doctools/trunk/Doc-26/distutils/sourcedist.rst doctools/trunk/Doc-26/extending/extending.rst doctools/trunk/Doc-26/extending/index.rst doctools/trunk/Doc-26/library/compiler.rst doctools/trunk/Doc-26/library/contextlib.rst doctools/trunk/Doc-26/library/cookielib.rst doctools/trunk/Doc-26/library/index.rst doctools/trunk/Doc-26/library/intro.rst doctools/trunk/Doc-26/library/sqlite3.rst doctools/trunk/Doc-26/library/stdtypes.rst doctools/trunk/Doc-26/library/strings.rst doctools/trunk/Doc-26/library/tarfile.rst doctools/trunk/Doc-26/library/tkinter.rst doctools/trunk/Doc-26/library/xml.dom.minidom.rst doctools/trunk/Doc-26/reference/compound_stmts.rst doctools/trunk/Doc-26/reference/datamodel.rst doctools/trunk/Doc-26/reference/simple_stmts.rst doctools/trunk/Doc-3k/TODO doctools/trunk/Doc-3k/c-api/concrete.rst doctools/trunk/Doc-3k/c-api/intro.rst doctools/trunk/Doc-3k/conf.py doctools/trunk/Doc-3k/distutils/apiref.rst doctools/trunk/Doc-3k/distutils/introduction.rst doctools/trunk/Doc-3k/distutils/setupscript.rst doctools/trunk/Doc-3k/distutils/sourcedist.rst doctools/trunk/Doc-3k/extending/extending.rst doctools/trunk/Doc-3k/extending/index.rst doctools/trunk/Doc-3k/library/contextlib.rst doctools/trunk/Doc-3k/library/cookielib.rst doctools/trunk/Doc-3k/library/index.rst doctools/trunk/Doc-3k/library/intro.rst doctools/trunk/Doc-3k/library/sqlite3.rst doctools/trunk/Doc-3k/library/stdtypes.rst doctools/trunk/Doc-3k/library/strings.rst doctools/trunk/Doc-3k/library/tarfile.rst doctools/trunk/Doc-3k/library/tkinter.rst doctools/trunk/Doc-3k/library/xml.dom.minidom.rst doctools/trunk/Doc-3k/reference/compound_stmts.rst doctools/trunk/Doc-3k/reference/datamodel.rst doctools/trunk/Doc-3k/reference/simple_stmts.rst Log: Vanquish all remaining build warnings. Modified: doctools/trunk/Doc-26/TODO ============================================================================== --- doctools/trunk/Doc-26/TODO (original) +++ doctools/trunk/Doc-26/TODO Thu Aug 2 17:44:40 2007 @@ -2,7 +2,6 @@ ====================== * fix all references and links marked with `XXX` -* fix all duplicate labels and undefined label references * split very large files and add toctrees * integrate standalone HOWTOs * find out which files get "comments disabled" metadata Modified: doctools/trunk/Doc-26/c-api/concrete.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/concrete.rst (original) +++ doctools/trunk/Doc-26/c-api/concrete.rst Thu Aug 2 17:44:40 2007 @@ -2934,7 +2934,7 @@ .. versionadded:: 2.3 -.. _weakref-objects: +.. _weakrefobjects: Weak Reference Objects ---------------------- @@ -3168,7 +3168,7 @@ *NULL*. -.. _datetime-objects: +.. _datetimeobjects: DateTime Objects ---------------- Modified: doctools/trunk/Doc-26/c-api/intro.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/intro.rst (original) +++ doctools/trunk/Doc-26/c-api/intro.rst Thu Aug 2 17:44:40 2007 @@ -1,7 +1,7 @@ .. highlightlang:: c -.. _intro: +.. _api-intro: ************ Introduction @@ -30,7 +30,7 @@ application. -.. _includes: +.. _api-includes: Include Files ============= @@ -80,7 +80,7 @@ is no need to do anything special to use the API from C++. -.. _objects: +.. _api-objects: Objects, Types and Reference Counts =================================== @@ -107,7 +107,7 @@ pointed to by *a* is a Python list. -.. _refcounts: +.. _api-refcounts: Reference Counts ---------------- @@ -170,7 +170,7 @@ they are done with the result; this soon becomes second nature. -.. _refcountdetails: +.. _api-refcountdetails: Reference Count Details ^^^^^^^^^^^^^^^^^^^^^^^ @@ -335,7 +335,7 @@ .. index:: single: sum_sequence() -.. _types: +.. _api-types: Types ----- @@ -349,7 +349,7 @@ use them. -.. _exceptions: +.. _api-exceptions: Exceptions ========== @@ -501,7 +501,7 @@ the final call made is successful. -.. _embedding: +.. _api-embedding: Embedding Python ================ @@ -525,8 +525,6 @@ :mod:`__builtin__`, :mod:`__main__`, :mod:`sys`, and :mod:`exceptions`. It also initializes the module search path (``sys.path``). -.. % - .. index:: single: PySys_SetArgv() :cfunc:`Py_Initialize` does not set the "script argument list" (``sys.argv``). @@ -579,7 +577,7 @@ allocated by extension modules currently cannot be released. -.. _debugging: +.. _api-debugging: Debugging Builds ================ Modified: doctools/trunk/Doc-26/conf.py ============================================================================== --- doctools/trunk/Doc-26/conf.py (original) +++ doctools/trunk/Doc-26/conf.py Thu Aug 2 17:44:40 2007 @@ -33,6 +33,7 @@ 'whatsnew/2.5.rst', 'maclib/scrap.rst', 'library/xmllib.rst', + 'library/xml.etree.rst', ] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, Modified: doctools/trunk/Doc-26/distutils/apiref.rst ============================================================================== --- doctools/trunk/Doc-26/distutils/apiref.rst (original) +++ doctools/trunk/Doc-26/distutils/apiref.rst Thu Aug 2 17:44:40 2007 @@ -1415,7 +1415,118 @@ Also provides :func:`find_executable` to search the path for a given executable name. -XXX: input{sysconfig} :XXX + +:mod:`distutils.sysconfig` --- System configuration information +=============================================================== + +.. module:: distutils.sysconfig + :synopsis: Low-level access to configuration information of the Python interpreter. +.. moduleauthor:: Fred L. Drake, Jr. +.. moduleauthor:: Greg Ward +.. sectionauthor:: Fred L. Drake, Jr. + + +The :mod:`distutils.sysconfig` module provides access to Python's low-level +configuration information. The specific configuration variables available +depend heavily on the platform and configuration. The specific variables depend +on the build process for the specific version of Python being run; the variables +are those found in the :file:`Makefile` and configuration header that are +installed with Python on Unix systems. The configuration header is called +:file:`pyconfig.h` for Python versions starting with 2.2, and :file:`config.h` +for earlier versions of Python. + +Some additional functions are provided which perform some useful manipulations +for other parts of the :mod:`distutils` package. + + +.. data:: PREFIX + + The result of ``os.path.normpath(sys.prefix)``. + + +.. data:: EXEC_PREFIX + + The result of ``os.path.normpath(sys.exec_prefix)``. + + +.. function:: get_config_var(name) + + Return the value of a single variable. This is equivalent to + ``get_config_vars().get(name)``. + + +.. function:: get_config_vars(...) + + Return a set of variable definitions. If there are no arguments, this returns a + dictionary mapping names of configuration variables to values. If arguments are + provided, they should be strings, and the return value will be a sequence giving + the associated values. If a given name does not have a corresponding value, + ``None`` will be included for that variable. + + +.. function:: get_config_h_filename() + + Return the full path name of the configuration header. For Unix, this will be + the header generated by the :program:`configure` script; for other platforms the + header will have been supplied directly by the Python source distribution. The + file is a platform-specific text file. + + +.. function:: get_makefile_filename() + + Return the full path name of the :file:`Makefile` used to build Python. For + Unix, this will be a file generated by the :program:`configure` script; the + meaning for other platforms will vary. The file is a platform-specific text + file, if it exists. This function is only useful on POSIX platforms. + + +.. function:: get_python_inc([plat_specific[, prefix]]) + + Return the directory for either the general or platform-dependent C include + files. If *plat_specific* is true, the platform-dependent include directory is + returned; if false or omitted, the platform-independent directory is returned. + If *prefix* is given, it is used as either the prefix instead of + :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if + *plat_specific* is true. + + +.. function:: get_python_lib([plat_specific[, standard_lib[, prefix]]]) + + Return the directory for either the general or platform-dependent library + installation. If *plat_specific* is true, the platform-dependent include + directory is returned; if false or omitted, the platform-independent directory + is returned. If *prefix* is given, it is used as either the prefix instead of + :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if + *plat_specific* is true. If *standard_lib* is true, the directory for the + standard library is returned rather than the directory for the installation of + third-party extensions. + +The following function is only intended for use within the :mod:`distutils` +package. + + +.. function:: customize_compiler(compiler) + + Do any platform-specific customization of a + :class:`distutils.ccompiler.CCompiler` instance. + + This function is only needed on Unix at this time, but should be called + consistently to support forward-compatibility. It inserts the information that + varies across Unix flavors and is stored in Python's :file:`Makefile`. This + information includes the selected compiler, compiler and linker options, and the + extension used by the linker for shared objects. + +This function is even more special-purpose, and should only be used from +Python's own build procedures. + + +.. function:: set_python_build() + + Inform the :mod:`distutils.sysconfig` module that it is being used as part of + the build process for Python. This changes a lot of relative locations for + files, allowing them to be located in the build area rather than in an installed + Python. + :mod:`distutils.text_file` --- The TextFile class ================================================= @@ -1870,20 +1981,3 @@ *sub_commands* is usually defined at the \*end\* of a class, because predicates can be unbound methods, so they must already have been defined. The canonical example is the :command:`install` command. - -.. % -.. % The ugly "%begin{latexonly}" pseudo-environments are really just to -.. % keep LaTeX2HTML quiet during the \renewcommand{} macros; they're -.. % not really valuable. -.. % -.. % begin{latexonly} -.. % end{latexonly} - -XXX: input{moddist.ind} :XXX -.. % Module Index -.. % begin{latexonly} -.. % end{latexonly} - -XXX: input{dist.ind} :XXX -.. % Index - Modified: doctools/trunk/Doc-26/distutils/introduction.rst ============================================================================== --- doctools/trunk/Doc-26/distutils/introduction.rst (original) +++ doctools/trunk/Doc-26/distutils/introduction.rst Thu Aug 2 17:44:40 2007 @@ -1,4 +1,4 @@ -.. _intro: +.. _distutils-intro: **************************** An Introduction to Distutils @@ -10,7 +10,7 @@ Python Modules (XXX reference: ../inst/inst.html) manual. -.. _concepts: +.. _distutils-concepts: Concepts & Terminology ====================== @@ -41,7 +41,7 @@ code. -.. _simple-example: +.. _distutils-simple-example: A Simple Example ================ Modified: doctools/trunk/Doc-26/distutils/setupscript.rst ============================================================================== --- doctools/trunk/Doc-26/distutils/setupscript.rst (original) +++ doctools/trunk/Doc-26/distutils/setupscript.rst Thu Aug 2 17:44:40 2007 @@ -8,7 +8,7 @@ installing modules using the Distutils. The main purpose of the setup script is to describe your module distribution to the Distutils, so that the various commands that operate on your modules do the right thing. As we saw in section -:ref:`simple-example` above, the setup script consists mainly of a call to +:ref:`distutils-simple-example` above, the setup script consists mainly of a call to :func:`setup`, and most information supplied to the Distutils by the module developer is supplied as keyword arguments to :func:`setup`. @@ -33,7 +33,7 @@ ) There are only two differences between this and the trivial one-file -distribution presented in section :ref:`simple-example`: more metadata, and the +distribution presented in section :ref:`distutils-simple-example`: more metadata, and the specification of pure Python modules by package, rather than by module. This is important since the Distutils consist of a couple of dozen modules split into (so far) two packages; an explicit list of every module would be tedious to @@ -114,7 +114,7 @@ For a small module distribution, you might prefer to list all modules rather than listing packages---especially the case of a single module that goes in the "root package" (i.e., no package at all). This simplest case was shown in -section :ref:`simple-example`; here is a slightly more involved example:: +section :ref:`distutils-simple-example`; here is a slightly more involved example:: py_modules = ['mod1', 'pkg.mod2'] Modified: doctools/trunk/Doc-26/distutils/sourcedist.rst ============================================================================== --- doctools/trunk/Doc-26/distutils/sourcedist.rst (original) +++ doctools/trunk/Doc-26/distutils/sourcedist.rst Thu Aug 2 17:44:40 2007 @@ -4,7 +4,7 @@ Creating a Source Distribution ****************************** -As shown in section :ref:`simple-example`, you use the :command:`sdist` command +As shown in section :ref:`distutils-simple-example`, you use the :command:`sdist` command to create a source distribution. In the simplest case, :: python setup.py sdist Deleted: /doctools/trunk/Doc-26/distutils/sysconfig.rst ============================================================================== --- /doctools/trunk/Doc-26/distutils/sysconfig.rst Thu Aug 2 17:44:40 2007 +++ (empty file) @@ -1,112 +0,0 @@ - -:mod:`distutils.sysconfig` --- System configuration information -=============================================================== - -.. module:: distutils.sysconfig - :synopsis: Low-level access to configuration information of the Python interpreter. -.. moduleauthor:: Fred L. Drake, Jr. -.. moduleauthor:: Greg Ward -.. sectionauthor:: Fred L. Drake, Jr. - - -The :mod:`distutils.sysconfig` module provides access to Python's low-level -configuration information. The specific configuration variables available -depend heavily on the platform and configuration. The specific variables depend -on the build process for the specific version of Python being run; the variables -are those found in the :file:`Makefile` and configuration header that are -installed with Python on Unix systems. The configuration header is called -:file:`pyconfig.h` for Python versions starting with 2.2, and :file:`config.h` -for earlier versions of Python. - -Some additional functions are provided which perform some useful manipulations -for other parts of the :mod:`distutils` package. - - -.. data:: PREFIX - - The result of ``os.path.normpath(sys.prefix)``. - - -.. data:: EXEC_PREFIX - - The result of ``os.path.normpath(sys.exec_prefix)``. - - -.. function:: get_config_var(name) - - Return the value of a single variable. This is equivalent to - ``get_config_vars().get(name)``. - - -.. function:: get_config_vars(...) - - Return a set of variable definitions. If there are no arguments, this returns a - dictionary mapping names of configuration variables to values. If arguments are - provided, they should be strings, and the return value will be a sequence giving - the associated values. If a given name does not have a corresponding value, - ``None`` will be included for that variable. - - -.. function:: get_config_h_filename() - - Return the full path name of the configuration header. For Unix, this will be - the header generated by the :program:`configure` script; for other platforms the - header will have been supplied directly by the Python source distribution. The - file is a platform-specific text file. - - -.. function:: get_makefile_filename() - - Return the full path name of the :file:`Makefile` used to build Python. For - Unix, this will be a file generated by the :program:`configure` script; the - meaning for other platforms will vary. The file is a platform-specific text - file, if it exists. This function is only useful on POSIX platforms. - - -.. function:: get_python_inc([plat_specific[, prefix]]) - - Return the directory for either the general or platform-dependent C include - files. If *plat_specific* is true, the platform-dependent include directory is - returned; if false or omitted, the platform-independent directory is returned. - If *prefix* is given, it is used as either the prefix instead of - :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if - *plat_specific* is true. - - -.. function:: get_python_lib([plat_specific[, standard_lib[, prefix]]]) - - Return the directory for either the general or platform-dependent library - installation. If *plat_specific* is true, the platform-dependent include - directory is returned; if false or omitted, the platform-independent directory - is returned. If *prefix* is given, it is used as either the prefix instead of - :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if - *plat_specific* is true. If *standard_lib* is true, the directory for the - standard library is returned rather than the directory for the installation of - third-party extensions. - -The following function is only intended for use within the :mod:`distutils` -package. - - -.. function:: customize_compiler(compiler) - - Do any platform-specific customization of a - :class:`distutils.ccompiler.CCompiler` instance. - - This function is only needed on Unix at this time, but should be called - consistently to support forward-compatibility. It inserts the information that - varies across Unix flavors and is stored in Python's :file:`Makefile`. This - information includes the selected compiler, compiler and linker options, and the - extension used by the linker for shared objects. - -This function is even more special-purpose, and should only be used from -Python's own build procedures. - - -.. function:: set_python_build() - - Inform the :mod:`distutils.sysconfig` module that it is being used as part of - the build process for Python. This changes a lot of relative locations for - files, allowing them to be located in the build area rather than in an installed - Python. - Modified: doctools/trunk/Doc-26/extending/extending.rst ============================================================================== --- doctools/trunk/Doc-26/extending/extending.rst (original) +++ doctools/trunk/Doc-26/extending/extending.rst Thu Aug 2 17:44:40 2007 @@ -1,7 +1,7 @@ .. highlightlang:: c -.. _intro: +.. _extending-intro: ****************************** Extending Python with C or C++ @@ -21,7 +21,7 @@ your system setup; details are given in later chapters. -.. _simpleexample: +.. _extending-simpleexample: A Simple Example ================ @@ -103,7 +103,7 @@ return *NULL* immediately (as we saw in the example). -.. _errors: +.. _extending-errors: Intermezzo: Errors and Exceptions ================================= @@ -1109,8 +1109,8 @@ this macro before accessing the C API. The exporting module is a modification of the :mod:`spam` module from section -:ref:`simpleexample`. The function :func:`spam.system` does not call the C -library function :cfunc:`system` directly, but a function +:ref:`extending-simpleexample`. The function :func:`spam.system` does not call +the C library function :cfunc:`system` directly, but a function :cfunc:`PySpam_System`, which would of course do something more complicated in reality (such as adding "spam" to every command). This function :cfunc:`PySpam_System` is also exported to other extension modules. Modified: doctools/trunk/Doc-26/extending/index.rst ============================================================================== --- doctools/trunk/Doc-26/extending/index.rst (original) +++ doctools/trunk/Doc-26/extending/index.rst Thu Aug 2 17:44:40 2007 @@ -17,7 +17,7 @@ This document assumes basic knowledge about Python. For an informal introduction to the language, see :ref:`tutorial-index`. :ref:`reference-index` -gives a more formal definition of the language. :ref:`modules-index` documents +gives a more formal definition of the language. :ref:`library-index` documents the existing object types, functions and modules (both built-in and written in Python) that give the language its wide application range. Deleted: /doctools/trunk/Doc-26/library/asttable.rst ============================================================================== --- /doctools/trunk/Doc-26/library/asttable.rst Thu Aug 2 17:44:40 2007 +++ (empty file) @@ -1,290 +0,0 @@ -+-----------------------+--------------------+---------------------------------+ -| Node type | Attribute | Value | -+=======================+====================+=================================+ -| :class:`Add` | :attr:`left` | left operand | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | right operand | -+-----------------------+--------------------+---------------------------------+ -| :class:`And` | :attr:`nodes` | list of operands | -+-----------------------+--------------------+---------------------------------+ -| :class:`AssAttr` | | *attribute as target of | -| | | assignment* | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`expr` | expression on the left-hand | -| | | side of the dot | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`attrname` | the attribute name, a string | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`flags` | XXX | -+-----------------------+--------------------+---------------------------------+ -| :class:`AssList` | :attr:`nodes` | list of list elements being | -| | | assigned to | -+-----------------------+--------------------+---------------------------------+ -| :class:`AssName` | :attr:`name` | name being assigned to | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`flags` | XXX | -+-----------------------+--------------------+---------------------------------+ -| :class:`AssTuple` | :attr:`nodes` | list of tuple elements being | -| | | assigned to | -+-----------------------+--------------------+---------------------------------+ -| :class:`Assert` | :attr:`test` | the expression to be tested | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`fail` | the value of the | -| | | :exc:`AssertionError` | -+-----------------------+--------------------+---------------------------------+ -| :class:`Assign` | :attr:`nodes` | a list of assignment targets, | -| | | one per equal sign | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`expr` | the value being assigned | -+-----------------------+--------------------+---------------------------------+ -| :class:`AugAssign` | :attr:`node` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`op` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Backquote` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Bitand` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Bitor` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Bitxor` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Break` | | | -+-----------------------+--------------------+---------------------------------+ -| :class:`CallFunc` | :attr:`node` | expression for the callee | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`args` | a list of arguments | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`star_args` | the extended \*-arg value | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`dstar_args` | the extended \*\*-arg value | -+-----------------------+--------------------+---------------------------------+ -| :class:`Class` | :attr:`name` | the name of the class, a string | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`bases` | a list of base classes | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`doc` | doc string, a string or | -| | | ``None`` | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`code` | the body of the class statement | -+-----------------------+--------------------+---------------------------------+ -| :class:`Compare` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`ops` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Const` | :attr:`value` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Continue` | | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Decorators` | :attr:`nodes` | List of function decorator | -| | | expressions | -+-----------------------+--------------------+---------------------------------+ -| :class:`Dict` | :attr:`items` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Discard` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Div` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Ellipsis` | | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Expression` | :attr:`node` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Exec` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`locals` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`globals` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`FloorDiv` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`For` | :attr:`assign` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`list` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`body` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`else_` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`From` | :attr:`modname` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`names` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Function` | :attr:`decorators` | :class:`Decorators` or ``None`` | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`name` | name used in def, a string | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`argnames` | list of argument names, as | -| | | strings | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`defaults` | list of default values | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`flags` | xxx | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`doc` | doc string, a string or | -| | | ``None`` | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`code` | the body of the function | -+-----------------------+--------------------+---------------------------------+ -| :class:`GenExpr` | :attr:`code` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`GenExprFor` | :attr:`assign` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`iter` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`ifs` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`GenExprIf` | :attr:`test` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`GenExprInner` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`quals` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Getattr` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`attrname` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Global` | :attr:`names` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`If` | :attr:`tests` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`else_` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Import` | :attr:`names` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Invert` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Keyword` | :attr:`name` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Lambda` | :attr:`argnames` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`defaults` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`flags` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`code` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`LeftShift` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`List` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`ListComp` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`quals` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`ListCompFor` | :attr:`assign` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`list` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`ifs` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`ListCompIf` | :attr:`test` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Mod` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Module` | :attr:`doc` | doc string, a string or | -| | | ``None`` | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`node` | body of the module, a | -| | | :class:`Stmt` | -+-----------------------+--------------------+---------------------------------+ -| :class:`Mul` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Name` | :attr:`name` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Not` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Or` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Pass` | | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Power` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Print` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`dest` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Printnl` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`dest` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Raise` | :attr:`expr1` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`expr2` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`expr3` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Return` | :attr:`value` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`RightShift` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Slice` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`flags` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`lower` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`upper` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Sliceobj` | :attr:`nodes` | list of statements | -+-----------------------+--------------------+---------------------------------+ -| :class:`Stmt` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Sub` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Subscript` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`flags` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`subs` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`TryExcept` | :attr:`body` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`handlers` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`else_` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`TryFinally` | :attr:`body` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`final` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Tuple` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`UnaryAdd` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`UnarySub` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`While` | :attr:`test` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`body` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`else_` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`With` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`vars` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`body` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Yield` | :attr:`value` | | -+-----------------------+--------------------+---------------------------------+ - Modified: doctools/trunk/Doc-26/library/compiler.rst ============================================================================== --- doctools/trunk/Doc-26/library/compiler.rst (original) +++ doctools/trunk/Doc-26/library/compiler.rst Thu Aug 2 17:44:40 2007 @@ -213,7 +213,296 @@ order in which they are returned by :meth:`getChildren` and :meth:`getChildNodes`. -XXX: input{asttable} :XXX ++-----------------------+--------------------+---------------------------------+ +| Node type | Attribute | Value | ++=======================+====================+=================================+ +| :class:`Add` | :attr:`left` | left operand | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`right` | right operand | ++-----------------------+--------------------+---------------------------------+ +| :class:`And` | :attr:`nodes` | list of operands | ++-----------------------+--------------------+---------------------------------+ +| :class:`AssAttr` | | *attribute as target of | +| | | assignment* | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`expr` | expression on the left-hand | +| | | side of the dot | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`attrname` | the attribute name, a string | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`flags` | XXX | ++-----------------------+--------------------+---------------------------------+ +| :class:`AssList` | :attr:`nodes` | list of list elements being | +| | | assigned to | ++-----------------------+--------------------+---------------------------------+ +| :class:`AssName` | :attr:`name` | name being assigned to | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`flags` | XXX | ++-----------------------+--------------------+---------------------------------+ +| :class:`AssTuple` | :attr:`nodes` | list of tuple elements being | +| | | assigned to | ++-----------------------+--------------------+---------------------------------+ +| :class:`Assert` | :attr:`test` | the expression to be tested | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`fail` | the value of the | +| | | :exc:`AssertionError` | ++-----------------------+--------------------+---------------------------------+ +| :class:`Assign` | :attr:`nodes` | a list of assignment targets, | +| | | one per equal sign | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`expr` | the value being assigned | ++-----------------------+--------------------+---------------------------------+ +| :class:`AugAssign` | :attr:`node` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`op` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Backquote` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Bitand` | :attr:`nodes` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Bitor` | :attr:`nodes` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Bitxor` | :attr:`nodes` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Break` | | | ++-----------------------+--------------------+---------------------------------+ +| :class:`CallFunc` | :attr:`node` | expression for the callee | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`args` | a list of arguments | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`star_args` | the extended \*-arg value | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`dstar_args` | the extended \*\*-arg value | ++-----------------------+--------------------+---------------------------------+ +| :class:`Class` | :attr:`name` | the name of the class, a string | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`bases` | a list of base classes | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`doc` | doc string, a string or | +| | | ``None`` | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`code` | the body of the class statement | ++-----------------------+--------------------+---------------------------------+ +| :class:`Compare` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`ops` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Const` | :attr:`value` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Continue` | | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Decorators` | :attr:`nodes` | List of function decorator | +| | | expressions | ++-----------------------+--------------------+---------------------------------+ +| :class:`Dict` | :attr:`items` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Discard` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Div` | :attr:`left` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`right` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Ellipsis` | | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Expression` | :attr:`node` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Exec` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`locals` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`globals` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`FloorDiv` | :attr:`left` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`right` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`For` | :attr:`assign` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`list` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`body` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`else_` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`From` | :attr:`modname` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`names` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Function` | :attr:`decorators` | :class:`Decorators` or ``None`` | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`name` | name used in def, a string | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`argnames` | list of argument names, as | +| | | strings | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`defaults` | list of default values | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`flags` | xxx | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`doc` | doc string, a string or | +| | | ``None`` | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`code` | the body of the function | ++-----------------------+--------------------+---------------------------------+ +| :class:`GenExpr` | :attr:`code` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`GenExprFor` | :attr:`assign` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`iter` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`ifs` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`GenExprIf` | :attr:`test` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`GenExprInner` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`quals` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Getattr` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`attrname` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Global` | :attr:`names` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`If` | :attr:`tests` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`else_` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Import` | :attr:`names` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Invert` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Keyword` | :attr:`name` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Lambda` | :attr:`argnames` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`defaults` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`flags` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`code` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`LeftShift` | :attr:`left` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`right` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`List` | :attr:`nodes` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`ListComp` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`quals` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`ListCompFor` | :attr:`assign` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`list` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`ifs` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`ListCompIf` | :attr:`test` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Mod` | :attr:`left` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`right` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Module` | :attr:`doc` | doc string, a string or | +| | | ``None`` | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`node` | body of the module, a | +| | | :class:`Stmt` | ++-----------------------+--------------------+---------------------------------+ +| :class:`Mul` | :attr:`left` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`right` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Name` | :attr:`name` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Not` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Or` | :attr:`nodes` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Pass` | | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Power` | :attr:`left` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`right` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Print` | :attr:`nodes` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`dest` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Printnl` | :attr:`nodes` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`dest` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Raise` | :attr:`expr1` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`expr2` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`expr3` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Return` | :attr:`value` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`RightShift` | :attr:`left` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`right` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Slice` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`flags` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`lower` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`upper` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Sliceobj` | :attr:`nodes` | list of statements | ++-----------------------+--------------------+---------------------------------+ +| :class:`Stmt` | :attr:`nodes` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Sub` | :attr:`left` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`right` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Subscript` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`flags` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`subs` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`TryExcept` | :attr:`body` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`handlers` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`else_` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`TryFinally` | :attr:`body` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`final` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Tuple` | :attr:`nodes` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`UnaryAdd` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`UnarySub` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`While` | :attr:`test` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`body` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`else_` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`With` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`vars` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`body` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Yield` | :attr:`value` | | ++-----------------------+--------------------+---------------------------------+ + Assignment nodes ---------------- Modified: doctools/trunk/Doc-26/library/contextlib.rst ============================================================================== --- doctools/trunk/Doc-26/library/contextlib.rst (original) +++ doctools/trunk/Doc-26/library/contextlib.rst Thu Aug 2 17:44:40 2007 @@ -82,8 +82,6 @@ :meth:`__exit__` methods should avoid raising exceptions, and in particular they should not re-raise a passed-in exception. -.. _context-closing: - .. function:: closing(thing) Modified: doctools/trunk/Doc-26/library/cookielib.rst ============================================================================== --- doctools/trunk/Doc-26/library/cookielib.rst (original) +++ doctools/trunk/Doc-26/library/cookielib.rst Thu Aug 2 17:44:40 2007 @@ -32,9 +32,8 @@ :mailheader:`Set-Cookie2` headers (eg. ``domain`` and ``expires``) are conventionally referred to as :dfn:`attributes`. To distinguish them from Python attributes, the documentation for this module uses the term - :dfn:`cookie-attribute` instead + :dfn:`cookie-attribute` instead. -. The module defines the following exception: @@ -47,9 +46,8 @@ .. note:: For backwards-compatibility with Python 2.4 (which raised an :exc:`IOError`), - :exc:`LoadError` is a subclass of :exc:`IOError` + :exc:`LoadError` is a subclass of :exc:`IOError`. - . The following classes are provided: @@ -601,7 +599,7 @@ Equivalent to ``DomainStrictNoDots|DomainStrictNonDomain``. -.. _cookie-objects: +.. _cookielib-cookie-objects: Cookie Objects -------------- Added: doctools/trunk/Doc-26/library/idle.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-26/library/idle.rst Thu Aug 2 17:44:40 2007 @@ -0,0 +1,288 @@ +.. _idle: + +Idle +==== + +.. moduleauthor:: Guido van Rossum + + +.. % \declaremodule{standard}{idle} +.. % \modulesynopsis{A Python Integrated Development Environment} + +.. index:: + single: Idle + single: Python Editor + single: Integrated Development Environment + +Idle is the Python IDE built with the :mod:`Tkinter` GUI toolkit. + +IDLE has the following features: + +* coded in 100% pure Python, using the :mod:`Tkinter` GUI toolkit + +* cross-platform: works on Windows and Unix (on Mac OS, there are currently + problems with Tcl/Tk) + +* multi-window text editor with multiple undo, Python colorizing and many other + features, e.g. smart indent and call tips + +* Python shell window (a.k.a. interactive interpreter) + +* debugger (not complete, but you can set breakpoints, view and step) + + +Menus +----- + + +File menu +^^^^^^^^^ + +New window + create a new editing window + +Open... + open an existing file + +Open module... + open an existing module (searches sys.path) + +Class browser + show classes and methods in current file + +Path browser + show sys.path directories, modules, classes and methods + +.. index:: + single: Class browser + single: Path browser + +Save + save current window to the associated file (unsaved windows have a \* before and + after the window title) + +Save As... + save current window to new file, which becomes the associated file + +Save Copy As... + save current window to different file without changing the associated file + +Close + close current window (asks to save if unsaved) + +Exit + close all windows and quit IDLE (asks to save if unsaved) + + +Edit menu +^^^^^^^^^ + +Undo + Undo last change to current window (max 1000 changes) + +Redo + Redo last undone change to current window + +Cut + Copy selection into system-wide clipboard; then delete selection + +Copy + Copy selection into system-wide clipboard + +Paste + Insert system-wide clipboard into window + +Select All + Select the entire contents of the edit buffer + +Find... + Open a search dialog box with many options + +Find again + Repeat last search + +Find selection + Search for the string in the selection + +Find in Files... + Open a search dialog box for searching files + +Replace... + Open a search-and-replace dialog box + +Go to line + Ask for a line number and show that line + +Indent region + Shift selected lines right 4 spaces + +Dedent region + Shift selected lines left 4 spaces + +Comment out region + Insert ## in front of selected lines + +Uncomment region + Remove leading # or ## from selected lines + +Tabify region + Turns *leading* stretches of spaces into tabs + +Untabify region + Turn *all* tabs into the right number of spaces + +Expand word + Expand the word you have typed to match another word in the same buffer; repeat + to get a different expansion + +Format Paragraph + Reformat the current blank-line-separated paragraph + +Import module + Import or reload the current module + +Run script + Execute the current file in the __main__ namespace + +.. index:: + single: Import module + single: Run script + + +Windows menu +^^^^^^^^^^^^ + +Zoom Height + toggles the window between normal size (24x80) and maximum height. + +The rest of this menu lists the names of all open windows; select one to bring +it to the foreground (deiconifying it if necessary). + + +Debug menu (in the Python Shell window only) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Go to file/line + look around the insert point for a filename and linenumber, open the file, and + show the line. + +Open stack viewer + show the stack traceback of the last exception + +Debugger toggle + Run commands in the shell under the debugger + +JIT Stack viewer toggle + Open stack viewer on traceback + +.. index:: + single: stack viewer + single: debugger + + +Basic editing and navigation +---------------------------- + +* :kbd:`Backspace` deletes to the left; :kbd:`Del` deletes to the right + +* Arrow keys and :kbd:`Page Up`/:kbd:`Page Down` to move around + +* :kbd:`Home`/:kbd:`End` go to begin/end of line + +* :kbd:`C-Home`/:kbd:`C-End` go to begin/end of file + +* Some :program:`Emacs` bindings may also work, including :kbd:`C-B`, + :kbd:`C-P`, :kbd:`C-A`, :kbd:`C-E`, :kbd:`C-D`, :kbd:`C-L` + + +Automatic indentation +^^^^^^^^^^^^^^^^^^^^^ + +After a block-opening statement, the next line is indented by 4 spaces (in the +Python Shell window by one tab). After certain keywords (break, return etc.) +the next line is dedented. In leading indentation, :kbd:`Backspace` deletes up +to 4 spaces if they are there. :kbd:`Tab` inserts 1-4 spaces (in the Python +Shell window one tab). See also the indent/dedent region commands in the edit +menu. + + +Python Shell window +^^^^^^^^^^^^^^^^^^^ + +* :kbd:`C-C` interrupts executing command + +* :kbd:`C-D` sends end-of-file; closes window if typed at a ``>>>`` prompt + +* :kbd:`Alt-p` retrieves previous command matching what you have typed + +* :kbd:`Alt-n` retrieves next + +* :kbd:`Return` while on any previous command retrieves that command + +* :kbd:`Alt-/` (Expand word) is also useful here + +.. index:: single: indentation + + +Syntax colors +------------- + +The coloring is applied in a background "thread," so you may occasionally see +uncolorized text. To change the color scheme, edit the ``[Colors]`` section in +:file:`config.txt`. + +Python syntax colors: + Keywords + orange + + Strings + green + + Comments + red + + Definitions + blue + +Shell colors: + Console output + brown + + stdout + blue + + stderr + dark green + + stdin + black + + +Command line usage +^^^^^^^^^^^^^^^^^^ + +:: + + idle.py [-c command] [-d] [-e] [-s] [-t title] [arg] ... + + -c command run this command + -d enable debugger + -e edit mode; arguments are files to be edited + -s run $IDLESTARTUP or $PYTHONSTARTUP first + -t title set title of shell window + +If there are arguments: + +#. If :option:`-e` is used, arguments are files opened for editing and + ``sys.argv`` reflects the arguments passed to IDLE itself. + +#. Otherwise, if :option:`-c` is used, all arguments are placed in + ``sys.argv[1:...]``, with ``sys.argv[0]`` set to ``'-c'``. + +#. Otherwise, if neither :option:`-e` nor :option:`-c` is used, the first + argument is a script which is executed with the remaining arguments in + ``sys.argv[1:...]`` and ``sys.argv[0]`` set to the script name. If the script + name is '-', no script is executed but an interactive Python session is started; + the arguments are still available in ``sys.argv``. + + Modified: doctools/trunk/Doc-26/library/index.rst ============================================================================== --- doctools/trunk/Doc-26/library/index.rst (original) +++ doctools/trunk/Doc-26/library/index.rst Thu Aug 2 17:44:40 2007 @@ -51,7 +51,7 @@ ipc.rst internet.rst mm.rst - tkinter.rst + tk.rst i18n.rst frameworks.rst development.rst Modified: doctools/trunk/Doc-26/library/intro.rst ============================================================================== --- doctools/trunk/Doc-26/library/intro.rst (original) +++ doctools/trunk/Doc-26/library/intro.rst Thu Aug 2 17:44:40 2007 @@ -1,5 +1,5 @@ -.. _intro: +.. _library-intro: ************ Introduction Added: doctools/trunk/Doc-26/library/othergui.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-26/library/othergui.rst Thu Aug 2 17:44:40 2007 @@ -0,0 +1,93 @@ +.. _other-gui-packages: + +Other Graphical User Interface Packages +======================================= + +There are an number of extension widget sets to :mod:`Tkinter`. + + +.. seealso:: + + `Python megawidgets `_ + is a toolkit for building high-level compound widgets in Python using the + :mod:`Tkinter` module. It consists of a set of base classes and a library of + flexible and extensible megawidgets built on this foundation. These megawidgets + include notebooks, comboboxes, selection widgets, paned widgets, scrolled + widgets, dialog windows, etc. Also, with the Pmw.Blt interface to BLT, the + busy, graph, stripchart, tabset and vector commands are be available. + + The initial ideas for Pmw were taken from the Tk ``itcl`` extensions ``[incr + Tk]`` by Michael McLennan and ``[incr Widgets]`` by Mark Ulferts. Several of the + megawidgets are direct translations from the itcl to Python. It offers most of + the range of widgets that ``[incr Widgets]`` does, and is almost as complete as + Tix, lacking however Tix's fast :class:`HList` widget for drawing trees. + + `Tkinter3000 Widget Construction Kit (WCK) `_ + is a library that allows you to write new Tkinter widgets in pure Python. The + WCK framework gives you full control over widget creation, configuration, screen + appearance, and event handling. WCK widgets can be very fast and light-weight, + since they can operate directly on Python data structures, without having to + transfer data through the Tk/Tcl layer. + + .. % + +Other GUI packages are also available for Python: + + +.. seealso:: + + `wxPython `_ + wxPython is a cross-platform GUI toolkit for Python that is built around the + popular `wxWidgets `_ C++ toolkit. ?It provides a + native look and feel for applications on Windows, Mac OS X, and Unix systems by + using each platform's native widgets where ever possible, (GTK+ on Unix-like + systems). ?In addition to an extensive set of widgets, wxPython provides classes + for online documentation and context sensitive help, printing, HTML viewing, + low-level device context drawing, drag and drop, system clipboard access, an + XML-based resource format and more, including an ever growing library of user- + contributed modules. ?Both the wxWidgets and wxPython projects are under active + development and continuous improvement, and have active and helpful user and + developer communities. + + `wxPython in Action `_ + The wxPython book, by Noel Rappin and Robin Dunn. + + PyQt + PyQt is a :program:`sip`\ -wrapped binding to the Qt toolkit. Qt is an + extensive C++ GUI toolkit that is available for Unix, Windows and Mac OS X. + :program:`sip` is a tool for generating bindings for C++ libraries as Python + classes, and is specifically designed for Python. An online manual is available + at http://www.opendocspublishing.com/pyqt/ (errata are located at + http://www.valdyas.org/python/book.html). + + `PyKDE `_ + PyKDE is a :program:`sip`\ -wrapped interface to the KDE desktop libraries. KDE + is a desktop environment for Unix computers; the graphical components are based + on Qt. + + `FXPy `_ + is a Python extension module which provides an interface to the `FOX + `_ GUI. FOX is a C++ based Toolkit for + developing Graphical User Interfaces easily and effectively. It offers a wide, + and growing, collection of Controls, and provides state of the art facilities + such as drag and drop, selection, as well as OpenGL widgets for 3D graphical + manipulation. FOX also implements icons, images, and user-convenience features + such as status line help, and tooltips. + + Even though FOX offers a large collection of controls already, FOX leverages C++ + to allow programmers to easily build additional Controls and GUI elements, + simply by taking existing controls, and creating a derived class which simply + adds or redefines the desired behavior. + + `PyGTK `_ + is a set of bindings for the `GTK `_ widget set. It + provides an object oriented interface that is slightly higher level than the C + one. It automatically does all the type casting and reference counting that you + would have to do normally with the C API. There are also `bindings + `_ to `GNOME `_, and + a `tutorial + `_ is + available. + +.. % XXX Reference URLs that compare the different UI packages + Added: doctools/trunk/Doc-26/library/scrolledtext.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-26/library/scrolledtext.rst Thu Aug 2 17:44:40 2007 @@ -0,0 +1,32 @@ +:mod:`ScrolledText` --- Scrolled Text Widget +============================================ + +.. module:: ScrolledText + :platform: Tk + :synopsis: Text widget with a vertical scroll bar. +.. sectionauthor:: Fred L. Drake, Jr. + + +The :mod:`ScrolledText` module provides a class of the same name which +implements a basic text widget which has a vertical scroll bar configured to do +the "right thing." Using the :class:`ScrolledText` class is a lot easier than +setting up a text widget and scroll bar directly. The constructor is the same +as that of the :class:`Tkinter.Text` class. + +The text widget and scrollbar are packed together in a :class:`Frame`, and the +methods of the :class:`Grid` and :class:`Pack` geometry managers are acquired +from the :class:`Frame` object. This allows the :class:`ScrolledText` widget to +be used directly to achieve most normal geometry management behavior. + +Should more specific control be necessary, the following attributes are +available: + + +.. attribute:: ScrolledText.frame + + The frame which surrounds the text and scroll bar widgets. + + +.. attribute:: ScrolledText.vbar + + The scroll bar widget. Modified: doctools/trunk/Doc-26/library/sqlite3.rst ============================================================================== --- doctools/trunk/Doc-26/library/sqlite3.rst (original) +++ doctools/trunk/Doc-26/library/sqlite3.rst Thu Aug 2 17:44:40 2007 @@ -148,9 +148,8 @@ for the lock to go away until raising an exception. The default for the timeout parameter is 5.0 (five seconds). - For the *isolation_level* parameter, please see the :attr:`isolation_level` - property of :class:`Connection` objects in section - :ref:`sqlite3-connection-isolationlevel`. + For the *isolation_level* parameter, please see the + :attr:`Connection.isolation_level` property of :class:`Connection` objects. SQLite natively supports only the types TEXT, INTEGER, FLOAT, BLOB and NULL. If you want to use other types you must add support for them yourself. The @@ -221,9 +220,6 @@ A :class:`Connection` instance has the following attributes and methods: -.. _sqlite3-connection-isolationlevel: - - .. attribute:: Connection.isolation_level Get or set the current isolation level. None for autocommit mode or one of Modified: doctools/trunk/Doc-26/library/stdtypes.rst ============================================================================== --- doctools/trunk/Doc-26/library/stdtypes.rst (original) +++ doctools/trunk/Doc-26/library/stdtypes.rst Thu Aug 2 17:44:40 2007 @@ -1,5 +1,5 @@ -.. _types: +.. _bltin-types: ************** Built-in Types @@ -120,7 +120,7 @@ interpreted as ``not (a == b)``, and ``a == not b`` is a syntax error. -.. _comparisons: +.. _stdcomparisons: Comparisons =========== @@ -1781,9 +1781,8 @@ Not all "file-like" types in Python support use as a context manager for the :keyword:`with` statement. If your code is intended to work with any file-like - object, you can use the :func:`closing` function in the :mod:`contextlib` module - instead of using the object directly. See section :ref:`context-closing` for - details. + object, you can use the function :func:`contextlib.closing` instead of using + the object directly. .. method:: file.flush() Modified: doctools/trunk/Doc-26/library/strings.rst ============================================================================== --- doctools/trunk/Doc-26/library/strings.rst (original) +++ doctools/trunk/Doc-26/library/strings.rst Thu Aug 2 17:44:40 2007 @@ -1,5 +1,5 @@ -.. _strings: +.. _stringservices: *************** String Services Modified: doctools/trunk/Doc-26/library/tarfile.rst ============================================================================== --- doctools/trunk/Doc-26/library/tarfile.rst (original) +++ doctools/trunk/Doc-26/library/tarfile.rst Thu Aug 2 17:44:40 2007 @@ -1,3 +1,4 @@ +.. _tarfile-mod: :mod:`tarfile` --- Read and write tar archive files =================================================== @@ -286,7 +287,7 @@ .. method:: TarFile.open(...) Alternative constructor. The :func:`open` function on module level is actually a - shortcut to this classmethod. See section :ref:`module-tarfile` for details. + shortcut to this classmethod. See section :ref:`tarfile-mod` for details. .. method:: TarFile.getmember(name) Added: doctools/trunk/Doc-26/library/tix.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-26/library/tix.rst Thu Aug 2 17:44:40 2007 @@ -0,0 +1,602 @@ +:mod:`Tix` --- Extension widgets for Tk +======================================= + +.. module:: Tix + :synopsis: Tk Extension Widgets for Tkinter +.. sectionauthor:: Mike Clarkson + + +.. index:: single: Tix + +The :mod:`Tix` (Tk Interface Extension) module provides an additional rich set +of widgets. Although the standard Tk library has many useful widgets, they are +far from complete. The :mod:`Tix` library provides most of the commonly needed +widgets that are missing from standard Tk: :class:`HList`, :class:`ComboBox`, +:class:`Control` (a.k.a. SpinBox) and an assortment of scrollable widgets. +:mod:`Tix` also includes many more widgets that are generally useful in a wide +range of applications: :class:`NoteBook`, :class:`FileEntry`, +:class:`PanedWindow`, etc; there are more than 40 of them. + +With all these new widgets, you can introduce new interaction techniques into +applications, creating more useful and more intuitive user interfaces. You can +design your application by choosing the most appropriate widgets to match the +special needs of your application and users. + + +.. seealso:: + + `Tix Homepage `_ + The home page for :mod:`Tix`. This includes links to additional documentation + and downloads. + + `Tix Man Pages `_ + On-line version of the man pages and reference material. + + `Tix Programming Guide `_ + On-line version of the programmer's reference material. + + `Tix Development Applications `_ + Tix applications for development of Tix and Tkinter programs. Tide applications + work under Tk or Tkinter, and include :program:`TixInspect`, an inspector to + remotely modify and debug Tix/Tk/Tkinter applications. + + +Using Tix +--------- + + +.. class:: Tix(screenName[, baseName[, className]]) + + Toplevel widget of Tix which represents mostly the main window of an + application. It has an associated Tcl interpreter. + + Classes in the :mod:`Tix` module subclasses the classes in the :mod:`Tkinter` + module. The former imports the latter, so to use :mod:`Tix` with Tkinter, all + you need to do is to import one module. In general, you can just import + :mod:`Tix`, and replace the toplevel call to :class:`Tkinter.Tk` with + :class:`Tix.Tk`:: + + import Tix + from Tkconstants import * + root = Tix.Tk() + +To use :mod:`Tix`, you must have the :mod:`Tix` widgets installed, usually +alongside your installation of the Tk widgets. To test your installation, try +the following:: + + import Tix + root = Tix.Tk() + root.tk.eval('package require Tix') + +If this fails, you have a Tk installation problem which must be resolved before +proceeding. Use the environment variable :envvar:`TIX_LIBRARY` to point to the +installed :mod:`Tix` library directory, and make sure you have the dynamic +object library (:file:`tix8183.dll` or :file:`libtix8183.so`) in the same +directory that contains your Tk dynamic object library (:file:`tk8183.dll` or +:file:`libtk8183.so`). The directory with the dynamic object library should also +have a file called :file:`pkgIndex.tcl` (case sensitive), which contains the +line:: + + package ifneeded Tix 8.1 [list load "[file join $dir tix8183.dll]" Tix] + +.. % $ <-- bow to font-lock + + +Tix Widgets +----------- + +`Tix `_ +introduces over 40 widget classes to the :mod:`Tkinter` repertoire. There is a +demo of all the :mod:`Tix` widgets in the :file:`Demo/tix` directory of the +standard distribution. + +.. % The Python sample code is still being added to Python, hence commented out + + +Basic Widgets +^^^^^^^^^^^^^ + + +.. class:: Balloon() + + A `Balloon + `_ that + pops up over a widget to provide help. When the user moves the cursor inside a + widget to which a Balloon widget has been bound, a small pop-up window with a + descriptive message will be shown on the screen. + +.. % Python Demo of: +.. % \ulink{Balloon}{http://tix.sourceforge.net/dist/current/demos/samples/Balloon.tcl} + + +.. class:: ButtonBox() + + The `ButtonBox + `_ + widget creates a box of buttons, such as is commonly used for ``Ok Cancel``. + +.. % Python Demo of: +.. % \ulink{ButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/BtnBox.tcl} + + +.. class:: ComboBox() + + The `ComboBox + `_ + widget is similar to the combo box control in MS Windows. The user can select a + choice by either typing in the entry subwdget or selecting from the listbox + subwidget. + +.. % Python Demo of: +.. % \ulink{ComboBox}{http://tix.sourceforge.net/dist/current/demos/samples/ComboBox.tcl} + + +.. class:: Control() + + The `Control + `_ + widget is also known as the :class:`SpinBox` widget. The user can adjust the + value by pressing the two arrow buttons or by entering the value directly into + the entry. The new value will be checked against the user-defined upper and + lower limits. + +.. % Python Demo of: +.. % \ulink{Control}{http://tix.sourceforge.net/dist/current/demos/samples/Control.tcl} + + +.. class:: LabelEntry() + + The `LabelEntry + `_ + widget packages an entry widget and a label into one mega widget. It can be used + be used to simplify the creation of "entry-form" type of interface. + +.. % Python Demo of: +.. % \ulink{LabelEntry}{http://tix.sourceforge.net/dist/current/demos/samples/LabEntry.tcl} + + +.. class:: LabelFrame() + + The `LabelFrame + `_ + widget packages a frame widget and a label into one mega widget. To create + widgets inside a LabelFrame widget, one creates the new widgets relative to the + :attr:`frame` subwidget and manage them inside the :attr:`frame` subwidget. + +.. % Python Demo of: +.. % \ulink{LabelFrame}{http://tix.sourceforge.net/dist/current/demos/samples/LabFrame.tcl} + + +.. class:: Meter() + + The `Meter + `_ widget + can be used to show the progress of a background job which may take a long time + to execute. + +.. % Python Demo of: +.. % \ulink{Meter}{http://tix.sourceforge.net/dist/current/demos/samples/Meter.tcl} + + +.. class:: OptionMenu() + + The `OptionMenu + `_ + creates a menu button of options. + +.. % Python Demo of: +.. % \ulink{OptionMenu}{http://tix.sourceforge.net/dist/current/demos/samples/OptMenu.tcl} + + +.. class:: PopupMenu() + + The `PopupMenu + `_ + widget can be used as a replacement of the ``tk_popup`` command. The advantage + of the :mod:`Tix` :class:`PopupMenu` widget is it requires less application code + to manipulate. + +.. % Python Demo of: +.. % \ulink{PopupMenu}{http://tix.sourceforge.net/dist/current/demos/samples/PopMenu.tcl} + + +.. class:: Select() + + The `Select + `_ widget + is a container of button subwidgets. It can be used to provide radio-box or + check-box style of selection options for the user. + +.. % Python Demo of: +.. % \ulink{Select}{http://tix.sourceforge.net/dist/current/demos/samples/Select.tcl} + + +.. class:: StdButtonBox() + + The `StdButtonBox + `_ + widget is a group of standard buttons for Motif-like dialog boxes. + +.. % Python Demo of: +.. % \ulink{StdButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/StdBBox.tcl} + + +File Selectors +^^^^^^^^^^^^^^ + + +.. class:: DirList() + + The `DirList + `_ + widget displays a list view of a directory, its previous directories and its + sub-directories. The user can choose one of the directories displayed in the + list or change to another directory. + +.. % Python Demo of: +.. % \ulink{DirList}{http://tix.sourceforge.net/dist/current/demos/samples/DirList.tcl} + + +.. class:: DirTree() + + The `DirTree + `_ + widget displays a tree view of a directory, its previous directories and its + sub-directories. The user can choose one of the directories displayed in the + list or change to another directory. + +.. % Python Demo of: +.. % \ulink{DirTree}{http://tix.sourceforge.net/dist/current/demos/samples/DirTree.tcl} + + +.. class:: DirSelectDialog() + + The `DirSelectDialog + `_ + widget presents the directories in the file system in a dialog window. The user + can use this dialog window to navigate through the file system to select the + desired directory. + +.. % Python Demo of: +.. % \ulink{DirSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/DirDlg.tcl} + + +.. class:: DirSelectBox() + + The :class:`DirSelectBox` is similar to the standard Motif(TM) directory- + selection box. It is generally used for the user to choose a directory. + DirSelectBox stores the directories mostly recently selected into a ComboBox + widget so that they can be quickly selected again. + + +.. class:: ExFileSelectBox() + + The `ExFileSelectBox + `_ + widget is usually embedded in a tixExFileSelectDialog widget. It provides an + convenient method for the user to select files. The style of the + :class:`ExFileSelectBox` widget is very similar to the standard file dialog on + MS Windows 3.1. + +.. % Python Demo of: +.. % \ulink{ExFileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/EFileDlg.tcl} + + +.. class:: FileSelectBox() + + The `FileSelectBox + `_ + is similar to the standard Motif(TM) file-selection box. It is generally used + for the user to choose a file. FileSelectBox stores the files mostly recently + selected into a :class:`ComboBox` widget so that they can be quickly selected + again. + +.. % Python Demo of: +.. % \ulink{FileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/FileDlg.tcl} + + +.. class:: FileEntry() + + The `FileEntry + `_ + widget can be used to input a filename. The user can type in the filename + manually. Alternatively, the user can press the button widget that sits next to + the entry, which will bring up a file selection dialog. + +.. % Python Demo of: +.. % \ulink{FileEntry}{http://tix.sourceforge.net/dist/current/demos/samples/FileEnt.tcl} + + +Hierachical ListBox +^^^^^^^^^^^^^^^^^^^ + + +.. class:: HList() + + The `HList + `_ widget + can be used to display any data that have a hierarchical structure, for example, + file system directory trees. The list entries are indented and connected by + branch lines according to their places in the hierarchy. + +.. % Python Demo of: +.. % \ulink{HList}{http://tix.sourceforge.net/dist/current/demos/samples/HList1.tcl} + + +.. class:: CheckList() + + The `CheckList + `_ + widget displays a list of items to be selected by the user. CheckList acts + similarly to the Tk checkbutton or radiobutton widgets, except it is capable of + handling many more items than checkbuttons or radiobuttons. + +.. % Python Demo of: +.. % \ulink{ CheckList}{http://tix.sourceforge.net/dist/current/demos/samples/ChkList.tcl} +.. % Python Demo of: +.. % \ulink{ScrolledHList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList.tcl} +.. % Python Demo of: +.. % \ulink{ScrolledHList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList2.tcl} + + +.. class:: Tree() + + The `Tree + `_ widget + can be used to display hierarchical data in a tree form. The user can adjust the + view of the tree by opening or closing parts of the tree. + +.. % Python Demo of: +.. % \ulink{Tree}{http://tix.sourceforge.net/dist/current/demos/samples/Tree.tcl} +.. % Python Demo of: +.. % \ulink{Tree (Dynamic)}{http://tix.sourceforge.net/dist/current/demos/samples/DynTree.tcl} + + +Tabular ListBox +^^^^^^^^^^^^^^^ + + +.. class:: TList() + + The `TList + `_ widget + can be used to display data in a tabular format. The list entries of a + :class:`TList` widget are similar to the entries in the Tk listbox widget. The + main differences are (1) the :class:`TList` widget can display the list entries + in a two dimensional format and (2) you can use graphical images as well as + multiple colors and fonts for the list entries. + +.. % Python Demo of: +.. % \ulink{ScrolledTList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/STList1.tcl} +.. % Python Demo of: +.. % \ulink{ScrolledTList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/STList2.tcl} +.. % Grid has yet to be added to Python +.. % \subsubsection{Grid Widget} +.. % Python Demo of: +.. % \ulink{Simple Grid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid0.tcl} +.. % Python Demo of: +.. % \ulink{ScrolledGrid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid1.tcl} +.. % Python Demo of: +.. % \ulink{Editable Grid}{http://tix.sourceforge.net/dist/current/demos/samples/EditGrid.tcl} + + +Manager Widgets +^^^^^^^^^^^^^^^ + + +.. class:: PanedWindow() + + The `PanedWindow + `_ + widget allows the user to interactively manipulate the sizes of several panes. + The panes can be arranged either vertically or horizontally. The user changes + the sizes of the panes by dragging the resize handle between two panes. + +.. % Python Demo of: +.. % \ulink{PanedWindow}{http://tix.sourceforge.net/dist/current/demos/samples/PanedWin.tcl} + + +.. class:: ListNoteBook() + + The `ListNoteBook + `_ + widget is very similar to the :class:`TixNoteBook` widget: it can be used to + display many windows in a limited space using a notebook metaphor. The notebook + is divided into a stack of pages (windows). At one time only one of these pages + can be shown. The user can navigate through these pages by choosing the name of + the desired page in the :attr:`hlist` subwidget. + +.. % Python Demo of: +.. % \ulink{ListNoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/ListNBK.tcl} + + +.. class:: NoteBook() + + The `NoteBook + `_ + widget can be used to display many windows in a limited space using a notebook + metaphor. The notebook is divided into a stack of pages. At one time only one of + these pages can be shown. The user can navigate through these pages by choosing + the visual "tabs" at the top of the NoteBook widget. + +.. % Python Demo of: +.. % \ulink{NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/NoteBook.tcl} + +.. % \subsubsection{Scrolled Widgets} +.. % Python Demo of: +.. % \ulink{ScrolledListBox}{http://tix.sourceforge.net/dist/current/demos/samples/SListBox.tcl} +.. % Python Demo of: +.. % \ulink{ScrolledText}{http://tix.sourceforge.net/dist/current/demos/samples/SText.tcl} +.. % Python Demo of: +.. % \ulink{ScrolledWindow}{http://tix.sourceforge.net/dist/current/demos/samples/SWindow.tcl} +.. % Python Demo of: +.. % \ulink{Canvas Object View}{http://tix.sourceforge.net/dist/current/demos/samples/CObjView.tcl} + + +Image Types +^^^^^^^^^^^ + +The :mod:`Tix` module adds: + +* `pixmap `_ + capabilities to all :mod:`Tix` and :mod:`Tkinter` widgets to create color images + from XPM files. + + .. % Python Demo of: + .. % \ulink{XPM Image In Button}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm.tcl} + .. % Python Demo of: + .. % \ulink{XPM Image In Menu}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm1.tcl} + +* `Compound + `_ image + types can be used to create images that consists of multiple horizontal lines; + each line is composed of a series of items (texts, bitmaps, images or spaces) + arranged from left to right. For example, a compound image can be used to + display a bitmap and a text string simultaneously in a Tk :class:`Button` + widget. + + .. % Python Demo of: + .. % \ulink{Compound Image In Buttons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg.tcl} + .. % Python Demo of: + .. % \ulink{Compound Image In NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg2.tcl} + .. % Python Demo of: + .. % \ulink{Compound Image Notebook Color Tabs}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg4.tcl} + .. % Python Demo of: + .. % \ulink{Compound Image Icons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg3.tcl} + + +Miscellaneous Widgets +^^^^^^^^^^^^^^^^^^^^^ + + +.. class:: InputOnly() + + The `InputOnly + `_ + widgets are to accept inputs from the user, which can be done with the ``bind`` + command (Unix only). + + +Form Geometry Manager +^^^^^^^^^^^^^^^^^^^^^ + +In addition, :mod:`Tix` augments :mod:`Tkinter` by providing: + + +.. class:: Form() + + The `Form + `_ geometry + manager based on attachment rules for all Tk widgets. + +.. % begin{latexonly} +.. % \subsection{Tix Class Structure} +.. % +.. % \begin{figure}[hbtp] +.. % \centerline{\epsfig{file=hierarchy.png,width=.9\textwidth}} +.. % \vspace{.5cm} +.. % \caption{The Class Hierarchy of Tix Widgets} +.. % \end{figure} +.. % end{latexonly} + + +Tix Commands +------------ + + +.. class:: tixCommand() + + The `tix commands + `_ provide + access to miscellaneous elements of :mod:`Tix`'s internal state and the + :mod:`Tix` application context. Most of the information manipulated by these + methods pertains to the application as a whole, or to a screen or display, + rather than to a particular window. + + To view the current settings, the common usage is:: + + import Tix + root = Tix.Tk() + print root.tix_configure() + + +.. method:: tixCommand.tix_configure([cnf,] **kw) + + Query or modify the configuration options of the Tix application context. If no + option is specified, returns a dictionary all of the available options. If + option is specified with no value, then the method returns a list describing the + one named option (this list will be identical to the corresponding sublist of + the value returned if no option is specified). If one or more option-value + pairs are specified, then the method modifies the given option(s) to have the + given value(s); in this case the method returns an empty string. Option may be + any of the configuration options. + + +.. method:: tixCommand.tix_cget(option) + + Returns the current value of the configuration option given by *option*. Option + may be any of the configuration options. + + +.. method:: tixCommand.tix_getbitmap(name) + + Locates a bitmap file of the name ``name.xpm`` or ``name`` in one of the bitmap + directories (see the :meth:`tix_addbitmapdir` method). By using + :meth:`tix_getbitmap`, you can avoid hard coding the pathnames of the bitmap + files in your application. When successful, it returns the complete pathname of + the bitmap file, prefixed with the character ``@``. The returned value can be + used to configure the ``bitmap`` option of the Tk and Tix widgets. + + +.. method:: tixCommand.tix_addbitmapdir(directory) + + Tix maintains a list of directories under which the :meth:`tix_getimage` and + :meth:`tix_getbitmap` methods will search for image files. The standard bitmap + directory is :file:`$TIX_LIBRARY/bitmaps`. The :meth:`tix_addbitmapdir` method + adds *directory* into this list. By using this method, the image files of an + applications can also be located using the :meth:`tix_getimage` or + :meth:`tix_getbitmap` method. + + +.. method:: tixCommand.tix_filedialog([dlgclass]) + + Returns the file selection dialog that may be shared among different calls from + this application. This method will create a file selection dialog widget when + it is called the first time. This dialog will be returned by all subsequent + calls to :meth:`tix_filedialog`. An optional dlgclass parameter can be passed + as a string to specified what type of file selection dialog widget is desired. + Possible options are ``tix``, ``FileSelectDialog`` or ``tixExFileSelectDialog``. + + +.. method:: tixCommand.tix_getimage(self, name) + + Locates an image file of the name :file:`name.xpm`, :file:`name.xbm` or + :file:`name.ppm` in one of the bitmap directories (see the + :meth:`tix_addbitmapdir` method above). If more than one file with the same name + (but different extensions) exist, then the image type is chosen according to the + depth of the X display: xbm images are chosen on monochrome displays and color + images are chosen on color displays. By using :meth:`tix_getimage`, you can + avoid hard coding the pathnames of the image files in your application. When + successful, this method returns the name of the newly created image, which can + be used to configure the ``image`` option of the Tk and Tix widgets. + + +.. method:: tixCommand.tix_option_get(name) + + Gets the options maintained by the Tix scheme mechanism. + + +.. method:: tixCommand.tix_resetoptions(newScheme, newFontSet[, newScmPrio]) + + Resets the scheme and fontset of the Tix application to *newScheme* and + *newFontSet*, respectively. This affects only those widgets created after this + call. Therefore, it is best to call the resetoptions method before the creation + of any widgets in a Tix application. + + The optional parameter *newScmPrio* can be given to reset the priority level of + the Tk options set by the Tix schemes. + + Because of the way Tk handles the X option database, after Tix has been has + imported and inited, it is not possible to reset the color schemes and font sets + using the :meth:`tix_config` method. Instead, the :meth:`tix_resetoptions` + method must be used. Added: doctools/trunk/Doc-26/library/tk.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-26/library/tk.rst Thu Aug 2 17:44:40 2007 @@ -0,0 +1,40 @@ +.. _tkinter: + +********************************* +Graphical User Interfaces with Tk +********************************* + +.. index:: + single: GUI + single: Graphical User Interface + single: Tkinter + single: Tk + +Tk/Tcl has long been an integral part of Python. It provides a robust and +platform independent windowing toolkit, that is available to Python programmers +using the :mod:`Tkinter` module, and its extension, the :mod:`Tix` module. + +The :mod:`Tkinter` module is a thin object-oriented layer on top of Tcl/Tk. To +use :mod:`Tkinter`, you don't need to write Tcl code, but you will need to +consult the Tk documentation, and occasionally the Tcl documentation. +:mod:`Tkinter` is a set of wrappers that implement the Tk widgets as Python +classes. In addition, the internal module :mod:`_tkinter` provides a threadsafe +mechanism which allows Python and Tcl to interact. + +Tk is not the only GUI for Python; see section :ref:`other-gui-packages` for +more information on other GUI toolkits for Python. + +.. toctree:: + + tkinter.rst + tix.rst + scrolledtext.rst + turtle.rst + idle.rst + othergui.rst + +.. % Other sections I have in mind are +.. % Tkinter internals +.. % Freezing Tkinter applications + + Modified: doctools/trunk/Doc-26/library/tkinter.rst ============================================================================== --- doctools/trunk/Doc-26/library/tkinter.rst (original) +++ doctools/trunk/Doc-26/library/tkinter.rst Thu Aug 2 17:44:40 2007 @@ -1,38 +1,3 @@ - -.. _tkinter: - -********************************* -Graphical User Interfaces with Tk -********************************* - -.. index:: - single: GUI - single: Graphical User Interface - single: Tkinter - single: Tk - -Tk/Tcl has long been an integral part of Python. It provides a robust and -platform independent windowing toolkit, that is available to Python programmers -using the :mod:`Tkinter` module, and its extension, the :mod:`Tix` module. - -The :mod:`Tkinter` module is a thin object-oriented layer on top of Tcl/Tk. To -use :mod:`Tkinter`, you don't need to write Tcl code, but you will need to -consult the Tk documentation, and occasionally the Tcl documentation. -:mod:`Tkinter` is a set of wrappers that implement the Tk widgets as Python -classes. In addition, the internal module :mod:`_tkinter` provides a threadsafe -mechanism which allows Python and Tcl to interact. - -Tk is not the only GUI for Python; see section :ref:`other-gui-packages` for -more information on other GUI toolkits for Python. - -.. % Other sections I have in mind are -.. % Tkinter internals -.. % Freezing Tkinter applications - - -.. toctree:: - - :mod:`Tkinter` --- Python interface to Tcl/Tk ============================================= @@ -873,1024 +838,3 @@ deleted, the image data is deleted as well, and Tk will display an empty box wherever the image was used. - -:mod:`Tix` --- Extension widgets for Tk -======================================= - -.. module:: Tix - :synopsis: Tk Extension Widgets for Tkinter -.. sectionauthor:: Mike Clarkson - - -.. index:: single: Tix - -The :mod:`Tix` (Tk Interface Extension) module provides an additional rich set -of widgets. Although the standard Tk library has many useful widgets, they are -far from complete. The :mod:`Tix` library provides most of the commonly needed -widgets that are missing from standard Tk: :class:`HList`, :class:`ComboBox`, -:class:`Control` (a.k.a. SpinBox) and an assortment of scrollable widgets. -:mod:`Tix` also includes many more widgets that are generally useful in a wide -range of applications: :class:`NoteBook`, :class:`FileEntry`, -:class:`PanedWindow`, etc; there are more than 40 of them. - -With all these new widgets, you can introduce new interaction techniques into -applications, creating more useful and more intuitive user interfaces. You can -design your application by choosing the most appropriate widgets to match the -special needs of your application and users. - - -.. seealso:: - - `Tix Homepage `_ - The home page for :mod:`Tix`. This includes links to additional documentation - and downloads. - - `Tix Man Pages `_ - On-line version of the man pages and reference material. - - `Tix Programming Guide `_ - On-line version of the programmer's reference material. - - `Tix Development Applications `_ - Tix applications for development of Tix and Tkinter programs. Tide applications - work under Tk or Tkinter, and include :program:`TixInspect`, an inspector to - remotely modify and debug Tix/Tk/Tkinter applications. - - -Using Tix ---------- - - -.. class:: Tix(screenName[, baseName[, className]]) - - Toplevel widget of Tix which represents mostly the main window of an - application. It has an associated Tcl interpreter. - - Classes in the :mod:`Tix` module subclasses the classes in the :mod:`Tkinter` - module. The former imports the latter, so to use :mod:`Tix` with Tkinter, all - you need to do is to import one module. In general, you can just import - :mod:`Tix`, and replace the toplevel call to :class:`Tkinter.Tk` with - :class:`Tix.Tk`:: - - import Tix - from Tkconstants import * - root = Tix.Tk() - -To use :mod:`Tix`, you must have the :mod:`Tix` widgets installed, usually -alongside your installation of the Tk widgets. To test your installation, try -the following:: - - import Tix - root = Tix.Tk() - root.tk.eval('package require Tix') - -If this fails, you have a Tk installation problem which must be resolved before -proceeding. Use the environment variable :envvar:`TIX_LIBRARY` to point to the -installed :mod:`Tix` library directory, and make sure you have the dynamic -object library (:file:`tix8183.dll` or :file:`libtix8183.so`) in the same -directory that contains your Tk dynamic object library (:file:`tk8183.dll` or -:file:`libtk8183.so`). The directory with the dynamic object library should also -have a file called :file:`pkgIndex.tcl` (case sensitive), which contains the -line:: - - package ifneeded Tix 8.1 [list load "[file join $dir tix8183.dll]" Tix] - -.. % $ <-- bow to font-lock - - -Tix Widgets ------------ - -`Tix `_ -introduces over 40 widget classes to the :mod:`Tkinter` repertoire. There is a -demo of all the :mod:`Tix` widgets in the :file:`Demo/tix` directory of the -standard distribution. - -.. % The Python sample code is still being added to Python, hence commented out - - -Basic Widgets -^^^^^^^^^^^^^ - - -.. class:: Balloon() - - A `Balloon - `_ that - pops up over a widget to provide help. When the user moves the cursor inside a - widget to which a Balloon widget has been bound, a small pop-up window with a - descriptive message will be shown on the screen. - -.. % Python Demo of: -.. % \ulink{Balloon}{http://tix.sourceforge.net/dist/current/demos/samples/Balloon.tcl} - - -.. class:: ButtonBox() - - The `ButtonBox - `_ - widget creates a box of buttons, such as is commonly used for ``Ok Cancel``. - -.. % Python Demo of: -.. % \ulink{ButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/BtnBox.tcl} - - -.. class:: ComboBox() - - The `ComboBox - `_ - widget is similar to the combo box control in MS Windows. The user can select a - choice by either typing in the entry subwdget or selecting from the listbox - subwidget. - -.. % Python Demo of: -.. % \ulink{ComboBox}{http://tix.sourceforge.net/dist/current/demos/samples/ComboBox.tcl} - - -.. class:: Control() - - The `Control - `_ - widget is also known as the :class:`SpinBox` widget. The user can adjust the - value by pressing the two arrow buttons or by entering the value directly into - the entry. The new value will be checked against the user-defined upper and - lower limits. - -.. % Python Demo of: -.. % \ulink{Control}{http://tix.sourceforge.net/dist/current/demos/samples/Control.tcl} - - -.. class:: LabelEntry() - - The `LabelEntry - `_ - widget packages an entry widget and a label into one mega widget. It can be used - be used to simplify the creation of "entry-form" type of interface. - -.. % Python Demo of: -.. % \ulink{LabelEntry}{http://tix.sourceforge.net/dist/current/demos/samples/LabEntry.tcl} - - -.. class:: LabelFrame() - - The `LabelFrame - `_ - widget packages a frame widget and a label into one mega widget. To create - widgets inside a LabelFrame widget, one creates the new widgets relative to the - :attr:`frame` subwidget and manage them inside the :attr:`frame` subwidget. - -.. % Python Demo of: -.. % \ulink{LabelFrame}{http://tix.sourceforge.net/dist/current/demos/samples/LabFrame.tcl} - - -.. class:: Meter() - - The `Meter - `_ widget - can be used to show the progress of a background job which may take a long time - to execute. - -.. % Python Demo of: -.. % \ulink{Meter}{http://tix.sourceforge.net/dist/current/demos/samples/Meter.tcl} - - -.. class:: OptionMenu() - - The `OptionMenu - `_ - creates a menu button of options. - -.. % Python Demo of: -.. % \ulink{OptionMenu}{http://tix.sourceforge.net/dist/current/demos/samples/OptMenu.tcl} - - -.. class:: PopupMenu() - - The `PopupMenu - `_ - widget can be used as a replacement of the ``tk_popup`` command. The advantage - of the :mod:`Tix` :class:`PopupMenu` widget is it requires less application code - to manipulate. - -.. % Python Demo of: -.. % \ulink{PopupMenu}{http://tix.sourceforge.net/dist/current/demos/samples/PopMenu.tcl} - - -.. class:: Select() - - The `Select - `_ widget - is a container of button subwidgets. It can be used to provide radio-box or - check-box style of selection options for the user. - -.. % Python Demo of: -.. % \ulink{Select}{http://tix.sourceforge.net/dist/current/demos/samples/Select.tcl} - - -.. class:: StdButtonBox() - - The `StdButtonBox - `_ - widget is a group of standard buttons for Motif-like dialog boxes. - -.. % Python Demo of: -.. % \ulink{StdButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/StdBBox.tcl} - - -File Selectors -^^^^^^^^^^^^^^ - - -.. class:: DirList() - - The `DirList - `_ - widget displays a list view of a directory, its previous directories and its - sub-directories. The user can choose one of the directories displayed in the - list or change to another directory. - -.. % Python Demo of: -.. % \ulink{DirList}{http://tix.sourceforge.net/dist/current/demos/samples/DirList.tcl} - - -.. class:: DirTree() - - The `DirTree - `_ - widget displays a tree view of a directory, its previous directories and its - sub-directories. The user can choose one of the directories displayed in the - list or change to another directory. - -.. % Python Demo of: -.. % \ulink{DirTree}{http://tix.sourceforge.net/dist/current/demos/samples/DirTree.tcl} - - -.. class:: DirSelectDialog() - - The `DirSelectDialog - `_ - widget presents the directories in the file system in a dialog window. The user - can use this dialog window to navigate through the file system to select the - desired directory. - -.. % Python Demo of: -.. % \ulink{DirSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/DirDlg.tcl} - - -.. class:: DirSelectBox() - - The :class:`DirSelectBox` is similar to the standard Motif(TM) directory- - selection box. It is generally used for the user to choose a directory. - DirSelectBox stores the directories mostly recently selected into a ComboBox - widget so that they can be quickly selected again. - - -.. class:: ExFileSelectBox() - - The `ExFileSelectBox - `_ - widget is usually embedded in a tixExFileSelectDialog widget. It provides an - convenient method for the user to select files. The style of the - :class:`ExFileSelectBox` widget is very similar to the standard file dialog on - MS Windows 3.1. - -.. % Python Demo of: -.. % \ulink{ExFileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/EFileDlg.tcl} - - -.. class:: FileSelectBox() - - The `FileSelectBox - `_ - is similar to the standard Motif(TM) file-selection box. It is generally used - for the user to choose a file. FileSelectBox stores the files mostly recently - selected into a :class:`ComboBox` widget so that they can be quickly selected - again. - -.. % Python Demo of: -.. % \ulink{FileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/FileDlg.tcl} - - -.. class:: FileEntry() - - The `FileEntry - `_ - widget can be used to input a filename. The user can type in the filename - manually. Alternatively, the user can press the button widget that sits next to - the entry, which will bring up a file selection dialog. - -.. % Python Demo of: -.. % \ulink{FileEntry}{http://tix.sourceforge.net/dist/current/demos/samples/FileEnt.tcl} - - -Hierachical ListBox -^^^^^^^^^^^^^^^^^^^ - - -.. class:: HList() - - The `HList - `_ widget - can be used to display any data that have a hierarchical structure, for example, - file system directory trees. The list entries are indented and connected by - branch lines according to their places in the hierarchy. - -.. % Python Demo of: -.. % \ulink{HList}{http://tix.sourceforge.net/dist/current/demos/samples/HList1.tcl} - - -.. class:: CheckList() - - The `CheckList - `_ - widget displays a list of items to be selected by the user. CheckList acts - similarly to the Tk checkbutton or radiobutton widgets, except it is capable of - handling many more items than checkbuttons or radiobuttons. - -.. % Python Demo of: -.. % \ulink{ CheckList}{http://tix.sourceforge.net/dist/current/demos/samples/ChkList.tcl} -.. % Python Demo of: -.. % \ulink{ScrolledHList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList.tcl} -.. % Python Demo of: -.. % \ulink{ScrolledHList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList2.tcl} - - -.. class:: Tree() - - The `Tree - `_ widget - can be used to display hierarchical data in a tree form. The user can adjust the - view of the tree by opening or closing parts of the tree. - -.. % Python Demo of: -.. % \ulink{Tree}{http://tix.sourceforge.net/dist/current/demos/samples/Tree.tcl} -.. % Python Demo of: -.. % \ulink{Tree (Dynamic)}{http://tix.sourceforge.net/dist/current/demos/samples/DynTree.tcl} - - -Tabular ListBox -^^^^^^^^^^^^^^^ - - -.. class:: TList() - - The `TList - `_ widget - can be used to display data in a tabular format. The list entries of a - :class:`TList` widget are similar to the entries in the Tk listbox widget. The - main differences are (1) the :class:`TList` widget can display the list entries - in a two dimensional format and (2) you can use graphical images as well as - multiple colors and fonts for the list entries. - -.. % Python Demo of: -.. % \ulink{ScrolledTList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/STList1.tcl} -.. % Python Demo of: -.. % \ulink{ScrolledTList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/STList2.tcl} -.. % Grid has yet to be added to Python -.. % \subsubsection{Grid Widget} -.. % Python Demo of: -.. % \ulink{Simple Grid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid0.tcl} -.. % Python Demo of: -.. % \ulink{ScrolledGrid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid1.tcl} -.. % Python Demo of: -.. % \ulink{Editable Grid}{http://tix.sourceforge.net/dist/current/demos/samples/EditGrid.tcl} - - -Manager Widgets -^^^^^^^^^^^^^^^ - - -.. class:: PanedWindow() - - The `PanedWindow - `_ - widget allows the user to interactively manipulate the sizes of several panes. - The panes can be arranged either vertically or horizontally. The user changes - the sizes of the panes by dragging the resize handle between two panes. - -.. % Python Demo of: -.. % \ulink{PanedWindow}{http://tix.sourceforge.net/dist/current/demos/samples/PanedWin.tcl} - - -.. class:: ListNoteBook() - - The `ListNoteBook - `_ - widget is very similar to the :class:`TixNoteBook` widget: it can be used to - display many windows in a limited space using a notebook metaphor. The notebook - is divided into a stack of pages (windows). At one time only one of these pages - can be shown. The user can navigate through these pages by choosing the name of - the desired page in the :attr:`hlist` subwidget. - -.. % Python Demo of: -.. % \ulink{ListNoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/ListNBK.tcl} - - -.. class:: NoteBook() - - The `NoteBook - `_ - widget can be used to display many windows in a limited space using a notebook - metaphor. The notebook is divided into a stack of pages. At one time only one of - these pages can be shown. The user can navigate through these pages by choosing - the visual "tabs" at the top of the NoteBook widget. - -.. % Python Demo of: -.. % \ulink{NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/NoteBook.tcl} - -.. % \subsubsection{Scrolled Widgets} -.. % Python Demo of: -.. % \ulink{ScrolledListBox}{http://tix.sourceforge.net/dist/current/demos/samples/SListBox.tcl} -.. % Python Demo of: -.. % \ulink{ScrolledText}{http://tix.sourceforge.net/dist/current/demos/samples/SText.tcl} -.. % Python Demo of: -.. % \ulink{ScrolledWindow}{http://tix.sourceforge.net/dist/current/demos/samples/SWindow.tcl} -.. % Python Demo of: -.. % \ulink{Canvas Object View}{http://tix.sourceforge.net/dist/current/demos/samples/CObjView.tcl} - - -Image Types -^^^^^^^^^^^ - -The :mod:`Tix` module adds: - -* `pixmap `_ - capabilities to all :mod:`Tix` and :mod:`Tkinter` widgets to create color images - from XPM files. - - .. % Python Demo of: - .. % \ulink{XPM Image In Button}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm.tcl} - .. % Python Demo of: - .. % \ulink{XPM Image In Menu}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm1.tcl} - -* `Compound - `_ image - types can be used to create images that consists of multiple horizontal lines; - each line is composed of a series of items (texts, bitmaps, images or spaces) - arranged from left to right. For example, a compound image can be used to - display a bitmap and a text string simultaneously in a Tk :class:`Button` - widget. - - .. % Python Demo of: - .. % \ulink{Compound Image In Buttons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg.tcl} - .. % Python Demo of: - .. % \ulink{Compound Image In NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg2.tcl} - .. % Python Demo of: - .. % \ulink{Compound Image Notebook Color Tabs}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg4.tcl} - .. % Python Demo of: - .. % \ulink{Compound Image Icons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg3.tcl} - - -Miscellaneous Widgets -^^^^^^^^^^^^^^^^^^^^^ - - -.. class:: InputOnly() - - The `InputOnly - `_ - widgets are to accept inputs from the user, which can be done with the ``bind`` - command (Unix only). - - -Form Geometry Manager -^^^^^^^^^^^^^^^^^^^^^ - -In addition, :mod:`Tix` augments :mod:`Tkinter` by providing: - - -.. class:: Form() - - The `Form - `_ geometry - manager based on attachment rules for all Tk widgets. - -.. % begin{latexonly} -.. % \subsection{Tix Class Structure} -.. % -.. % \begin{figure}[hbtp] -.. % \centerline{\epsfig{file=hierarchy.png,width=.9\textwidth}} -.. % \vspace{.5cm} -.. % \caption{The Class Hierarchy of Tix Widgets} -.. % \end{figure} -.. % end{latexonly} - - -Tix Commands ------------- - - -.. class:: tixCommand() - - The `tix commands - `_ provide - access to miscellaneous elements of :mod:`Tix`'s internal state and the - :mod:`Tix` application context. Most of the information manipulated by these - methods pertains to the application as a whole, or to a screen or display, - rather than to a particular window. - - To view the current settings, the common usage is:: - - import Tix - root = Tix.Tk() - print root.tix_configure() - - -.. method:: tixCommand.tix_configure([cnf,] **kw) - - Query or modify the configuration options of the Tix application context. If no - option is specified, returns a dictionary all of the available options. If - option is specified with no value, then the method returns a list describing the - one named option (this list will be identical to the corresponding sublist of - the value returned if no option is specified). If one or more option-value - pairs are specified, then the method modifies the given option(s) to have the - given value(s); in this case the method returns an empty string. Option may be - any of the configuration options. - - -.. method:: tixCommand.tix_cget(option) - - Returns the current value of the configuration option given by *option*. Option - may be any of the configuration options. - - -.. method:: tixCommand.tix_getbitmap(name) - - Locates a bitmap file of the name ``name.xpm`` or ``name`` in one of the bitmap - directories (see the :meth:`tix_addbitmapdir` method). By using - :meth:`tix_getbitmap`, you can avoid hard coding the pathnames of the bitmap - files in your application. When successful, it returns the complete pathname of - the bitmap file, prefixed with the character ``@``. The returned value can be - used to configure the ``bitmap`` option of the Tk and Tix widgets. - - -.. method:: tixCommand.tix_addbitmapdir(directory) - - Tix maintains a list of directories under which the :meth:`tix_getimage` and - :meth:`tix_getbitmap` methods will search for image files. The standard bitmap - directory is :file:`$TIX_LIBRARY/bitmaps`. The :meth:`tix_addbitmapdir` method - adds *directory* into this list. By using this method, the image files of an - applications can also be located using the :meth:`tix_getimage` or - :meth:`tix_getbitmap` method. - - -.. method:: tixCommand.tix_filedialog([dlgclass]) - - Returns the file selection dialog that may be shared among different calls from - this application. This method will create a file selection dialog widget when - it is called the first time. This dialog will be returned by all subsequent - calls to :meth:`tix_filedialog`. An optional dlgclass parameter can be passed - as a string to specified what type of file selection dialog widget is desired. - Possible options are ``tix``, ``FileSelectDialog`` or ``tixExFileSelectDialog``. - - -.. method:: tixCommand.tix_getimage(self, name) - - Locates an image file of the name :file:`name.xpm`, :file:`name.xbm` or - :file:`name.ppm` in one of the bitmap directories (see the - :meth:`tix_addbitmapdir` method above). If more than one file with the same name - (but different extensions) exist, then the image type is chosen according to the - depth of the X display: xbm images are chosen on monochrome displays and color - images are chosen on color displays. By using :meth:`tix_getimage`, you can - avoid hard coding the pathnames of the image files in your application. When - successful, this method returns the name of the newly created image, which can - be used to configure the ``image`` option of the Tk and Tix widgets. - - -.. method:: tixCommand.tix_option_get(name) - - Gets the options maintained by the Tix scheme mechanism. - - -.. method:: tixCommand.tix_resetoptions(newScheme, newFontSet[, newScmPrio]) - - Resets the scheme and fontset of the Tix application to *newScheme* and - *newFontSet*, respectively. This affects only those widgets created after this - call. Therefore, it is best to call the resetoptions method before the creation - of any widgets in a Tix application. - - The optional parameter *newScmPrio* can be given to reset the priority level of - the Tk options set by the Tix schemes. - - Because of the way Tk handles the X option database, after Tix has been has - imported and inited, it is not possible to reset the color schemes and font sets - using the :meth:`tix_config` method. Instead, the :meth:`tix_resetoptions` - method must be used. - - -:mod:`ScrolledText` --- Scrolled Text Widget -============================================ - -.. module:: ScrolledText - :platform: Tk - :synopsis: Text widget with a vertical scroll bar. -.. sectionauthor:: Fred L. Drake, Jr. - - -The :mod:`ScrolledText` module provides a class of the same name which -implements a basic text widget which has a vertical scroll bar configured to do -the "right thing." Using the :class:`ScrolledText` class is a lot easier than -setting up a text widget and scroll bar directly. The constructor is the same -as that of the :class:`Tkinter.Text` class. - -The text widget and scrollbar are packed together in a :class:`Frame`, and the -methods of the :class:`Grid` and :class:`Pack` geometry managers are acquired -from the :class:`Frame` object. This allows the :class:`ScrolledText` widget to -be used directly to achieve most normal geometry management behavior. - -Should more specific control be necessary, the following attributes are -available: - - -.. attribute:: ScrolledText.frame - - The frame which surrounds the text and scroll bar widgets. - - -.. attribute:: ScrolledText.vbar - - The scroll bar widget. - -XXX: input{libturtle} :XXX - -.. _idle: - -Idle -==== - -.. moduleauthor:: Guido van Rossum - - -.. % \declaremodule{standard}{idle} -.. % \modulesynopsis{A Python Integrated Development Environment} - -.. index:: - single: Idle - single: Python Editor - single: Integrated Development Environment - -Idle is the Python IDE built with the :mod:`Tkinter` GUI toolkit. - -IDLE has the following features: - -* coded in 100% pure Python, using the :mod:`Tkinter` GUI toolkit - -* cross-platform: works on Windows and Unix (on Mac OS, there are currently - problems with Tcl/Tk) - -* multi-window text editor with multiple undo, Python colorizing and many other - features, e.g. smart indent and call tips - -* Python shell window (a.k.a. interactive interpreter) - -* debugger (not complete, but you can set breakpoints, view and step) - - -Menus ------ - - -File menu -^^^^^^^^^ - -New window - create a new editing window - -Open... - open an existing file - -Open module... - open an existing module (searches sys.path) - -Class browser - show classes and methods in current file - -Path browser - show sys.path directories, modules, classes and methods - -.. index:: - single: Class browser - single: Path browser - -Save - save current window to the associated file (unsaved windows have a \* before and - after the window title) - -Save As... - save current window to new file, which becomes the associated file - -Save Copy As... - save current window to different file without changing the associated file - -Close - close current window (asks to save if unsaved) - -Exit - close all windows and quit IDLE (asks to save if unsaved) - - -Edit menu -^^^^^^^^^ - -Undo - Undo last change to current window (max 1000 changes) - -Redo - Redo last undone change to current window - -Cut - Copy selection into system-wide clipboard; then delete selection - -Copy - Copy selection into system-wide clipboard - -Paste - Insert system-wide clipboard into window - -Select All - Select the entire contents of the edit buffer - -Find... - Open a search dialog box with many options - -Find again - Repeat last search - -Find selection - Search for the string in the selection - -Find in Files... - Open a search dialog box for searching files - -Replace... - Open a search-and-replace dialog box - -Go to line - Ask for a line number and show that line - -Indent region - Shift selected lines right 4 spaces - -Dedent region - Shift selected lines left 4 spaces - -Comment out region - Insert ## in front of selected lines - -Uncomment region - Remove leading # or ## from selected lines - -Tabify region - Turns *leading* stretches of spaces into tabs - -Untabify region - Turn *all* tabs into the right number of spaces - -Expand word - Expand the word you have typed to match another word in the same buffer; repeat - to get a different expansion - -Format Paragraph - Reformat the current blank-line-separated paragraph - -Import module - Import or reload the current module - -Run script - Execute the current file in the __main__ namespace - -.. index:: - single: Import module - single: Run script - - -Windows menu -^^^^^^^^^^^^ - -Zoom Height - toggles the window between normal size (24x80) and maximum height. - -The rest of this menu lists the names of all open windows; select one to bring -it to the foreground (deiconifying it if necessary). - - -Debug menu (in the Python Shell window only) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Go to file/line - look around the insert point for a filename and linenumber, open the file, and - show the line. - -Open stack viewer - show the stack traceback of the last exception - -Debugger toggle - Run commands in the shell under the debugger - -JIT Stack viewer toggle - Open stack viewer on traceback - -.. index:: - single: stack viewer - single: debugger - - -Basic editing and navigation ----------------------------- - -* :kbd:`Backspace` deletes to the left; :kbd:`Del` deletes to the right - -* Arrow keys and :kbd:`Page Up`/:kbd:`Page Down` to move around - -* :kbd:`Home`/:kbd:`End` go to begin/end of line - -* :kbd:`C-Home`/:kbd:`C-End` go to begin/end of file - -* Some :program:`Emacs` bindings may also work, including :kbd:`C-B`, - :kbd:`C-P`, :kbd:`C-A`, :kbd:`C-E`, :kbd:`C-D`, :kbd:`C-L` - - -Automatic indentation -^^^^^^^^^^^^^^^^^^^^^ - -After a block-opening statement, the next line is indented by 4 spaces (in the -Python Shell window by one tab). After certain keywords (break, return etc.) -the next line is dedented. In leading indentation, :kbd:`Backspace` deletes up -to 4 spaces if they are there. :kbd:`Tab` inserts 1-4 spaces (in the Python -Shell window one tab). See also the indent/dedent region commands in the edit -menu. - - -Python Shell window -^^^^^^^^^^^^^^^^^^^ - -* :kbd:`C-C` interrupts executing command - -* :kbd:`C-D` sends end-of-file; closes window if typed at a ``>>>`` prompt - -* :kbd:`Alt-p` retrieves previous command matching what you have typed - -* :kbd:`Alt-n` retrieves next - -* :kbd:`Return` while on any previous command retrieves that command - -* :kbd:`Alt-/` (Expand word) is also useful here - -.. index:: single: indentation - - -Syntax colors -------------- - -The coloring is applied in a background "thread," so you may occasionally see -uncolorized text. To change the color scheme, edit the ``[Colors]`` section in -:file:`config.txt`. - -Python syntax colors: - Keywords - orange - - Strings - green - - Comments - red - - Definitions - blue - -Shell colors: - Console output - brown - - stdout - blue - - stderr - dark green - - stdin - black - - -Command line usage -^^^^^^^^^^^^^^^^^^ - -:: - - idle.py [-c command] [-d] [-e] [-s] [-t title] [arg] ... - - -c command run this command - -d enable debugger - -e edit mode; arguments are files to be edited - -s run $IDLESTARTUP or $PYTHONSTARTUP first - -t title set title of shell window - -If there are arguments: - -#. If :option:`-e` is used, arguments are files opened for editing and - ``sys.argv`` reflects the arguments passed to IDLE itself. - -#. Otherwise, if :option:`-c` is used, all arguments are placed in - ``sys.argv[1:...]``, with ``sys.argv[0]`` set to ``'-c'``. - -#. Otherwise, if neither :option:`-e` nor :option:`-c` is used, the first - argument is a script which is executed with the remaining arguments in - ``sys.argv[1:...]`` and ``sys.argv[0]`` set to the script name. If the script - name is '-', no script is executed but an interactive Python session is started; - the arguments are still available in ``sys.argv``. - - -.. _other-gui-packages: - -Other Graphical User Interface Packages -======================================= - -There are an number of extension widget sets to :mod:`Tkinter`. - - -.. seealso:: - - `Python megawidgets `_ - is a toolkit for building high-level compound widgets in Python using the - :mod:`Tkinter` module. It consists of a set of base classes and a library of - flexible and extensible megawidgets built on this foundation. These megawidgets - include notebooks, comboboxes, selection widgets, paned widgets, scrolled - widgets, dialog windows, etc. Also, with the Pmw.Blt interface to BLT, the - busy, graph, stripchart, tabset and vector commands are be available. - - The initial ideas for Pmw were taken from the Tk ``itcl`` extensions ``[incr - Tk]`` by Michael McLennan and ``[incr Widgets]`` by Mark Ulferts. Several of the - megawidgets are direct translations from the itcl to Python. It offers most of - the range of widgets that ``[incr Widgets]`` does, and is almost as complete as - Tix, lacking however Tix's fast :class:`HList` widget for drawing trees. - - `Tkinter3000 Widget Construction Kit (WCK) `_ - is a library that allows you to write new Tkinter widgets in pure Python. The - WCK framework gives you full control over widget creation, configuration, screen - appearance, and event handling. WCK widgets can be very fast and light-weight, - since they can operate directly on Python data structures, without having to - transfer data through the Tk/Tcl layer. - - .. % - -Other GUI packages are also available for Python: - - -.. seealso:: - - `wxPython `_ - wxPython is a cross-platform GUI toolkit for Python that is built around the - popular `wxWidgets `_ C++ toolkit. ?It provides a - native look and feel for applications on Windows, Mac OS X, and Unix systems by - using each platform's native widgets where ever possible, (GTK+ on Unix-like - systems). ?In addition to an extensive set of widgets, wxPython provides classes - for online documentation and context sensitive help, printing, HTML viewing, - low-level device context drawing, drag and drop, system clipboard access, an - XML-based resource format and more, including an ever growing library of user- - contributed modules. ?Both the wxWidgets and wxPython projects are under active - development and continuous improvement, and have active and helpful user and - developer communities. - - `wxPython in Action `_ - The wxPython book, by Noel Rappin and Robin Dunn. - - PyQt - PyQt is a :program:`sip`\ -wrapped binding to the Qt toolkit. Qt is an - extensive C++ GUI toolkit that is available for Unix, Windows and Mac OS X. - :program:`sip` is a tool for generating bindings for C++ libraries as Python - classes, and is specifically designed for Python. An online manual is available - at http://www.opendocspublishing.com/pyqt/ (errata are located at - http://www.valdyas.org/python/book.html). - - `PyKDE `_ - PyKDE is a :program:`sip`\ -wrapped interface to the KDE desktop libraries. KDE - is a desktop environment for Unix computers; the graphical components are based - on Qt. - - `FXPy `_ - is a Python extension module which provides an interface to the `FOX - `_ GUI. FOX is a C++ based Toolkit for - developing Graphical User Interfaces easily and effectively. It offers a wide, - and growing, collection of Controls, and provides state of the art facilities - such as drag and drop, selection, as well as OpenGL widgets for 3D graphical - manipulation. FOX also implements icons, images, and user-convenience features - such as status line help, and tooltips. - - Even though FOX offers a large collection of controls already, FOX leverages C++ - to allow programmers to easily build additional Controls and GUI elements, - simply by taking existing controls, and creating a derived class which simply - adds or redefines the desired behavior. - - `PyGTK `_ - is a set of bindings for the `GTK `_ widget set. It - provides an object oriented interface that is slightly higher level than the C - one. It automatically does all the type casting and reference counting that you - would have to do normally with the C API. There are also `bindings - `_ to `GNOME `_, and - a `tutorial - `_ is - available. - -.. % XXX Reference URLs that compare the different UI packages - Modified: doctools/trunk/Doc-26/library/xml.dom.minidom.rst ============================================================================== --- doctools/trunk/Doc-26/library/xml.dom.minidom.rst (original) +++ doctools/trunk/Doc-26/library/xml.dom.minidom.rst Thu Aug 2 17:44:40 2007 @@ -108,7 +108,7 @@ The W3C recommendation for the DOM supported by :mod:`xml.dom.minidom`. -.. _dom-objects: +.. _minidom-objects: DOM Objects ----------- Modified: doctools/trunk/Doc-26/reference/compound_stmts.rst ============================================================================== --- doctools/trunk/Doc-26/reference/compound_stmts.rst (original) +++ doctools/trunk/Doc-26/reference/compound_stmts.rst Thu Aug 2 17:44:40 2007 @@ -272,7 +272,7 @@ assigned to three variables in the :mod:`sys` module: ``sys.exc_type`` receives the object identifying the exception; ``sys.exc_value`` receives the exception's parameter; ``sys.exc_traceback`` receives a traceback object (see section -:ref:`traceback`) identifying the point in the program where the exception +:ref:`types`) identifying the point in the program where the exception occurred. These details are also available through the :func:`sys.exc_info` function, which returns a tuple ``(exc_type, exc_value, exc_traceback)``. Use of the corresponding variables is deprecated in favor of this function, since Modified: doctools/trunk/Doc-26/reference/datamodel.rst ============================================================================== --- doctools/trunk/Doc-26/reference/datamodel.rst (original) +++ doctools/trunk/Doc-26/reference/datamodel.rst Thu Aug 2 17:44:40 2007 @@ -988,8 +988,6 @@ can implement a Jump command (aka Set Next Statement) by writing to f_lineno. Traceback objects - .. _traceback: - .. index:: object: traceback pair: stack; trace Modified: doctools/trunk/Doc-26/reference/simple_stmts.rst ============================================================================== --- doctools/trunk/Doc-26/reference/simple_stmts.rst (original) +++ doctools/trunk/Doc-26/reference/simple_stmts.rst Thu Aug 2 17:44:40 2007 @@ -563,7 +563,7 @@ .. index:: object: traceback If a third object is present and not ``None``, it must be a traceback object -(see section :ref:`traceback`), and it is substituted instead of the current +(see section :ref:`types`), and it is substituted instead of the current location as the place where the exception occurred. If the third object is present and not a traceback object or ``None``, a :exc:`TypeError` exception is raised. The three-expression form of :keyword:`raise` is useful to re-raise an Modified: doctools/trunk/Doc-3k/TODO ============================================================================== --- doctools/trunk/Doc-3k/TODO (original) +++ doctools/trunk/Doc-3k/TODO Thu Aug 2 17:44:40 2007 @@ -2,7 +2,6 @@ ====================== * fix all references and links marked with `XXX` -* fix all duplicate labels and undefined label references * split very large files and add toctrees * integrate standalone HOWTOs * find out which files get "comments disabled" metadata Modified: doctools/trunk/Doc-3k/c-api/concrete.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/concrete.rst (original) +++ doctools/trunk/Doc-3k/c-api/concrete.rst Thu Aug 2 17:44:40 2007 @@ -3051,7 +3051,7 @@ .. versionadded:: 2.3 -.. _weakref-objects: +.. _weakrefobjects: Weak Reference Objects ---------------------- @@ -3285,7 +3285,7 @@ *NULL*. -.. _datetime-objects: +.. _datetimeobjects: DateTime Objects ---------------- Modified: doctools/trunk/Doc-3k/c-api/intro.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/intro.rst (original) +++ doctools/trunk/Doc-3k/c-api/intro.rst Thu Aug 2 17:44:40 2007 @@ -1,7 +1,7 @@ .. highlightlang:: c -.. _intro: +.. _api-intro: ************ Introduction @@ -30,7 +30,7 @@ application. -.. _includes: +.. _api-includes: Include Files ============= @@ -80,7 +80,7 @@ is no need to do anything special to use the API from C++. -.. _objects: +.. _api-objects: Objects, Types and Reference Counts =================================== @@ -107,7 +107,7 @@ pointed to by *a* is a Python list. -.. _refcounts: +.. _api-refcounts: Reference Counts ---------------- @@ -170,7 +170,7 @@ they are done with the result; this soon becomes second nature. -.. _refcountdetails: +.. _api-refcountdetails: Reference Count Details ^^^^^^^^^^^^^^^^^^^^^^^ @@ -335,7 +335,7 @@ .. index:: single: sum_sequence() -.. _types: +.. _api-types: Types ----- @@ -349,7 +349,7 @@ use them. -.. _exceptions: +.. _api-exceptions: Exceptions ========== @@ -496,7 +496,7 @@ the final call made is successful. -.. _embedding: +.. _api-embedding: Embedding Python ================ @@ -520,8 +520,6 @@ :mod:`__builtin__`, :mod:`__main__`, :mod:`sys`, and :mod:`exceptions`. It also initializes the module search path (``sys.path``). -.. % - .. index:: single: PySys_SetArgv() :cfunc:`Py_Initialize` does not set the "script argument list" (``sys.argv``). @@ -574,7 +572,7 @@ allocated by extension modules currently cannot be released. -.. _debugging: +.. _api-debugging: Debugging Builds ================ Modified: doctools/trunk/Doc-3k/conf.py ============================================================================== --- doctools/trunk/Doc-3k/conf.py (original) +++ doctools/trunk/Doc-3k/conf.py Thu Aug 2 17:44:40 2007 @@ -34,6 +34,7 @@ 'whatsnew/2.6.rst', 'maclib/scrap.rst', 'library/xmllib.rst', + 'library/xml.etree.rst', ] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, Modified: doctools/trunk/Doc-3k/distutils/apiref.rst ============================================================================== --- doctools/trunk/Doc-3k/distutils/apiref.rst (original) +++ doctools/trunk/Doc-3k/distutils/apiref.rst Thu Aug 2 17:44:40 2007 @@ -1415,7 +1415,118 @@ Also provides :func:`find_executable` to search the path for a given executable name. -XXX: input{sysconfig} :XXX + +:mod:`distutils.sysconfig` --- System configuration information +=============================================================== + +.. module:: distutils.sysconfig + :synopsis: Low-level access to configuration information of the Python interpreter. +.. moduleauthor:: Fred L. Drake, Jr. +.. moduleauthor:: Greg Ward +.. sectionauthor:: Fred L. Drake, Jr. + + +The :mod:`distutils.sysconfig` module provides access to Python's low-level +configuration information. The specific configuration variables available +depend heavily on the platform and configuration. The specific variables depend +on the build process for the specific version of Python being run; the variables +are those found in the :file:`Makefile` and configuration header that are +installed with Python on Unix systems. The configuration header is called +:file:`pyconfig.h` for Python versions starting with 2.2, and :file:`config.h` +for earlier versions of Python. + +Some additional functions are provided which perform some useful manipulations +for other parts of the :mod:`distutils` package. + + +.. data:: PREFIX + + The result of ``os.path.normpath(sys.prefix)``. + + +.. data:: EXEC_PREFIX + + The result of ``os.path.normpath(sys.exec_prefix)``. + + +.. function:: get_config_var(name) + + Return the value of a single variable. This is equivalent to + ``get_config_vars().get(name)``. + + +.. function:: get_config_vars(...) + + Return a set of variable definitions. If there are no arguments, this returns a + dictionary mapping names of configuration variables to values. If arguments are + provided, they should be strings, and the return value will be a sequence giving + the associated values. If a given name does not have a corresponding value, + ``None`` will be included for that variable. + + +.. function:: get_config_h_filename() + + Return the full path name of the configuration header. For Unix, this will be + the header generated by the :program:`configure` script; for other platforms the + header will have been supplied directly by the Python source distribution. The + file is a platform-specific text file. + + +.. function:: get_makefile_filename() + + Return the full path name of the :file:`Makefile` used to build Python. For + Unix, this will be a file generated by the :program:`configure` script; the + meaning for other platforms will vary. The file is a platform-specific text + file, if it exists. This function is only useful on POSIX platforms. + + +.. function:: get_python_inc([plat_specific[, prefix]]) + + Return the directory for either the general or platform-dependent C include + files. If *plat_specific* is true, the platform-dependent include directory is + returned; if false or omitted, the platform-independent directory is returned. + If *prefix* is given, it is used as either the prefix instead of + :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if + *plat_specific* is true. + + +.. function:: get_python_lib([plat_specific[, standard_lib[, prefix]]]) + + Return the directory for either the general or platform-dependent library + installation. If *plat_specific* is true, the platform-dependent include + directory is returned; if false or omitted, the platform-independent directory + is returned. If *prefix* is given, it is used as either the prefix instead of + :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if + *plat_specific* is true. If *standard_lib* is true, the directory for the + standard library is returned rather than the directory for the installation of + third-party extensions. + +The following function is only intended for use within the :mod:`distutils` +package. + + +.. function:: customize_compiler(compiler) + + Do any platform-specific customization of a + :class:`distutils.ccompiler.CCompiler` instance. + + This function is only needed on Unix at this time, but should be called + consistently to support forward-compatibility. It inserts the information that + varies across Unix flavors and is stored in Python's :file:`Makefile`. This + information includes the selected compiler, compiler and linker options, and the + extension used by the linker for shared objects. + +This function is even more special-purpose, and should only be used from +Python's own build procedures. + + +.. function:: set_python_build() + + Inform the :mod:`distutils.sysconfig` module that it is being used as part of + the build process for Python. This changes a lot of relative locations for + files, allowing them to be located in the build area rather than in an installed + Python. + :mod:`distutils.text_file` --- The TextFile class ================================================= @@ -1870,20 +1981,3 @@ *sub_commands* is usually defined at the \*end\* of a class, because predicates can be unbound methods, so they must already have been defined. The canonical example is the :command:`install` command. - -.. % -.. % The ugly "%begin{latexonly}" pseudo-environments are really just to -.. % keep LaTeX2HTML quiet during the \renewcommand{} macros; they're -.. % not really valuable. -.. % -.. % begin{latexonly} -.. % end{latexonly} - -XXX: input{moddist.ind} :XXX -.. % Module Index -.. % begin{latexonly} -.. % end{latexonly} - -XXX: input{dist.ind} :XXX -.. % Index - Modified: doctools/trunk/Doc-3k/distutils/introduction.rst ============================================================================== --- doctools/trunk/Doc-3k/distutils/introduction.rst (original) +++ doctools/trunk/Doc-3k/distutils/introduction.rst Thu Aug 2 17:44:40 2007 @@ -1,4 +1,4 @@ -.. _intro: +.. _distutils-intro: **************************** An Introduction to Distutils @@ -10,7 +10,7 @@ Python Modules (XXX reference: ../inst/inst.html) manual. -.. _concepts: +.. _distutils-concepts: Concepts & Terminology ====================== @@ -41,7 +41,7 @@ code. -.. _simple-example: +.. _distutils-simple-example: A Simple Example ================ Modified: doctools/trunk/Doc-3k/distutils/setupscript.rst ============================================================================== --- doctools/trunk/Doc-3k/distutils/setupscript.rst (original) +++ doctools/trunk/Doc-3k/distutils/setupscript.rst Thu Aug 2 17:44:40 2007 @@ -8,7 +8,7 @@ installing modules using the Distutils. The main purpose of the setup script is to describe your module distribution to the Distutils, so that the various commands that operate on your modules do the right thing. As we saw in section -:ref:`simple-example` above, the setup script consists mainly of a call to +:ref:`distutils-simple-example` above, the setup script consists mainly of a call to :func:`setup`, and most information supplied to the Distutils by the module developer is supplied as keyword arguments to :func:`setup`. @@ -33,7 +33,7 @@ ) There are only two differences between this and the trivial one-file -distribution presented in section :ref:`simple-example`: more metadata, and the +distribution presented in section :ref:`distutils-simple-example`: more metadata, and the specification of pure Python modules by package, rather than by module. This is important since the Distutils consist of a couple of dozen modules split into (so far) two packages; an explicit list of every module would be tedious to @@ -114,7 +114,7 @@ For a small module distribution, you might prefer to list all modules rather than listing packages---especially the case of a single module that goes in the "root package" (i.e., no package at all). This simplest case was shown in -section :ref:`simple-example`; here is a slightly more involved example:: +section :ref:`distutils-simple-example`; here is a slightly more involved example:: py_modules = ['mod1', 'pkg.mod2'] Modified: doctools/trunk/Doc-3k/distutils/sourcedist.rst ============================================================================== --- doctools/trunk/Doc-3k/distutils/sourcedist.rst (original) +++ doctools/trunk/Doc-3k/distutils/sourcedist.rst Thu Aug 2 17:44:40 2007 @@ -4,7 +4,7 @@ Creating a Source Distribution ****************************** -As shown in section :ref:`simple-example`, you use the :command:`sdist` command +As shown in section :ref:`distutils-simple-example`, you use the :command:`sdist` command to create a source distribution. In the simplest case, :: python setup.py sdist Deleted: /doctools/trunk/Doc-3k/distutils/sysconfig.rst ============================================================================== --- /doctools/trunk/Doc-3k/distutils/sysconfig.rst Thu Aug 2 17:44:40 2007 +++ (empty file) @@ -1,112 +0,0 @@ - -:mod:`distutils.sysconfig` --- System configuration information -=============================================================== - -.. module:: distutils.sysconfig - :synopsis: Low-level access to configuration information of the Python interpreter. -.. moduleauthor:: Fred L. Drake, Jr. -.. moduleauthor:: Greg Ward -.. sectionauthor:: Fred L. Drake, Jr. - - -The :mod:`distutils.sysconfig` module provides access to Python's low-level -configuration information. The specific configuration variables available -depend heavily on the platform and configuration. The specific variables depend -on the build process for the specific version of Python being run; the variables -are those found in the :file:`Makefile` and configuration header that are -installed with Python on Unix systems. The configuration header is called -:file:`pyconfig.h` for Python versions starting with 2.2, and :file:`config.h` -for earlier versions of Python. - -Some additional functions are provided which perform some useful manipulations -for other parts of the :mod:`distutils` package. - - -.. data:: PREFIX - - The result of ``os.path.normpath(sys.prefix)``. - - -.. data:: EXEC_PREFIX - - The result of ``os.path.normpath(sys.exec_prefix)``. - - -.. function:: get_config_var(name) - - Return the value of a single variable. This is equivalent to - ``get_config_vars().get(name)``. - - -.. function:: get_config_vars(...) - - Return a set of variable definitions. If there are no arguments, this returns a - dictionary mapping names of configuration variables to values. If arguments are - provided, they should be strings, and the return value will be a sequence giving - the associated values. If a given name does not have a corresponding value, - ``None`` will be included for that variable. - - -.. function:: get_config_h_filename() - - Return the full path name of the configuration header. For Unix, this will be - the header generated by the :program:`configure` script; for other platforms the - header will have been supplied directly by the Python source distribution. The - file is a platform-specific text file. - - -.. function:: get_makefile_filename() - - Return the full path name of the :file:`Makefile` used to build Python. For - Unix, this will be a file generated by the :program:`configure` script; the - meaning for other platforms will vary. The file is a platform-specific text - file, if it exists. This function is only useful on POSIX platforms. - - -.. function:: get_python_inc([plat_specific[, prefix]]) - - Return the directory for either the general or platform-dependent C include - files. If *plat_specific* is true, the platform-dependent include directory is - returned; if false or omitted, the platform-independent directory is returned. - If *prefix* is given, it is used as either the prefix instead of - :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if - *plat_specific* is true. - - -.. function:: get_python_lib([plat_specific[, standard_lib[, prefix]]]) - - Return the directory for either the general or platform-dependent library - installation. If *plat_specific* is true, the platform-dependent include - directory is returned; if false or omitted, the platform-independent directory - is returned. If *prefix* is given, it is used as either the prefix instead of - :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if - *plat_specific* is true. If *standard_lib* is true, the directory for the - standard library is returned rather than the directory for the installation of - third-party extensions. - -The following function is only intended for use within the :mod:`distutils` -package. - - -.. function:: customize_compiler(compiler) - - Do any platform-specific customization of a - :class:`distutils.ccompiler.CCompiler` instance. - - This function is only needed on Unix at this time, but should be called - consistently to support forward-compatibility. It inserts the information that - varies across Unix flavors and is stored in Python's :file:`Makefile`. This - information includes the selected compiler, compiler and linker options, and the - extension used by the linker for shared objects. - -This function is even more special-purpose, and should only be used from -Python's own build procedures. - - -.. function:: set_python_build() - - Inform the :mod:`distutils.sysconfig` module that it is being used as part of - the build process for Python. This changes a lot of relative locations for - files, allowing them to be located in the build area rather than in an installed - Python. - Modified: doctools/trunk/Doc-3k/extending/extending.rst ============================================================================== --- doctools/trunk/Doc-3k/extending/extending.rst (original) +++ doctools/trunk/Doc-3k/extending/extending.rst Thu Aug 2 17:44:40 2007 @@ -1,7 +1,7 @@ .. highlightlang:: c -.. _intro: +.. _extending-intro: ****************************** Extending Python with C or C++ @@ -21,7 +21,7 @@ your system setup; details are given in later chapters. -.. _simpleexample: +.. _extending-simpleexample: A Simple Example ================ @@ -103,7 +103,7 @@ return *NULL* immediately (as we saw in the example). -.. _errors: +.. _extending-errors: Intermezzo: Errors and Exceptions ================================= @@ -1107,8 +1107,8 @@ this macro before accessing the C API. The exporting module is a modification of the :mod:`spam` module from section -:ref:`simpleexample`. The function :func:`spam.system` does not call the C -library function :cfunc:`system` directly, but a function +:ref:`extending-simpleexample`. The function :func:`spam.system` does not call +the C library function :cfunc:`system` directly, but a function :cfunc:`PySpam_System`, which would of course do something more complicated in reality (such as adding "spam" to every command). This function :cfunc:`PySpam_System` is also exported to other extension modules. Modified: doctools/trunk/Doc-3k/extending/index.rst ============================================================================== --- doctools/trunk/Doc-3k/extending/index.rst (original) +++ doctools/trunk/Doc-3k/extending/index.rst Thu Aug 2 17:44:40 2007 @@ -17,7 +17,7 @@ This document assumes basic knowledge about Python. For an informal introduction to the language, see :ref:`tutorial-index`. :ref:`reference-index` -gives a more formal definition of the language. :ref:`modules-index` documents +gives a more formal definition of the language. :ref:`library-index` documents the existing object types, functions and modules (both built-in and written in Python) that give the language its wide application range. Deleted: /doctools/trunk/Doc-3k/library/asttable.rst ============================================================================== --- /doctools/trunk/Doc-3k/library/asttable.rst Thu Aug 2 17:44:40 2007 +++ (empty file) @@ -1,288 +0,0 @@ -+-----------------------+--------------------+---------------------------------+ -| Node type | Attribute | Value | -+=======================+====================+=================================+ -| :class:`Add` | :attr:`left` | left operand | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | right operand | -+-----------------------+--------------------+---------------------------------+ -| :class:`And` | :attr:`nodes` | list of operands | -+-----------------------+--------------------+---------------------------------+ -| :class:`AssAttr` | | *attribute as target of | -| | | assignment* | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`expr` | expression on the left-hand | -| | | side of the dot | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`attrname` | the attribute name, a string | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`flags` | XXX | -+-----------------------+--------------------+---------------------------------+ -| :class:`AssList` | :attr:`nodes` | list of list elements being | -| | | assigned to | -+-----------------------+--------------------+---------------------------------+ -| :class:`AssName` | :attr:`name` | name being assigned to | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`flags` | XXX | -+-----------------------+--------------------+---------------------------------+ -| :class:`AssTuple` | :attr:`nodes` | list of tuple elements being | -| | | assigned to | -+-----------------------+--------------------+---------------------------------+ -| :class:`Assert` | :attr:`test` | the expression to be tested | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`fail` | the value of the | -| | | :exc:`AssertionError` | -+-----------------------+--------------------+---------------------------------+ -| :class:`Assign` | :attr:`nodes` | a list of assignment targets, | -| | | one per equal sign | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`expr` | the value being assigned | -+-----------------------+--------------------+---------------------------------+ -| :class:`AugAssign` | :attr:`node` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`op` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Bitand` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Bitor` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Bitxor` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Break` | | | -+-----------------------+--------------------+---------------------------------+ -| :class:`CallFunc` | :attr:`node` | expression for the callee | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`args` | a list of arguments | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`star_args` | the extended \*-arg value | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`dstar_args` | the extended \*\*-arg value | -+-----------------------+--------------------+---------------------------------+ -| :class:`Class` | :attr:`name` | the name of the class, a string | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`bases` | a list of base classes | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`doc` | doc string, a string or | -| | | ``None`` | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`code` | the body of the class statement | -+-----------------------+--------------------+---------------------------------+ -| :class:`Compare` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`ops` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Const` | :attr:`value` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Continue` | | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Decorators` | :attr:`nodes` | List of function decorator | -| | | expressions | -+-----------------------+--------------------+---------------------------------+ -| :class:`Dict` | :attr:`items` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Discard` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Div` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Ellipsis` | | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Expression` | :attr:`node` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Exec` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`locals` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`globals` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`FloorDiv` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`For` | :attr:`assign` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`list` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`body` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`else_` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`From` | :attr:`modname` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`names` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Function` | :attr:`decorators` | :class:`Decorators` or ``None`` | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`name` | name used in def, a string | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`argnames` | list of argument names, as | -| | | strings | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`defaults` | list of default values | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`flags` | xxx | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`doc` | doc string, a string or | -| | | ``None`` | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`code` | the body of the function | -+-----------------------+--------------------+---------------------------------+ -| :class:`GenExpr` | :attr:`code` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`GenExprFor` | :attr:`assign` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`iter` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`ifs` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`GenExprIf` | :attr:`test` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`GenExprInner` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`quals` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Getattr` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`attrname` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Global` | :attr:`names` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`If` | :attr:`tests` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`else_` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Import` | :attr:`names` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Invert` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Keyword` | :attr:`name` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Lambda` | :attr:`argnames` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`defaults` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`flags` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`code` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`LeftShift` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`List` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`ListComp` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`quals` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`ListCompFor` | :attr:`assign` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`list` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`ifs` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`ListCompIf` | :attr:`test` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Mod` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Module` | :attr:`doc` | doc string, a string or | -| | | ``None`` | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`node` | body of the module, a | -| | | :class:`Stmt` | -+-----------------------+--------------------+---------------------------------+ -| :class:`Mul` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Name` | :attr:`name` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Not` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Or` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Pass` | | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Power` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Print` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`dest` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Printnl` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`dest` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Raise` | :attr:`expr1` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`expr2` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`expr3` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Return` | :attr:`value` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`RightShift` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Slice` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`flags` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`lower` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`upper` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Sliceobj` | :attr:`nodes` | list of statements | -+-----------------------+--------------------+---------------------------------+ -| :class:`Stmt` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Sub` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Subscript` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`flags` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`subs` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`TryExcept` | :attr:`body` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`handlers` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`else_` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`TryFinally` | :attr:`body` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`final` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Tuple` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`UnaryAdd` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`UnarySub` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`While` | :attr:`test` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`body` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`else_` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`With` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`vars` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`body` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Yield` | :attr:`value` | | -+-----------------------+--------------------+---------------------------------+ - Modified: doctools/trunk/Doc-3k/library/contextlib.rst ============================================================================== --- doctools/trunk/Doc-3k/library/contextlib.rst (original) +++ doctools/trunk/Doc-3k/library/contextlib.rst Thu Aug 2 17:44:40 2007 @@ -82,8 +82,6 @@ :meth:`__exit__` methods should avoid raising exceptions, and in particular they should not re-raise a passed-in exception. -.. _context-closing: - .. function:: closing(thing) Modified: doctools/trunk/Doc-3k/library/cookielib.rst ============================================================================== --- doctools/trunk/Doc-3k/library/cookielib.rst (original) +++ doctools/trunk/Doc-3k/library/cookielib.rst Thu Aug 2 17:44:40 2007 @@ -32,9 +32,8 @@ :mailheader:`Set-Cookie2` headers (eg. ``domain`` and ``expires``) are conventionally referred to as :dfn:`attributes`. To distinguish them from Python attributes, the documentation for this module uses the term - :dfn:`cookie-attribute` instead + :dfn:`cookie-attribute` instead. -. The module defines the following exception: @@ -47,9 +46,8 @@ .. note:: For backwards-compatibility with Python 2.4 (which raised an :exc:`IOError`), - :exc:`LoadError` is a subclass of :exc:`IOError` + :exc:`LoadError` is a subclass of :exc:`IOError`. - . The following classes are provided: @@ -601,7 +599,7 @@ Equivalent to ``DomainStrictNoDots|DomainStrictNonDomain``. -.. _cookie-objects: +.. _cookielib-cookie-objects: Cookie Objects -------------- Added: doctools/trunk/Doc-3k/library/idle.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-3k/library/idle.rst Thu Aug 2 17:44:40 2007 @@ -0,0 +1,288 @@ +.. _idle: + +Idle +==== + +.. moduleauthor:: Guido van Rossum + + +.. % \declaremodule{standard}{idle} +.. % \modulesynopsis{A Python Integrated Development Environment} + +.. index:: + single: Idle + single: Python Editor + single: Integrated Development Environment + +Idle is the Python IDE built with the :mod:`Tkinter` GUI toolkit. + +IDLE has the following features: + +* coded in 100% pure Python, using the :mod:`Tkinter` GUI toolkit + +* cross-platform: works on Windows and Unix (on Mac OS, there are currently + problems with Tcl/Tk) + +* multi-window text editor with multiple undo, Python colorizing and many other + features, e.g. smart indent and call tips + +* Python shell window (a.k.a. interactive interpreter) + +* debugger (not complete, but you can set breakpoints, view and step) + + +Menus +----- + + +File menu +^^^^^^^^^ + +New window + create a new editing window + +Open... + open an existing file + +Open module... + open an existing module (searches sys.path) + +Class browser + show classes and methods in current file + +Path browser + show sys.path directories, modules, classes and methods + +.. index:: + single: Class browser + single: Path browser + +Save + save current window to the associated file (unsaved windows have a \* before and + after the window title) + +Save As... + save current window to new file, which becomes the associated file + +Save Copy As... + save current window to different file without changing the associated file + +Close + close current window (asks to save if unsaved) + +Exit + close all windows and quit IDLE (asks to save if unsaved) + + +Edit menu +^^^^^^^^^ + +Undo + Undo last change to current window (max 1000 changes) + +Redo + Redo last undone change to current window + +Cut + Copy selection into system-wide clipboard; then delete selection + +Copy + Copy selection into system-wide clipboard + +Paste + Insert system-wide clipboard into window + +Select All + Select the entire contents of the edit buffer + +Find... + Open a search dialog box with many options + +Find again + Repeat last search + +Find selection + Search for the string in the selection + +Find in Files... + Open a search dialog box for searching files + +Replace... + Open a search-and-replace dialog box + +Go to line + Ask for a line number and show that line + +Indent region + Shift selected lines right 4 spaces + +Dedent region + Shift selected lines left 4 spaces + +Comment out region + Insert ## in front of selected lines + +Uncomment region + Remove leading # or ## from selected lines + +Tabify region + Turns *leading* stretches of spaces into tabs + +Untabify region + Turn *all* tabs into the right number of spaces + +Expand word + Expand the word you have typed to match another word in the same buffer; repeat + to get a different expansion + +Format Paragraph + Reformat the current blank-line-separated paragraph + +Import module + Import or reload the current module + +Run script + Execute the current file in the __main__ namespace + +.. index:: + single: Import module + single: Run script + + +Windows menu +^^^^^^^^^^^^ + +Zoom Height + toggles the window between normal size (24x80) and maximum height. + +The rest of this menu lists the names of all open windows; select one to bring +it to the foreground (deiconifying it if necessary). + + +Debug menu (in the Python Shell window only) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Go to file/line + look around the insert point for a filename and linenumber, open the file, and + show the line. + +Open stack viewer + show the stack traceback of the last exception + +Debugger toggle + Run commands in the shell under the debugger + +JIT Stack viewer toggle + Open stack viewer on traceback + +.. index:: + single: stack viewer + single: debugger + + +Basic editing and navigation +---------------------------- + +* :kbd:`Backspace` deletes to the left; :kbd:`Del` deletes to the right + +* Arrow keys and :kbd:`Page Up`/:kbd:`Page Down` to move around + +* :kbd:`Home`/:kbd:`End` go to begin/end of line + +* :kbd:`C-Home`/:kbd:`C-End` go to begin/end of file + +* Some :program:`Emacs` bindings may also work, including :kbd:`C-B`, + :kbd:`C-P`, :kbd:`C-A`, :kbd:`C-E`, :kbd:`C-D`, :kbd:`C-L` + + +Automatic indentation +^^^^^^^^^^^^^^^^^^^^^ + +After a block-opening statement, the next line is indented by 4 spaces (in the +Python Shell window by one tab). After certain keywords (break, return etc.) +the next line is dedented. In leading indentation, :kbd:`Backspace` deletes up +to 4 spaces if they are there. :kbd:`Tab` inserts 1-4 spaces (in the Python +Shell window one tab). See also the indent/dedent region commands in the edit +menu. + + +Python Shell window +^^^^^^^^^^^^^^^^^^^ + +* :kbd:`C-C` interrupts executing command + +* :kbd:`C-D` sends end-of-file; closes window if typed at a ``>>>`` prompt + +* :kbd:`Alt-p` retrieves previous command matching what you have typed + +* :kbd:`Alt-n` retrieves next + +* :kbd:`Return` while on any previous command retrieves that command + +* :kbd:`Alt-/` (Expand word) is also useful here + +.. index:: single: indentation + + +Syntax colors +------------- + +The coloring is applied in a background "thread," so you may occasionally see +uncolorized text. To change the color scheme, edit the ``[Colors]`` section in +:file:`config.txt`. + +Python syntax colors: + Keywords + orange + + Strings + green + + Comments + red + + Definitions + blue + +Shell colors: + Console output + brown + + stdout + blue + + stderr + dark green + + stdin + black + + +Command line usage +^^^^^^^^^^^^^^^^^^ + +:: + + idle.py [-c command] [-d] [-e] [-s] [-t title] [arg] ... + + -c command run this command + -d enable debugger + -e edit mode; arguments are files to be edited + -s run $IDLESTARTUP or $PYTHONSTARTUP first + -t title set title of shell window + +If there are arguments: + +#. If :option:`-e` is used, arguments are files opened for editing and + ``sys.argv`` reflects the arguments passed to IDLE itself. + +#. Otherwise, if :option:`-c` is used, all arguments are placed in + ``sys.argv[1:...]``, with ``sys.argv[0]`` set to ``'-c'``. + +#. Otherwise, if neither :option:`-e` nor :option:`-c` is used, the first + argument is a script which is executed with the remaining arguments in + ``sys.argv[1:...]`` and ``sys.argv[0]`` set to the script name. If the script + name is '-', no script is executed but an interactive Python session is started; + the arguments are still available in ``sys.argv``. + + Modified: doctools/trunk/Doc-3k/library/index.rst ============================================================================== --- doctools/trunk/Doc-3k/library/index.rst (original) +++ doctools/trunk/Doc-3k/library/index.rst Thu Aug 2 17:44:40 2007 @@ -51,7 +51,7 @@ ipc.rst internet.rst mm.rst - tkinter.rst + tk.rst i18n.rst frameworks.rst development.rst Modified: doctools/trunk/Doc-3k/library/intro.rst ============================================================================== --- doctools/trunk/Doc-3k/library/intro.rst (original) +++ doctools/trunk/Doc-3k/library/intro.rst Thu Aug 2 17:44:40 2007 @@ -1,5 +1,5 @@ -.. _intro: +.. _library-intro: ************ Introduction Added: doctools/trunk/Doc-3k/library/othergui.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-3k/library/othergui.rst Thu Aug 2 17:44:40 2007 @@ -0,0 +1,93 @@ +.. _other-gui-packages: + +Other Graphical User Interface Packages +======================================= + +There are an number of extension widget sets to :mod:`Tkinter`. + + +.. seealso:: + + `Python megawidgets `_ + is a toolkit for building high-level compound widgets in Python using the + :mod:`Tkinter` module. It consists of a set of base classes and a library of + flexible and extensible megawidgets built on this foundation. These megawidgets + include notebooks, comboboxes, selection widgets, paned widgets, scrolled + widgets, dialog windows, etc. Also, with the Pmw.Blt interface to BLT, the + busy, graph, stripchart, tabset and vector commands are be available. + + The initial ideas for Pmw were taken from the Tk ``itcl`` extensions ``[incr + Tk]`` by Michael McLennan and ``[incr Widgets]`` by Mark Ulferts. Several of the + megawidgets are direct translations from the itcl to Python. It offers most of + the range of widgets that ``[incr Widgets]`` does, and is almost as complete as + Tix, lacking however Tix's fast :class:`HList` widget for drawing trees. + + `Tkinter3000 Widget Construction Kit (WCK) `_ + is a library that allows you to write new Tkinter widgets in pure Python. The + WCK framework gives you full control over widget creation, configuration, screen + appearance, and event handling. WCK widgets can be very fast and light-weight, + since they can operate directly on Python data structures, without having to + transfer data through the Tk/Tcl layer. + + .. % + +Other GUI packages are also available for Python: + + +.. seealso:: + + `wxPython `_ + wxPython is a cross-platform GUI toolkit for Python that is built around the + popular `wxWidgets `_ C++ toolkit. ?It provides a + native look and feel for applications on Windows, Mac OS X, and Unix systems by + using each platform's native widgets where ever possible, (GTK+ on Unix-like + systems). ?In addition to an extensive set of widgets, wxPython provides classes + for online documentation and context sensitive help, printing, HTML viewing, + low-level device context drawing, drag and drop, system clipboard access, an + XML-based resource format and more, including an ever growing library of user- + contributed modules. ?Both the wxWidgets and wxPython projects are under active + development and continuous improvement, and have active and helpful user and + developer communities. + + `wxPython in Action `_ + The wxPython book, by Noel Rappin and Robin Dunn. + + PyQt + PyQt is a :program:`sip`\ -wrapped binding to the Qt toolkit. Qt is an + extensive C++ GUI toolkit that is available for Unix, Windows and Mac OS X. + :program:`sip` is a tool for generating bindings for C++ libraries as Python + classes, and is specifically designed for Python. An online manual is available + at http://www.opendocspublishing.com/pyqt/ (errata are located at + http://www.valdyas.org/python/book.html). + + `PyKDE `_ + PyKDE is a :program:`sip`\ -wrapped interface to the KDE desktop libraries. KDE + is a desktop environment for Unix computers; the graphical components are based + on Qt. + + `FXPy `_ + is a Python extension module which provides an interface to the `FOX + `_ GUI. FOX is a C++ based Toolkit for + developing Graphical User Interfaces easily and effectively. It offers a wide, + and growing, collection of Controls, and provides state of the art facilities + such as drag and drop, selection, as well as OpenGL widgets for 3D graphical + manipulation. FOX also implements icons, images, and user-convenience features + such as status line help, and tooltips. + + Even though FOX offers a large collection of controls already, FOX leverages C++ + to allow programmers to easily build additional Controls and GUI elements, + simply by taking existing controls, and creating a derived class which simply + adds or redefines the desired behavior. + + `PyGTK `_ + is a set of bindings for the `GTK `_ widget set. It + provides an object oriented interface that is slightly higher level than the C + one. It automatically does all the type casting and reference counting that you + would have to do normally with the C API. There are also `bindings + `_ to `GNOME `_, and + a `tutorial + `_ is + available. + +.. % XXX Reference URLs that compare the different UI packages + Added: doctools/trunk/Doc-3k/library/scrolledtext.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-3k/library/scrolledtext.rst Thu Aug 2 17:44:40 2007 @@ -0,0 +1,32 @@ +:mod:`ScrolledText` --- Scrolled Text Widget +============================================ + +.. module:: ScrolledText + :platform: Tk + :synopsis: Text widget with a vertical scroll bar. +.. sectionauthor:: Fred L. Drake, Jr. + + +The :mod:`ScrolledText` module provides a class of the same name which +implements a basic text widget which has a vertical scroll bar configured to do +the "right thing." Using the :class:`ScrolledText` class is a lot easier than +setting up a text widget and scroll bar directly. The constructor is the same +as that of the :class:`Tkinter.Text` class. + +The text widget and scrollbar are packed together in a :class:`Frame`, and the +methods of the :class:`Grid` and :class:`Pack` geometry managers are acquired +from the :class:`Frame` object. This allows the :class:`ScrolledText` widget to +be used directly to achieve most normal geometry management behavior. + +Should more specific control be necessary, the following attributes are +available: + + +.. attribute:: ScrolledText.frame + + The frame which surrounds the text and scroll bar widgets. + + +.. attribute:: ScrolledText.vbar + + The scroll bar widget. Modified: doctools/trunk/Doc-3k/library/sqlite3.rst ============================================================================== --- doctools/trunk/Doc-3k/library/sqlite3.rst (original) +++ doctools/trunk/Doc-3k/library/sqlite3.rst Thu Aug 2 17:44:40 2007 @@ -148,9 +148,8 @@ for the lock to go away until raising an exception. The default for the timeout parameter is 5.0 (five seconds). - For the *isolation_level* parameter, please see the :attr:`isolation_level` - property of :class:`Connection` objects in section - :ref:`sqlite3-connection-isolationlevel`. + For the *isolation_level* parameter, please see the + :attr:`Connection.isolation_level` property of :class:`Connection` objects. SQLite natively supports only the types TEXT, INTEGER, FLOAT, BLOB and NULL. If you want to use other types you must add support for them yourself. The @@ -221,9 +220,6 @@ A :class:`Connection` instance has the following attributes and methods: -.. _sqlite3-connection-isolationlevel: - - .. attribute:: Connection.isolation_level Get or set the current isolation level. None for autocommit mode or one of Modified: doctools/trunk/Doc-3k/library/stdtypes.rst ============================================================================== --- doctools/trunk/Doc-3k/library/stdtypes.rst (original) +++ doctools/trunk/Doc-3k/library/stdtypes.rst Thu Aug 2 17:44:40 2007 @@ -1,5 +1,5 @@ -.. _types: +.. _bltin-types: ************** Built-in Types @@ -120,7 +120,7 @@ interpreted as ``not (a == b)``, and ``a == not b`` is a syntax error. -.. _comparisons: +.. _stdcomparisons: Comparisons =========== @@ -1764,9 +1764,8 @@ Not all "file-like" types in Python support use as a context manager for the :keyword:`with` statement. If your code is intended to work with any file-like - object, you can use the :func:`closing` function in the :mod:`contextlib` module - instead of using the object directly. See section :ref:`context-closing` for - details. + object, you can use the function :func:`contextlib.closing` instead of using + the object directly. .. method:: file.flush() Modified: doctools/trunk/Doc-3k/library/strings.rst ============================================================================== --- doctools/trunk/Doc-3k/library/strings.rst (original) +++ doctools/trunk/Doc-3k/library/strings.rst Thu Aug 2 17:44:40 2007 @@ -1,5 +1,5 @@ -.. _strings: +.. _stringservices: *************** String Services Modified: doctools/trunk/Doc-3k/library/tarfile.rst ============================================================================== --- doctools/trunk/Doc-3k/library/tarfile.rst (original) +++ doctools/trunk/Doc-3k/library/tarfile.rst Thu Aug 2 17:44:40 2007 @@ -1,3 +1,4 @@ +.. _tarfile-mod: :mod:`tarfile` --- Read and write tar archive files =================================================== @@ -286,7 +287,7 @@ .. method:: TarFile.open(...) Alternative constructor. The :func:`open` function on module level is actually a - shortcut to this classmethod. See section :ref:`module-tarfile` for details. + shortcut to this classmethod. See section :ref:`tarfile-mod` for details. .. method:: TarFile.getmember(name) Added: doctools/trunk/Doc-3k/library/tix.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-3k/library/tix.rst Thu Aug 2 17:44:40 2007 @@ -0,0 +1,602 @@ +:mod:`Tix` --- Extension widgets for Tk +======================================= + +.. module:: Tix + :synopsis: Tk Extension Widgets for Tkinter +.. sectionauthor:: Mike Clarkson + + +.. index:: single: Tix + +The :mod:`Tix` (Tk Interface Extension) module provides an additional rich set +of widgets. Although the standard Tk library has many useful widgets, they are +far from complete. The :mod:`Tix` library provides most of the commonly needed +widgets that are missing from standard Tk: :class:`HList`, :class:`ComboBox`, +:class:`Control` (a.k.a. SpinBox) and an assortment of scrollable widgets. +:mod:`Tix` also includes many more widgets that are generally useful in a wide +range of applications: :class:`NoteBook`, :class:`FileEntry`, +:class:`PanedWindow`, etc; there are more than 40 of them. + +With all these new widgets, you can introduce new interaction techniques into +applications, creating more useful and more intuitive user interfaces. You can +design your application by choosing the most appropriate widgets to match the +special needs of your application and users. + + +.. seealso:: + + `Tix Homepage `_ + The home page for :mod:`Tix`. This includes links to additional documentation + and downloads. + + `Tix Man Pages `_ + On-line version of the man pages and reference material. + + `Tix Programming Guide `_ + On-line version of the programmer's reference material. + + `Tix Development Applications `_ + Tix applications for development of Tix and Tkinter programs. Tide applications + work under Tk or Tkinter, and include :program:`TixInspect`, an inspector to + remotely modify and debug Tix/Tk/Tkinter applications. + + +Using Tix +--------- + + +.. class:: Tix(screenName[, baseName[, className]]) + + Toplevel widget of Tix which represents mostly the main window of an + application. It has an associated Tcl interpreter. + + Classes in the :mod:`Tix` module subclasses the classes in the :mod:`Tkinter` + module. The former imports the latter, so to use :mod:`Tix` with Tkinter, all + you need to do is to import one module. In general, you can just import + :mod:`Tix`, and replace the toplevel call to :class:`Tkinter.Tk` with + :class:`Tix.Tk`:: + + import Tix + from Tkconstants import * + root = Tix.Tk() + +To use :mod:`Tix`, you must have the :mod:`Tix` widgets installed, usually +alongside your installation of the Tk widgets. To test your installation, try +the following:: + + import Tix + root = Tix.Tk() + root.tk.eval('package require Tix') + +If this fails, you have a Tk installation problem which must be resolved before +proceeding. Use the environment variable :envvar:`TIX_LIBRARY` to point to the +installed :mod:`Tix` library directory, and make sure you have the dynamic +object library (:file:`tix8183.dll` or :file:`libtix8183.so`) in the same +directory that contains your Tk dynamic object library (:file:`tk8183.dll` or +:file:`libtk8183.so`). The directory with the dynamic object library should also +have a file called :file:`pkgIndex.tcl` (case sensitive), which contains the +line:: + + package ifneeded Tix 8.1 [list load "[file join $dir tix8183.dll]" Tix] + +.. % $ <-- bow to font-lock + + +Tix Widgets +----------- + +`Tix `_ +introduces over 40 widget classes to the :mod:`Tkinter` repertoire. There is a +demo of all the :mod:`Tix` widgets in the :file:`Demo/tix` directory of the +standard distribution. + +.. % The Python sample code is still being added to Python, hence commented out + + +Basic Widgets +^^^^^^^^^^^^^ + + +.. class:: Balloon() + + A `Balloon + `_ that + pops up over a widget to provide help. When the user moves the cursor inside a + widget to which a Balloon widget has been bound, a small pop-up window with a + descriptive message will be shown on the screen. + +.. % Python Demo of: +.. % \ulink{Balloon}{http://tix.sourceforge.net/dist/current/demos/samples/Balloon.tcl} + + +.. class:: ButtonBox() + + The `ButtonBox + `_ + widget creates a box of buttons, such as is commonly used for ``Ok Cancel``. + +.. % Python Demo of: +.. % \ulink{ButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/BtnBox.tcl} + + +.. class:: ComboBox() + + The `ComboBox + `_ + widget is similar to the combo box control in MS Windows. The user can select a + choice by either typing in the entry subwdget or selecting from the listbox + subwidget. + +.. % Python Demo of: +.. % \ulink{ComboBox}{http://tix.sourceforge.net/dist/current/demos/samples/ComboBox.tcl} + + +.. class:: Control() + + The `Control + `_ + widget is also known as the :class:`SpinBox` widget. The user can adjust the + value by pressing the two arrow buttons or by entering the value directly into + the entry. The new value will be checked against the user-defined upper and + lower limits. + +.. % Python Demo of: +.. % \ulink{Control}{http://tix.sourceforge.net/dist/current/demos/samples/Control.tcl} + + +.. class:: LabelEntry() + + The `LabelEntry + `_ + widget packages an entry widget and a label into one mega widget. It can be used + be used to simplify the creation of "entry-form" type of interface. + +.. % Python Demo of: +.. % \ulink{LabelEntry}{http://tix.sourceforge.net/dist/current/demos/samples/LabEntry.tcl} + + +.. class:: LabelFrame() + + The `LabelFrame + `_ + widget packages a frame widget and a label into one mega widget. To create + widgets inside a LabelFrame widget, one creates the new widgets relative to the + :attr:`frame` subwidget and manage them inside the :attr:`frame` subwidget. + +.. % Python Demo of: +.. % \ulink{LabelFrame}{http://tix.sourceforge.net/dist/current/demos/samples/LabFrame.tcl} + + +.. class:: Meter() + + The `Meter + `_ widget + can be used to show the progress of a background job which may take a long time + to execute. + +.. % Python Demo of: +.. % \ulink{Meter}{http://tix.sourceforge.net/dist/current/demos/samples/Meter.tcl} + + +.. class:: OptionMenu() + + The `OptionMenu + `_ + creates a menu button of options. + +.. % Python Demo of: +.. % \ulink{OptionMenu}{http://tix.sourceforge.net/dist/current/demos/samples/OptMenu.tcl} + + +.. class:: PopupMenu() + + The `PopupMenu + `_ + widget can be used as a replacement of the ``tk_popup`` command. The advantage + of the :mod:`Tix` :class:`PopupMenu` widget is it requires less application code + to manipulate. + +.. % Python Demo of: +.. % \ulink{PopupMenu}{http://tix.sourceforge.net/dist/current/demos/samples/PopMenu.tcl} + + +.. class:: Select() + + The `Select + `_ widget + is a container of button subwidgets. It can be used to provide radio-box or + check-box style of selection options for the user. + +.. % Python Demo of: +.. % \ulink{Select}{http://tix.sourceforge.net/dist/current/demos/samples/Select.tcl} + + +.. class:: StdButtonBox() + + The `StdButtonBox + `_ + widget is a group of standard buttons for Motif-like dialog boxes. + +.. % Python Demo of: +.. % \ulink{StdButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/StdBBox.tcl} + + +File Selectors +^^^^^^^^^^^^^^ + + +.. class:: DirList() + + The `DirList + `_ + widget displays a list view of a directory, its previous directories and its + sub-directories. The user can choose one of the directories displayed in the + list or change to another directory. + +.. % Python Demo of: +.. % \ulink{DirList}{http://tix.sourceforge.net/dist/current/demos/samples/DirList.tcl} + + +.. class:: DirTree() + + The `DirTree + `_ + widget displays a tree view of a directory, its previous directories and its + sub-directories. The user can choose one of the directories displayed in the + list or change to another directory. + +.. % Python Demo of: +.. % \ulink{DirTree}{http://tix.sourceforge.net/dist/current/demos/samples/DirTree.tcl} + + +.. class:: DirSelectDialog() + + The `DirSelectDialog + `_ + widget presents the directories in the file system in a dialog window. The user + can use this dialog window to navigate through the file system to select the + desired directory. + +.. % Python Demo of: +.. % \ulink{DirSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/DirDlg.tcl} + + +.. class:: DirSelectBox() + + The :class:`DirSelectBox` is similar to the standard Motif(TM) directory- + selection box. It is generally used for the user to choose a directory. + DirSelectBox stores the directories mostly recently selected into a ComboBox + widget so that they can be quickly selected again. + + +.. class:: ExFileSelectBox() + + The `ExFileSelectBox + `_ + widget is usually embedded in a tixExFileSelectDialog widget. It provides an + convenient method for the user to select files. The style of the + :class:`ExFileSelectBox` widget is very similar to the standard file dialog on + MS Windows 3.1. + +.. % Python Demo of: +.. % \ulink{ExFileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/EFileDlg.tcl} + + +.. class:: FileSelectBox() + + The `FileSelectBox + `_ + is similar to the standard Motif(TM) file-selection box. It is generally used + for the user to choose a file. FileSelectBox stores the files mostly recently + selected into a :class:`ComboBox` widget so that they can be quickly selected + again. + +.. % Python Demo of: +.. % \ulink{FileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/FileDlg.tcl} + + +.. class:: FileEntry() + + The `FileEntry + `_ + widget can be used to input a filename. The user can type in the filename + manually. Alternatively, the user can press the button widget that sits next to + the entry, which will bring up a file selection dialog. + +.. % Python Demo of: +.. % \ulink{FileEntry}{http://tix.sourceforge.net/dist/current/demos/samples/FileEnt.tcl} + + +Hierachical ListBox +^^^^^^^^^^^^^^^^^^^ + + +.. class:: HList() + + The `HList + `_ widget + can be used to display any data that have a hierarchical structure, for example, + file system directory trees. The list entries are indented and connected by + branch lines according to their places in the hierarchy. + +.. % Python Demo of: +.. % \ulink{HList}{http://tix.sourceforge.net/dist/current/demos/samples/HList1.tcl} + + +.. class:: CheckList() + + The `CheckList + `_ + widget displays a list of items to be selected by the user. CheckList acts + similarly to the Tk checkbutton or radiobutton widgets, except it is capable of + handling many more items than checkbuttons or radiobuttons. + +.. % Python Demo of: +.. % \ulink{ CheckList}{http://tix.sourceforge.net/dist/current/demos/samples/ChkList.tcl} +.. % Python Demo of: +.. % \ulink{ScrolledHList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList.tcl} +.. % Python Demo of: +.. % \ulink{ScrolledHList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList2.tcl} + + +.. class:: Tree() + + The `Tree + `_ widget + can be used to display hierarchical data in a tree form. The user can adjust the + view of the tree by opening or closing parts of the tree. + +.. % Python Demo of: +.. % \ulink{Tree}{http://tix.sourceforge.net/dist/current/demos/samples/Tree.tcl} +.. % Python Demo of: +.. % \ulink{Tree (Dynamic)}{http://tix.sourceforge.net/dist/current/demos/samples/DynTree.tcl} + + +Tabular ListBox +^^^^^^^^^^^^^^^ + + +.. class:: TList() + + The `TList + `_ widget + can be used to display data in a tabular format. The list entries of a + :class:`TList` widget are similar to the entries in the Tk listbox widget. The + main differences are (1) the :class:`TList` widget can display the list entries + in a two dimensional format and (2) you can use graphical images as well as + multiple colors and fonts for the list entries. + +.. % Python Demo of: +.. % \ulink{ScrolledTList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/STList1.tcl} +.. % Python Demo of: +.. % \ulink{ScrolledTList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/STList2.tcl} +.. % Grid has yet to be added to Python +.. % \subsubsection{Grid Widget} +.. % Python Demo of: +.. % \ulink{Simple Grid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid0.tcl} +.. % Python Demo of: +.. % \ulink{ScrolledGrid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid1.tcl} +.. % Python Demo of: +.. % \ulink{Editable Grid}{http://tix.sourceforge.net/dist/current/demos/samples/EditGrid.tcl} + + +Manager Widgets +^^^^^^^^^^^^^^^ + + +.. class:: PanedWindow() + + The `PanedWindow + `_ + widget allows the user to interactively manipulate the sizes of several panes. + The panes can be arranged either vertically or horizontally. The user changes + the sizes of the panes by dragging the resize handle between two panes. + +.. % Python Demo of: +.. % \ulink{PanedWindow}{http://tix.sourceforge.net/dist/current/demos/samples/PanedWin.tcl} + + +.. class:: ListNoteBook() + + The `ListNoteBook + `_ + widget is very similar to the :class:`TixNoteBook` widget: it can be used to + display many windows in a limited space using a notebook metaphor. The notebook + is divided into a stack of pages (windows). At one time only one of these pages + can be shown. The user can navigate through these pages by choosing the name of + the desired page in the :attr:`hlist` subwidget. + +.. % Python Demo of: +.. % \ulink{ListNoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/ListNBK.tcl} + + +.. class:: NoteBook() + + The `NoteBook + `_ + widget can be used to display many windows in a limited space using a notebook + metaphor. The notebook is divided into a stack of pages. At one time only one of + these pages can be shown. The user can navigate through these pages by choosing + the visual "tabs" at the top of the NoteBook widget. + +.. % Python Demo of: +.. % \ulink{NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/NoteBook.tcl} + +.. % \subsubsection{Scrolled Widgets} +.. % Python Demo of: +.. % \ulink{ScrolledListBox}{http://tix.sourceforge.net/dist/current/demos/samples/SListBox.tcl} +.. % Python Demo of: +.. % \ulink{ScrolledText}{http://tix.sourceforge.net/dist/current/demos/samples/SText.tcl} +.. % Python Demo of: +.. % \ulink{ScrolledWindow}{http://tix.sourceforge.net/dist/current/demos/samples/SWindow.tcl} +.. % Python Demo of: +.. % \ulink{Canvas Object View}{http://tix.sourceforge.net/dist/current/demos/samples/CObjView.tcl} + + +Image Types +^^^^^^^^^^^ + +The :mod:`Tix` module adds: + +* `pixmap `_ + capabilities to all :mod:`Tix` and :mod:`Tkinter` widgets to create color images + from XPM files. + + .. % Python Demo of: + .. % \ulink{XPM Image In Button}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm.tcl} + .. % Python Demo of: + .. % \ulink{XPM Image In Menu}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm1.tcl} + +* `Compound + `_ image + types can be used to create images that consists of multiple horizontal lines; + each line is composed of a series of items (texts, bitmaps, images or spaces) + arranged from left to right. For example, a compound image can be used to + display a bitmap and a text string simultaneously in a Tk :class:`Button` + widget. + + .. % Python Demo of: + .. % \ulink{Compound Image In Buttons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg.tcl} + .. % Python Demo of: + .. % \ulink{Compound Image In NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg2.tcl} + .. % Python Demo of: + .. % \ulink{Compound Image Notebook Color Tabs}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg4.tcl} + .. % Python Demo of: + .. % \ulink{Compound Image Icons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg3.tcl} + + +Miscellaneous Widgets +^^^^^^^^^^^^^^^^^^^^^ + + +.. class:: InputOnly() + + The `InputOnly + `_ + widgets are to accept inputs from the user, which can be done with the ``bind`` + command (Unix only). + + +Form Geometry Manager +^^^^^^^^^^^^^^^^^^^^^ + +In addition, :mod:`Tix` augments :mod:`Tkinter` by providing: + + +.. class:: Form() + + The `Form + `_ geometry + manager based on attachment rules for all Tk widgets. + +.. % begin{latexonly} +.. % \subsection{Tix Class Structure} +.. % +.. % \begin{figure}[hbtp] +.. % \centerline{\epsfig{file=hierarchy.png,width=.9\textwidth}} +.. % \vspace{.5cm} +.. % \caption{The Class Hierarchy of Tix Widgets} +.. % \end{figure} +.. % end{latexonly} + + +Tix Commands +------------ + + +.. class:: tixCommand() + + The `tix commands + `_ provide + access to miscellaneous elements of :mod:`Tix`'s internal state and the + :mod:`Tix` application context. Most of the information manipulated by these + methods pertains to the application as a whole, or to a screen or display, + rather than to a particular window. + + To view the current settings, the common usage is:: + + import Tix + root = Tix.Tk() + print root.tix_configure() + + +.. method:: tixCommand.tix_configure([cnf,] **kw) + + Query or modify the configuration options of the Tix application context. If no + option is specified, returns a dictionary all of the available options. If + option is specified with no value, then the method returns a list describing the + one named option (this list will be identical to the corresponding sublist of + the value returned if no option is specified). If one or more option-value + pairs are specified, then the method modifies the given option(s) to have the + given value(s); in this case the method returns an empty string. Option may be + any of the configuration options. + + +.. method:: tixCommand.tix_cget(option) + + Returns the current value of the configuration option given by *option*. Option + may be any of the configuration options. + + +.. method:: tixCommand.tix_getbitmap(name) + + Locates a bitmap file of the name ``name.xpm`` or ``name`` in one of the bitmap + directories (see the :meth:`tix_addbitmapdir` method). By using + :meth:`tix_getbitmap`, you can avoid hard coding the pathnames of the bitmap + files in your application. When successful, it returns the complete pathname of + the bitmap file, prefixed with the character ``@``. The returned value can be + used to configure the ``bitmap`` option of the Tk and Tix widgets. + + +.. method:: tixCommand.tix_addbitmapdir(directory) + + Tix maintains a list of directories under which the :meth:`tix_getimage` and + :meth:`tix_getbitmap` methods will search for image files. The standard bitmap + directory is :file:`$TIX_LIBRARY/bitmaps`. The :meth:`tix_addbitmapdir` method + adds *directory* into this list. By using this method, the image files of an + applications can also be located using the :meth:`tix_getimage` or + :meth:`tix_getbitmap` method. + + +.. method:: tixCommand.tix_filedialog([dlgclass]) + + Returns the file selection dialog that may be shared among different calls from + this application. This method will create a file selection dialog widget when + it is called the first time. This dialog will be returned by all subsequent + calls to :meth:`tix_filedialog`. An optional dlgclass parameter can be passed + as a string to specified what type of file selection dialog widget is desired. + Possible options are ``tix``, ``FileSelectDialog`` or ``tixExFileSelectDialog``. + + +.. method:: tixCommand.tix_getimage(self, name) + + Locates an image file of the name :file:`name.xpm`, :file:`name.xbm` or + :file:`name.ppm` in one of the bitmap directories (see the + :meth:`tix_addbitmapdir` method above). If more than one file with the same name + (but different extensions) exist, then the image type is chosen according to the + depth of the X display: xbm images are chosen on monochrome displays and color + images are chosen on color displays. By using :meth:`tix_getimage`, you can + avoid hard coding the pathnames of the image files in your application. When + successful, this method returns the name of the newly created image, which can + be used to configure the ``image`` option of the Tk and Tix widgets. + + +.. method:: tixCommand.tix_option_get(name) + + Gets the options maintained by the Tix scheme mechanism. + + +.. method:: tixCommand.tix_resetoptions(newScheme, newFontSet[, newScmPrio]) + + Resets the scheme and fontset of the Tix application to *newScheme* and + *newFontSet*, respectively. This affects only those widgets created after this + call. Therefore, it is best to call the resetoptions method before the creation + of any widgets in a Tix application. + + The optional parameter *newScmPrio* can be given to reset the priority level of + the Tk options set by the Tix schemes. + + Because of the way Tk handles the X option database, after Tix has been has + imported and inited, it is not possible to reset the color schemes and font sets + using the :meth:`tix_config` method. Instead, the :meth:`tix_resetoptions` + method must be used. Added: doctools/trunk/Doc-3k/library/tk.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-3k/library/tk.rst Thu Aug 2 17:44:40 2007 @@ -0,0 +1,40 @@ +.. _tkinter: + +********************************* +Graphical User Interfaces with Tk +********************************* + +.. index:: + single: GUI + single: Graphical User Interface + single: Tkinter + single: Tk + +Tk/Tcl has long been an integral part of Python. It provides a robust and +platform independent windowing toolkit, that is available to Python programmers +using the :mod:`Tkinter` module, and its extension, the :mod:`Tix` module. + +The :mod:`Tkinter` module is a thin object-oriented layer on top of Tcl/Tk. To +use :mod:`Tkinter`, you don't need to write Tcl code, but you will need to +consult the Tk documentation, and occasionally the Tcl documentation. +:mod:`Tkinter` is a set of wrappers that implement the Tk widgets as Python +classes. In addition, the internal module :mod:`_tkinter` provides a threadsafe +mechanism which allows Python and Tcl to interact. + +Tk is not the only GUI for Python; see section :ref:`other-gui-packages` for +more information on other GUI toolkits for Python. + +.. toctree:: + + tkinter.rst + tix.rst + scrolledtext.rst + turtle.rst + idle.rst + othergui.rst + +.. % Other sections I have in mind are +.. % Tkinter internals +.. % Freezing Tkinter applications + + Modified: doctools/trunk/Doc-3k/library/tkinter.rst ============================================================================== --- doctools/trunk/Doc-3k/library/tkinter.rst (original) +++ doctools/trunk/Doc-3k/library/tkinter.rst Thu Aug 2 17:44:40 2007 @@ -1,38 +1,3 @@ - -.. _tkinter: - -********************************* -Graphical User Interfaces with Tk -********************************* - -.. index:: - single: GUI - single: Graphical User Interface - single: Tkinter - single: Tk - -Tk/Tcl has long been an integral part of Python. It provides a robust and -platform independent windowing toolkit, that is available to Python programmers -using the :mod:`Tkinter` module, and its extension, the :mod:`Tix` module. - -The :mod:`Tkinter` module is a thin object-oriented layer on top of Tcl/Tk. To -use :mod:`Tkinter`, you don't need to write Tcl code, but you will need to -consult the Tk documentation, and occasionally the Tcl documentation. -:mod:`Tkinter` is a set of wrappers that implement the Tk widgets as Python -classes. In addition, the internal module :mod:`_tkinter` provides a threadsafe -mechanism which allows Python and Tcl to interact. - -Tk is not the only GUI for Python; see section :ref:`other-gui-packages` for -more information on other GUI toolkits for Python. - -.. % Other sections I have in mind are -.. % Tkinter internals -.. % Freezing Tkinter applications - - -.. toctree:: - - :mod:`Tkinter` --- Python interface to Tcl/Tk ============================================= @@ -873,1024 +838,3 @@ deleted, the image data is deleted as well, and Tk will display an empty box wherever the image was used. - -:mod:`Tix` --- Extension widgets for Tk -======================================= - -.. module:: Tix - :synopsis: Tk Extension Widgets for Tkinter -.. sectionauthor:: Mike Clarkson - - -.. index:: single: Tix - -The :mod:`Tix` (Tk Interface Extension) module provides an additional rich set -of widgets. Although the standard Tk library has many useful widgets, they are -far from complete. The :mod:`Tix` library provides most of the commonly needed -widgets that are missing from standard Tk: :class:`HList`, :class:`ComboBox`, -:class:`Control` (a.k.a. SpinBox) and an assortment of scrollable widgets. -:mod:`Tix` also includes many more widgets that are generally useful in a wide -range of applications: :class:`NoteBook`, :class:`FileEntry`, -:class:`PanedWindow`, etc; there are more than 40 of them. - -With all these new widgets, you can introduce new interaction techniques into -applications, creating more useful and more intuitive user interfaces. You can -design your application by choosing the most appropriate widgets to match the -special needs of your application and users. - - -.. seealso:: - - `Tix Homepage `_ - The home page for :mod:`Tix`. This includes links to additional documentation - and downloads. - - `Tix Man Pages `_ - On-line version of the man pages and reference material. - - `Tix Programming Guide `_ - On-line version of the programmer's reference material. - - `Tix Development Applications `_ - Tix applications for development of Tix and Tkinter programs. Tide applications - work under Tk or Tkinter, and include :program:`TixInspect`, an inspector to - remotely modify and debug Tix/Tk/Tkinter applications. - - -Using Tix ---------- - - -.. class:: Tix(screenName[, baseName[, className]]) - - Toplevel widget of Tix which represents mostly the main window of an - application. It has an associated Tcl interpreter. - - Classes in the :mod:`Tix` module subclasses the classes in the :mod:`Tkinter` - module. The former imports the latter, so to use :mod:`Tix` with Tkinter, all - you need to do is to import one module. In general, you can just import - :mod:`Tix`, and replace the toplevel call to :class:`Tkinter.Tk` with - :class:`Tix.Tk`:: - - import Tix - from Tkconstants import * - root = Tix.Tk() - -To use :mod:`Tix`, you must have the :mod:`Tix` widgets installed, usually -alongside your installation of the Tk widgets. To test your installation, try -the following:: - - import Tix - root = Tix.Tk() - root.tk.eval('package require Tix') - -If this fails, you have a Tk installation problem which must be resolved before -proceeding. Use the environment variable :envvar:`TIX_LIBRARY` to point to the -installed :mod:`Tix` library directory, and make sure you have the dynamic -object library (:file:`tix8183.dll` or :file:`libtix8183.so`) in the same -directory that contains your Tk dynamic object library (:file:`tk8183.dll` or -:file:`libtk8183.so`). The directory with the dynamic object library should also -have a file called :file:`pkgIndex.tcl` (case sensitive), which contains the -line:: - - package ifneeded Tix 8.1 [list load "[file join $dir tix8183.dll]" Tix] - -.. % $ <-- bow to font-lock - - -Tix Widgets ------------ - -`Tix `_ -introduces over 40 widget classes to the :mod:`Tkinter` repertoire. There is a -demo of all the :mod:`Tix` widgets in the :file:`Demo/tix` directory of the -standard distribution. - -.. % The Python sample code is still being added to Python, hence commented out - - -Basic Widgets -^^^^^^^^^^^^^ - - -.. class:: Balloon() - - A `Balloon - `_ that - pops up over a widget to provide help. When the user moves the cursor inside a - widget to which a Balloon widget has been bound, a small pop-up window with a - descriptive message will be shown on the screen. - -.. % Python Demo of: -.. % \ulink{Balloon}{http://tix.sourceforge.net/dist/current/demos/samples/Balloon.tcl} - - -.. class:: ButtonBox() - - The `ButtonBox - `_ - widget creates a box of buttons, such as is commonly used for ``Ok Cancel``. - -.. % Python Demo of: -.. % \ulink{ButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/BtnBox.tcl} - - -.. class:: ComboBox() - - The `ComboBox - `_ - widget is similar to the combo box control in MS Windows. The user can select a - choice by either typing in the entry subwdget or selecting from the listbox - subwidget. - -.. % Python Demo of: -.. % \ulink{ComboBox}{http://tix.sourceforge.net/dist/current/demos/samples/ComboBox.tcl} - - -.. class:: Control() - - The `Control - `_ - widget is also known as the :class:`SpinBox` widget. The user can adjust the - value by pressing the two arrow buttons or by entering the value directly into - the entry. The new value will be checked against the user-defined upper and - lower limits. - -.. % Python Demo of: -.. % \ulink{Control}{http://tix.sourceforge.net/dist/current/demos/samples/Control.tcl} - - -.. class:: LabelEntry() - - The `LabelEntry - `_ - widget packages an entry widget and a label into one mega widget. It can be used - be used to simplify the creation of "entry-form" type of interface. - -.. % Python Demo of: -.. % \ulink{LabelEntry}{http://tix.sourceforge.net/dist/current/demos/samples/LabEntry.tcl} - - -.. class:: LabelFrame() - - The `LabelFrame - `_ - widget packages a frame widget and a label into one mega widget. To create - widgets inside a LabelFrame widget, one creates the new widgets relative to the - :attr:`frame` subwidget and manage them inside the :attr:`frame` subwidget. - -.. % Python Demo of: -.. % \ulink{LabelFrame}{http://tix.sourceforge.net/dist/current/demos/samples/LabFrame.tcl} - - -.. class:: Meter() - - The `Meter - `_ widget - can be used to show the progress of a background job which may take a long time - to execute. - -.. % Python Demo of: -.. % \ulink{Meter}{http://tix.sourceforge.net/dist/current/demos/samples/Meter.tcl} - - -.. class:: OptionMenu() - - The `OptionMenu - `_ - creates a menu button of options. - -.. % Python Demo of: -.. % \ulink{OptionMenu}{http://tix.sourceforge.net/dist/current/demos/samples/OptMenu.tcl} - - -.. class:: PopupMenu() - - The `PopupMenu - `_ - widget can be used as a replacement of the ``tk_popup`` command. The advantage - of the :mod:`Tix` :class:`PopupMenu` widget is it requires less application code - to manipulate. - -.. % Python Demo of: -.. % \ulink{PopupMenu}{http://tix.sourceforge.net/dist/current/demos/samples/PopMenu.tcl} - - -.. class:: Select() - - The `Select - `_ widget - is a container of button subwidgets. It can be used to provide radio-box or - check-box style of selection options for the user. - -.. % Python Demo of: -.. % \ulink{Select}{http://tix.sourceforge.net/dist/current/demos/samples/Select.tcl} - - -.. class:: StdButtonBox() - - The `StdButtonBox - `_ - widget is a group of standard buttons for Motif-like dialog boxes. - -.. % Python Demo of: -.. % \ulink{StdButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/StdBBox.tcl} - - -File Selectors -^^^^^^^^^^^^^^ - - -.. class:: DirList() - - The `DirList - `_ - widget displays a list view of a directory, its previous directories and its - sub-directories. The user can choose one of the directories displayed in the - list or change to another directory. - -.. % Python Demo of: -.. % \ulink{DirList}{http://tix.sourceforge.net/dist/current/demos/samples/DirList.tcl} - - -.. class:: DirTree() - - The `DirTree - `_ - widget displays a tree view of a directory, its previous directories and its - sub-directories. The user can choose one of the directories displayed in the - list or change to another directory. - -.. % Python Demo of: -.. % \ulink{DirTree}{http://tix.sourceforge.net/dist/current/demos/samples/DirTree.tcl} - - -.. class:: DirSelectDialog() - - The `DirSelectDialog - `_ - widget presents the directories in the file system in a dialog window. The user - can use this dialog window to navigate through the file system to select the - desired directory. - -.. % Python Demo of: -.. % \ulink{DirSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/DirDlg.tcl} - - -.. class:: DirSelectBox() - - The :class:`DirSelectBox` is similar to the standard Motif(TM) directory- - selection box. It is generally used for the user to choose a directory. - DirSelectBox stores the directories mostly recently selected into a ComboBox - widget so that they can be quickly selected again. - - -.. class:: ExFileSelectBox() - - The `ExFileSelectBox - `_ - widget is usually embedded in a tixExFileSelectDialog widget. It provides an - convenient method for the user to select files. The style of the - :class:`ExFileSelectBox` widget is very similar to the standard file dialog on - MS Windows 3.1. - -.. % Python Demo of: -.. % \ulink{ExFileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/EFileDlg.tcl} - - -.. class:: FileSelectBox() - - The `FileSelectBox - `_ - is similar to the standard Motif(TM) file-selection box. It is generally used - for the user to choose a file. FileSelectBox stores the files mostly recently - selected into a :class:`ComboBox` widget so that they can be quickly selected - again. - -.. % Python Demo of: -.. % \ulink{FileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/FileDlg.tcl} - - -.. class:: FileEntry() - - The `FileEntry - `_ - widget can be used to input a filename. The user can type in the filename - manually. Alternatively, the user can press the button widget that sits next to - the entry, which will bring up a file selection dialog. - -.. % Python Demo of: -.. % \ulink{FileEntry}{http://tix.sourceforge.net/dist/current/demos/samples/FileEnt.tcl} - - -Hierachical ListBox -^^^^^^^^^^^^^^^^^^^ - - -.. class:: HList() - - The `HList - `_ widget - can be used to display any data that have a hierarchical structure, for example, - file system directory trees. The list entries are indented and connected by - branch lines according to their places in the hierarchy. - -.. % Python Demo of: -.. % \ulink{HList}{http://tix.sourceforge.net/dist/current/demos/samples/HList1.tcl} - - -.. class:: CheckList() - - The `CheckList - `_ - widget displays a list of items to be selected by the user. CheckList acts - similarly to the Tk checkbutton or radiobutton widgets, except it is capable of - handling many more items than checkbuttons or radiobuttons. - -.. % Python Demo of: -.. % \ulink{ CheckList}{http://tix.sourceforge.net/dist/current/demos/samples/ChkList.tcl} -.. % Python Demo of: -.. % \ulink{ScrolledHList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList.tcl} -.. % Python Demo of: -.. % \ulink{ScrolledHList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList2.tcl} - - -.. class:: Tree() - - The `Tree - `_ widget - can be used to display hierarchical data in a tree form. The user can adjust the - view of the tree by opening or closing parts of the tree. - -.. % Python Demo of: -.. % \ulink{Tree}{http://tix.sourceforge.net/dist/current/demos/samples/Tree.tcl} -.. % Python Demo of: -.. % \ulink{Tree (Dynamic)}{http://tix.sourceforge.net/dist/current/demos/samples/DynTree.tcl} - - -Tabular ListBox -^^^^^^^^^^^^^^^ - - -.. class:: TList() - - The `TList - `_ widget - can be used to display data in a tabular format. The list entries of a - :class:`TList` widget are similar to the entries in the Tk listbox widget. The - main differences are (1) the :class:`TList` widget can display the list entries - in a two dimensional format and (2) you can use graphical images as well as - multiple colors and fonts for the list entries. - -.. % Python Demo of: -.. % \ulink{ScrolledTList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/STList1.tcl} -.. % Python Demo of: -.. % \ulink{ScrolledTList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/STList2.tcl} -.. % Grid has yet to be added to Python -.. % \subsubsection{Grid Widget} -.. % Python Demo of: -.. % \ulink{Simple Grid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid0.tcl} -.. % Python Demo of: -.. % \ulink{ScrolledGrid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid1.tcl} -.. % Python Demo of: -.. % \ulink{Editable Grid}{http://tix.sourceforge.net/dist/current/demos/samples/EditGrid.tcl} - - -Manager Widgets -^^^^^^^^^^^^^^^ - - -.. class:: PanedWindow() - - The `PanedWindow - `_ - widget allows the user to interactively manipulate the sizes of several panes. - The panes can be arranged either vertically or horizontally. The user changes - the sizes of the panes by dragging the resize handle between two panes. - -.. % Python Demo of: -.. % \ulink{PanedWindow}{http://tix.sourceforge.net/dist/current/demos/samples/PanedWin.tcl} - - -.. class:: ListNoteBook() - - The `ListNoteBook - `_ - widget is very similar to the :class:`TixNoteBook` widget: it can be used to - display many windows in a limited space using a notebook metaphor. The notebook - is divided into a stack of pages (windows). At one time only one of these pages - can be shown. The user can navigate through these pages by choosing the name of - the desired page in the :attr:`hlist` subwidget. - -.. % Python Demo of: -.. % \ulink{ListNoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/ListNBK.tcl} - - -.. class:: NoteBook() - - The `NoteBook - `_ - widget can be used to display many windows in a limited space using a notebook - metaphor. The notebook is divided into a stack of pages. At one time only one of - these pages can be shown. The user can navigate through these pages by choosing - the visual "tabs" at the top of the NoteBook widget. - -.. % Python Demo of: -.. % \ulink{NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/NoteBook.tcl} - -.. % \subsubsection{Scrolled Widgets} -.. % Python Demo of: -.. % \ulink{ScrolledListBox}{http://tix.sourceforge.net/dist/current/demos/samples/SListBox.tcl} -.. % Python Demo of: -.. % \ulink{ScrolledText}{http://tix.sourceforge.net/dist/current/demos/samples/SText.tcl} -.. % Python Demo of: -.. % \ulink{ScrolledWindow}{http://tix.sourceforge.net/dist/current/demos/samples/SWindow.tcl} -.. % Python Demo of: -.. % \ulink{Canvas Object View}{http://tix.sourceforge.net/dist/current/demos/samples/CObjView.tcl} - - -Image Types -^^^^^^^^^^^ - -The :mod:`Tix` module adds: - -* `pixmap `_ - capabilities to all :mod:`Tix` and :mod:`Tkinter` widgets to create color images - from XPM files. - - .. % Python Demo of: - .. % \ulink{XPM Image In Button}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm.tcl} - .. % Python Demo of: - .. % \ulink{XPM Image In Menu}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm1.tcl} - -* `Compound - `_ image - types can be used to create images that consists of multiple horizontal lines; - each line is composed of a series of items (texts, bitmaps, images or spaces) - arranged from left to right. For example, a compound image can be used to - display a bitmap and a text string simultaneously in a Tk :class:`Button` - widget. - - .. % Python Demo of: - .. % \ulink{Compound Image In Buttons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg.tcl} - .. % Python Demo of: - .. % \ulink{Compound Image In NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg2.tcl} - .. % Python Demo of: - .. % \ulink{Compound Image Notebook Color Tabs}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg4.tcl} - .. % Python Demo of: - .. % \ulink{Compound Image Icons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg3.tcl} - - -Miscellaneous Widgets -^^^^^^^^^^^^^^^^^^^^^ - - -.. class:: InputOnly() - - The `InputOnly - `_ - widgets are to accept inputs from the user, which can be done with the ``bind`` - command (Unix only). - - -Form Geometry Manager -^^^^^^^^^^^^^^^^^^^^^ - -In addition, :mod:`Tix` augments :mod:`Tkinter` by providing: - - -.. class:: Form() - - The `Form - `_ geometry - manager based on attachment rules for all Tk widgets. - -.. % begin{latexonly} -.. % \subsection{Tix Class Structure} -.. % -.. % \begin{figure}[hbtp] -.. % \centerline{\epsfig{file=hierarchy.png,width=.9\textwidth}} -.. % \vspace{.5cm} -.. % \caption{The Class Hierarchy of Tix Widgets} -.. % \end{figure} -.. % end{latexonly} - - -Tix Commands ------------- - - -.. class:: tixCommand() - - The `tix commands - `_ provide - access to miscellaneous elements of :mod:`Tix`'s internal state and the - :mod:`Tix` application context. Most of the information manipulated by these - methods pertains to the application as a whole, or to a screen or display, - rather than to a particular window. - - To view the current settings, the common usage is:: - - import Tix - root = Tix.Tk() - print root.tix_configure() - - -.. method:: tixCommand.tix_configure([cnf,] **kw) - - Query or modify the configuration options of the Tix application context. If no - option is specified, returns a dictionary all of the available options. If - option is specified with no value, then the method returns a list describing the - one named option (this list will be identical to the corresponding sublist of - the value returned if no option is specified). If one or more option-value - pairs are specified, then the method modifies the given option(s) to have the - given value(s); in this case the method returns an empty string. Option may be - any of the configuration options. - - -.. method:: tixCommand.tix_cget(option) - - Returns the current value of the configuration option given by *option*. Option - may be any of the configuration options. - - -.. method:: tixCommand.tix_getbitmap(name) - - Locates a bitmap file of the name ``name.xpm`` or ``name`` in one of the bitmap - directories (see the :meth:`tix_addbitmapdir` method). By using - :meth:`tix_getbitmap`, you can avoid hard coding the pathnames of the bitmap - files in your application. When successful, it returns the complete pathname of - the bitmap file, prefixed with the character ``@``. The returned value can be - used to configure the ``bitmap`` option of the Tk and Tix widgets. - - -.. method:: tixCommand.tix_addbitmapdir(directory) - - Tix maintains a list of directories under which the :meth:`tix_getimage` and - :meth:`tix_getbitmap` methods will search for image files. The standard bitmap - directory is :file:`$TIX_LIBRARY/bitmaps`. The :meth:`tix_addbitmapdir` method - adds *directory* into this list. By using this method, the image files of an - applications can also be located using the :meth:`tix_getimage` or - :meth:`tix_getbitmap` method. - - -.. method:: tixCommand.tix_filedialog([dlgclass]) - - Returns the file selection dialog that may be shared among different calls from - this application. This method will create a file selection dialog widget when - it is called the first time. This dialog will be returned by all subsequent - calls to :meth:`tix_filedialog`. An optional dlgclass parameter can be passed - as a string to specified what type of file selection dialog widget is desired. - Possible options are ``tix``, ``FileSelectDialog`` or ``tixExFileSelectDialog``. - - -.. method:: tixCommand.tix_getimage(self, name) - - Locates an image file of the name :file:`name.xpm`, :file:`name.xbm` or - :file:`name.ppm` in one of the bitmap directories (see the - :meth:`tix_addbitmapdir` method above). If more than one file with the same name - (but different extensions) exist, then the image type is chosen according to the - depth of the X display: xbm images are chosen on monochrome displays and color - images are chosen on color displays. By using :meth:`tix_getimage`, you can - avoid hard coding the pathnames of the image files in your application. When - successful, this method returns the name of the newly created image, which can - be used to configure the ``image`` option of the Tk and Tix widgets. - - -.. method:: tixCommand.tix_option_get(name) - - Gets the options maintained by the Tix scheme mechanism. - - -.. method:: tixCommand.tix_resetoptions(newScheme, newFontSet[, newScmPrio]) - - Resets the scheme and fontset of the Tix application to *newScheme* and - *newFontSet*, respectively. This affects only those widgets created after this - call. Therefore, it is best to call the resetoptions method before the creation - of any widgets in a Tix application. - - The optional parameter *newScmPrio* can be given to reset the priority level of - the Tk options set by the Tix schemes. - - Because of the way Tk handles the X option database, after Tix has been has - imported and inited, it is not possible to reset the color schemes and font sets - using the :meth:`tix_config` method. Instead, the :meth:`tix_resetoptions` - method must be used. - - -:mod:`ScrolledText` --- Scrolled Text Widget -============================================ - -.. module:: ScrolledText - :platform: Tk - :synopsis: Text widget with a vertical scroll bar. -.. sectionauthor:: Fred L. Drake, Jr. - - -The :mod:`ScrolledText` module provides a class of the same name which -implements a basic text widget which has a vertical scroll bar configured to do -the "right thing." Using the :class:`ScrolledText` class is a lot easier than -setting up a text widget and scroll bar directly. The constructor is the same -as that of the :class:`Tkinter.Text` class. - -The text widget and scrollbar are packed together in a :class:`Frame`, and the -methods of the :class:`Grid` and :class:`Pack` geometry managers are acquired -from the :class:`Frame` object. This allows the :class:`ScrolledText` widget to -be used directly to achieve most normal geometry management behavior. - -Should more specific control be necessary, the following attributes are -available: - - -.. attribute:: ScrolledText.frame - - The frame which surrounds the text and scroll bar widgets. - - -.. attribute:: ScrolledText.vbar - - The scroll bar widget. - -XXX: input{libturtle} :XXX - -.. _idle: - -Idle -==== - -.. moduleauthor:: Guido van Rossum - - -.. % \declaremodule{standard}{idle} -.. % \modulesynopsis{A Python Integrated Development Environment} - -.. index:: - single: Idle - single: Python Editor - single: Integrated Development Environment - -Idle is the Python IDE built with the :mod:`Tkinter` GUI toolkit. - -IDLE has the following features: - -* coded in 100% pure Python, using the :mod:`Tkinter` GUI toolkit - -* cross-platform: works on Windows and Unix (on Mac OS, there are currently - problems with Tcl/Tk) - -* multi-window text editor with multiple undo, Python colorizing and many other - features, e.g. smart indent and call tips - -* Python shell window (a.k.a. interactive interpreter) - -* debugger (not complete, but you can set breakpoints, view and step) - - -Menus ------ - - -File menu -^^^^^^^^^ - -New window - create a new editing window - -Open... - open an existing file - -Open module... - open an existing module (searches sys.path) - -Class browser - show classes and methods in current file - -Path browser - show sys.path directories, modules, classes and methods - -.. index:: - single: Class browser - single: Path browser - -Save - save current window to the associated file (unsaved windows have a \* before and - after the window title) - -Save As... - save current window to new file, which becomes the associated file - -Save Copy As... - save current window to different file without changing the associated file - -Close - close current window (asks to save if unsaved) - -Exit - close all windows and quit IDLE (asks to save if unsaved) - - -Edit menu -^^^^^^^^^ - -Undo - Undo last change to current window (max 1000 changes) - -Redo - Redo last undone change to current window - -Cut - Copy selection into system-wide clipboard; then delete selection - -Copy - Copy selection into system-wide clipboard - -Paste - Insert system-wide clipboard into window - -Select All - Select the entire contents of the edit buffer - -Find... - Open a search dialog box with many options - -Find again - Repeat last search - -Find selection - Search for the string in the selection - -Find in Files... - Open a search dialog box for searching files - -Replace... - Open a search-and-replace dialog box - -Go to line - Ask for a line number and show that line - -Indent region - Shift selected lines right 4 spaces - -Dedent region - Shift selected lines left 4 spaces - -Comment out region - Insert ## in front of selected lines - -Uncomment region - Remove leading # or ## from selected lines - -Tabify region - Turns *leading* stretches of spaces into tabs - -Untabify region - Turn *all* tabs into the right number of spaces - -Expand word - Expand the word you have typed to match another word in the same buffer; repeat - to get a different expansion - -Format Paragraph - Reformat the current blank-line-separated paragraph - -Import module - Import or reload the current module - -Run script - Execute the current file in the __main__ namespace - -.. index:: - single: Import module - single: Run script - - -Windows menu -^^^^^^^^^^^^ - -Zoom Height - toggles the window between normal size (24x80) and maximum height. - -The rest of this menu lists the names of all open windows; select one to bring -it to the foreground (deiconifying it if necessary). - - -Debug menu (in the Python Shell window only) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Go to file/line - look around the insert point for a filename and linenumber, open the file, and - show the line. - -Open stack viewer - show the stack traceback of the last exception - -Debugger toggle - Run commands in the shell under the debugger - -JIT Stack viewer toggle - Open stack viewer on traceback - -.. index:: - single: stack viewer - single: debugger - - -Basic editing and navigation ----------------------------- - -* :kbd:`Backspace` deletes to the left; :kbd:`Del` deletes to the right - -* Arrow keys and :kbd:`Page Up`/:kbd:`Page Down` to move around - -* :kbd:`Home`/:kbd:`End` go to begin/end of line - -* :kbd:`C-Home`/:kbd:`C-End` go to begin/end of file - -* Some :program:`Emacs` bindings may also work, including :kbd:`C-B`, - :kbd:`C-P`, :kbd:`C-A`, :kbd:`C-E`, :kbd:`C-D`, :kbd:`C-L` - - -Automatic indentation -^^^^^^^^^^^^^^^^^^^^^ - -After a block-opening statement, the next line is indented by 4 spaces (in the -Python Shell window by one tab). After certain keywords (break, return etc.) -the next line is dedented. In leading indentation, :kbd:`Backspace` deletes up -to 4 spaces if they are there. :kbd:`Tab` inserts 1-4 spaces (in the Python -Shell window one tab). See also the indent/dedent region commands in the edit -menu. - - -Python Shell window -^^^^^^^^^^^^^^^^^^^ - -* :kbd:`C-C` interrupts executing command - -* :kbd:`C-D` sends end-of-file; closes window if typed at a ``>>>`` prompt - -* :kbd:`Alt-p` retrieves previous command matching what you have typed - -* :kbd:`Alt-n` retrieves next - -* :kbd:`Return` while on any previous command retrieves that command - -* :kbd:`Alt-/` (Expand word) is also useful here - -.. index:: single: indentation - - -Syntax colors -------------- - -The coloring is applied in a background "thread," so you may occasionally see -uncolorized text. To change the color scheme, edit the ``[Colors]`` section in -:file:`config.txt`. - -Python syntax colors: - Keywords - orange - - Strings - green - - Comments - red - - Definitions - blue - -Shell colors: - Console output - brown - - stdout - blue - - stderr - dark green - - stdin - black - - -Command line usage -^^^^^^^^^^^^^^^^^^ - -:: - - idle.py [-c command] [-d] [-e] [-s] [-t title] [arg] ... - - -c command run this command - -d enable debugger - -e edit mode; arguments are files to be edited - -s run $IDLESTARTUP or $PYTHONSTARTUP first - -t title set title of shell window - -If there are arguments: - -#. If :option:`-e` is used, arguments are files opened for editing and - ``sys.argv`` reflects the arguments passed to IDLE itself. - -#. Otherwise, if :option:`-c` is used, all arguments are placed in - ``sys.argv[1:...]``, with ``sys.argv[0]`` set to ``'-c'``. - -#. Otherwise, if neither :option:`-e` nor :option:`-c` is used, the first - argument is a script which is executed with the remaining arguments in - ``sys.argv[1:...]`` and ``sys.argv[0]`` set to the script name. If the script - name is '-', no script is executed but an interactive Python session is started; - the arguments are still available in ``sys.argv``. - - -.. _other-gui-packages: - -Other Graphical User Interface Packages -======================================= - -There are an number of extension widget sets to :mod:`Tkinter`. - - -.. seealso:: - - `Python megawidgets `_ - is a toolkit for building high-level compound widgets in Python using the - :mod:`Tkinter` module. It consists of a set of base classes and a library of - flexible and extensible megawidgets built on this foundation. These megawidgets - include notebooks, comboboxes, selection widgets, paned widgets, scrolled - widgets, dialog windows, etc. Also, with the Pmw.Blt interface to BLT, the - busy, graph, stripchart, tabset and vector commands are be available. - - The initial ideas for Pmw were taken from the Tk ``itcl`` extensions ``[incr - Tk]`` by Michael McLennan and ``[incr Widgets]`` by Mark Ulferts. Several of the - megawidgets are direct translations from the itcl to Python. It offers most of - the range of widgets that ``[incr Widgets]`` does, and is almost as complete as - Tix, lacking however Tix's fast :class:`HList` widget for drawing trees. - - `Tkinter3000 Widget Construction Kit (WCK) `_ - is a library that allows you to write new Tkinter widgets in pure Python. The - WCK framework gives you full control over widget creation, configuration, screen - appearance, and event handling. WCK widgets can be very fast and light-weight, - since they can operate directly on Python data structures, without having to - transfer data through the Tk/Tcl layer. - - .. % - -Other GUI packages are also available for Python: - - -.. seealso:: - - `wxPython `_ - wxPython is a cross-platform GUI toolkit for Python that is built around the - popular `wxWidgets `_ C++ toolkit. ?It provides a - native look and feel for applications on Windows, Mac OS X, and Unix systems by - using each platform's native widgets where ever possible, (GTK+ on Unix-like - systems). ?In addition to an extensive set of widgets, wxPython provides classes - for online documentation and context sensitive help, printing, HTML viewing, - low-level device context drawing, drag and drop, system clipboard access, an - XML-based resource format and more, including an ever growing library of user- - contributed modules. ?Both the wxWidgets and wxPython projects are under active - development and continuous improvement, and have active and helpful user and - developer communities. - - `wxPython in Action `_ - The wxPython book, by Noel Rappin and Robin Dunn. - - PyQt - PyQt is a :program:`sip`\ -wrapped binding to the Qt toolkit. Qt is an - extensive C++ GUI toolkit that is available for Unix, Windows and Mac OS X. - :program:`sip` is a tool for generating bindings for C++ libraries as Python - classes, and is specifically designed for Python. An online manual is available - at http://www.opendocspublishing.com/pyqt/ (errata are located at - http://www.valdyas.org/python/book.html). - - `PyKDE `_ - PyKDE is a :program:`sip`\ -wrapped interface to the KDE desktop libraries. KDE - is a desktop environment for Unix computers; the graphical components are based - on Qt. - - `FXPy `_ - is a Python extension module which provides an interface to the `FOX - `_ GUI. FOX is a C++ based Toolkit for - developing Graphical User Interfaces easily and effectively. It offers a wide, - and growing, collection of Controls, and provides state of the art facilities - such as drag and drop, selection, as well as OpenGL widgets for 3D graphical - manipulation. FOX also implements icons, images, and user-convenience features - such as status line help, and tooltips. - - Even though FOX offers a large collection of controls already, FOX leverages C++ - to allow programmers to easily build additional Controls and GUI elements, - simply by taking existing controls, and creating a derived class which simply - adds or redefines the desired behavior. - - `PyGTK `_ - is a set of bindings for the `GTK `_ widget set. It - provides an object oriented interface that is slightly higher level than the C - one. It automatically does all the type casting and reference counting that you - would have to do normally with the C API. There are also `bindings - `_ to `GNOME `_, and - a `tutorial - `_ is - available. - -.. % XXX Reference URLs that compare the different UI packages - Modified: doctools/trunk/Doc-3k/library/xml.dom.minidom.rst ============================================================================== --- doctools/trunk/Doc-3k/library/xml.dom.minidom.rst (original) +++ doctools/trunk/Doc-3k/library/xml.dom.minidom.rst Thu Aug 2 17:44:40 2007 @@ -108,7 +108,7 @@ The W3C recommendation for the DOM supported by :mod:`xml.dom.minidom`. -.. _dom-objects: +.. _minidom-objects: DOM Objects ----------- Modified: doctools/trunk/Doc-3k/reference/compound_stmts.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/compound_stmts.rst (original) +++ doctools/trunk/Doc-3k/reference/compound_stmts.rst Thu Aug 2 17:44:40 2007 @@ -270,7 +270,7 @@ :func:`sys.exc_info` returns a 3-tuple consisting of: ``exc_type`` receives the object identifying the exception; ``exc_value`` receives the exception's parameter; ``exc_traceback`` receives a traceback object (see section -:ref:`traceback`) identifying the point in the program where the exception +:ref:`types`) identifying the point in the program where the exception occurred. :func:`sys.exc_info` values are restored to their previous values (before the call) when returning from a function that handled an exception. Modified: doctools/trunk/Doc-3k/reference/datamodel.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/datamodel.rst (original) +++ doctools/trunk/Doc-3k/reference/datamodel.rst Thu Aug 2 17:44:40 2007 @@ -989,8 +989,6 @@ can implement a Jump command (aka Set Next Statement) by writing to f_lineno. Traceback objects - .. _traceback: - .. index:: object: traceback pair: stack; trace Modified: doctools/trunk/Doc-3k/reference/simple_stmts.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/simple_stmts.rst (original) +++ doctools/trunk/Doc-3k/reference/simple_stmts.rst Thu Aug 2 17:44:40 2007 @@ -500,7 +500,7 @@ .. index:: object: traceback If a third object is present and not ``None``, it must be a traceback object -(see section :ref:`traceback`), and it is substituted instead of the current +(see section :ref:`types`), and it is substituted instead of the current location as the place where the exception occurred. If the third object is present and not a traceback object or ``None``, a :exc:`TypeError` exception is raised. The three-expression form of :keyword:`raise` is useful to re-raise an From python-checkins at python.org Thu Aug 2 18:13:06 2007 From: python-checkins at python.org (georg.brandl) Date: Thu, 2 Aug 2007 18:13:06 +0200 (CEST) Subject: [Python-checkins] r56671 - in doctools/trunk/Doc-3k: library/ast.rst reference/expressions.rst reference/simple_stmts.rst Message-ID: <20070802161306.67CBE1E400F@bag.python.org> Author: georg.brandl Date: Thu Aug 2 18:13:06 2007 New Revision: 56671 Removed: doctools/trunk/Doc-3k/library/ast.rst Modified: doctools/trunk/Doc-3k/reference/expressions.rst doctools/trunk/Doc-3k/reference/simple_stmts.rst Log: Extra 3k fixes. Deleted: /doctools/trunk/Doc-3k/library/ast.rst ============================================================================== --- /doctools/trunk/Doc-3k/library/ast.rst Thu Aug 2 18:13:06 2007 +++ (empty file) @@ -1,62 +0,0 @@ -.. % XXX Label can't be _ast? -.. % XXX Where should this section/chapter go? - - -.. _ast: - -********************* -Abstract Syntax Trees -********************* - -.. sectionauthor:: Martin v. L?wis - - -.. versionadded:: 2.5 - -The ``_ast`` module helps Python applications to process trees of the Python -abstract syntax grammar. The Python compiler currently provides read-only access -to such trees, meaning that applications can only create a tree for a given -piece of Python source code; generating byte code from a (potentially modified) -tree is not supported. The abstract syntax itself might change with each Python -release; this module helps to find out programmatically what the current grammar -looks like. - -An abstract syntax tree can be generated by passing ``_ast.PyCF_ONLY_AST`` as a -flag to the :func:`compile` builtin function. The result will be a tree of -objects whose classes all inherit from ``_ast.AST``. - -The actual classes are derived from the ``Parser/Python.asdl`` file, which is -reproduced below. There is one class defined for each left-hand side symbol in -the abstract grammar (for example, ``_ast.stmt`` or ``_ast.expr``). In addition, -there is one class defined for each constructor on the right-hand side; these -classes inherit from the classes for the left-hand side trees. For example, -``_ast.BinOp`` inherits from ``_ast.expr``. For production rules with -alternatives (aka "sums"), the left-hand side class is abstract: only instances -of specific constructor nodes are ever created. - -Each concrete class has an attribute ``_fields`` which gives the names of all -child nodes. - -Each instance of a concrete class has one attribute for each child node, of the -type as defined in the grammar. For example, ``_ast.BinOp`` instances have an -attribute ``left`` of type ``_ast.expr``. Instances of ``_ast.expr`` and -``_ast.stmt`` subclasses also have lineno and col_offset attributes. The lineno -is the line number of source text (1 indexed so the first line is line 1) and -the col_offset is the utf8 byte offset of the first token that generated the -node. The utf8 offset is recorded because the parser uses utf8 internally. - -If these attributes are marked as optional in the grammar (using a question -mark), the value might be ``None``. If the attributes can have zero-or-more -values (marked with an asterisk), the values are represented as Python lists. - - -Abstract Grammar -================ - -The module defines a string constant ``__version__`` which is the decimal -subversion revision number of the file shown below. - -The abstract grammar is currently defined as follows: - - -.. XXX includefile ../../Parser/Python.asdl Modified: doctools/trunk/Doc-3k/reference/expressions.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/expressions.rst (original) +++ doctools/trunk/Doc-3k/reference/expressions.rst Thu Aug 2 18:13:06 2007 @@ -31,9 +31,11 @@ .. index:: pair: arithmetic; conversion +.. XXX no coercion rules are documented anymore + When a description of an arithmetic operator below uses the phrase "the numeric arguments are converted to a common type," the arguments are coerced using the -coercion rules listed at :ref:`coercion-rules`. If both arguments are standard +coercion rules. If both arguments are standard numeric types, the following coercions are applied: * If either argument is a complex number, the other is converted to complex; Modified: doctools/trunk/Doc-3k/reference/simple_stmts.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/simple_stmts.rst (original) +++ doctools/trunk/Doc-3k/reference/simple_stmts.rst Thu Aug 2 18:13:06 2007 @@ -59,7 +59,7 @@ In interactive mode, if the value is not ``None``, it is converted to a string using the built-in :func:`repr` function and the resulting string is written to -standard output (see section :ref:`print`) on a line by itself. (Expression +standard output (see :func:`print`) on a line by itself. (Expression statements yielding ``None`` are not written, so that procedure calls do not cause any output.) From python-checkins at python.org Thu Aug 2 18:52:00 2007 From: python-checkins at python.org (guido.van.rossum) Date: Thu, 2 Aug 2007 18:52:00 +0200 (CEST) Subject: [Python-checkins] r56673 - peps/trunk/pep-3115.txt Message-ID: <20070802165200.2AA071E4013@bag.python.org> Author: guido.van.rossum Date: Thu Aug 2 18:51:59 2007 New Revision: 56673 Modified: peps/trunk/pep-3115.txt Log: Mention that type.__prepare__() exists for use via super(). Modified: peps/trunk/pep-3115.txt ============================================================================== --- peps/trunk/pep-3115.txt (original) +++ peps/trunk/pep-3115.txt Thu Aug 2 18:51:59 2007 @@ -132,6 +132,10 @@ assignment algorithm. (Note also that 'metaclass' is a keyword- only argument as per PEP 3102 [6].) + Even though __prepare__ is not required, the default metaclass + ('type') implements it, for the convenience of subclasses calling + it via super(). + __prepare__ returns a dictionary-like object which is used to store the class member definitions during evaluation of the class body. In other words, the class body is evaluated as a function block From python-checkins at python.org Thu Aug 2 20:07:53 2007 From: python-checkins at python.org (georg.brandl) Date: Thu, 2 Aug 2007 20:07:53 +0200 (CEST) Subject: [Python-checkins] r56674 - in doctools/trunk: Doc-26/TODO Doc-26/about.rst Doc-26/c-api/concrete.rst Doc-26/c-api/intro.rst Doc-26/c-api/newtypes.rst Doc-26/c-api/utilities.rst Doc-26/distutils/index.rst Doc-26/distutils/introduction.rst Doc-26/extending/building.rst Doc-26/extending/extending.rst Doc-26/extending/newtypes.rst Doc-26/extending/windows.rst Doc-26/install/index.rst Doc-26/library/array.rst Doc-26/library/ast.rst Doc-26/library/audioop.rst Doc-26/library/codecs.rst Doc-26/library/distutils.rst Doc-26/library/exceptions.rst Doc-26/library/functions.rst Doc-26/library/objects.rst Doc-26/library/operator.rst Doc-26/library/parser.rst Doc-26/library/pdb.rst Doc-26/library/stdtypes.rst Doc-26/library/warnings.rst Doc-26/library/weakref.rst Doc-26/library/webbrowser.rst Doc-26/library/xml.etree.elementtree.rst Doc-26/library/xml.sax.handler.rst Doc-26/maclib/mac.rst Doc-26/reference/datamodel.rst Doc-26/reference/expressions.rst Doc-26/reference/introduction.rst Doc-26/reference/lexical_analysis.rst Doc-26/reference/simple_stmts.rst Doc-26/tutorial/controlflow.rst Doc-26/tutorial/datastructures.rst Doc-26/tutorial/errors.rst Doc-26/tutorial/glossary.rst Doc-26/tutorial/inputoutput.rst Doc-26/tutorial/interactive.rst Doc-26/tutorial/interpreter.rst Doc-26/tutorial/modules.rst Doc-26/tutorial/stdlib.rst Doc-26/tutorial/stdlib2.rst Doc-26/tutorial/whatnow.rst Doc-26/whatsnew/2.3.rst Doc-26/whatsnew/2.4.rst Doc-26/whatsnew/2.6.rst Doc-3k/TODO Doc-3k/about.rst Doc-3k/c-api/concrete.rst Doc-3k/c-api/intro.rst Doc-3k/c-api/newtypes.rst Doc-3k/c-api/utilities.rst Doc-3k/distutils/index.rst Doc-3k/distutils/introduction.rst Doc-3k/extending/building.rst Doc-3k/extending/extending.rst Doc-3k/extending/newtypes.rst Doc-3k/extending/windows.rst Doc-3k/install/index.rst Doc-3k/library/array.rst Doc-3k/library/audioop.rst Doc-3k/library/codecs.rst Doc-3k/library/distutils.rst Doc-3k/library/exceptions.rst Doc-3k/library/functions.rst Doc-3k/library/objects.rst Doc-3k/library/operator.rst Doc-3k/library/parser.rst Doc-3k/library/pdb.rst Doc-3k/library/stdtypes.rst Doc-3k/library/warnings.rst Doc-3k/library/weakref.rst Doc-3k/library/webbrowser.rst Doc-3k/library/xml.etree.elementtree.rst Doc-3k/library/xml.sax.handler.rst Doc-3k/maclib/mac.rst Doc-3k/reference/datamodel.rst Doc-3k/reference/expressions.rst Doc-3k/reference/introduction.rst Doc-3k/reference/lexical_analysis.rst Doc-3k/reference/simple_stmts.rst Doc-3k/tutorial/controlflow.rst Doc-3k/tutorial/datastructures.rst Doc-3k/tutorial/errors.rst Doc-3k/tutorial/glossary.rst Doc-3k/tutorial/inputoutput.rst Doc-3k/tutorial/interactive.rst Doc-3k/tutorial/interpreter.rst Doc-3k/tutorial/modules.rst Doc-3k/tutorial/stdlib.rst Doc-3k/tutorial/stdlib2.rst Doc-3k/tutorial/whatnow.rst Doc-3k/whatsnew/2.3.rst Doc-3k/whatsnew/2.4.rst Doc-3k/whatsnew/2.6.rst Message-ID: <20070802180753.966531E4017@bag.python.org> Author: georg.brandl Date: Thu Aug 2 20:07:46 2007 New Revision: 56674 Modified: doctools/trunk/Doc-26/TODO doctools/trunk/Doc-26/about.rst doctools/trunk/Doc-26/c-api/concrete.rst doctools/trunk/Doc-26/c-api/intro.rst doctools/trunk/Doc-26/c-api/newtypes.rst doctools/trunk/Doc-26/c-api/utilities.rst doctools/trunk/Doc-26/distutils/index.rst doctools/trunk/Doc-26/distutils/introduction.rst doctools/trunk/Doc-26/extending/building.rst doctools/trunk/Doc-26/extending/extending.rst doctools/trunk/Doc-26/extending/newtypes.rst doctools/trunk/Doc-26/extending/windows.rst doctools/trunk/Doc-26/install/index.rst doctools/trunk/Doc-26/library/array.rst doctools/trunk/Doc-26/library/ast.rst doctools/trunk/Doc-26/library/audioop.rst doctools/trunk/Doc-26/library/codecs.rst doctools/trunk/Doc-26/library/distutils.rst doctools/trunk/Doc-26/library/exceptions.rst doctools/trunk/Doc-26/library/functions.rst doctools/trunk/Doc-26/library/objects.rst doctools/trunk/Doc-26/library/operator.rst doctools/trunk/Doc-26/library/parser.rst doctools/trunk/Doc-26/library/pdb.rst doctools/trunk/Doc-26/library/stdtypes.rst doctools/trunk/Doc-26/library/warnings.rst doctools/trunk/Doc-26/library/weakref.rst doctools/trunk/Doc-26/library/webbrowser.rst doctools/trunk/Doc-26/library/xml.etree.elementtree.rst doctools/trunk/Doc-26/library/xml.sax.handler.rst doctools/trunk/Doc-26/maclib/mac.rst doctools/trunk/Doc-26/reference/datamodel.rst doctools/trunk/Doc-26/reference/expressions.rst doctools/trunk/Doc-26/reference/introduction.rst doctools/trunk/Doc-26/reference/lexical_analysis.rst doctools/trunk/Doc-26/reference/simple_stmts.rst doctools/trunk/Doc-26/tutorial/controlflow.rst doctools/trunk/Doc-26/tutorial/datastructures.rst doctools/trunk/Doc-26/tutorial/errors.rst doctools/trunk/Doc-26/tutorial/glossary.rst doctools/trunk/Doc-26/tutorial/inputoutput.rst doctools/trunk/Doc-26/tutorial/interactive.rst doctools/trunk/Doc-26/tutorial/interpreter.rst doctools/trunk/Doc-26/tutorial/modules.rst doctools/trunk/Doc-26/tutorial/stdlib.rst doctools/trunk/Doc-26/tutorial/stdlib2.rst doctools/trunk/Doc-26/tutorial/whatnow.rst doctools/trunk/Doc-26/whatsnew/2.3.rst doctools/trunk/Doc-26/whatsnew/2.4.rst doctools/trunk/Doc-26/whatsnew/2.6.rst doctools/trunk/Doc-3k/TODO doctools/trunk/Doc-3k/about.rst doctools/trunk/Doc-3k/c-api/concrete.rst doctools/trunk/Doc-3k/c-api/intro.rst doctools/trunk/Doc-3k/c-api/newtypes.rst doctools/trunk/Doc-3k/c-api/utilities.rst doctools/trunk/Doc-3k/distutils/index.rst doctools/trunk/Doc-3k/distutils/introduction.rst doctools/trunk/Doc-3k/extending/building.rst doctools/trunk/Doc-3k/extending/extending.rst doctools/trunk/Doc-3k/extending/newtypes.rst doctools/trunk/Doc-3k/extending/windows.rst doctools/trunk/Doc-3k/install/index.rst doctools/trunk/Doc-3k/library/array.rst doctools/trunk/Doc-3k/library/audioop.rst doctools/trunk/Doc-3k/library/codecs.rst doctools/trunk/Doc-3k/library/distutils.rst doctools/trunk/Doc-3k/library/exceptions.rst doctools/trunk/Doc-3k/library/functions.rst doctools/trunk/Doc-3k/library/objects.rst doctools/trunk/Doc-3k/library/operator.rst doctools/trunk/Doc-3k/library/parser.rst doctools/trunk/Doc-3k/library/pdb.rst doctools/trunk/Doc-3k/library/stdtypes.rst doctools/trunk/Doc-3k/library/warnings.rst doctools/trunk/Doc-3k/library/weakref.rst doctools/trunk/Doc-3k/library/webbrowser.rst doctools/trunk/Doc-3k/library/xml.etree.elementtree.rst doctools/trunk/Doc-3k/library/xml.sax.handler.rst doctools/trunk/Doc-3k/maclib/mac.rst doctools/trunk/Doc-3k/reference/datamodel.rst doctools/trunk/Doc-3k/reference/expressions.rst doctools/trunk/Doc-3k/reference/introduction.rst doctools/trunk/Doc-3k/reference/lexical_analysis.rst doctools/trunk/Doc-3k/reference/simple_stmts.rst doctools/trunk/Doc-3k/tutorial/controlflow.rst doctools/trunk/Doc-3k/tutorial/datastructures.rst doctools/trunk/Doc-3k/tutorial/errors.rst doctools/trunk/Doc-3k/tutorial/glossary.rst doctools/trunk/Doc-3k/tutorial/inputoutput.rst doctools/trunk/Doc-3k/tutorial/interactive.rst doctools/trunk/Doc-3k/tutorial/interpreter.rst doctools/trunk/Doc-3k/tutorial/modules.rst doctools/trunk/Doc-3k/tutorial/stdlib.rst doctools/trunk/Doc-3k/tutorial/stdlib2.rst doctools/trunk/Doc-3k/tutorial/whatnow.rst doctools/trunk/Doc-3k/whatsnew/2.3.rst doctools/trunk/Doc-3k/whatsnew/2.4.rst doctools/trunk/Doc-3k/whatsnew/2.6.rst Log: Replace all previously inter-document links by :ref:s. Modified: doctools/trunk/Doc-26/TODO ============================================================================== --- doctools/trunk/Doc-26/TODO (original) +++ doctools/trunk/Doc-26/TODO Thu Aug 2 20:07:46 2007 @@ -1,7 +1,6 @@ To do after conversion ====================== -* fix all references and links marked with `XXX` * split very large files and add toctrees * integrate standalone HOWTOs * find out which files get "comments disabled" metadata Modified: doctools/trunk/Doc-26/about.rst ============================================================================== --- doctools/trunk/Doc-26/about.rst (original) +++ doctools/trunk/Doc-26/about.rst Thu Aug 2 20:07:46 2007 @@ -2,6 +2,7 @@ About these documents ===================== + These documents are generated from `reStructuredText `_ sources by *Sphinx*, a document processor specifically written for the Python documentation. @@ -15,4 +16,6 @@ See :ref:`reporting-bugs` for information how to report bugs in Python itself. -.. include:: ACKS \ No newline at end of file +.. % include the ACKS file here so that it can be maintained separately + +.. include:: ACKS Modified: doctools/trunk/Doc-26/c-api/concrete.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/concrete.rst (original) +++ doctools/trunk/Doc-26/c-api/concrete.rst Thu Aug 2 20:07:46 2007 @@ -2201,22 +2201,19 @@ .. cfunction:: PyObject* PyDict_Items(PyObject *p) Return a :ctype:`PyListObject` containing all the items from the dictionary, as - in the dictionary method :meth:`items` (see the Python Library Reference (XXX - reference: ../lib/lib.html)). + in the dictionary method :meth:`dict.items`. .. cfunction:: PyObject* PyDict_Keys(PyObject *p) Return a :ctype:`PyListObject` containing all the keys from the dictionary, as - in the dictionary method :meth:`keys` (see the Python Library Reference (XXX - reference: ../lib/lib.html)). + in the dictionary method :meth:`dict.keys`. .. cfunction:: PyObject* PyDict_Values(PyObject *p) Return a :ctype:`PyListObject` containing all the values from the dictionary - *p*, as in the dictionary method :meth:`values` (see the Python Library - Reference (XXX reference: ../lib/lib.html)). + *p*, as in the dictionary method :meth:`dict.values`. .. cfunction:: Py_ssize_t PyDict_Size(PyObject *p) Modified: doctools/trunk/Doc-26/c-api/intro.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/intro.rst (original) +++ doctools/trunk/Doc-26/c-api/intro.rst Thu Aug 2 20:07:46 2007 @@ -99,12 +99,11 @@ deallocated, they are typically static :ctype:`PyTypeObject` objects. All Python objects (even Python integers) have a :dfn:`type` and a -:dfn:`reference count`. An object's type determines what kind of object it is -(e.g., an integer, a list, or a user-defined function; there are many more as -explained in the Python Reference Manual (XXX reference: ../ref/ref.html)). For -each of the well-known types there is a macro to check whether an object is of -that type; for instance, ``PyList_Check(a)`` is true if (and only if) the object -pointed to by *a* is a Python list. +:dfn:`reference count`. An object's type determines what kind of object it is +(e.g., an integer, a list, or a user-defined function; there are many more as +explained in :ref:`types`). For each of the well-known types there is a macro +to check whether an object is of that type; for instance, ``PyList_Check(a)`` is +true if (and only if) the object pointed to by *a* is a Python list. .. _api-refcounts: Modified: doctools/trunk/Doc-26/c-api/newtypes.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/newtypes.rst (original) +++ doctools/trunk/Doc-26/c-api/newtypes.rst Thu Aug 2 20:07:46 2007 @@ -610,17 +610,17 @@ This field is inherited by subtypes. -PyNumberMethods \*tp_as_number; +.. cmember:: PyNumberMethods *tp_as_number; -XXX + XXX -PySequenceMethods \*tp_as_sequence; +.. cmember:: PySequenceMethods *tp_as_sequence; -XXX + XXX -PyMappingMethods \*tp_as_mapping; +.. cmember:: PyMappingMethods *tp_as_mapping; -XXX + XXX .. cmember:: hashfunc PyTypeObject.tp_hash @@ -842,12 +842,13 @@ .. data:: Py_TPFLAGS_HAVE_GC - This bit is set when the object supports garbage collection. If this bit is - set, instances must be created using :cfunc:`PyObject_GC_New` and destroyed - using :cfunc:`PyObject_GC_Del`. More information in section XXX about garbage - collection. This bit also implies that the GC-related fields - :attr:`tp_traverse` and :attr:`tp_clear` are present in the type object; but - those fields also exist when :const:`Py_TPFLAGS_HAVE_GC` is clear but + This bit is set when the object supports garbage collection. If this bit + is set, instances must be created using :cfunc:`PyObject_GC_New` and + destroyed using :cfunc:`PyObject_GC_Del`. More information in section + :ref:`supporting-cycle-detection`. This bit also implies that the + GC-related fields :attr:`tp_traverse` and :attr:`tp_clear` are present in + the type object; but those fields also exist when + :const:`Py_TPFLAGS_HAVE_GC` is clear but :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` is set. @@ -1598,9 +1599,8 @@ other objects, or which only store references to atomic types (such as numbers or strings), do not need to provide any explicit support for garbage collection. -An example showing the use of these interfaces can be found in "Supporting the -Cycle Collector (XXX reference: ../ext/example-cycle-support.html)" in Extending -and Embedding the Python Interpreter (XXX reference: ../ext/ext.html). +.. An example showing the use of these interfaces can be found in "Supporting the +.. Cycle Collector (XXX reference: ../ext/example-cycle-support.html)". To create a container type, the :attr:`tp_flags` field of the type object must include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the Modified: doctools/trunk/Doc-26/c-api/utilities.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/utilities.rst (original) +++ doctools/trunk/Doc-26/c-api/utilities.rst Thu Aug 2 20:07:46 2007 @@ -370,6 +370,7 @@ .. versionchanged:: 2.4 *version* indicates the file format. + The following functions allow marshalled values to be read back in. XXX What about error detection? It appears that reading past the end of the @@ -425,8 +426,8 @@ ===================================== These functions are useful when creating your own extensions functions and -methods. Additional information and examples are available in Extending and -Embedding the Python Interpreter (XXX reference: ../ext/ext.html). +methods. Additional information and examples are available in +:ref:`extending-index`. The first three of these functions described, :cfunc:`PyArg_ParseTuple`, :cfunc:`PyArg_ParseTupleAndKeywords`, and :cfunc:`PyArg_Parse`, all use *format Modified: doctools/trunk/Doc-26/distutils/index.rst ============================================================================== --- doctools/trunk/Doc-26/distutils/index.rst (original) +++ doctools/trunk/Doc-26/distutils/index.rst Thu Aug 2 20:07:46 2007 @@ -4,6 +4,8 @@ Distributing Python Modules ############################### +:Authors: Greg Ward, Anthony Baxter +:Email: distutils-sig at python.org :Release: |version| :Date: |today| Modified: doctools/trunk/Doc-26/distutils/introduction.rst ============================================================================== --- doctools/trunk/Doc-26/distutils/introduction.rst (original) +++ doctools/trunk/Doc-26/distutils/introduction.rst Thu Aug 2 20:07:46 2007 @@ -6,8 +6,8 @@ This document covers using the Distutils to distribute your Python modules, concentrating on the role of developer/distributor: if you're looking for -information on installing Python modules, you should refer to the Installing -Python Modules (XXX reference: ../inst/inst.html) manual. +information on installing Python modules, you should refer to the +:ref:`install-index` chapter. .. _distutils-concepts: Modified: doctools/trunk/Doc-26/extending/building.rst ============================================================================== --- doctools/trunk/Doc-26/extending/building.rst (original) +++ doctools/trunk/Doc-26/extending/building.rst Thu Aug 2 20:07:46 2007 @@ -52,7 +52,7 @@ information to build packages, and it specifies the contents of the package. Normally, a package will contain of addition modules, like Python source modules, documentation, subpackages, etc. Please refer to the distutils -documentation in Distributing Python Modules (XXX reference: ../dist/dist.html) +documentation in :ref:`distutils-index` to learn more about the features of distutils; this section explains building extension modules only. Modified: doctools/trunk/Doc-26/extending/extending.rst ============================================================================== --- doctools/trunk/Doc-26/extending/extending.rst (original) +++ doctools/trunk/Doc-26/extending/extending.rst Thu Aug 2 20:07:46 2007 @@ -117,8 +117,8 @@ traceback in case the error originated in Python code. These three variables are the C equivalents of the Python variables ``sys.exc_type``, ``sys.exc_value`` and ``sys.exc_traceback`` (see the section on module -:mod:`sys` in the Python Library Reference (XXX reference: ../lib/lib.html)). -It is important to know about them to understand how errors are passed around. +:mod:`sys` in the Python Library Reference). It is important to know about them +to understand how errors are passed around. The Python API defines a number of functions to set various types of exceptions. @@ -212,8 +212,7 @@ Note that the Python name for the exception object is :exc:`spam.error`. The :cfunc:`PyErr_NewException` function may create a class with the base class being :exc:`Exception` (unless another class is passed in instead of *NULL*), -described in the Python Library Reference (XXX reference: ../lib/lib.html) under -"Built-in Exceptions." +described in :ref:`bltin-exceptions`. Note also that the :cdata:`SpamError` variable retains a reference to the newly created exception class; this is intentional! Since the exception could be @@ -550,10 +549,9 @@ The *arg* argument must be a tuple object containing an argument list passed from Python to a C function. The *format* argument must be a format string, -whose syntax is explained in "Parsing arguments and building values (XXX -reference: ../api/arg-parsing.html)" in the Python/C API Reference Manual (XXX -reference: ../api/api.html). The remaining arguments must be addresses of -variables whose type is determined by the format string. +whose syntax is explained in :ref:`arg-parsing` in the Python/C API Reference +Manual. The remaining arguments must be addresses of variables whose type is +determined by the format string. Note that while :cfunc:`PyArg_ParseTuple` checks that the Python arguments have the required types, it cannot check the validity of the addresses of C variables @@ -816,7 +814,7 @@ The cycle detector is able to detect garbage cycles and can reclaim them so long as there are no finalizers implemented in Python (:meth:`__del__` methods). When there are such finalizers, the detector exposes the cycles through the -:mod:`gc` module (XXX reference: ../lib/module-gc.html) (specifically, the +:mod:`gc` module (specifically, the ``garbage`` variable in that module). The :mod:`gc` module also exposes a way to run the detector (the :func:`collect` function), as well as configuration interfaces and the ability to disable the detector at runtime. The cycle @@ -1257,8 +1255,7 @@ Finally it should be mentioned that CObjects offer additional functionality, which is especially useful for memory allocation and deallocation of the pointer stored in a CObject. The details are described in the Python/C API Reference -Manual (XXX reference: ../api/api.html) in the section "CObjects (XXX reference: -../api/cObjects.html)" and in the implementation of CObjects (files +Manual in the section :ref:`cobjects` and in the implementation of CObjects (files :file:`Include/cobject.h` and :file:`Objects/cobject.c` in the Python source code distribution). Modified: doctools/trunk/Doc-26/extending/newtypes.rst ============================================================================== --- doctools/trunk/Doc-26/extending/newtypes.rst (original) +++ doctools/trunk/Doc-26/extending/newtypes.rst Thu Aug 2 20:07:46 2007 @@ -1355,9 +1355,8 @@ ------------------------- Python supports a variety of *abstract* 'protocols;' the specific interfaces -provided to use these interfaces are documented in the Python/C API Reference -Manual (XXX reference: ../api/api.html) in the chapter "Abstract Objects Layer -(XXX reference: ../api/abstract.html)." +provided to use these interfaces are documented in :ref:`abstract`. + A number of these abstract interfaces were defined early in the development of the Python implementation. In particular, the number, mapping, and sequence Modified: doctools/trunk/Doc-26/extending/windows.rst ============================================================================== --- doctools/trunk/Doc-26/extending/windows.rst (original) +++ doctools/trunk/Doc-26/extending/windows.rst Thu Aug 2 20:07:46 2007 @@ -36,13 +36,11 @@ =================== There are two approaches to building extension modules on Windows, just as there -are on Unix: use the :mod:`distutils` (XXX reference: ../lib/module- -distutils.html) package to control the build process, or do things manually. -The distutils approach works well for most extensions; documentation on using -:mod:`distutils` (XXX reference: ../lib/module-distutils.html) to build and -package extension modules is available in Distributing Python Modules (XXX -reference: ../dist/dist.html). This section describes the manual approach to -building Python extensions written in C or C++. +are on Unix: use the :mod:`distutils` package to control the build process, or +do things manually. The distutils approach works well for most extensions; +documentation on using :mod:`distutils` to build and package extension modules +is available in :ref:`distutils-index`. This section describes the manual +approach to building Python extensions written in C or C++. To build extensions using these instructions, you need to have a copy of the Python sources of the same version as your installed Python. You will need Modified: doctools/trunk/Doc-26/install/index.rst ============================================================================== --- doctools/trunk/Doc-26/install/index.rst (original) +++ doctools/trunk/Doc-26/install/index.rst Thu Aug 2 20:07:46 2007 @@ -1,12 +1,14 @@ -.. _install-index: - .. highlightlang:: none +.. _install-index: + ***************************** Installing Python Modules ***************************** :Author: Greg Ward +:Release: |version| +:Date: |today| .. % TODO: .. % Fill in XXX comments @@ -21,8 +23,6 @@ .. % Finally, it might be useful to include all the material from my "Care .. % and Feeding of a Python Installation" talk in here somewhere. Yow! -XXX: input{boilerplate} :XXX - .. topic:: Abstract This document describes the Python Distribution Utilities ("Distutils") from the @@ -30,17 +30,6 @@ standard Python installation by building and installing third-party Python modules and extensions. -.. % \begin{abstract} -.. % \noindent -.. % Abstract this! -.. % \end{abstract} - -.. % The ugly "%begin{latexonly}" pseudo-environment suppresses the table -.. % of contents for HTML generation. -.. % -.. % begin{latexonly} -.. % end{latexonly} - .. _inst-intro: @@ -64,7 +53,7 @@ document; there will be some brief forays into using Python's interactive mode to explore your installation, but that's it. If you're looking for information on how to distribute your own Python modules so that others may use them, see -the Distributing Python Modules (XXX reference: ../dist/dist.html) manual. +the :ref:`distutils-index` manual. .. _inst-trivial-install: @@ -728,7 +717,7 @@ (2) On Unix, if the :envvar:`HOME` environment variable is not defined, the user's home directory will be determined with the :func:`getpwuid` function from the - standard :mod:`pwd` (XXX reference: ../lib/module-pwd.html) module. + standard :mod:`pwd` module. (3) I.e., in the current directory (usually the location of the setup script). @@ -1020,4 +1009,3 @@ .. [#] Then you have no POSIX emulation available, but you also don't need :file:`cygwin1.dll`. - Modified: doctools/trunk/Doc-26/library/array.rst ============================================================================== --- doctools/trunk/Doc-26/library/array.rst (original) +++ doctools/trunk/Doc-26/library/array.rst Thu Aug 2 20:07:46 2007 @@ -112,8 +112,7 @@ effectively make use of this information), it makes more sense to use the buffer interface supported by array objects. This method is maintained for backward compatibility and should be avoided in new code. The buffer interface is - documented in the Python/C API Reference Manual (XXX reference: - ../api/newTypes.html). + documented in :ref:`bufferobjects`. .. method:: array.byteswap() Modified: doctools/trunk/Doc-26/library/ast.rst ============================================================================== --- doctools/trunk/Doc-26/library/ast.rst (original) +++ doctools/trunk/Doc-26/library/ast.rst Thu Aug 2 20:07:46 2007 @@ -1,13 +1,11 @@ -.. % XXX Label can't be _ast? -.. % XXX Where should this section/chapter go? - - .. _ast: ********************* Abstract Syntax Trees ********************* +.. module:: _ast + .. sectionauthor:: Martin v. L?wis Modified: doctools/trunk/Doc-26/library/audioop.rst ============================================================================== --- doctools/trunk/Doc-26/library/audioop.rst (original) +++ doctools/trunk/Doc-26/library/audioop.rst Thu Aug 2 20:07:46 2007 @@ -191,11 +191,7 @@ .. function:: rms(fragment, width) - Return the root-mean-square of the fragment, i.e. :: - - XXX: translate this math - \catcode`_=8 - \sqrt{\frac{\sum{{S_{i}}^{2}}}{n}} + Return the root-mean-square of the fragment, i.e. ``sqrt(sum(S_i^2)/n)``. This is a measure of the power in an audio signal. Modified: doctools/trunk/Doc-26/library/codecs.rst ============================================================================== --- doctools/trunk/Doc-26/library/codecs.rst (original) +++ doctools/trunk/Doc-26/library/codecs.rst Thu Aug 2 20:07:46 2007 @@ -1141,11 +1141,7 @@ .. module:: encodings.idna :synopsis: Internationalized Domain Names implementation - - -.. % XXX The next line triggers a formatting bug, so it's commented out -.. % until that can be fixed. -.. % \moduleauthor{Martin v. L\"owis} +.. moduleauthor:: Martin v. L?wis .. versionadded:: 2.3 @@ -1204,13 +1200,10 @@ :mod:`encodings.utf_8_sig` --- UTF-8 codec with BOM signature ------------------------------------------------------------- -.. module:: encodings.utf-8-sig +.. module:: encodings.utf_8_sig :synopsis: UTF-8 codec with BOM signature .. moduleauthor:: Walter D?rwald - -.. % XXX utf_8_sig gives TeX errors - .. versionadded:: 2.5 This module implements a variant of the UTF-8 codec: On encoding a UTF-8 encoded Modified: doctools/trunk/Doc-26/library/distutils.rst ============================================================================== --- doctools/trunk/Doc-26/library/distutils.rst (original) +++ doctools/trunk/Doc-26/library/distutils.rst Thu Aug 2 20:07:46 2007 @@ -13,23 +13,17 @@ 100%-pure Python, or may be extension modules written in C, or may be collections of Python packages which include modules coded in both Python and C. -This package is discussed in two separate documents which are included in the -Python documentation package. To learn about distributing new modules using the -:mod:`distutils` facilities, read Distributing Python Modules (XXX reference: -../dist/dist.html); this includes documentation needed to extend distutils. To -learn about installing Python modules, whether or not the author made use of the -:mod:`distutils` package, read Installing Python Modules (XXX reference: -../inst/inst.html). +This package is discussed in two separate chapters: .. seealso:: - `Distributing Python Modules <../dist/dist.html>`_ + :ref:`distutils-index` The manual for developers and packagers of Python modules. This describes how to prepare :mod:`distutils`\ -based packages so that they may be easily installed into an existing Python installation. - `Installing Python Modules <../inst/inst.html>`_ + :ref:`install-index` An "administrators" manual which includes information on installing modules into an existing Python installation. You do not need to be a Python programmer to read this manual. Modified: doctools/trunk/Doc-26/library/exceptions.rst ============================================================================== --- doctools/trunk/Doc-26/library/exceptions.rst (original) +++ doctools/trunk/Doc-26/library/exceptions.rst Thu Aug 2 20:07:46 2007 @@ -1,3 +1,4 @@ +.. _bltin-exceptions: Built-in Exceptions =================== @@ -40,8 +41,8 @@ The built-in exception classes can be sub-classed to define new exceptions; programmers are encouraged to at least derive new exceptions from the :exc:`Exception` class and not :exc:`BaseException`. More information on -defining exceptions is available in the Python Tutorial (XXX reference: -../tut/tut.html) under the heading "User-defined Exceptions." +defining exceptions is available in the Python Tutorial under +:ref:`tut-userexceptions`. The following exceptions are only used as base classes for other exceptions. Modified: doctools/trunk/Doc-26/library/functions.rst ============================================================================== --- doctools/trunk/Doc-26/library/functions.rst (original) +++ doctools/trunk/Doc-26/library/functions.rst Thu Aug 2 20:07:46 2007 @@ -154,8 +154,7 @@ def f(cls, arg1, arg2, ...): ... The ``@classmethod`` form is a function decorator -- see the description of - function definitions in chapter 7 of the Python Reference Manual (XXX reference: - ../ref/ref.html) for details. + function definitions in :ref:`function` for details. It can be called either on the class (such as ``C.f()``) or on an instance (such as ``C().f()``). The instance is ignored except for its class. If a class @@ -166,8 +165,7 @@ see :func:`staticmethod` in this section. For more information on class methods, consult the documentation on the standard - type hierarchy in chapter 3 of the Python Reference Manual (XXX reference: - ../ref/types.html) (at the bottom). + type hierarchy in :ref:`types`. .. versionadded:: 2.2 @@ -1063,8 +1061,7 @@ def f(arg1, arg2, ...): ... The ``@staticmethod`` form is a function decorator -- see the description of - function definitions in chapter 7 of the Python Reference Manual (XXX reference: - ../ref/function.html) for details. + function definitions in :ref:`function` for details. It can be called either on the class (such as ``C.f()``) or on an instance (such as ``C().f()``). The instance is ignored except for its class. @@ -1073,8 +1070,7 @@ advanced concept, see :func:`classmethod` in this section. For more information on static methods, consult the documentation on the - standard type hierarchy in chapter 3 of the Python Reference Manual (XXX - reference: ../ref/types.html) (at the bottom). + standard type hierarchy in :ref:`types`. .. versionadded:: 2.2 Modified: doctools/trunk/Doc-26/library/objects.rst ============================================================================== --- doctools/trunk/Doc-26/library/objects.rst (original) +++ doctools/trunk/Doc-26/library/objects.rst Thu Aug 2 20:07:46 2007 @@ -22,8 +22,8 @@ in order of ascending priority (within a table) and grouping operators that have the same priority in the same box. Binary operators of the same priority group from left to right. (Unary operators group from right to left, but there you -have no real choice.) See chapter 5 of the Python Reference Manual (XXX -reference: ../ref/ref.html) for the complete picture on operator priorities. +have no real choice.) See :ref:`operator-summary` for the complete picture on +operator priorities. .. rubric:: Footnotes Modified: doctools/trunk/Doc-26/library/operator.rst ============================================================================== --- doctools/trunk/Doc-26/library/operator.rst (original) +++ doctools/trunk/Doc-26/library/operator.rst Thu Aug 2 20:07:46 2007 @@ -36,13 +36,12 @@ __gt__(a, b) Perform "rich comparisons" between *a* and *b*. Specifically, ``lt(a, b)`` is - equivalent to ``a < b``, ``le(a, b)`` is equivalent to ``a <= b``, ``eq(a, b)`` - is equivalent to ``a == b``, ``ne(a, b)`` is equivalent to ``a != b``, ``gt(a, - b)`` is equivalent to ``a > b`` and ``ge(a, b)`` is equivalent to ``a >= b``. - Note that unlike the built-in :func:`cmp`, these functions can return any value, - which may or may not be interpretable as a Boolean value. See the Python - Reference Manual (XXX reference: ../ref/ref.html) for more information about - rich comparisons. + equivalent to ``a < b``, ``le(a, b)`` is equivalent to ``a <= b``, ``eq(a, + b)`` is equivalent to ``a == b``, ``ne(a, b)`` is equivalent to ``a != b``, + ``gt(a, b)`` is equivalent to ``a > b`` and ``ge(a, b)`` is equivalent to ``a + >= b``. Note that unlike the built-in :func:`cmp`, these functions can + return any value, which may or may not be interpretable as a Boolean value. + See :ref:`comparisons` for more information about rich comparisons. .. versionadded:: 2.2 Modified: doctools/trunk/Doc-26/library/parser.rst ============================================================================== --- doctools/trunk/Doc-26/library/parser.rst (original) +++ doctools/trunk/Doc-26/library/parser.rst Thu Aug 2 20:07:46 2007 @@ -32,7 +32,7 @@ Most importantly, a good understanding of the Python grammar processed by the internal parser is required. For full information on the language syntax, refer -to the Python Language Reference (XXX reference: ../ref/ref.html). The parser +to :ref:`reference-index`. The parser itself is created from a grammar specification defined in the file :file:`Grammar/Grammar` in the standard Python distribution. The parse trees stored in the AST objects created by this module are the actual output from the Modified: doctools/trunk/Doc-26/library/pdb.rst ============================================================================== --- doctools/trunk/Doc-26/library/pdb.rst (original) +++ doctools/trunk/Doc-26/library/pdb.rst Thu Aug 2 20:07:46 2007 @@ -406,6 +406,5 @@ Note that as an exception is propagated down the chain of callers, an ``'exception'`` event is generated at each level. -For more information on code and frame objects, refer to the Python Reference -Manual (XXX reference: ../ref/ref.html). +For more information on code and frame objects, refer to :ref:`types`. Modified: doctools/trunk/Doc-26/library/stdtypes.rst ============================================================================== --- doctools/trunk/Doc-26/library/stdtypes.rst (original) +++ doctools/trunk/Doc-26/library/stdtypes.rst Thu Aug 2 20:07:46 2007 @@ -26,10 +26,7 @@ practically all objects can be compared, tested for truth value, and converted to a string (with the :func:`repr` function or the slightly different :func:`str` function). The latter function is implicitly used when an object is -written by the :keyword:`print` statement. (Information on the :keyword:`print` -statement (XXX reference: ../ref/print.html) and other language statements can -be found in the Python Reference Manual (XXX reference: ../ref/ref.html) and the -Python Tutorial (XXX reference: ../tut/tut.html).) +written by the :func:`print` function. .. _truth: @@ -186,10 +183,9 @@ .. index:: single: __cmp__() (instance method) -Instances of a class normally compare as non-equal unless the class defines the -:meth:`__cmp__` method. Refer to the Python Reference Manual (XXX reference: -../ref/customization.html) for information on the use of this method to effect -object comparisons. +Instances of a class normally compare as non-equal unless the class defines the +:meth:`__cmp__` method. Refer to :ref:`customization`) for information on the +use of this method to effect object comparisons. **Implementation note:** Objects of different types except numbers are ordered by their type names; objects of the same types that don't support proper @@ -498,12 +494,11 @@ object: list String literals are written in single or double quotes: ``'xyzzy'``, -``"frobozz"``. See chapter 2 of the Python Reference Manual (XXX reference: -../ref/strings.html) for more about string literals. Unicode strings are much -like strings, but are specified in the syntax using a preceding ``'u'`` -character: ``u'abc'``, ``u"def"``. Lists are constructed with square brackets, -separating items with commas: ``[a, b, c]``. Tuples are constructed by the -comma operator (not within square brackets), with or without enclosing +``"frobozz"``. See :ref:`strings` for more about string literals. Unicode +strings are much like strings, but are specified in the syntax using a preceding +``'u'`` character: ``u'abc'``, ``u"def"``. Lists are constructed with square +brackets, separating items with commas: ``[a, b, c]``. Tuples are constructed +by the comma operator (not within square brackets), with or without enclosing parentheses, but an empty tuple must have the enclosing parentheses, such as ``a, b, c`` or ``()``. A single item tuple must have a trailing comma, such as ``(d,)``. @@ -2133,8 +2128,7 @@ .. _classes and instances: -See chapters 3 and 7 of the Python Reference Manual (XXX reference: -../ref/ref.html) for these. +See :ref:`objects` and :ref:`class` for these. .. _typesfunctions: @@ -2149,8 +2143,7 @@ defined functions. Both support the same operation (to call the function), but the implementation is different, hence the different object types. -See the Python Reference Manual (XXX reference: ../ref/ref.html) for more -information. +See :ref:`function` for more information. .. _typesmethods: @@ -2192,8 +2185,7 @@ c = C() c.method.im_func.whoami = 'my name is c' -See the Python Reference Manual (XXX reference: ../ref/ref.html) for more -information. +See :ref:`types` for more information. .. _bltin-code-objects: @@ -2221,8 +2213,7 @@ A code object can be executed or evaluated by passing it (instead of a source string) to the :keyword:`exec` statement or the built-in :func:`eval` function. -See the Python Reference Manual (XXX reference: ../ref/ref.html) for more -information. +See :ref:`types` for more information. .. _bltin-type-objects: @@ -2259,9 +2250,9 @@ The Ellipsis Object ------------------- -This object is used by extended slice notation (see the Python Reference Manual -(XXX reference: ../ref/ref.html)). It supports no special operations. There is -exactly one ellipsis object, named :const:`Ellipsis` (a built-in name). +This object is used by extended slice notation (see :ref:`slicings`). It +supports no special operations. There is exactly one ellipsis object, named +:const:`Ellipsis` (a built-in name). It is written as ``Ellipsis``. @@ -2290,9 +2281,8 @@ Internal Objects ---------------- -See the Python Reference Manual (XXX reference: ../ref/ref.html) for this -information. It describes stack frame objects, traceback objects, and slice -objects. +See :ref:`types` for this information. It describes stack frame objects, +traceback objects, and slice objects. .. _specialattrs: @@ -2342,8 +2332,8 @@ .. rubric:: Footnotes -.. [#] Additional information on these special methods may be found in the Python - Reference Manual (XXX reference: ../ref/ref.html). +.. [#] Additional information on these special methods may be found in the Python + Reference Manual (:ref:`customization`). .. [#] As a consequence, the list ``[1, 2]`` is considered equal to ``[1.0, 2.0]``, and similarly for tuples. Modified: doctools/trunk/Doc-26/library/warnings.rst ============================================================================== --- doctools/trunk/Doc-26/library/warnings.rst (original) +++ doctools/trunk/Doc-26/library/warnings.rst Thu Aug 2 20:07:46 2007 @@ -16,8 +16,8 @@ might want to issue a warning when a program uses an obsolete module. Python programmers issue warnings by calling the :func:`warn` function defined -in this module. (C programmers use :cfunc:`PyErr_Warn`; see the Python/C API -Reference Manual (XXX reference: ../api/exceptionHandling.html) for details). +in this module. (C programmers use :cfunc:`PyErr_Warn`; see +:ref:`exceptionhandling` for details). Warning messages are normally written to ``sys.stderr``, but their disposition can be changed flexibly, from ignoring all warnings to turning them into Modified: doctools/trunk/Doc-26/library/weakref.rst ============================================================================== --- doctools/trunk/Doc-26/library/weakref.rst (original) +++ doctools/trunk/Doc-26/library/weakref.rst Thu Aug 2 20:07:46 2007 @@ -65,14 +65,8 @@ obj = Dict(red=1, green=2, blue=3) # this object is weak referencable -Extension types can easily be made to support weak references; see "Weak -Reference Support (XXX reference: ../ext/weakref-support.html)" in Extending and -Embedding the Python Interpreter (XXX reference: ../ext/ext.html). - -.. % The referenced section used to appear in this document with the -.. % \label weakref-extension. It would be good to be able to generate a -.. % redirect for the corresponding HTML page (weakref-extension.html) -.. % for on-line versions of this document. +Extension types can easily be made to support weak references; see +:ref:`weakref-support`. .. class:: ref(object[, callback]) Modified: doctools/trunk/Doc-26/library/webbrowser.rst ============================================================================== --- doctools/trunk/Doc-26/library/webbrowser.rst (original) +++ doctools/trunk/Doc-26/library/webbrowser.rst Thu Aug 2 20:07:46 2007 @@ -151,9 +151,7 @@ Only on Windows platforms. (3) - Only on MacOS platforms; requires the standard MacPython :mod:`ic` module, - described in the Macintosh Library Modules (XXX reference: ../mac/module- - ic.html) manual. + Only on MacOS platforms; requires the standard MacPython :mod:`ic` module. (4) Only on MacOS X platform. Modified: doctools/trunk/Doc-26/library/xml.etree.elementtree.rst ============================================================================== --- doctools/trunk/Doc-26/library/xml.etree.elementtree.rst (original) +++ doctools/trunk/Doc-26/library/xml.etree.elementtree.rst Thu Aug 2 20:07:46 2007 @@ -267,7 +267,7 @@ .. method:: Element.remove(subelement) - Removes *subelement* from the element. Unlike the findXXX methods this method + Removes *subelement* from the element. Unlike the findXYZ methods this method compares elements based on the instance identity, not on tag value or contents. Element objects also support the following sequence type methods for working Modified: doctools/trunk/Doc-26/library/xml.sax.handler.rst ============================================================================== --- doctools/trunk/Doc-26/library/xml.sax.handler.rst (original) +++ doctools/trunk/Doc-26/library/xml.sax.handler.rst Thu Aug 2 20:07:46 2007 @@ -207,7 +207,7 @@ information to the application to expand prefixes in those contexts itself, if necessary. - .. % % XXX This is not really the default, is it? MvL + .. % XXX This is not really the default, is it? MvL Note that :meth:`startPrefixMapping` and :meth:`endPrefixMapping` events are not guaranteed to be properly nested relative to each-other: all @@ -232,7 +232,7 @@ The *name* parameter contains the raw XML 1.0 name of the element type as a string and the *attrs* parameter holds an object of the :class:`Attributes` - interface (XXX reference: attributes-objects.html) containing the attributes of + interface (see :ref:`attributes-objects`) containing the attributes of the element. The object passed as *attrs* may be re-used by the parser; holding on to a reference to it is not a reliable way to keep a copy of the attributes. To keep a copy of the attributes, use the :meth:`copy` method of the *attrs* @@ -254,7 +254,7 @@ The *name* parameter contains the name of the element type as a ``(uri, localname)`` tuple, the *qname* parameter contains the raw XML 1.0 name used in the source document, and the *attrs* parameter holds an instance of the - :class:`AttributesNS` interface (XXX reference: attributes-ns-objects.html) + :class:`AttributesNS` interface (see :ref:`attributes-ns-objects`) containing the attributes of the element. If no namespace is associated with the element, the *uri* component of *name* will be ``None``. The object passed as *attrs* may be re-used by the parser; holding on to a reference to it is not Modified: doctools/trunk/Doc-26/maclib/mac.rst ============================================================================== --- doctools/trunk/Doc-26/maclib/mac.rst (original) +++ doctools/trunk/Doc-26/maclib/mac.rst Thu Aug 2 20:07:46 2007 @@ -11,8 +11,8 @@ This module is the Mac OS 9 (and earlier) implementation of the :mod:`os.path` module. It can be used to manipulate old-style Macintosh pathnames on Mac OS X -(or any other platform). Refer to the Python Library Reference (XXX reference: -../lib/lib.html) for documentation of :mod:`os.path`. +(or any other platform). Refer to the Python Library Reference for documentation +of :mod:`os.path`. The following functions are available in this module: :func:`normcase`, :func:`normpath`, :func:`isabs`, :func:`join`, :func:`split`, :func:`isdir`, Modified: doctools/trunk/Doc-26/reference/datamodel.rst ============================================================================== --- doctools/trunk/Doc-26/reference/datamodel.rst (original) +++ doctools/trunk/Doc-26/reference/datamodel.rst Thu Aug 2 20:07:46 2007 @@ -60,8 +60,8 @@ reference-counting scheme with (optional) delayed detection of cyclically linked garbage, which collects most objects as soon as they become unreachable, but is not guaranteed to collect garbage containing circular references. See the -Python Library Reference (XXX reference: ../lib/module-gc.html) for information -on controlling the collection of cyclic garbage.) +documentation of the :mod:`gc` module for information on controlling the +collection of cyclic garbage.) Note that the use of the implementation's tracing or debugging facilities may keep objects alive that would normally be collectable. Also note that catching @@ -862,12 +862,12 @@ single: stderr (in module sys) A file object represents an open file. File objects are created by the - :func:`open` built-in function, and also by :func:`os.popen`, :func:`os.fdopen`, - and the :meth:`makefile` method of socket objects (and perhaps by other - functions or methods provided by extension modules). The objects ``sys.stdin``, - ``sys.stdout`` and ``sys.stderr`` are initialized to file objects corresponding - to the interpreter's standard input, output and error streams. See the Python - Library Reference (XXX reference: ../lib/lib.html) for complete documentation of + :func:`open` built-in function, and also by :func:`os.popen`, + :func:`os.fdopen`, and the :meth:`makefile` method of socket objects (and + perhaps by other functions or methods provided by extension modules). The + objects ``sys.stdin``, ``sys.stdout`` and ``sys.stderr`` are initialized to + file objects corresponding to the interpreter's standard input, output and + error streams. See :ref:`bltin-file-objects` for complete documentation of file objects. Internal types @@ -1217,24 +1217,25 @@ .. note:: - ``del x`` doesn't directly call ``x.__del__()`` --- the former decrements the - reference count for ``x`` by one, and the latter is only called when ``x``'s - reference count reaches zero. Some common situations that may prevent the - reference count of an object from going to zero include: circular references - between objects (e.g., a doubly-linked list or a tree data structure with parent - and child pointers); a reference to the object on the stack frame of a function - that caught an exception (the traceback stored in ``sys.exc_traceback`` keeps - the stack frame alive); or a reference to the object on the stack frame that - raised an unhandled exception in interactive mode (the traceback stored in - ``sys.last_traceback`` keeps the stack frame alive). The first situation can - only be remedied by explicitly breaking the cycles; the latter two situations - can be resolved by storing ``None`` in ``sys.exc_traceback`` or - ``sys.last_traceback``. Circular references which are garbage are detected when - the option cycle detector is enabled (it's on by default), but can only be - cleaned up if there are no Python-level :meth:`__del__` methods involved. Refer - to the documentation for the :mod:`gc` module (XXX reference: ../lib/module- - gc.html) for more information about how :meth:`__del__` methods are handled by - the cycle detector, particularly the description of the ``garbage`` value. + ``del x`` doesn't directly call ``x.__del__()`` --- the former decrements + the reference count for ``x`` by one, and the latter is only called when + ``x``'s reference count reaches zero. Some common situations that may + prevent the reference count of an object from going to zero include: + circular references between objects (e.g., a doubly-linked list or a tree + data structure with parent and child pointers); a reference to the object + on the stack frame of a function that caught an exception (the traceback + stored in ``sys.exc_traceback`` keeps the stack frame alive); or a + reference to the object on the stack frame that raised an unhandled + exception in interactive mode (the traceback stored in + ``sys.last_traceback`` keeps the stack frame alive). The first situation + can only be remedied by explicitly breaking the cycles; the latter two + situations can be resolved by storing ``None`` in ``sys.exc_traceback`` or + ``sys.last_traceback``. Circular references which are garbage are + detected when the option cycle detector is enabled (it's on by default), + but can only be cleaned up if there are no Python-level :meth:`__del__` + methods involved. Refer to the documentation for the :mod:`gc` module for + more information about how :meth:`__del__` methods are handled by the + cycle detector, particularly the description of the ``garbage`` value. .. warning:: @@ -1824,9 +1825,7 @@ should also be made available as the method :meth:`iterkeys`. Iterator objects also need to implement this method; they are required to return - themselves. For more information on iterator objects, see "Iterator Types (XXX - reference: ../lib/typeiter.html)" in the Python Library Reference (XXX - reference: ../lib/lib.html). + themselves. For more information on iterator objects, see :ref:`typeiter`. The membership test operators (:keyword:`in` and :keyword:`not in`) are normally implemented as an iteration through a sequence. However, container objects can @@ -2231,9 +2230,7 @@ Typical uses of context managers include saving and restoring various kinds of global state, locking and unlocking resources, closing opened files, etc. -For more information on context managers, see "Context Types (XXX reference: -../lib/typecontextmanager.html)" in the Python Library Reference (XXX reference: -../lib/lib.html). +For more information on context managers, see :ref:`typecontextmanager`. .. method:: context manager.__enter__(self) Modified: doctools/trunk/Doc-26/reference/expressions.rst ============================================================================== --- doctools/trunk/Doc-26/reference/expressions.rst (original) +++ doctools/trunk/Doc-26/reference/expressions.rst Thu Aug 2 20:07:46 2007 @@ -747,9 +747,8 @@ object: method object: function - The result is up to the interpreter; see the Python Library Reference (XXX - reference: ../lib/built-in-funcs.html) for the descriptions of built-in - functions and methods. + The result is up to the interpreter; see :ref:`built-in-funcs` for the + descriptions of built-in functions and methods. a class object: .. index:: @@ -903,8 +902,7 @@ In addition to performing the modulo operation on numbers, the ``%`` operator is also overloaded by string and unicode objects to perform string formatting (also known as interpolation). The syntax for string formatting is described in the -Python Library Reference (XXX reference: ../lib/typesseq-strings.html), section -"Sequence Types". +Python Library Reference, section :ref:`typesseq-strings`. .. deprecated:: 2.3 The floor division operator, the modulo operator, and the :func:`divmod` @@ -1241,7 +1239,7 @@ expr3, expr4 = expr1, expr2 -.. _summary: +.. _operator-summary: Summary ======= Modified: doctools/trunk/Doc-26/reference/introduction.rst ============================================================================== --- doctools/trunk/Doc-26/reference/introduction.rst (original) +++ doctools/trunk/Doc-26/reference/introduction.rst Thu Aug 2 20:07:46 2007 @@ -29,9 +29,9 @@ you'll find short "implementation notes" sprinkled throughout the text. Every Python implementation comes with a number of built-in and standard -modules. These are not documented here, but in the separate Python Library -Reference (XXX reference: ../lib/lib.html) document. A few built-in modules are -mentioned when they interact in a significant way with the language definition. +modules. These are documented in :ref:`library-index`. A few built-in modules +are mentioned when they interact in a significant way with the language +definition. .. _implementations: Modified: doctools/trunk/Doc-26/reference/lexical_analysis.rst ============================================================================== --- doctools/trunk/Doc-26/reference/lexical_analysis.rst (original) +++ doctools/trunk/Doc-26/reference/lexical_analysis.rst Thu Aug 2 20:07:46 2007 @@ -390,9 +390,9 @@ .. note:: - The name ``_`` is often used in conjunction with internationalization; refer to - the documentation for the :mod:`gettext` module (XXX reference: ../lib/module- - gettext.html) for more information on this convention. + The name ``_`` is often used in conjunction with internationalization; + refer to the documentation for the :mod:`gettext` module for more + information on this convention. ``__*__`` System-defined names. These names are defined by the interpreter and its Modified: doctools/trunk/Doc-26/reference/simple_stmts.rst ============================================================================== --- doctools/trunk/Doc-26/reference/simple_stmts.rst (original) +++ doctools/trunk/Doc-26/reference/simple_stmts.rst Thu Aug 2 20:07:46 2007 @@ -760,9 +760,8 @@ .. index:: builtin: __import__ The built-in function :func:`__import__` is provided to support applications -that determine which modules need to be loaded dynamically; refer to Built-in -Functions (XXX reference: ../lib/built-in-funcs.html) in the Python Library -Reference (XXX reference: ../lib/lib.html) for additional information. +that determine which modules need to be loaded dynamically; refer to +:ref:`built-in-funcs` for additional information. .. _future: @@ -833,8 +832,7 @@ a future statement will, by default, use the new syntax or semantics associated with the future statement. This can, starting with Python 2.2 be controlled by optional arguments to :func:`compile` --- see the documentation of that function -in the Python Library Reference (XXX reference: ../lib/built-in-funcs.html) for -details. +for details. A future statement typed at an interactive interpreter prompt will take effect for the rest of the interpreter session. If an interpreter is started with the Modified: doctools/trunk/Doc-26/tutorial/controlflow.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/controlflow.rst (original) +++ doctools/trunk/Doc-26/tutorial/controlflow.rst Thu Aug 2 20:07:46 2007 @@ -393,12 +393,12 @@ TypeError: function() got multiple values for keyword argument 'a' When a final formal parameter of the form ``**name`` is present, it receives a -dictionary (XXX reference: ../lib/typesmapping.html) containing all keyword -arguments except for those corresponding to a formal parameter. This may be -combined with a formal parameter of the form ``*name`` (described in the next -subsection) which receives a tuple containing the positional arguments beyond -the formal parameter list. (``*name`` must occur before ``**name``.) For -example, if we define a function like this:: +dictionary (see :ref:`typesmapping`) containing all keyword arguments except for +those corresponding to a formal parameter. This may be combined with a formal +parameter of the form ``*name`` (described in the next subsection) which +receives a tuple containing the positional arguments beyond the formal parameter +list. (``*name`` must occur before ``**name``.) For example, if we define a +function like this:: def cheeseshop(kind, *arguments, **keywords): print "-- Do you have any", kind, '?' Modified: doctools/trunk/Doc-26/tutorial/datastructures.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/datastructures.rst (original) +++ doctools/trunk/Doc-26/tutorial/datastructures.rst Thu Aug 2 20:07:46 2007 @@ -47,8 +47,7 @@ is specified, ``a.pop()`` removes and returns the last item in the list. (The square brackets around the *i* in the method signature denote that the parameter is optional, not that you should type square brackets at that position. You - will see this notation frequently in the Python Library Reference (XXX - reference: ../lib/lib.html).) + will see this notation frequently in the Python Library Reference.) .. method:: list.index(x) @@ -302,10 +301,10 @@ ==================== We saw that lists and strings have many common properties, such as indexing and -slicing operations. They are two examples of *sequence* data types (XXX -reference: ../lib/typesseq.html). Since Python is an evolving language, other -sequence data types may be added. There is also another standard sequence data -type: the *tuple*. +slicing operations. They are two examples of *sequence* data types (see +:ref:`typesseq`). Since Python is an evolving language, other sequence data +types may be added. There is also another standard sequence data type: the +*tuple*. A tuple consists of a number of values separated by commas, for instance:: @@ -404,9 +403,9 @@ Dictionaries ============ -Another useful data type built into Python is the *dictionary* (XXX reference: -../lib/typesmapping.html). Dictionaries are sometimes found in other languages -as "associative memories" or "associative arrays". Unlike sequences, which are +Another useful data type built into Python is the *dictionary* (see +:ref:`typesmapping`). Dictionaries are sometimes found in other languages as +"associative memories" or "associative arrays". Unlike sequences, which are indexed by a range of numbers, dictionaries are indexed by *keys*, which can be any immutable type; strings and numbers can always be keys. Tuples can be used as keys if they contain only strings, numbers, or tuples; if a tuple contains Modified: doctools/trunk/Doc-26/tutorial/errors.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/errors.rst (original) +++ doctools/trunk/Doc-26/tutorial/errors.rst Thu Aug 2 20:07:46 2007 @@ -71,8 +71,7 @@ traceback listing source lines; however, it will not display lines read from standard input. -The Python Library Reference (XXX reference: ../lib/module-exceptions.html) -lists the built-in exceptions and their meanings. +:ref:`bltin-exceptions` lists the built-in exceptions and their meanings. .. _tut-handling: Modified: doctools/trunk/Doc-26/tutorial/glossary.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/glossary.rst (original) +++ doctools/trunk/Doc-26/tutorial/glossary.rst Thu Aug 2 20:07:46 2007 @@ -118,9 +118,8 @@ from __future__ import division the expression ``11/4`` would evaluate to ``2.75``. By importing the - :mod:`__future__` (XXX reference: ../lib/module-future.html) module and - evaluating its variables, you can see when a new feature was first added to the - language and when it will become the default:: + :mod:`__future__` module and evaluating its variables, you can see when a new + feature was first added to the language and when it will become the default:: >>> import __future__ >>> __future__.division @@ -296,9 +295,8 @@ namespaces. Namespaces also aid readability and maintainability by making it clear which module implements a function. For instance, writing :func:`random.seed` or :func:`itertools.izip` makes it clear that those - functions are implemented by the :mod:`random` (XXX reference: ../lib/module- - random.html) and :mod:`itertools` (XXX reference: ../lib/module-itertools.html) - modules respectively. + functions are implemented by the :mod:`random` and :mod:`itertools` modules + respectively. .. index:: single: nested scope Modified: doctools/trunk/Doc-26/tutorial/inputoutput.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/inputoutput.rst (original) +++ doctools/trunk/Doc-26/tutorial/inputoutput.rst Thu Aug 2 20:07:46 2007 @@ -323,14 +323,13 @@ complicated. Rather than have users be constantly writing and debugging code to save -complicated data types, Python provides a standard module called :mod:`pickle` -(XXX reference: ../lib/module-pickle.html). This is an amazing module that can -take almost any Python object (even some forms of Python code!), and convert it -to a string representation; this process is called :dfn:`pickling`. -Reconstructing the object from the string representation is called -:dfn:`unpickling`. Between pickling and unpickling, the string representing the -object may have been stored in a file or data, or sent over a network connection -to some distant machine. +complicated data types, Python provides a standard module called :mod:`pickle`. +This is an amazing module that can take almost any Python object (even some +forms of Python code!), and convert it to a string representation; this process +is called :dfn:`pickling`. Reconstructing the object from the string +representation is called :dfn:`unpickling`. Between pickling and unpickling, +the string representing the object may have been stored in a file or data, or +sent over a network connection to some distant machine. If you have an object ``x``, and a file object ``f`` that's been opened for writing, the simplest way to pickle the object takes only one line of code:: @@ -344,15 +343,12 @@ (There are other variants of this, used when pickling many objects or when you don't want to write the pickled data to a file; consult the complete -documentation for :mod:`pickle` (XXX reference: ../lib/module-pickle.html) in -the Python Library Reference (XXX reference: ../lib/).) +documentation for :mod:`pickle` in the Python Library Reference.) -:mod:`pickle` (XXX reference: ../lib/module-pickle.html) is the standard way to -make Python objects which can be stored and reused by other programs or by a -future invocation of the same program; the technical term for this is a -:dfn:`persistent` object. Because :mod:`pickle` (XXX reference: ../lib/module- -pickle.html) is so widely used, many authors who write Python extensions take -care to ensure that new data types such as matrices can be properly pickled and -unpickled. +:mod:`pickle` is the standard way to make Python objects which can be stored and +reused by other programs or by a future invocation of the same program; the +technical term for this is a :dfn:`persistent` object. Because :mod:`pickle` is +so widely used, many authors who write Python extensions take care to ensure +that new data types such as matrices can be properly pickled and unpickled. Modified: doctools/trunk/Doc-26/tutorial/interactive.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/interactive.rst (original) +++ doctools/trunk/Doc-26/tutorial/interactive.rst Thu Aug 2 20:07:46 2007 @@ -115,8 +115,8 @@ the startup file is executed in the same namespace as the interactive commands, and removing the names avoids creating side effects in the interactive environment. You may find it convenient to keep some of the imported modules, -such as :mod:`os` (XXX reference: ../lib/module-os.html), which turn out to be -needed in most sessions with the interpreter. :: +such as :mod:`os`, which turn out to be needed in most sessions with the +interpreter. :: # Add auto-completion and a stored history file of commands to your Python # interactive interpreter. Requires Python 2.0+, readline. Autocomplete is Modified: doctools/trunk/Doc-26/tutorial/interpreter.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/interpreter.rst (original) +++ doctools/trunk/Doc-26/tutorial/interpreter.rst Thu Aug 2 20:07:46 2007 @@ -182,9 +182,8 @@ With that declaration, all characters in the source file will be treated as having the encoding *encoding*, and it will be possible to directly write Unicode string literals in the selected encoding. The list of possible -encodings can be found in the Python Library Reference (XXX reference: -../lib/lib.html), in the section on :mod:`codecs` (XXX reference: ../lib/module- -codecs.html). +encodings can be found in the Python Library Reference, in the section on +:mod:`codecs`. For example, to write Unicode literals including the Euro currency symbol, the ISO-8859-15 encoding can be used, with the Euro symbol having the ordinal value Modified: doctools/trunk/Doc-26/tutorial/modules.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/modules.rst (original) +++ doctools/trunk/Doc-26/tutorial/modules.rst Thu Aug 2 20:07:46 2007 @@ -215,9 +215,8 @@ .. index:: module: compileall -* The module :mod:`compileall` (XXX reference: ../lib/module-compileall.html) - can create :file:`.pyc` files (or :file:`.pyo` files when :option:`-O` is used) - for all modules in a directory. +* The module :mod:`compileall` can create :file:`.pyc` files (or :file:`.pyo` + files when :option:`-O` is used) for all modules in a directory. .. % @@ -230,15 +229,14 @@ .. index:: module: sys Python comes with a library of standard modules, described in a separate -document, the Python Library Reference (XXX reference: ../lib/lib.html) -("Library Reference" hereafter). Some modules are built into the interpreter; -these provide access to operations that are not part of the core of the language -but are nevertheless built in, either for efficiency or to provide access to -operating system primitives such as system calls. The set of such modules is a -configuration option which also depends on the underlying platform For example, -the :mod:`winreg` module is only provided on Windows systems. One particular -module deserves some attention: :mod:`sys` (XXX reference: ../lib/module- -sys.html), which is built into every Python interpreter. The variables +document, the Python Library Reference ("Library Reference" hereafter). Some +modules are built into the interpreter; these provide access to operations that +are not part of the core of the language but are nevertheless built in, either +for efficiency or to provide access to operating system primitives such as +system calls. The set of such modules is a configuration option which also +depends on the underlying platform For example, the :mod:`winreg` module is only +provided on Windows systems. One particular module deserves some attention: +:mod:`sys`, which is built into every Python interpreter. The variables ``sys.ps1`` and ``sys.ps2`` define the strings used as primary and secondary prompts: Modified: doctools/trunk/Doc-26/tutorial/stdlib.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/stdlib.rst (original) +++ doctools/trunk/Doc-26/tutorial/stdlib.rst Thu Aug 2 20:07:46 2007 @@ -10,8 +10,8 @@ Operating System Interface ========================== -The :mod:`os` (XXX reference: ../lib/module-os.html) module provides dozens of -functions for interacting with the operating system:: +The :mod:`os` module provides dozens of functions for interacting with the +operating system:: >>> import os >>> os.system('time 0:02') @@ -35,9 +35,8 @@ >>> help(os) -For daily file and directory management tasks, the :mod:`shutil` (XXX -reference: ../lib/module-shutil.html) module provides a higher level interface -that is easier to use:: +For daily file and directory management tasks, the :mod:`shutil` module provides +a higher level interface that is easier to use:: >>> import shutil >>> shutil.copyfile('data.db', 'archive.db') @@ -49,8 +48,8 @@ File Wildcards ============== -The :mod:`glob` (XXX reference: ../lib/module-glob.html) module provides a -function for making file lists from directory wildcard searches:: +The :mod:`glob` module provides a function for making file lists from directory +wildcard searches:: >>> import glob >>> glob.glob('*.py') @@ -63,18 +62,17 @@ ====================== Common utility scripts often need to process command line arguments. These -arguments are stored in the :mod:`sys` (XXX reference: ../lib/module-sys.html) -module's *argv* attribute as a list. For instance the following output results -from running ``python demo.py one two three`` at the command line:: +arguments are stored in the :mod:`sys` module's *argv* attribute as a list. For +instance the following output results from running ``python demo.py one two +three`` at the command line:: >>> import sys >>> print sys.argv ['demo.py', 'one', 'two', 'three'] -The :mod:`getopt` (XXX reference: ../lib/module-getopt.html) module processes -*sys.argv* using the conventions of the Unix :func:`getopt` function. More -powerful and flexible command line processing is provided by the :mod:`optparse` -(XXX reference: ../lib/module-optparse.html) module. +The :mod:`getopt` module processes *sys.argv* using the conventions of the Unix +:func:`getopt` function. More powerful and flexible command line processing is +provided by the :mod:`optparse` module. .. _tut-stderr: @@ -82,10 +80,9 @@ Error Output Redirection and Program Termination ================================================ -The :mod:`sys` (XXX reference: ../lib/module-sys.html) module also has -attributes for *stdin*, *stdout*, and *stderr*. The latter is useful for -emitting warnings and error messages to make them visible even when *stdout* has -been redirected:: +The :mod:`sys` module also has attributes for *stdin*, *stdout*, and *stderr*. +The latter is useful for emitting warnings and error messages to make them +visible even when *stdout* has been redirected:: >>> sys.stderr.write('Warning, log file not found starting a new one\n') Warning, log file not found starting a new one @@ -98,9 +95,9 @@ String Pattern Matching ======================= -The :mod:`re` (XXX reference: ../lib/module-re.html) module provides regular -expression tools for advanced string processing. For complex matching and -manipulation, regular expressions offer succinct, optimized solutions:: +The :mod:`re` module provides regular expression tools for advanced string +processing. For complex matching and manipulation, regular expressions offer +succinct, optimized solutions:: >>> import re >>> re.findall(r'\bf[a-z]*', 'which foot or hand fell fastest') @@ -120,8 +117,8 @@ Mathematics =========== -The :mod:`math` (XXX reference: ../lib/module-math.html) module gives access to -the underlying C library functions for floating point math:: +The :mod:`math` module gives access to the underlying C library functions for +floating point math:: >>> import math >>> math.cos(math.pi / 4.0) @@ -129,8 +126,7 @@ >>> math.log(1024, 2) 10.0 -The :mod:`random` (XXX reference: ../lib/module-random.html) module provides -tools for making random selections:: +The :mod:`random` module provides tools for making random selections:: >>> import random >>> random.choice(['apple', 'pear', 'banana']) @@ -149,9 +145,8 @@ =============== There are a number of modules for accessing the internet and processing internet -protocols. Two of the simplest are :mod:`urllib2` (XXX reference: ../lib/module- -urllib2.html) for retrieving data from urls and :mod:`smtplib` (XXX reference: -../lib/module-smtplib.html) for sending mail:: +protocols. Two of the simplest are :mod:`urllib2` for retrieving data from urls +and :mod:`smtplib` for sending mail:: >>> import urllib2 >>> for line in urllib2.urlopen('http://tycho.usno.navy.mil/cgi-bin/timer.pl'): @@ -176,11 +171,11 @@ Dates and Times =============== -The :mod:`datetime` (XXX reference: ../lib/module-datetime.html) module supplies -classes for manipulating dates and times in both simple and complex ways. While -date and time arithmetic is supported, the focus of the implementation is on -efficient member extraction for output formatting and manipulation. The module -also supports objects that are timezone aware. :: +The :mod:`datetime` module supplies classes for manipulating dates and times in +both simple and complex ways. While date and time arithmetic is supported, the +focus of the implementation is on efficient member extraction for output +formatting and manipulation. The module also supports objects that are timezone +aware. :: # dates are easily constructed and formatted >>> from datetime import date @@ -203,10 +198,8 @@ ================ Common data archiving and compression formats are directly supported by modules -including: :mod:`zlib` (XXX reference: ../lib/module-zlib.html), :mod:`gzip` -(XXX reference: ../lib/module-gzip.html), :mod:`bz2` (XXX reference: ../lib -/module-bz2.html), :mod:`zipfile` (XXX reference: ../lib/module-zipfile.html), -and :mod:`tarfile` (XXX reference: ../lib/module-tarfile.html). :: +including: :mod:`zlib`, :mod:`gzip`, :mod:`bz2`, :mod:`zipfile` and +:mod:`tarfile`. :: >>> import zlib >>> s = 'witch which has which witches wrist watch' @@ -232,8 +225,7 @@ For example, it may be tempting to use the tuple packing and unpacking feature instead of the traditional approach to swapping arguments. The :mod:`timeit` -(XXX reference: ../lib/module-timeit.html) module quickly demonstrates a modest -performance advantage:: +module quickly demonstrates a modest performance advantage:: >>> from timeit import Timer >>> Timer('t=a; a=b; b=t', 'a=1; b=2').timeit() @@ -241,9 +233,9 @@ >>> Timer('a,b = b,a', 'a=1; b=2').timeit() 0.54962537085770791 -In contrast to :mod:`timeit`'s fine level of granularity, the :mod:`profile` -(XXX reference: ../lib/module-profile.html) and :mod:`pstats` modules provide -tools for identifying time critical sections in larger blocks of code. +In contrast to :mod:`timeit`'s fine level of granularity, the :mod:`profile` and +:mod:`pstats` modules provide tools for identifying time critical sections in +larger blocks of code. .. _tut-quality-control: @@ -255,12 +247,12 @@ function as it is developed and to run those tests frequently during the development process. -The :mod:`doctest` (XXX reference: ../lib/module-doctest.html) module provides a -tool for scanning a module and validating tests embedded in a program's -docstrings. Test construction is as simple as cutting-and-pasting a typical -call along with its results into the docstring. This improves the documentation -by providing the user with an example and it allows the doctest module to make -sure the code remains true to the documentation:: +The :mod:`doctest` module provides a tool for scanning a module and validating +tests embedded in a program's docstrings. Test construction is as simple as +cutting-and-pasting a typical call along with its results into the docstring. +This improves the documentation by providing the user with an example and it +allows the doctest module to make sure the code remains true to the +documentation:: def average(values): """Computes the arithmetic mean of a list of numbers. @@ -273,9 +265,9 @@ import doctest doctest.testmod() # automatically validate the embedded tests -The :mod:`unittest` (XXX reference: ../lib/module-unittest.html) module is not -as effortless as the :mod:`doctest` module, but it allows a more comprehensive -set of tests to be maintained in a separate file:: +The :mod:`unittest` module is not as effortless as the :mod:`doctest` module, +but it allows a more comprehensive set of tests to be maintained in a separate +file:: import unittest @@ -298,28 +290,24 @@ Python has a "batteries included" philosophy. This is best seen through the sophisticated and robust capabilities of its larger packages. For example: -* The :mod:`xmlrpclib` (XXX reference: ../lib/module-xmlrpclib.html) and - :mod:`SimpleXMLRPCServer` (XXX reference: ../lib/module-SimpleXMLRPCServer.html) - modules make implementing remote procedure calls into an almost trivial task. - Despite the modules names, no direct knowledge or handling of XML is needed. - -* The :mod:`email` (XXX reference: ../lib/module-email.html) package is a - library for managing email messages, including MIME and other RFC 2822-based - message documents. Unlike :mod:`smtplib` and :mod:`poplib` which actually send - and receive messages, the email package has a complete toolset for building or - decoding complex message structures (including attachments) and for implementing - internet encoding and header protocols. - -* The :mod:`xml.dom` (XXX reference: ../lib/module-xml.dom.html) and - :mod:`xml.sax` (XXX reference: ../lib/module-xml.sax.html) packages provide - robust support for parsing this popular data interchange format. Likewise, the - :mod:`csv` (XXX reference: ../lib/module-csv.html) module supports direct reads - and writes in a common database format. Together, these modules and packages - greatly simplify data interchange between python applications and other tools. +* The :mod:`xmlrpclib` and :mod:`SimpleXMLRPCServer` modules make implementing + remote procedure calls into an almost trivial task. Despite the modules + names, no direct knowledge or handling of XML is needed. + +* The :mod:`email` package is a library for managing email messages, including + MIME and other RFC 2822-based message documents. Unlike :mod:`smtplib` and + :mod:`poplib` which actually send and receive messages, the email package has + a complete toolset for building or decoding complex message structures + (including attachments) and for implementing internet encoding and header + protocols. + +* The :mod:`xml.dom` and :mod:`xml.sax` packages provide robust support for + parsing this popular data interchange format. Likewise, the :mod:`csv` module + supports direct reads and writes in a common database format. Together, these + modules and packages greatly simplify data interchange between python + applications and other tools. * Internationalization is supported by a number of modules including - :mod:`gettext` (XXX reference: ../lib/module-gettext.html), :mod:`locale` (XXX - reference: ../lib/module-locale.html), and the :mod:`codecs` (XXX reference: - ../lib/module-codecs.html) package. + :mod:`gettext`, :mod:`locale`, and the :mod:`codecs` package. Modified: doctools/trunk/Doc-26/tutorial/stdlib2.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/stdlib2.rst (original) +++ doctools/trunk/Doc-26/tutorial/stdlib2.rst Thu Aug 2 20:07:46 2007 @@ -13,19 +13,17 @@ Output Formatting ================= -The :mod:`repr` (XXX reference: ../lib/module-repr.html) module provides a -version of :func:`repr` customized for abbreviated displays of large or deeply -nested containers:: +The :mod:`repr` module provides a version of :func:`repr` customized for +abbreviated displays of large or deeply nested containers:: >>> import repr >>> repr.repr(set('supercalifragilisticexpialidocious')) "set(['a', 'c', 'd', 'e', 'f', 'g', ...])" -The :mod:`pprint` (XXX reference: ../lib/module-pprint.html) module offers more -sophisticated control over printing both built-in and user defined objects in a -way that is readable by the interpreter. When the result is longer than one -line, the "pretty printer" adds line breaks and indentation to more clearly -reveal data structure:: +The :mod:`pprint` module offers more sophisticated control over printing both +built-in and user defined objects in a way that is readable by the interpreter. +When the result is longer than one line, the "pretty printer" adds line breaks +and indentation to more clearly reveal data structure:: >>> import pprint >>> t = [[[['black', 'cyan'], 'white', ['green', 'red']], [['magenta', @@ -38,8 +36,8 @@ [['magenta', 'yellow'], 'blue']]] -The :mod:`textwrap` (XXX reference: ../lib/module-textwrap.html) module formats -paragraphs of text to fit a given screen width:: +The :mod:`textwrap` module formats paragraphs of text to fit a given screen +width:: >>> import textwrap >>> doc = """The wrap() method is just like fill() except that it returns @@ -52,10 +50,9 @@ instead of one big string with newlines to separate the wrapped lines. -The :mod:`locale` (XXX reference: ../lib/module-locale.html) module accesses a -database of culture specific data formats. The grouping attribute of locale's -format function provides a direct way of formatting numbers with group -separators:: +The :mod:`locale` module accesses a database of culture specific data formats. +The grouping attribute of locale's format function provides a direct way of +formatting numbers with group separators:: >>> import locale >>> locale.setlocale(locale.LC_ALL, 'English_United States.1252') @@ -74,10 +71,9 @@ Templating ========== -The :mod:`string` (XXX reference: ../lib/module-string.html) module includes a -versatile :class:`Template` class with a simplified syntax suitable for editing -by end-users. This allows users to customize their applications without having -to alter the application. +The :mod:`string` module includes a versatile :class:`Template` class with a +simplified syntax suitable for editing by end-users. This allows users to +customize their applications without having to alter the application. The format uses placeholder names formed by ``$`` with valid Python identifiers (alphanumeric characters and underscores). Surrounding the placeholder with @@ -136,11 +132,10 @@ Working with Binary Data Record Layouts ======================================= -The :mod:`struct` (XXX reference: ../lib/module-struct.html) module provides -:func:`pack` and :func:`unpack` functions for working with variable length -binary record formats. The following example shows how to loop through header -information in a ZIP file (with pack codes ``"H"`` and ``"L"`` representing two -and four byte unsigned numbers respectively):: +The :mod:`struct` module provides :func:`pack` and :func:`unpack` functions for +working with variable length binary record formats. The following example shows +how to loop through header information in a ZIP file (with pack codes ``"H"`` +and ``"L"`` representing two and four byte unsigned numbers respectively):: import struct @@ -170,9 +165,8 @@ that accept user input while other tasks run in the background. A related use case is running I/O in parallel with computations in another thread. -The following code shows how the high level :mod:`threading` (XXX reference: -../lib/module-threading.html) module can run tasks in background while the main -program continues to run:: +The following code shows how the high level :mod:`threading` module can run +tasks in background while the main program continues to run:: import threading, zipfile @@ -202,10 +196,9 @@ While those tools are powerful, minor design errors can result in problems that are difficult to reproduce. So, the preferred approach to task coordination is to concentrate all access to a resource in a single thread and then use the -:mod:`Queue` (XXX reference: ../lib/module-Queue.html) module to feed that -thread with requests from other threads. Applications using :class:`Queue` -objects for inter-thread communication and coordination are easier to design, -more readable, and more reliable. +:mod:`Queue` module to feed that thread with requests from other threads. +Applications using :class:`Queue` objects for inter-thread communication and +coordination are easier to design, more readable, and more reliable. .. _tut-logging: @@ -213,9 +206,8 @@ Logging ======= -The :mod:`logging` (XXX reference: ../lib/module-logging.html) module offers a -full featured and flexible logging system. At its simplest, log messages are -sent to a file or to ``sys.stderr``:: +The :mod:`logging` module offers a full featured and flexible logging system. +At its simplest, log messages are sent to a file or to ``sys.stderr``:: import logging logging.debug('Debugging information') @@ -253,11 +245,10 @@ This approach works fine for most applications but occasionally there is a need to track objects only as long as they are being used by something else. Unfortunately, just tracking them creates a reference that makes them permanent. -The :mod:`weakref` (XXX reference: ../lib/module-weakref.html) module provides -tools for tracking objects without creating a reference. When the object is no -longer needed, it is automatically removed from a weakref table and a callback -is triggered for weakref objects. Typical applications include caching objects -that are expensive to create:: +The :mod:`weakref` module provides tools for tracking objects without creating a +reference. When the object is no longer needed, it is automatically removed +from a weakref table and a callback is triggered for weakref objects. Typical +applications include caching objects that are expensive to create:: >>> import weakref, gc >>> class A: @@ -292,11 +283,11 @@ sometimes there is a need for alternative implementations with different performance trade-offs. -The :mod:`array` (XXX reference: ../lib/module-array.html) module provides an -:class:`array()` object that is like a list that stores only homogenous data and -stores it more compactly. The following example shows an array of numbers -stored as two byte unsigned binary numbers (typecode ``"H"``) rather than the -usual 16 bytes per entry for regular lists of python int objects:: +The :mod:`array` module provides an :class:`array()` object that is like a list +that stores only homogenous data and stores it more compactly. The following +example shows an array of numbers stored as two byte unsigned binary numbers +(typecode ``"H"``) rather than the usual 16 bytes per entry for regular lists of +python int objects:: >>> from array import array >>> a = array('H', [4000, 10, 700, 22222]) @@ -305,10 +296,10 @@ >>> a[1:3] array('H', [10, 700]) -The :mod:`collections` (XXX reference: ../lib/module-collections.html) module -provides a :class:`deque()` object that is like a list with faster appends and -pops from the left side but slower lookups in the middle. These objects are well -suited for implementing queues and breadth first tree searches:: +The :mod:`collections` module provides a :class:`deque()` object that is like a +list with faster appends and pops from the left side but slower lookups in the +middle. These objects are well suited for implementing queues and breadth first +tree searches:: >>> from collections import deque >>> d = deque(["task1", "task2", "task3"]) @@ -325,8 +316,8 @@ unsearched.append(m) In addition to alternative list implementations, the library also offers other -tools such as the :mod:`bisect` (XXX reference: ../lib/module-bisect.html) -module with functions for manipulating sorted lists:: +tools such as the :mod:`bisect` module with functions for manipulating sorted +lists:: >>> import bisect >>> scores = [(100, 'perl'), (200, 'tcl'), (400, 'lua'), (500, 'python')] @@ -334,10 +325,10 @@ >>> scores [(100, 'perl'), (200, 'tcl'), (300, 'ruby'), (400, 'lua'), (500, 'python')] -The :mod:`heapq` (XXX reference: ../lib/module-heapq.html) module provides -functions for implementing heaps based on regular lists. The lowest valued -entry is always kept at position zero. This is useful for applications which -repeatedly access the smallest element but do not want to run a full list sort:: +The :mod:`heapq` module provides functions for implementing heaps based on +regular lists. The lowest valued entry is always kept at position zero. This +is useful for applications which repeatedly access the smallest element but do +not want to run a full list sort:: >>> from heapq import heapify, heappop, heappush >>> data = [1, 3, 5, 7, 9, 2, 4, 6, 8, 0] @@ -352,14 +343,14 @@ Decimal Floating Point Arithmetic ================================= -The :mod:`decimal` (XXX reference: ../lib/module-decimal.html) module offers a -:class:`Decimal` datatype for decimal floating point arithmetic. Compared to -the built-in :class:`float` implementation of binary floating point, the new -class is especially helpful for financial applications and other uses which -require exact decimal representation, control over precision, control over -rounding to meet legal or regulatory requirements, tracking of significant -decimal places, or for applications where the user expects the results to match -calculations done by hand. +The :mod:`decimal` module offers a :class:`Decimal` datatype for decimal +floating point arithmetic. Compared to the built-in :class:`float` +implementation of binary floating point, the new class is especially helpful for +financial applications and other uses which require exact decimal +representation, control over precision, control over rounding to meet legal or +regulatory requirements, tracking of significant decimal places, or for +applications where the user expects the results to match calculations done by +hand. For example, calculating a 5% tax on a 70 cent phone charge gives different results in decimal floating point and binary floating point. The difference Modified: doctools/trunk/Doc-26/tutorial/whatnow.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/whatnow.rst (original) +++ doctools/trunk/Doc-26/tutorial/whatnow.rst Thu Aug 2 20:07:46 2007 @@ -11,7 +11,7 @@ This tutorial is part of Python's documentation set. Some other documents in the set are: -* Python Library Reference (XXX reference: ../lib/lib.html): +* :ref:`library-index`: You should browse through this manual, which gives complete (though terse) reference material about types, functions, and the modules in the standard @@ -21,12 +21,12 @@ and many other tasks. Skimming through the Library Reference will give you an idea of what's available. -* Installing Python Modules (XXX reference: ../inst/inst.html) explains how to - install external modules written by other Python users. +* :ref:`install-index` explains how to install external modules written by other + Python users. -* Language Reference (XXX reference: ../ref/ref.html): A detailed explanation - of Python's syntax and semantics. It's heavy reading, but is useful as a - complete guide to the language itself. +* :ref:`reference-index`: A detailed explanation of Python's syntax and + semantics. It's heavy reading, but is useful as a complete guide to the + language itself. More Python resources: Modified: doctools/trunk/Doc-26/whatsnew/2.3.rst ============================================================================== --- doctools/trunk/Doc-26/whatsnew/2.3.rst (original) +++ doctools/trunk/Doc-26/whatsnew/2.3.rst Thu Aug 2 20:07:46 2007 @@ -30,10 +30,9 @@ This article doesn't attempt to provide a complete specification of the new features, but instead provides a convenient overview. For full details, you should refer to the documentation for Python 2.3, such as the Python Library -Reference (XXX reference: ../lib/lib.html) and the Python Reference Manual (XXX -reference: ../ref/ref.html). If you want to understand the complete -implementation and design rationale, refer to the PEP for a particular new -feature. +Reference and the Python Reference Manual. If you want to understand the +complete implementation and design rationale, refer to the PEP for a particular +new feature. .. % ====================================================================== @@ -1345,7 +1344,7 @@ elements in the iterator for which the function :func:`predicate` returns :const:`True`, and ``itertools.repeat(obj, N)`` returns ``obj`` *N* times. There are a number of other functions in the module; see the package's reference - documentation (XXX reference: ../lib/module-itertools.html) for details. + documentation for details. (Contributed by Raymond Hettinger.) * Two new functions in the :mod:`math` module, :func:`degrees(rads)` and @@ -1506,8 +1505,7 @@ the text wrapping strategy. Both the :class:`TextWrapper` class and the :func:`wrap` and :func:`fill` functions support a number of additional keyword arguments for fine-tuning the formatting; consult the module's documentation - (XXX reference: ../lib/module-textwrap.html) for details. (Contributed by Greg - Ward.) + for details. (Contributed by Greg Ward.) * The :mod:`thread` and :mod:`threading` modules now have companion modules, :mod:`dummy_thread` and :mod:`dummy_threading`, that provide a do-nothing @@ -1725,8 +1723,8 @@ support for parsing strings and getting back a :class:`date` or :class:`datetime`. -For more information, refer to the module's reference documentation (XXX -reference: ../lib/module-datetime.html). (Contributed by Tim Peters.) +For more information, refer to the module's reference documentation. +(Contributed by Tim Peters.) .. % ====================================================================== @@ -1787,10 +1785,8 @@ set maximum length of output $ -See the module's documentation (XXX reference: ../lib/module-optparse.html) for -more details. +See the module's documentation for more details. -.. % $ prevent Emacs tex-mode from getting confused Optik was written by Greg Ward, with suggestions from the readers of the Getopt SIG. Modified: doctools/trunk/Doc-26/whatsnew/2.4.rst ============================================================================== --- doctools/trunk/Doc-26/whatsnew/2.4.rst (original) +++ doctools/trunk/Doc-26/whatsnew/2.4.rst Thu Aug 2 20:07:46 2007 @@ -25,10 +25,9 @@ This article doesn't attempt to provide a complete specification of every single new feature, but instead provides a brief introduction to each feature. For full details, you should refer to the documentation for Python 2.4, such as the -Python Library Reference (XXX reference: ../lib/lib.html) and the Python -Reference Manual (XXX reference: ../ref/ref.html). Often you will be referred -to the PEP for a particular new feature for explanations of the implementation -and design rationale. +Python Library Reference and the Python Reference Manual. Often you will be +referred to the PEP for a particular new feature for explanations of the +implementation and design rationale. .. % ====================================================================== Modified: doctools/trunk/Doc-26/whatsnew/2.6.rst ============================================================================== --- doctools/trunk/Doc-26/whatsnew/2.6.rst (original) +++ doctools/trunk/Doc-26/whatsnew/2.6.rst Thu Aug 2 20:07:46 2007 @@ -3,8 +3,8 @@ **************************** :Author: A.M. Kuchling - -.. |release| replace:: 0.0 +:Release: |release| +:Date: |today| .. % $Id: whatsnew26.tex 55746 2007-06-02 18:33:53Z neal.norwitz $ .. % Rules for maintenance: Modified: doctools/trunk/Doc-3k/TODO ============================================================================== --- doctools/trunk/Doc-3k/TODO (original) +++ doctools/trunk/Doc-3k/TODO Thu Aug 2 20:07:46 2007 @@ -1,7 +1,6 @@ To do after conversion ====================== -* fix all references and links marked with `XXX` * split very large files and add toctrees * integrate standalone HOWTOs * find out which files get "comments disabled" metadata Modified: doctools/trunk/Doc-3k/about.rst ============================================================================== --- doctools/trunk/Doc-3k/about.rst (original) +++ doctools/trunk/Doc-3k/about.rst Thu Aug 2 20:07:46 2007 @@ -2,6 +2,7 @@ About these documents ===================== + These documents are generated from `reStructuredText `_ sources by *Sphinx*, a document processor specifically written for the Python documentation. @@ -15,4 +16,6 @@ See :ref:`reporting-bugs` for information how to report bugs in Python itself. -.. include:: ACKS \ No newline at end of file +.. % include the ACKS file here so that it can be maintained separately + +.. include:: ACKS Modified: doctools/trunk/Doc-3k/c-api/concrete.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/concrete.rst (original) +++ doctools/trunk/Doc-3k/c-api/concrete.rst Thu Aug 2 20:07:46 2007 @@ -2318,22 +2318,19 @@ .. cfunction:: PyObject* PyDict_Items(PyObject *p) Return a :ctype:`PyListObject` containing all the items from the dictionary, as - in the dictionary method :meth:`items` (see the Python Library Reference (XXX - reference: ../lib/lib.html)). + in the dictionary method :meth:`dict.items`. .. cfunction:: PyObject* PyDict_Keys(PyObject *p) Return a :ctype:`PyListObject` containing all the keys from the dictionary, as - in the dictionary method :meth:`keys` (see the Python Library Reference (XXX - reference: ../lib/lib.html)). + in the dictionary method :meth:`dict.keys`. .. cfunction:: PyObject* PyDict_Values(PyObject *p) Return a :ctype:`PyListObject` containing all the values from the dictionary - *p*, as in the dictionary method :meth:`values` (see the Python Library - Reference (XXX reference: ../lib/lib.html)). + *p*, as in the dictionary method :meth:`dict.values`. .. cfunction:: Py_ssize_t PyDict_Size(PyObject *p) Modified: doctools/trunk/Doc-3k/c-api/intro.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/intro.rst (original) +++ doctools/trunk/Doc-3k/c-api/intro.rst Thu Aug 2 20:07:46 2007 @@ -99,12 +99,11 @@ deallocated, they are typically static :ctype:`PyTypeObject` objects. All Python objects (even Python integers) have a :dfn:`type` and a -:dfn:`reference count`. An object's type determines what kind of object it is -(e.g., an integer, a list, or a user-defined function; there are many more as -explained in the Python Reference Manual (XXX reference: ../ref/ref.html)). For -each of the well-known types there is a macro to check whether an object is of -that type; for instance, ``PyList_Check(a)`` is true if (and only if) the object -pointed to by *a* is a Python list. +:dfn:`reference count`. An object's type determines what kind of object it is +(e.g., an integer, a list, or a user-defined function; there are many more as +explained in :ref:`types`). For each of the well-known types there is a macro +to check whether an object is of that type; for instance, ``PyList_Check(a)`` is +true if (and only if) the object pointed to by *a* is a Python list. .. _api-refcounts: Modified: doctools/trunk/Doc-3k/c-api/newtypes.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/newtypes.rst (original) +++ doctools/trunk/Doc-3k/c-api/newtypes.rst Thu Aug 2 20:07:46 2007 @@ -610,17 +610,17 @@ This field is inherited by subtypes. -PyNumberMethods \*tp_as_number; +.. cmember:: PyNumberMethods *tp_as_number; -XXX + XXX -PySequenceMethods \*tp_as_sequence; +.. cmember:: PySequenceMethods *tp_as_sequence; -XXX + XXX -PyMappingMethods \*tp_as_mapping; +.. cmember:: PyMappingMethods *tp_as_mapping; -XXX + XXX .. cmember:: hashfunc PyTypeObject.tp_hash @@ -842,12 +842,13 @@ .. data:: Py_TPFLAGS_HAVE_GC - This bit is set when the object supports garbage collection. If this bit is - set, instances must be created using :cfunc:`PyObject_GC_New` and destroyed - using :cfunc:`PyObject_GC_Del`. More information in section XXX about garbage - collection. This bit also implies that the GC-related fields - :attr:`tp_traverse` and :attr:`tp_clear` are present in the type object; but - those fields also exist when :const:`Py_TPFLAGS_HAVE_GC` is clear but + This bit is set when the object supports garbage collection. If this bit + is set, instances must be created using :cfunc:`PyObject_GC_New` and + destroyed using :cfunc:`PyObject_GC_Del`. More information in section + :ref:`supporting-cycle-detection`. This bit also implies that the + GC-related fields :attr:`tp_traverse` and :attr:`tp_clear` are present in + the type object; but those fields also exist when + :const:`Py_TPFLAGS_HAVE_GC` is clear but :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` is set. @@ -1598,9 +1599,8 @@ other objects, or which only store references to atomic types (such as numbers or strings), do not need to provide any explicit support for garbage collection. -An example showing the use of these interfaces can be found in "Supporting the -Cycle Collector (XXX reference: ../ext/example-cycle-support.html)" in Extending -and Embedding the Python Interpreter (XXX reference: ../ext/ext.html). +.. An example showing the use of these interfaces can be found in "Supporting the +.. Cycle Collector (XXX reference: ../ext/example-cycle-support.html)". To create a container type, the :attr:`tp_flags` field of the type object must include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the Modified: doctools/trunk/Doc-3k/c-api/utilities.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/utilities.rst (original) +++ doctools/trunk/Doc-3k/c-api/utilities.rst Thu Aug 2 20:07:46 2007 @@ -366,6 +366,7 @@ .. versionchanged:: 2.4 *version* indicates the file format. + The following functions allow marshalled values to be read back in. XXX What about error detection? It appears that reading past the end of the @@ -421,8 +422,8 @@ ===================================== These functions are useful when creating your own extensions functions and -methods. Additional information and examples are available in Extending and -Embedding the Python Interpreter (XXX reference: ../ext/ext.html). +methods. Additional information and examples are available in +:ref:`extending-index`. The first three of these functions described, :cfunc:`PyArg_ParseTuple`, :cfunc:`PyArg_ParseTupleAndKeywords`, and :cfunc:`PyArg_Parse`, all use *format Modified: doctools/trunk/Doc-3k/distutils/index.rst ============================================================================== --- doctools/trunk/Doc-3k/distutils/index.rst (original) +++ doctools/trunk/Doc-3k/distutils/index.rst Thu Aug 2 20:07:46 2007 @@ -4,6 +4,8 @@ Distributing Python Modules ############################### +:Authors: Greg Ward, Anthony Baxter +:Email: distutils-sig at python.org :Release: |version| :Date: |today| Modified: doctools/trunk/Doc-3k/distutils/introduction.rst ============================================================================== --- doctools/trunk/Doc-3k/distutils/introduction.rst (original) +++ doctools/trunk/Doc-3k/distutils/introduction.rst Thu Aug 2 20:07:46 2007 @@ -6,8 +6,8 @@ This document covers using the Distutils to distribute your Python modules, concentrating on the role of developer/distributor: if you're looking for -information on installing Python modules, you should refer to the Installing -Python Modules (XXX reference: ../inst/inst.html) manual. +information on installing Python modules, you should refer to the +:ref:`install-index` chapter. .. _distutils-concepts: Modified: doctools/trunk/Doc-3k/extending/building.rst ============================================================================== --- doctools/trunk/Doc-3k/extending/building.rst (original) +++ doctools/trunk/Doc-3k/extending/building.rst Thu Aug 2 20:07:46 2007 @@ -52,7 +52,7 @@ information to build packages, and it specifies the contents of the package. Normally, a package will contain of addition modules, like Python source modules, documentation, subpackages, etc. Please refer to the distutils -documentation in Distributing Python Modules (XXX reference: ../dist/dist.html) +documentation in :ref:`distutils-index` to learn more about the features of distutils; this section explains building extension modules only. Modified: doctools/trunk/Doc-3k/extending/extending.rst ============================================================================== --- doctools/trunk/Doc-3k/extending/extending.rst (original) +++ doctools/trunk/Doc-3k/extending/extending.rst Thu Aug 2 20:07:46 2007 @@ -115,10 +115,9 @@ second global variable stores the "associated value" of the exception (the second argument to :keyword:`raise`). A third variable contains the stack traceback in case the error originated in Python code. These three variables -are the C equivalents of the result in Python of :meth:`sys.exc_info` (see the -section on module :mod:`sys` in the Python Library Reference (XXX reference: -../lib/lib.html)). It is important to know about them to understand how errors -are passed around. +are the C equivalents of the result in Python of :meth:`sys.exc_info` (see the +section on module :mod:`sys` in the Python Library Reference). It is important +to know about them to understand how errors are passed around. The Python API defines a number of functions to set various types of exceptions. @@ -212,8 +211,7 @@ Note that the Python name for the exception object is :exc:`spam.error`. The :cfunc:`PyErr_NewException` function may create a class with the base class being :exc:`Exception` (unless another class is passed in instead of *NULL*), -described in the Python Library Reference (XXX reference: ../lib/lib.html) under -"Built-in Exceptions." +described in :ref:`bltin-exceptions`. Note also that the :cdata:`SpamError` variable retains a reference to the newly created exception class; this is intentional! Since the exception could be @@ -546,10 +544,9 @@ The *arg* argument must be a tuple object containing an argument list passed from Python to a C function. The *format* argument must be a format string, -whose syntax is explained in "Parsing arguments and building values (XXX -reference: ../api/arg-parsing.html)" in the Python/C API Reference Manual (XXX -reference: ../api/api.html). The remaining arguments must be addresses of -variables whose type is determined by the format string. +whose syntax is explained in :ref:`arg-parsing` in the Python/C API Reference +Manual. The remaining arguments must be addresses of variables whose type is +determined by the format string. Note that while :cfunc:`PyArg_ParseTuple` checks that the Python arguments have the required types, it cannot check the validity of the addresses of C variables @@ -814,7 +811,7 @@ The cycle detector is able to detect garbage cycles and can reclaim them so long as there are no finalizers implemented in Python (:meth:`__del__` methods). When there are such finalizers, the detector exposes the cycles through the -:mod:`gc` module (XXX reference: ../lib/module-gc.html) (specifically, the +:mod:`gc` module (specifically, the ``garbage`` variable in that module). The :mod:`gc` module also exposes a way to run the detector (the :func:`collect` function), as well as configuration interfaces and the ability to disable the detector at runtime. The cycle @@ -1255,8 +1252,7 @@ Finally it should be mentioned that CObjects offer additional functionality, which is especially useful for memory allocation and deallocation of the pointer stored in a CObject. The details are described in the Python/C API Reference -Manual (XXX reference: ../api/api.html) in the section "CObjects (XXX reference: -../api/cObjects.html)" and in the implementation of CObjects (files +Manual in the section :ref:`cobjects` and in the implementation of CObjects (files :file:`Include/cobject.h` and :file:`Objects/cobject.c` in the Python source code distribution). Modified: doctools/trunk/Doc-3k/extending/newtypes.rst ============================================================================== --- doctools/trunk/Doc-3k/extending/newtypes.rst (original) +++ doctools/trunk/Doc-3k/extending/newtypes.rst Thu Aug 2 20:07:46 2007 @@ -1355,9 +1355,8 @@ ------------------------- Python supports a variety of *abstract* 'protocols;' the specific interfaces -provided to use these interfaces are documented in the Python/C API Reference -Manual (XXX reference: ../api/api.html) in the chapter "Abstract Objects Layer -(XXX reference: ../api/abstract.html)." +provided to use these interfaces are documented in :ref:`abstract`. + A number of these abstract interfaces were defined early in the development of the Python implementation. In particular, the number, mapping, and sequence Modified: doctools/trunk/Doc-3k/extending/windows.rst ============================================================================== --- doctools/trunk/Doc-3k/extending/windows.rst (original) +++ doctools/trunk/Doc-3k/extending/windows.rst Thu Aug 2 20:07:46 2007 @@ -36,13 +36,11 @@ =================== There are two approaches to building extension modules on Windows, just as there -are on Unix: use the :mod:`distutils` (XXX reference: ../lib/module- -distutils.html) package to control the build process, or do things manually. -The distutils approach works well for most extensions; documentation on using -:mod:`distutils` (XXX reference: ../lib/module-distutils.html) to build and -package extension modules is available in Distributing Python Modules (XXX -reference: ../dist/dist.html). This section describes the manual approach to -building Python extensions written in C or C++. +are on Unix: use the :mod:`distutils` package to control the build process, or +do things manually. The distutils approach works well for most extensions; +documentation on using :mod:`distutils` to build and package extension modules +is available in :ref:`distutils-index`. This section describes the manual +approach to building Python extensions written in C or C++. To build extensions using these instructions, you need to have a copy of the Python sources of the same version as your installed Python. You will need Modified: doctools/trunk/Doc-3k/install/index.rst ============================================================================== --- doctools/trunk/Doc-3k/install/index.rst (original) +++ doctools/trunk/Doc-3k/install/index.rst Thu Aug 2 20:07:46 2007 @@ -1,12 +1,14 @@ -.. _install-index: - .. highlightlang:: none +.. _install-index: + ***************************** Installing Python Modules ***************************** :Author: Greg Ward +:Release: |version| +:Date: |today| .. % TODO: .. % Fill in XXX comments @@ -21,8 +23,6 @@ .. % Finally, it might be useful to include all the material from my "Care .. % and Feeding of a Python Installation" talk in here somewhere. Yow! -XXX: input{boilerplate} :XXX - .. topic:: Abstract This document describes the Python Distribution Utilities ("Distutils") from the @@ -30,17 +30,6 @@ standard Python installation by building and installing third-party Python modules and extensions. -.. % \begin{abstract} -.. % \noindent -.. % Abstract this! -.. % \end{abstract} - -.. % The ugly "%begin{latexonly}" pseudo-environment suppresses the table -.. % of contents for HTML generation. -.. % -.. % begin{latexonly} -.. % end{latexonly} - .. _inst-intro: @@ -64,7 +53,7 @@ document; there will be some brief forays into using Python's interactive mode to explore your installation, but that's it. If you're looking for information on how to distribute your own Python modules so that others may use them, see -the Distributing Python Modules (XXX reference: ../dist/dist.html) manual. +the :ref:`distutils-index` manual. .. _inst-trivial-install: @@ -728,7 +717,7 @@ (2) On Unix, if the :envvar:`HOME` environment variable is not defined, the user's home directory will be determined with the :func:`getpwuid` function from the - standard :mod:`pwd` (XXX reference: ../lib/module-pwd.html) module. + standard :mod:`pwd` module. (3) I.e., in the current directory (usually the location of the setup script). @@ -1020,4 +1009,3 @@ .. [#] Then you have no POSIX emulation available, but you also don't need :file:`cygwin1.dll`. - Modified: doctools/trunk/Doc-3k/library/array.rst ============================================================================== --- doctools/trunk/Doc-3k/library/array.rst (original) +++ doctools/trunk/Doc-3k/library/array.rst Thu Aug 2 20:07:46 2007 @@ -112,8 +112,7 @@ effectively make use of this information), it makes more sense to use the buffer interface supported by array objects. This method is maintained for backward compatibility and should be avoided in new code. The buffer interface is - documented in the Python/C API Reference Manual (XXX reference: - ../api/newTypes.html). + documented in :ref:`bufferobjects`. .. method:: array.byteswap() Modified: doctools/trunk/Doc-3k/library/audioop.rst ============================================================================== --- doctools/trunk/Doc-3k/library/audioop.rst (original) +++ doctools/trunk/Doc-3k/library/audioop.rst Thu Aug 2 20:07:46 2007 @@ -191,11 +191,7 @@ .. function:: rms(fragment, width) - Return the root-mean-square of the fragment, i.e. :: - - XXX: translate this math - \catcode`_=8 - \sqrt{\frac{\sum{{S_{i}}^{2}}}{n}} + Return the root-mean-square of the fragment, i.e. ``sqrt(sum(S_i^2)/n)``. This is a measure of the power in an audio signal. Modified: doctools/trunk/Doc-3k/library/codecs.rst ============================================================================== --- doctools/trunk/Doc-3k/library/codecs.rst (original) +++ doctools/trunk/Doc-3k/library/codecs.rst Thu Aug 2 20:07:46 2007 @@ -1157,11 +1157,7 @@ .. module:: encodings.idna :synopsis: Internationalized Domain Names implementation - - -.. % XXX The next line triggers a formatting bug, so it's commented out -.. % until that can be fixed. -.. % \moduleauthor{Martin v. L\"owis} +.. moduleauthor:: Martin v. L?wis .. versionadded:: 2.3 @@ -1220,13 +1216,10 @@ :mod:`encodings.utf_8_sig` --- UTF-8 codec with BOM signature ------------------------------------------------------------- -.. module:: encodings.utf-8-sig +.. module:: encodings.utf_8_sig :synopsis: UTF-8 codec with BOM signature .. moduleauthor:: Walter D?rwald - -.. % XXX utf_8_sig gives TeX errors - .. versionadded:: 2.5 This module implements a variant of the UTF-8 codec: On encoding a UTF-8 encoded Modified: doctools/trunk/Doc-3k/library/distutils.rst ============================================================================== --- doctools/trunk/Doc-3k/library/distutils.rst (original) +++ doctools/trunk/Doc-3k/library/distutils.rst Thu Aug 2 20:07:46 2007 @@ -13,23 +13,17 @@ 100%-pure Python, or may be extension modules written in C, or may be collections of Python packages which include modules coded in both Python and C. -This package is discussed in two separate documents which are included in the -Python documentation package. To learn about distributing new modules using the -:mod:`distutils` facilities, read Distributing Python Modules (XXX reference: -../dist/dist.html); this includes documentation needed to extend distutils. To -learn about installing Python modules, whether or not the author made use of the -:mod:`distutils` package, read Installing Python Modules (XXX reference: -../inst/inst.html). +This package is discussed in two separate chapters: .. seealso:: - `Distributing Python Modules <../dist/dist.html>`_ + :ref:`distutils-index` The manual for developers and packagers of Python modules. This describes how to prepare :mod:`distutils`\ -based packages so that they may be easily installed into an existing Python installation. - `Installing Python Modules <../inst/inst.html>`_ + :ref:`install-index` An "administrators" manual which includes information on installing modules into an existing Python installation. You do not need to be a Python programmer to read this manual. Modified: doctools/trunk/Doc-3k/library/exceptions.rst ============================================================================== --- doctools/trunk/Doc-3k/library/exceptions.rst (original) +++ doctools/trunk/Doc-3k/library/exceptions.rst Thu Aug 2 20:07:46 2007 @@ -1,3 +1,4 @@ +.. _bltin-exceptions: Built-in Exceptions =================== @@ -40,8 +41,8 @@ The built-in exception classes can be sub-classed to define new exceptions; programmers are encouraged to at least derive new exceptions from the :exc:`Exception` class and not :exc:`BaseException`. More information on -defining exceptions is available in the Python Tutorial (XXX reference: -../tut/tut.html) under the heading "User-defined Exceptions." +defining exceptions is available in the Python Tutorial under +:ref:`tut-userexceptions`. The following exceptions are only used as base classes for other exceptions. Modified: doctools/trunk/Doc-3k/library/functions.rst ============================================================================== --- doctools/trunk/Doc-3k/library/functions.rst (original) +++ doctools/trunk/Doc-3k/library/functions.rst Thu Aug 2 20:07:46 2007 @@ -154,8 +154,7 @@ def f(cls, arg1, arg2, ...): ... The ``@classmethod`` form is a function decorator -- see the description of - function definitions in chapter 7 of the Python Reference Manual (XXX reference: - ../ref/ref.html) for details. + function definitions in :ref:`function` for details. It can be called either on the class (such as ``C.f()``) or on an instance (such as ``C().f()``). The instance is ignored except for its class. If a class @@ -166,8 +165,7 @@ see :func:`staticmethod` in this section. For more information on class methods, consult the documentation on the standard - type hierarchy in chapter 3 of the Python Reference Manual (XXX reference: - ../ref/types.html) (at the bottom). + type hierarchy in :ref:`types`. .. versionadded:: 2.2 @@ -995,8 +993,7 @@ def f(arg1, arg2, ...): ... The ``@staticmethod`` form is a function decorator -- see the description of - function definitions in chapter 7 of the Python Reference Manual (XXX reference: - ../ref/function.html) for details. + function definitions in :ref:`function` for details. It can be called either on the class (such as ``C.f()``) or on an instance (such as ``C().f()``). The instance is ignored except for its class. @@ -1005,8 +1002,7 @@ advanced concept, see :func:`classmethod` in this section. For more information on static methods, consult the documentation on the - standard type hierarchy in chapter 3 of the Python Reference Manual (XXX - reference: ../ref/types.html) (at the bottom). + standard type hierarchy in :ref:`types`. .. versionadded:: 2.2 Modified: doctools/trunk/Doc-3k/library/objects.rst ============================================================================== --- doctools/trunk/Doc-3k/library/objects.rst (original) +++ doctools/trunk/Doc-3k/library/objects.rst Thu Aug 2 20:07:46 2007 @@ -22,8 +22,8 @@ in order of ascending priority (within a table) and grouping operators that have the same priority in the same box. Binary operators of the same priority group from left to right. (Unary operators group from right to left, but there you -have no real choice.) See chapter 5 of the Python Reference Manual (XXX -reference: ../ref/ref.html) for the complete picture on operator priorities. +have no real choice.) See :ref:`operator-summary` for the complete picture on +operator priorities. .. rubric:: Footnotes Modified: doctools/trunk/Doc-3k/library/operator.rst ============================================================================== --- doctools/trunk/Doc-3k/library/operator.rst (original) +++ doctools/trunk/Doc-3k/library/operator.rst Thu Aug 2 20:07:46 2007 @@ -36,13 +36,12 @@ __gt__(a, b) Perform "rich comparisons" between *a* and *b*. Specifically, ``lt(a, b)`` is - equivalent to ``a < b``, ``le(a, b)`` is equivalent to ``a <= b``, ``eq(a, b)`` - is equivalent to ``a == b``, ``ne(a, b)`` is equivalent to ``a != b``, ``gt(a, - b)`` is equivalent to ``a > b`` and ``ge(a, b)`` is equivalent to ``a >= b``. - Note that unlike the built-in :func:`cmp`, these functions can return any value, - which may or may not be interpretable as a Boolean value. See the Python - Reference Manual (XXX reference: ../ref/ref.html) for more information about - rich comparisons. + equivalent to ``a < b``, ``le(a, b)`` is equivalent to ``a <= b``, ``eq(a, + b)`` is equivalent to ``a == b``, ``ne(a, b)`` is equivalent to ``a != b``, + ``gt(a, b)`` is equivalent to ``a > b`` and ``ge(a, b)`` is equivalent to ``a + >= b``. Note that unlike the built-in :func:`cmp`, these functions can + return any value, which may or may not be interpretable as a Boolean value. + See :ref:`comparisons` for more information about rich comparisons. .. versionadded:: 2.2 Modified: doctools/trunk/Doc-3k/library/parser.rst ============================================================================== --- doctools/trunk/Doc-3k/library/parser.rst (original) +++ doctools/trunk/Doc-3k/library/parser.rst Thu Aug 2 20:07:46 2007 @@ -32,7 +32,7 @@ Most importantly, a good understanding of the Python grammar processed by the internal parser is required. For full information on the language syntax, refer -to the Python Language Reference (XXX reference: ../ref/ref.html). The parser +to :ref:`reference-index`. The parser itself is created from a grammar specification defined in the file :file:`Grammar/Grammar` in the standard Python distribution. The parse trees stored in the AST objects created by this module are the actual output from the Modified: doctools/trunk/Doc-3k/library/pdb.rst ============================================================================== --- doctools/trunk/Doc-3k/library/pdb.rst (original) +++ doctools/trunk/Doc-3k/library/pdb.rst Thu Aug 2 20:07:46 2007 @@ -405,6 +405,5 @@ Note that as an exception is propagated down the chain of callers, an ``'exception'`` event is generated at each level. -For more information on code and frame objects, refer to the Python Reference -Manual (XXX reference: ../ref/ref.html). +For more information on code and frame objects, refer to :ref:`types`. Modified: doctools/trunk/Doc-3k/library/stdtypes.rst ============================================================================== --- doctools/trunk/Doc-3k/library/stdtypes.rst (original) +++ doctools/trunk/Doc-3k/library/stdtypes.rst Thu Aug 2 20:07:46 2007 @@ -26,10 +26,7 @@ practically all objects can be compared, tested for truth value, and converted to a string (with the :func:`repr` function or the slightly different :func:`str` function). The latter function is implicitly used when an object is -written by the :keyword:`print` statement. (Information on the :keyword:`print` -statement (XXX reference: ../ref/print.html) and other language statements can -be found in the Python Reference Manual (XXX reference: ../ref/ref.html) and the -Python Tutorial (XXX reference: ../tut/tut.html).) +written by the :func:`print` function. .. _truth: @@ -178,10 +175,9 @@ .. index:: single: __cmp__() (instance method) -Instances of a class normally compare as non-equal unless the class defines the -:meth:`__cmp__` method. Refer to the Python Reference Manual (XXX reference: -../ref/customization.html) for information on the use of this method to effect -object comparisons. +Instances of a class normally compare as non-equal unless the class defines the +:meth:`__cmp__` method. Refer to :ref:`customization`) for information on the +use of this method to effect object comparisons. **Implementation note:** Objects of different types except numbers are ordered by their type names; objects of the same types that don't support proper @@ -490,12 +486,11 @@ object: list String literals are written in single or double quotes: ``'xyzzy'``, -``"frobozz"``. See chapter 2 of the Python Reference Manual (XXX reference: -../ref/strings.html) for more about string literals. Unicode strings are much -like strings, but are specified in the syntax using a preceding ``'u'`` -character: ``u'abc'``, ``u"def"``. Lists are constructed with square brackets, -separating items with commas: ``[a, b, c]``. Tuples are constructed by the -comma operator (not within square brackets), with or without enclosing +``"frobozz"``. See :ref:`strings` for more about string literals. Unicode +strings are much like strings, but are specified in the syntax using a preceding +``'u'`` character: ``u'abc'``, ``u"def"``. Lists are constructed with square +brackets, separating items with commas: ``[a, b, c]``. Tuples are constructed +by the comma operator (not within square brackets), with or without enclosing parentheses, but an empty tuple must have the enclosing parentheses, such as ``a, b, c`` or ``()``. A single item tuple must have a trailing comma, such as ``(d,)``. @@ -2106,8 +2101,7 @@ .. _classes and instances: -See chapters 3 and 7 of the Python Reference Manual (XXX reference: -../ref/ref.html) for these. +See :ref:`objects` and :ref:`class` for these. .. _typesfunctions: @@ -2122,8 +2116,7 @@ defined functions. Both support the same operation (to call the function), but the implementation is different, hence the different object types. -See the Python Reference Manual (XXX reference: ../ref/ref.html) for more -information. +See :ref:`function` for more information. .. _typesmethods: @@ -2165,8 +2158,7 @@ c = C() c.method.im_func.whoami = 'my name is c' -See the Python Reference Manual (XXX reference: ../ref/ref.html) for more -information. +See :ref:`types` for more information. .. _bltin-code-objects: @@ -2194,8 +2186,7 @@ A code object can be executed or evaluated by passing it (instead of a source string) to the :func:`exec` or :func:`eval` built-in functions. -See the Python Reference Manual (XXX reference: ../ref/ref.html) for more -information. +See :ref:`types` for more information. .. _bltin-type-objects: @@ -2232,9 +2223,9 @@ The Ellipsis Object ------------------- -This object is mostly used by extended slice notation (see the Python Reference -Manual (XXX reference: ../ref/ref.html)). It supports no special operations. -There is exactly one ellipsis object, named :const:`Ellipsis` (a built-in name). +This object is mostly used by extended slice notation (see :ref:`slicings`). It +supports no special operations. There is exactly one ellipsis object, named +:const:`Ellipsis` (a built-in name). It is written as ``Ellipsis`` or ``...``. @@ -2263,9 +2254,8 @@ Internal Objects ---------------- -See the Python Reference Manual (XXX reference: ../ref/ref.html) for this -information. It describes stack frame objects, traceback objects, and slice -objects. +See :ref:`types` for this information. It describes stack frame objects, +traceback objects, and slice objects. .. _specialattrs: @@ -2315,8 +2305,8 @@ .. rubric:: Footnotes -.. [#] Additional information on these special methods may be found in the Python - Reference Manual (XXX reference: ../ref/ref.html). +.. [#] Additional information on these special methods may be found in the Python + Reference Manual (:ref:`customization`). .. [#] As a consequence, the list ``[1, 2]`` is considered equal to ``[1.0, 2.0]``, and similarly for tuples. Modified: doctools/trunk/Doc-3k/library/warnings.rst ============================================================================== --- doctools/trunk/Doc-3k/library/warnings.rst (original) +++ doctools/trunk/Doc-3k/library/warnings.rst Thu Aug 2 20:07:46 2007 @@ -16,8 +16,8 @@ might want to issue a warning when a program uses an obsolete module. Python programmers issue warnings by calling the :func:`warn` function defined -in this module. (C programmers use :cfunc:`PyErr_Warn`; see the Python/C API -Reference Manual (XXX reference: ../api/exceptionHandling.html) for details). +in this module. (C programmers use :cfunc:`PyErr_Warn`; see +:ref:`exceptionhandling` for details). Warning messages are normally written to ``sys.stderr``, but their disposition can be changed flexibly, from ignoring all warnings to turning them into Modified: doctools/trunk/Doc-3k/library/weakref.rst ============================================================================== --- doctools/trunk/Doc-3k/library/weakref.rst (original) +++ doctools/trunk/Doc-3k/library/weakref.rst Thu Aug 2 20:07:46 2007 @@ -65,14 +65,8 @@ obj = Dict(red=1, green=2, blue=3) # this object is weak referencable -Extension types can easily be made to support weak references; see "Weak -Reference Support (XXX reference: ../ext/weakref-support.html)" in Extending and -Embedding the Python Interpreter (XXX reference: ../ext/ext.html). - -.. % The referenced section used to appear in this document with the -.. % \label weakref-extension. It would be good to be able to generate a -.. % redirect for the corresponding HTML page (weakref-extension.html) -.. % for on-line versions of this document. +Extension types can easily be made to support weak references; see +:ref:`weakref-support`. .. class:: ref(object[, callback]) Modified: doctools/trunk/Doc-3k/library/webbrowser.rst ============================================================================== --- doctools/trunk/Doc-3k/library/webbrowser.rst (original) +++ doctools/trunk/Doc-3k/library/webbrowser.rst Thu Aug 2 20:07:46 2007 @@ -151,9 +151,7 @@ Only on Windows platforms. (3) - Only on MacOS platforms; requires the standard MacPython :mod:`ic` module, - described in the Macintosh Library Modules (XXX reference: ../mac/module- - ic.html) manual. + Only on MacOS platforms; requires the standard MacPython :mod:`ic` module. (4) Only on MacOS X platform. Modified: doctools/trunk/Doc-3k/library/xml.etree.elementtree.rst ============================================================================== --- doctools/trunk/Doc-3k/library/xml.etree.elementtree.rst (original) +++ doctools/trunk/Doc-3k/library/xml.etree.elementtree.rst Thu Aug 2 20:07:46 2007 @@ -267,7 +267,7 @@ .. method:: Element.remove(subelement) - Removes *subelement* from the element. Unlike the findXXX methods this method + Removes *subelement* from the element. Unlike the findXYZ methods this method compares elements based on the instance identity, not on tag value or contents. Element objects also support the following sequence type methods for working Modified: doctools/trunk/Doc-3k/library/xml.sax.handler.rst ============================================================================== --- doctools/trunk/Doc-3k/library/xml.sax.handler.rst (original) +++ doctools/trunk/Doc-3k/library/xml.sax.handler.rst Thu Aug 2 20:07:46 2007 @@ -207,7 +207,7 @@ information to the application to expand prefixes in those contexts itself, if necessary. - .. % % XXX This is not really the default, is it? MvL + .. % XXX This is not really the default, is it? MvL Note that :meth:`startPrefixMapping` and :meth:`endPrefixMapping` events are not guaranteed to be properly nested relative to each-other: all @@ -232,7 +232,7 @@ The *name* parameter contains the raw XML 1.0 name of the element type as a string and the *attrs* parameter holds an object of the :class:`Attributes` - interface (XXX reference: attributes-objects.html) containing the attributes of + interface (see :ref:`attributes-objects`) containing the attributes of the element. The object passed as *attrs* may be re-used by the parser; holding on to a reference to it is not a reliable way to keep a copy of the attributes. To keep a copy of the attributes, use the :meth:`copy` method of the *attrs* @@ -254,7 +254,7 @@ The *name* parameter contains the name of the element type as a ``(uri, localname)`` tuple, the *qname* parameter contains the raw XML 1.0 name used in the source document, and the *attrs* parameter holds an instance of the - :class:`AttributesNS` interface (XXX reference: attributes-ns-objects.html) + :class:`AttributesNS` interface (see :ref:`attributes-ns-objects`) containing the attributes of the element. If no namespace is associated with the element, the *uri* component of *name* will be ``None``. The object passed as *attrs* may be re-used by the parser; holding on to a reference to it is not Modified: doctools/trunk/Doc-3k/maclib/mac.rst ============================================================================== --- doctools/trunk/Doc-3k/maclib/mac.rst (original) +++ doctools/trunk/Doc-3k/maclib/mac.rst Thu Aug 2 20:07:46 2007 @@ -11,8 +11,8 @@ This module is the Mac OS 9 (and earlier) implementation of the :mod:`os.path` module. It can be used to manipulate old-style Macintosh pathnames on Mac OS X -(or any other platform). Refer to the Python Library Reference (XXX reference: -../lib/lib.html) for documentation of :mod:`os.path`. +(or any other platform). Refer to the Python Library Reference for documentation +of :mod:`os.path`. The following functions are available in this module: :func:`normcase`, :func:`normpath`, :func:`isabs`, :func:`join`, :func:`split`, :func:`isdir`, Modified: doctools/trunk/Doc-3k/reference/datamodel.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/datamodel.rst (original) +++ doctools/trunk/Doc-3k/reference/datamodel.rst Thu Aug 2 20:07:46 2007 @@ -60,8 +60,8 @@ reference-counting scheme with (optional) delayed detection of cyclically linked garbage, which collects most objects as soon as they become unreachable, but is not guaranteed to collect garbage containing circular references. See the -Python Library Reference (XXX reference: ../lib/module-gc.html) for information -on controlling the collection of cyclic garbage.) +documentation of the :mod:`gc` module for information on controlling the +collection of cyclic garbage.) Note that the use of the implementation's tracing or debugging facilities may keep objects alive that would normally be collectable. Also note that catching @@ -865,12 +865,12 @@ single: stderr (in module sys) A file object represents an open file. File objects are created by the - :func:`open` built-in function, and also by :func:`os.popen`, :func:`os.fdopen`, - and the :meth:`makefile` method of socket objects (and perhaps by other - functions or methods provided by extension modules). The objects ``sys.stdin``, - ``sys.stdout`` and ``sys.stderr`` are initialized to file objects corresponding - to the interpreter's standard input, output and error streams. See the Python - Library Reference (XXX reference: ../lib/lib.html) for complete documentation of + :func:`open` built-in function, and also by :func:`os.popen`, + :func:`os.fdopen`, and the :meth:`makefile` method of socket objects (and + perhaps by other functions or methods provided by extension modules). The + objects ``sys.stdin``, ``sys.stdout`` and ``sys.stderr`` are initialized to + file objects corresponding to the interpreter's standard input, output and + error streams. See :ref:`bltin-file-objects` for complete documentation of file objects. Internal types @@ -1215,24 +1215,25 @@ .. note:: - ``del x`` doesn't directly call ``x.__del__()`` --- the former decrements the - reference count for ``x`` by one, and the latter is only called when ``x``'s - reference count reaches zero. Some common situations that may prevent the - reference count of an object from going to zero include: circular references - between objects (e.g., a doubly-linked list or a tree data structure with parent - and child pointers); a reference to the object on the stack frame of a function - that caught an exception (the traceback stored in ``sys.exc_info()[2]`` keeps - the stack frame alive); or a reference to the object on the stack frame that - raised an unhandled exception in interactive mode (the traceback stored in - ``sys.last_traceback`` keeps the stack frame alive). The first situation can - only be remedied by explicitly breaking the cycles; the latter two situations - can be resolved by storing ``None`` in ``sys.last_traceback``. Circular - references which are garbage are detected when the option cycle detector is - enabled (it's on by default), but can only be cleaned up if there are no Python- - level :meth:`__del__` methods involved. Refer to the documentation for the - :mod:`gc` module (XXX reference: ../lib/module-gc.html) for more information - about how :meth:`__del__` methods are handled by the cycle detector, - particularly the description of the ``garbage`` value. + ``del x`` doesn't directly call ``x.__del__()`` --- the former decrements + the reference count for ``x`` by one, and the latter is only called when + ``x``'s reference count reaches zero. Some common situations that may + prevent the reference count of an object from going to zero include: + circular references between objects (e.g., a doubly-linked list or a tree + data structure with parent and child pointers); a reference to the object + on the stack frame of a function that caught an exception (the traceback + stored in ``sys.exc_info()[2]`` keeps the stack frame alive); or a + reference to the object on the stack frame that raised an unhandled + exception in interactive mode (the traceback stored in + ``sys.last_traceback`` keeps the stack frame alive). The first situation + can only be remedied by explicitly breaking the cycles; the latter two + situations can be resolved by storing ``None`` in ``sys.last_traceback``. + Circular references which are garbage are detected when the option cycle + detector is enabled (it's on by default), but can only be cleaned up if + there are no Python- level :meth:`__del__` methods involved. Refer to the + documentation for the :mod:`gc` module for more information about how + :meth:`__del__` methods are handled by the cycle detector, particularly + the description of the ``garbage`` value. .. warning:: @@ -1821,9 +1822,7 @@ should also be made available as the method :meth:`iterkeys`. Iterator objects also need to implement this method; they are required to return - themselves. For more information on iterator objects, see "Iterator Types (XXX - reference: ../lib/typeiter.html)" in the Python Library Reference (XXX - reference: ../lib/lib.html). + themselves. For more information on iterator objects, see :ref:`typeiter`. The membership test operators (:keyword:`in` and :keyword:`not in`) are normally implemented as an iteration through a sequence. However, container objects can @@ -2103,9 +2102,7 @@ Typical uses of context managers include saving and restoring various kinds of global state, locking and unlocking resources, closing opened files, etc. -For more information on context managers, see "Context Types (XXX reference: -../lib/typecontextmanager.html)" in the Python Library Reference (XXX reference: -../lib/lib.html). +For more information on context managers, see :ref:`typecontextmanager`. .. method:: context manager.__enter__(self) Modified: doctools/trunk/Doc-3k/reference/expressions.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/expressions.rst (original) +++ doctools/trunk/Doc-3k/reference/expressions.rst Thu Aug 2 20:07:46 2007 @@ -699,9 +699,8 @@ object: method object: function - The result is up to the interpreter; see the Python Library Reference (XXX - reference: ../lib/built-in-funcs.html) for the descriptions of built-in - functions and methods. + The result is up to the interpreter; see :ref:`built-in-funcs` for the + descriptions of built-in functions and methods. a class object: .. index:: @@ -855,8 +854,7 @@ In addition to performing the modulo operation on numbers, the ``%`` operator is also overloaded by string and unicode objects to perform string formatting (also known as interpolation). The syntax for string formatting is described in the -Python Library Reference (XXX reference: ../lib/typesseq-strings.html), section -"Sequence Types". +Python Library Reference, section :ref:`typesseq-strings`. .. deprecated:: 2.3 The floor division operator, the modulo operator, and the :func:`divmod` @@ -1189,7 +1187,7 @@ expr3, expr4 = expr1, expr2 -.. _summary: +.. _operator-summary: Summary ======= Modified: doctools/trunk/Doc-3k/reference/introduction.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/introduction.rst (original) +++ doctools/trunk/Doc-3k/reference/introduction.rst Thu Aug 2 20:07:46 2007 @@ -29,9 +29,9 @@ you'll find short "implementation notes" sprinkled throughout the text. Every Python implementation comes with a number of built-in and standard -modules. These are not documented here, but in the separate Python Library -Reference (XXX reference: ../lib/lib.html) document. A few built-in modules are -mentioned when they interact in a significant way with the language definition. +modules. These are documented in :ref:`library-index`. A few built-in modules +are mentioned when they interact in a significant way with the language +definition. .. _implementations: Modified: doctools/trunk/Doc-3k/reference/lexical_analysis.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/lexical_analysis.rst (original) +++ doctools/trunk/Doc-3k/reference/lexical_analysis.rst Thu Aug 2 20:07:46 2007 @@ -389,9 +389,9 @@ .. note:: - The name ``_`` is often used in conjunction with internationalization; refer to - the documentation for the :mod:`gettext` module (XXX reference: ../lib/module- - gettext.html) for more information on this convention. + The name ``_`` is often used in conjunction with internationalization; + refer to the documentation for the :mod:`gettext` module for more + information on this convention. ``__*__`` System-defined names. These names are defined by the interpreter and its Modified: doctools/trunk/Doc-3k/reference/simple_stmts.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/simple_stmts.rst (original) +++ doctools/trunk/Doc-3k/reference/simple_stmts.rst Thu Aug 2 20:07:46 2007 @@ -697,9 +697,8 @@ .. index:: builtin: __import__ The built-in function :func:`__import__` is provided to support applications -that determine which modules need to be loaded dynamically; refer to Built-in -Functions (XXX reference: ../lib/built-in-funcs.html) in the Python Library -Reference (XXX reference: ../lib/lib.html) for additional information. +that determine which modules need to be loaded dynamically; refer to +:ref:`built-in-funcs` for additional information. .. _future: @@ -769,9 +768,8 @@ and :func:`execfile` that occur in a module :mod:`M` containing a future statement will, by default, use the new syntax or semantics associated with the future statement. This can, starting with Python 2.2 be controlled by optional -arguments to :func:`compile` --- see the documentation of that function in the -Python Library Reference (XXX reference: ../lib/built-in-funcs.html) for -details. +arguments to :func:`compile` --- see the documentation of that function +for details. A future statement typed at an interactive interpreter prompt will take effect for the rest of the interpreter session. If an interpreter is started with the Modified: doctools/trunk/Doc-3k/tutorial/controlflow.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/controlflow.rst (original) +++ doctools/trunk/Doc-3k/tutorial/controlflow.rst Thu Aug 2 20:07:46 2007 @@ -405,12 +405,12 @@ TypeError: function() got multiple values for keyword argument 'a' When a final formal parameter of the form ``**name`` is present, it receives a -dictionary (XXX reference: ../lib/typesmapping.html) containing all keyword -arguments except for those corresponding to a formal parameter. This may be -combined with a formal parameter of the form ``*name`` (described in the next -subsection) which receives a tuple containing the positional arguments beyond -the formal parameter list. (``*name`` must occur before ``**name``.) For -example, if we define a function like this:: +dictionary (see :ref:`typesmapping`) containing all keyword arguments except for +those corresponding to a formal parameter. This may be combined with a formal +parameter of the form ``*name`` (described in the next subsection) which +receives a tuple containing the positional arguments beyond the formal parameter +list. (``*name`` must occur before ``**name``.) For example, if we define a +function like this:: def cheeseshop(kind, *arguments, **keywords): print "-- Do you have any", kind, '?' Modified: doctools/trunk/Doc-3k/tutorial/datastructures.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/datastructures.rst (original) +++ doctools/trunk/Doc-3k/tutorial/datastructures.rst Thu Aug 2 20:07:46 2007 @@ -47,8 +47,7 @@ is specified, ``a.pop()`` removes and returns the last item in the list. (The square brackets around the *i* in the method signature denote that the parameter is optional, not that you should type square brackets at that position. You - will see this notation frequently in the Python Library Reference (XXX - reference: ../lib/lib.html).) + will see this notation frequently in the Python Library Reference.) .. method:: list.index(x) @@ -271,10 +270,10 @@ ==================== We saw that lists and strings have many common properties, such as indexing and -slicing operations. They are two examples of *sequence* data types (XXX -reference: ../lib/typesseq.html). Since Python is an evolving language, other -sequence data types may be added. There is also another standard sequence data -type: the *tuple*. +slicing operations. They are two examples of *sequence* data types (see +:ref:`typesseq`). Since Python is an evolving language, other sequence data +types may be added. There is also another standard sequence data type: the +*tuple*. A tuple consists of a number of values separated by commas, for instance:: @@ -373,9 +372,9 @@ Dictionaries ============ -Another useful data type built into Python is the *dictionary* (XXX reference: -../lib/typesmapping.html). Dictionaries are sometimes found in other languages -as "associative memories" or "associative arrays". Unlike sequences, which are +Another useful data type built into Python is the *dictionary* (see +:ref:`typesmapping`). Dictionaries are sometimes found in other languages as +"associative memories" or "associative arrays". Unlike sequences, which are indexed by a range of numbers, dictionaries are indexed by *keys*, which can be any immutable type; strings and numbers can always be keys. Tuples can be used as keys if they contain only strings, numbers, or tuples; if a tuple contains Modified: doctools/trunk/Doc-3k/tutorial/errors.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/errors.rst (original) +++ doctools/trunk/Doc-3k/tutorial/errors.rst Thu Aug 2 20:07:46 2007 @@ -71,8 +71,7 @@ traceback listing source lines; however, it will not display lines read from standard input. -The Python Library Reference (XXX reference: ../lib/module-exceptions.html) -lists the built-in exceptions and their meanings. +:ref:`bltin-exceptions` lists the built-in exceptions and their meanings. .. _tut-handling: Modified: doctools/trunk/Doc-3k/tutorial/glossary.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/glossary.rst (original) +++ doctools/trunk/Doc-3k/tutorial/glossary.rst Thu Aug 2 20:07:46 2007 @@ -100,9 +100,9 @@ from __future__ import new_feature - By importing the :mod:`__future__` (XXX reference: ../lib/module-future.html) - module and evaluating its variables, you can see when a new feature was first - added to the language and when it will become the default:: + By importing the :mod:`__future__` module and evaluating its variables, you + can see when a new feature was first added to the language and when it will + become the default:: >>> import __future__ >>> __future__.division @@ -273,9 +273,8 @@ namespaces. Namespaces also aid readability and maintainability by making it clear which module implements a function. For instance, writing :func:`random.seed` or :func:`itertools.izip` makes it clear that those - functions are implemented by the :mod:`random` (XXX reference: ../lib/module- - random.html) and :mod:`itertools` (XXX reference: ../lib/module-itertools.html) - modules respectively. + functions are implemented by the :mod:`random` and :mod:`itertools` modules + respectively. .. index:: single: nested scope Modified: doctools/trunk/Doc-3k/tutorial/inputoutput.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/inputoutput.rst (original) +++ doctools/trunk/Doc-3k/tutorial/inputoutput.rst Thu Aug 2 20:07:46 2007 @@ -323,14 +323,13 @@ complicated. Rather than have users be constantly writing and debugging code to save -complicated data types, Python provides a standard module called :mod:`pickle` -(XXX reference: ../lib/module-pickle.html). This is an amazing module that can -take almost any Python object (even some forms of Python code!), and convert it -to a string representation; this process is called :dfn:`pickling`. -Reconstructing the object from the string representation is called -:dfn:`unpickling`. Between pickling and unpickling, the string representing the -object may have been stored in a file or data, or sent over a network connection -to some distant machine. +complicated data types, Python provides a standard module called :mod:`pickle`. +This is an amazing module that can take almost any Python object (even some +forms of Python code!), and convert it to a string representation; this process +is called :dfn:`pickling`. Reconstructing the object from the string +representation is called :dfn:`unpickling`. Between pickling and unpickling, +the string representing the object may have been stored in a file or data, or +sent over a network connection to some distant machine. If you have an object ``x``, and a file object ``f`` that's been opened for writing, the simplest way to pickle the object takes only one line of code:: @@ -344,15 +343,12 @@ (There are other variants of this, used when pickling many objects or when you don't want to write the pickled data to a file; consult the complete -documentation for :mod:`pickle` (XXX reference: ../lib/module-pickle.html) in -the Python Library Reference (XXX reference: ../lib/).) +documentation for :mod:`pickle` in the Python Library Reference.) -:mod:`pickle` (XXX reference: ../lib/module-pickle.html) is the standard way to -make Python objects which can be stored and reused by other programs or by a -future invocation of the same program; the technical term for this is a -:dfn:`persistent` object. Because :mod:`pickle` (XXX reference: ../lib/module- -pickle.html) is so widely used, many authors who write Python extensions take -care to ensure that new data types such as matrices can be properly pickled and -unpickled. +:mod:`pickle` is the standard way to make Python objects which can be stored and +reused by other programs or by a future invocation of the same program; the +technical term for this is a :dfn:`persistent` object. Because :mod:`pickle` is +so widely used, many authors who write Python extensions take care to ensure +that new data types such as matrices can be properly pickled and unpickled. Modified: doctools/trunk/Doc-3k/tutorial/interactive.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/interactive.rst (original) +++ doctools/trunk/Doc-3k/tutorial/interactive.rst Thu Aug 2 20:07:46 2007 @@ -115,8 +115,8 @@ the startup file is executed in the same namespace as the interactive commands, and removing the names avoids creating side effects in the interactive environment. You may find it convenient to keep some of the imported modules, -such as :mod:`os` (XXX reference: ../lib/module-os.html), which turn out to be -needed in most sessions with the interpreter. :: +such as :mod:`os`, which turn out to be needed in most sessions with the +interpreter. :: # Add auto-completion and a stored history file of commands to your Python # interactive interpreter. Requires Python 2.0+, readline. Autocomplete is Modified: doctools/trunk/Doc-3k/tutorial/interpreter.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/interpreter.rst (original) +++ doctools/trunk/Doc-3k/tutorial/interpreter.rst Thu Aug 2 20:07:46 2007 @@ -182,9 +182,8 @@ With that declaration, all characters in the source file will be treated as having the encoding *encoding*, and it will be possible to directly write Unicode string literals in the selected encoding. The list of possible -encodings can be found in the Python Library Reference (XXX reference: -../lib/lib.html), in the section on :mod:`codecs` (XXX reference: ../lib/module- -codecs.html). +encodings can be found in the Python Library Reference, in the section on +:mod:`codecs`. For example, to write Unicode literals including the Euro currency symbol, the ISO-8859-15 encoding can be used, with the Euro symbol having the ordinal value Modified: doctools/trunk/Doc-3k/tutorial/modules.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/modules.rst (original) +++ doctools/trunk/Doc-3k/tutorial/modules.rst Thu Aug 2 20:07:46 2007 @@ -215,9 +215,8 @@ .. index:: module: compileall -* The module :mod:`compileall` (XXX reference: ../lib/module-compileall.html) - can create :file:`.pyc` files (or :file:`.pyo` files when :option:`-O` is used) - for all modules in a directory. +* The module :mod:`compileall` can create :file:`.pyc` files (or :file:`.pyo` + files when :option:`-O` is used) for all modules in a directory. .. % @@ -230,15 +229,14 @@ .. index:: module: sys Python comes with a library of standard modules, described in a separate -document, the Python Library Reference (XXX reference: ../lib/lib.html) -("Library Reference" hereafter). Some modules are built into the interpreter; -these provide access to operations that are not part of the core of the language -but are nevertheless built in, either for efficiency or to provide access to -operating system primitives such as system calls. The set of such modules is a -configuration option which also depends on the underlying platform For example, -the :mod:`winreg` module is only provided on Windows systems. One particular -module deserves some attention: :mod:`sys` (XXX reference: ../lib/module- -sys.html), which is built into every Python interpreter. The variables +document, the Python Library Reference ("Library Reference" hereafter). Some +modules are built into the interpreter; these provide access to operations that +are not part of the core of the language but are nevertheless built in, either +for efficiency or to provide access to operating system primitives such as +system calls. The set of such modules is a configuration option which also +depends on the underlying platform For example, the :mod:`winreg` module is only +provided on Windows systems. One particular module deserves some attention: +:mod:`sys`, which is built into every Python interpreter. The variables ``sys.ps1`` and ``sys.ps2`` define the strings used as primary and secondary prompts: Modified: doctools/trunk/Doc-3k/tutorial/stdlib.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/stdlib.rst (original) +++ doctools/trunk/Doc-3k/tutorial/stdlib.rst Thu Aug 2 20:07:46 2007 @@ -10,8 +10,8 @@ Operating System Interface ========================== -The :mod:`os` (XXX reference: ../lib/module-os.html) module provides dozens of -functions for interacting with the operating system:: +The :mod:`os` module provides dozens of functions for interacting with the +operating system:: >>> import os >>> os.system('time 0:02') @@ -35,9 +35,8 @@ >>> help(os) -For daily file and directory management tasks, the :mod:`shutil` (XXX -reference: ../lib/module-shutil.html) module provides a higher level interface -that is easier to use:: +For daily file and directory management tasks, the :mod:`shutil` module provides +a higher level interface that is easier to use:: >>> import shutil >>> shutil.copyfile('data.db', 'archive.db') @@ -49,8 +48,8 @@ File Wildcards ============== -The :mod:`glob` (XXX reference: ../lib/module-glob.html) module provides a -function for making file lists from directory wildcard searches:: +The :mod:`glob` module provides a function for making file lists from directory +wildcard searches:: >>> import glob >>> glob.glob('*.py') @@ -63,18 +62,17 @@ ====================== Common utility scripts often need to process command line arguments. These -arguments are stored in the :mod:`sys` (XXX reference: ../lib/module-sys.html) -module's *argv* attribute as a list. For instance the following output results -from running ``python demo.py one two three`` at the command line:: +arguments are stored in the :mod:`sys` module's *argv* attribute as a list. For +instance the following output results from running ``python demo.py one two +three`` at the command line:: >>> import sys >>> print sys.argv ['demo.py', 'one', 'two', 'three'] -The :mod:`getopt` (XXX reference: ../lib/module-getopt.html) module processes -*sys.argv* using the conventions of the Unix :func:`getopt` function. More -powerful and flexible command line processing is provided by the :mod:`optparse` -(XXX reference: ../lib/module-optparse.html) module. +The :mod:`getopt` module processes *sys.argv* using the conventions of the Unix +:func:`getopt` function. More powerful and flexible command line processing is +provided by the :mod:`optparse` module. .. _tut-stderr: @@ -82,10 +80,9 @@ Error Output Redirection and Program Termination ================================================ -The :mod:`sys` (XXX reference: ../lib/module-sys.html) module also has -attributes for *stdin*, *stdout*, and *stderr*. The latter is useful for -emitting warnings and error messages to make them visible even when *stdout* has -been redirected:: +The :mod:`sys` module also has attributes for *stdin*, *stdout*, and *stderr*. +The latter is useful for emitting warnings and error messages to make them +visible even when *stdout* has been redirected:: >>> sys.stderr.write('Warning, log file not found starting a new one\n') Warning, log file not found starting a new one @@ -98,9 +95,9 @@ String Pattern Matching ======================= -The :mod:`re` (XXX reference: ../lib/module-re.html) module provides regular -expression tools for advanced string processing. For complex matching and -manipulation, regular expressions offer succinct, optimized solutions:: +The :mod:`re` module provides regular expression tools for advanced string +processing. For complex matching and manipulation, regular expressions offer +succinct, optimized solutions:: >>> import re >>> re.findall(r'\bf[a-z]*', 'which foot or hand fell fastest') @@ -120,8 +117,8 @@ Mathematics =========== -The :mod:`math` (XXX reference: ../lib/module-math.html) module gives access to -the underlying C library functions for floating point math:: +The :mod:`math` module gives access to the underlying C library functions for +floating point math:: >>> import math >>> math.cos(math.pi / 4.0) @@ -129,8 +126,7 @@ >>> math.log(1024, 2) 10.0 -The :mod:`random` (XXX reference: ../lib/module-random.html) module provides -tools for making random selections:: +The :mod:`random` module provides tools for making random selections:: >>> import random >>> random.choice(['apple', 'pear', 'banana']) @@ -149,9 +145,8 @@ =============== There are a number of modules for accessing the internet and processing internet -protocols. Two of the simplest are :mod:`urllib2` (XXX reference: ../lib/module- -urllib2.html) for retrieving data from urls and :mod:`smtplib` (XXX reference: -../lib/module-smtplib.html) for sending mail:: +protocols. Two of the simplest are :mod:`urllib2` for retrieving data from urls +and :mod:`smtplib` for sending mail:: >>> import urllib2 >>> for line in urllib2.urlopen('http://tycho.usno.navy.mil/cgi-bin/timer.pl'): @@ -176,11 +171,11 @@ Dates and Times =============== -The :mod:`datetime` (XXX reference: ../lib/module-datetime.html) module supplies -classes for manipulating dates and times in both simple and complex ways. While -date and time arithmetic is supported, the focus of the implementation is on -efficient member extraction for output formatting and manipulation. The module -also supports objects that are timezone aware. :: +The :mod:`datetime` module supplies classes for manipulating dates and times in +both simple and complex ways. While date and time arithmetic is supported, the +focus of the implementation is on efficient member extraction for output +formatting and manipulation. The module also supports objects that are timezone +aware. :: # dates are easily constructed and formatted >>> from datetime import date @@ -203,10 +198,8 @@ ================ Common data archiving and compression formats are directly supported by modules -including: :mod:`zlib` (XXX reference: ../lib/module-zlib.html), :mod:`gzip` -(XXX reference: ../lib/module-gzip.html), :mod:`bz2` (XXX reference: ../lib -/module-bz2.html), :mod:`zipfile` (XXX reference: ../lib/module-zipfile.html), -and :mod:`tarfile` (XXX reference: ../lib/module-tarfile.html). :: +including: :mod:`zlib`, :mod:`gzip`, :mod:`bz2`, :mod:`zipfile` and +:mod:`tarfile`. :: >>> import zlib >>> s = 'witch which has which witches wrist watch' @@ -232,8 +225,7 @@ For example, it may be tempting to use the tuple packing and unpacking feature instead of the traditional approach to swapping arguments. The :mod:`timeit` -(XXX reference: ../lib/module-timeit.html) module quickly demonstrates a modest -performance advantage:: +module quickly demonstrates a modest performance advantage:: >>> from timeit import Timer >>> Timer('t=a; a=b; b=t', 'a=1; b=2').timeit() @@ -241,9 +233,9 @@ >>> Timer('a,b = b,a', 'a=1; b=2').timeit() 0.54962537085770791 -In contrast to :mod:`timeit`'s fine level of granularity, the :mod:`profile` -(XXX reference: ../lib/module-profile.html) and :mod:`pstats` modules provide -tools for identifying time critical sections in larger blocks of code. +In contrast to :mod:`timeit`'s fine level of granularity, the :mod:`profile` and +:mod:`pstats` modules provide tools for identifying time critical sections in +larger blocks of code. .. _tut-quality-control: @@ -255,12 +247,12 @@ function as it is developed and to run those tests frequently during the development process. -The :mod:`doctest` (XXX reference: ../lib/module-doctest.html) module provides a -tool for scanning a module and validating tests embedded in a program's -docstrings. Test construction is as simple as cutting-and-pasting a typical -call along with its results into the docstring. This improves the documentation -by providing the user with an example and it allows the doctest module to make -sure the code remains true to the documentation:: +The :mod:`doctest` module provides a tool for scanning a module and validating +tests embedded in a program's docstrings. Test construction is as simple as +cutting-and-pasting a typical call along with its results into the docstring. +This improves the documentation by providing the user with an example and it +allows the doctest module to make sure the code remains true to the +documentation:: def average(values): """Computes the arithmetic mean of a list of numbers. @@ -273,9 +265,9 @@ import doctest doctest.testmod() # automatically validate the embedded tests -The :mod:`unittest` (XXX reference: ../lib/module-unittest.html) module is not -as effortless as the :mod:`doctest` module, but it allows a more comprehensive -set of tests to be maintained in a separate file:: +The :mod:`unittest` module is not as effortless as the :mod:`doctest` module, +but it allows a more comprehensive set of tests to be maintained in a separate +file:: import unittest @@ -298,28 +290,24 @@ Python has a "batteries included" philosophy. This is best seen through the sophisticated and robust capabilities of its larger packages. For example: -* The :mod:`xmlrpclib` (XXX reference: ../lib/module-xmlrpclib.html) and - :mod:`SimpleXMLRPCServer` (XXX reference: ../lib/module-SimpleXMLRPCServer.html) - modules make implementing remote procedure calls into an almost trivial task. - Despite the modules names, no direct knowledge or handling of XML is needed. - -* The :mod:`email` (XXX reference: ../lib/module-email.html) package is a - library for managing email messages, including MIME and other RFC 2822-based - message documents. Unlike :mod:`smtplib` and :mod:`poplib` which actually send - and receive messages, the email package has a complete toolset for building or - decoding complex message structures (including attachments) and for implementing - internet encoding and header protocols. - -* The :mod:`xml.dom` (XXX reference: ../lib/module-xml.dom.html) and - :mod:`xml.sax` (XXX reference: ../lib/module-xml.sax.html) packages provide - robust support for parsing this popular data interchange format. Likewise, the - :mod:`csv` (XXX reference: ../lib/module-csv.html) module supports direct reads - and writes in a common database format. Together, these modules and packages - greatly simplify data interchange between python applications and other tools. +* The :mod:`xmlrpclib` and :mod:`SimpleXMLRPCServer` modules make implementing + remote procedure calls into an almost trivial task. Despite the modules + names, no direct knowledge or handling of XML is needed. + +* The :mod:`email` package is a library for managing email messages, including + MIME and other RFC 2822-based message documents. Unlike :mod:`smtplib` and + :mod:`poplib` which actually send and receive messages, the email package has + a complete toolset for building or decoding complex message structures + (including attachments) and for implementing internet encoding and header + protocols. + +* The :mod:`xml.dom` and :mod:`xml.sax` packages provide robust support for + parsing this popular data interchange format. Likewise, the :mod:`csv` module + supports direct reads and writes in a common database format. Together, these + modules and packages greatly simplify data interchange between python + applications and other tools. * Internationalization is supported by a number of modules including - :mod:`gettext` (XXX reference: ../lib/module-gettext.html), :mod:`locale` (XXX - reference: ../lib/module-locale.html), and the :mod:`codecs` (XXX reference: - ../lib/module-codecs.html) package. + :mod:`gettext`, :mod:`locale`, and the :mod:`codecs` package. Modified: doctools/trunk/Doc-3k/tutorial/stdlib2.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/stdlib2.rst (original) +++ doctools/trunk/Doc-3k/tutorial/stdlib2.rst Thu Aug 2 20:07:46 2007 @@ -13,19 +13,17 @@ Output Formatting ================= -The :mod:`repr` (XXX reference: ../lib/module-repr.html) module provides a -version of :func:`repr` customized for abbreviated displays of large or deeply -nested containers:: +The :mod:`repr` module provides a version of :func:`repr` customized for +abbreviated displays of large or deeply nested containers:: >>> import repr >>> repr.repr(set('supercalifragilisticexpialidocious')) "set(['a', 'c', 'd', 'e', 'f', 'g', ...])" -The :mod:`pprint` (XXX reference: ../lib/module-pprint.html) module offers more -sophisticated control over printing both built-in and user defined objects in a -way that is readable by the interpreter. When the result is longer than one -line, the "pretty printer" adds line breaks and indentation to more clearly -reveal data structure:: +The :mod:`pprint` module offers more sophisticated control over printing both +built-in and user defined objects in a way that is readable by the interpreter. +When the result is longer than one line, the "pretty printer" adds line breaks +and indentation to more clearly reveal data structure:: >>> import pprint >>> t = [[[['black', 'cyan'], 'white', ['green', 'red']], [['magenta', @@ -38,8 +36,8 @@ [['magenta', 'yellow'], 'blue']]] -The :mod:`textwrap` (XXX reference: ../lib/module-textwrap.html) module formats -paragraphs of text to fit a given screen width:: +The :mod:`textwrap` module formats paragraphs of text to fit a given screen +width:: >>> import textwrap >>> doc = """The wrap() method is just like fill() except that it returns @@ -52,10 +50,9 @@ instead of one big string with newlines to separate the wrapped lines. -The :mod:`locale` (XXX reference: ../lib/module-locale.html) module accesses a -database of culture specific data formats. The grouping attribute of locale's -format function provides a direct way of formatting numbers with group -separators:: +The :mod:`locale` module accesses a database of culture specific data formats. +The grouping attribute of locale's format function provides a direct way of +formatting numbers with group separators:: >>> import locale >>> locale.setlocale(locale.LC_ALL, 'English_United States.1252') @@ -74,10 +71,9 @@ Templating ========== -The :mod:`string` (XXX reference: ../lib/module-string.html) module includes a -versatile :class:`Template` class with a simplified syntax suitable for editing -by end-users. This allows users to customize their applications without having -to alter the application. +The :mod:`string` module includes a versatile :class:`Template` class with a +simplified syntax suitable for editing by end-users. This allows users to +customize their applications without having to alter the application. The format uses placeholder names formed by ``$`` with valid Python identifiers (alphanumeric characters and underscores). Surrounding the placeholder with @@ -141,11 +137,10 @@ Working with Binary Data Record Layouts ======================================= -The :mod:`struct` (XXX reference: ../lib/module-struct.html) module provides -:func:`pack` and :func:`unpack` functions for working with variable length -binary record formats. The following example shows how to loop through header -information in a ZIP file (with pack codes ``"H"`` and ``"L"`` representing two -and four byte unsigned numbers respectively):: +The :mod:`struct` module provides :func:`pack` and :func:`unpack` functions for +working with variable length binary record formats. The following example shows +how to loop through header information in a ZIP file (with pack codes ``"H"`` +and ``"L"`` representing two and four byte unsigned numbers respectively):: import struct @@ -175,9 +170,8 @@ that accept user input while other tasks run in the background. A related use case is running I/O in parallel with computations in another thread. -The following code shows how the high level :mod:`threading` (XXX reference: -../lib/module-threading.html) module can run tasks in background while the main -program continues to run:: +The following code shows how the high level :mod:`threading` module can run +tasks in background while the main program continues to run:: import threading, zipfile @@ -207,10 +201,9 @@ While those tools are powerful, minor design errors can result in problems that are difficult to reproduce. So, the preferred approach to task coordination is to concentrate all access to a resource in a single thread and then use the -:mod:`Queue` (XXX reference: ../lib/module-Queue.html) module to feed that -thread with requests from other threads. Applications using :class:`Queue` -objects for inter-thread communication and coordination are easier to design, -more readable, and more reliable. +:mod:`Queue` module to feed that thread with requests from other threads. +Applications using :class:`Queue` objects for inter-thread communication and +coordination are easier to design, more readable, and more reliable. .. _tut-logging: @@ -218,9 +211,8 @@ Logging ======= -The :mod:`logging` (XXX reference: ../lib/module-logging.html) module offers a -full featured and flexible logging system. At its simplest, log messages are -sent to a file or to ``sys.stderr``:: +The :mod:`logging` module offers a full featured and flexible logging system. +At its simplest, log messages are sent to a file or to ``sys.stderr``:: import logging logging.debug('Debugging information') @@ -258,11 +250,10 @@ This approach works fine for most applications but occasionally there is a need to track objects only as long as they are being used by something else. Unfortunately, just tracking them creates a reference that makes them permanent. -The :mod:`weakref` (XXX reference: ../lib/module-weakref.html) module provides -tools for tracking objects without creating a reference. When the object is no -longer needed, it is automatically removed from a weakref table and a callback -is triggered for weakref objects. Typical applications include caching objects -that are expensive to create:: +The :mod:`weakref` module provides tools for tracking objects without creating a +reference. When the object is no longer needed, it is automatically removed +from a weakref table and a callback is triggered for weakref objects. Typical +applications include caching objects that are expensive to create:: >>> import weakref, gc >>> class A: @@ -297,11 +288,11 @@ sometimes there is a need for alternative implementations with different performance trade-offs. -The :mod:`array` (XXX reference: ../lib/module-array.html) module provides an -:class:`array()` object that is like a list that stores only homogenous data and -stores it more compactly. The following example shows an array of numbers -stored as two byte unsigned binary numbers (typecode ``"H"``) rather than the -usual 16 bytes per entry for regular lists of python int objects:: +The :mod:`array` module provides an :class:`array()` object that is like a list +that stores only homogenous data and stores it more compactly. The following +example shows an array of numbers stored as two byte unsigned binary numbers +(typecode ``"H"``) rather than the usual 16 bytes per entry for regular lists of +python int objects:: >>> from array import array >>> a = array('H', [4000, 10, 700, 22222]) @@ -310,10 +301,10 @@ >>> a[1:3] array('H', [10, 700]) -The :mod:`collections` (XXX reference: ../lib/module-collections.html) module -provides a :class:`deque()` object that is like a list with faster appends and -pops from the left side but slower lookups in the middle. These objects are well -suited for implementing queues and breadth first tree searches:: +The :mod:`collections` module provides a :class:`deque()` object that is like a +list with faster appends and pops from the left side but slower lookups in the +middle. These objects are well suited for implementing queues and breadth first +tree searches:: >>> from collections import deque >>> d = deque(["task1", "task2", "task3"]) @@ -330,8 +321,8 @@ unsearched.append(m) In addition to alternative list implementations, the library also offers other -tools such as the :mod:`bisect` (XXX reference: ../lib/module-bisect.html) -module with functions for manipulating sorted lists:: +tools such as the :mod:`bisect` module with functions for manipulating sorted +lists:: >>> import bisect >>> scores = [(100, 'perl'), (200, 'tcl'), (400, 'lua'), (500, 'python')] @@ -339,10 +330,10 @@ >>> scores [(100, 'perl'), (200, 'tcl'), (300, 'ruby'), (400, 'lua'), (500, 'python')] -The :mod:`heapq` (XXX reference: ../lib/module-heapq.html) module provides -functions for implementing heaps based on regular lists. The lowest valued -entry is always kept at position zero. This is useful for applications which -repeatedly access the smallest element but do not want to run a full list sort:: +The :mod:`heapq` module provides functions for implementing heaps based on +regular lists. The lowest valued entry is always kept at position zero. This +is useful for applications which repeatedly access the smallest element but do +not want to run a full list sort:: >>> from heapq import heapify, heappop, heappush >>> data = [1, 3, 5, 7, 9, 2, 4, 6, 8, 0] @@ -357,14 +348,14 @@ Decimal Floating Point Arithmetic ================================= -The :mod:`decimal` (XXX reference: ../lib/module-decimal.html) module offers a -:class:`Decimal` datatype for decimal floating point arithmetic. Compared to -the built-in :class:`float` implementation of binary floating point, the new -class is especially helpful for financial applications and other uses which -require exact decimal representation, control over precision, control over -rounding to meet legal or regulatory requirements, tracking of significant -decimal places, or for applications where the user expects the results to match -calculations done by hand. +The :mod:`decimal` module offers a :class:`Decimal` datatype for decimal +floating point arithmetic. Compared to the built-in :class:`float` +implementation of binary floating point, the new class is especially helpful for +financial applications and other uses which require exact decimal +representation, control over precision, control over rounding to meet legal or +regulatory requirements, tracking of significant decimal places, or for +applications where the user expects the results to match calculations done by +hand. For example, calculating a 5% tax on a 70 cent phone charge gives different results in decimal floating point and binary floating point. The difference Modified: doctools/trunk/Doc-3k/tutorial/whatnow.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/whatnow.rst (original) +++ doctools/trunk/Doc-3k/tutorial/whatnow.rst Thu Aug 2 20:07:46 2007 @@ -11,7 +11,7 @@ This tutorial is part of Python's documentation set. Some other documents in the set are: -* Python Library Reference (XXX reference: ../lib/lib.html): +* :ref:`library-index`: You should browse through this manual, which gives complete (though terse) reference material about types, functions, and the modules in the standard @@ -21,12 +21,12 @@ and many other tasks. Skimming through the Library Reference will give you an idea of what's available. -* Installing Python Modules (XXX reference: ../inst/inst.html) explains how to - install external modules written by other Python users. +* :ref:`install-index` explains how to install external modules written by other + Python users. -* Language Reference (XXX reference: ../ref/ref.html): A detailed explanation - of Python's syntax and semantics. It's heavy reading, but is useful as a - complete guide to the language itself. +* :ref:`reference-index`: A detailed explanation of Python's syntax and + semantics. It's heavy reading, but is useful as a complete guide to the + language itself. More Python resources: Modified: doctools/trunk/Doc-3k/whatsnew/2.3.rst ============================================================================== --- doctools/trunk/Doc-3k/whatsnew/2.3.rst (original) +++ doctools/trunk/Doc-3k/whatsnew/2.3.rst Thu Aug 2 20:07:46 2007 @@ -30,10 +30,9 @@ This article doesn't attempt to provide a complete specification of the new features, but instead provides a convenient overview. For full details, you should refer to the documentation for Python 2.3, such as the Python Library -Reference (XXX reference: ../lib/lib.html) and the Python Reference Manual (XXX -reference: ../ref/ref.html). If you want to understand the complete -implementation and design rationale, refer to the PEP for a particular new -feature. +Reference and the Python Reference Manual. If you want to understand the +complete implementation and design rationale, refer to the PEP for a particular +new feature. .. % ====================================================================== @@ -1345,7 +1344,7 @@ elements in the iterator for which the function :func:`predicate` returns :const:`True`, and ``itertools.repeat(obj, N)`` returns ``obj`` *N* times. There are a number of other functions in the module; see the package's reference - documentation (XXX reference: ../lib/module-itertools.html) for details. + documentation for details. (Contributed by Raymond Hettinger.) * Two new functions in the :mod:`math` module, :func:`degrees(rads)` and @@ -1506,8 +1505,7 @@ the text wrapping strategy. Both the :class:`TextWrapper` class and the :func:`wrap` and :func:`fill` functions support a number of additional keyword arguments for fine-tuning the formatting; consult the module's documentation - (XXX reference: ../lib/module-textwrap.html) for details. (Contributed by Greg - Ward.) + for details. (Contributed by Greg Ward.) * The :mod:`thread` and :mod:`threading` modules now have companion modules, :mod:`dummy_thread` and :mod:`dummy_threading`, that provide a do-nothing @@ -1725,8 +1723,8 @@ support for parsing strings and getting back a :class:`date` or :class:`datetime`. -For more information, refer to the module's reference documentation (XXX -reference: ../lib/module-datetime.html). (Contributed by Tim Peters.) +For more information, refer to the module's reference documentation. +(Contributed by Tim Peters.) .. % ====================================================================== @@ -1787,10 +1785,8 @@ set maximum length of output $ -See the module's documentation (XXX reference: ../lib/module-optparse.html) for -more details. +See the module's documentation for more details. -.. % $ prevent Emacs tex-mode from getting confused Optik was written by Greg Ward, with suggestions from the readers of the Getopt SIG. Modified: doctools/trunk/Doc-3k/whatsnew/2.4.rst ============================================================================== --- doctools/trunk/Doc-3k/whatsnew/2.4.rst (original) +++ doctools/trunk/Doc-3k/whatsnew/2.4.rst Thu Aug 2 20:07:46 2007 @@ -25,10 +25,9 @@ This article doesn't attempt to provide a complete specification of every single new feature, but instead provides a brief introduction to each feature. For full details, you should refer to the documentation for Python 2.4, such as the -Python Library Reference (XXX reference: ../lib/lib.html) and the Python -Reference Manual (XXX reference: ../ref/ref.html). Often you will be referred -to the PEP for a particular new feature for explanations of the implementation -and design rationale. +Python Library Reference and the Python Reference Manual. Often you will be +referred to the PEP for a particular new feature for explanations of the +implementation and design rationale. .. % ====================================================================== Modified: doctools/trunk/Doc-3k/whatsnew/2.6.rst ============================================================================== --- doctools/trunk/Doc-3k/whatsnew/2.6.rst (original) +++ doctools/trunk/Doc-3k/whatsnew/2.6.rst Thu Aug 2 20:07:46 2007 @@ -3,8 +3,8 @@ **************************** :Author: A.M. Kuchling - -.. |release| replace:: 0.0 +:Release: |release| +:Date: |today| .. % $Id: whatsnew26.tex 55963 2007-06-13 18:07:49Z guido.van.rossum $ .. % Rules for maintenance: From python-checkins at python.org Thu Aug 2 21:43:38 2007 From: python-checkins at python.org (guido.van.rossum) Date: Thu, 2 Aug 2007 21:43:38 +0200 (CEST) Subject: [Python-checkins] r56675 - peps/trunk/pep-3141.txt Message-ID: <20070802194338.D52521E400B@bag.python.org> Author: guido.van.rossum Date: Thu Aug 2 21:43:38 2007 New Revision: 56675 Modified: peps/trunk/pep-3141.txt Log: New ersion by Jeffrey, nearing perfection. :-) Modified: peps/trunk/pep-3141.txt ============================================================================== --- peps/trunk/pep-3141.txt (original) +++ peps/trunk/pep-3141.txt Thu Aug 2 21:43:38 2007 @@ -7,7 +7,7 @@ Type: Standards Track Content-Type: text/x-rst Created: 23-Apr-2007 -Post-History: 25-Apr-2007, 16-May-2007, xx-Aug-2007 +Post-History: 25-Apr-2007, 16-May-2007, 02-Aug-2007 Abstract @@ -39,6 +39,9 @@ terminology from PEP 3119, but the hierarchy is intended to be meaningful for any systematic method of defining sets of classes. +The type checks in the standard library should use these classes +instead of the concrete built-ins. + Numeric Classes --------------- @@ -52,7 +55,9 @@ Most implementations of complex numbers will be hashable, but if you need to rely on that, you'll have to check it explicitly: mutable -numbers are supported by this hierarchy. :: +numbers are supported by this hierarchy. **Open issue:** Should +__pos__ coerce the argument to be an instance of the type it's defined +on? Why do the builtins do this? :: class Complex(Number): """Complex defines the operations that work on the builtin complex type. @@ -199,7 +204,7 @@ @abstractmethod def __floordiv__(self, other): - """The floor() of self/other.""" + """The floor() of self/other. Integral.""" raise NotImplementedError @abstractmethod @@ -220,6 +225,7 @@ """< on Reals defines a total ordering, except perhaps for NaN.""" raise NotImplementedError + @abstractmethod def __le__(self, other): raise NotImplementedError @@ -380,19 +386,20 @@ least Integral ``>= x``. 4. ``__round__(self)``, called from ``round(x)``, with returns the - Integral closest to ``x``, rounding half toward even. We could - support the 2-argument version, but then we'd only return an - Integral if the second argument were ``<= 0``. + Integral closest to ``x``, rounding half toward even. **Open + issue:** We could support the 2-argument version, but then we'd + only return an Integral if the second argument were ``<= 0``. 5. ``__properfraction__(self)``, called from a new function, ``math.properfraction(x)``, which resembles C's ``modf()``: returns a pair ``(n:Integral, r:Real)`` where ``x == n + r``, both ``n`` and ``r`` have the same sign as ``x``, and ``abs(r) < 1``. **Open - issue:** Oh, we already have ``math.modf``. Do we want to keep the - bad name? + issue:** Oh, we already have ``math.modf``. What name do we want + for this? Should we use divmod(x, 1) instead? Because the ``int()`` conversion from ``float`` is equivalent to but -less explicit than ``trunc()``, let's remove it. +less explicit than ``trunc()``, let's remove it. (Or, if that breaks +too much, just add a deprecation warning.) ``complex.__{divmod,mod,floordiv,int,float}__`` should also go away. These should continue to raise ``TypeError`` to help confused From python-checkins at python.org Thu Aug 2 22:13:28 2007 From: python-checkins at python.org (collin.winter) Date: Thu, 2 Aug 2007 22:13:28 +0200 (CEST) Subject: [Python-checkins] r56676 - in sandbox/trunk/2to3: fixes/fix_imports.py fixes/fix_stringio.py tests/test_fixers.py Message-ID: <20070802201328.74C101E400F@bag.python.org> Author: collin.winter Date: Thu Aug 2 22:13:27 2007 New Revision: 56676 Added: sandbox/trunk/2to3/fixes/fix_imports.py - copied, changed from r56432, sandbox/trunk/2to3/fixes/fix_stringio.py Removed: sandbox/trunk/2to3/fixes/fix_stringio.py Modified: sandbox/trunk/2to3/ (props changed) sandbox/trunk/2to3/tests/test_fixers.py Log: Turn fix_stringio into a more general import fixer (fix_imports). Copied: sandbox/trunk/2to3/fixes/fix_imports.py (from r56432, sandbox/trunk/2to3/fixes/fix_stringio.py) ============================================================================== --- sandbox/trunk/2to3/fixes/fix_stringio.py (original) +++ sandbox/trunk/2to3/fixes/fix_imports.py Thu Aug 2 22:13:27 2007 @@ -13,32 +13,47 @@ # Local imports from fixes import basefix -from fixes.util import Name, attr_chain, any +from fixes.util import Name, attr_chain, any, set -MODULE = "('StringIO' | 'cStringIO')" +MAPPING = {"StringIO": ("io", ["StringIO"]), + "cStringIO": ("io", ["StringIO"]), + "md5": ("hashlib", ["md5"])} + + +def alternates(members): + return "(" + "|".join(map(repr, members)) + ")" + + +def build_pattern(): + bare = set() + for old_module, (new_module, members) in MAPPING.items(): + bare.add(old_module) + bare.update(members) + members = alternates(members) + yield """import_name< 'import' (module=%r + | dotted_as_names< any* module=%r any* >) > + """ % (old_module, old_module) + yield """import_from< 'from' module_name=%r 'import' + ( %s | import_as_name< %s 'as' any >) > + """ % (old_module, members, members) + yield """import_from< 'from' module_name=%r 'import' star='*' > + """ % old_module + yield """import_name< 'import' + dotted_as_name< module_name=%r 'as' any > > + """ % old_module + yield """power< module_name=%r trailer< '.' %s > any* > + """ % (old_module, members) + yield """bare_name=%s""" % alternates(bare) -class FixStringio(basefix.BaseFix): - PATTERN = """ - import_name< 'import' (module=%s - | dotted_as_names< any* module=%s any* >) > - | - import_from< 'from' module_name=%s 'import' - ( 'StringIO' | import_as_name< 'StringIO' 'as' any >) > - | - import_from< 'from' module_name=%s 'import' star='*' > - | - import_name< 'import' dotted_as_name< module_name=%s 'as' any > > - | - power< module_name=%s trailer< '.' 'StringIO' > any* > - | - bare_name=%s - """ % ((MODULE,) * 7) + +class FixImports(basefix.BaseFix): + PATTERN = "|".join(build_pattern()) order = "pre" # Pre-order tree traversal - # Don't match 'StringIO' if it's within another match + # Don't match the node if it's within another match def match(self, node): - match = super(FixStringio, self).match + match = super(FixImports, self).match results = match(node) if results: if any([match(obj) for obj in attr_chain(node, "parent")]): @@ -47,24 +62,28 @@ return False def start_tree(self, tree, filename): - super(FixStringio, self).start_tree(tree, filename) - self.module_import = False + super(FixImports, self).start_tree(tree, filename) + self.replace = {} def transform(self, node, results): import_mod = results.get("module") - module_name = results.get("module_name") + mod_name = results.get("module_name") bare_name = results.get("bare_name") star = results.get("star") + if import_mod or mod_name: + new_name, members = MAPPING[(import_mod or mod_name).value] + if import_mod: - import_mod = import_mod[0] - self.module_import = True - import_mod.replace(Name("io", prefix=import_mod.get_prefix())) - elif module_name: - module_name = module_name[0] - module_name.replace(Name("io", prefix=module_name.get_prefix())) + self.replace[import_mod.value] = new_name + import_mod.replace(Name(new_name, prefix=import_mod.get_prefix())) + elif mod_name: if star: - star.replace(Name("StringIO", prefix=star.get_prefix())) - elif bare_name and self.module_import: + self.cannot_convert(node, "Cannot handle star imports.") + else: + mod_name.replace(Name(new_name, prefix=mod_name.get_prefix())) + elif bare_name: bare_name = bare_name[0] - bare_name.replace(Name("io", prefix=bare_name.get_prefix())) + new_name = self.replace.get(bare_name.value) + if new_name: + bare_name.replace(Name(new_name, prefix=bare_name.get_prefix())) Deleted: /sandbox/trunk/2to3/fixes/fix_stringio.py ============================================================================== --- /sandbox/trunk/2to3/fixes/fix_stringio.py Thu Aug 2 22:13:27 2007 +++ (empty file) @@ -1,70 +0,0 @@ -"""StringIO.StringIO -> io.StringIO (imports, too). - -Imports this fixer picks up on: -* "import StringIO" -> "import io" -* "from StringIO import StringIO" -> "from io import StringIO" -* "import StringIO as foo" -> "import io as foo" - -If the fixer finds "import StringIO", all "StringIO.StringIO" attribute -lookups will be translated to "io.StringIO" and all "StringIO" names -will be translated to "io". -""" -# Author: Collin Winter - -# Local imports -from fixes import basefix -from fixes.util import Name, attr_chain, any - -MODULE = "('StringIO' | 'cStringIO')" - -class FixStringio(basefix.BaseFix): - PATTERN = """ - import_name< 'import' (module=%s - | dotted_as_names< any* module=%s any* >) > - | - import_from< 'from' module_name=%s 'import' - ( 'StringIO' | import_as_name< 'StringIO' 'as' any >) > - | - import_from< 'from' module_name=%s 'import' star='*' > - | - import_name< 'import' dotted_as_name< module_name=%s 'as' any > > - | - power< module_name=%s trailer< '.' 'StringIO' > any* > - | - bare_name=%s - """ % ((MODULE,) * 7) - - order = "pre" # Pre-order tree traversal - - # Don't match 'StringIO' if it's within another match - def match(self, node): - match = super(FixStringio, self).match - results = match(node) - if results: - if any([match(obj) for obj in attr_chain(node, "parent")]): - return False - return results - return False - - def start_tree(self, tree, filename): - super(FixStringio, self).start_tree(tree, filename) - self.module_import = False - - def transform(self, node, results): - import_mod = results.get("module") - module_name = results.get("module_name") - bare_name = results.get("bare_name") - star = results.get("star") - - if import_mod: - import_mod = import_mod[0] - self.module_import = True - import_mod.replace(Name("io", prefix=import_mod.get_prefix())) - elif module_name: - module_name = module_name[0] - module_name.replace(Name("io", prefix=module_name.get_prefix())) - if star: - star.replace(Name("StringIO", prefix=star.get_prefix())) - elif bare_name and self.module_import: - bare_name = bare_name[0] - bare_name.replace(Name("io", prefix=bare_name.get_prefix())) Modified: sandbox/trunk/2to3/tests/test_fixers.py ============================================================================== --- sandbox/trunk/2to3/tests/test_fixers.py (original) +++ sandbox/trunk/2to3/tests/test_fixers.py Thu Aug 2 22:13:27 2007 @@ -1277,73 +1277,80 @@ self.unchanged(s) -class Test_stringio(FixerTestCase): - fixer = "stringio" +class Test_imports(FixerTestCase): + fixer = "imports" - modules = ["StringIO", "cStringIO"] + modules = {"StringIO": ("io", ["StringIO"]), + "cStringIO": ("io", ["StringIO"]), + "md5": ("hashlib", ["md5"])} def test_import_module(self): - for module in self.modules: - b = "import %s" % module - a = "import io" + for old, (new, members) in self.modules.items(): + b = "import %s" % old + a = "import %s" % new self.check(b, a) - b = "import foo, %s, bar" % module - a = "import foo, io, bar" + b = "import foo, %s, bar" % old + a = "import foo, %s, bar" % new self.check(b, a) def test_import_from(self): - for module in self.modules: - b = "from %s import StringIO" % module - a = "from io import StringIO" - self.check(b, a) - - b = "from %s import *" % module - a = "from io import StringIO" - self.check(b, a) + for old, (new, members) in self.modules.items(): + for member in members: + b = "from %s import %s" % (old, ", ".join(members)) + a = "from %s import %s" % (new, ", ".join(members)) + self.check(b, a) - s = "from foo import StringIO" - self.unchanged(s) + s = "from foo import %s" % ", ".join(members) + self.unchanged(s) def test_import_module_as(self): - for module in self.modules: - b = "import %s as foo_bar" % module - a = "import io as foo_bar" + for old, (new, members) in self.modules.items(): + b = "import %s as foo_bar" % old + a = "import %s as foo_bar" % new self.check(b, a) - b = "import %s as foo_bar" % module - a = "import io as foo_bar" + b = "import %s as foo_bar" % old + a = "import %s as foo_bar" % new self.check(b, a) def test_import_from_as(self): - for module in self.modules: - b = "from %s import StringIO as foo_bar" % module - a = "from io import StringIO as foo_bar" - self.check(b, a) + for old, (new, members) in self.modules.items(): + for member in members: + b = "from %s import %s as foo_bar" % (old, ", ".join(members)) + a = "from %s import %s as foo_bar" % (new, ", ".join(members)) + self.check(b, a) + + def test_star(self): + for old in self.modules: + s = "from %s import *" % old + self.warns_unchanged(s, "Cannot handle star imports") def test_import_module_usage(self): - for module in self.modules: - b = """ - import %s - foo(%s, %s.StringIO) - """ % (module, module, module) - a = """ - import io - foo(io, io.StringIO) - """ - self.check(b, a) + for old, (new, members) in self.modules.items(): + for member in members: + b = """ + import %s + foo(%s, %s.%s) + """ % (old, old, old, member) + a = """ + import %s + foo(%s, %s.%s) + """ % (new, new, new, member) + self.check(b, a) def test_from_import_usage(self): - for module in self.modules: - b = """ - from %s import StringIO - foo(StringIO, StringIO()) - """ % module - a = """ - from io import StringIO - foo(StringIO, StringIO()) - """ - self.check(b, a) + for old, (new, members) in self.modules.items(): + for member in members: + b = """ + from %s import %s + foo(%s, %s()) + """ % (old, member, member, member) + a = """ + from %s import %s + foo(%s, %s()) + """ % (new, member, member, member) + self.check(b, a) class Test_input(FixerTestCase): From python-checkins at python.org Thu Aug 2 22:13:40 2007 From: python-checkins at python.org (collin.winter) Date: Thu, 2 Aug 2007 22:13:40 +0200 (CEST) Subject: [Python-checkins] r56677 - in sandbox/trunk/2to3: README fixes/fix_imports.py Message-ID: <20070802201340.CC34F1E4014@bag.python.org> Author: collin.winter Date: Thu Aug 2 22:13:40 2007 New Revision: 56677 Modified: sandbox/trunk/2to3/ (props changed) sandbox/trunk/2to3/README sandbox/trunk/2to3/fixes/fix_imports.py Log: Docs fixes. Modified: sandbox/trunk/2to3/README ============================================================================== --- sandbox/trunk/2to3/README (original) +++ sandbox/trunk/2to3/README Thu Aug 2 22:13:40 2007 @@ -49,6 +49,8 @@ * **fix_has_key** - "d.has_key(x)" -> "x in d". +* **fix_imports** - Fix incompatible imports. + * **fix_input** - "input()" -> "eval(input())" (PEP 3111). * **fix_intern** - "intern(x)" -> "sys.intern(x)". @@ -73,8 +75,6 @@ * **fix_repr** - swap backticks for repr() calls. -* **fix_stringio** - StringIO.StringIO -> io.StringIO (imports, too). - * **fix_throw** - fix generator.throw() calls to be 3.0-compliant (PEP 3109). * **fix_tuple_params** - remove tuple parameters from function, method and Modified: sandbox/trunk/2to3/fixes/fix_imports.py ============================================================================== --- sandbox/trunk/2to3/fixes/fix_imports.py (original) +++ sandbox/trunk/2to3/fixes/fix_imports.py Thu Aug 2 22:13:40 2007 @@ -1,13 +1,9 @@ -"""StringIO.StringIO -> io.StringIO (imports, too). +"""Fix incompatible imports and module references. -Imports this fixer picks up on: -* "import StringIO" -> "import io" -* "from StringIO import StringIO" -> "from io import StringIO" -* "import StringIO as foo" -> "import io as foo" - -If the fixer finds "import StringIO", all "StringIO.StringIO" attribute -lookups will be translated to "io.StringIO" and all "StringIO" names -will be translated to "io". +Fixes: + * StringIO -> io + * cStringIO -> io + * md5 -> hashlib """ # Author: Collin Winter From python-checkins at python.org Thu Aug 2 22:33:09 2007 From: python-checkins at python.org (georg.brandl) Date: Thu, 2 Aug 2007 22:33:09 +0200 (CEST) Subject: [Python-checkins] r56678 - in doctools/trunk: Doc-26/TODO Doc-26/library/cgi.rst Doc-26/library/code.rst Doc-26/library/cookielib.rst Doc-26/library/doctest.rst Doc-26/library/email.mime.rst Doc-26/library/fileinput.rst Doc-26/library/functools.rst Doc-26/library/logging.rst Doc-26/library/mailcap.rst Doc-26/library/mimewriter.rst Doc-26/library/operator.rst Doc-26/library/os.path.rst Doc-26/library/profile.rst Doc-26/library/py_compile.rst Doc-26/library/re.rst Doc-26/library/runpy.rst Doc-26/library/smtpd.rst Doc-26/library/struct.rst Doc-26/library/urllib2.rst Doc-26/library/urlparse.rst Doc-26/library/wsgiref.rst Doc-3k/TODO Doc-3k/library/cgi.rst Doc-3k/library/code.rst Doc-3k/library/cookielib.rst Doc-3k/library/doctest.rst Doc-3k/library/email.mime.rst Doc-3k/library/fileinput.rst Doc-3k/library/functools.rst Doc-3k/library/logging.rst Doc-3k/library/mailcap.rst Doc-3k/library/operator.rst Doc-3k/library/os.path.rst Doc-3k/library/profile.rst Doc-3k/library/py_compile.rst Doc-3k/library/re.rst Doc-3k/library/runpy.rst Doc-3k/library/smtpd.rst Doc-3k/library/struct.rst Doc-3k/library/urllib2.rst Doc-3k/library/urlparse.rst Doc-3k/library/wsgiref.rst Message-ID: <20070802203309.9BB381E4037@bag.python.org> Author: georg.brandl Date: Thu Aug 2 22:33:06 2007 New Revision: 56678 Modified: doctools/trunk/Doc-26/TODO doctools/trunk/Doc-26/library/cgi.rst doctools/trunk/Doc-26/library/code.rst doctools/trunk/Doc-26/library/cookielib.rst doctools/trunk/Doc-26/library/doctest.rst doctools/trunk/Doc-26/library/email.mime.rst doctools/trunk/Doc-26/library/fileinput.rst doctools/trunk/Doc-26/library/functools.rst doctools/trunk/Doc-26/library/logging.rst doctools/trunk/Doc-26/library/mailcap.rst doctools/trunk/Doc-26/library/mimewriter.rst doctools/trunk/Doc-26/library/operator.rst doctools/trunk/Doc-26/library/os.path.rst doctools/trunk/Doc-26/library/profile.rst doctools/trunk/Doc-26/library/py_compile.rst doctools/trunk/Doc-26/library/re.rst doctools/trunk/Doc-26/library/runpy.rst doctools/trunk/Doc-26/library/smtpd.rst doctools/trunk/Doc-26/library/struct.rst doctools/trunk/Doc-26/library/urllib2.rst doctools/trunk/Doc-26/library/urlparse.rst doctools/trunk/Doc-26/library/wsgiref.rst doctools/trunk/Doc-3k/TODO doctools/trunk/Doc-3k/library/cgi.rst doctools/trunk/Doc-3k/library/code.rst doctools/trunk/Doc-3k/library/cookielib.rst doctools/trunk/Doc-3k/library/doctest.rst doctools/trunk/Doc-3k/library/email.mime.rst doctools/trunk/Doc-3k/library/fileinput.rst doctools/trunk/Doc-3k/library/functools.rst doctools/trunk/Doc-3k/library/logging.rst doctools/trunk/Doc-3k/library/mailcap.rst doctools/trunk/Doc-3k/library/operator.rst doctools/trunk/Doc-3k/library/os.path.rst doctools/trunk/Doc-3k/library/profile.rst doctools/trunk/Doc-3k/library/py_compile.rst doctools/trunk/Doc-3k/library/re.rst doctools/trunk/Doc-3k/library/runpy.rst doctools/trunk/Doc-3k/library/smtpd.rst doctools/trunk/Doc-3k/library/struct.rst doctools/trunk/Doc-3k/library/urllib2.rst doctools/trunk/Doc-3k/library/urlparse.rst doctools/trunk/Doc-3k/library/wsgiref.rst Log: Add missing synopses for library modules. Modified: doctools/trunk/Doc-26/TODO ============================================================================== --- doctools/trunk/Doc-26/TODO (original) +++ doctools/trunk/Doc-26/TODO Thu Aug 2 22:33:06 2007 @@ -4,7 +4,6 @@ * split very large files and add toctrees * integrate standalone HOWTOs * find out which files get "comments disabled" metadata -* add synopses for each module * write "About these documents" * finish "Documenting Python" * extend copyright.rst Modified: doctools/trunk/Doc-26/library/cgi.rst ============================================================================== --- doctools/trunk/Doc-26/library/cgi.rst (original) +++ doctools/trunk/Doc-26/library/cgi.rst Thu Aug 2 22:33:06 2007 @@ -3,8 +3,7 @@ ================================================ .. module:: cgi - - + :synopsis: Helpers for running Python scripts via the Common Gateway Interface. .. index:: @@ -13,13 +12,10 @@ pair: HTTP; protocol pair: MIME; headers single: URL - -.. index:: single: Common Gateway Interface + single: Common Gateway Interface Support module for Common Gateway Interface (CGI) scripts. -.. % - This module defines a number of utilities for use by CGI scripts written in Python. Modified: doctools/trunk/Doc-26/library/code.rst ============================================================================== --- doctools/trunk/Doc-26/library/code.rst (original) +++ doctools/trunk/Doc-26/library/code.rst Thu Aug 2 22:33:06 2007 @@ -3,7 +3,7 @@ ======================================== .. module:: code - + :synopsis: Facilities to implement read-eval-print loops. Modified: doctools/trunk/Doc-26/library/cookielib.rst ============================================================================== --- doctools/trunk/Doc-26/library/cookielib.rst (original) +++ doctools/trunk/Doc-26/library/cookielib.rst Thu Aug 2 22:33:06 2007 @@ -3,6 +3,7 @@ ===================================================== .. module:: cookielib + :synopsis: Classes for automatic handling of HTTP cookies. .. moduleauthor:: John J. Lee .. sectionauthor:: John J. Lee Modified: doctools/trunk/Doc-26/library/doctest.rst ============================================================================== --- doctools/trunk/Doc-26/library/doctest.rst (original) +++ doctools/trunk/Doc-26/library/doctest.rst Thu Aug 2 22:33:06 2007 @@ -1,16 +1,14 @@ - :mod:`doctest` --- Test interactive Python examples =================================================== .. module:: doctest + :synopsis: Test pieces of code within docstrings. .. moduleauthor:: Tim Peters .. sectionauthor:: Tim Peters .. sectionauthor:: Moshe Zadka .. sectionauthor:: Edward Loper - - The :mod:`doctest` module searches for pieces of text that look like interactive Python sessions, and then executes those sessions to verify that they work exactly as shown. There are several common ways to use doctest: Modified: doctools/trunk/Doc-26/library/email.mime.rst ============================================================================== --- doctools/trunk/Doc-26/library/email.mime.rst (original) +++ doctools/trunk/Doc-26/library/email.mime.rst Thu Aug 2 22:33:06 2007 @@ -1,7 +1,8 @@ :mod:`email`: Creating email and MIME objects from scratch ---------------------------------------------------------- -.. module:: email.mime.text +.. module:: email.mime + :synopsis: Build MIME messages. Ordinarily, you get a message object structure by passing a file or some text to Modified: doctools/trunk/Doc-26/library/fileinput.rst ============================================================================== --- doctools/trunk/Doc-26/library/fileinput.rst (original) +++ doctools/trunk/Doc-26/library/fileinput.rst Thu Aug 2 22:33:06 2007 @@ -1,14 +1,12 @@ - :mod:`fileinput` --- Iterate over lines from multiple input streams =================================================================== .. module:: fileinput + :synopsis: Loop over standard input or a list of files. .. moduleauthor:: Guido van Rossum .. sectionauthor:: Fred L. Drake, Jr. - - This module implements a helper class and functions to quickly write a loop over standard input or a list of files. Modified: doctools/trunk/Doc-26/library/functools.rst ============================================================================== --- doctools/trunk/Doc-26/library/functools.rst (original) +++ doctools/trunk/Doc-26/library/functools.rst Thu Aug 2 22:33:06 2007 @@ -1,18 +1,14 @@ - -:mod:`functools` --- Higher order functions and operations on callable objects. -=============================================================================== +:mod:`functools` --- Higher order functions and operations on callable objects +============================================================================== .. module:: functools + :synopsis: Higher order functions and operations on callable objects. .. moduleauthor:: Peter Harris .. moduleauthor:: Raymond Hettinger .. moduleauthor:: Nick Coghlan .. sectionauthor:: Peter Harris -.. % standard library, in Python - - - .. versionadded:: 2.5 The :mod:`functools` module is for higher-order functions: functions that act on Modified: doctools/trunk/Doc-26/library/logging.rst ============================================================================== --- doctools/trunk/Doc-26/library/logging.rst (original) +++ doctools/trunk/Doc-26/library/logging.rst Thu Aug 2 22:33:06 2007 @@ -1,8 +1,8 @@ - :mod:`logging` --- Logging facility for Python ============================================== .. module:: logging + :synopsis: Flexible error logging system for applications. .. moduleauthor:: Vinay Sajip Modified: doctools/trunk/Doc-26/library/mailcap.rst ============================================================================== --- doctools/trunk/Doc-26/library/mailcap.rst (original) +++ doctools/trunk/Doc-26/library/mailcap.rst Thu Aug 2 22:33:06 2007 @@ -1,9 +1,8 @@ - -:mod:`mailcap` --- Mailcap file handling. -========================================= +:mod:`mailcap` --- Mailcap file handling +======================================== .. module:: mailcap - + :synopsis: Mailcap file handling. Modified: doctools/trunk/Doc-26/library/mimewriter.rst ============================================================================== --- doctools/trunk/Doc-26/library/mimewriter.rst (original) +++ doctools/trunk/Doc-26/library/mimewriter.rst Thu Aug 2 22:33:06 2007 @@ -1,9 +1,8 @@ - :mod:`MimeWriter` --- Generic MIME file writer ============================================== .. module:: MimeWriter - + :synopsis: Write MIME format files. .. sectionauthor:: Christopher G. Petrilli Modified: doctools/trunk/Doc-26/library/operator.rst ============================================================================== --- doctools/trunk/Doc-26/library/operator.rst (original) +++ doctools/trunk/Doc-26/library/operator.rst Thu Aug 2 22:33:06 2007 @@ -1,13 +1,12 @@ - -:mod:`operator` --- Standard operators as functions. -==================================================== +:mod:`operator` --- Standard operators as functions +=================================================== .. module:: operator + :synopsis: Functions corresponding to the standard operators. .. sectionauthor:: Skip Montanaro - The :mod:`operator` module exports a set of functions implemented in C corresponding to the intrinsic operators of Python. For example, ``operator.add(x, y)`` is equivalent to the expression ``x+y``. The function Modified: doctools/trunk/Doc-26/library/os.path.rst ============================================================================== --- doctools/trunk/Doc-26/library/os.path.rst (original) +++ doctools/trunk/Doc-26/library/os.path.rst Thu Aug 2 22:33:06 2007 @@ -3,8 +3,7 @@ ================================================ .. module:: os.path - - + :synopsis: Operations on pathnames. .. index:: single: path; operations Modified: doctools/trunk/Doc-26/library/profile.rst ============================================================================== --- doctools/trunk/Doc-26/library/profile.rst (original) +++ doctools/trunk/Doc-26/library/profile.rst Thu Aug 2 22:33:06 2007 @@ -355,11 +355,9 @@ The :class:`Stats` class is defined in the :mod:`pstats` module. -.. module:: pstats - -.. % now switch modules.... -.. % (This \stmodindex use may be hard to change ;-( ) +.. module:: pstats + :synopsis: Statistics object for use with the profiler. .. class:: Stats(filename[, stream=sys.stdout[, ...]]) Modified: doctools/trunk/Doc-26/library/py_compile.rst ============================================================================== --- doctools/trunk/Doc-26/library/py_compile.rst (original) +++ doctools/trunk/Doc-26/library/py_compile.rst Thu Aug 2 22:33:06 2007 @@ -1,9 +1,8 @@ - :mod:`py_compile` --- Compile Python source files ================================================= .. module:: py_compile - + :synopsis: Generate byte-code files from Python source files. .. % Documentation based on module docstrings, by Fred L. Drake, Jr. .. % Modified: doctools/trunk/Doc-26/library/re.rst ============================================================================== --- doctools/trunk/Doc-26/library/re.rst (original) +++ doctools/trunk/Doc-26/library/re.rst Thu Aug 2 22:33:06 2007 @@ -3,6 +3,7 @@ =========================================== .. module:: re + :synopsis: Regular expression operations. .. moduleauthor:: Fredrik Lundh .. sectionauthor:: Andrew M. Kuchling Modified: doctools/trunk/Doc-26/library/runpy.rst ============================================================================== --- doctools/trunk/Doc-26/library/runpy.rst (original) +++ doctools/trunk/Doc-26/library/runpy.rst Thu Aug 2 22:33:06 2007 @@ -1,15 +1,11 @@ - -:mod:`runpy` --- Locating and executing Python modules. -======================================================= +:mod:`runpy` --- Locating and executing Python modules +====================================================== .. module:: runpy + :synopsis: Locate and run Python modules without importing them first. .. moduleauthor:: Nick Coghlan -.. % standard library, in Python - - - .. versionadded:: 2.5 The :mod:`runpy` module is used to locate and run Python modules without Modified: doctools/trunk/Doc-26/library/smtpd.rst ============================================================================== --- doctools/trunk/Doc-26/library/smtpd.rst (original) +++ doctools/trunk/Doc-26/library/smtpd.rst Thu Aug 2 22:33:06 2007 @@ -1,9 +1,8 @@ - :mod:`smtpd` --- SMTP Server ============================ .. module:: smtpd - + :synopsis: A SMTP server implementation in Python. .. moduleauthor:: Barry Warsaw .. sectionauthor:: Moshe Zadka Modified: doctools/trunk/Doc-26/library/struct.rst ============================================================================== --- doctools/trunk/Doc-26/library/struct.rst (original) +++ doctools/trunk/Doc-26/library/struct.rst Thu Aug 2 22:33:06 2007 @@ -3,9 +3,7 @@ ========================================================= .. module:: struct - - - + :synopsis: Interpret strings as packed binary data. .. index:: pair: C; structures Modified: doctools/trunk/Doc-26/library/urllib2.rst ============================================================================== --- doctools/trunk/Doc-26/library/urllib2.rst (original) +++ doctools/trunk/Doc-26/library/urllib2.rst Thu Aug 2 22:33:06 2007 @@ -1,14 +1,12 @@ - :mod:`urllib2` --- extensible library for opening URLs ====================================================== .. module:: urllib2 + :synopsis: Next generation URL opening library. .. moduleauthor:: Jeremy Hylton .. sectionauthor:: Moshe Zadka - - The :mod:`urllib2` module defines functions and classes which help in opening URLs (mostly HTTP) in a complex world --- basic and digest authentication, redirections, cookies and more. Modified: doctools/trunk/Doc-26/library/urlparse.rst ============================================================================== --- doctools/trunk/Doc-26/library/urlparse.rst (original) +++ doctools/trunk/Doc-26/library/urlparse.rst Thu Aug 2 22:33:06 2007 @@ -1,10 +1,8 @@ - :mod:`urlparse` --- Parse URLs into components ============================================== .. module:: urlparse - - + :synopsis: Parse URLs into or assemble them from components. .. index:: Modified: doctools/trunk/Doc-26/library/wsgiref.rst ============================================================================== --- doctools/trunk/Doc-26/library/wsgiref.rst (original) +++ doctools/trunk/Doc-26/library/wsgiref.rst Thu Aug 2 22:33:06 2007 @@ -1,9 +1,8 @@ - :mod:`wsgiref` --- WSGI Utilities and Reference Implementation ============================================================== .. module:: wsgiref - :synopsis: WSGI Utilities and Reference Implementation + :synopsis: WSGI Utilities and Reference Implementation. .. moduleauthor:: Phillip J. Eby .. sectionauthor:: Phillip J. Eby @@ -37,6 +36,7 @@ ------------------------------------------------- .. module:: wsgiref.util + :synopsis: WSGI environment utilities. This module provides a variety of utility functions for working with WSGI @@ -142,6 +142,7 @@ ---------------------------------------------------- .. module:: wsgiref.headers + :synopsis: WSGI response header tools. This module provides a single class, :class:`Headers`, for convenient @@ -221,6 +222,7 @@ --------------------------------------------------------- .. module:: wsgiref.simple_server + :synopsis: A simple WSGI HTTP server. This module implements a simple HTTP server (based on :mod:`BaseHTTPServer`) @@ -232,7 +234,7 @@ :mod:`wsgiref.util`.) -.. function:: make_server(host, port, app [, server_class=:class:`WSGIServer` [, handler_class=:class:`WSGIRequestHandler`]]) +.. function:: make_server(host, port, app [, server_class=WSGIServer [, handler_class=:class:`WSGIRequestHandler`]]) Create a new WSGI server listening on *host* and *port*, accepting connections for *app*. The return value is an instance of the supplied *server_class*, and @@ -327,10 +329,11 @@ interface. -:mod:`wsgiref.validate` -- WSGI conformance checker ---------------------------------------------------- +:mod:`wsgiref.validate` --- WSGI conformance checker +---------------------------------------------------- .. module:: wsgiref.validate + :synopsis: WSGI conformance checker. When creating new WSGI application objects, frameworks, servers, or middleware, @@ -375,6 +378,7 @@ ------------------------------------------------------ .. module:: wsgiref.handlers + :synopsis: WSGI server/gateway base classes. This module provides base handler classes for implementing WSGI servers and Modified: doctools/trunk/Doc-3k/TODO ============================================================================== --- doctools/trunk/Doc-3k/TODO (original) +++ doctools/trunk/Doc-3k/TODO Thu Aug 2 22:33:06 2007 @@ -4,7 +4,6 @@ * split very large files and add toctrees * integrate standalone HOWTOs * find out which files get "comments disabled" metadata -* add synopses for each module * write "About these documents" * finish "Documenting Python" * extend copyright.rst Modified: doctools/trunk/Doc-3k/library/cgi.rst ============================================================================== --- doctools/trunk/Doc-3k/library/cgi.rst (original) +++ doctools/trunk/Doc-3k/library/cgi.rst Thu Aug 2 22:33:06 2007 @@ -3,8 +3,7 @@ ================================================ .. module:: cgi - - + :synopsis: Helpers for running Python scripts via the Common Gateway Interface. .. index:: @@ -13,13 +12,10 @@ pair: HTTP; protocol pair: MIME; headers single: URL - -.. index:: single: Common Gateway Interface + single: Common Gateway Interface Support module for Common Gateway Interface (CGI) scripts. -.. % - This module defines a number of utilities for use by CGI scripts written in Python. Modified: doctools/trunk/Doc-3k/library/code.rst ============================================================================== --- doctools/trunk/Doc-3k/library/code.rst (original) +++ doctools/trunk/Doc-3k/library/code.rst Thu Aug 2 22:33:06 2007 @@ -3,7 +3,7 @@ ======================================== .. module:: code - + :synopsis: Facilities to implement read-eval-print loops. Modified: doctools/trunk/Doc-3k/library/cookielib.rst ============================================================================== --- doctools/trunk/Doc-3k/library/cookielib.rst (original) +++ doctools/trunk/Doc-3k/library/cookielib.rst Thu Aug 2 22:33:06 2007 @@ -3,6 +3,7 @@ ===================================================== .. module:: cookielib + :synopsis: Classes for automatic handling of HTTP cookies. .. moduleauthor:: John J. Lee .. sectionauthor:: John J. Lee Modified: doctools/trunk/Doc-3k/library/doctest.rst ============================================================================== --- doctools/trunk/Doc-3k/library/doctest.rst (original) +++ doctools/trunk/Doc-3k/library/doctest.rst Thu Aug 2 22:33:06 2007 @@ -1,16 +1,14 @@ - :mod:`doctest` --- Test interactive Python examples =================================================== .. module:: doctest + :synopsis: Test pieces of code within docstrings. .. moduleauthor:: Tim Peters .. sectionauthor:: Tim Peters .. sectionauthor:: Moshe Zadka .. sectionauthor:: Edward Loper - - The :mod:`doctest` module searches for pieces of text that look like interactive Python sessions, and then executes those sessions to verify that they work exactly as shown. There are several common ways to use doctest: Modified: doctools/trunk/Doc-3k/library/email.mime.rst ============================================================================== --- doctools/trunk/Doc-3k/library/email.mime.rst (original) +++ doctools/trunk/Doc-3k/library/email.mime.rst Thu Aug 2 22:33:06 2007 @@ -1,7 +1,8 @@ :mod:`email`: Creating email and MIME objects from scratch ---------------------------------------------------------- -.. module:: email.mime.text +.. module:: email.mime + :synopsis: Build MIME messages. Ordinarily, you get a message object structure by passing a file or some text to Modified: doctools/trunk/Doc-3k/library/fileinput.rst ============================================================================== --- doctools/trunk/Doc-3k/library/fileinput.rst (original) +++ doctools/trunk/Doc-3k/library/fileinput.rst Thu Aug 2 22:33:06 2007 @@ -1,14 +1,12 @@ - :mod:`fileinput` --- Iterate over lines from multiple input streams =================================================================== .. module:: fileinput + :synopsis: Loop over standard input or a list of files. .. moduleauthor:: Guido van Rossum .. sectionauthor:: Fred L. Drake, Jr. - - This module implements a helper class and functions to quickly write a loop over standard input or a list of files. Modified: doctools/trunk/Doc-3k/library/functools.rst ============================================================================== --- doctools/trunk/Doc-3k/library/functools.rst (original) +++ doctools/trunk/Doc-3k/library/functools.rst Thu Aug 2 22:33:06 2007 @@ -1,18 +1,14 @@ - -:mod:`functools` --- Higher order functions and operations on callable objects. -=============================================================================== +:mod:`functools` --- Higher order functions and operations on callable objects +============================================================================== .. module:: functools + :synopsis: Higher order functions and operations on callable objects. .. moduleauthor:: Peter Harris .. moduleauthor:: Raymond Hettinger .. moduleauthor:: Nick Coghlan .. sectionauthor:: Peter Harris -.. % standard library, in Python - - - .. versionadded:: 2.5 The :mod:`functools` module is for higher-order functions: functions that act on Modified: doctools/trunk/Doc-3k/library/logging.rst ============================================================================== --- doctools/trunk/Doc-3k/library/logging.rst (original) +++ doctools/trunk/Doc-3k/library/logging.rst Thu Aug 2 22:33:06 2007 @@ -1,8 +1,8 @@ - :mod:`logging` --- Logging facility for Python ============================================== .. module:: logging + :synopsis: Flexible error logging system for applications. .. moduleauthor:: Vinay Sajip Modified: doctools/trunk/Doc-3k/library/mailcap.rst ============================================================================== --- doctools/trunk/Doc-3k/library/mailcap.rst (original) +++ doctools/trunk/Doc-3k/library/mailcap.rst Thu Aug 2 22:33:06 2007 @@ -1,9 +1,8 @@ - -:mod:`mailcap` --- Mailcap file handling. -========================================= +:mod:`mailcap` --- Mailcap file handling +======================================== .. module:: mailcap - + :synopsis: Mailcap file handling. Modified: doctools/trunk/Doc-3k/library/operator.rst ============================================================================== --- doctools/trunk/Doc-3k/library/operator.rst (original) +++ doctools/trunk/Doc-3k/library/operator.rst Thu Aug 2 22:33:06 2007 @@ -1,13 +1,12 @@ - -:mod:`operator` --- Standard operators as functions. -==================================================== +:mod:`operator` --- Standard operators as functions +=================================================== .. module:: operator + :synopsis: Functions corresponding to the standard operators. .. sectionauthor:: Skip Montanaro - The :mod:`operator` module exports a set of functions implemented in C corresponding to the intrinsic operators of Python. For example, ``operator.add(x, y)`` is equivalent to the expression ``x+y``. The function Modified: doctools/trunk/Doc-3k/library/os.path.rst ============================================================================== --- doctools/trunk/Doc-3k/library/os.path.rst (original) +++ doctools/trunk/Doc-3k/library/os.path.rst Thu Aug 2 22:33:06 2007 @@ -3,8 +3,7 @@ ================================================ .. module:: os.path - - + :synopsis: Operations on pathnames. .. index:: single: path; operations Modified: doctools/trunk/Doc-3k/library/profile.rst ============================================================================== --- doctools/trunk/Doc-3k/library/profile.rst (original) +++ doctools/trunk/Doc-3k/library/profile.rst Thu Aug 2 22:33:06 2007 @@ -355,11 +355,9 @@ The :class:`Stats` class is defined in the :mod:`pstats` module. -.. module:: pstats - -.. % now switch modules.... -.. % (This \stmodindex use may be hard to change ;-( ) +.. module:: pstats + :synopsis: Statistics object for use with the profiler. .. class:: Stats(filename[, stream=sys.stdout[, ...]]) Modified: doctools/trunk/Doc-3k/library/py_compile.rst ============================================================================== --- doctools/trunk/Doc-3k/library/py_compile.rst (original) +++ doctools/trunk/Doc-3k/library/py_compile.rst Thu Aug 2 22:33:06 2007 @@ -1,9 +1,8 @@ - :mod:`py_compile` --- Compile Python source files ================================================= .. module:: py_compile - + :synopsis: Generate byte-code files from Python source files. .. % Documentation based on module docstrings, by Fred L. Drake, Jr. .. % Modified: doctools/trunk/Doc-3k/library/re.rst ============================================================================== --- doctools/trunk/Doc-3k/library/re.rst (original) +++ doctools/trunk/Doc-3k/library/re.rst Thu Aug 2 22:33:06 2007 @@ -3,6 +3,7 @@ =========================================== .. module:: re + :synopsis: Regular expression operations. .. moduleauthor:: Fredrik Lundh .. sectionauthor:: Andrew M. Kuchling Modified: doctools/trunk/Doc-3k/library/runpy.rst ============================================================================== --- doctools/trunk/Doc-3k/library/runpy.rst (original) +++ doctools/trunk/Doc-3k/library/runpy.rst Thu Aug 2 22:33:06 2007 @@ -1,15 +1,11 @@ - -:mod:`runpy` --- Locating and executing Python modules. -======================================================= +:mod:`runpy` --- Locating and executing Python modules +====================================================== .. module:: runpy + :synopsis: Locate and run Python modules without importing them first. .. moduleauthor:: Nick Coghlan -.. % standard library, in Python - - - .. versionadded:: 2.5 The :mod:`runpy` module is used to locate and run Python modules without Modified: doctools/trunk/Doc-3k/library/smtpd.rst ============================================================================== --- doctools/trunk/Doc-3k/library/smtpd.rst (original) +++ doctools/trunk/Doc-3k/library/smtpd.rst Thu Aug 2 22:33:06 2007 @@ -1,9 +1,8 @@ - :mod:`smtpd` --- SMTP Server ============================ .. module:: smtpd - + :synopsis: A SMTP server implementation in Python. .. moduleauthor:: Barry Warsaw .. sectionauthor:: Moshe Zadka Modified: doctools/trunk/Doc-3k/library/struct.rst ============================================================================== --- doctools/trunk/Doc-3k/library/struct.rst (original) +++ doctools/trunk/Doc-3k/library/struct.rst Thu Aug 2 22:33:06 2007 @@ -3,9 +3,7 @@ ========================================================= .. module:: struct - - - + :synopsis: Interpret strings as packed binary data. .. index:: pair: C; structures Modified: doctools/trunk/Doc-3k/library/urllib2.rst ============================================================================== --- doctools/trunk/Doc-3k/library/urllib2.rst (original) +++ doctools/trunk/Doc-3k/library/urllib2.rst Thu Aug 2 22:33:06 2007 @@ -1,14 +1,12 @@ - :mod:`urllib2` --- extensible library for opening URLs ====================================================== .. module:: urllib2 + :synopsis: Next generation URL opening library. .. moduleauthor:: Jeremy Hylton .. sectionauthor:: Moshe Zadka - - The :mod:`urllib2` module defines functions and classes which help in opening URLs (mostly HTTP) in a complex world --- basic and digest authentication, redirections, cookies and more. Modified: doctools/trunk/Doc-3k/library/urlparse.rst ============================================================================== --- doctools/trunk/Doc-3k/library/urlparse.rst (original) +++ doctools/trunk/Doc-3k/library/urlparse.rst Thu Aug 2 22:33:06 2007 @@ -1,10 +1,8 @@ - :mod:`urlparse` --- Parse URLs into components ============================================== .. module:: urlparse - - + :synopsis: Parse URLs into or assemble them from components. .. index:: Modified: doctools/trunk/Doc-3k/library/wsgiref.rst ============================================================================== --- doctools/trunk/Doc-3k/library/wsgiref.rst (original) +++ doctools/trunk/Doc-3k/library/wsgiref.rst Thu Aug 2 22:33:06 2007 @@ -1,9 +1,8 @@ - :mod:`wsgiref` --- WSGI Utilities and Reference Implementation ============================================================== .. module:: wsgiref - :synopsis: WSGI Utilities and Reference Implementation + :synopsis: WSGI Utilities and Reference Implementation. .. moduleauthor:: Phillip J. Eby .. sectionauthor:: Phillip J. Eby @@ -37,6 +36,7 @@ ------------------------------------------------- .. module:: wsgiref.util + :synopsis: WSGI environment utilities. This module provides a variety of utility functions for working with WSGI @@ -142,6 +142,7 @@ ---------------------------------------------------- .. module:: wsgiref.headers + :synopsis: WSGI response header tools. This module provides a single class, :class:`Headers`, for convenient @@ -221,6 +222,7 @@ --------------------------------------------------------- .. module:: wsgiref.simple_server + :synopsis: A simple WSGI HTTP server. This module implements a simple HTTP server (based on :mod:`BaseHTTPServer`) @@ -232,7 +234,7 @@ :mod:`wsgiref.util`.) -.. function:: make_server(host, port, app [, server_class=:class:`WSGIServer` [, handler_class=:class:`WSGIRequestHandler`]]) +.. function:: make_server(host, port, app [, server_class=WSGIServer [, handler_class=:class:`WSGIRequestHandler`]]) Create a new WSGI server listening on *host* and *port*, accepting connections for *app*. The return value is an instance of the supplied *server_class*, and @@ -327,10 +329,11 @@ interface. -:mod:`wsgiref.validate` -- WSGI conformance checker ---------------------------------------------------- +:mod:`wsgiref.validate` --- WSGI conformance checker +---------------------------------------------------- .. module:: wsgiref.validate + :synopsis: WSGI conformance checker. When creating new WSGI application objects, frameworks, servers, or middleware, @@ -375,6 +378,7 @@ ------------------------------------------------------ .. module:: wsgiref.handlers + :synopsis: WSGI server/gateway base classes. This module provides base handler classes for implementing WSGI servers and From python-checkins at python.org Thu Aug 2 23:28:59 2007 From: python-checkins at python.org (matthias.klose) Date: Thu, 2 Aug 2007 23:28:59 +0200 (CEST) Subject: [Python-checkins] r56679 - in python/branches/release25-maint: Doc/info/Makefile Misc/NEWS Message-ID: <20070802212859.36FBD1E400F@bag.python.org> Author: matthias.klose Date: Thu Aug 2 23:28:57 2007 New Revision: 56679 Modified: python/branches/release25-maint/Doc/info/Makefile python/branches/release25-maint/Misc/NEWS Log: - Allow Emacs 22 for building the documentation in info format. Modified: python/branches/release25-maint/Doc/info/Makefile ============================================================================== --- python/branches/release25-maint/Doc/info/Makefile (original) +++ python/branches/release25-maint/Doc/info/Makefile Thu Aug 2 23:28:57 2007 @@ -34,10 +34,10 @@ check-emacs-version: @v="`$(EMACS) --version 2>&1 | egrep '^(GNU |X)Emacs [12]*'`"; \ - if `echo "$$v" | grep '^GNU Emacs 21' >/dev/null 2>&1`; then \ + if `echo "$$v" | grep '^GNU Emacs 2[12]' >/dev/null 2>&1`; then \ echo "Using $(EMACS) to build the info docs"; \ else \ - echo "GNU Emacs 21 is required to build the info docs"; \ + echo "GNU Emacs 21 or 22 is required to build the info docs"; \ echo "Found $$v"; \ false; \ fi Modified: python/branches/release25-maint/Misc/NEWS ============================================================================== --- python/branches/release25-maint/Misc/NEWS (original) +++ python/branches/release25-maint/Misc/NEWS Thu Aug 2 23:28:57 2007 @@ -106,6 +106,8 @@ - Patch #1673122: Use an explicit path to libtool when building a framework. This avoids picking up GNU libtool from a users PATH. +- Allow Emacs 22 for building the documentation in info format. + What's New in Python 2.5.1? ============================= From python-checkins at python.org Thu Aug 2 23:31:41 2007 From: python-checkins at python.org (georg.brandl) Date: Thu, 2 Aug 2007 23:31:41 +0200 (CEST) Subject: [Python-checkins] r56680 - in doctools/trunk: Doc-26/ACKS Doc-26/TODO Doc-26/contents.rst Doc-26/howto Doc-26/howto/advocacy.rst Doc-26/howto/curses.rst Doc-26/howto/doanddont.rst Doc-26/howto/functional.rst Doc-26/howto/index.rst Doc-26/howto/regex.rst Doc-26/howto/sockets.rst Doc-26/howto/unicode.rst Doc-26/howto/urllib2.rst Doc-3k/ACKS Doc-3k/TODO Doc-3k/contents.rst Doc-3k/howto Doc-3k/howto/advocacy.rst Doc-3k/howto/curses.rst Doc-3k/howto/doanddont.rst Doc-3k/howto/functional.rst Doc-3k/howto/index.rst Doc-3k/howto/regex.rst Doc-3k/howto/sockets.rst Doc-3k/howto/unicode.rst Doc-3k/howto/urllib2.rst sphinx/templates/index.html Message-ID: <20070802213141.DC9D61E400A@bag.python.org> Author: georg.brandl Date: Thu Aug 2 23:31:34 2007 New Revision: 56680 Added: doctools/trunk/Doc-26/howto/ doctools/trunk/Doc-26/howto/advocacy.rst doctools/trunk/Doc-26/howto/curses.rst doctools/trunk/Doc-26/howto/doanddont.rst doctools/trunk/Doc-26/howto/functional.rst doctools/trunk/Doc-26/howto/index.rst doctools/trunk/Doc-26/howto/regex.rst doctools/trunk/Doc-26/howto/sockets.rst doctools/trunk/Doc-26/howto/unicode.rst doctools/trunk/Doc-26/howto/urllib2.rst doctools/trunk/Doc-3k/howto/ doctools/trunk/Doc-3k/howto/advocacy.rst doctools/trunk/Doc-3k/howto/curses.rst doctools/trunk/Doc-3k/howto/doanddont.rst doctools/trunk/Doc-3k/howto/functional.rst doctools/trunk/Doc-3k/howto/index.rst doctools/trunk/Doc-3k/howto/regex.rst doctools/trunk/Doc-3k/howto/sockets.rst doctools/trunk/Doc-3k/howto/unicode.rst doctools/trunk/Doc-3k/howto/urllib2.rst Modified: doctools/trunk/Doc-26/ACKS doctools/trunk/Doc-26/TODO doctools/trunk/Doc-26/contents.rst doctools/trunk/Doc-3k/ACKS doctools/trunk/Doc-3k/TODO doctools/trunk/Doc-3k/contents.rst doctools/trunk/sphinx/templates/index.html Log: Integrate the HOWTOs into the tree. Modified: doctools/trunk/Doc-26/ACKS ============================================================================== --- doctools/trunk/Doc-26/ACKS (original) +++ doctools/trunk/Doc-26/ACKS Thu Aug 2 23:31:34 2007 @@ -15,7 +15,7 @@ * Steve Alexander * Jim Ahlstrom * Fred Allen -* A. Amoroso +* \A. Amoroso * Pehr Anderson * Oliver Andrich * Jes?s Cea Avi?n @@ -40,7 +40,7 @@ * Jeremy Craven * Andrew Dalke * Ben Darnell -* L. Peter Deutsch +* \L. Peter Deutsch * Robert Donohue * Fred L. Drake, Jr. * Jeff Epler Modified: doctools/trunk/Doc-26/TODO ============================================================================== --- doctools/trunk/Doc-26/TODO (original) +++ doctools/trunk/Doc-26/TODO Thu Aug 2 23:31:34 2007 @@ -2,7 +2,6 @@ ====================== * split very large files and add toctrees -* integrate standalone HOWTOs * find out which files get "comments disabled" metadata * write "About these documents" * finish "Documenting Python" Modified: doctools/trunk/Doc-26/contents.rst ============================================================================== --- doctools/trunk/Doc-26/contents.rst (original) +++ doctools/trunk/Doc-26/contents.rst Thu Aug 2 23:31:34 2007 @@ -14,6 +14,7 @@ distutils/index.rst install/index.rst documenting/index.rst + howto/index.rst bugs.rst about.rst Added: doctools/trunk/Doc-26/howto/advocacy.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-26/howto/advocacy.rst Thu Aug 2 23:31:34 2007 @@ -0,0 +1,356 @@ +************************* + Python Advocacy HOWTO +************************* + +:Author: A.M. Kuchling +:Release: 0.03 + + +.. topic:: Abstract + + It's usually difficult to get your management to accept open source software, + and Python is no exception to this rule. This document discusses reasons to use + Python, strategies for winning acceptance, facts and arguments you can use, and + cases where you *shouldn't* try to use Python. + + +Reasons to Use Python +===================== + +There are several reasons to incorporate a scripting language into your +development process, and this section will discuss them, and why Python has some +properties that make it a particularly good choice. + + +Programmability +--------------- + +Programs are often organized in a modular fashion. Lower-level operations are +grouped together, and called by higher-level functions, which may in turn be +used as basic operations by still further upper levels. + +For example, the lowest level might define a very low-level set of functions for +accessing a hash table. The next level might use hash tables to store the +headers of a mail message, mapping a header name like ``Date`` to a value such +as ``Tue, 13 May 1997 20:00:54 -0400``. A yet higher level may operate on +message objects, without knowing or caring that message headers are stored in a +hash table, and so forth. + +Often, the lowest levels do very simple things; they implement a data structure +such as a binary tree or hash table, or they perform some simple computation, +such as converting a date string to a number. The higher levels then contain +logic connecting these primitive operations. Using the approach, the primitives +can be seen as basic building blocks which are then glued together to produce +the complete product. + +Why is this design approach relevant to Python? Because Python is well suited +to functioning as such a glue language. A common approach is to write a Python +module that implements the lower level operations; for the sake of speed, the +implementation might be in C, Java, or even Fortran. Once the primitives are +available to Python programs, the logic underlying higher level operations is +written in the form of Python code. The high-level logic is then more +understandable, and easier to modify. + +John Ousterhout wrote a paper that explains this idea at greater length, +entitled "Scripting: Higher Level Programming for the 21st Century". I +recommend that you read this paper; see the references for the URL. Ousterhout +is the inventor of the Tcl language, and therefore argues that Tcl should be +used for this purpose; he only briefly refers to other languages such as Python, +Perl, and Lisp/Scheme, but in reality, Ousterhout's argument applies to +scripting languages in general, since you could equally write extensions for any +of the languages mentioned above. + + +Prototyping +----------- + +In *The Mythical Man-Month*, Fredrick Brooks suggests the following rule when +planning software projects: "Plan to throw one away; you will anyway." Brooks +is saying that the first attempt at a software design often turns out to be +wrong; unless the problem is very simple or you're an extremely good designer, +you'll find that new requirements and features become apparent once development +has actually started. If these new requirements can't be cleanly incorporated +into the program's structure, you're presented with two unpleasant choices: +hammer the new features into the program somehow, or scrap everything and write +a new version of the program, taking the new features into account from the +beginning. + +Python provides you with a good environment for quickly developing an initial +prototype. That lets you get the overall program structure and logic right, and +you can fine-tune small details in the fast development cycle that Python +provides. Once you're satisfied with the GUI interface or program output, you +can translate the Python code into C++, Fortran, Java, or some other compiled +language. + +Prototyping means you have to be careful not to use too many Python features +that are hard to implement in your other language. Using ``eval()``, or regular +expressions, or the :mod:`pickle` module, means that you're going to need C or +Java libraries for formula evaluation, regular expressions, and serialization, +for example. But it's not hard to avoid such tricky code, and in the end the +translation usually isn't very difficult. The resulting code can be rapidly +debugged, because any serious logical errors will have been removed from the +prototype, leaving only more minor slip-ups in the translation to track down. + +This strategy builds on the earlier discussion of programmability. Using Python +as glue to connect lower-level components has obvious relevance for constructing +prototype systems. In this way Python can help you with development, even if +end users never come in contact with Python code at all. If the performance of +the Python version is adequate and corporate politics allow it, you may not need +to do a translation into C or Java, but it can still be faster to develop a +prototype and then translate it, instead of attempting to produce the final +version immediately. + +One example of this development strategy is Microsoft Merchant Server. Version +1.0 was written in pure Python, by a company that subsequently was purchased by +Microsoft. Version 2.0 began to translate the code into C++, shipping with some +C++code and some Python code. Version 3.0 didn't contain any Python at all; all +the code had been translated into C++. Even though the product doesn't contain +a Python interpreter, the Python language has still served a useful purpose by +speeding up development. + +This is a very common use for Python. Past conference papers have also +described this approach for developing high-level numerical algorithms; see +David M. Beazley and Peter S. Lomdahl's paper "Feeding a Large-scale Physics +Application to Python" in the references for a good example. If an algorithm's +basic operations are things like "Take the inverse of this 4000x4000 matrix", +and are implemented in some lower-level language, then Python has almost no +additional performance cost; the extra time required for Python to evaluate an +expression like ``m.invert()`` is dwarfed by the cost of the actual computation. +It's particularly good for applications where seemingly endless tweaking is +required to get things right. GUI interfaces and Web sites are prime examples. + +The Python code is also shorter and faster to write (once you're familiar with +Python), so it's easier to throw it away if you decide your approach was wrong; +if you'd spent two weeks working on it instead of just two hours, you might +waste time trying to patch up what you've got out of a natural reluctance to +admit that those two weeks were wasted. Truthfully, those two weeks haven't +been wasted, since you've learnt something about the problem and the technology +you're using to solve it, but it's human nature to view this as a failure of +some sort. + + +Simplicity and Ease of Understanding +------------------------------------ + +Python is definitely *not* a toy language that's only usable for small tasks. +The language features are general and powerful enough to enable it to be used +for many different purposes. It's useful at the small end, for 10- or 20-line +scripts, but it also scales up to larger systems that contain thousands of lines +of code. + +However, this expressiveness doesn't come at the cost of an obscure or tricky +syntax. While Python has some dark corners that can lead to obscure code, there +are relatively few such corners, and proper design can isolate their use to only +a few classes or modules. It's certainly possible to write confusing code by +using too many features with too little concern for clarity, but most Python +code can look a lot like a slightly-formalized version of human-understandable +pseudocode. + +In *The New Hacker's Dictionary*, Eric S. Raymond gives the following definition +for "compact": + +.. epigraph:: + + Compact *adj.* Of a design, describes the valuable property that it can all be + apprehended at once in one's head. This generally means the thing created from + the design can be used with greater facility and fewer errors than an equivalent + tool that is not compact. Compactness does not imply triviality or lack of + power; for example, C is compact and FORTRAN is not, but C is more powerful than + FORTRAN. Designs become non-compact through accreting features and cruft that + don't merge cleanly into the overall design scheme (thus, some fans of Classic C + maintain that ANSI C is no longer compact). + + (From http://www.catb.org/ esr/jargon/html/C/compact.html) + +In this sense of the word, Python is quite compact, because the language has +just a few ideas, which are used in lots of places. Take namespaces, for +example. Import a module with ``import math``, and you create a new namespace +called ``math``. Classes are also namespaces that share many of the properties +of modules, and have a few of their own; for example, you can create instances +of a class. Instances? They're yet another namespace. Namespaces are currently +implemented as Python dictionaries, so they have the same methods as the +standard dictionary data type: .keys() returns all the keys, and so forth. + +This simplicity arises from Python's development history. The language syntax +derives from different sources; ABC, a relatively obscure teaching language, is +one primary influence, and Modula-3 is another. (For more information about ABC +and Modula-3, consult their respective Web sites at http://www.cwi.nl/ +steven/abc/ and http://www.m3.org.) Other features have come from C, Icon, +Algol-68, and even Perl. Python hasn't really innovated very much, but instead +has tried to keep the language small and easy to learn, building on ideas that +have been tried in other languages and found useful. + +Simplicity is a virtue that should not be underestimated. It lets you learn the +language more quickly, and then rapidly write code, code that often works the +first time you run it. + + +Java Integration +---------------- + +If you're working with Java, Jython (http://www.jython.org/) is definitely worth +your attention. Jython is a re-implementation of Python in Java that compiles +Python code into Java bytecodes. The resulting environment has very tight, +almost seamless, integration with Java. It's trivial to access Java classes +from Python, and you can write Python classes that subclass Java classes. +Jython can be used for prototyping Java applications in much the same way +CPython is used, and it can also be used for test suites for Java code, or +embedded in a Java application to add scripting capabilities. + + +Arguments and Rebuttals +======================= + +Let's say that you've decided upon Python as the best choice for your +application. How can you convince your management, or your fellow developers, +to use Python? This section lists some common arguments against using Python, +and provides some possible rebuttals. + +**Python is freely available software that doesn't cost anything. How good can +it be?** + +Very good, indeed. These days Linux and Apache, two other pieces of open source +software, are becoming more respected as alternatives to commercial software, +but Python hasn't had all the publicity. + +Python has been around for several years, with many users and developers. +Accordingly, the interpreter has been used by many people, and has gotten most +of the bugs shaken out of it. While bugs are still discovered at intervals, +they're usually either quite obscure (they'd have to be, for no one to have run +into them before) or they involve interfaces to external libraries. The +internals of the language itself are quite stable. + +Having the source code should be viewed as making the software available for +peer review; people can examine the code, suggest (and implement) improvements, +and track down bugs. To find out more about the idea of open source code, along +with arguments and case studies supporting it, go to http://www.opensource.org. + +**Who's going to support it?** + +Python has a sizable community of developers, and the number is still growing. +The Internet community surrounding the language is an active one, and is worth +being considered another one of Python's advantages. Most questions posted to +the comp.lang.python newsgroup are quickly answered by someone. + +Should you need to dig into the source code, you'll find it's clear and well- +organized, so it's not very difficult to write extensions and track down bugs +yourself. If you'd prefer to pay for support, there are companies and +individuals who offer commercial support for Python. + +**Who uses Python for serious work?** + +Lots of people; one interesting thing about Python is the surprising diversity +of applications that it's been used for. People are using Python to: + +* Run Web sites + +* Write GUI interfaces + +* Control number-crunching code on supercomputers + +* Make a commercial application scriptable by embedding the Python interpreter + inside it + +* Process large XML data sets + +* Build test suites for C or Java code + +Whatever your application domain is, there's probably someone who's used Python +for something similar. Yet, despite being useable for such high-end +applications, Python's still simple enough to use for little jobs. + +See http://wiki.python.org/moin/OrganizationsUsingPython for a list of some of +the organizations that use Python. + +**What are the restrictions on Python's use?** + +They're practically nonexistent. Consult the :file:`Misc/COPYRIGHT` file in the +source distribution, or http://www.python.org/doc/Copyright.html for the full +language, but it boils down to three conditions. + +* You have to leave the copyright notice on the software; if you don't include + the source code in a product, you have to put the copyright notice in the + supporting documentation. + +* Don't claim that the institutions that have developed Python endorse your + product in any way. + +* If something goes wrong, you can't sue for damages. Practically all software + licences contain this condition. + +Notice that you don't have to provide source code for anything that contains +Python or is built with it. Also, the Python interpreter and accompanying +documentation can be modified and redistributed in any way you like, and you +don't have to pay anyone any licensing fees at all. + +**Why should we use an obscure language like Python instead of well-known +language X?** + +I hope this HOWTO, and the documents listed in the final section, will help +convince you that Python isn't obscure, and has a healthily growing user base. +One word of advice: always present Python's positive advantages, instead of +concentrating on language X's failings. People want to know why a solution is +good, rather than why all the other solutions are bad. So instead of attacking +a competing solution on various grounds, simply show how Python's virtues can +help. + + +Useful Resources +================ + +http://www.pythonology.com/success + The Python Success Stories are a collection of stories from successful users of + Python, with the emphasis on business and corporate users. + +.. % \term{\url{http://www.fsbassociates.com/books/pythonchpt1.htm}} +.. % The first chapter of \emph{Internet Programming with Python} also +.. % examines some of the reasons for using Python. The book is well worth +.. % buying, but the publishers have made the first chapter available on +.. % the Web. + +http://home.pacbell.net/ouster/scripting.html + John Ousterhout's white paper on scripting is a good argument for the utility of + scripting languages, though naturally enough, he emphasizes Tcl, the language he + developed. Most of the arguments would apply to any scripting language. + +http://www.python.org/workshops/1997-10/proceedings/beazley.html + The authors, David M. Beazley and Peter S. Lomdahl, describe their use of + Python at Los Alamos National Laboratory. It's another good example of how + Python can help get real work done. This quotation from the paper has been + echoed by many people: + + .. epigraph:: + + Originally developed as a large monolithic application for massively parallel + processing systems, we have used Python to transform our application into a + flexible, highly modular, and extremely powerful system for performing + simulation, data analysis, and visualization. In addition, we describe how + Python has solved a number of important problems related to the development, + debugging, deployment, and maintenance of scientific software. + +http://pythonjournal.cognizor.com/pyj1/Everitt-Feit_interview98-V1.html + This interview with Andy Feit, discussing Infoseek's use of Python, can be used + to show that choosing Python didn't introduce any difficulties into a company's + development process, and provided some substantial benefits. + +.. % \term{\url{http://www.python.org/psa/Commercial.html}} +.. % Robin Friedrich wrote this document on how to support Python's use in +.. % commercial projects. + +http://www.python.org/workshops/1997-10/proceedings/stein.ps + For the 6th Python conference, Greg Stein presented a paper that traced Python's + adoption and usage at a startup called eShop, and later at Microsoft. + +http://www.opensource.org + Management may be doubtful of the reliability and usefulness of software that + wasn't written commercially. This site presents arguments that show how open + source software can have considerable advantages over closed-source software. + +http://sunsite.unc.edu/LDP/HOWTO/mini/Advocacy.html + The Linux Advocacy mini-HOWTO was the inspiration for this document, and is also + well worth reading for general suggestions on winning acceptance for a new + technology, such as Linux or Python. In general, you won't make much progress + by simply attacking existing systems and complaining about their inadequacies; + this often ends up looking like unfocused whining. It's much better to point + out some of the many areas where Python is an improvement over other systems. + Added: doctools/trunk/Doc-26/howto/curses.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-26/howto/curses.rst Thu Aug 2 23:31:34 2007 @@ -0,0 +1,433 @@ +********************************** + Curses Programming with Python +********************************** + +:Author: A.M. Kuchling, Eric S. Raymond +:Release: 2.02 + + +.. topic:: Abstract + + This document describes how to write text-mode programs with Python 2.x, using + the :mod:`curses` extension module to control the display. + + +What is curses? +=============== + +The curses library supplies a terminal-independent screen-painting and keyboard- +handling facility for text-based terminals; such terminals include VT100s, the +Linux console, and the simulated terminal provided by X11 programs such as xterm +and rxvt. Display terminals support various control codes to perform common +operations such as moving the cursor, scrolling the screen, and erasing areas. +Different terminals use widely differing codes, and often have their own minor +quirks. + +In a world of X displays, one might ask "why bother"? It's true that character- +cell display terminals are an obsolete technology, but there are niches in which +being able to do fancy things with them are still valuable. One is on small- +footprint or embedded Unixes that don't carry an X server. Another is for +tools like OS installers and kernel configurators that may have to run before X +is available. + +The curses library hides all the details of different terminals, and provides +the programmer with an abstraction of a display, containing multiple non- +overlapping windows. The contents of a window can be changed in various ways-- +adding text, erasing it, changing its appearance--and the curses library will +automagically figure out what control codes need to be sent to the terminal to +produce the right output. + +The curses library was originally written for BSD Unix; the later System V +versions of Unix from AT&T added many enhancements and new functions. BSD curses +is no longer maintained, having been replaced by ncurses, which is an open- +source implementation of the AT&T interface. If you're using an open-source +Unix such as Linux or FreeBSD, your system almost certainly uses ncurses. Since +most current commercial Unix versions are based on System V code, all the +functions described here will probably be available. The older versions of +curses carried by some proprietary Unixes may not support everything, though. + +No one has made a Windows port of the curses module. On a Windows platform, try +the Console module written by Fredrik Lundh. The Console module provides +cursor-addressable text output, plus full support for mouse and keyboard input, +and is available from http://effbot.org/efflib/console. + + +The Python curses module +------------------------ + +Thy Python module is a fairly simple wrapper over the C functions provided by +curses; if you're already familiar with curses programming in C, it's really +easy to transfer that knowledge to Python. The biggest difference is that the +Python interface makes things simpler, by merging different C functions such as +:func:`addstr`, :func:`mvaddstr`, :func:`mvwaddstr`, into a single +:meth:`addstr` method. You'll see this covered in more detail later. + +This HOWTO is simply an introduction to writing text-mode programs with curses +and Python. It doesn't attempt to be a complete guide to the curses API; for +that, see the Python library guide's section on ncurses, and the C manual pages +for ncurses. It will, however, give you the basic ideas. + + +Starting and ending a curses application +======================================== + +Before doing anything, curses must be initialized. This is done by calling the +:func:`initscr` function, which will determine the terminal type, send any +required setup codes to the terminal, and create various internal data +structures. If successful, :func:`initscr` returns a window object representing +the entire screen; this is usually called ``stdscr``, after the name of the +corresponding C variable. :: + + import curses + stdscr = curses.initscr() + +Usually curses applications turn off automatic echoing of keys to the screen, in +order to be able to read keys and only display them under certain circumstances. +This requires calling the :func:`noecho` function. :: + + curses.noecho() + +Applications will also commonly need to react to keys instantly, without +requiring the Enter key to be pressed; this is called cbreak mode, as opposed to +the usual buffered input mode. :: + + curses.cbreak() + +Terminals usually return special keys, such as the cursor keys or navigation +keys such as Page Up and Home, as a multibyte escape sequence. While you could +write your application to expect such sequences and process them accordingly, +curses can do it for you, returning a special value such as +:const:`curses.KEY_LEFT`. To get curses to do the job, you'll have to enable +keypad mode. :: + + stdscr.keypad(1) + +Terminating a curses application is much easier than starting one. You'll need +to call :: + + curses.nocbreak(); stdscr.keypad(0); curses.echo() + +to reverse the curses-friendly terminal settings. Then call the :func:`endwin` +function to restore the terminal to its original operating mode. :: + + curses.endwin() + +A common problem when debugging a curses application is to get your terminal +messed up when the application dies without restoring the terminal to its +previous state. In Python this commonly happens when your code is buggy and +raises an uncaught exception. Keys are no longer be echoed to the screen when +you type them, for example, which makes using the shell difficult. + +In Python you can avoid these complications and make debugging much easier by +importing the module :mod:`curses.wrapper`. It supplies a :func:`wrapper` +function that takes a callable. It does the initializations described above, +and also initializes colors if color support is present. It then runs your +provided callable and finally deinitializes appropriately. The callable is +called inside a try-catch clause which catches exceptions, performs curses +deinitialization, and then passes the exception upwards. Thus, your terminal +won't be left in a funny state on exception. + + +Windows and Pads +================ + +Windows are the basic abstraction in curses. A window object represents a +rectangular area of the screen, and supports various methods to display text, +erase it, allow the user to input strings, and so forth. + +The ``stdscr`` object returned by the :func:`initscr` function is a window +object that covers the entire screen. Many programs may need only this single +window, but you might wish to divide the screen into smaller windows, in order +to redraw or clear them separately. The :func:`newwin` function creates a new +window of a given size, returning the new window object. :: + + begin_x = 20 ; begin_y = 7 + height = 5 ; width = 40 + win = curses.newwin(height, width, begin_y, begin_x) + +A word about the coordinate system used in curses: coordinates are always passed +in the order *y,x*, and the top-left corner of a window is coordinate (0,0). +This breaks a common convention for handling coordinates, where the *x* +coordinate usually comes first. This is an unfortunate difference from most +other computer applications, but it's been part of curses since it was first +written, and it's too late to change things now. + +When you call a method to display or erase text, the effect doesn't immediately +show up on the display. This is because curses was originally written with slow +300-baud terminal connections in mind; with these terminals, minimizing the time +required to redraw the screen is very important. This lets curses accumulate +changes to the screen, and display them in the most efficient manner. For +example, if your program displays some characters in a window, and then clears +the window, there's no need to send the original characters because they'd never +be visible. + +Accordingly, curses requires that you explicitly tell it to redraw windows, +using the :func:`refresh` method of window objects. In practice, this doesn't +really complicate programming with curses much. Most programs go into a flurry +of activity, and then pause waiting for a keypress or some other action on the +part of the user. All you have to do is to be sure that the screen has been +redrawn before pausing to wait for user input, by simply calling +``stdscr.refresh()`` or the :func:`refresh` method of some other relevant +window. + +A pad is a special case of a window; it can be larger than the actual display +screen, and only a portion of it displayed at a time. Creating a pad simply +requires the pad's height and width, while refreshing a pad requires giving the +coordinates of the on-screen area where a subsection of the pad will be +displayed. :: + + pad = curses.newpad(100, 100) + # These loops fill the pad with letters; this is + # explained in the next section + for y in range(0, 100): + for x in range(0, 100): + try: pad.addch(y,x, ord('a') + (x*x+y*y) % 26 ) + except curses.error: pass + + # Displays a section of the pad in the middle of the screen + pad.refresh( 0,0, 5,5, 20,75) + +The :func:`refresh` call displays a section of the pad in the rectangle +extending from coordinate (5,5) to coordinate (20,75) on the screen; the upper +left corner of the displayed section is coordinate (0,0) on the pad. Beyond +that difference, pads are exactly like ordinary windows and support the same +methods. + +If you have multiple windows and pads on screen there is a more efficient way to +go, which will prevent annoying screen flicker at refresh time. Use the +:meth:`noutrefresh` method of each window to update the data structure +representing the desired state of the screen; then change the physical screen to +match the desired state in one go with the function :func:`doupdate`. The +normal :meth:`refresh` method calls :func:`doupdate` as its last act. + + +Displaying Text +=============== + +From a C programmer's point of view, curses may sometimes look like a twisty +maze of functions, all subtly different. For example, :func:`addstr` displays a +string at the current cursor location in the ``stdscr`` window, while +:func:`mvaddstr` moves to a given y,x coordinate first before displaying the +string. :func:`waddstr` is just like :func:`addstr`, but allows specifying a +window to use, instead of using ``stdscr`` by default. :func:`mvwaddstr` follows +similarly. + +Fortunately the Python interface hides all these details; ``stdscr`` is a window +object like any other, and methods like :func:`addstr` accept multiple argument +forms. Usually there are four different forms. + ++---------------------------------+-----------------------------------------------+ +| Form | Description | ++=================================+===============================================+ +| *str* or *ch* | Display the string *str* or character *ch* at | +| | the current position | ++---------------------------------+-----------------------------------------------+ +| *str* or *ch*, *attr* | Display the string *str* or character *ch*, | +| | using attribute *attr* at the current | +| | position | ++---------------------------------+-----------------------------------------------+ +| *y*, *x*, *str* or *ch* | Move to position *y,x* within the window, and | +| | display *str* or *ch* | ++---------------------------------+-----------------------------------------------+ +| *y*, *x*, *str* or *ch*, *attr* | Move to position *y,x* within the window, and | +| | display *str* or *ch*, using attribute *attr* | ++---------------------------------+-----------------------------------------------+ + +Attributes allow displaying text in highlighted forms, such as in boldface, +underline, reverse code, or in color. They'll be explained in more detail in +the next subsection. + +The :func:`addstr` function takes a Python string as the value to be displayed, +while the :func:`addch` functions take a character, which can be either a Python +string of length 1 or an integer. If it's a string, you're limited to +displaying characters between 0 and 255. SVr4 curses provides constants for +extension characters; these constants are integers greater than 255. For +example, :const:`ACS_PLMINUS` is a +/- symbol, and :const:`ACS_ULCORNER` is the +upper left corner of a box (handy for drawing borders). + +Windows remember where the cursor was left after the last operation, so if you +leave out the *y,x* coordinates, the string or character will be displayed +wherever the last operation left off. You can also move the cursor with the +:func:`move(y,x)` method. Because some terminals always display a flashing +cursor, you may want to ensure that the cursor is positioned in some location +where it won't be distracting; it can be confusing to have the cursor blinking +at some apparently random location. + +If your application doesn't need a blinking cursor at all, you can call +:func:`curs_set(0)` to make it invisible. Equivalently, and for compatibility +with older curses versions, there's a :func:`leaveok(bool)` function. When +*bool* is true, the curses library will attempt to suppress the flashing cursor, +and you won't need to worry about leaving it in odd locations. + + +Attributes and Color +-------------------- + +Characters can be displayed in different ways. Status lines in a text-based +application are commonly shown in reverse video; a text viewer may need to +highlight certain words. curses supports this by allowing you to specify an +attribute for each cell on the screen. + +An attribute is a integer, each bit representing a different attribute. You can +try to display text with multiple attribute bits set, but curses doesn't +guarantee that all the possible combinations are available, or that they're all +visually distinct. That depends on the ability of the terminal being used, so +it's safest to stick to the most commonly available attributes, listed here. + ++----------------------+--------------------------------------+ +| Attribute | Description | ++======================+======================================+ +| :const:`A_BLINK` | Blinking text | ++----------------------+--------------------------------------+ +| :const:`A_BOLD` | Extra bright or bold text | ++----------------------+--------------------------------------+ +| :const:`A_DIM` | Half bright text | ++----------------------+--------------------------------------+ +| :const:`A_REVERSE` | Reverse-video text | ++----------------------+--------------------------------------+ +| :const:`A_STANDOUT` | The best highlighting mode available | ++----------------------+--------------------------------------+ +| :const:`A_UNDERLINE` | Underlined text | ++----------------------+--------------------------------------+ + +So, to display a reverse-video status line on the top line of the screen, you +could code:: + + stdscr.addstr(0, 0, "Current mode: Typing mode", + curses.A_REVERSE) + stdscr.refresh() + +The curses library also supports color on those terminals that provide it, The +most common such terminal is probably the Linux console, followed by color +xterms. + +To use color, you must call the :func:`start_color` function soon after calling +:func:`initscr`, to initialize the default color set (the +:func:`curses.wrapper.wrapper` function does this automatically). Once that's +done, the :func:`has_colors` function returns TRUE if the terminal in use can +actually display color. (Note: curses uses the American spelling 'color', +instead of the Canadian/British spelling 'colour'. If you're used to the +British spelling, you'll have to resign yourself to misspelling it for the sake +of these functions.) + +The curses library maintains a finite number of color pairs, containing a +foreground (or text) color and a background color. You can get the attribute +value corresponding to a color pair with the :func:`color_pair` function; this +can be bitwise-OR'ed with other attributes such as :const:`A_REVERSE`, but +again, such combinations are not guaranteed to work on all terminals. + +An example, which displays a line of text using color pair 1:: + + stdscr.addstr( "Pretty text", curses.color_pair(1) ) + stdscr.refresh() + +As I said before, a color pair consists of a foreground and background color. +:func:`start_color` initializes 8 basic colors when it activates color mode. +They are: 0:black, 1:red, 2:green, 3:yellow, 4:blue, 5:magenta, 6:cyan, and +7:white. The curses module defines named constants for each of these colors: +:const:`curses.COLOR_BLACK`, :const:`curses.COLOR_RED`, and so forth. + +The :func:`init_pair(n, f, b)` function changes the definition of color pair +*n*, to foreground color f and background color b. Color pair 0 is hard-wired +to white on black, and cannot be changed. + +Let's put all this together. To change color 1 to red text on a white +background, you would call:: + + curses.init_pair(1, curses.COLOR_RED, curses.COLOR_WHITE) + +When you change a color pair, any text already displayed using that color pair +will change to the new colors. You can also display new text in this color +with:: + + stdscr.addstr(0,0, "RED ALERT!", curses.color_pair(1) ) + +Very fancy terminals can change the definitions of the actual colors to a given +RGB value. This lets you change color 1, which is usually red, to purple or +blue or any other color you like. Unfortunately, the Linux console doesn't +support this, so I'm unable to try it out, and can't provide any examples. You +can check if your terminal can do this by calling :func:`can_change_color`, +which returns TRUE if the capability is there. If you're lucky enough to have +such a talented terminal, consult your system's man pages for more information. + + +User Input +========== + +The curses library itself offers only very simple input mechanisms. Python's +support adds a text-input widget that makes up some of the lack. + +The most common way to get input to a window is to use its :meth:`getch` method. +:meth:`getch` pauses and waits for the user to hit a key, displaying it if +:func:`echo` has been called earlier. You can optionally specify a coordinate +to which the cursor should be moved before pausing. + +It's possible to change this behavior with the method :meth:`nodelay`. After +:meth:`nodelay(1)`, :meth:`getch` for the window becomes non-blocking and +returns ``curses.ERR`` (a value of -1) when no input is ready. There's also a +:func:`halfdelay` function, which can be used to (in effect) set a timer on each +:meth:`getch`; if no input becomes available within the number of milliseconds +specified as the argument to :func:`halfdelay`, curses raises an exception. + +The :meth:`getch` method returns an integer; if it's between 0 and 255, it +represents the ASCII code of the key pressed. Values greater than 255 are +special keys such as Page Up, Home, or the cursor keys. You can compare the +value returned to constants such as :const:`curses.KEY_PPAGE`, +:const:`curses.KEY_HOME`, or :const:`curses.KEY_LEFT`. Usually the main loop of +your program will look something like this:: + + while 1: + c = stdscr.getch() + if c == ord('p'): PrintDocument() + elif c == ord('q'): break # Exit the while() + elif c == curses.KEY_HOME: x = y = 0 + +The :mod:`curses.ascii` module supplies ASCII class membership functions that +take either integer or 1-character-string arguments; these may be useful in +writing more readable tests for your command interpreters. It also supplies +conversion functions that take either integer or 1-character-string arguments +and return the same type. For example, :func:`curses.ascii.ctrl` returns the +control character corresponding to its argument. + +There's also a method to retrieve an entire string, :const:`getstr()`. It isn't +used very often, because its functionality is quite limited; the only editing +keys available are the backspace key and the Enter key, which terminates the +string. It can optionally be limited to a fixed number of characters. :: + + curses.echo() # Enable echoing of characters + + # Get a 15-character string, with the cursor on the top line + s = stdscr.getstr(0,0, 15) + +The Python :mod:`curses.textpad` module supplies something better. With it, you +can turn a window into a text box that supports an Emacs-like set of +keybindings. Various methods of :class:`Textbox` class support editing with +input validation and gathering the edit results either with or without trailing +spaces. See the library documentation on :mod:`curses.textpad` for the +details. + + +For More Information +==================== + +This HOWTO didn't cover some advanced topics, such as screen-scraping or +capturing mouse events from an xterm instance. But the Python library page for +the curses modules is now pretty complete. You should browse it next. + +If you're in doubt about the detailed behavior of any of the ncurses entry +points, consult the manual pages for your curses implementation, whether it's +ncurses or a proprietary Unix vendor's. The manual pages will document any +quirks, and provide complete lists of all the functions, attributes, and +:const:`ACS_\*` characters available to you. + +Because the curses API is so large, some functions aren't supported in the +Python interface, not because they're difficult to implement, but because no one +has needed them yet. Feel free to add them and then submit a patch. Also, we +don't yet have support for the menus or panels libraries associated with +ncurses; feel free to add that. + +If you write an interesting little program, feel free to contribute it as +another demo. We can always use more of them! + +The ncurses FAQ: http://dickey.his.com/ncurses/ncurses.faq.html + Added: doctools/trunk/Doc-26/howto/doanddont.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-26/howto/doanddont.rst Thu Aug 2 23:31:34 2007 @@ -0,0 +1,308 @@ +************************************ + Idioms and Anti-Idioms in Python +************************************ + +:Author: Moshe Zadka + +This document is placed in the public doman. + + +.. topic:: Abstract + + This document can be considered a companion to the tutorial. It shows how to use + Python, and even more importantly, how *not* to use Python. + + +Language Constructs You Should Not Use +====================================== + +While Python has relatively few gotchas compared to other languages, it still +has some constructs which are only useful in corner cases, or are plain +dangerous. + + +from module import \* +--------------------- + + +Inside Function Definitions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``from module import *`` is *invalid* inside function definitions. While many +versions of Python do not check for the invalidity, it does not make it more +valid, no more then having a smart lawyer makes a man innocent. Do not use it +like that ever. Even in versions where it was accepted, it made the function +execution slower, because the compiler could not be certain which names are +local and which are global. In Python 2.1 this construct causes warnings, and +sometimes even errors. + + +At Module Level +^^^^^^^^^^^^^^^ + +While it is valid to use ``from module import *`` at module level it is usually +a bad idea. For one, this loses an important property Python otherwise has --- +you can know where each toplevel name is defined by a simple "search" function +in your favourite editor. You also open yourself to trouble in the future, if +some module grows additional functions or classes. + +One of the most awful question asked on the newsgroup is why this code:: + + f = open("www") + f.read() + +does not work. Of course, it works just fine (assuming you have a file called +"www".) But it does not work if somewhere in the module, the statement ``from os +import *`` is present. The :mod:`os` module has a function called :func:`open` +which returns an integer. While it is very useful, shadowing builtins is one of +its least useful properties. + +Remember, you can never know for sure what names a module exports, so either +take what you need --- ``from module import name1, name2``, or keep them in the +module and access on a per-need basis --- ``import module;print module.name``. + + +When It Is Just Fine +^^^^^^^^^^^^^^^^^^^^ + +There are situations in which ``from module import *`` is just fine: + +* The interactive prompt. For example, ``from math import *`` makes Python an + amazing scientific calculator. + +* When extending a module in C with a module in Python. + +* When the module advertises itself as ``from import *`` safe. + + +Unadorned :keyword:`exec`, :func:`execfile` and friends +------------------------------------------------------- + +The word "unadorned" refers to the use without an explicit dictionary, in which +case those constructs evaluate code in the *current* environment. This is +dangerous for the same reasons ``from import *`` is dangerous --- it might step +over variables you are counting on and mess up things for the rest of your code. +Simply do not do that. + +Bad examples:: + + >>> for name in sys.argv[1:]: + >>> exec "%s=1" % name + >>> def func(s, **kw): + >>> for var, val in kw.items(): + >>> exec "s.%s=val" % var # invalid! + >>> execfile("handler.py") + >>> handle() + +Good examples:: + + >>> d = {} + >>> for name in sys.argv[1:]: + >>> d[name] = 1 + >>> def func(s, **kw): + >>> for var, val in kw.items(): + >>> setattr(s, var, val) + >>> d={} + >>> execfile("handle.py", d, d) + >>> handle = d['handle'] + >>> handle() + + +from module import name1, name2 +------------------------------- + +This is a "don't" which is much weaker then the previous "don't"s but is still +something you should not do if you don't have good reasons to do that. The +reason it is usually bad idea is because you suddenly have an object which lives +in two seperate namespaces. When the binding in one namespace changes, the +binding in the other will not, so there will be a discrepancy between them. This +happens when, for example, one module is reloaded, or changes the definition of +a function at runtime. + +Bad example:: + + # foo.py + a = 1 + + # bar.py + from foo import a + if something(): + a = 2 # danger: foo.a != a + +Good example:: + + # foo.py + a = 1 + + # bar.py + import foo + if something(): + foo.a = 2 + + +except: +------- + +Python has the ``except:`` clause, which catches all exceptions. Since *every* +error in Python raises an exception, this makes many programming errors look +like runtime problems, and hinders the debugging process. + +The following code shows a great example:: + + try: + foo = opne("file") # misspelled "open" + except: + sys.exit("could not open file!") + +The second line triggers a :exc:`NameError` which is caught by the except +clause. The program will exit, and you will have no idea that this has nothing +to do with the readability of ``"file"``. + +The example above is better written :: + + try: + foo = opne("file") # will be changed to "open" as soon as we run it + except IOError: + sys.exit("could not open file") + +There are some situations in which the ``except:`` clause is useful: for +example, in a framework when running callbacks, it is good not to let any +callback disturb the framework. + + +Exceptions +========== + +Exceptions are a useful feature of Python. You should learn to raise them +whenever something unexpected occurs, and catch them only where you can do +something about them. + +The following is a very popular anti-idiom :: + + def get_status(file): + if not os.path.exists(file): + print "file not found" + sys.exit(1) + return open(file).readline() + +Consider the case the file gets deleted between the time the call to +:func:`os.path.exists` is made and the time :func:`open` is called. That means +the last line will throw an :exc:`IOError`. The same would happen if *file* +exists but has no read permission. Since testing this on a normal machine on +existing and non-existing files make it seem bugless, that means in testing the +results will seem fine, and the code will get shipped. Then an unhandled +:exc:`IOError` escapes to the user, who has to watch the ugly traceback. + +Here is a better way to do it. :: + + def get_status(file): + try: + return open(file).readline() + except (IOError, OSError): + print "file not found" + sys.exit(1) + +In this version, \*either\* the file gets opened and the line is read (so it +works even on flaky NFS or SMB connections), or the message is printed and the +application aborted. + +Still, :func:`get_status` makes too many assumptions --- that it will only be +used in a short running script, and not, say, in a long running server. Sure, +the caller could do something like :: + + try: + status = get_status(log) + except SystemExit: + status = None + +So, try to make as few ``except`` clauses in your code --- those will usually be +a catch-all in the :func:`main`, or inside calls which should always succeed. + +So, the best version is probably :: + + def get_status(file): + return open(file).readline() + +The caller can deal with the exception if it wants (for example, if it tries +several files in a loop), or just let the exception filter upwards to *its* +caller. + +The last version is not very good either --- due to implementation details, the +file would not be closed when an exception is raised until the handler finishes, +and perhaps not at all in non-C implementations (e.g., Jython). :: + + def get_status(file): + fp = open(file) + try: + return fp.readline() + finally: + fp.close() + + +Using the Batteries +=================== + +Every so often, people seem to be writing stuff in the Python library again, +usually poorly. While the occasional module has a poor interface, it is usually +much better to use the rich standard library and data types that come with +Python then inventing your own. + +A useful module very few people know about is :mod:`os.path`. It always has the +correct path arithmetic for your operating system, and will usually be much +better then whatever you come up with yourself. + +Compare:: + + # ugh! + return dir+"/"+file + # better + return os.path.join(dir, file) + +More useful functions in :mod:`os.path`: :func:`basename`, :func:`dirname` and +:func:`splitext`. + +There are also many useful builtin functions people seem not to be aware of for +some reason: :func:`min` and :func:`max` can find the minimum/maximum of any +sequence with comparable semantics, for example, yet many people write their own +:func:`max`/:func:`min`. Another highly useful function is :func:`reduce`. A +classical use of :func:`reduce` is something like :: + + import sys, operator + nums = map(float, sys.argv[1:]) + print reduce(operator.add, nums)/len(nums) + +This cute little script prints the average of all numbers given on the command +line. The :func:`reduce` adds up all the numbers, and the rest is just some pre- +and postprocessing. + +On the same note, note that :func:`float`, :func:`int` and :func:`long` all +accept arguments of type string, and so are suited to parsing --- assuming you +are ready to deal with the :exc:`ValueError` they raise. + + +Using Backslash to Continue Statements +====================================== + +Since Python treats a newline as a statement terminator, and since statements +are often more then is comfortable to put in one line, many people do:: + + if foo.bar()['first'][0] == baz.quux(1, 2)[5:9] and \ + calculate_number(10, 20) != forbulate(500, 360): + pass + +You should realize that this is dangerous: a stray space after the ``XXX`` would +make this line wrong, and stray spaces are notoriously hard to see in editors. +In this case, at least it would be a syntax error, but if the code was:: + + value = foo.bar()['first'][0]*baz.quux(1, 2)[5:9] \ + + calculate_number(10, 20)*forbulate(500, 360) + +then it would just be subtly wrong. + +It is usually much better to use the implicit continuation inside parenthesis: + +This version is bulletproof:: + + value = (foo.bar()['first'][0]*baz.quux(1, 2)[5:9] + + calculate_number(10, 20)*forbulate(500, 360)) + Added: doctools/trunk/Doc-26/howto/functional.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-26/howto/functional.rst Thu Aug 2 23:31:34 2007 @@ -0,0 +1,1400 @@ +******************************** + Functional Programming HOWTO +******************************** + +:Author: \A. M. Kuchling +:Release: 0.30 + +(This is a first draft. Please send comments/error reports/suggestions to +amk at amk.ca. This URL is probably not going to be the final location of the +document, so be careful about linking to it -- you may want to add a +disclaimer.) + +In this document, we'll take a tour of Python's features suitable for +implementing programs in a functional style. After an introduction to the +concepts of functional programming, we'll look at language features such as +iterators and generators and relevant library modules such as :mod:`itertools` +and :mod:`functools`. + + +Introduction +============ + +This section explains the basic concept of functional programming; if you're +just interested in learning about Python language features, skip to the next +section. + +Programming languages support decomposing problems in several different ways: + +* Most programming languages are **procedural**: programs are lists of + instructions that tell the computer what to do with the program's input. C, + Pascal, and even Unix shells are procedural languages. + +* In **declarative** languages, you write a specification that describes the + problem to be solved, and the language implementation figures out how to + perform the computation efficiently. SQL is the declarative language you're + most likely to be familiar with; a SQL query describes the data set you want + to retrieve, and the SQL engine decides whether to scan tables or use indexes, + which subclauses should be performed first, etc. + +* **Object-oriented** programs manipulate collections of objects. Objects have + internal state and support methods that query or modify this internal state in + some way. Smalltalk and Java are object-oriented languages. C++ and Python + are languages that support object-oriented programming, but don't force the + use of object-oriented features. + +* **Functional** programming decomposes a problem into a set of functions. + Ideally, functions only take inputs and produce outputs, and don't have any + internal state that affects the output produced for a given input. Well-known + functional languages include the ML family (Standard ML, OCaml, and other + variants) and Haskell. + +The designers of some computer languages have chosen one approach to programming +that's emphasized. This often makes it difficult to write programs that use a +different approach. Other languages are multi-paradigm languages that support +several different approaches. Lisp, C++, and Python are multi-paradigm; you can +write programs or libraries that are largely procedural, object-oriented, or +functional in all of these languages. In a large program, different sections +might be written using different approaches; the GUI might be object-oriented +while the processing logic is procedural or functional, for example. + +In a functional program, input flows through a set of functions. Each function +operates on its input and produces some output. Functional style frowns upon +functions with side effects that modify internal state or make other changes +that aren't visible in the function's return value. Functions that have no side +effects at all are called **purely functional**. Avoiding side effects means +not using data structures that get updated as a program runs; every function's +output must only depend on its input. + +Some languages are very strict about purity and don't even have assignment +statements such as ``a=3`` or ``c = a + b``, but it's difficult to avoid all +side effects. Printing to the screen or writing to a disk file are side +effects, for example. For example, in Python a ``print`` statement or a +``time.sleep(1)`` both return no useful value; they're only called for their +side effects of sending some text to the screen or pausing execution for a +second. + +Python programs written in functional style usually won't go to the extreme of +avoiding all I/O or all assignments; instead, they'll provide a +functional-appearing interface but will use non-functional features internally. +For example, the implementation of a function will still use assignments to +local variables, but won't modify global variables or have other side effects. + +Functional programming can be considered the opposite of object-oriented +programming. Objects are little capsules containing some internal state along +with a collection of method calls that let you modify this state, and programs +consist of making the right set of state changes. Functional programming wants +to avoid state changes as much as possible and works with data flowing between +functions. In Python you might combine the two approaches by writing functions +that take and return instances representing objects in your application (e-mail +messages, transactions, etc.). + +Functional design may seem like an odd constraint to work under. Why should you +avoid objects and side effects? There are theoretical and practical advantages +to the functional style: + +* Formal provability. +* Modularity. +* Composability. +* Ease of debugging and testing. + +Formal provability +------------------ + +A theoretical benefit is that it's easier to construct a mathematical proof that +a functional program is correct. + +For a long time researchers have been interested in finding ways to +mathematically prove programs correct. This is different from testing a program +on numerous inputs and concluding that its output is usually correct, or reading +a program's source code and concluding that the code looks right; the goal is +instead a rigorous proof that a program produces the right result for all +possible inputs. + +The technique used to prove programs correct is to write down **invariants**, +properties of the input data and of the program's variables that are always +true. For each line of code, you then show that if invariants X and Y are true +**before** the line is executed, the slightly different invariants X' and Y' are +true **after** the line is executed. This continues until you reach the end of +the program, at which point the invariants should match the desired conditions +on the program's output. + +Functional programming's avoidance of assignments arose because assignments are +difficult to handle with this technique; assignments can break invariants that +were true before the assignment without producing any new invariants that can be +propagated onward. + +Unfortunately, proving programs correct is largely impractical and not relevant +to Python software. Even trivial programs require proofs that are several pages +long; the proof of correctness for a moderately complicated program would be +enormous, and few or none of the programs you use daily (the Python interpreter, +your XML parser, your web browser) could be proven correct. Even if you wrote +down or generated a proof, there would then be the question of verifying the +proof; maybe there's an error in it, and you wrongly believe you've proved the +program correct. + +Modularity +---------- + +A more practical benefit of functional programming is that it forces you to +break apart your problem into small pieces. Programs are more modular as a +result. It's easier to specify and write a small function that does one thing +than a large function that performs a complicated transformation. Small +functions are also easier to read and to check for errors. + + +Ease of debugging and testing +----------------------------- + +Testing and debugging a functional-style program is easier. + +Debugging is simplified because functions are generally small and clearly +specified. When a program doesn't work, each function is an interface point +where you can check that the data are correct. You can look at the intermediate +inputs and outputs to quickly isolate the function that's responsible for a bug. + +Testing is easier because each function is a potential subject for a unit test. +Functions don't depend on system state that needs to be replicated before +running a test; instead you only have to synthesize the right input and then +check that the output matches expectations. + + + +Composability +------------- + +As you work on a functional-style program, you'll write a number of functions +with varying inputs and outputs. Some of these functions will be unavoidably +specialized to a particular application, but others will be useful in a wide +variety of programs. For example, a function that takes a directory path and +returns all the XML files in the directory, or a function that takes a filename +and returns its contents, can be applied to many different situations. + +Over time you'll form a personal library of utilities. Often you'll assemble +new programs by arranging existing functions in a new configuration and writing +a few functions specialized for the current task. + + + +Iterators +========= + +I'll start by looking at a Python language feature that's an important +foundation for writing functional-style programs: iterators. + +An iterator is an object representing a stream of data; this object returns the +data one element at a time. A Python iterator must support a method called +``next()`` that takes no arguments and always returns the next element of the +stream. If there are no more elements in the stream, ``next()`` must raise the +``StopIteration`` exception. Iterators don't have to be finite, though; it's +perfectly reasonable to write an iterator that produces an infinite stream of +data. + +The built-in :func:`iter` function takes an arbitrary object and tries to return +an iterator that will return the object's contents or elements, raising +:exc:`TypeError` if the object doesn't support iteration. Several of Python's +built-in data types support iteration, the most common being lists and +dictionaries. An object is called an **iterable** object if you can get an +iterator for it. + +You can experiment with the iteration interface manually:: + + >>> L = [1,2,3] + >>> it = iter(L) + >>> print it + + >>> it.next() + 1 + >>> it.next() + 2 + >>> it.next() + 3 + >>> it.next() + Traceback (most recent call last): + File "", line 1, in ? + StopIteration + >>> + +Python expects iterable objects in several different contexts, the most +important being the ``for`` statement. In the statement ``for X in Y``, Y must +be an iterator or some object for which ``iter()`` can create an iterator. +These two statements are equivalent:: + + for i in iter(obj): + print i + + for i in obj: + print i + +Iterators can be materialized as lists or tuples by using the :func:`list` or +:func:`tuple` constructor functions:: + + >>> L = [1,2,3] + >>> iterator = iter(L) + >>> t = tuple(iterator) + >>> t + (1, 2, 3) + +Sequence unpacking also supports iterators: if you know an iterator will return +N elements, you can unpack them into an N-tuple:: + + >>> L = [1,2,3] + >>> iterator = iter(L) + >>> a,b,c = iterator + >>> a,b,c + (1, 2, 3) + +Built-in functions such as :func:`max` and :func:`min` can take a single +iterator argument and will return the largest or smallest element. The ``"in"`` +and ``"not in"`` operators also support iterators: ``X in iterator`` is true if +X is found in the stream returned by the iterator. You'll run into obvious +problems if the iterator is infinite; ``max()``, ``min()``, and ``"not in"`` +will never return, and if the element X never appears in the stream, the +``"in"`` operator won't return either. + +Note that you can only go forward in an iterator; there's no way to get the +previous element, reset the iterator, or make a copy of it. Iterator objects +can optionally provide these additional capabilities, but the iterator protocol +only specifies the ``next()`` method. Functions may therefore consume all of +the iterator's output, and if you need to do something different with the same +stream, you'll have to create a new iterator. + + + +Data Types That Support Iterators +--------------------------------- + +We've already seen how lists and tuples support iterators. In fact, any Python +sequence type, such as strings, will automatically support creation of an +iterator. + +Calling :func:`iter` on a dictionary returns an iterator that will loop over the +dictionary's keys:: + + >>> m = {'Jan': 1, 'Feb': 2, 'Mar': 3, 'Apr': 4, 'May': 5, 'Jun': 6, + ... 'Jul': 7, 'Aug': 8, 'Sep': 9, 'Oct': 10, 'Nov': 11, 'Dec': 12} + >>> for key in m: + ... print key, m[key] + Mar 3 + Feb 2 + Aug 8 + Sep 9 + May 5 + Jun 6 + Jul 7 + Jan 1 + Apr 4 + Nov 11 + Dec 12 + Oct 10 + +Note that the order is essentially random, because it's based on the hash +ordering of the objects in the dictionary. + +Applying ``iter()`` to a dictionary always loops over the keys, but dictionaries +have methods that return other iterators. If you want to iterate over keys, +values, or key/value pairs, you can explicitly call the ``iterkeys()``, +``itervalues()``, or ``iteritems()`` methods to get an appropriate iterator. + +The :func:`dict` constructor can accept an iterator that returns a finite stream +of ``(key, value)`` tuples:: + + >>> L = [('Italy', 'Rome'), ('France', 'Paris'), ('US', 'Washington DC')] + >>> dict(iter(L)) + {'Italy': 'Rome', 'US': 'Washington DC', 'France': 'Paris'} + +Files also support iteration by calling the ``readline()`` method until there +are no more lines in the file. This means you can read each line of a file like +this:: + + for line in file: + # do something for each line + ... + +Sets can take their contents from an iterable and let you iterate over the set's +elements:: + + S = set((2, 3, 5, 7, 11, 13)) + for i in S: + print i + + + +Generator expressions and list comprehensions +============================================= + +Two common operations on an iterator's output are 1) performing some operation +for every element, 2) selecting a subset of elements that meet some condition. +For example, given a list of strings, you might want to strip off trailing +whitespace from each line or extract all the strings containing a given +substring. + +List comprehensions and generator expressions (short form: "listcomps" and +"genexps") are a concise notation for such operations, borrowed from the +functional programming language Haskell (http://www.haskell.org). You can strip +all the whitespace from a stream of strings with the following code:: + + line_list = [' line 1\n', 'line 2 \n', ...] + + # Generator expression -- returns iterator + stripped_iter = (line.strip() for line in line_list) + + # List comprehension -- returns list + stripped_list = [line.strip() for line in line_list] + +You can select only certain elements by adding an ``"if"`` condition:: + + stripped_list = [line.strip() for line in line_list + if line != ""] + +With a list comprehension, you get back a Python list; ``stripped_list`` is a +list containing the resulting lines, not an iterator. Generator expressions +return an iterator that computes the values as necessary, not needing to +materialize all the values at once. This means that list comprehensions aren't +useful if you're working with iterators that return an infinite stream or a very +large amount of data. Generator expressions are preferable in these situations. + +Generator expressions are surrounded by parentheses ("()") and list +comprehensions are surrounded by square brackets ("[]"). Generator expressions +have the form:: + + ( expression for expr in sequence1 + if condition1 + for expr2 in sequence2 + if condition2 + for expr3 in sequence3 ... + if condition3 + for exprN in sequenceN + if conditionN ) + +Again, for a list comprehension only the outside brackets are different (square +brackets instead of parentheses). + +The elements of the generated output will be the successive values of +``expression``. The ``if`` clauses are all optional; if present, ``expression`` +is only evaluated and added to the result when ``condition`` is true. + +Generator expressions always have to be written inside parentheses, but the +parentheses signalling a function call also count. If you want to create an +iterator that will be immediately passed to a function you can write:: + + obj_total = sum(obj.count for obj in list_all_objects()) + +The ``for...in`` clauses contain the sequences to be iterated over. The +sequences do not have to be the same length, because they are iterated over from +left to right, **not** in parallel. For each element in ``sequence1``, +``sequence2`` is looped over from the beginning. ``sequence3`` is then looped +over for each resulting pair of elements from ``sequence1`` and ``sequence2``. + +To put it another way, a list comprehension or generator expression is +equivalent to the following Python code:: + + for expr1 in sequence1: + if not (condition1): + continue # Skip this element + for expr2 in sequence2: + if not (condition2): + continue # Skip this element + ... + for exprN in sequenceN: + if not (conditionN): + continue # Skip this element + + # Output the value of + # the expression. + +This means that when there are multiple ``for...in`` clauses but no ``if`` +clauses, the length of the resulting output will be equal to the product of the +lengths of all the sequences. If you have two lists of length 3, the output +list is 9 elements long:: + + seq1 = 'abc' + seq2 = (1,2,3) + >>> [ (x,y) for x in seq1 for y in seq2] + [('a', 1), ('a', 2), ('a', 3), + ('b', 1), ('b', 2), ('b', 3), + ('c', 1), ('c', 2), ('c', 3)] + +To avoid introducing an ambiguity into Python's grammar, if ``expression`` is +creating a tuple, it must be surrounded with parentheses. The first list +comprehension below is a syntax error, while the second one is correct:: + + # Syntax error + [ x,y for x in seq1 for y in seq2] + # Correct + [ (x,y) for x in seq1 for y in seq2] + + +Generators +========== + +Generators are a special class of functions that simplify the task of writing +iterators. Regular functions compute a value and return it, but generators +return an iterator that returns a stream of values. + +You're doubtless familiar with how regular function calls work in Python or C. +When you call a function, it gets a private namespace where its local variables +are created. When the function reaches a ``return`` statement, the local +variables are destroyed and the value is returned to the caller. A later call +to the same function creates a new private namespace and a fresh set of local +variables. But, what if the local variables weren't thrown away on exiting a +function? What if you could later resume the function where it left off? This +is what generators provide; they can be thought of as resumable functions. + +Here's the simplest example of a generator function:: + + def generate_ints(N): + for i in range(N): + yield i + +Any function containing a ``yield`` keyword is a generator function; this is +detected by Python's bytecode compiler which compiles the function specially as +a result. + +When you call a generator function, it doesn't return a single value; instead it +returns a generator object that supports the iterator protocol. On executing +the ``yield`` expression, the generator outputs the value of ``i``, similar to a +``return`` statement. The big difference between ``yield`` and a ``return`` +statement is that on reaching a ``yield`` the generator's state of execution is +suspended and local variables are preserved. On the next call to the +generator's ``.next()`` method, the function will resume executing. + +Here's a sample usage of the ``generate_ints()`` generator:: + + >>> gen = generate_ints(3) + >>> gen + + >>> gen.next() + 0 + >>> gen.next() + 1 + >>> gen.next() + 2 + >>> gen.next() + Traceback (most recent call last): + File "stdin", line 1, in ? + File "stdin", line 2, in generate_ints + StopIteration + +You could equally write ``for i in generate_ints(5)``, or ``a,b,c = +generate_ints(3)``. + +Inside a generator function, the ``return`` statement can only be used without a +value, and signals the end of the procession of values; after executing a +``return`` the generator cannot return any further values. ``return`` with a +value, such as ``return 5``, is a syntax error inside a generator function. The +end of the generator's results can also be indicated by raising +``StopIteration`` manually, or by just letting the flow of execution fall off +the bottom of the function. + +You could achieve the effect of generators manually by writing your own class +and storing all the local variables of the generator as instance variables. For +example, returning a list of integers could be done by setting ``self.count`` to +0, and having the ``next()`` method increment ``self.count`` and return it. +However, for a moderately complicated generator, writing a corresponding class +can be much messier. + +The test suite included with Python's library, ``test_generators.py``, contains +a number of more interesting examples. Here's one generator that implements an +in-order traversal of a tree using generators recursively. + +:: + + # A recursive generator that generates Tree leaves in in-order. + def inorder(t): + if t: + for x in inorder(t.left): + yield x + + yield t.label + + for x in inorder(t.right): + yield x + +Two other examples in ``test_generators.py`` produce solutions for the N-Queens +problem (placing N queens on an NxN chess board so that no queen threatens +another) and the Knight's Tour (finding a route that takes a knight to every +square of an NxN chessboard without visiting any square twice). + + + +Passing values into a generator +------------------------------- + +In Python 2.4 and earlier, generators only produced output. Once a generator's +code was invoked to create an iterator, there was no way to pass any new +information into the function when its execution is resumed. You could hack +together this ability by making the generator look at a global variable or by +passing in some mutable object that callers then modify, but these approaches +are messy. + +In Python 2.5 there's a simple way to pass values into a generator. +:keyword:`yield` became an expression, returning a value that can be assigned to +a variable or otherwise operated on:: + + val = (yield i) + +I recommend that you **always** put parentheses around a ``yield`` expression +when you're doing something with the returned value, as in the above example. +The parentheses aren't always necessary, but it's easier to always add them +instead of having to remember when they're needed. + +(PEP 342 explains the exact rules, which are that a ``yield``-expression must +always be parenthesized except when it occurs at the top-level expression on the +right-hand side of an assignment. This means you can write ``val = yield i`` +but have to use parentheses when there's an operation, as in ``val = (yield i) ++ 12``.) + +Values are sent into a generator by calling its ``send(value)`` method. This +method resumes the generator's code and the ``yield`` expression returns the +specified value. If the regular ``next()`` method is called, the ``yield`` +returns ``None``. + +Here's a simple counter that increments by 1 and allows changing the value of +the internal counter. + +:: + + def counter (maximum): + i = 0 + while i < maximum: + val = (yield i) + # If value provided, change counter + if val is not None: + i = val + else: + i += 1 + +And here's an example of changing the counter: + + >>> it = counter(10) + >>> print it.next() + 0 + >>> print it.next() + 1 + >>> print it.send(8) + 8 + >>> print it.next() + 9 + >>> print it.next() + Traceback (most recent call last): + File ``t.py'', line 15, in ? + print it.next() + StopIteration + +Because ``yield`` will often be returning ``None``, you should always check for +this case. Don't just use its value in expressions unless you're sure that the +``send()`` method will be the only method used resume your generator function. + +In addition to ``send()``, there are two other new methods on generators: + +* ``throw(type, value=None, traceback=None)`` is used to raise an exception + inside the generator; the exception is raised by the ``yield`` expression + where the generator's execution is paused. + +* ``close()`` raises a :exc:`GeneratorExit` exception inside the generator to + terminate the iteration. On receiving this exception, the generator's code + must either raise :exc:`GeneratorExit` or :exc:`StopIteration`; catching the + exception and doing anything else is illegal and will trigger a + :exc:`RuntimeError`. ``close()`` will also be called by Python's garbage + collector when the generator is garbage-collected. + + If you need to run cleanup code when a :exc:`GeneratorExit` occurs, I suggest + using a ``try: ... finally:`` suite instead of catching :exc:`GeneratorExit`. + +The cumulative effect of these changes is to turn generators from one-way +producers of information into both producers and consumers. + +Generators also become **coroutines**, a more generalized form of subroutines. +Subroutines are entered at one point and exited at another point (the top of the +function, and a ``return`` statement), but coroutines can be entered, exited, +and resumed at many different points (the ``yield`` statements). + + +Built-in functions +================== + +Let's look in more detail at built-in functions often used with iterators. + +Two Python's built-in functions, :func:`map` and :func:`filter`, are somewhat +obsolete; they duplicate the features of list comprehensions but return actual +lists instead of iterators. + +``map(f, iterA, iterB, ...)`` returns a list containing ``f(iterA[0], iterB[0]), +f(iterA[1], iterB[1]), f(iterA[2], iterB[2]), ...``. + +:: + + def upper(s): + return s.upper() + map(upper, ['sentence', 'fragment']) => + ['SENTENCE', 'FRAGMENT'] + + [upper(s) for s in ['sentence', 'fragment']] => + ['SENTENCE', 'FRAGMENT'] + +As shown above, you can achieve the same effect with a list comprehension. The +:func:`itertools.imap` function does the same thing but can handle infinite +iterators; it'll be discussed later, in the section on the :mod:`itertools` module. + +``filter(predicate, iter)`` returns a list that contains all the sequence +elements that meet a certain condition, and is similarly duplicated by list +comprehensions. A **predicate** is a function that returns the truth value of +some condition; for use with :func:`filter`, the predicate must take a single +value. + +:: + + def is_even(x): + return (x % 2) == 0 + + filter(is_even, range(10)) => + [0, 2, 4, 6, 8] + +This can also be written as a list comprehension:: + + >>> [x for x in range(10) if is_even(x)] + [0, 2, 4, 6, 8] + +:func:`filter` also has a counterpart in the :mod:`itertools` module, +:func:`itertools.ifilter`, that returns an iterator and can therefore handle +infinite sequences just as :func:`itertools.imap` can. + +``reduce(func, iter, [initial_value])`` doesn't have a counterpart in the +:mod:`itertools` module because it cumulatively performs an operation on all the +iterable's elements and therefore can't be applied to infinite iterables. +``func`` must be a function that takes two elements and returns a single value. +:func:`reduce` takes the first two elements A and B returned by the iterator and +calculates ``func(A, B)``. It then requests the third element, C, calculates +``func(func(A, B), C)``, combines this result with the fourth element returned, +and continues until the iterable is exhausted. If the iterable returns no +values at all, a :exc:`TypeError` exception is raised. If the initial value is +supplied, it's used as a starting point and ``func(initial_value, A)`` is the +first calculation. + +:: + + import operator + reduce(operator.concat, ['A', 'BB', 'C']) => + 'ABBC' + reduce(operator.concat, []) => + TypeError: reduce() of empty sequence with no initial value + reduce(operator.mul, [1,2,3], 1) => + 6 + reduce(operator.mul, [], 1) => + 1 + +If you use :func:`operator.add` with :func:`reduce`, you'll add up all the +elements of the iterable. This case is so common that there's a special +built-in called :func:`sum` to compute it:: + + reduce(operator.add, [1,2,3,4], 0) => + 10 + sum([1,2,3,4]) => + 10 + sum([]) => + 0 + +For many uses of :func:`reduce`, though, it can be clearer to just write the +obvious :keyword:`for` loop:: + + # Instead of: + product = reduce(operator.mul, [1,2,3], 1) + + # You can write: + product = 1 + for i in [1,2,3]: + product *= i + + +``enumerate(iter)`` counts off the elements in the iterable, returning 2-tuples +containing the count and each element. + +:: + + enumerate(['subject', 'verb', 'object']) => + (0, 'subject'), (1, 'verb'), (2, 'object') + +:func:`enumerate` is often used when looping through a list and recording the +indexes at which certain conditions are met:: + + f = open('data.txt', 'r') + for i, line in enumerate(f): + if line.strip() == '': + print 'Blank line at line #%i' % i + +``sorted(iterable, [cmp=None], [key=None], [reverse=False)`` collects all the +elements of the iterable into a list, sorts the list, and returns the sorted +result. The ``cmp``, ``key``, and ``reverse`` arguments are passed through to +the constructed list's ``.sort()`` method. + +:: + + import random + # Generate 8 random numbers between [0, 10000) + rand_list = random.sample(range(10000), 8) + rand_list => + [769, 7953, 9828, 6431, 8442, 9878, 6213, 2207] + sorted(rand_list) => + [769, 2207, 6213, 6431, 7953, 8442, 9828, 9878] + sorted(rand_list, reverse=True) => + [9878, 9828, 8442, 7953, 6431, 6213, 2207, 769] + +(For a more detailed discussion of sorting, see the Sorting mini-HOWTO in the +Python wiki at http://wiki.python.org/moin/HowTo/Sorting.) + +The ``any(iter)`` and ``all(iter)`` built-ins look at the truth values of an +iterable's contents. :func:`any` returns True if any element in the iterable is +a true value, and :func:`all` returns True if all of the elements are true +values:: + + any([0,1,0]) => + True + any([0,0,0]) => + False + any([1,1,1]) => + True + all([0,1,0]) => + False + all([0,0,0]) => + False + all([1,1,1]) => + True + + +Small functions and the lambda expression +========================================= + +When writing functional-style programs, you'll often need little functions that +act as predicates or that combine elements in some way. + +If there's a Python built-in or a module function that's suitable, you don't +need to define a new function at all:: + + stripped_lines = [line.strip() for line in lines] + existing_files = filter(os.path.exists, file_list) + +If the function you need doesn't exist, you need to write it. One way to write +small functions is to use the ``lambda`` statement. ``lambda`` takes a number +of parameters and an expression combining these parameters, and creates a small +function that returns the value of the expression:: + + lowercase = lambda x: x.lower() + + print_assign = lambda name, value: name + '=' + str(value) + + adder = lambda x, y: x+y + +An alternative is to just use the ``def`` statement and define a function in the +usual way:: + + def lowercase(x): + return x.lower() + + def print_assign(name, value): + return name + '=' + str(value) + + def adder(x,y): + return x + y + +Which alternative is preferable? That's a style question; my usual course is to +avoid using ``lambda``. + +One reason for my preference is that ``lambda`` is quite limited in the +functions it can define. The result has to be computable as a single +expression, which means you can't have multiway ``if... elif... else`` +comparisons or ``try... except`` statements. If you try to do too much in a +``lambda`` statement, you'll end up with an overly complicated expression that's +hard to read. Quick, what's the following code doing? + +:: + + total = reduce(lambda a, b: (0, a[1] + b[1]), items)[1] + +You can figure it out, but it takes time to disentangle the expression to figure +out what's going on. Using a short nested ``def`` statements makes things a +little bit better:: + + def combine (a, b): + return 0, a[1] + b[1] + + total = reduce(combine, items)[1] + +But it would be best of all if I had simply used a ``for`` loop:: + + total = 0 + for a, b in items: + total += b + +Or the :func:`sum` built-in and a generator expression:: + + total = sum(b for a,b in items) + +Many uses of :func:`reduce` are clearer when written as ``for`` loops. + +Fredrik Lundh once suggested the following set of rules for refactoring uses of +``lambda``: + +1) Write a lambda function. +2) Write a comment explaining what the heck that lambda does. +3) Study the comment for a while, and think of a name that captures the essence + of the comment. +4) Convert the lambda to a def statement, using that name. +5) Remove the comment. + +I really like these rules, but you're free to disagree that this lambda-free +style is better. + + +The itertools module +==================== + +The :mod:`itertools` module contains a number of commonly-used iterators as well +as functions for combining several iterators. This section will introduce the +module's contents by showing small examples. + +The module's functions fall into a few broad classes: + +* Functions that create a new iterator based on an existing iterator. +* Functions for treating an iterator's elements as function arguments. +* Functions for selecting portions of an iterator's output. +* A function for grouping an iterator's output. + +Creating new iterators +---------------------- + +``itertools.count(n)`` returns an infinite stream of integers, increasing by 1 +each time. You can optionally supply the starting number, which defaults to 0:: + + itertools.count() => + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ... + itertools.count(10) => + 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, ... + +``itertools.cycle(iter)`` saves a copy of the contents of a provided iterable +and returns a new iterator that returns its elements from first to last. The +new iterator will repeat these elements infinitely. + +:: + + itertools.cycle([1,2,3,4,5]) => + 1, 2, 3, 4, 5, 1, 2, 3, 4, 5, ... + +``itertools.repeat(elem, [n])`` returns the provided element ``n`` times, or +returns the element endlessly if ``n`` is not provided. + +:: + + itertools.repeat('abc') => + abc, abc, abc, abc, abc, abc, abc, abc, abc, abc, ... + itertools.repeat('abc', 5) => + abc, abc, abc, abc, abc + +``itertools.chain(iterA, iterB, ...)`` takes an arbitrary number of iterables as +input, and returns all the elements of the first iterator, then all the elements +of the second, and so on, until all of the iterables have been exhausted. + +:: + + itertools.chain(['a', 'b', 'c'], (1, 2, 3)) => + a, b, c, 1, 2, 3 + +``itertools.izip(iterA, iterB, ...)`` takes one element from each iterable and +returns them in a tuple:: + + itertools.izip(['a', 'b', 'c'], (1, 2, 3)) => + ('a', 1), ('b', 2), ('c', 3) + +It's similiar to the built-in :func:`zip` function, but doesn't construct an +in-memory list and exhaust all the input iterators before returning; instead +tuples are constructed and returned only if they're requested. (The technical +term for this behaviour is `lazy evaluation +`__.) + +This iterator is intended to be used with iterables that are all of the same +length. If the iterables are of different lengths, the resulting stream will be +the same length as the shortest iterable. + +:: + + itertools.izip(['a', 'b'], (1, 2, 3)) => + ('a', 1), ('b', 2) + +You should avoid doing this, though, because an element may be taken from the +longer iterators and discarded. This means you can't go on to use the iterators +further because you risk skipping a discarded element. + +``itertools.islice(iter, [start], stop, [step])`` returns a stream that's a +slice of the iterator. With a single ``stop`` argument, it will return the +first ``stop`` elements. If you supply a starting index, you'll get +``stop-start`` elements, and if you supply a value for ``step``, elements will +be skipped accordingly. Unlike Python's string and list slicing, you can't use +negative values for ``start``, ``stop``, or ``step``. + +:: + + itertools.islice(range(10), 8) => + 0, 1, 2, 3, 4, 5, 6, 7 + itertools.islice(range(10), 2, 8) => + 2, 3, 4, 5, 6, 7 + itertools.islice(range(10), 2, 8, 2) => + 2, 4, 6 + +``itertools.tee(iter, [n])`` replicates an iterator; it returns ``n`` +independent iterators that will all return the contents of the source iterator. +If you don't supply a value for ``n``, the default is 2. Replicating iterators +requires saving some of the contents of the source iterator, so this can consume +significant memory if the iterator is large and one of the new iterators is +consumed more than the others. + +:: + + itertools.tee( itertools.count() ) => + iterA, iterB + + where iterA -> + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ... + + and iterB -> + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ... + + +Calling functions on elements +----------------------------- + +Two functions are used for calling other functions on the contents of an +iterable. + +``itertools.imap(f, iterA, iterB, ...)`` returns a stream containing +``f(iterA[0], iterB[0]), f(iterA[1], iterB[1]), f(iterA[2], iterB[2]), ...``:: + + itertools.imap(operator.add, [5, 6, 5], [1, 2, 3]) => + 6, 8, 8 + +The ``operator`` module contains a set of functions corresponding to Python's +operators. Some examples are ``operator.add(a, b)`` (adds two values), +``operator.ne(a, b)`` (same as ``a!=b``), and ``operator.attrgetter('id')`` +(returns a callable that fetches the ``"id"`` attribute). + +``itertools.starmap(func, iter)`` assumes that the iterable will return a stream +of tuples, and calls ``f()`` using these tuples as the arguments:: + + itertools.starmap(os.path.join, + [('/usr', 'bin', 'java'), ('/bin', 'python'), + ('/usr', 'bin', 'perl'),('/usr', 'bin', 'ruby')]) + => + /usr/bin/java, /bin/python, /usr/bin/perl, /usr/bin/ruby + + +Selecting elements +------------------ + +Another group of functions chooses a subset of an iterator's elements based on a +predicate. + +``itertools.ifilter(predicate, iter)`` returns all the elements for which the +predicate returns true:: + + def is_even(x): + return (x % 2) == 0 + + itertools.ifilter(is_even, itertools.count()) => + 0, 2, 4, 6, 8, 10, 12, 14, ... + +``itertools.ifilterfalse(predicate, iter)`` is the opposite, returning all +elements for which the predicate returns false:: + + itertools.ifilterfalse(is_even, itertools.count()) => + 1, 3, 5, 7, 9, 11, 13, 15, ... + +``itertools.takewhile(predicate, iter)`` returns elements for as long as the +predicate returns true. Once the predicate returns false, the iterator will +signal the end of its results. + +:: + + def less_than_10(x): + return (x < 10) + + itertools.takewhile(less_than_10, itertools.count()) => + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 + + itertools.takewhile(is_even, itertools.count()) => + 0 + +``itertools.dropwhile(predicate, iter)`` discards elements while the predicate +returns true, and then returns the rest of the iterable's results. + +:: + + itertools.dropwhile(less_than_10, itertools.count()) => + 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, ... + + itertools.dropwhile(is_even, itertools.count()) => + 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ... + + +Grouping elements +''''''''''''''''' + +The last function I'll discuss, ``itertools.groupby(iter, key_func=None)``, is +the most complicated. ``key_func(elem)`` is a function that can compute a key +value for each element returned by the iterable. If you don't supply a key +function, the key is simply each element itself. + +``groupby()`` collects all the consecutive elements from the underlying iterable +that have the same key value, and returns a stream of 2-tuples containing a key +value and an iterator for the elements with that key. + +:: + + city_list = [('Decatur', 'AL'), ('Huntsville', 'AL'), ('Selma', 'AL'), + ('Anchorage', 'AK'), ('Nome', 'AK'), + ('Flagstaff', 'AZ'), ('Phoenix', 'AZ'), ('Tucson', 'AZ'), + ... + ] + + def get_state ((city, state)): + return state + + itertools.groupby(city_list, get_state) => + ('AL', iterator-1), + ('AK', iterator-2), + ('AZ', iterator-3), ... + + where + iterator-1 => + ('Decatur', 'AL'), ('Huntsville', 'AL'), ('Selma', 'AL') + iterator-2 => + ('Anchorage', 'AK'), ('Nome', 'AK') + iterator-3 => + ('Flagstaff', 'AZ'), ('Phoenix', 'AZ'), ('Tucson', 'AZ') + +``groupby()`` assumes that the underlying iterable's contents will already be +sorted based on the key. Note that the returned iterators also use the +underlying iterable, so you have to consume the results of iterator-1 before +requesting iterator-2 and its corresponding key. + + +The functools module +==================== + +The :mod:`functools` module in Python 2.5 contains some higher-order functions. +A **higher-order function** takes one or more functions as input and returns a +new function. The most useful tool in this module is the +:func:`functools.partial` function. + +For programs written in a functional style, you'll sometimes want to construct +variants of existing functions that have some of the parameters filled in. +Consider a Python function ``f(a, b, c)``; you may wish to create a new function +``g(b, c)`` that's equivalent to ``f(1, b, c)``; you're filling in a value for +one of ``f()``'s parameters. This is called "partial function application". + +The constructor for ``partial`` takes the arguments ``(function, arg1, arg2, +... kwarg1=value1, kwarg2=value2)``. The resulting object is callable, so you +can just call it to invoke ``function`` with the filled-in arguments. + +Here's a small but realistic example:: + + import functools + + def log (message, subsystem): + "Write the contents of 'message' to the specified subsystem." + print '%s: %s' % (subsystem, message) + ... + + server_log = functools.partial(log, subsystem='server') + server_log('Unable to open socket') + + +The operator module +------------------- + +The :mod:`operator` module was mentioned earlier. It contains a set of +functions corresponding to Python's operators. These functions are often useful +in functional-style code because they save you from writing trivial functions +that perform a single operation. + +Some of the functions in this module are: + +* Math operations: ``add()``, ``sub()``, ``mul()``, ``div()``, ``floordiv()``, + ``abs()``, ... +* Logical operations: ``not_()``, ``truth()``. +* Bitwise operations: ``and_()``, ``or_()``, ``invert()``. +* Comparisons: ``eq()``, ``ne()``, ``lt()``, ``le()``, ``gt()``, and ``ge()``. +* Object identity: ``is_()``, ``is_not()``. + +Consult the operator module's documentation for a complete list. + + + +The functional module +--------------------- + +Collin Winter's `functional module `__ +provides a number of more advanced tools for functional programming. It also +reimplements several Python built-ins, trying to make them more intuitive to +those used to functional programming in other languages. + +This section contains an introduction to some of the most important functions in +``functional``; full documentation can be found at `the project's website +`__. + +``compose(outer, inner, unpack=False)`` + +The ``compose()`` function implements function composition. In other words, it +returns a wrapper around the ``outer`` and ``inner`` callables, such that the +return value from ``inner`` is fed directly to ``outer``. That is, + +:: + + >>> def add(a, b): + ... return a + b + ... + >>> def double(a): + ... return 2 * a + ... + >>> compose(double, add)(5, 6) + 22 + +is equivalent to + +:: + + >>> double(add(5, 6)) + 22 + +The ``unpack`` keyword is provided to work around the fact that Python functions +are not always `fully curried `__. By +default, it is expected that the ``inner`` function will return a single object +and that the ``outer`` function will take a single argument. Setting the +``unpack`` argument causes ``compose`` to expect a tuple from ``inner`` which +will be expanded before being passed to ``outer``. Put simply, + +:: + + compose(f, g)(5, 6) + +is equivalent to:: + + f(g(5, 6)) + +while + +:: + + compose(f, g, unpack=True)(5, 6) + +is equivalent to:: + + f(*g(5, 6)) + +Even though ``compose()`` only accepts two functions, it's trivial to build up a +version that will compose any number of functions. We'll use ``reduce()``, +``compose()`` and ``partial()`` (the last of which is provided by both +``functional`` and ``functools``). + +:: + + from functional import compose, partial + + multi_compose = partial(reduce, compose) + + +We can also use ``map()``, ``compose()`` and ``partial()`` to craft a version of +``"".join(...)`` that converts its arguments to string:: + + from functional import compose, partial + + join = compose("".join, partial(map, str)) + + +``flip(func)`` + +``flip()`` wraps the callable in ``func`` and causes it to receive its +non-keyword arguments in reverse order. + +:: + + >>> def triple(a, b, c): + ... return (a, b, c) + ... + >>> triple(5, 6, 7) + (5, 6, 7) + >>> + >>> flipped_triple = flip(triple) + >>> flipped_triple(5, 6, 7) + (7, 6, 5) + +``foldl(func, start, iterable)`` + +``foldl()`` takes a binary function, a starting value (usually some kind of +'zero'), and an iterable. The function is applied to the starting value and the +first element of the list, then the result of that and the second element of the +list, then the result of that and the third element of the list, and so on. + +This means that a call such as:: + + foldl(f, 0, [1, 2, 3]) + +is equivalent to:: + + f(f(f(0, 1), 2), 3) + + +``foldl()`` is roughly equivalent to the following recursive function:: + + def foldl(func, start, seq): + if len(seq) == 0: + return start + + return foldl(func, func(start, seq[0]), seq[1:]) + +Speaking of equivalence, the above ``foldl`` call can be expressed in terms of +the built-in ``reduce`` like so:: + + reduce(f, [1, 2, 3], 0) + + +We can use ``foldl()``, ``operator.concat()`` and ``partial()`` to write a +cleaner, more aesthetically-pleasing version of Python's ``"".join(...)`` +idiom:: + + from functional import foldl, partial + from operator import concat + + join = partial(foldl, concat, "") + + +Revision History and Acknowledgements +===================================== + +The author would like to thank the following people for offering suggestions, +corrections and assistance with various drafts of this article: Ian Bicking, +Nick Coghlan, Nick Efford, Raymond Hettinger, Jim Jewett, Mike Krell, Leandro +Lameiro, Jussi Salmela, Collin Winter, Blake Winton. + +Version 0.1: posted June 30 2006. + +Version 0.11: posted July 1 2006. Typo fixes. + +Version 0.2: posted July 10 2006. Merged genexp and listcomp sections into one. +Typo fixes. + +Version 0.21: Added more references suggested on the tutor mailing list. + +Version 0.30: Adds a section on the ``functional`` module written by Collin +Winter; adds short section on the operator module; a few other edits. + + +References +========== + +General +------- + +**Structure and Interpretation of Computer Programs**, by Harold Abelson and +Gerald Jay Sussman with Julie Sussman. Full text at +http://mitpress.mit.edu/sicp/. In this classic textbook of computer science, +chapters 2 and 3 discuss the use of sequences and streams to organize the data +flow inside a program. The book uses Scheme for its examples, but many of the +design approaches described in these chapters are applicable to functional-style +Python code. + +http://www.defmacro.org/ramblings/fp.html: A general introduction to functional +programming that uses Java examples and has a lengthy historical introduction. + +http://en.wikipedia.org/wiki/Functional_programming: General Wikipedia entry +describing functional programming. + +http://en.wikipedia.org/wiki/Coroutine: Entry for coroutines. + +http://en.wikipedia.org/wiki/Currying: Entry for the concept of currying. + +Python-specific +--------------- + +http://gnosis.cx/TPiP/: The first chapter of David Mertz's book +:title-reference:`Text Processing in Python` discusses functional programming +for text processing, in the section titled "Utilizing Higher-Order Functions in +Text Processing". + +Mertz also wrote a 3-part series of articles on functional programming +for IBM's DeveloperWorks site; see +`part 1 `__, +`part 2 `__, and +`part 3 `__, + + +Python documentation +-------------------- + +Documentation for the :mod:`itertools` module. + +Documentation for the :mod:`operator` module. + +:pep:`289`: "Generator Expressions" + +:pep:`342`: "Coroutines via Enhanced Generators" describes the new generator +features in Python 2.5. + +.. comment + + Topics to place + ----------------------------- + + XXX os.walk() + + XXX Need a large example. + + But will an example add much? I'll post a first draft and see + what the comments say. + +.. comment + + Original outline: + Introduction + Idea of FP + Programs built out of functions + Functions are strictly input-output, no internal state + Opposed to OO programming, where objects have state + + Why FP? + Formal provability + Assignment is difficult to reason about + Not very relevant to Python + Modularity + Small functions that do one thing + Debuggability: + Easy to test due to lack of state + Easy to verify output from intermediate steps + Composability + You assemble a toolbox of functions that can be mixed + + Tackling a problem + Need a significant example + + Iterators + Generators + The itertools module + List comprehensions + Small functions and the lambda statement + Built-in functions + map + filter + reduce + +.. comment + + Handy little function for printing part of an iterator -- used + while writing this document. + + import itertools + def print_iter(it): + slice = itertools.islice(it, 10) + for elem in slice[:-1]: + sys.stdout.write(str(elem)) + sys.stdout.write(', ') + print elem[-1] + + Added: doctools/trunk/Doc-26/howto/index.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-26/howto/index.rst Thu Aug 2 23:31:34 2007 @@ -0,0 +1,24 @@ +*************** + Python HOWTOs +*************** + +Python HOWTOs are documents that cover a single, specific topic, +and attempt to cover it fairly completely. Modelled on the Linux +Documentation Project's HOWTO collection, this collection is an +effort to foster documentation that's more detailed than the +Python Library Reference. + +Currently, the HOWTOs are: + +.. toctree:: + :maxdepth: 1 + + advocacy.rst + curses.rst + doanddont.rst + functional.rst + regex.rst + sockets.rst + unicode.rst + urllib2.rst + Added: doctools/trunk/Doc-26/howto/regex.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-26/howto/regex.rst Thu Aug 2 23:31:34 2007 @@ -0,0 +1,1377 @@ +**************************** + Regular Expression HOWTO +**************************** + +:Author: A.M. Kuchling +:Release: 0.05 + +.. % TODO: +.. % Document lookbehind assertions +.. % Better way of displaying a RE, a string, and what it matches +.. % Mention optional argument to match.groups() +.. % Unicode (at least a reference) + + +.. topic:: Abstract + + This document is an introductory tutorial to using regular expressions in Python + with the :mod:`re` module. It provides a gentler introduction than the + corresponding section in the Library Reference. + + +Introduction +============ + +The :mod:`re` module was added in Python 1.5, and provides Perl-style regular +expression patterns. Earlier versions of Python came with the :mod:`regex` +module, which provided Emacs-style patterns. The :mod:`regex` module was +removed completely in Python 2.5. + +Regular expressions (called REs, or regexes, or regex patterns) are essentially +a tiny, highly specialized programming language embedded inside Python and made +available through the :mod:`re` module. Using this little language, you specify +the rules for the set of possible strings that you want to match; this set might +contain English sentences, or e-mail addresses, or TeX commands, or anything you +like. You can then ask questions such as "Does this string match the pattern?", +or "Is there a match for the pattern anywhere in this string?". You can also +use REs to modify a string or to split it apart in various ways. + +Regular expression patterns are compiled into a series of bytecodes which are +then executed by a matching engine written in C. For advanced use, it may be +necessary to pay careful attention to how the engine will execute a given RE, +and write the RE in a certain way in order to produce bytecode that runs faster. +Optimization isn't covered in this document, because it requires that you have a +good understanding of the matching engine's internals. + +The regular expression language is relatively small and restricted, so not all +possible string processing tasks can be done using regular expressions. There +are also tasks that *can* be done with regular expressions, but the expressions +turn out to be very complicated. In these cases, you may be better off writing +Python code to do the processing; while Python code will be slower than an +elaborate regular expression, it will also probably be more understandable. + + +Simple Patterns +=============== + +We'll start by learning about the simplest possible regular expressions. Since +regular expressions are used to operate on strings, we'll begin with the most +common task: matching characters. + +For a detailed explanation of the computer science underlying regular +expressions (deterministic and non-deterministic finite automata), you can refer +to almost any textbook on writing compilers. + + +Matching Characters +------------------- + +Most letters and characters will simply match themselves. For example, the +regular expression ``test`` will match the string ``test`` exactly. (You can +enable a case-insensitive mode that would let this RE match ``Test`` or ``TEST`` +as well; more about this later.) + +There are exceptions to this rule; some characters are special +:dfn:`metacharacters`, and don't match themselves. Instead, they signal that +some out-of-the-ordinary thing should be matched, or they affect other portions +of the RE by repeating them or changing their meaning. Much of this document is +devoted to discussing various metacharacters and what they do. + +Here's a complete list of the metacharacters; their meanings will be discussed +in the rest of this HOWTO. :: + + . ^ $ * + ? { [ ] \ | ( ) + +The first metacharacters we'll look at are ``[`` and ``]``. They're used for +specifying a character class, which is a set of characters that you wish to +match. Characters can be listed individually, or a range of characters can be +indicated by giving two characters and separating them by a ``'-'``. For +example, ``[abc]`` will match any of the characters ``a``, ``b``, or ``c``; this +is the same as ``[a-c]``, which uses a range to express the same set of +characters. If you wanted to match only lowercase letters, your RE would be +``[a-z]``. + +.. % $ + +Metacharacters are not active inside classes. For example, ``[akm$]`` will +match any of the characters ``'a'``, ``'k'``, ``'m'``, or ``'$'``; ``'$'`` is +usually a metacharacter, but inside a character class it's stripped of its +special nature. + +You can match the characters not listed within the class by :dfn:`complementing` +the set. This is indicated by including a ``'^'`` as the first character of the +class; ``'^'`` outside a character class will simply match the ``'^'`` +character. For example, ``[^5]`` will match any character except ``'5'``. + +Perhaps the most important metacharacter is the backslash, ``\``. As in Python +string literals, the backslash can be followed by various characters to signal +various special sequences. It's also used to escape all the metacharacters so +you can still match them in patterns; for example, if you need to match a ``[`` +or ``\``, you can precede them with a backslash to remove their special +meaning: ``\[`` or ``\\``. + +Some of the special sequences beginning with ``'\'`` represent predefined sets +of characters that are often useful, such as the set of digits, the set of +letters, or the set of anything that isn't whitespace. The following predefined +special sequences are available: + +``\d`` + Matches any decimal digit; this is equivalent to the class ``[0-9]``. + +``\D`` + Matches any non-digit character; this is equivalent to the class ``[^0-9]``. + +``\s`` + Matches any whitespace character; this is equivalent to the class ``[ + \t\n\r\f\v]``. + +``\S`` + Matches any non-whitespace character; this is equivalent to the class ``[^ + \t\n\r\f\v]``. + +``\w`` + Matches any alphanumeric character; this is equivalent to the class + ``[a-zA-Z0-9_]``. + +``\W`` + Matches any non-alphanumeric character; this is equivalent to the class + ``[^a-zA-Z0-9_]``. + +These sequences can be included inside a character class. For example, +``[\s,.]`` is a character class that will match any whitespace character, or +``','`` or ``'.'``. + +The final metacharacter in this section is ``.``. It matches anything except a +newline character, and there's an alternate mode (``re.DOTALL``) where it will +match even a newline. ``'.'`` is often used where you want to match "any +character". + + +Repeating Things +---------------- + +Being able to match varying sets of characters is the first thing regular +expressions can do that isn't already possible with the methods available on +strings. However, if that was the only additional capability of regexes, they +wouldn't be much of an advance. Another capability is that you can specify that +portions of the RE must be repeated a certain number of times. + +The first metacharacter for repeating things that we'll look at is ``*``. ``*`` +doesn't match the literal character ``*``; instead, it specifies that the +previous character can be matched zero or more times, instead of exactly once. + +For example, ``ca*t`` will match ``ct`` (0 ``a`` characters), ``cat`` (1 ``a``), +``caaat`` (3 ``a`` characters), and so forth. The RE engine has various +internal limitations stemming from the size of C's ``int`` type that will +prevent it from matching over 2 billion ``a`` characters; you probably don't +have enough memory to construct a string that large, so you shouldn't run into +that limit. + +Repetitions such as ``*`` are :dfn:`greedy`; when repeating a RE, the matching +engine will try to repeat it as many times as possible. If later portions of the +pattern don't match, the matching engine will then back up and try again with +few repetitions. + +A step-by-step example will make this more obvious. Let's consider the +expression ``a[bcd]*b``. This matches the letter ``'a'``, zero or more letters +from the class ``[bcd]``, and finally ends with a ``'b'``. Now imagine matching +this RE against the string ``abcbd``. + ++------+-----------+---------------------------------+ +| Step | Matched | Explanation | ++======+===========+=================================+ +| 1 | ``a`` | The ``a`` in the RE matches. | ++------+-----------+---------------------------------+ +| 2 | ``abcbd`` | The engine matches ``[bcd]*``, | +| | | going as far as it can, which | +| | | is to the end of the string. | ++------+-----------+---------------------------------+ +| 3 | *Failure* | The engine tries to match | +| | | ``b``, but the current position | +| | | is at the end of the string, so | +| | | it fails. | ++------+-----------+---------------------------------+ +| 4 | ``abcb`` | Back up, so that ``[bcd]*`` | +| | | matches one less character. | ++------+-----------+---------------------------------+ +| 5 | *Failure* | Try ``b`` again, but the | +| | | current position is at the last | +| | | character, which is a ``'d'``. | ++------+-----------+---------------------------------+ +| 6 | ``abc`` | Back up again, so that | +| | | ``[bcd]*`` is only matching | +| | | ``bc``. | ++------+-----------+---------------------------------+ +| 6 | ``abcb`` | Try ``b`` again. This time | +| | | but the character at the | +| | | current position is ``'b'``, so | +| | | it succeeds. | ++------+-----------+---------------------------------+ + +The end of the RE has now been reached, and it has matched ``abcb``. This +demonstrates how the matching engine goes as far as it can at first, and if no +match is found it will then progressively back up and retry the rest of the RE +again and again. It will back up until it has tried zero matches for +``[bcd]*``, and if that subsequently fails, the engine will conclude that the +string doesn't match the RE at all. + +Another repeating metacharacter is ``+``, which matches one or more times. Pay +careful attention to the difference between ``*`` and ``+``; ``*`` matches +*zero* or more times, so whatever's being repeated may not be present at all, +while ``+`` requires at least *one* occurrence. To use a similar example, +``ca+t`` will match ``cat`` (1 ``a``), ``caaat`` (3 ``a``'s), but won't match +``ct``. + +There are two more repeating qualifiers. The question mark character, ``?``, +matches either once or zero times; you can think of it as marking something as +being optional. For example, ``home-?brew`` matches either ``homebrew`` or +``home-brew``. + +The most complicated repeated qualifier is ``{m,n}``, where *m* and *n* are +decimal integers. This qualifier means there must be at least *m* repetitions, +and at most *n*. For example, ``a/{1,3}b`` will match ``a/b``, ``a//b``, and +``a///b``. It won't match ``ab``, which has no slashes, or ``a////b``, which +has four. + +You can omit either *m* or *n*; in that case, a reasonable value is assumed for +the missing value. Omitting *m* is interpreted as a lower limit of 0, while +omitting *n* results in an upper bound of infinity --- actually, the upper bound +is the 2-billion limit mentioned earlier, but that might as well be infinity. + +Readers of a reductionist bent may notice that the three other qualifiers can +all be expressed using this notation. ``{0,}`` is the same as ``*``, ``{1,}`` +is equivalent to ``+``, and ``{0,1}`` is the same as ``?``. It's better to use +``*``, ``+``, or ``?`` when you can, simply because they're shorter and easier +to read. + + +Using Regular Expressions +========================= + +Now that we've looked at some simple regular expressions, how do we actually use +them in Python? The :mod:`re` module provides an interface to the regular +expression engine, allowing you to compile REs into objects and then perform +matches with them. + + +Compiling Regular Expressions +----------------------------- + +Regular expressions are compiled into :class:`RegexObject` instances, which have +methods for various operations such as searching for pattern matches or +performing string substitutions. :: + + >>> import re + >>> p = re.compile('ab*') + >>> print p + + +:func:`re.compile` also accepts an optional *flags* argument, used to enable +various special features and syntax variations. We'll go over the available +settings later, but for now a single example will do:: + + >>> p = re.compile('ab*', re.IGNORECASE) + +The RE is passed to :func:`re.compile` as a string. REs are handled as strings +because regular expressions aren't part of the core Python language, and no +special syntax was created for expressing them. (There are applications that +don't need REs at all, so there's no need to bloat the language specification by +including them.) Instead, the :mod:`re` module is simply a C extension module +included with Python, just like the :mod:`socket` or :mod:`zlib` modules. + +Putting REs in strings keeps the Python language simpler, but has one +disadvantage which is the topic of the next section. + + +The Backslash Plague +-------------------- + +As stated earlier, regular expressions use the backslash character (``'\'``) to +indicate special forms or to allow special characters to be used without +invoking their special meaning. This conflicts with Python's usage of the same +character for the same purpose in string literals. + +Let's say you want to write a RE that matches the string ``\section``, which +might be found in a LaTeX file. To figure out what to write in the program +code, start with the desired string to be matched. Next, you must escape any +backslashes and other metacharacters by preceding them with a backslash, +resulting in the string ``\\section``. The resulting string that must be passed +to :func:`re.compile` must be ``\\section``. However, to express this as a +Python string literal, both backslashes must be escaped *again*. + ++-------------------+------------------------------------------+ +| Characters | Stage | ++===================+==========================================+ +| ``\section`` | Text string to be matched | ++-------------------+------------------------------------------+ +| ``\\section`` | Escaped backslash for :func:`re.compile` | ++-------------------+------------------------------------------+ +| ``"\\\\section"`` | Escaped backslashes for a string literal | ++-------------------+------------------------------------------+ + +In short, to match a literal backslash, one has to write ``'\\\\'`` as the RE +string, because the regular expression must be ``\\``, and each backslash must +be expressed as ``\\`` inside a regular Python string literal. In REs that +feature backslashes repeatedly, this leads to lots of repeated backslashes and +makes the resulting strings difficult to understand. + +The solution is to use Python's raw string notation for regular expressions; +backslashes are not handled in any special way in a string literal prefixed with +``'r'``, so ``r"\n"`` is a two-character string containing ``'\'`` and ``'n'``, +while ``"\n"`` is a one-character string containing a newline. Regular +expressions will often be written in Python code using this raw string notation. + ++-------------------+------------------+ +| Regular String | Raw string | ++===================+==================+ +| ``"ab*"`` | ``r"ab*"`` | ++-------------------+------------------+ +| ``"\\\\section"`` | ``r"\\section"`` | ++-------------------+------------------+ +| ``"\\w+\\s+\\1"`` | ``r"\w+\s+\1"`` | ++-------------------+------------------+ + + +Performing Matches +------------------ + +Once you have an object representing a compiled regular expression, what do you +do with it? :class:`RegexObject` instances have several methods and attributes. +Only the most significant ones will be covered here; consult `the Library +Reference `_ for a complete +listing. + ++------------------+-----------------------------------------------+ +| Method/Attribute | Purpose | ++==================+===============================================+ +| ``match()`` | Determine if the RE matches at the beginning | +| | of the string. | ++------------------+-----------------------------------------------+ +| ``search()`` | Scan through a string, looking for any | +| | location where this RE matches. | ++------------------+-----------------------------------------------+ +| ``findall()`` | Find all substrings where the RE matches, and | +| | returns them as a list. | ++------------------+-----------------------------------------------+ +| ``finditer()`` | Find all substrings where the RE matches, and | +| | returns them as an iterator. | ++------------------+-----------------------------------------------+ + +:meth:`match` and :meth:`search` return ``None`` if no match can be found. If +they're successful, a ``MatchObject`` instance is returned, containing +information about the match: where it starts and ends, the substring it matched, +and more. + +You can learn about this by interactively experimenting with the :mod:`re` +module. If you have Tkinter available, you may also want to look at +:file:`Tools/scripts/redemo.py`, a demonstration program included with the +Python distribution. It allows you to enter REs and strings, and displays +whether the RE matches or fails. :file:`redemo.py` can be quite useful when +trying to debug a complicated RE. Phil Schwartz's `Kodos `_ is also an interactive tool for developing and testing +RE patterns. + +This HOWTO uses the standard Python interpreter for its examples. First, run the +Python interpreter, import the :mod:`re` module, and compile a RE:: + + Python 2.2.2 (#1, Feb 10 2003, 12:57:01) + >>> import re + >>> p = re.compile('[a-z]+') + >>> p + <_sre.SRE_Pattern object at 80c3c28> + +Now, you can try matching various strings against the RE ``[a-z]+``. An empty +string shouldn't match at all, since ``+`` means 'one or more repetitions'. +:meth:`match` should return ``None`` in this case, which will cause the +interpreter to print no output. You can explicitly print the result of +:meth:`match` to make this clear. :: + + >>> p.match("") + >>> print p.match("") + None + +Now, let's try it on a string that it should match, such as ``tempo``. In this +case, :meth:`match` will return a :class:`MatchObject`, so you should store the +result in a variable for later use. :: + + >>> m = p.match('tempo') + >>> print m + <_sre.SRE_Match object at 80c4f68> + +Now you can query the :class:`MatchObject` for information about the matching +string. :class:`MatchObject` instances also have several methods and +attributes; the most important ones are: + ++------------------+--------------------------------------------+ +| Method/Attribute | Purpose | ++==================+============================================+ +| ``group()`` | Return the string matched by the RE | ++------------------+--------------------------------------------+ +| ``start()`` | Return the starting position of the match | ++------------------+--------------------------------------------+ +| ``end()`` | Return the ending position of the match | ++------------------+--------------------------------------------+ +| ``span()`` | Return a tuple containing the (start, end) | +| | positions of the match | ++------------------+--------------------------------------------+ + +Trying these methods will soon clarify their meaning:: + + >>> m.group() + 'tempo' + >>> m.start(), m.end() + (0, 5) + >>> m.span() + (0, 5) + +:meth:`group` returns the substring that was matched by the RE. :meth:`start` +and :meth:`end` return the starting and ending index of the match. :meth:`span` +returns both start and end indexes in a single tuple. Since the :meth:`match` +method only checks if the RE matches at the start of a string, :meth:`start` +will always be zero. However, the :meth:`search` method of :class:`RegexObject` +instances scans through the string, so the match may not start at zero in that +case. :: + + >>> print p.match('::: message') + None + >>> m = p.search('::: message') ; print m + + >>> m.group() + 'message' + >>> m.span() + (4, 11) + +In actual programs, the most common style is to store the :class:`MatchObject` +in a variable, and then check if it was ``None``. This usually looks like:: + + p = re.compile( ... ) + m = p.match( 'string goes here' ) + if m: + print 'Match found: ', m.group() + else: + print 'No match' + +Two :class:`RegexObject` methods return all of the matches for a pattern. +:meth:`findall` returns a list of matching strings:: + + >>> p = re.compile('\d+') + >>> p.findall('12 drummers drumming, 11 pipers piping, 10 lords a-leaping') + ['12', '11', '10'] + +:meth:`findall` has to create the entire list before it can be returned as the +result. The :meth:`finditer` method returns a sequence of :class:`MatchObject` +instances as an iterator. [#]_ :: + + >>> iterator = p.finditer('12 drummers drumming, 11 ... 10 ...') + >>> iterator + + >>> for match in iterator: + ... print match.span() + ... + (0, 2) + (22, 24) + (29, 31) + + +Module-Level Functions +---------------------- + +You don't have to create a :class:`RegexObject` and call its methods; the +:mod:`re` module also provides top-level functions called :func:`match`, +:func:`search`, :func:`findall`, :func:`sub`, and so forth. These functions +take the same arguments as the corresponding :class:`RegexObject` method, with +the RE string added as the first argument, and still return either ``None`` or a +:class:`MatchObject` instance. :: + + >>> print re.match(r'From\s+', 'Fromage amk') + None + >>> re.match(r'From\s+', 'From amk Thu May 14 19:12:10 1998') + + +Under the hood, these functions simply produce a :class:`RegexObject` for you +and call the appropriate method on it. They also store the compiled object in a +cache, so future calls using the same RE are faster. + +Should you use these module-level functions, or should you get the +:class:`RegexObject` and call its methods yourself? That choice depends on how +frequently the RE will be used, and on your personal coding style. If the RE is +being used at only one point in the code, then the module functions are probably +more convenient. If a program contains a lot of regular expressions, or re-uses +the same ones in several locations, then it might be worthwhile to collect all +the definitions in one place, in a section of code that compiles all the REs +ahead of time. To take an example from the standard library, here's an extract +from :file:`xmllib.py`:: + + ref = re.compile( ... ) + entityref = re.compile( ... ) + charref = re.compile( ... ) + starttagopen = re.compile( ... ) + +I generally prefer to work with the compiled object, even for one-time uses, but +few people will be as much of a purist about this as I am. + + +Compilation Flags +----------------- + +Compilation flags let you modify some aspects of how regular expressions work. +Flags are available in the :mod:`re` module under two names, a long name such as +:const:`IGNORECASE` and a short, one-letter form such as :const:`I`. (If you're +familiar with Perl's pattern modifiers, the one-letter forms use the same +letters; the short form of :const:`re.VERBOSE` is :const:`re.X`, for example.) +Multiple flags can be specified by bitwise OR-ing them; ``re.I | re.M`` sets +both the :const:`I` and :const:`M` flags, for example. + +Here's a table of the available flags, followed by a more detailed explanation +of each one. + ++---------------------------------+--------------------------------------------+ +| Flag | Meaning | ++=================================+============================================+ +| :const:`DOTALL`, :const:`S` | Make ``.`` match any character, including | +| | newlines | ++---------------------------------+--------------------------------------------+ +| :const:`IGNORECASE`, :const:`I` | Do case-insensitive matches | ++---------------------------------+--------------------------------------------+ +| :const:`LOCALE`, :const:`L` | Do a locale-aware match | ++---------------------------------+--------------------------------------------+ +| :const:`MULTILINE`, :const:`M` | Multi-line matching, affecting ``^`` and | +| | ``$`` | ++---------------------------------+--------------------------------------------+ +| :const:`VERBOSE`, :const:`X` | Enable verbose REs, which can be organized | +| | more cleanly and understandably. | ++---------------------------------+--------------------------------------------+ + + +.. data:: I + IGNORECASE + :noindex: + + Perform case-insensitive matching; character class and literal strings will + match letters by ignoring case. For example, ``[A-Z]`` will match lowercase + letters, too, and ``Spam`` will match ``Spam``, ``spam``, or ``spAM``. This + lowercasing doesn't take the current locale into account; it will if you also + set the :const:`LOCALE` flag. + + +.. data:: L + LOCALE + :noindex: + + Make ``\w``, ``\W``, ``\b``, and ``\B``, dependent on the current locale. + + Locales are a feature of the C library intended to help in writing programs that + take account of language differences. For example, if you're processing French + text, you'd want to be able to write ``\w+`` to match words, but ``\w`` only + matches the character class ``[A-Za-z]``; it won't match ``'?'`` or ``'?'``. If + your system is configured properly and a French locale is selected, certain C + functions will tell the program that ``'?'`` should also be considered a letter. + Setting the :const:`LOCALE` flag when compiling a regular expression will cause + the resulting compiled object to use these C functions for ``\w``; this is + slower, but also enables ``\w+`` to match French words as you'd expect. + + +.. data:: M + MULTILINE + :noindex: + + (``^`` and ``$`` haven't been explained yet; they'll be introduced in section + :ref:`more-metacharacters`.) + + Usually ``^`` matches only at the beginning of the string, and ``$`` matches + only at the end of the string and immediately before the newline (if any) at the + end of the string. When this flag is specified, ``^`` matches at the beginning + of the string and at the beginning of each line within the string, immediately + following each newline. Similarly, the ``$`` metacharacter matches either at + the end of the string and at the end of each line (immediately preceding each + newline). + + +.. data:: S + DOTALL + :noindex: + + Makes the ``'.'`` special character match any character at all, including a + newline; without this flag, ``'.'`` will match anything *except* a newline. + + +.. data:: X + VERBOSE + :noindex: + + This flag allows you to write regular expressions that are more readable by + granting you more flexibility in how you can format them. When this flag has + been specified, whitespace within the RE string is ignored, except when the + whitespace is in a character class or preceded by an unescaped backslash; this + lets you organize and indent the RE more clearly. This flag also lets you put + comments within a RE that will be ignored by the engine; comments are marked by + a ``'#'`` that's neither in a character class or preceded by an unescaped + backslash. + + For example, here's a RE that uses :const:`re.VERBOSE`; see how much easier it + is to read? :: + + charref = re.compile(r""" + &[#] # Start of a numeric entity reference + ( + 0[0-7]+ # Octal form + | [0-9]+ # Decimal form + | x[0-9a-fA-F]+ # Hexadecimal form + ) + ; # Trailing semicolon + """, re.VERBOSE) + + Without the verbose setting, the RE would look like this:: + + charref = re.compile("&#(0[0-7]+" + "|[0-9]+" + "|x[0-9a-fA-F]+);") + + In the above example, Python's automatic concatenation of string literals has + been used to break up the RE into smaller pieces, but it's still more difficult + to understand than the version using :const:`re.VERBOSE`. + + +More Pattern Power +================== + +So far we've only covered a part of the features of regular expressions. In +this section, we'll cover some new metacharacters, and how to use groups to +retrieve portions of the text that was matched. + + +.. _more-metacharacters: + +More Metacharacters +------------------- + +There are some metacharacters that we haven't covered yet. Most of them will be +covered in this section. + +Some of the remaining metacharacters to be discussed are :dfn:`zero-width +assertions`. They don't cause the engine to advance through the string; +instead, they consume no characters at all, and simply succeed or fail. For +example, ``\b`` is an assertion that the current position is located at a word +boundary; the position isn't changed by the ``\b`` at all. This means that +zero-width assertions should never be repeated, because if they match once at a +given location, they can obviously be matched an infinite number of times. + +``|`` + Alternation, or the "or" operator. If A and B are regular expressions, + ``A|B`` will match any string that matches either ``A`` or ``B``. ``|`` has very + low precedence in order to make it work reasonably when you're alternating + multi-character strings. ``Crow|Servo`` will match either ``Crow`` or ``Servo``, + not ``Cro``, a ``'w'`` or an ``'S'``, and ``ervo``. + + To match a literal ``'|'``, use ``\|``, or enclose it inside a character class, + as in ``[|]``. + +``^`` + Matches at the beginning of lines. Unless the :const:`MULTILINE` flag has been + set, this will only match at the beginning of the string. In :const:`MULTILINE` + mode, this also matches immediately after each newline within the string. + + For example, if you wish to match the word ``From`` only at the beginning of a + line, the RE to use is ``^From``. :: + + >>> print re.search('^From', 'From Here to Eternity') + + >>> print re.search('^From', 'Reciting From Memory') + None + + .. % To match a literal \character{\^}, use \regexp{\e\^} or enclose it + .. % inside a character class, as in \regexp{[{\e}\^]}. + +``$`` + Matches at the end of a line, which is defined as either the end of the string, + or any location followed by a newline character. :: + + >>> print re.search('}$', '{block}') + + >>> print re.search('}$', '{block} ') + None + >>> print re.search('}$', '{block}\n') + + + To match a literal ``'$'``, use ``\$`` or enclose it inside a character class, + as in ``[$]``. + + .. % $ + +``\A`` + Matches only at the start of the string. When not in :const:`MULTILINE` mode, + ``\A`` and ``^`` are effectively the same. In :const:`MULTILINE` mode, they're + different: ``\A`` still matches only at the beginning of the string, but ``^`` + may match at any location inside the string that follows a newline character. + +``\Z`` + Matches only at the end of the string. + +``\b`` + Word boundary. This is a zero-width assertion that matches only at the + beginning or end of a word. A word is defined as a sequence of alphanumeric + characters, so the end of a word is indicated by whitespace or a non- + alphanumeric character. + + The following example matches ``class`` only when it's a complete word; it won't + match when it's contained inside another word. :: + + >>> p = re.compile(r'\bclass\b') + >>> print p.search('no class at all') + + >>> print p.search('the declassified algorithm') + None + >>> print p.search('one subclass is') + None + + There are two subtleties you should remember when using this special sequence. + First, this is the worst collision between Python's string literals and regular + expression sequences. In Python's string literals, ``\b`` is the backspace + character, ASCII value 8. If you're not using raw strings, then Python will + convert the ``\b`` to a backspace, and your RE won't match as you expect it to. + The following example looks the same as our previous RE, but omits the ``'r'`` + in front of the RE string. :: + + >>> p = re.compile('\bclass\b') + >>> print p.search('no class at all') + None + >>> print p.search('\b' + 'class' + '\b') + + + Second, inside a character class, where there's no use for this assertion, + ``\b`` represents the backspace character, for compatibility with Python's + string literals. + +``\B`` + Another zero-width assertion, this is the opposite of ``\b``, only matching when + the current position is not at a word boundary. + + +Grouping +-------- + +Frequently you need to obtain more information than just whether the RE matched +or not. Regular expressions are often used to dissect strings by writing a RE +divided into several subgroups which match different components of interest. +For example, an RFC-822 header line is divided into a header name and a value, +separated by a ``':'``, like this:: + + From: author at example.com + User-Agent: Thunderbird 1.5.0.9 (X11/20061227) + MIME-Version: 1.0 + To: editor at example.com + +This can be handled by writing a regular expression which matches an entire +header line, and has one group which matches the header name, and another group +which matches the header's value. + +Groups are marked by the ``'('``, ``')'`` metacharacters. ``'('`` and ``')'`` +have much the same meaning as they do in mathematical expressions; they group +together the expressions contained inside them, and you can repeat the contents +of a group with a repeating qualifier, such as ``*``, ``+``, ``?``, or +``{m,n}``. For example, ``(ab)*`` will match zero or more repetitions of +``ab``. :: + + >>> p = re.compile('(ab)*') + >>> print p.match('ababababab').span() + (0, 10) + +Groups indicated with ``'('``, ``')'`` also capture the starting and ending +index of the text that they match; this can be retrieved by passing an argument +to :meth:`group`, :meth:`start`, :meth:`end`, and :meth:`span`. Groups are +numbered starting with 0. Group 0 is always present; it's the whole RE, so +:class:`MatchObject` methods all have group 0 as their default argument. Later +we'll see how to express groups that don't capture the span of text that they +match. :: + + >>> p = re.compile('(a)b') + >>> m = p.match('ab') + >>> m.group() + 'ab' + >>> m.group(0) + 'ab' + +Subgroups are numbered from left to right, from 1 upward. Groups can be nested; +to determine the number, just count the opening parenthesis characters, going +from left to right. :: + + >>> p = re.compile('(a(b)c)d') + >>> m = p.match('abcd') + >>> m.group(0) + 'abcd' + >>> m.group(1) + 'abc' + >>> m.group(2) + 'b' + +:meth:`group` can be passed multiple group numbers at a time, in which case it +will return a tuple containing the corresponding values for those groups. :: + + >>> m.group(2,1,2) + ('b', 'abc', 'b') + +The :meth:`groups` method returns a tuple containing the strings for all the +subgroups, from 1 up to however many there are. :: + + >>> m.groups() + ('abc', 'b') + +Backreferences in a pattern allow you to specify that the contents of an earlier +capturing group must also be found at the current location in the string. For +example, ``\1`` will succeed if the exact contents of group 1 can be found at +the current position, and fails otherwise. Remember that Python's string +literals also use a backslash followed by numbers to allow including arbitrary +characters in a string, so be sure to use a raw string when incorporating +backreferences in a RE. + +For example, the following RE detects doubled words in a string. :: + + >>> p = re.compile(r'(\b\w+)\s+\1') + >>> p.search('Paris in the the spring').group() + 'the the' + +Backreferences like this aren't often useful for just searching through a string +--- there are few text formats which repeat data in this way --- but you'll soon +find out that they're *very* useful when performing string substitutions. + + +Non-capturing and Named Groups +------------------------------ + +Elaborate REs may use many groups, both to capture substrings of interest, and +to group and structure the RE itself. In complex REs, it becomes difficult to +keep track of the group numbers. There are two features which help with this +problem. Both of them use a common syntax for regular expression extensions, so +we'll look at that first. + +Perl 5 added several additional features to standard regular expressions, and +the Python :mod:`re` module supports most of them. It would have been +difficult to choose new single-keystroke metacharacters or new special sequences +beginning with ``\`` to represent the new features without making Perl's regular +expressions confusingly different from standard REs. If you chose ``&`` as a +new metacharacter, for example, old expressions would be assuming that ``&`` was +a regular character and wouldn't have escaped it by writing ``\&`` or ``[&]``. + +The solution chosen by the Perl developers was to use ``(?...)`` as the +extension syntax. ``?`` immediately after a parenthesis was a syntax error +because the ``?`` would have nothing to repeat, so this didn't introduce any +compatibility problems. The characters immediately after the ``?`` indicate +what extension is being used, so ``(?=foo)`` is one thing (a positive lookahead +assertion) and ``(?:foo)`` is something else (a non-capturing group containing +the subexpression ``foo``). + +Python adds an extension syntax to Perl's extension syntax. If the first +character after the question mark is a ``P``, you know that it's an extension +that's specific to Python. Currently there are two such extensions: +``(?P...)`` defines a named group, and ``(?P=name)`` is a backreference to +a named group. If future versions of Perl 5 add similar features using a +different syntax, the :mod:`re` module will be changed to support the new +syntax, while preserving the Python-specific syntax for compatibility's sake. + +Now that we've looked at the general extension syntax, we can return to the +features that simplify working with groups in complex REs. Since groups are +numbered from left to right and a complex expression may use many groups, it can +become difficult to keep track of the correct numbering. Modifying such a +complex RE is annoying, too: insert a new group near the beginning and you +change the numbers of everything that follows it. + +Sometimes you'll want to use a group to collect a part of a regular expression, +but aren't interested in retrieving the group's contents. You can make this fact +explicit by using a non-capturing group: ``(?:...)``, where you can replace the +``...`` with any other regular expression. :: + + >>> m = re.match("([abc])+", "abc") + >>> m.groups() + ('c',) + >>> m = re.match("(?:[abc])+", "abc") + >>> m.groups() + () + +Except for the fact that you can't retrieve the contents of what the group +matched, a non-capturing group behaves exactly the same as a capturing group; +you can put anything inside it, repeat it with a repetition metacharacter such +as ``*``, and nest it within other groups (capturing or non-capturing). +``(?:...)`` is particularly useful when modifying an existing pattern, since you +can add new groups without changing how all the other groups are numbered. It +should be mentioned that there's no performance difference in searching between +capturing and non-capturing groups; neither form is any faster than the other. + +A more significant feature is named groups: instead of referring to them by +numbers, groups can be referenced by a name. + +The syntax for a named group is one of the Python-specific extensions: +``(?P...)``. *name* is, obviously, the name of the group. Named groups +also behave exactly like capturing groups, and additionally associate a name +with a group. The :class:`MatchObject` methods that deal with capturing groups +all accept either integers that refer to the group by number or strings that +contain the desired group's name. Named groups are still given numbers, so you +can retrieve information about a group in two ways:: + + >>> p = re.compile(r'(?P\b\w+\b)') + >>> m = p.search( '(((( Lots of punctuation )))' ) + >>> m.group('word') + 'Lots' + >>> m.group(1) + 'Lots' + +Named groups are handy because they let you use easily-remembered names, instead +of having to remember numbers. Here's an example RE from the :mod:`imaplib` +module:: + + InternalDate = re.compile(r'INTERNALDATE "' + r'(?P[ 123][0-9])-(?P[A-Z][a-z][a-z])-' + r'(?P[0-9][0-9][0-9][0-9])' + r' (?P[0-9][0-9]):(?P[0-9][0-9]):(?P[0-9][0-9])' + r' (?P[-+])(?P[0-9][0-9])(?P[0-9][0-9])' + r'"') + +It's obviously much easier to retrieve ``m.group('zonem')``, instead of having +to remember to retrieve group 9. + +The syntax for backreferences in an expression such as ``(...)\1`` refers to the +number of the group. There's naturally a variant that uses the group name +instead of the number. This is another Python extension: ``(?P=name)`` indicates +that the contents of the group called *name* should again be matched at the +current point. The regular expression for finding doubled words, +``(\b\w+)\s+\1`` can also be written as ``(?P\b\w+)\s+(?P=word)``:: + + >>> p = re.compile(r'(?P\b\w+)\s+(?P=word)') + >>> p.search('Paris in the the spring').group() + 'the the' + + +Lookahead Assertions +-------------------- + +Another zero-width assertion is the lookahead assertion. Lookahead assertions +are available in both positive and negative form, and look like this: + +``(?=...)`` + Positive lookahead assertion. This succeeds if the contained regular + expression, represented here by ``...``, successfully matches at the current + location, and fails otherwise. But, once the contained expression has been + tried, the matching engine doesn't advance at all; the rest of the pattern is + tried right where the assertion started. + +``(?!...)`` + Negative lookahead assertion. This is the opposite of the positive assertion; + it succeeds if the contained expression *doesn't* match at the current position + in the string. + +To make this concrete, let's look at a case where a lookahead is useful. +Consider a simple pattern to match a filename and split it apart into a base +name and an extension, separated by a ``.``. For example, in ``news.rc``, +``news`` is the base name, and ``rc`` is the filename's extension. + +The pattern to match this is quite simple: + +``.*[.].*$`` + +Notice that the ``.`` needs to be treated specially because it's a +metacharacter; I've put it inside a character class. Also notice the trailing +``$``; this is added to ensure that all the rest of the string must be included +in the extension. This regular expression matches ``foo.bar`` and +``autoexec.bat`` and ``sendmail.cf`` and ``printers.conf``. + +Now, consider complicating the problem a bit; what if you want to match +filenames where the extension is not ``bat``? Some incorrect attempts: + +``.*[.][^b].*$`` The first attempt above tries to exclude ``bat`` by requiring +that the first character of the extension is not a ``b``. This is wrong, +because the pattern also doesn't match ``foo.bar``. + +.. % $ + +``.*[.]([^b]..|.[^a].|..[^t])$`` + +.. % Messes up the HTML without the curly braces around \^ + +The expression gets messier when you try to patch up the first solution by +requiring one of the following cases to match: the first character of the +extension isn't ``b``; the second character isn't ``a``; or the third character +isn't ``t``. This accepts ``foo.bar`` and rejects ``autoexec.bat``, but it +requires a three-letter extension and won't accept a filename with a two-letter +extension such as ``sendmail.cf``. We'll complicate the pattern again in an +effort to fix it. + +``.*[.]([^b].?.?|.[^a]?.?|..?[^t]?)$`` + +In the third attempt, the second and third letters are all made optional in +order to allow matching extensions shorter than three characters, such as +``sendmail.cf``. + +The pattern's getting really complicated now, which makes it hard to read and +understand. Worse, if the problem changes and you want to exclude both ``bat`` +and ``exe`` as extensions, the pattern would get even more complicated and +confusing. + +A negative lookahead cuts through all this confusion: + +``.*[.](?!bat$).*$`` The negative lookahead means: if the expression ``bat`` +doesn't match at this point, try the rest of the pattern; if ``bat$`` does +match, the whole pattern will fail. The trailing ``$`` is required to ensure +that something like ``sample.batch``, where the extension only starts with +``bat``, will be allowed. + +.. % $ + +Excluding another filename extension is now easy; simply add it as an +alternative inside the assertion. The following pattern excludes filenames that +end in either ``bat`` or ``exe``: + +``.*[.](?!bat$|exe$).*$`` + +.. % $ + + +Modifying Strings +================= + +Up to this point, we've simply performed searches against a static string. +Regular expressions are also commonly used to modify strings in various ways, +using the following :class:`RegexObject` methods: + ++------------------+-----------------------------------------------+ +| Method/Attribute | Purpose | ++==================+===============================================+ +| ``split()`` | Split the string into a list, splitting it | +| | wherever the RE matches | ++------------------+-----------------------------------------------+ +| ``sub()`` | Find all substrings where the RE matches, and | +| | replace them with a different string | ++------------------+-----------------------------------------------+ +| ``subn()`` | Does the same thing as :meth:`sub`, but | +| | returns the new string and the number of | +| | replacements | ++------------------+-----------------------------------------------+ + + +Splitting Strings +----------------- + +The :meth:`split` method of a :class:`RegexObject` splits a string apart +wherever the RE matches, returning a list of the pieces. It's similar to the +:meth:`split` method of strings but provides much more generality in the +delimiters that you can split by; :meth:`split` only supports splitting by +whitespace or by a fixed string. As you'd expect, there's a module-level +:func:`re.split` function, too. + + +.. method:: .split(string [, maxsplit\ ``= 0``]) + :noindex: + + Split *string* by the matches of the regular expression. If capturing + parentheses are used in the RE, then their contents will also be returned as + part of the resulting list. If *maxsplit* is nonzero, at most *maxsplit* splits + are performed. + +You can limit the number of splits made, by passing a value for *maxsplit*. +When *maxsplit* is nonzero, at most *maxsplit* splits will be made, and the +remainder of the string is returned as the final element of the list. In the +following example, the delimiter is any sequence of non-alphanumeric characters. +:: + + >>> p = re.compile(r'\W+') + >>> p.split('This is a test, short and sweet, of split().') + ['This', 'is', 'a', 'test', 'short', 'and', 'sweet', 'of', 'split', ''] + >>> p.split('This is a test, short and sweet, of split().', 3) + ['This', 'is', 'a', 'test, short and sweet, of split().'] + +Sometimes you're not only interested in what the text between delimiters is, but +also need to know what the delimiter was. If capturing parentheses are used in +the RE, then their values are also returned as part of the list. Compare the +following calls:: + + >>> p = re.compile(r'\W+') + >>> p2 = re.compile(r'(\W+)') + >>> p.split('This... is a test.') + ['This', 'is', 'a', 'test', ''] + >>> p2.split('This... is a test.') + ['This', '... ', 'is', ' ', 'a', ' ', 'test', '.', ''] + +The module-level function :func:`re.split` adds the RE to be used as the first +argument, but is otherwise the same. :: + + >>> re.split('[\W]+', 'Words, words, words.') + ['Words', 'words', 'words', ''] + >>> re.split('([\W]+)', 'Words, words, words.') + ['Words', ', ', 'words', ', ', 'words', '.', ''] + >>> re.split('[\W]+', 'Words, words, words.', 1) + ['Words', 'words, words.'] + + +Search and Replace +------------------ + +Another common task is to find all the matches for a pattern, and replace them +with a different string. The :meth:`sub` method takes a replacement value, +which can be either a string or a function, and the string to be processed. + + +.. method:: .sub(replacement, string[, count\ ``= 0``]) + :noindex: + + Returns the string obtained by replacing the leftmost non-overlapping + occurrences of the RE in *string* by the replacement *replacement*. If the + pattern isn't found, *string* is returned unchanged. + + The optional argument *count* is the maximum number of pattern occurrences to be + replaced; *count* must be a non-negative integer. The default value of 0 means + to replace all occurrences. + +Here's a simple example of using the :meth:`sub` method. It replaces colour +names with the word ``colour``:: + + >>> p = re.compile( '(blue|white|red)') + >>> p.sub( 'colour', 'blue socks and red shoes') + 'colour socks and colour shoes' + >>> p.sub( 'colour', 'blue socks and red shoes', count=1) + 'colour socks and red shoes' + +The :meth:`subn` method does the same work, but returns a 2-tuple containing the +new string value and the number of replacements that were performed:: + + >>> p = re.compile( '(blue|white|red)') + >>> p.subn( 'colour', 'blue socks and red shoes') + ('colour socks and colour shoes', 2) + >>> p.subn( 'colour', 'no colours at all') + ('no colours at all', 0) + +Empty matches are replaced only when they're not adjacent to a previous match. +:: + + >>> p = re.compile('x*') + >>> p.sub('-', 'abxd') + '-a-b-d-' + +If *replacement* is a string, any backslash escapes in it are processed. That +is, ``\n`` is converted to a single newline character, ``\r`` is converted to a +carriage return, and so forth. Unknown escapes such as ``\j`` are left alone. +Backreferences, such as ``\6``, are replaced with the substring matched by the +corresponding group in the RE. This lets you incorporate portions of the +original text in the resulting replacement string. + +This example matches the word ``section`` followed by a string enclosed in +``{``, ``}``, and changes ``section`` to ``subsection``:: + + >>> p = re.compile('section{ ( [^}]* ) }', re.VERBOSE) + >>> p.sub(r'subsection{\1}','section{First} section{second}') + 'subsection{First} subsection{second}' + +There's also a syntax for referring to named groups as defined by the +``(?P...)`` syntax. ``\g`` will use the substring matched by the +group named ``name``, and ``\g`` uses the corresponding group number. +``\g<2>`` is therefore equivalent to ``\2``, but isn't ambiguous in a +replacement string such as ``\g<2>0``. (``\20`` would be interpreted as a +reference to group 20, not a reference to group 2 followed by the literal +character ``'0'``.) The following substitutions are all equivalent, but use all +three variations of the replacement string. :: + + >>> p = re.compile('section{ (?P [^}]* ) }', re.VERBOSE) + >>> p.sub(r'subsection{\1}','section{First}') + 'subsection{First}' + >>> p.sub(r'subsection{\g<1>}','section{First}') + 'subsection{First}' + >>> p.sub(r'subsection{\g}','section{First}') + 'subsection{First}' + +*replacement* can also be a function, which gives you even more control. If +*replacement* is a function, the function is called for every non-overlapping +occurrence of *pattern*. On each call, the function is passed a +:class:`MatchObject` argument for the match and can use this information to +compute the desired replacement string and return it. + +In the following example, the replacement function translates decimals into +hexadecimal:: + + >>> def hexrepl( match ): + ... "Return the hex string for a decimal number" + ... value = int( match.group() ) + ... return hex(value) + ... + >>> p = re.compile(r'\d+') + >>> p.sub(hexrepl, 'Call 65490 for printing, 49152 for user code.') + 'Call 0xffd2 for printing, 0xc000 for user code.' + +When using the module-level :func:`re.sub` function, the pattern is passed as +the first argument. The pattern may be a string or a :class:`RegexObject`; if +you need to specify regular expression flags, you must either use a +:class:`RegexObject` as the first parameter, or use embedded modifiers in the +pattern, e.g. ``sub("(?i)b+", "x", "bbbb BBBB")`` returns ``'x x'``. + + +Common Problems +=============== + +Regular expressions are a powerful tool for some applications, but in some ways +their behaviour isn't intuitive and at times they don't behave the way you may +expect them to. This section will point out some of the most common pitfalls. + + +Use String Methods +------------------ + +Sometimes using the :mod:`re` module is a mistake. If you're matching a fixed +string, or a single character class, and you're not using any :mod:`re` features +such as the :const:`IGNORECASE` flag, then the full power of regular expressions +may not be required. Strings have several methods for performing operations with +fixed strings and they're usually much faster, because the implementation is a +single small C loop that's been optimized for the purpose, instead of the large, +more generalized regular expression engine. + +One example might be replacing a single fixed string with another one; for +example, you might replace ``word`` with ``deed``. ``re.sub()`` seems like the +function to use for this, but consider the :meth:`replace` method. Note that +:func:`replace` will also replace ``word`` inside words, turning ``swordfish`` +into ``sdeedfish``, but the naive RE ``word`` would have done that, too. (To +avoid performing the substitution on parts of words, the pattern would have to +be ``\bword\b``, in order to require that ``word`` have a word boundary on +either side. This takes the job beyond :meth:`replace`'s abilities.) + +Another common task is deleting every occurrence of a single character from a +string or replacing it with another single character. You might do this with +something like ``re.sub('\n', ' ', S)``, but :meth:`translate` is capable of +doing both tasks and will be faster than any regular expression operation can +be. + +In short, before turning to the :mod:`re` module, consider whether your problem +can be solved with a faster and simpler string method. + + +match() versus search() +----------------------- + +The :func:`match` function only checks if the RE matches at the beginning of the +string while :func:`search` will scan forward through the string for a match. +It's important to keep this distinction in mind. Remember, :func:`match` will +only report a successful match which will start at 0; if the match wouldn't +start at zero, :func:`match` will *not* report it. :: + + >>> print re.match('super', 'superstition').span() + (0, 5) + >>> print re.match('super', 'insuperable') + None + +On the other hand, :func:`search` will scan forward through the string, +reporting the first match it finds. :: + + >>> print re.search('super', 'superstition').span() + (0, 5) + >>> print re.search('super', 'insuperable').span() + (2, 7) + +Sometimes you'll be tempted to keep using :func:`re.match`, and just add ``.*`` +to the front of your RE. Resist this temptation and use :func:`re.search` +instead. The regular expression compiler does some analysis of REs in order to +speed up the process of looking for a match. One such analysis figures out what +the first character of a match must be; for example, a pattern starting with +``Crow`` must match starting with a ``'C'``. The analysis lets the engine +quickly scan through the string looking for the starting character, only trying +the full match if a ``'C'`` is found. + +Adding ``.*`` defeats this optimization, requiring scanning to the end of the +string and then backtracking to find a match for the rest of the RE. Use +:func:`re.search` instead. + + +Greedy versus Non-Greedy +------------------------ + +When repeating a regular expression, as in ``a*``, the resulting action is to +consume as much of the pattern as possible. This fact often bites you when +you're trying to match a pair of balanced delimiters, such as the angle brackets +surrounding an HTML tag. The naive pattern for matching a single HTML tag +doesn't work because of the greedy nature of ``.*``. :: + + >>> s = 'Title' + >>> len(s) + 32 + >>> print re.match('<.*>', s).span() + (0, 32) + >>> print re.match('<.*>', s).group() + Title + +The RE matches the ``'<'`` in ````, and the ``.*`` consumes the rest of +the string. There's still more left in the RE, though, and the ``>`` can't +match at the end of the string, so the regular expression engine has to +backtrack character by character until it finds a match for the ``>``. The +final match extends from the ``'<'`` in ```` to the ``'>'`` in +````, which isn't what you want. + +In this case, the solution is to use the non-greedy qualifiers ``*?``, ``+?``, +``??``, or ``{m,n}?``, which match as *little* text as possible. In the above +example, the ``'>'`` is tried immediately after the first ``'<'`` matches, and +when it fails, the engine advances a character at a time, retrying the ``'>'`` +at every step. This produces just the right result:: + + >>> print re.match('<.*?>', s).group() + + +(Note that parsing HTML or XML with regular expressions is painful. Quick-and- +dirty patterns will handle common cases, but HTML and XML have special cases +that will break the obvious regular expression; by the time you've written a +regular expression that handles all of the possible cases, the patterns will be +*very* complicated. Use an HTML or XML parser module for such tasks.) + + +Not Using re.VERBOSE +-------------------- + +By now you've probably noticed that regular expressions are a very compact +notation, but they're not terribly readable. REs of moderate complexity can +become lengthy collections of backslashes, parentheses, and metacharacters, +making them difficult to read and understand. + +For such REs, specifying the ``re.VERBOSE`` flag when compiling the regular +expression can be helpful, because it allows you to format the regular +expression more clearly. + +The ``re.VERBOSE`` flag has several effects. Whitespace in the regular +expression that *isn't* inside a character class is ignored. This means that an +expression such as ``dog | cat`` is equivalent to the less readable ``dog|cat``, +but ``[a b]`` will still match the characters ``'a'``, ``'b'``, or a space. In +addition, you can also put comments inside a RE; comments extend from a ``#`` +character to the next newline. When used with triple-quoted strings, this +enables REs to be formatted more neatly:: + + pat = re.compile(r""" + \s* # Skip leading whitespace + (?P
      [^:]+) # Header name + \s* : # Whitespace, and a colon + (?P.*?) # The header's value -- *? used to + # lose the following trailing whitespace + \s*$ # Trailing whitespace to end-of-line + """, re.VERBOSE) + +This is far more readable than: + +.. % $ + +:: + + pat = re.compile(r"\s*(?P
      [^:]+)\s*:(?P.*?)\s*$") + +.. % $ + + +Feedback +======== + +Regular expressions are a complicated topic. Did this document help you +understand them? Were there parts that were unclear, or Problems you +encountered that weren't covered here? If so, please send suggestions for +improvements to the author. + +The most complete book on regular expressions is almost certainly Jeffrey +Friedl's Mastering Regular Expressions, published by O'Reilly. Unfortunately, +it exclusively concentrates on Perl and Java's flavours of regular expressions, +and doesn't contain any Python material at all, so it won't be useful as a +reference for programming in Python. (The first edition covered Python's now- +removed :mod:`regex` module, which won't help you much.) Consider checking it +out from your library. + + +.. rubric:: Footnotes + +.. [#] Introduced in Python 2.2.2. + Added: doctools/trunk/Doc-26/howto/sockets.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-26/howto/sockets.rst Thu Aug 2 23:31:34 2007 @@ -0,0 +1,421 @@ +**************************** + Socket Programming HOWTO +**************************** + +:Author: Gordon McMillan + + +.. topic:: Abstract + + Sockets are used nearly everywhere, but are one of the most severely + misunderstood technologies around. This is a 10,000 foot overview of sockets. + It's not really a tutorial - you'll still have work to do in getting things + operational. It doesn't cover the fine points (and there are a lot of them), but + I hope it will give you enough background to begin using them decently. + + +Sockets +======= + +Sockets are used nearly everywhere, but are one of the most severely +misunderstood technologies around. This is a 10,000 foot overview of sockets. +It's not really a tutorial - you'll still have work to do in getting things +working. It doesn't cover the fine points (and there are a lot of them), but I +hope it will give you enough background to begin using them decently. + +I'm only going to talk about INET sockets, but they account for at least 99% of +the sockets in use. And I'll only talk about STREAM sockets - unless you really +know what you're doing (in which case this HOWTO isn't for you!), you'll get +better behavior and performance from a STREAM socket than anything else. I will +try to clear up the mystery of what a socket is, as well as some hints on how to +work with blocking and non-blocking sockets. But I'll start by talking about +blocking sockets. You'll need to know how they work before dealing with non- +blocking sockets. + +Part of the trouble with understanding these things is that "socket" can mean a +number of subtly different things, depending on context. So first, let's make a +distinction between a "client" socket - an endpoint of a conversation, and a +"server" socket, which is more like a switchboard operator. The client +application (your browser, for example) uses "client" sockets exclusively; the +web server it's talking to uses both "server" sockets and "client" sockets. + + +History +------- + +Of the various forms of IPC (*Inter Process Communication*), sockets are by far +the most popular. On any given platform, there are likely to be other forms of +IPC that are faster, but for cross-platform communication, sockets are about the +only game in town. + +They were invented in Berkeley as part of the BSD flavor of Unix. They spread +like wildfire with the Internet. With good reason --- the combination of sockets +with INET makes talking to arbitrary machines around the world unbelievably easy +(at least compared to other schemes). + + +Creating a Socket +================= + +Roughly speaking, when you clicked on the link that brought you to this page, +your browser did something like the following:: + + #create an INET, STREAMing socket + s = socket.socket( + socket.AF_INET, socket.SOCK_STREAM) + #now connect to the web server on port 80 + # - the normal http port + s.connect(("www.mcmillan-inc.com", 80)) + +When the ``connect`` completes, the socket ``s`` can now be used to send in a +request for the text of this page. The same socket will read the reply, and then +be destroyed. That's right - destroyed. Client sockets are normally only used +for one exchange (or a small set of sequential exchanges). + +What happens in the web server is a bit more complex. First, the web server +creates a "server socket". :: + + #create an INET, STREAMing socket + serversocket = socket.socket( + socket.AF_INET, socket.SOCK_STREAM) + #bind the socket to a public host, + # and a well-known port + serversocket.bind((socket.gethostname(), 80)) + #become a server socket + serversocket.listen(5) + +A couple things to notice: we used ``socket.gethostname()`` so that the socket +would be visible to the outside world. If we had used ``s.bind(('', 80))`` or +``s.bind(('localhost', 80))`` or ``s.bind(('127.0.0.1', 80))`` we would still +have a "server" socket, but one that was only visible within the same machine. + +A second thing to note: low number ports are usually reserved for "well known" +services (HTTP, SNMP etc). If you're playing around, use a nice high number (4 +digits). + +Finally, the argument to ``listen`` tells the socket library that we want it to +queue up as many as 5 connect requests (the normal max) before refusing outside +connections. If the rest of the code is written properly, that should be plenty. + +OK, now we have a "server" socket, listening on port 80. Now we enter the +mainloop of the web server:: + + while 1: + #accept connections from outside + (clientsocket, address) = serversocket.accept() + #now do something with the clientsocket + #in this case, we'll pretend this is a threaded server + ct = client_thread(clientsocket) + ct.run() + +There's actually 3 general ways in which this loop could work - dispatching a +thread to handle ``clientsocket``, create a new process to handle +``clientsocket``, or restructure this app to use non-blocking sockets, and +mulitplex between our "server" socket and any active ``clientsocket``\ s using +``select``. More about that later. The important thing to understand now is +this: this is *all* a "server" socket does. It doesn't send any data. It doesn't +receive any data. It just produces "client" sockets. Each ``clientsocket`` is +created in response to some *other* "client" socket doing a ``connect()`` to the +host and port we're bound to. As soon as we've created that ``clientsocket``, we +go back to listening for more connections. The two "clients" are free to chat it +up - they are using some dynamically allocated port which will be recycled when +the conversation ends. + + +IPC +--- + +If you need fast IPC between two processes on one machine, you should look into +whatever form of shared memory the platform offers. A simple protocol based +around shared memory and locks or semaphores is by far the fastest technique. + +If you do decide to use sockets, bind the "server" socket to ``'localhost'``. On +most platforms, this will take a shortcut around a couple of layers of network +code and be quite a bit faster. + + +Using a Socket +============== + +The first thing to note, is that the web browser's "client" socket and the web +server's "client" socket are identical beasts. That is, this is a "peer to peer" +conversation. Or to put it another way, *as the designer, you will have to +decide what the rules of etiquette are for a conversation*. Normally, the +``connect``\ ing socket starts the conversation, by sending in a request, or +perhaps a signon. But that's a design decision - it's not a rule of sockets. + +Now there are two sets of verbs to use for communication. You can use ``send`` +and ``recv``, or you can transform your client socket into a file-like beast and +use ``read`` and ``write``. The latter is the way Java presents their sockets. +I'm not going to talk about it here, except to warn you that you need to use +``flush`` on sockets. These are buffered "files", and a common mistake is to +``write`` something, and then ``read`` for a reply. Without a ``flush`` in +there, you may wait forever for the reply, because the request may still be in +your output buffer. + +Now we come the major stumbling block of sockets - ``send`` and ``recv`` operate +on the network buffers. They do not necessarily handle all the bytes you hand +them (or expect from them), because their major focus is handling the network +buffers. In general, they return when the associated network buffers have been +filled (``send``) or emptied (``recv``). They then tell you how many bytes they +handled. It is *your* responsibility to call them again until your message has +been completely dealt with. + +When a ``recv`` returns 0 bytes, it means the other side has closed (or is in +the process of closing) the connection. You will not receive any more data on +this connection. Ever. You may be able to send data successfully; I'll talk +about that some on the next page. + +A protocol like HTTP uses a socket for only one transfer. The client sends a +request, the reads a reply. That's it. The socket is discarded. This means that +a client can detect the end of the reply by receiving 0 bytes. + +But if you plan to reuse your socket for further transfers, you need to realize +that *there is no "EOT" (End of Transfer) on a socket.* I repeat: if a socket +``send`` or ``recv`` returns after handling 0 bytes, the connection has been +broken. If the connection has *not* been broken, you may wait on a ``recv`` +forever, because the socket will *not* tell you that there's nothing more to +read (for now). Now if you think about that a bit, you'll come to realize a +fundamental truth of sockets: *messages must either be fixed length* (yuck), *or +be delimited* (shrug), *or indicate how long they are* (much better), *or end by +shutting down the connection*. The choice is entirely yours, (but some ways are +righter than others). + +Assuming you don't want to end the connection, the simplest solution is a fixed +length message:: + + class mysocket: + '''demonstration class only + - coded for clarity, not efficiency + ''' + + def __init__(self, sock=None): + if sock is None: + self.sock = socket.socket( + socket.AF_INET, socket.SOCK_STREAM) + else: + self.sock = sock + + def connect(self, host, port): + self.sock.connect((host, port)) + + def mysend(self, msg): + totalsent = 0 + while totalsent < MSGLEN: + sent = self.sock.send(msg[totalsent:]) + if sent == 0: + raise RuntimeError, \\ + "socket connection broken" + totalsent = totalsent + sent + + def myreceive(self): + msg = '' + while len(msg) < MSGLEN: + chunk = self.sock.recv(MSGLEN-len(msg)) + if chunk == '': + raise RuntimeError, \\ + "socket connection broken" + msg = msg + chunk + return msg + +The sending code here is usable for almost any messaging scheme - in Python you +send strings, and you can use ``len()`` to determine its length (even if it has +embedded ``\0`` characters). It's mostly the receiving code that gets more +complex. (And in C, it's not much worse, except you can't use ``strlen`` if the +message has embedded ``\0``\ s.) + +The easiest enhancement is to make the first character of the message an +indicator of message type, and have the type determine the length. Now you have +two ``recv``\ s - the first to get (at least) that first character so you can +look up the length, and the second in a loop to get the rest. If you decide to +go the delimited route, you'll be receiving in some arbitrary chunk size, (4096 +or 8192 is frequently a good match for network buffer sizes), and scanning what +you've received for a delimiter. + +One complication to be aware of: if your conversational protocol allows multiple +messages to be sent back to back (without some kind of reply), and you pass +``recv`` an arbitrary chunk size, you may end up reading the start of a +following message. You'll need to put that aside and hold onto it, until it's +needed. + +Prefixing the message with it's length (say, as 5 numeric characters) gets more +complex, because (believe it or not), you may not get all 5 characters in one +``recv``. In playing around, you'll get away with it; but in high network loads, +your code will very quickly break unless you use two ``recv`` loops - the first +to determine the length, the second to get the data part of the message. Nasty. +This is also when you'll discover that ``send`` does not always manage to get +rid of everything in one pass. And despite having read this, you will eventually +get bit by it! + +In the interests of space, building your character, (and preserving my +competitive position), these enhancements are left as an exercise for the +reader. Lets move on to cleaning up. + + +Binary Data +----------- + +It is perfectly possible to send binary data over a socket. The major problem is +that not all machines use the same formats for binary data. For example, a +Motorola chip will represent a 16 bit integer with the value 1 as the two hex +bytes 00 01. Intel and DEC, however, are byte-reversed - that same 1 is 01 00. +Socket libraries have calls for converting 16 and 32 bit integers - ``ntohl, +htonl, ntohs, htons`` where "n" means *network* and "h" means *host*, "s" means +*short* and "l" means *long*. Where network order is host order, these do +nothing, but where the machine is byte-reversed, these swap the bytes around +appropriately. + +In these days of 32 bit machines, the ascii representation of binary data is +frequently smaller than the binary representation. That's because a surprising +amount of the time, all those longs have the value 0, or maybe 1. The string "0" +would be two bytes, while binary is four. Of course, this doesn't fit well with +fixed-length messages. Decisions, decisions. + + +Disconnecting +============= + +Strictly speaking, you're supposed to use ``shutdown`` on a socket before you +``close`` it. The ``shutdown`` is an advisory to the socket at the other end. +Depending on the argument you pass it, it can mean "I'm not going to send +anymore, but I'll still listen", or "I'm not listening, good riddance!". Most +socket libraries, however, are so used to programmers neglecting to use this +piece of etiquette that normally a ``close`` is the same as ``shutdown(); +close()``. So in most situations, an explicit ``shutdown`` is not needed. + +One way to use ``shutdown`` effectively is in an HTTP-like exchange. The client +sends a request and then does a ``shutdown(1)``. This tells the server "This +client is done sending, but can still receive." The server can detect "EOF" by +a receive of 0 bytes. It can assume it has the complete request. The server +sends a reply. If the ``send`` completes successfully then, indeed, the client +was still receiving. + +Python takes the automatic shutdown a step further, and says that when a socket +is garbage collected, it will automatically do a ``close`` if it's needed. But +relying on this is a very bad habit. If your socket just disappears without +doing a ``close``, the socket at the other end may hang indefinitely, thinking +you're just being slow. *Please* ``close`` your sockets when you're done. + + +When Sockets Die +---------------- + +Probably the worst thing about using blocking sockets is what happens when the +other side comes down hard (without doing a ``close``). Your socket is likely to +hang. SOCKSTREAM is a reliable protocol, and it will wait a long, long time +before giving up on a connection. If you're using threads, the entire thread is +essentially dead. There's not much you can do about it. As long as you aren't +doing something dumb, like holding a lock while doing a blocking read, the +thread isn't really consuming much in the way of resources. Do *not* try to kill +the thread - part of the reason that threads are more efficient than processes +is that they avoid the overhead associated with the automatic recycling of +resources. In other words, if you do manage to kill the thread, your whole +process is likely to be screwed up. + + +Non-blocking Sockets +==================== + +If you've understood the preceeding, you already know most of what you need to +know about the mechanics of using sockets. You'll still use the same calls, in +much the same ways. It's just that, if you do it right, your app will be almost +inside-out. + +In Python, you use ``socket.setblocking(0)`` to make it non-blocking. In C, it's +more complex, (for one thing, you'll need to choose between the BSD flavor +``O_NONBLOCK`` and the almost indistinguishable Posix flavor ``O_NDELAY``, which +is completely different from ``TCP_NODELAY``), but it's the exact same idea. You +do this after creating the socket, but before using it. (Actually, if you're +nuts, you can switch back and forth.) + +The major mechanical difference is that ``send``, ``recv``, ``connect`` and +``accept`` can return without having done anything. You have (of course) a +number of choices. You can check return code and error codes and generally drive +yourself crazy. If you don't believe me, try it sometime. Your app will grow +large, buggy and suck CPU. So let's skip the brain-dead solutions and do it +right. + +Use ``select``. + +In C, coding ``select`` is fairly complex. In Python, it's a piece of cake, but +it's close enough to the C version that if you understand ``select`` in Python, +you'll have little trouble with it in C. :: + + ready_to_read, ready_to_write, in_error = \\ + select.select( + potential_readers, + potential_writers, + potential_errs, + timeout) + +You pass ``select`` three lists: the first contains all sockets that you might +want to try reading; the second all the sockets you might want to try writing +to, and the last (normally left empty) those that you want to check for errors. +You should note that a socket can go into more than one list. The ``select`` +call is blocking, but you can give it a timeout. This is generally a sensible +thing to do - give it a nice long timeout (say a minute) unless you have good +reason to do otherwise. + +In return, you will get three lists. They have the sockets that are actually +readable, writable and in error. Each of these lists is a subset (possbily +empty) of the corresponding list you passed in. And if you put a socket in more +than one input list, it will only be (at most) in one output list. + +If a socket is in the output readable list, you can be as-close-to-certain-as- +we-ever-get-in-this-business that a ``recv`` on that socket will return +*something*. Same idea for the writable list. You'll be able to send +*something*. Maybe not all you want to, but *something* is better than nothing. +(Actually, any reasonably healthy socket will return as writable - it just means +outbound network buffer space is available.) + +If you have a "server" socket, put it in the potential_readers list. If it comes +out in the readable list, your ``accept`` will (almost certainly) work. If you +have created a new socket to ``connect`` to someone else, put it in the +ptoential_writers list. If it shows up in the writable list, you have a decent +chance that it has connected. + +One very nasty problem with ``select``: if somewhere in those input lists of +sockets is one which has died a nasty death, the ``select`` will fail. You then +need to loop through every single damn socket in all those lists and do a +``select([sock],[],[],0)`` until you find the bad one. That timeout of 0 means +it won't take long, but it's ugly. + +Actually, ``select`` can be handy even with blocking sockets. It's one way of +determining whether you will block - the socket returns as readable when there's +something in the buffers. However, this still doesn't help with the problem of +determining whether the other end is done, or just busy with something else. + +**Portability alert**: On Unix, ``select`` works both with the sockets and +files. Don't try this on Windows. On Windows, ``select`` works with sockets +only. Also note that in C, many of the more advanced socket options are done +differently on Windows. In fact, on Windows I usually use threads (which work +very, very well) with my sockets. Face it, if you want any kind of performance, +your code will look very different on Windows than on Unix. (I haven't the +foggiest how you do this stuff on a Mac.) + + +Performance +----------- + +There's no question that the fastest sockets code uses non-blocking sockets and +select to multiplex them. You can put together something that will saturate a +LAN connection without putting any strain on the CPU. The trouble is that an app +written this way can't do much of anything else - it needs to be ready to +shuffle bytes around at all times. + +Assuming that your app is actually supposed to do something more than that, +threading is the optimal solution, (and using non-blocking sockets will be +faster than using blocking sockets). Unfortunately, threading support in Unixes +varies both in API and quality. So the normal Unix solution is to fork a +subprocess to deal with each connection. The overhead for this is significant +(and don't do this on Windows - the overhead of process creation is enormous +there). It also means that unless each subprocess is completely independent, +you'll need to use another form of IPC, say a pipe, or shared memory and +semaphores, to communicate between the parent and child processes. + +Finally, remember that even though blocking sockets are somewhat slower than +non-blocking, in many cases they are the "right" solution. After all, if your +app is driven by the data it receives over a socket, there's not much sense in +complicating the logic just so your app can wait on ``select`` instead of +``recv``. + Added: doctools/trunk/Doc-26/howto/unicode.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-26/howto/unicode.rst Thu Aug 2 23:31:34 2007 @@ -0,0 +1,732 @@ +***************** + Unicode HOWTO +***************** + +:Release: 1.02 + +This HOWTO discusses Python's support for Unicode, and explains various problems +that people commonly encounter when trying to work with Unicode. + +Introduction to Unicode +======================= + +History of Character Codes +-------------------------- + +In 1968, the American Standard Code for Information Interchange, better known by +its acronym ASCII, was standardized. ASCII defined numeric codes for various +characters, with the numeric values running from 0 to +127. For example, the lowercase letter 'a' is assigned 97 as its code +value. + +ASCII was an American-developed standard, so it only defined unaccented +characters. There was an 'e', but no '?' or '?'. This meant that languages +which required accented characters couldn't be faithfully represented in ASCII. +(Actually the missing accents matter for English, too, which contains words such +as 'na?ve' and 'caf?', and some publications have house styles which require +spellings such as 'co?perate'.) + +For a while people just wrote programs that didn't display accents. I remember +looking at Apple ][ BASIC programs, published in French-language publications in +the mid-1980s, that had lines like these:: + + PRINT "FICHER EST COMPLETE." + PRINT "CARACTERE NON ACCEPTE." + +Those messages should contain accents, and they just look wrong to someone who +can read French. + +In the 1980s, almost all personal computers were 8-bit, meaning that bytes could +hold values ranging from 0 to 255. ASCII codes only went up to 127, so some +machines assigned values between 128 and 255 to accented characters. Different +machines had different codes, however, which led to problems exchanging files. +Eventually various commonly used sets of values for the 128-255 range emerged. +Some were true standards, defined by the International Standards Organization, +and some were **de facto** conventions that were invented by one company or +another and managed to catch on. + +255 characters aren't very many. For example, you can't fit both the accented +characters used in Western Europe and the Cyrillic alphabet used for Russian +into the 128-255 range because there are more than 127 such characters. + +You could write files using different codes (all your Russian files in a coding +system called KOI8, all your French files in a different coding system called +Latin1), but what if you wanted to write a French document that quotes some +Russian text? In the 1980s people began to want to solve this problem, and the +Unicode standardization effort began. + +Unicode started out using 16-bit characters instead of 8-bit characters. 16 +bits means you have 2^16 = 65,536 distinct values available, making it possible +to represent many different characters from many different alphabets; an initial +goal was to have Unicode contain the alphabets for every single human language. +It turns out that even 16 bits isn't enough to meet that goal, and the modern +Unicode specification uses a wider range of codes, 0-1,114,111 (0x10ffff in +base-16). + +There's a related ISO standard, ISO 10646. Unicode and ISO 10646 were +originally separate efforts, but the specifications were merged with the 1.1 +revision of Unicode. + +(This discussion of Unicode's history is highly simplified. I don't think the +average Python programmer needs to worry about the historical details; consult +the Unicode consortium site listed in the References for more information.) + + +Definitions +----------- + +A **character** is the smallest possible component of a text. 'A', 'B', 'C', +etc., are all different characters. So are '?' and '?'. Characters are +abstractions, and vary depending on the language or context you're talking +about. For example, the symbol for ohms (?) is usually drawn much like the +capital letter omega (?) in the Greek alphabet (they may even be the same in +some fonts), but these are two different characters that have different +meanings. + +The Unicode standard describes how characters are represented by **code +points**. A code point is an integer value, usually denoted in base 16. In the +standard, a code point is written using the notation U+12ca to mean the +character with value 0x12ca (4810 decimal). The Unicode standard contains a lot +of tables listing characters and their corresponding code points:: + + 0061 'a'; LATIN SMALL LETTER A + 0062 'b'; LATIN SMALL LETTER B + 0063 'c'; LATIN SMALL LETTER C + ... + 007B '{'; LEFT CURLY BRACKET + +Strictly, these definitions imply that it's meaningless to say 'this is +character U+12ca'. U+12ca is a code point, which represents some particular +character; in this case, it represents the character 'ETHIOPIC SYLLABLE WI'. In +informal contexts, this distinction between code points and characters will +sometimes be forgotten. + +A character is represented on a screen or on paper by a set of graphical +elements that's called a **glyph**. The glyph for an uppercase A, for example, +is two diagonal strokes and a horizontal stroke, though the exact details will +depend on the font being used. Most Python code doesn't need to worry about +glyphs; figuring out the correct glyph to display is generally the job of a GUI +toolkit or a terminal's font renderer. + + +Encodings +--------- + +To summarize the previous section: a Unicode string is a sequence of code +points, which are numbers from 0 to 0x10ffff. This sequence needs to be +represented as a set of bytes (meaning, values from 0-255) in memory. The rules +for translating a Unicode string into a sequence of bytes are called an +**encoding**. + +The first encoding you might think of is an array of 32-bit integers. In this +representation, the string "Python" would look like this:: + + P y t h o n + 0x50 00 00 00 79 00 00 00 74 00 00 00 68 00 00 00 6f 00 00 00 6e 00 00 00 + 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 + +This representation is straightforward but using it presents a number of +problems. + +1. It's not portable; different processors order the bytes differently. + +2. It's very wasteful of space. In most texts, the majority of the code points + are less than 127, or less than 255, so a lot of space is occupied by zero + bytes. The above string takes 24 bytes compared to the 6 bytes needed for an + ASCII representation. Increased RAM usage doesn't matter too much (desktop + computers have megabytes of RAM, and strings aren't usually that large), but + expanding our usage of disk and network bandwidth by a factor of 4 is + intolerable. + +3. It's not compatible with existing C functions such as ``strlen()``, so a new + family of wide string functions would need to be used. + +4. Many Internet standards are defined in terms of textual data, and can't + handle content with embedded zero bytes. + +Generally people don't use this encoding, instead choosing other encodings that +are more efficient and convenient. + +Encodings don't have to handle every possible Unicode character, and most +encodings don't. For example, Python's default encoding is the 'ascii' +encoding. The rules for converting a Unicode string into the ASCII encoding are +simple; for each code point: + +1. If the code point is < 128, each byte is the same as the value of the code + point. + +2. If the code point is 128 or greater, the Unicode string can't be represented + in this encoding. (Python raises a :exc:`UnicodeEncodeError` exception in this + case.) + +Latin-1, also known as ISO-8859-1, is a similar encoding. Unicode code points +0-255 are identical to the Latin-1 values, so converting to this encoding simply +requires converting code points to byte values; if a code point larger than 255 +is encountered, the string can't be encoded into Latin-1. + +Encodings don't have to be simple one-to-one mappings like Latin-1. Consider +IBM's EBCDIC, which was used on IBM mainframes. Letter values weren't in one +block: 'a' through 'i' had values from 129 to 137, but 'j' through 'r' were 145 +through 153. If you wanted to use EBCDIC as an encoding, you'd probably use +some sort of lookup table to perform the conversion, but this is largely an +internal detail. + +UTF-8 is one of the most commonly used encodings. UTF stands for "Unicode +Transformation Format", and the '8' means that 8-bit numbers are used in the +encoding. (There's also a UTF-16 encoding, but it's less frequently used than +UTF-8.) UTF-8 uses the following rules: + +1. If the code point is <128, it's represented by the corresponding byte value. +2. If the code point is between 128 and 0x7ff, it's turned into two byte values + between 128 and 255. +3. Code points >0x7ff are turned into three- or four-byte sequences, where each + byte of the sequence is between 128 and 255. + +UTF-8 has several convenient properties: + +1. It can handle any Unicode code point. +2. A Unicode string is turned into a string of bytes containing no embedded zero + bytes. This avoids byte-ordering issues, and means UTF-8 strings can be + processed by C functions such as ``strcpy()`` and sent through protocols that + can't handle zero bytes. +3. A string of ASCII text is also valid UTF-8 text. +4. UTF-8 is fairly compact; the majority of code points are turned into two + bytes, and values less than 128 occupy only a single byte. +5. If bytes are corrupted or lost, it's possible to determine the start of the + next UTF-8-encoded code point and resynchronize. It's also unlikely that + random 8-bit data will look like valid UTF-8. + + + +References +---------- + +The Unicode Consortium site at has character charts, a +glossary, and PDF versions of the Unicode specification. Be prepared for some +difficult reading. is a chronology of the +origin and development of Unicode. + +To help understand the standard, Jukka Korpela has written an introductory guide +to reading the Unicode character tables, available at +. + +Roman Czyborra wrote another explanation of Unicode's basic principles; it's at +. Czyborra has written a number of +other Unicode-related documentation, available from . + +Two other good introductory articles were written by Joel Spolsky + and Jason Orendorff +. If this introduction didn't make +things clear to you, you should try reading one of these alternate articles +before continuing. + +Wikipedia entries are often helpful; see the entries for "character encoding" + and UTF-8 +, for example. + + +Python's Unicode Support +======================== + +Now that you've learned the rudiments of Unicode, we can look at Python's +Unicode features. + + +The Unicode Type +---------------- + +Unicode strings are expressed as instances of the :class:`unicode` type, one of +Python's repertoire of built-in types. It derives from an abstract type called +:class:`basestring`, which is also an ancestor of the :class:`str` type; you can +therefore check if a value is a string type with ``isinstance(value, +basestring)``. Under the hood, Python represents Unicode strings as either 16- +or 32-bit integers, depending on how the Python interpreter was compiled. + +The :func:`unicode` constructor has the signature ``unicode(string[, encoding, +errors])``. All of its arguments should be 8-bit strings. The first argument +is converted to Unicode using the specified encoding; if you leave off the +``encoding`` argument, the ASCII encoding is used for the conversion, so +characters greater than 127 will be treated as errors:: + + >>> unicode('abcdef') + u'abcdef' + >>> s = unicode('abcdef') + >>> type(s) + + >>> unicode('abcdef' + chr(255)) + Traceback (most recent call last): + File "", line 1, in ? + UnicodeDecodeError: 'ascii' codec can't decode byte 0xff in position 6: + ordinal not in range(128) + +The ``errors`` argument specifies the response when the input string can't be +converted according to the encoding's rules. Legal values for this argument are +'strict' (raise a ``UnicodeDecodeError`` exception), 'replace' (add U+FFFD, +'REPLACEMENT CHARACTER'), or 'ignore' (just leave the character out of the +Unicode result). The following examples show the differences:: + + >>> unicode('\x80abc', errors='strict') + Traceback (most recent call last): + File "", line 1, in ? + UnicodeDecodeError: 'ascii' codec can't decode byte 0x80 in position 0: + ordinal not in range(128) + >>> unicode('\x80abc', errors='replace') + u'\ufffdabc' + >>> unicode('\x80abc', errors='ignore') + u'abc' + +Encodings are specified as strings containing the encoding's name. Python 2.4 +comes with roughly 100 different encodings; see the Python Library Reference at + for a list. Some encodings +have multiple names; for example, 'latin-1', 'iso_8859_1' and '8859' are all +synonyms for the same encoding. + +One-character Unicode strings can also be created with the :func:`unichr` +built-in function, which takes integers and returns a Unicode string of length 1 +that contains the corresponding code point. The reverse operation is the +built-in :func:`ord` function that takes a one-character Unicode string and +returns the code point value:: + + >>> unichr(40960) + u'\ua000' + >>> ord(u'\ua000') + 40960 + +Instances of the :class:`unicode` type have many of the same methods as the +8-bit string type for operations such as searching and formatting:: + + >>> s = u'Was ever feather so lightly blown to and fro as this multitude?' + >>> s.count('e') + 5 + >>> s.find('feather') + 9 + >>> s.find('bird') + -1 + >>> s.replace('feather', 'sand') + u'Was ever sand so lightly blown to and fro as this multitude?' + >>> s.upper() + u'WAS EVER FEATHER SO LIGHTLY BLOWN TO AND FRO AS THIS MULTITUDE?' + +Note that the arguments to these methods can be Unicode strings or 8-bit +strings. 8-bit strings will be converted to Unicode before carrying out the +operation; Python's default ASCII encoding will be used, so characters greater +than 127 will cause an exception:: + + >>> s.find('Was\x9f') + Traceback (most recent call last): + File "", line 1, in ? + UnicodeDecodeError: 'ascii' codec can't decode byte 0x9f in position 3: ordinal not in range(128) + >>> s.find(u'Was\x9f') + -1 + +Much Python code that operates on strings will therefore work with Unicode +strings without requiring any changes to the code. (Input and output code needs +more updating for Unicode; more on this later.) + +Another important method is ``.encode([encoding], [errors='strict'])``, which +returns an 8-bit string version of the Unicode string, encoded in the requested +encoding. The ``errors`` parameter is the same as the parameter of the +``unicode()`` constructor, with one additional possibility; as well as 'strict', +'ignore', and 'replace', you can also pass 'xmlcharrefreplace' which uses XML's +character references. The following example shows the different results:: + + >>> u = unichr(40960) + u'abcd' + unichr(1972) + >>> u.encode('utf-8') + '\xea\x80\x80abcd\xde\xb4' + >>> u.encode('ascii') + Traceback (most recent call last): + File "", line 1, in ? + UnicodeEncodeError: 'ascii' codec can't encode character '\ua000' in position 0: ordinal not in range(128) + >>> u.encode('ascii', 'ignore') + 'abcd' + >>> u.encode('ascii', 'replace') + '?abcd?' + >>> u.encode('ascii', 'xmlcharrefreplace') + 'ꀀabcd޴' + +Python's 8-bit strings have a ``.decode([encoding], [errors])`` method that +interprets the string using the given encoding:: + + >>> u = unichr(40960) + u'abcd' + unichr(1972) # Assemble a string + >>> utf8_version = u.encode('utf-8') # Encode as UTF-8 + >>> type(utf8_version), utf8_version + (, '\xea\x80\x80abcd\xde\xb4') + >>> u2 = utf8_version.decode('utf-8') # Decode using UTF-8 + >>> u == u2 # The two strings match + True + +The low-level routines for registering and accessing the available encodings are +found in the :mod:`codecs` module. However, the encoding and decoding functions +returned by this module are usually more low-level than is comfortable, so I'm +not going to describe the :mod:`codecs` module here. If you need to implement a +completely new encoding, you'll need to learn about the :mod:`codecs` module +interfaces, but implementing encodings is a specialized task that also won't be +covered here. Consult the Python documentation to learn more about this module. + +The most commonly used part of the :mod:`codecs` module is the +:func:`codecs.open` function which will be discussed in the section on input and +output. + + +Unicode Literals in Python Source Code +-------------------------------------- + +In Python source code, Unicode literals are written as strings prefixed with the +'u' or 'U' character: ``u'abcdefghijk'``. Specific code points can be written +using the ``\u`` escape sequence, which is followed by four hex digits giving +the code point. The ``\U`` escape sequence is similar, but expects 8 hex +digits, not 4. + +Unicode literals can also use the same escape sequences as 8-bit strings, +including ``\x``, but ``\x`` only takes two hex digits so it can't express an +arbitrary code point. Octal escapes can go up to U+01ff, which is octal 777. + +:: + + >>> s = u"a\xac\u1234\u20ac\U00008000" + ^^^^ two-digit hex escape + ^^^^^^ four-digit Unicode escape + ^^^^^^^^^^ eight-digit Unicode escape + >>> for c in s: print ord(c), + ... + 97 172 4660 8364 32768 + +Using escape sequences for code points greater than 127 is fine in small doses, +but becomes an annoyance if you're using many accented characters, as you would +in a program with messages in French or some other accent-using language. You +can also assemble strings using the :func:`unichr` built-in function, but this is +even more tedious. + +Ideally, you'd want to be able to write literals in your language's natural +encoding. You could then edit Python source code with your favorite editor +which would display the accented characters naturally, and have the right +characters used at runtime. + +Python supports writing Unicode literals in any encoding, but you have to +declare the encoding being used. This is done by including a special comment as +either the first or second line of the source file:: + + #!/usr/bin/env python + # -*- coding: latin-1 -*- + + u = u'abcd?' + print ord(u[-1]) + +The syntax is inspired by Emacs's notation for specifying variables local to a +file. Emacs supports many different variables, but Python only supports +'coding'. The ``-*-`` symbols indicate that the comment is special; within +them, you must supply the name ``coding`` and the name of your chosen encoding, +separated by ``':'``. + +If you don't include such a comment, the default encoding used will be ASCII. +Versions of Python before 2.4 were Euro-centric and assumed Latin-1 as a default +encoding for string literals; in Python 2.4, characters greater than 127 still +work but result in a warning. For example, the following program has no +encoding declaration:: + + #!/usr/bin/env python + u = u'abcd?' + print ord(u[-1]) + +When you run it with Python 2.4, it will output the following warning:: + + amk:~$ python p263.py + sys:1: DeprecationWarning: Non-ASCII character '\xe9' + in file p263.py on line 2, but no encoding declared; + see http://www.python.org/peps/pep-0263.html for details + + +Unicode Properties +------------------ + +The Unicode specification includes a database of information about code points. +For each code point that's defined, the information includes the character's +name, its category, the numeric value if applicable (Unicode has characters +representing the Roman numerals and fractions such as one-third and +four-fifths). There are also properties related to the code point's use in +bidirectional text and other display-related properties. + +The following program displays some information about several characters, and +prints the numeric value of one particular character:: + + import unicodedata + + u = unichr(233) + unichr(0x0bf2) + unichr(3972) + unichr(6000) + unichr(13231) + + for i, c in enumerate(u): + print i, '%04x' % ord(c), unicodedata.category(c), + print unicodedata.name(c) + + # Get numeric value of second character + print unicodedata.numeric(u[1]) + +When run, this prints:: + + 0 00e9 Ll LATIN SMALL LETTER E WITH ACUTE + 1 0bf2 No TAMIL NUMBER ONE THOUSAND + 2 0f84 Mn TIBETAN MARK HALANTA + 3 1770 Lo TAGBANWA LETTER SA + 4 33af So SQUARE RAD OVER S SQUARED + 1000.0 + +The category codes are abbreviations describing the nature of the character. +These are grouped into categories such as "Letter", "Number", "Punctuation", or +"Symbol", which in turn are broken up into subcategories. To take the codes +from the above output, ``'Ll'`` means 'Letter, lowercase', ``'No'`` means +"Number, other", ``'Mn'`` is "Mark, nonspacing", and ``'So'`` is "Symbol, +other". See + for a +list of category codes. + +References +---------- + +The Unicode and 8-bit string types are described in the Python library reference +at :ref:`typesseq`. + +The documentation for the :mod:`unicodedata` module. + +The documentation for the :mod:`codecs` module. + +Marc-Andr? Lemburg gave a presentation at EuroPython 2002 titled "Python and +Unicode". A PDF version of his slides is available at +, and is an +excellent overview of the design of Python's Unicode features. + + +Reading and Writing Unicode Data +================================ + +Once you've written some code that works with Unicode data, the next problem is +input/output. How do you get Unicode strings into your program, and how do you +convert Unicode into a form suitable for storage or transmission? + +It's possible that you may not need to do anything depending on your input +sources and output destinations; you should check whether the libraries used in +your application support Unicode natively. XML parsers often return Unicode +data, for example. Many relational databases also support Unicode-valued +columns and can return Unicode values from an SQL query. + +Unicode data is usually converted to a particular encoding before it gets +written to disk or sent over a socket. It's possible to do all the work +yourself: open a file, read an 8-bit string from it, and convert the string with +``unicode(str, encoding)``. However, the manual approach is not recommended. + +One problem is the multi-byte nature of encodings; one Unicode character can be +represented by several bytes. If you want to read the file in arbitrary-sized +chunks (say, 1K or 4K), you need to write error-handling code to catch the case +where only part of the bytes encoding a single Unicode character are read at the +end of a chunk. One solution would be to read the entire file into memory and +then perform the decoding, but that prevents you from working with files that +are extremely large; if you need to read a 2Gb file, you need 2Gb of RAM. +(More, really, since for at least a moment you'd need to have both the encoded +string and its Unicode version in memory.) + +The solution would be to use the low-level decoding interface to catch the case +of partial coding sequences. The work of implementing this has already been +done for you: the :mod:`codecs` module includes a version of the :func:`open` +function that returns a file-like object that assumes the file's contents are in +a specified encoding and accepts Unicode parameters for methods such as +``.read()`` and ``.write()``. + +The function's parameters are ``open(filename, mode='rb', encoding=None, +errors='strict', buffering=1)``. ``mode`` can be ``'r'``, ``'w'``, or ``'a'``, +just like the corresponding parameter to the regular built-in ``open()`` +function; add a ``'+'`` to update the file. ``buffering`` is similarly parallel +to the standard function's parameter. ``encoding`` is a string giving the +encoding to use; if it's left as ``None``, a regular Python file object that +accepts 8-bit strings is returned. Otherwise, a wrapper object is returned, and +data written to or read from the wrapper object will be converted as needed. +``errors`` specifies the action for encoding errors and can be one of the usual +values of 'strict', 'ignore', and 'replace'. + +Reading Unicode from a file is therefore simple:: + + import codecs + f = codecs.open('unicode.rst', encoding='utf-8') + for line in f: + print repr(line) + +It's also possible to open files in update mode, allowing both reading and +writing:: + + f = codecs.open('test', encoding='utf-8', mode='w+') + f.write(u'\u4500 blah blah blah\n') + f.seek(0) + print repr(f.readline()[:1]) + f.close() + +Unicode character U+FEFF is used as a byte-order mark (BOM), and is often +written as the first character of a file in order to assist with autodetection +of the file's byte ordering. Some encodings, such as UTF-16, expect a BOM to be +present at the start of a file; when such an encoding is used, the BOM will be +automatically written as the first character and will be silently dropped when +the file is read. There are variants of these encodings, such as 'utf-16-le' +and 'utf-16-be' for little-endian and big-endian encodings, that specify one +particular byte ordering and don't skip the BOM. + + +Unicode filenames +----------------- + +Most of the operating systems in common use today support filenames that contain +arbitrary Unicode characters. Usually this is implemented by converting the +Unicode string into some encoding that varies depending on the system. For +example, MacOS X uses UTF-8 while Windows uses a configurable encoding; on +Windows, Python uses the name "mbcs" to refer to whatever the currently +configured encoding is. On Unix systems, there will only be a filesystem +encoding if you've set the ``LANG`` or ``LC_CTYPE`` environment variables; if +you haven't, the default encoding is ASCII. + +The :func:`sys.getfilesystemencoding` function returns the encoding to use on +your current system, in case you want to do the encoding manually, but there's +not much reason to bother. When opening a file for reading or writing, you can +usually just provide the Unicode string as the filename, and it will be +automatically converted to the right encoding for you:: + + filename = u'filename\u4500abc' + f = open(filename, 'w') + f.write('blah\n') + f.close() + +Functions in the :mod:`os` module such as :func:`os.stat` will also accept Unicode +filenames. + +:func:`os.listdir`, which returns filenames, raises an issue: should it return +the Unicode version of filenames, or should it return 8-bit strings containing +the encoded versions? :func:`os.listdir` will do both, depending on whether you +provided the directory path as an 8-bit string or a Unicode string. If you pass +a Unicode string as the path, filenames will be decoded using the filesystem's +encoding and a list of Unicode strings will be returned, while passing an 8-bit +path will return the 8-bit versions of the filenames. For example, assuming the +default filesystem encoding is UTF-8, running the following program:: + + fn = u'filename\u4500abc' + f = open(fn, 'w') + f.close() + + import os + print os.listdir('.') + print os.listdir(u'.') + +will produce the following output:: + + amk:~$ python t.py + ['.svn', 'filename\xe4\x94\x80abc', ...] + [u'.svn', u'filename\u4500abc', ...] + +The first list contains UTF-8-encoded filenames, and the second list contains +the Unicode versions. + + + +Tips for Writing Unicode-aware Programs +--------------------------------------- + +This section provides some suggestions on writing software that deals with +Unicode. + +The most important tip is: + + Software should only work with Unicode strings internally, converting to a + particular encoding on output. + +If you attempt to write processing functions that accept both Unicode and 8-bit +strings, you will find your program vulnerable to bugs wherever you combine the +two different kinds of strings. Python's default encoding is ASCII, so whenever +a character with an ASCII value > 127 is in the input data, you'll get a +:exc:`UnicodeDecodeError` because that character can't be handled by the ASCII +encoding. + +It's easy to miss such problems if you only test your software with data that +doesn't contain any accents; everything will seem to work, but there's actually +a bug in your program waiting for the first user who attempts to use characters +> 127. A second tip, therefore, is: + + Include characters > 127 and, even better, characters > 255 in your test + data. + +When using data coming from a web browser or some other untrusted source, a +common technique is to check for illegal characters in a string before using the +string in a generated command line or storing it in a database. If you're doing +this, be careful to check the string once it's in the form that will be used or +stored; it's possible for encodings to be used to disguise characters. This is +especially true if the input data also specifies the encoding; many encodings +leave the commonly checked-for characters alone, but Python includes some +encodings such as ``'base64'`` that modify every single character. + +For example, let's say you have a content management system that takes a Unicode +filename, and you want to disallow paths with a '/' character. You might write +this code:: + + def read_file (filename, encoding): + if '/' in filename: + raise ValueError("'/' not allowed in filenames") + unicode_name = filename.decode(encoding) + f = open(unicode_name, 'r') + # ... return contents of file ... + +However, if an attacker could specify the ``'base64'`` encoding, they could pass +``'L2V0Yy9wYXNzd2Q='``, which is the base-64 encoded form of the string +``'/etc/passwd'``, to read a system file. The above code looks for ``'/'`` +characters in the encoded form and misses the dangerous character in the +resulting decoded form. + +References +---------- + +The PDF slides for Marc-Andr? Lemburg's presentation "Writing Unicode-aware +Applications in Python" are available at + +and discuss questions of character encodings as well as how to internationalize +and localize an application. + + +Revision History and Acknowledgements +===================================== + +Thanks to the following people who have noted errors or offered suggestions on +this article: Nicholas Bastin, Marius Gedminas, Kent Johnson, Ken Krugler, +Marc-Andr? Lemburg, Martin von L?wis, Chad Whitacre. + +Version 1.0: posted August 5 2005. + +Version 1.01: posted August 7 2005. Corrects factual and markup errors; adds +several links. + +Version 1.02: posted August 16 2005. Corrects factual errors. + + +.. comment Additional topic: building Python w/ UCS2 or UCS4 support +.. comment Describe obscure -U switch somewhere? +.. comment Describe use of codecs.StreamRecoder and StreamReaderWriter + +.. comment + Original outline: + + - [ ] Unicode introduction + - [ ] ASCII + - [ ] Terms + - [ ] Character + - [ ] Code point + - [ ] Encodings + - [ ] Common encodings: ASCII, Latin-1, UTF-8 + - [ ] Unicode Python type + - [ ] Writing unicode literals + - [ ] Obscurity: -U switch + - [ ] Built-ins + - [ ] unichr() + - [ ] ord() + - [ ] unicode() constructor + - [ ] Unicode type + - [ ] encode(), decode() methods + - [ ] Unicodedata module for character properties + - [ ] I/O + - [ ] Reading/writing Unicode data into files + - [ ] Byte-order marks + - [ ] Unicode filenames + - [ ] Writing Unicode programs + - [ ] Do everything in Unicode + - [ ] Declaring source code encodings (PEP 263) + - [ ] Other issues + - [ ] Building Python (UCS2, UCS4) Added: doctools/trunk/Doc-26/howto/urllib2.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-26/howto/urllib2.rst Thu Aug 2 23:31:34 2007 @@ -0,0 +1,573 @@ +************************************************ + HOWTO Fetch Internet Resources Using urllib2 +************************************************ + +:Author: `Michael Foord `_ + +.. note:: + + There is an French translation of an earlier revision of this + HOWTO, available at `urllib2 - Le Manuel manquant + `_. + + + +Introduction +============ + +.. sidebar:: Related Articles + + You may also find useful the following article on fetching web resources + with Python : + + * `Basic Authentication `_ + + A tutorial on *Basic Authentication*, with examples in Python. + +**urllib2** is a `Python `_ module for fetching URLs +(Uniform Resource Locators). It offers a very simple interface, in the form of +the *urlopen* function. This is capable of fetching URLs using a variety of +different protocols. It also offers a slightly more complex interface for +handling common situations - like basic authentication, cookies, proxies and so +on. These are provided by objects called handlers and openers. + +urllib2 supports fetching URLs for many "URL schemes" (identified by the string +before the ":" in URL - for example "ftp" is the URL scheme of +"ftp://python.org/") using their associated network protocols (e.g. FTP, HTTP). +This tutorial focuses on the most common case, HTTP. + +For straightforward situations *urlopen* is very easy to use. But as soon as you +encounter errors or non-trivial cases when opening HTTP URLs, you will need some +understanding of the HyperText Transfer Protocol. The most comprehensive and +authoritative reference to HTTP is :rfc:`2616`. This is a technical document and +not intended to be easy to read. This HOWTO aims to illustrate using *urllib2*, +with enough detail about HTTP to help you through. It is not intended to replace +the :mod:`urllib2` docs, but is supplementary to them. + + +Fetching URLs +============= + +The simplest way to use urllib2 is as follows:: + + import urllib2 + response = urllib2.urlopen('http://python.org/') + html = response.read() + +Many uses of urllib2 will be that simple (note that instead of an 'http:' URL we +could have used an URL starting with 'ftp:', 'file:', etc.). However, it's the +purpose of this tutorial to explain the more complicated cases, concentrating on +HTTP. + +HTTP is based on requests and responses - the client makes requests and servers +send responses. urllib2 mirrors this with a ``Request`` object which represents +the HTTP request you are making. In its simplest form you create a Request +object that specifies the URL you want to fetch. Calling ``urlopen`` with this +Request object returns a response object for the URL requested. This response is +a file-like object, which means you can for example call ``.read()`` on the +response:: + + import urllib2 + + req = urllib2.Request('http://www.voidspace.org.uk') + response = urllib2.urlopen(req) + the_page = response.read() + +Note that urllib2 makes use of the same Request interface to handle all URL +schemes. For example, you can make an FTP request like so:: + + req = urllib2.Request('ftp://example.com/') + +In the case of HTTP, there are two extra things that Request objects allow you +to do: First, you can pass data to be sent to the server. Second, you can pass +extra information ("metadata") *about* the data or the about request itself, to +the server - this information is sent as HTTP "headers". Let's look at each of +these in turn. + +Data +---- + +Sometimes you want to send data to a URL (often the URL will refer to a CGI +(Common Gateway Interface) script [#]_ or other web application). With HTTP, +this is often done using what's known as a **POST** request. This is often what +your browser does when you submit a HTML form that you filled in on the web. Not +all POSTs have to come from forms: you can use a POST to transmit arbitrary data +to your own application. In the common case of HTML forms, the data needs to be +encoded in a standard way, and then passed to the Request object as the ``data`` +argument. The encoding is done using a function from the ``urllib`` library +*not* from ``urllib2``. :: + + import urllib + import urllib2 + + url = 'http://www.someserver.com/cgi-bin/register.cgi' + values = {'name' : 'Michael Foord', + 'location' : 'Northampton', + 'language' : 'Python' } + + data = urllib.urlencode(values) + req = urllib2.Request(url, data) + response = urllib2.urlopen(req) + the_page = response.read() + +Note that other encodings are sometimes required (e.g. for file upload from HTML +forms - see `HTML Specification, Form Submission +`_ for more +details). + +If you do not pass the ``data`` argument, urllib2 uses a **GET** request. One +way in which GET and POST requests differ is that POST requests often have +"side-effects": they change the state of the system in some way (for example by +placing an order with the website for a hundredweight of tinned spam to be +delivered to your door). Though the HTTP standard makes it clear that POSTs are +intended to *always* cause side-effects, and GET requests *never* to cause +side-effects, nothing prevents a GET request from having side-effects, nor a +POST requests from having no side-effects. Data can also be passed in an HTTP +GET request by encoding it in the URL itself. + +This is done as follows:: + + >>> import urllib2 + >>> import urllib + >>> data = {} + >>> data['name'] = 'Somebody Here' + >>> data['location'] = 'Northampton' + >>> data['language'] = 'Python' + >>> url_values = urllib.urlencode(data) + >>> print url_values + name=Somebody+Here&language=Python&location=Northampton + >>> url = 'http://www.example.com/example.cgi' + >>> full_url = url + '?' + url_values + >>> data = urllib2.open(full_url) + +Notice that the full URL is created by adding a ``?`` to the URL, followed by +the encoded values. + +Headers +------- + +We'll discuss here one particular HTTP header, to illustrate how to add headers +to your HTTP request. + +Some websites [#]_ dislike being browsed by programs, or send different versions +to different browsers [#]_ . By default urllib2 identifies itself as +``Python-urllib/x.y`` (where ``x`` and ``y`` are the major and minor version +numbers of the Python release, +e.g. ``Python-urllib/2.5``), which may confuse the site, or just plain +not work. The way a browser identifies itself is through the +``User-Agent`` header [#]_. When you create a Request object you can +pass a dictionary of headers in. The following example makes the same +request as above, but identifies itself as a version of Internet +Explorer [#]_. :: + + import urllib + import urllib2 + + url = 'http://www.someserver.com/cgi-bin/register.cgi' + user_agent = 'Mozilla/4.0 (compatible; MSIE 5.5; Windows NT)' + values = {'name' : 'Michael Foord', + 'location' : 'Northampton', + 'language' : 'Python' } + headers = { 'User-Agent' : user_agent } + + data = urllib.urlencode(values) + req = urllib2.Request(url, data, headers) + response = urllib2.urlopen(req) + the_page = response.read() + +The response also has two useful methods. See the section on `info and geturl`_ +which comes after we have a look at what happens when things go wrong. + + +Handling Exceptions +=================== + +*urlopen* raises ``URLError`` when it cannot handle a response (though as usual +with Python APIs, builtin exceptions such as ValueError, TypeError etc. may also +be raised). + +``HTTPError`` is the subclass of ``URLError`` raised in the specific case of +HTTP URLs. + +URLError +-------- + +Often, URLError is raised because there is no network connection (no route to +the specified server), or the specified server doesn't exist. In this case, the +exception raised will have a 'reason' attribute, which is a tuple containing an +error code and a text error message. + +e.g. :: + + >>> req = urllib2.Request('http://www.pretend_server.org') + >>> try: urllib2.urlopen(req) + >>> except URLError, e: + >>> print e.reason + >>> + (4, 'getaddrinfo failed') + + +HTTPError +--------- + +Every HTTP response from the server contains a numeric "status code". Sometimes +the status code indicates that the server is unable to fulfil the request. The +default handlers will handle some of these responses for you (for example, if +the response is a "redirection" that requests the client fetch the document from +a different URL, urllib2 will handle that for you). For those it can't handle, +urlopen will raise an ``HTTPError``. Typical errors include '404' (page not +found), '403' (request forbidden), and '401' (authentication required). + +See section 10 of RFC 2616 for a reference on all the HTTP error codes. + +The ``HTTPError`` instance raised will have an integer 'code' attribute, which +corresponds to the error sent by the server. + +Error Codes +~~~~~~~~~~~ + +Because the default handlers handle redirects (codes in the 300 range), and +codes in the 100-299 range indicate success, you will usually only see error +codes in the 400-599 range. + +``BaseHTTPServer.BaseHTTPRequestHandler.responses`` is a useful dictionary of +response codes in that shows all the response codes used by RFC 2616. The +dictionary is reproduced here for convenience :: + + # Table mapping response codes to messages; entries have the + # form {code: (shortmessage, longmessage)}. + responses = { + 100: ('Continue', 'Request received, please continue'), + 101: ('Switching Protocols', + 'Switching to new protocol; obey Upgrade header'), + + 200: ('OK', 'Request fulfilled, document follows'), + 201: ('Created', 'Document created, URL follows'), + 202: ('Accepted', + 'Request accepted, processing continues off-line'), + 203: ('Non-Authoritative Information', 'Request fulfilled from cache'), + 204: ('No Content', 'Request fulfilled, nothing follows'), + 205: ('Reset Content', 'Clear input form for further input.'), + 206: ('Partial Content', 'Partial content follows.'), + + 300: ('Multiple Choices', + 'Object has several resources -- see URI list'), + 301: ('Moved Permanently', 'Object moved permanently -- see URI list'), + 302: ('Found', 'Object moved temporarily -- see URI list'), + 303: ('See Other', 'Object moved -- see Method and URL list'), + 304: ('Not Modified', + 'Document has not changed since given time'), + 305: ('Use Proxy', + 'You must use proxy specified in Location to access this ' + 'resource.'), + 307: ('Temporary Redirect', + 'Object moved temporarily -- see URI list'), + + 400: ('Bad Request', + 'Bad request syntax or unsupported method'), + 401: ('Unauthorized', + 'No permission -- see authorization schemes'), + 402: ('Payment Required', + 'No payment -- see charging schemes'), + 403: ('Forbidden', + 'Request forbidden -- authorization will not help'), + 404: ('Not Found', 'Nothing matches the given URI'), + 405: ('Method Not Allowed', + 'Specified method is invalid for this server.'), + 406: ('Not Acceptable', 'URI not available in preferred format.'), + 407: ('Proxy Authentication Required', 'You must authenticate with ' + 'this proxy before proceeding.'), + 408: ('Request Timeout', 'Request timed out; try again later.'), + 409: ('Conflict', 'Request conflict.'), + 410: ('Gone', + 'URI no longer exists and has been permanently removed.'), + 411: ('Length Required', 'Client must specify Content-Length.'), + 412: ('Precondition Failed', 'Precondition in headers is false.'), + 413: ('Request Entity Too Large', 'Entity is too large.'), + 414: ('Request-URI Too Long', 'URI is too long.'), + 415: ('Unsupported Media Type', 'Entity body in unsupported format.'), + 416: ('Requested Range Not Satisfiable', + 'Cannot satisfy request range.'), + 417: ('Expectation Failed', + 'Expect condition could not be satisfied.'), + + 500: ('Internal Server Error', 'Server got itself in trouble'), + 501: ('Not Implemented', + 'Server does not support this operation'), + 502: ('Bad Gateway', 'Invalid responses from another server/proxy.'), + 503: ('Service Unavailable', + 'The server cannot process the request due to a high load'), + 504: ('Gateway Timeout', + 'The gateway server did not receive a timely response'), + 505: ('HTTP Version Not Supported', 'Cannot fulfill request.'), + } + +When an error is raised the server responds by returning an HTTP error code +*and* an error page. You can use the ``HTTPError`` instance as a response on the +page returned. This means that as well as the code attribute, it also has read, +geturl, and info, methods. :: + + >>> req = urllib2.Request('http://www.python.org/fish.html') + >>> try: + >>> urllib2.urlopen(req) + >>> except URLError, e: + >>> print e.code + >>> print e.read() + >>> + 404 + + + Error 404: File Not Found + ...... etc... + +Wrapping it Up +-------------- + +So if you want to be prepared for ``HTTPError`` *or* ``URLError`` there are two +basic approaches. I prefer the second approach. + +Number 1 +~~~~~~~~ + +:: + + + from urllib2 import Request, urlopen, URLError, HTTPError + req = Request(someurl) + try: + response = urlopen(req) + except HTTPError, e: + print 'The server couldn\'t fulfill the request.' + print 'Error code: ', e.code + except URLError, e: + print 'We failed to reach a server.' + print 'Reason: ', e.reason + else: + # everything is fine + + +.. note:: + + The ``except HTTPError`` *must* come first, otherwise ``except URLError`` + will *also* catch an ``HTTPError``. + +Number 2 +~~~~~~~~ + +:: + + from urllib2 import Request, urlopen, URLError + req = Request(someurl) + try: + response = urlopen(req) + except URLError, e: + if hasattr(e, 'reason'): + print 'We failed to reach a server.' + print 'Reason: ', e.reason + elif hasattr(e, 'code'): + print 'The server couldn\'t fulfill the request.' + print 'Error code: ', e.code + else: + # everything is fine + + +info and geturl +=============== + +The response returned by urlopen (or the ``HTTPError`` instance) has two useful +methods ``info`` and ``geturl``. + +**geturl** - this returns the real URL of the page fetched. This is useful +because ``urlopen`` (or the opener object used) may have followed a +redirect. The URL of the page fetched may not be the same as the URL requested. + +**info** - this returns a dictionary-like object that describes the page +fetched, particularly the headers sent by the server. It is currently an +``httplib.HTTPMessage`` instance. + +Typical headers include 'Content-length', 'Content-type', and so on. See the +`Quick Reference to HTTP Headers `_ +for a useful listing of HTTP headers with brief explanations of their meaning +and use. + + +Openers and Handlers +==================== + +When you fetch a URL you use an opener (an instance of the perhaps +confusingly-named :class:`urllib2.OpenerDirector`). Normally we have been using +the default opener - via ``urlopen`` - but you can create custom +openers. Openers use handlers. All the "heavy lifting" is done by the +handlers. Each handler knows how to open URLs for a particular URL scheme (http, +ftp, etc.), or how to handle an aspect of URL opening, for example HTTP +redirections or HTTP cookies. + +You will want to create openers if you want to fetch URLs with specific handlers +installed, for example to get an opener that handles cookies, or to get an +opener that does not handle redirections. + +To create an opener, instantiate an ``OpenerDirector``, and then call +``.add_handler(some_handler_instance)`` repeatedly. + +Alternatively, you can use ``build_opener``, which is a convenience function for +creating opener objects with a single function call. ``build_opener`` adds +several handlers by default, but provides a quick way to add more and/or +override the default handlers. + +Other sorts of handlers you might want to can handle proxies, authentication, +and other common but slightly specialised situations. + +``install_opener`` can be used to make an ``opener`` object the (global) default +opener. This means that calls to ``urlopen`` will use the opener you have +installed. + +Opener objects have an ``open`` method, which can be called directly to fetch +urls in the same way as the ``urlopen`` function: there's no need to call +``install_opener``, except as a convenience. + + +Basic Authentication +==================== + +To illustrate creating and installing a handler we will use the +``HTTPBasicAuthHandler``. For a more detailed discussion of this subject - +including an explanation of how Basic Authentication works - see the `Basic +Authentication Tutorial +`_. + +When authentication is required, the server sends a header (as well as the 401 +error code) requesting authentication. This specifies the authentication scheme +and a 'realm'. The header looks like : ``Www-authenticate: SCHEME +realm="REALM"``. + +e.g. :: + + Www-authenticate: Basic realm="cPanel Users" + + +The client should then retry the request with the appropriate name and password +for the realm included as a header in the request. This is 'basic +authentication'. In order to simplify this process we can create an instance of +``HTTPBasicAuthHandler`` and an opener to use this handler. + +The ``HTTPBasicAuthHandler`` uses an object called a password manager to handle +the mapping of URLs and realms to passwords and usernames. If you know what the +realm is (from the authentication header sent by the server), then you can use a +``HTTPPasswordMgr``. Frequently one doesn't care what the realm is. In that +case, it is convenient to use ``HTTPPasswordMgrWithDefaultRealm``. This allows +you to specify a default username and password for a URL. This will be supplied +in the absence of you providing an alternative combination for a specific +realm. We indicate this by providing ``None`` as the realm argument to the +``add_password`` method. + +The top-level URL is the first URL that requires authentication. URLs "deeper" +than the URL you pass to .add_password() will also match. :: + + # create a password manager + password_mgr = urllib2.HTTPPasswordMgrWithDefaultRealm() + + # Add the username and password. + # If we knew the realm, we could use it instead of ``None``. + top_level_url = "http://example.com/foo/" + password_mgr.add_password(None, top_level_url, username, password) + + handler = urllib2.HTTPBasicAuthHandler(password_mgr) + + # create "opener" (OpenerDirector instance) + opener = urllib2.build_opener(handler) + + # use the opener to fetch a URL + opener.open(a_url) + + # Install the opener. + # Now all calls to urllib2.urlopen use our opener. + urllib2.install_opener(opener) + +.. note:: + + In the above example we only supplied our ``HHTPBasicAuthHandler`` to + ``build_opener``. By default openers have the handlers for normal situations + -- ``ProxyHandler``, ``UnknownHandler``, ``HTTPHandler``, + ``HTTPDefaultErrorHandler``, ``HTTPRedirectHandler``, ``FTPHandler``, + ``FileHandler``, ``HTTPErrorProcessor``. + +``top_level_url`` is in fact *either* a full URL (including the 'http:' scheme +component and the hostname and optionally the port number) +e.g. "http://example.com/" *or* an "authority" (i.e. the hostname, +optionally including the port number) e.g. "example.com" or "example.com:8080" +(the latter example includes a port number). The authority, if present, must +NOT contain the "userinfo" component - for example "joe at password:example.com" is +not correct. + + +Proxies +======= + +**urllib2** will auto-detect your proxy settings and use those. This is through +the ``ProxyHandler`` which is part of the normal handler chain. Normally that's +a good thing, but there are occasions when it may not be helpful [#]_. One way +to do this is to setup our own ``ProxyHandler``, with no proxies defined. This +is done using similar steps to setting up a `Basic Authentication`_ handler : :: + + >>> proxy_support = urllib2.ProxyHandler({}) + >>> opener = urllib2.build_opener(proxy_support) + >>> urllib2.install_opener(opener) + +.. note:: + + Currently ``urllib2`` *does not* support fetching of ``https`` locations + through a proxy. This can be a problem. + +Sockets and Layers +================== + +The Python support for fetching resources from the web is layered. urllib2 uses +the httplib library, which in turn uses the socket library. + +As of Python 2.3 you can specify how long a socket should wait for a response +before timing out. This can be useful in applications which have to fetch web +pages. By default the socket module has *no timeout* and can hang. Currently, +the socket timeout is not exposed at the httplib or urllib2 levels. However, +you can set the default timeout globally for all sockets using :: + + import socket + import urllib2 + + # timeout in seconds + timeout = 10 + socket.setdefaulttimeout(timeout) + + # this call to urllib2.urlopen now uses the default timeout + # we have set in the socket module + req = urllib2.Request('http://www.voidspace.org.uk') + response = urllib2.urlopen(req) + + +------- + + +Footnotes +========= + +This document was reviewed and revised by John Lee. + +.. [#] For an introduction to the CGI protocol see + `Writing Web Applications in Python `_. +.. [#] Like Google for example. The *proper* way to use google from a program + is to use `PyGoogle `_ of course. See + `Voidspace Google `_ + for some examples of using the Google API. +.. [#] Browser sniffing is a very bad practise for website design - building + sites using web standards is much more sensible. Unfortunately a lot of + sites still send different versions to different browsers. +.. [#] The user agent for MSIE 6 is + *'Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 1.1.4322)'* +.. [#] For details of more HTTP request headers, see + `Quick Reference to HTTP Headers`_. +.. [#] In my case I have to use a proxy to access the internet at work. If you + attempt to fetch *localhost* URLs through this proxy it blocks them. IE + is set to use the proxy, which urllib2 picks up on. In order to test + scripts with a localhost server, I have to prevent urllib2 from using + the proxy. Modified: doctools/trunk/Doc-3k/ACKS ============================================================================== --- doctools/trunk/Doc-3k/ACKS (original) +++ doctools/trunk/Doc-3k/ACKS Thu Aug 2 23:31:34 2007 @@ -15,7 +15,7 @@ * Steve Alexander * Jim Ahlstrom * Fred Allen -* A. Amoroso +* \A. Amoroso * Pehr Anderson * Oliver Andrich * Jes?s Cea Avi?n @@ -40,7 +40,7 @@ * Jeremy Craven * Andrew Dalke * Ben Darnell -* L. Peter Deutsch +* \L. Peter Deutsch * Robert Donohue * Fred L. Drake, Jr. * Jeff Epler Modified: doctools/trunk/Doc-3k/TODO ============================================================================== --- doctools/trunk/Doc-3k/TODO (original) +++ doctools/trunk/Doc-3k/TODO Thu Aug 2 23:31:34 2007 @@ -2,7 +2,6 @@ ====================== * split very large files and add toctrees -* integrate standalone HOWTOs * find out which files get "comments disabled" metadata * write "About these documents" * finish "Documenting Python" Modified: doctools/trunk/Doc-3k/contents.rst ============================================================================== --- doctools/trunk/Doc-3k/contents.rst (original) +++ doctools/trunk/Doc-3k/contents.rst Thu Aug 2 23:31:34 2007 @@ -14,6 +14,7 @@ distutils/index.rst install/index.rst documenting/index.rst + howto/index.rst bugs.rst about.rst Added: doctools/trunk/Doc-3k/howto/advocacy.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-3k/howto/advocacy.rst Thu Aug 2 23:31:34 2007 @@ -0,0 +1,356 @@ +************************* + Python Advocacy HOWTO +************************* + +:Author: A.M. Kuchling +:Release: 0.03 + + +.. topic:: Abstract + + It's usually difficult to get your management to accept open source software, + and Python is no exception to this rule. This document discusses reasons to use + Python, strategies for winning acceptance, facts and arguments you can use, and + cases where you *shouldn't* try to use Python. + + +Reasons to Use Python +===================== + +There are several reasons to incorporate a scripting language into your +development process, and this section will discuss them, and why Python has some +properties that make it a particularly good choice. + + +Programmability +--------------- + +Programs are often organized in a modular fashion. Lower-level operations are +grouped together, and called by higher-level functions, which may in turn be +used as basic operations by still further upper levels. + +For example, the lowest level might define a very low-level set of functions for +accessing a hash table. The next level might use hash tables to store the +headers of a mail message, mapping a header name like ``Date`` to a value such +as ``Tue, 13 May 1997 20:00:54 -0400``. A yet higher level may operate on +message objects, without knowing or caring that message headers are stored in a +hash table, and so forth. + +Often, the lowest levels do very simple things; they implement a data structure +such as a binary tree or hash table, or they perform some simple computation, +such as converting a date string to a number. The higher levels then contain +logic connecting these primitive operations. Using the approach, the primitives +can be seen as basic building blocks which are then glued together to produce +the complete product. + +Why is this design approach relevant to Python? Because Python is well suited +to functioning as such a glue language. A common approach is to write a Python +module that implements the lower level operations; for the sake of speed, the +implementation might be in C, Java, or even Fortran. Once the primitives are +available to Python programs, the logic underlying higher level operations is +written in the form of Python code. The high-level logic is then more +understandable, and easier to modify. + +John Ousterhout wrote a paper that explains this idea at greater length, +entitled "Scripting: Higher Level Programming for the 21st Century". I +recommend that you read this paper; see the references for the URL. Ousterhout +is the inventor of the Tcl language, and therefore argues that Tcl should be +used for this purpose; he only briefly refers to other languages such as Python, +Perl, and Lisp/Scheme, but in reality, Ousterhout's argument applies to +scripting languages in general, since you could equally write extensions for any +of the languages mentioned above. + + +Prototyping +----------- + +In *The Mythical Man-Month*, Fredrick Brooks suggests the following rule when +planning software projects: "Plan to throw one away; you will anyway." Brooks +is saying that the first attempt at a software design often turns out to be +wrong; unless the problem is very simple or you're an extremely good designer, +you'll find that new requirements and features become apparent once development +has actually started. If these new requirements can't be cleanly incorporated +into the program's structure, you're presented with two unpleasant choices: +hammer the new features into the program somehow, or scrap everything and write +a new version of the program, taking the new features into account from the +beginning. + +Python provides you with a good environment for quickly developing an initial +prototype. That lets you get the overall program structure and logic right, and +you can fine-tune small details in the fast development cycle that Python +provides. Once you're satisfied with the GUI interface or program output, you +can translate the Python code into C++, Fortran, Java, or some other compiled +language. + +Prototyping means you have to be careful not to use too many Python features +that are hard to implement in your other language. Using ``eval()``, or regular +expressions, or the :mod:`pickle` module, means that you're going to need C or +Java libraries for formula evaluation, regular expressions, and serialization, +for example. But it's not hard to avoid such tricky code, and in the end the +translation usually isn't very difficult. The resulting code can be rapidly +debugged, because any serious logical errors will have been removed from the +prototype, leaving only more minor slip-ups in the translation to track down. + +This strategy builds on the earlier discussion of programmability. Using Python +as glue to connect lower-level components has obvious relevance for constructing +prototype systems. In this way Python can help you with development, even if +end users never come in contact with Python code at all. If the performance of +the Python version is adequate and corporate politics allow it, you may not need +to do a translation into C or Java, but it can still be faster to develop a +prototype and then translate it, instead of attempting to produce the final +version immediately. + +One example of this development strategy is Microsoft Merchant Server. Version +1.0 was written in pure Python, by a company that subsequently was purchased by +Microsoft. Version 2.0 began to translate the code into C++, shipping with some +C++code and some Python code. Version 3.0 didn't contain any Python at all; all +the code had been translated into C++. Even though the product doesn't contain +a Python interpreter, the Python language has still served a useful purpose by +speeding up development. + +This is a very common use for Python. Past conference papers have also +described this approach for developing high-level numerical algorithms; see +David M. Beazley and Peter S. Lomdahl's paper "Feeding a Large-scale Physics +Application to Python" in the references for a good example. If an algorithm's +basic operations are things like "Take the inverse of this 4000x4000 matrix", +and are implemented in some lower-level language, then Python has almost no +additional performance cost; the extra time required for Python to evaluate an +expression like ``m.invert()`` is dwarfed by the cost of the actual computation. +It's particularly good for applications where seemingly endless tweaking is +required to get things right. GUI interfaces and Web sites are prime examples. + +The Python code is also shorter and faster to write (once you're familiar with +Python), so it's easier to throw it away if you decide your approach was wrong; +if you'd spent two weeks working on it instead of just two hours, you might +waste time trying to patch up what you've got out of a natural reluctance to +admit that those two weeks were wasted. Truthfully, those two weeks haven't +been wasted, since you've learnt something about the problem and the technology +you're using to solve it, but it's human nature to view this as a failure of +some sort. + + +Simplicity and Ease of Understanding +------------------------------------ + +Python is definitely *not* a toy language that's only usable for small tasks. +The language features are general and powerful enough to enable it to be used +for many different purposes. It's useful at the small end, for 10- or 20-line +scripts, but it also scales up to larger systems that contain thousands of lines +of code. + +However, this expressiveness doesn't come at the cost of an obscure or tricky +syntax. While Python has some dark corners that can lead to obscure code, there +are relatively few such corners, and proper design can isolate their use to only +a few classes or modules. It's certainly possible to write confusing code by +using too many features with too little concern for clarity, but most Python +code can look a lot like a slightly-formalized version of human-understandable +pseudocode. + +In *The New Hacker's Dictionary*, Eric S. Raymond gives the following definition +for "compact": + +.. epigraph:: + + Compact *adj.* Of a design, describes the valuable property that it can all be + apprehended at once in one's head. This generally means the thing created from + the design can be used with greater facility and fewer errors than an equivalent + tool that is not compact. Compactness does not imply triviality or lack of + power; for example, C is compact and FORTRAN is not, but C is more powerful than + FORTRAN. Designs become non-compact through accreting features and cruft that + don't merge cleanly into the overall design scheme (thus, some fans of Classic C + maintain that ANSI C is no longer compact). + + (From http://www.catb.org/ esr/jargon/html/C/compact.html) + +In this sense of the word, Python is quite compact, because the language has +just a few ideas, which are used in lots of places. Take namespaces, for +example. Import a module with ``import math``, and you create a new namespace +called ``math``. Classes are also namespaces that share many of the properties +of modules, and have a few of their own; for example, you can create instances +of a class. Instances? They're yet another namespace. Namespaces are currently +implemented as Python dictionaries, so they have the same methods as the +standard dictionary data type: .keys() returns all the keys, and so forth. + +This simplicity arises from Python's development history. The language syntax +derives from different sources; ABC, a relatively obscure teaching language, is +one primary influence, and Modula-3 is another. (For more information about ABC +and Modula-3, consult their respective Web sites at http://www.cwi.nl/ +steven/abc/ and http://www.m3.org.) Other features have come from C, Icon, +Algol-68, and even Perl. Python hasn't really innovated very much, but instead +has tried to keep the language small and easy to learn, building on ideas that +have been tried in other languages and found useful. + +Simplicity is a virtue that should not be underestimated. It lets you learn the +language more quickly, and then rapidly write code, code that often works the +first time you run it. + + +Java Integration +---------------- + +If you're working with Java, Jython (http://www.jython.org/) is definitely worth +your attention. Jython is a re-implementation of Python in Java that compiles +Python code into Java bytecodes. The resulting environment has very tight, +almost seamless, integration with Java. It's trivial to access Java classes +from Python, and you can write Python classes that subclass Java classes. +Jython can be used for prototyping Java applications in much the same way +CPython is used, and it can also be used for test suites for Java code, or +embedded in a Java application to add scripting capabilities. + + +Arguments and Rebuttals +======================= + +Let's say that you've decided upon Python as the best choice for your +application. How can you convince your management, or your fellow developers, +to use Python? This section lists some common arguments against using Python, +and provides some possible rebuttals. + +**Python is freely available software that doesn't cost anything. How good can +it be?** + +Very good, indeed. These days Linux and Apache, two other pieces of open source +software, are becoming more respected as alternatives to commercial software, +but Python hasn't had all the publicity. + +Python has been around for several years, with many users and developers. +Accordingly, the interpreter has been used by many people, and has gotten most +of the bugs shaken out of it. While bugs are still discovered at intervals, +they're usually either quite obscure (they'd have to be, for no one to have run +into them before) or they involve interfaces to external libraries. The +internals of the language itself are quite stable. + +Having the source code should be viewed as making the software available for +peer review; people can examine the code, suggest (and implement) improvements, +and track down bugs. To find out more about the idea of open source code, along +with arguments and case studies supporting it, go to http://www.opensource.org. + +**Who's going to support it?** + +Python has a sizable community of developers, and the number is still growing. +The Internet community surrounding the language is an active one, and is worth +being considered another one of Python's advantages. Most questions posted to +the comp.lang.python newsgroup are quickly answered by someone. + +Should you need to dig into the source code, you'll find it's clear and well- +organized, so it's not very difficult to write extensions and track down bugs +yourself. If you'd prefer to pay for support, there are companies and +individuals who offer commercial support for Python. + +**Who uses Python for serious work?** + +Lots of people; one interesting thing about Python is the surprising diversity +of applications that it's been used for. People are using Python to: + +* Run Web sites + +* Write GUI interfaces + +* Control number-crunching code on supercomputers + +* Make a commercial application scriptable by embedding the Python interpreter + inside it + +* Process large XML data sets + +* Build test suites for C or Java code + +Whatever your application domain is, there's probably someone who's used Python +for something similar. Yet, despite being useable for such high-end +applications, Python's still simple enough to use for little jobs. + +See http://wiki.python.org/moin/OrganizationsUsingPython for a list of some of +the organizations that use Python. + +**What are the restrictions on Python's use?** + +They're practically nonexistent. Consult the :file:`Misc/COPYRIGHT` file in the +source distribution, or http://www.python.org/doc/Copyright.html for the full +language, but it boils down to three conditions. + +* You have to leave the copyright notice on the software; if you don't include + the source code in a product, you have to put the copyright notice in the + supporting documentation. + +* Don't claim that the institutions that have developed Python endorse your + product in any way. + +* If something goes wrong, you can't sue for damages. Practically all software + licences contain this condition. + +Notice that you don't have to provide source code for anything that contains +Python or is built with it. Also, the Python interpreter and accompanying +documentation can be modified and redistributed in any way you like, and you +don't have to pay anyone any licensing fees at all. + +**Why should we use an obscure language like Python instead of well-known +language X?** + +I hope this HOWTO, and the documents listed in the final section, will help +convince you that Python isn't obscure, and has a healthily growing user base. +One word of advice: always present Python's positive advantages, instead of +concentrating on language X's failings. People want to know why a solution is +good, rather than why all the other solutions are bad. So instead of attacking +a competing solution on various grounds, simply show how Python's virtues can +help. + + +Useful Resources +================ + +http://www.pythonology.com/success + The Python Success Stories are a collection of stories from successful users of + Python, with the emphasis on business and corporate users. + +.. % \term{\url{http://www.fsbassociates.com/books/pythonchpt1.htm}} +.. % The first chapter of \emph{Internet Programming with Python} also +.. % examines some of the reasons for using Python. The book is well worth +.. % buying, but the publishers have made the first chapter available on +.. % the Web. + +http://home.pacbell.net/ouster/scripting.html + John Ousterhout's white paper on scripting is a good argument for the utility of + scripting languages, though naturally enough, he emphasizes Tcl, the language he + developed. Most of the arguments would apply to any scripting language. + +http://www.python.org/workshops/1997-10/proceedings/beazley.html + The authors, David M. Beazley and Peter S. Lomdahl, describe their use of + Python at Los Alamos National Laboratory. It's another good example of how + Python can help get real work done. This quotation from the paper has been + echoed by many people: + + .. epigraph:: + + Originally developed as a large monolithic application for massively parallel + processing systems, we have used Python to transform our application into a + flexible, highly modular, and extremely powerful system for performing + simulation, data analysis, and visualization. In addition, we describe how + Python has solved a number of important problems related to the development, + debugging, deployment, and maintenance of scientific software. + +http://pythonjournal.cognizor.com/pyj1/Everitt-Feit_interview98-V1.html + This interview with Andy Feit, discussing Infoseek's use of Python, can be used + to show that choosing Python didn't introduce any difficulties into a company's + development process, and provided some substantial benefits. + +.. % \term{\url{http://www.python.org/psa/Commercial.html}} +.. % Robin Friedrich wrote this document on how to support Python's use in +.. % commercial projects. + +http://www.python.org/workshops/1997-10/proceedings/stein.ps + For the 6th Python conference, Greg Stein presented a paper that traced Python's + adoption and usage at a startup called eShop, and later at Microsoft. + +http://www.opensource.org + Management may be doubtful of the reliability and usefulness of software that + wasn't written commercially. This site presents arguments that show how open + source software can have considerable advantages over closed-source software. + +http://sunsite.unc.edu/LDP/HOWTO/mini/Advocacy.html + The Linux Advocacy mini-HOWTO was the inspiration for this document, and is also + well worth reading for general suggestions on winning acceptance for a new + technology, such as Linux or Python. In general, you won't make much progress + by simply attacking existing systems and complaining about their inadequacies; + this often ends up looking like unfocused whining. It's much better to point + out some of the many areas where Python is an improvement over other systems. + Added: doctools/trunk/Doc-3k/howto/curses.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-3k/howto/curses.rst Thu Aug 2 23:31:34 2007 @@ -0,0 +1,433 @@ +********************************** + Curses Programming with Python +********************************** + +:Author: A.M. Kuchling, Eric S. Raymond +:Release: 2.02 + + +.. topic:: Abstract + + This document describes how to write text-mode programs with Python 2.x, using + the :mod:`curses` extension module to control the display. + + +What is curses? +=============== + +The curses library supplies a terminal-independent screen-painting and keyboard- +handling facility for text-based terminals; such terminals include VT100s, the +Linux console, and the simulated terminal provided by X11 programs such as xterm +and rxvt. Display terminals support various control codes to perform common +operations such as moving the cursor, scrolling the screen, and erasing areas. +Different terminals use widely differing codes, and often have their own minor +quirks. + +In a world of X displays, one might ask "why bother"? It's true that character- +cell display terminals are an obsolete technology, but there are niches in which +being able to do fancy things with them are still valuable. One is on small- +footprint or embedded Unixes that don't carry an X server. Another is for +tools like OS installers and kernel configurators that may have to run before X +is available. + +The curses library hides all the details of different terminals, and provides +the programmer with an abstraction of a display, containing multiple non- +overlapping windows. The contents of a window can be changed in various ways-- +adding text, erasing it, changing its appearance--and the curses library will +automagically figure out what control codes need to be sent to the terminal to +produce the right output. + +The curses library was originally written for BSD Unix; the later System V +versions of Unix from AT&T added many enhancements and new functions. BSD curses +is no longer maintained, having been replaced by ncurses, which is an open- +source implementation of the AT&T interface. If you're using an open-source +Unix such as Linux or FreeBSD, your system almost certainly uses ncurses. Since +most current commercial Unix versions are based on System V code, all the +functions described here will probably be available. The older versions of +curses carried by some proprietary Unixes may not support everything, though. + +No one has made a Windows port of the curses module. On a Windows platform, try +the Console module written by Fredrik Lundh. The Console module provides +cursor-addressable text output, plus full support for mouse and keyboard input, +and is available from http://effbot.org/efflib/console. + + +The Python curses module +------------------------ + +Thy Python module is a fairly simple wrapper over the C functions provided by +curses; if you're already familiar with curses programming in C, it's really +easy to transfer that knowledge to Python. The biggest difference is that the +Python interface makes things simpler, by merging different C functions such as +:func:`addstr`, :func:`mvaddstr`, :func:`mvwaddstr`, into a single +:meth:`addstr` method. You'll see this covered in more detail later. + +This HOWTO is simply an introduction to writing text-mode programs with curses +and Python. It doesn't attempt to be a complete guide to the curses API; for +that, see the Python library guide's section on ncurses, and the C manual pages +for ncurses. It will, however, give you the basic ideas. + + +Starting and ending a curses application +======================================== + +Before doing anything, curses must be initialized. This is done by calling the +:func:`initscr` function, which will determine the terminal type, send any +required setup codes to the terminal, and create various internal data +structures. If successful, :func:`initscr` returns a window object representing +the entire screen; this is usually called ``stdscr``, after the name of the +corresponding C variable. :: + + import curses + stdscr = curses.initscr() + +Usually curses applications turn off automatic echoing of keys to the screen, in +order to be able to read keys and only display them under certain circumstances. +This requires calling the :func:`noecho` function. :: + + curses.noecho() + +Applications will also commonly need to react to keys instantly, without +requiring the Enter key to be pressed; this is called cbreak mode, as opposed to +the usual buffered input mode. :: + + curses.cbreak() + +Terminals usually return special keys, such as the cursor keys or navigation +keys such as Page Up and Home, as a multibyte escape sequence. While you could +write your application to expect such sequences and process them accordingly, +curses can do it for you, returning a special value such as +:const:`curses.KEY_LEFT`. To get curses to do the job, you'll have to enable +keypad mode. :: + + stdscr.keypad(1) + +Terminating a curses application is much easier than starting one. You'll need +to call :: + + curses.nocbreak(); stdscr.keypad(0); curses.echo() + +to reverse the curses-friendly terminal settings. Then call the :func:`endwin` +function to restore the terminal to its original operating mode. :: + + curses.endwin() + +A common problem when debugging a curses application is to get your terminal +messed up when the application dies without restoring the terminal to its +previous state. In Python this commonly happens when your code is buggy and +raises an uncaught exception. Keys are no longer be echoed to the screen when +you type them, for example, which makes using the shell difficult. + +In Python you can avoid these complications and make debugging much easier by +importing the module :mod:`curses.wrapper`. It supplies a :func:`wrapper` +function that takes a callable. It does the initializations described above, +and also initializes colors if color support is present. It then runs your +provided callable and finally deinitializes appropriately. The callable is +called inside a try-catch clause which catches exceptions, performs curses +deinitialization, and then passes the exception upwards. Thus, your terminal +won't be left in a funny state on exception. + + +Windows and Pads +================ + +Windows are the basic abstraction in curses. A window object represents a +rectangular area of the screen, and supports various methods to display text, +erase it, allow the user to input strings, and so forth. + +The ``stdscr`` object returned by the :func:`initscr` function is a window +object that covers the entire screen. Many programs may need only this single +window, but you might wish to divide the screen into smaller windows, in order +to redraw or clear them separately. The :func:`newwin` function creates a new +window of a given size, returning the new window object. :: + + begin_x = 20 ; begin_y = 7 + height = 5 ; width = 40 + win = curses.newwin(height, width, begin_y, begin_x) + +A word about the coordinate system used in curses: coordinates are always passed +in the order *y,x*, and the top-left corner of a window is coordinate (0,0). +This breaks a common convention for handling coordinates, where the *x* +coordinate usually comes first. This is an unfortunate difference from most +other computer applications, but it's been part of curses since it was first +written, and it's too late to change things now. + +When you call a method to display or erase text, the effect doesn't immediately +show up on the display. This is because curses was originally written with slow +300-baud terminal connections in mind; with these terminals, minimizing the time +required to redraw the screen is very important. This lets curses accumulate +changes to the screen, and display them in the most efficient manner. For +example, if your program displays some characters in a window, and then clears +the window, there's no need to send the original characters because they'd never +be visible. + +Accordingly, curses requires that you explicitly tell it to redraw windows, +using the :func:`refresh` method of window objects. In practice, this doesn't +really complicate programming with curses much. Most programs go into a flurry +of activity, and then pause waiting for a keypress or some other action on the +part of the user. All you have to do is to be sure that the screen has been +redrawn before pausing to wait for user input, by simply calling +``stdscr.refresh()`` or the :func:`refresh` method of some other relevant +window. + +A pad is a special case of a window; it can be larger than the actual display +screen, and only a portion of it displayed at a time. Creating a pad simply +requires the pad's height and width, while refreshing a pad requires giving the +coordinates of the on-screen area where a subsection of the pad will be +displayed. :: + + pad = curses.newpad(100, 100) + # These loops fill the pad with letters; this is + # explained in the next section + for y in range(0, 100): + for x in range(0, 100): + try: pad.addch(y,x, ord('a') + (x*x+y*y) % 26 ) + except curses.error: pass + + # Displays a section of the pad in the middle of the screen + pad.refresh( 0,0, 5,5, 20,75) + +The :func:`refresh` call displays a section of the pad in the rectangle +extending from coordinate (5,5) to coordinate (20,75) on the screen; the upper +left corner of the displayed section is coordinate (0,0) on the pad. Beyond +that difference, pads are exactly like ordinary windows and support the same +methods. + +If you have multiple windows and pads on screen there is a more efficient way to +go, which will prevent annoying screen flicker at refresh time. Use the +:meth:`noutrefresh` method of each window to update the data structure +representing the desired state of the screen; then change the physical screen to +match the desired state in one go with the function :func:`doupdate`. The +normal :meth:`refresh` method calls :func:`doupdate` as its last act. + + +Displaying Text +=============== + +From a C programmer's point of view, curses may sometimes look like a twisty +maze of functions, all subtly different. For example, :func:`addstr` displays a +string at the current cursor location in the ``stdscr`` window, while +:func:`mvaddstr` moves to a given y,x coordinate first before displaying the +string. :func:`waddstr` is just like :func:`addstr`, but allows specifying a +window to use, instead of using ``stdscr`` by default. :func:`mvwaddstr` follows +similarly. + +Fortunately the Python interface hides all these details; ``stdscr`` is a window +object like any other, and methods like :func:`addstr` accept multiple argument +forms. Usually there are four different forms. + ++---------------------------------+-----------------------------------------------+ +| Form | Description | ++=================================+===============================================+ +| *str* or *ch* | Display the string *str* or character *ch* at | +| | the current position | ++---------------------------------+-----------------------------------------------+ +| *str* or *ch*, *attr* | Display the string *str* or character *ch*, | +| | using attribute *attr* at the current | +| | position | ++---------------------------------+-----------------------------------------------+ +| *y*, *x*, *str* or *ch* | Move to position *y,x* within the window, and | +| | display *str* or *ch* | ++---------------------------------+-----------------------------------------------+ +| *y*, *x*, *str* or *ch*, *attr* | Move to position *y,x* within the window, and | +| | display *str* or *ch*, using attribute *attr* | ++---------------------------------+-----------------------------------------------+ + +Attributes allow displaying text in highlighted forms, such as in boldface, +underline, reverse code, or in color. They'll be explained in more detail in +the next subsection. + +The :func:`addstr` function takes a Python string as the value to be displayed, +while the :func:`addch` functions take a character, which can be either a Python +string of length 1 or an integer. If it's a string, you're limited to +displaying characters between 0 and 255. SVr4 curses provides constants for +extension characters; these constants are integers greater than 255. For +example, :const:`ACS_PLMINUS` is a +/- symbol, and :const:`ACS_ULCORNER` is the +upper left corner of a box (handy for drawing borders). + +Windows remember where the cursor was left after the last operation, so if you +leave out the *y,x* coordinates, the string or character will be displayed +wherever the last operation left off. You can also move the cursor with the +:func:`move(y,x)` method. Because some terminals always display a flashing +cursor, you may want to ensure that the cursor is positioned in some location +where it won't be distracting; it can be confusing to have the cursor blinking +at some apparently random location. + +If your application doesn't need a blinking cursor at all, you can call +:func:`curs_set(0)` to make it invisible. Equivalently, and for compatibility +with older curses versions, there's a :func:`leaveok(bool)` function. When +*bool* is true, the curses library will attempt to suppress the flashing cursor, +and you won't need to worry about leaving it in odd locations. + + +Attributes and Color +-------------------- + +Characters can be displayed in different ways. Status lines in a text-based +application are commonly shown in reverse video; a text viewer may need to +highlight certain words. curses supports this by allowing you to specify an +attribute for each cell on the screen. + +An attribute is a integer, each bit representing a different attribute. You can +try to display text with multiple attribute bits set, but curses doesn't +guarantee that all the possible combinations are available, or that they're all +visually distinct. That depends on the ability of the terminal being used, so +it's safest to stick to the most commonly available attributes, listed here. + ++----------------------+--------------------------------------+ +| Attribute | Description | ++======================+======================================+ +| :const:`A_BLINK` | Blinking text | ++----------------------+--------------------------------------+ +| :const:`A_BOLD` | Extra bright or bold text | ++----------------------+--------------------------------------+ +| :const:`A_DIM` | Half bright text | ++----------------------+--------------------------------------+ +| :const:`A_REVERSE` | Reverse-video text | ++----------------------+--------------------------------------+ +| :const:`A_STANDOUT` | The best highlighting mode available | ++----------------------+--------------------------------------+ +| :const:`A_UNDERLINE` | Underlined text | ++----------------------+--------------------------------------+ + +So, to display a reverse-video status line on the top line of the screen, you +could code:: + + stdscr.addstr(0, 0, "Current mode: Typing mode", + curses.A_REVERSE) + stdscr.refresh() + +The curses library also supports color on those terminals that provide it, The +most common such terminal is probably the Linux console, followed by color +xterms. + +To use color, you must call the :func:`start_color` function soon after calling +:func:`initscr`, to initialize the default color set (the +:func:`curses.wrapper.wrapper` function does this automatically). Once that's +done, the :func:`has_colors` function returns TRUE if the terminal in use can +actually display color. (Note: curses uses the American spelling 'color', +instead of the Canadian/British spelling 'colour'. If you're used to the +British spelling, you'll have to resign yourself to misspelling it for the sake +of these functions.) + +The curses library maintains a finite number of color pairs, containing a +foreground (or text) color and a background color. You can get the attribute +value corresponding to a color pair with the :func:`color_pair` function; this +can be bitwise-OR'ed with other attributes such as :const:`A_REVERSE`, but +again, such combinations are not guaranteed to work on all terminals. + +An example, which displays a line of text using color pair 1:: + + stdscr.addstr( "Pretty text", curses.color_pair(1) ) + stdscr.refresh() + +As I said before, a color pair consists of a foreground and background color. +:func:`start_color` initializes 8 basic colors when it activates color mode. +They are: 0:black, 1:red, 2:green, 3:yellow, 4:blue, 5:magenta, 6:cyan, and +7:white. The curses module defines named constants for each of these colors: +:const:`curses.COLOR_BLACK`, :const:`curses.COLOR_RED`, and so forth. + +The :func:`init_pair(n, f, b)` function changes the definition of color pair +*n*, to foreground color f and background color b. Color pair 0 is hard-wired +to white on black, and cannot be changed. + +Let's put all this together. To change color 1 to red text on a white +background, you would call:: + + curses.init_pair(1, curses.COLOR_RED, curses.COLOR_WHITE) + +When you change a color pair, any text already displayed using that color pair +will change to the new colors. You can also display new text in this color +with:: + + stdscr.addstr(0,0, "RED ALERT!", curses.color_pair(1) ) + +Very fancy terminals can change the definitions of the actual colors to a given +RGB value. This lets you change color 1, which is usually red, to purple or +blue or any other color you like. Unfortunately, the Linux console doesn't +support this, so I'm unable to try it out, and can't provide any examples. You +can check if your terminal can do this by calling :func:`can_change_color`, +which returns TRUE if the capability is there. If you're lucky enough to have +such a talented terminal, consult your system's man pages for more information. + + +User Input +========== + +The curses library itself offers only very simple input mechanisms. Python's +support adds a text-input widget that makes up some of the lack. + +The most common way to get input to a window is to use its :meth:`getch` method. +:meth:`getch` pauses and waits for the user to hit a key, displaying it if +:func:`echo` has been called earlier. You can optionally specify a coordinate +to which the cursor should be moved before pausing. + +It's possible to change this behavior with the method :meth:`nodelay`. After +:meth:`nodelay(1)`, :meth:`getch` for the window becomes non-blocking and +returns ``curses.ERR`` (a value of -1) when no input is ready. There's also a +:func:`halfdelay` function, which can be used to (in effect) set a timer on each +:meth:`getch`; if no input becomes available within the number of milliseconds +specified as the argument to :func:`halfdelay`, curses raises an exception. + +The :meth:`getch` method returns an integer; if it's between 0 and 255, it +represents the ASCII code of the key pressed. Values greater than 255 are +special keys such as Page Up, Home, or the cursor keys. You can compare the +value returned to constants such as :const:`curses.KEY_PPAGE`, +:const:`curses.KEY_HOME`, or :const:`curses.KEY_LEFT`. Usually the main loop of +your program will look something like this:: + + while 1: + c = stdscr.getch() + if c == ord('p'): PrintDocument() + elif c == ord('q'): break # Exit the while() + elif c == curses.KEY_HOME: x = y = 0 + +The :mod:`curses.ascii` module supplies ASCII class membership functions that +take either integer or 1-character-string arguments; these may be useful in +writing more readable tests for your command interpreters. It also supplies +conversion functions that take either integer or 1-character-string arguments +and return the same type. For example, :func:`curses.ascii.ctrl` returns the +control character corresponding to its argument. + +There's also a method to retrieve an entire string, :const:`getstr()`. It isn't +used very often, because its functionality is quite limited; the only editing +keys available are the backspace key and the Enter key, which terminates the +string. It can optionally be limited to a fixed number of characters. :: + + curses.echo() # Enable echoing of characters + + # Get a 15-character string, with the cursor on the top line + s = stdscr.getstr(0,0, 15) + +The Python :mod:`curses.textpad` module supplies something better. With it, you +can turn a window into a text box that supports an Emacs-like set of +keybindings. Various methods of :class:`Textbox` class support editing with +input validation and gathering the edit results either with or without trailing +spaces. See the library documentation on :mod:`curses.textpad` for the +details. + + +For More Information +==================== + +This HOWTO didn't cover some advanced topics, such as screen-scraping or +capturing mouse events from an xterm instance. But the Python library page for +the curses modules is now pretty complete. You should browse it next. + +If you're in doubt about the detailed behavior of any of the ncurses entry +points, consult the manual pages for your curses implementation, whether it's +ncurses or a proprietary Unix vendor's. The manual pages will document any +quirks, and provide complete lists of all the functions, attributes, and +:const:`ACS_\*` characters available to you. + +Because the curses API is so large, some functions aren't supported in the +Python interface, not because they're difficult to implement, but because no one +has needed them yet. Feel free to add them and then submit a patch. Also, we +don't yet have support for the menus or panels libraries associated with +ncurses; feel free to add that. + +If you write an interesting little program, feel free to contribute it as +another demo. We can always use more of them! + +The ncurses FAQ: http://dickey.his.com/ncurses/ncurses.faq.html + Added: doctools/trunk/Doc-3k/howto/doanddont.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-3k/howto/doanddont.rst Thu Aug 2 23:31:34 2007 @@ -0,0 +1,308 @@ +************************************ + Idioms and Anti-Idioms in Python +************************************ + +:Author: Moshe Zadka + +This document is placed in the public doman. + + +.. topic:: Abstract + + This document can be considered a companion to the tutorial. It shows how to use + Python, and even more importantly, how *not* to use Python. + + +Language Constructs You Should Not Use +====================================== + +While Python has relatively few gotchas compared to other languages, it still +has some constructs which are only useful in corner cases, or are plain +dangerous. + + +from module import \* +--------------------- + + +Inside Function Definitions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``from module import *`` is *invalid* inside function definitions. While many +versions of Python do not check for the invalidity, it does not make it more +valid, no more then having a smart lawyer makes a man innocent. Do not use it +like that ever. Even in versions where it was accepted, it made the function +execution slower, because the compiler could not be certain which names are +local and which are global. In Python 2.1 this construct causes warnings, and +sometimes even errors. + + +At Module Level +^^^^^^^^^^^^^^^ + +While it is valid to use ``from module import *`` at module level it is usually +a bad idea. For one, this loses an important property Python otherwise has --- +you can know where each toplevel name is defined by a simple "search" function +in your favourite editor. You also open yourself to trouble in the future, if +some module grows additional functions or classes. + +One of the most awful question asked on the newsgroup is why this code:: + + f = open("www") + f.read() + +does not work. Of course, it works just fine (assuming you have a file called +"www".) But it does not work if somewhere in the module, the statement ``from os +import *`` is present. The :mod:`os` module has a function called :func:`open` +which returns an integer. While it is very useful, shadowing builtins is one of +its least useful properties. + +Remember, you can never know for sure what names a module exports, so either +take what you need --- ``from module import name1, name2``, or keep them in the +module and access on a per-need basis --- ``import module;print module.name``. + + +When It Is Just Fine +^^^^^^^^^^^^^^^^^^^^ + +There are situations in which ``from module import *`` is just fine: + +* The interactive prompt. For example, ``from math import *`` makes Python an + amazing scientific calculator. + +* When extending a module in C with a module in Python. + +* When the module advertises itself as ``from import *`` safe. + + +Unadorned :keyword:`exec`, :func:`execfile` and friends +------------------------------------------------------- + +The word "unadorned" refers to the use without an explicit dictionary, in which +case those constructs evaluate code in the *current* environment. This is +dangerous for the same reasons ``from import *`` is dangerous --- it might step +over variables you are counting on and mess up things for the rest of your code. +Simply do not do that. + +Bad examples:: + + >>> for name in sys.argv[1:]: + >>> exec "%s=1" % name + >>> def func(s, **kw): + >>> for var, val in kw.items(): + >>> exec "s.%s=val" % var # invalid! + >>> execfile("handler.py") + >>> handle() + +Good examples:: + + >>> d = {} + >>> for name in sys.argv[1:]: + >>> d[name] = 1 + >>> def func(s, **kw): + >>> for var, val in kw.items(): + >>> setattr(s, var, val) + >>> d={} + >>> execfile("handle.py", d, d) + >>> handle = d['handle'] + >>> handle() + + +from module import name1, name2 +------------------------------- + +This is a "don't" which is much weaker then the previous "don't"s but is still +something you should not do if you don't have good reasons to do that. The +reason it is usually bad idea is because you suddenly have an object which lives +in two seperate namespaces. When the binding in one namespace changes, the +binding in the other will not, so there will be a discrepancy between them. This +happens when, for example, one module is reloaded, or changes the definition of +a function at runtime. + +Bad example:: + + # foo.py + a = 1 + + # bar.py + from foo import a + if something(): + a = 2 # danger: foo.a != a + +Good example:: + + # foo.py + a = 1 + + # bar.py + import foo + if something(): + foo.a = 2 + + +except: +------- + +Python has the ``except:`` clause, which catches all exceptions. Since *every* +error in Python raises an exception, this makes many programming errors look +like runtime problems, and hinders the debugging process. + +The following code shows a great example:: + + try: + foo = opne("file") # misspelled "open" + except: + sys.exit("could not open file!") + +The second line triggers a :exc:`NameError` which is caught by the except +clause. The program will exit, and you will have no idea that this has nothing +to do with the readability of ``"file"``. + +The example above is better written :: + + try: + foo = opne("file") # will be changed to "open" as soon as we run it + except IOError: + sys.exit("could not open file") + +There are some situations in which the ``except:`` clause is useful: for +example, in a framework when running callbacks, it is good not to let any +callback disturb the framework. + + +Exceptions +========== + +Exceptions are a useful feature of Python. You should learn to raise them +whenever something unexpected occurs, and catch them only where you can do +something about them. + +The following is a very popular anti-idiom :: + + def get_status(file): + if not os.path.exists(file): + print "file not found" + sys.exit(1) + return open(file).readline() + +Consider the case the file gets deleted between the time the call to +:func:`os.path.exists` is made and the time :func:`open` is called. That means +the last line will throw an :exc:`IOError`. The same would happen if *file* +exists but has no read permission. Since testing this on a normal machine on +existing and non-existing files make it seem bugless, that means in testing the +results will seem fine, and the code will get shipped. Then an unhandled +:exc:`IOError` escapes to the user, who has to watch the ugly traceback. + +Here is a better way to do it. :: + + def get_status(file): + try: + return open(file).readline() + except (IOError, OSError): + print "file not found" + sys.exit(1) + +In this version, \*either\* the file gets opened and the line is read (so it +works even on flaky NFS or SMB connections), or the message is printed and the +application aborted. + +Still, :func:`get_status` makes too many assumptions --- that it will only be +used in a short running script, and not, say, in a long running server. Sure, +the caller could do something like :: + + try: + status = get_status(log) + except SystemExit: + status = None + +So, try to make as few ``except`` clauses in your code --- those will usually be +a catch-all in the :func:`main`, or inside calls which should always succeed. + +So, the best version is probably :: + + def get_status(file): + return open(file).readline() + +The caller can deal with the exception if it wants (for example, if it tries +several files in a loop), or just let the exception filter upwards to *its* +caller. + +The last version is not very good either --- due to implementation details, the +file would not be closed when an exception is raised until the handler finishes, +and perhaps not at all in non-C implementations (e.g., Jython). :: + + def get_status(file): + fp = open(file) + try: + return fp.readline() + finally: + fp.close() + + +Using the Batteries +=================== + +Every so often, people seem to be writing stuff in the Python library again, +usually poorly. While the occasional module has a poor interface, it is usually +much better to use the rich standard library and data types that come with +Python then inventing your own. + +A useful module very few people know about is :mod:`os.path`. It always has the +correct path arithmetic for your operating system, and will usually be much +better then whatever you come up with yourself. + +Compare:: + + # ugh! + return dir+"/"+file + # better + return os.path.join(dir, file) + +More useful functions in :mod:`os.path`: :func:`basename`, :func:`dirname` and +:func:`splitext`. + +There are also many useful builtin functions people seem not to be aware of for +some reason: :func:`min` and :func:`max` can find the minimum/maximum of any +sequence with comparable semantics, for example, yet many people write their own +:func:`max`/:func:`min`. Another highly useful function is :func:`reduce`. A +classical use of :func:`reduce` is something like :: + + import sys, operator + nums = map(float, sys.argv[1:]) + print reduce(operator.add, nums)/len(nums) + +This cute little script prints the average of all numbers given on the command +line. The :func:`reduce` adds up all the numbers, and the rest is just some pre- +and postprocessing. + +On the same note, note that :func:`float`, :func:`int` and :func:`long` all +accept arguments of type string, and so are suited to parsing --- assuming you +are ready to deal with the :exc:`ValueError` they raise. + + +Using Backslash to Continue Statements +====================================== + +Since Python treats a newline as a statement terminator, and since statements +are often more then is comfortable to put in one line, many people do:: + + if foo.bar()['first'][0] == baz.quux(1, 2)[5:9] and \ + calculate_number(10, 20) != forbulate(500, 360): + pass + +You should realize that this is dangerous: a stray space after the ``XXX`` would +make this line wrong, and stray spaces are notoriously hard to see in editors. +In this case, at least it would be a syntax error, but if the code was:: + + value = foo.bar()['first'][0]*baz.quux(1, 2)[5:9] \ + + calculate_number(10, 20)*forbulate(500, 360) + +then it would just be subtly wrong. + +It is usually much better to use the implicit continuation inside parenthesis: + +This version is bulletproof:: + + value = (foo.bar()['first'][0]*baz.quux(1, 2)[5:9] + + calculate_number(10, 20)*forbulate(500, 360)) + Added: doctools/trunk/Doc-3k/howto/functional.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-3k/howto/functional.rst Thu Aug 2 23:31:34 2007 @@ -0,0 +1,1400 @@ +******************************** + Functional Programming HOWTO +******************************** + +:Author: \A. M. Kuchling +:Release: 0.30 + +(This is a first draft. Please send comments/error reports/suggestions to +amk at amk.ca. This URL is probably not going to be the final location of the +document, so be careful about linking to it -- you may want to add a +disclaimer.) + +In this document, we'll take a tour of Python's features suitable for +implementing programs in a functional style. After an introduction to the +concepts of functional programming, we'll look at language features such as +iterators and generators and relevant library modules such as :mod:`itertools` +and :mod:`functools`. + + +Introduction +============ + +This section explains the basic concept of functional programming; if you're +just interested in learning about Python language features, skip to the next +section. + +Programming languages support decomposing problems in several different ways: + +* Most programming languages are **procedural**: programs are lists of + instructions that tell the computer what to do with the program's input. C, + Pascal, and even Unix shells are procedural languages. + +* In **declarative** languages, you write a specification that describes the + problem to be solved, and the language implementation figures out how to + perform the computation efficiently. SQL is the declarative language you're + most likely to be familiar with; a SQL query describes the data set you want + to retrieve, and the SQL engine decides whether to scan tables or use indexes, + which subclauses should be performed first, etc. + +* **Object-oriented** programs manipulate collections of objects. Objects have + internal state and support methods that query or modify this internal state in + some way. Smalltalk and Java are object-oriented languages. C++ and Python + are languages that support object-oriented programming, but don't force the + use of object-oriented features. + +* **Functional** programming decomposes a problem into a set of functions. + Ideally, functions only take inputs and produce outputs, and don't have any + internal state that affects the output produced for a given input. Well-known + functional languages include the ML family (Standard ML, OCaml, and other + variants) and Haskell. + +The designers of some computer languages have chosen one approach to programming +that's emphasized. This often makes it difficult to write programs that use a +different approach. Other languages are multi-paradigm languages that support +several different approaches. Lisp, C++, and Python are multi-paradigm; you can +write programs or libraries that are largely procedural, object-oriented, or +functional in all of these languages. In a large program, different sections +might be written using different approaches; the GUI might be object-oriented +while the processing logic is procedural or functional, for example. + +In a functional program, input flows through a set of functions. Each function +operates on its input and produces some output. Functional style frowns upon +functions with side effects that modify internal state or make other changes +that aren't visible in the function's return value. Functions that have no side +effects at all are called **purely functional**. Avoiding side effects means +not using data structures that get updated as a program runs; every function's +output must only depend on its input. + +Some languages are very strict about purity and don't even have assignment +statements such as ``a=3`` or ``c = a + b``, but it's difficult to avoid all +side effects. Printing to the screen or writing to a disk file are side +effects, for example. For example, in Python a ``print`` statement or a +``time.sleep(1)`` both return no useful value; they're only called for their +side effects of sending some text to the screen or pausing execution for a +second. + +Python programs written in functional style usually won't go to the extreme of +avoiding all I/O or all assignments; instead, they'll provide a +functional-appearing interface but will use non-functional features internally. +For example, the implementation of a function will still use assignments to +local variables, but won't modify global variables or have other side effects. + +Functional programming can be considered the opposite of object-oriented +programming. Objects are little capsules containing some internal state along +with a collection of method calls that let you modify this state, and programs +consist of making the right set of state changes. Functional programming wants +to avoid state changes as much as possible and works with data flowing between +functions. In Python you might combine the two approaches by writing functions +that take and return instances representing objects in your application (e-mail +messages, transactions, etc.). + +Functional design may seem like an odd constraint to work under. Why should you +avoid objects and side effects? There are theoretical and practical advantages +to the functional style: + +* Formal provability. +* Modularity. +* Composability. +* Ease of debugging and testing. + +Formal provability +------------------ + +A theoretical benefit is that it's easier to construct a mathematical proof that +a functional program is correct. + +For a long time researchers have been interested in finding ways to +mathematically prove programs correct. This is different from testing a program +on numerous inputs and concluding that its output is usually correct, or reading +a program's source code and concluding that the code looks right; the goal is +instead a rigorous proof that a program produces the right result for all +possible inputs. + +The technique used to prove programs correct is to write down **invariants**, +properties of the input data and of the program's variables that are always +true. For each line of code, you then show that if invariants X and Y are true +**before** the line is executed, the slightly different invariants X' and Y' are +true **after** the line is executed. This continues until you reach the end of +the program, at which point the invariants should match the desired conditions +on the program's output. + +Functional programming's avoidance of assignments arose because assignments are +difficult to handle with this technique; assignments can break invariants that +were true before the assignment without producing any new invariants that can be +propagated onward. + +Unfortunately, proving programs correct is largely impractical and not relevant +to Python software. Even trivial programs require proofs that are several pages +long; the proof of correctness for a moderately complicated program would be +enormous, and few or none of the programs you use daily (the Python interpreter, +your XML parser, your web browser) could be proven correct. Even if you wrote +down or generated a proof, there would then be the question of verifying the +proof; maybe there's an error in it, and you wrongly believe you've proved the +program correct. + +Modularity +---------- + +A more practical benefit of functional programming is that it forces you to +break apart your problem into small pieces. Programs are more modular as a +result. It's easier to specify and write a small function that does one thing +than a large function that performs a complicated transformation. Small +functions are also easier to read and to check for errors. + + +Ease of debugging and testing +----------------------------- + +Testing and debugging a functional-style program is easier. + +Debugging is simplified because functions are generally small and clearly +specified. When a program doesn't work, each function is an interface point +where you can check that the data are correct. You can look at the intermediate +inputs and outputs to quickly isolate the function that's responsible for a bug. + +Testing is easier because each function is a potential subject for a unit test. +Functions don't depend on system state that needs to be replicated before +running a test; instead you only have to synthesize the right input and then +check that the output matches expectations. + + + +Composability +------------- + +As you work on a functional-style program, you'll write a number of functions +with varying inputs and outputs. Some of these functions will be unavoidably +specialized to a particular application, but others will be useful in a wide +variety of programs. For example, a function that takes a directory path and +returns all the XML files in the directory, or a function that takes a filename +and returns its contents, can be applied to many different situations. + +Over time you'll form a personal library of utilities. Often you'll assemble +new programs by arranging existing functions in a new configuration and writing +a few functions specialized for the current task. + + + +Iterators +========= + +I'll start by looking at a Python language feature that's an important +foundation for writing functional-style programs: iterators. + +An iterator is an object representing a stream of data; this object returns the +data one element at a time. A Python iterator must support a method called +``next()`` that takes no arguments and always returns the next element of the +stream. If there are no more elements in the stream, ``next()`` must raise the +``StopIteration`` exception. Iterators don't have to be finite, though; it's +perfectly reasonable to write an iterator that produces an infinite stream of +data. + +The built-in :func:`iter` function takes an arbitrary object and tries to return +an iterator that will return the object's contents or elements, raising +:exc:`TypeError` if the object doesn't support iteration. Several of Python's +built-in data types support iteration, the most common being lists and +dictionaries. An object is called an **iterable** object if you can get an +iterator for it. + +You can experiment with the iteration interface manually:: + + >>> L = [1,2,3] + >>> it = iter(L) + >>> print it + + >>> it.next() + 1 + >>> it.next() + 2 + >>> it.next() + 3 + >>> it.next() + Traceback (most recent call last): + File "", line 1, in ? + StopIteration + >>> + +Python expects iterable objects in several different contexts, the most +important being the ``for`` statement. In the statement ``for X in Y``, Y must +be an iterator or some object for which ``iter()`` can create an iterator. +These two statements are equivalent:: + + for i in iter(obj): + print i + + for i in obj: + print i + +Iterators can be materialized as lists or tuples by using the :func:`list` or +:func:`tuple` constructor functions:: + + >>> L = [1,2,3] + >>> iterator = iter(L) + >>> t = tuple(iterator) + >>> t + (1, 2, 3) + +Sequence unpacking also supports iterators: if you know an iterator will return +N elements, you can unpack them into an N-tuple:: + + >>> L = [1,2,3] + >>> iterator = iter(L) + >>> a,b,c = iterator + >>> a,b,c + (1, 2, 3) + +Built-in functions such as :func:`max` and :func:`min` can take a single +iterator argument and will return the largest or smallest element. The ``"in"`` +and ``"not in"`` operators also support iterators: ``X in iterator`` is true if +X is found in the stream returned by the iterator. You'll run into obvious +problems if the iterator is infinite; ``max()``, ``min()``, and ``"not in"`` +will never return, and if the element X never appears in the stream, the +``"in"`` operator won't return either. + +Note that you can only go forward in an iterator; there's no way to get the +previous element, reset the iterator, or make a copy of it. Iterator objects +can optionally provide these additional capabilities, but the iterator protocol +only specifies the ``next()`` method. Functions may therefore consume all of +the iterator's output, and if you need to do something different with the same +stream, you'll have to create a new iterator. + + + +Data Types That Support Iterators +--------------------------------- + +We've already seen how lists and tuples support iterators. In fact, any Python +sequence type, such as strings, will automatically support creation of an +iterator. + +Calling :func:`iter` on a dictionary returns an iterator that will loop over the +dictionary's keys:: + + >>> m = {'Jan': 1, 'Feb': 2, 'Mar': 3, 'Apr': 4, 'May': 5, 'Jun': 6, + ... 'Jul': 7, 'Aug': 8, 'Sep': 9, 'Oct': 10, 'Nov': 11, 'Dec': 12} + >>> for key in m: + ... print key, m[key] + Mar 3 + Feb 2 + Aug 8 + Sep 9 + May 5 + Jun 6 + Jul 7 + Jan 1 + Apr 4 + Nov 11 + Dec 12 + Oct 10 + +Note that the order is essentially random, because it's based on the hash +ordering of the objects in the dictionary. + +Applying ``iter()`` to a dictionary always loops over the keys, but dictionaries +have methods that return other iterators. If you want to iterate over keys, +values, or key/value pairs, you can explicitly call the ``iterkeys()``, +``itervalues()``, or ``iteritems()`` methods to get an appropriate iterator. + +The :func:`dict` constructor can accept an iterator that returns a finite stream +of ``(key, value)`` tuples:: + + >>> L = [('Italy', 'Rome'), ('France', 'Paris'), ('US', 'Washington DC')] + >>> dict(iter(L)) + {'Italy': 'Rome', 'US': 'Washington DC', 'France': 'Paris'} + +Files also support iteration by calling the ``readline()`` method until there +are no more lines in the file. This means you can read each line of a file like +this:: + + for line in file: + # do something for each line + ... + +Sets can take their contents from an iterable and let you iterate over the set's +elements:: + + S = set((2, 3, 5, 7, 11, 13)) + for i in S: + print i + + + +Generator expressions and list comprehensions +============================================= + +Two common operations on an iterator's output are 1) performing some operation +for every element, 2) selecting a subset of elements that meet some condition. +For example, given a list of strings, you might want to strip off trailing +whitespace from each line or extract all the strings containing a given +substring. + +List comprehensions and generator expressions (short form: "listcomps" and +"genexps") are a concise notation for such operations, borrowed from the +functional programming language Haskell (http://www.haskell.org). You can strip +all the whitespace from a stream of strings with the following code:: + + line_list = [' line 1\n', 'line 2 \n', ...] + + # Generator expression -- returns iterator + stripped_iter = (line.strip() for line in line_list) + + # List comprehension -- returns list + stripped_list = [line.strip() for line in line_list] + +You can select only certain elements by adding an ``"if"`` condition:: + + stripped_list = [line.strip() for line in line_list + if line != ""] + +With a list comprehension, you get back a Python list; ``stripped_list`` is a +list containing the resulting lines, not an iterator. Generator expressions +return an iterator that computes the values as necessary, not needing to +materialize all the values at once. This means that list comprehensions aren't +useful if you're working with iterators that return an infinite stream or a very +large amount of data. Generator expressions are preferable in these situations. + +Generator expressions are surrounded by parentheses ("()") and list +comprehensions are surrounded by square brackets ("[]"). Generator expressions +have the form:: + + ( expression for expr in sequence1 + if condition1 + for expr2 in sequence2 + if condition2 + for expr3 in sequence3 ... + if condition3 + for exprN in sequenceN + if conditionN ) + +Again, for a list comprehension only the outside brackets are different (square +brackets instead of parentheses). + +The elements of the generated output will be the successive values of +``expression``. The ``if`` clauses are all optional; if present, ``expression`` +is only evaluated and added to the result when ``condition`` is true. + +Generator expressions always have to be written inside parentheses, but the +parentheses signalling a function call also count. If you want to create an +iterator that will be immediately passed to a function you can write:: + + obj_total = sum(obj.count for obj in list_all_objects()) + +The ``for...in`` clauses contain the sequences to be iterated over. The +sequences do not have to be the same length, because they are iterated over from +left to right, **not** in parallel. For each element in ``sequence1``, +``sequence2`` is looped over from the beginning. ``sequence3`` is then looped +over for each resulting pair of elements from ``sequence1`` and ``sequence2``. + +To put it another way, a list comprehension or generator expression is +equivalent to the following Python code:: + + for expr1 in sequence1: + if not (condition1): + continue # Skip this element + for expr2 in sequence2: + if not (condition2): + continue # Skip this element + ... + for exprN in sequenceN: + if not (conditionN): + continue # Skip this element + + # Output the value of + # the expression. + +This means that when there are multiple ``for...in`` clauses but no ``if`` +clauses, the length of the resulting output will be equal to the product of the +lengths of all the sequences. If you have two lists of length 3, the output +list is 9 elements long:: + + seq1 = 'abc' + seq2 = (1,2,3) + >>> [ (x,y) for x in seq1 for y in seq2] + [('a', 1), ('a', 2), ('a', 3), + ('b', 1), ('b', 2), ('b', 3), + ('c', 1), ('c', 2), ('c', 3)] + +To avoid introducing an ambiguity into Python's grammar, if ``expression`` is +creating a tuple, it must be surrounded with parentheses. The first list +comprehension below is a syntax error, while the second one is correct:: + + # Syntax error + [ x,y for x in seq1 for y in seq2] + # Correct + [ (x,y) for x in seq1 for y in seq2] + + +Generators +========== + +Generators are a special class of functions that simplify the task of writing +iterators. Regular functions compute a value and return it, but generators +return an iterator that returns a stream of values. + +You're doubtless familiar with how regular function calls work in Python or C. +When you call a function, it gets a private namespace where its local variables +are created. When the function reaches a ``return`` statement, the local +variables are destroyed and the value is returned to the caller. A later call +to the same function creates a new private namespace and a fresh set of local +variables. But, what if the local variables weren't thrown away on exiting a +function? What if you could later resume the function where it left off? This +is what generators provide; they can be thought of as resumable functions. + +Here's the simplest example of a generator function:: + + def generate_ints(N): + for i in range(N): + yield i + +Any function containing a ``yield`` keyword is a generator function; this is +detected by Python's bytecode compiler which compiles the function specially as +a result. + +When you call a generator function, it doesn't return a single value; instead it +returns a generator object that supports the iterator protocol. On executing +the ``yield`` expression, the generator outputs the value of ``i``, similar to a +``return`` statement. The big difference between ``yield`` and a ``return`` +statement is that on reaching a ``yield`` the generator's state of execution is +suspended and local variables are preserved. On the next call to the +generator's ``.next()`` method, the function will resume executing. + +Here's a sample usage of the ``generate_ints()`` generator:: + + >>> gen = generate_ints(3) + >>> gen + + >>> gen.next() + 0 + >>> gen.next() + 1 + >>> gen.next() + 2 + >>> gen.next() + Traceback (most recent call last): + File "stdin", line 1, in ? + File "stdin", line 2, in generate_ints + StopIteration + +You could equally write ``for i in generate_ints(5)``, or ``a,b,c = +generate_ints(3)``. + +Inside a generator function, the ``return`` statement can only be used without a +value, and signals the end of the procession of values; after executing a +``return`` the generator cannot return any further values. ``return`` with a +value, such as ``return 5``, is a syntax error inside a generator function. The +end of the generator's results can also be indicated by raising +``StopIteration`` manually, or by just letting the flow of execution fall off +the bottom of the function. + +You could achieve the effect of generators manually by writing your own class +and storing all the local variables of the generator as instance variables. For +example, returning a list of integers could be done by setting ``self.count`` to +0, and having the ``next()`` method increment ``self.count`` and return it. +However, for a moderately complicated generator, writing a corresponding class +can be much messier. + +The test suite included with Python's library, ``test_generators.py``, contains +a number of more interesting examples. Here's one generator that implements an +in-order traversal of a tree using generators recursively. + +:: + + # A recursive generator that generates Tree leaves in in-order. + def inorder(t): + if t: + for x in inorder(t.left): + yield x + + yield t.label + + for x in inorder(t.right): + yield x + +Two other examples in ``test_generators.py`` produce solutions for the N-Queens +problem (placing N queens on an NxN chess board so that no queen threatens +another) and the Knight's Tour (finding a route that takes a knight to every +square of an NxN chessboard without visiting any square twice). + + + +Passing values into a generator +------------------------------- + +In Python 2.4 and earlier, generators only produced output. Once a generator's +code was invoked to create an iterator, there was no way to pass any new +information into the function when its execution is resumed. You could hack +together this ability by making the generator look at a global variable or by +passing in some mutable object that callers then modify, but these approaches +are messy. + +In Python 2.5 there's a simple way to pass values into a generator. +:keyword:`yield` became an expression, returning a value that can be assigned to +a variable or otherwise operated on:: + + val = (yield i) + +I recommend that you **always** put parentheses around a ``yield`` expression +when you're doing something with the returned value, as in the above example. +The parentheses aren't always necessary, but it's easier to always add them +instead of having to remember when they're needed. + +(PEP 342 explains the exact rules, which are that a ``yield``-expression must +always be parenthesized except when it occurs at the top-level expression on the +right-hand side of an assignment. This means you can write ``val = yield i`` +but have to use parentheses when there's an operation, as in ``val = (yield i) ++ 12``.) + +Values are sent into a generator by calling its ``send(value)`` method. This +method resumes the generator's code and the ``yield`` expression returns the +specified value. If the regular ``next()`` method is called, the ``yield`` +returns ``None``. + +Here's a simple counter that increments by 1 and allows changing the value of +the internal counter. + +:: + + def counter (maximum): + i = 0 + while i < maximum: + val = (yield i) + # If value provided, change counter + if val is not None: + i = val + else: + i += 1 + +And here's an example of changing the counter: + + >>> it = counter(10) + >>> print it.next() + 0 + >>> print it.next() + 1 + >>> print it.send(8) + 8 + >>> print it.next() + 9 + >>> print it.next() + Traceback (most recent call last): + File ``t.py'', line 15, in ? + print it.next() + StopIteration + +Because ``yield`` will often be returning ``None``, you should always check for +this case. Don't just use its value in expressions unless you're sure that the +``send()`` method will be the only method used resume your generator function. + +In addition to ``send()``, there are two other new methods on generators: + +* ``throw(type, value=None, traceback=None)`` is used to raise an exception + inside the generator; the exception is raised by the ``yield`` expression + where the generator's execution is paused. + +* ``close()`` raises a :exc:`GeneratorExit` exception inside the generator to + terminate the iteration. On receiving this exception, the generator's code + must either raise :exc:`GeneratorExit` or :exc:`StopIteration`; catching the + exception and doing anything else is illegal and will trigger a + :exc:`RuntimeError`. ``close()`` will also be called by Python's garbage + collector when the generator is garbage-collected. + + If you need to run cleanup code when a :exc:`GeneratorExit` occurs, I suggest + using a ``try: ... finally:`` suite instead of catching :exc:`GeneratorExit`. + +The cumulative effect of these changes is to turn generators from one-way +producers of information into both producers and consumers. + +Generators also become **coroutines**, a more generalized form of subroutines. +Subroutines are entered at one point and exited at another point (the top of the +function, and a ``return`` statement), but coroutines can be entered, exited, +and resumed at many different points (the ``yield`` statements). + + +Built-in functions +================== + +Let's look in more detail at built-in functions often used with iterators. + +Two Python's built-in functions, :func:`map` and :func:`filter`, are somewhat +obsolete; they duplicate the features of list comprehensions but return actual +lists instead of iterators. + +``map(f, iterA, iterB, ...)`` returns a list containing ``f(iterA[0], iterB[0]), +f(iterA[1], iterB[1]), f(iterA[2], iterB[2]), ...``. + +:: + + def upper(s): + return s.upper() + map(upper, ['sentence', 'fragment']) => + ['SENTENCE', 'FRAGMENT'] + + [upper(s) for s in ['sentence', 'fragment']] => + ['SENTENCE', 'FRAGMENT'] + +As shown above, you can achieve the same effect with a list comprehension. The +:func:`itertools.imap` function does the same thing but can handle infinite +iterators; it'll be discussed later, in the section on the :mod:`itertools` module. + +``filter(predicate, iter)`` returns a list that contains all the sequence +elements that meet a certain condition, and is similarly duplicated by list +comprehensions. A **predicate** is a function that returns the truth value of +some condition; for use with :func:`filter`, the predicate must take a single +value. + +:: + + def is_even(x): + return (x % 2) == 0 + + filter(is_even, range(10)) => + [0, 2, 4, 6, 8] + +This can also be written as a list comprehension:: + + >>> [x for x in range(10) if is_even(x)] + [0, 2, 4, 6, 8] + +:func:`filter` also has a counterpart in the :mod:`itertools` module, +:func:`itertools.ifilter`, that returns an iterator and can therefore handle +infinite sequences just as :func:`itertools.imap` can. + +``reduce(func, iter, [initial_value])`` doesn't have a counterpart in the +:mod:`itertools` module because it cumulatively performs an operation on all the +iterable's elements and therefore can't be applied to infinite iterables. +``func`` must be a function that takes two elements and returns a single value. +:func:`reduce` takes the first two elements A and B returned by the iterator and +calculates ``func(A, B)``. It then requests the third element, C, calculates +``func(func(A, B), C)``, combines this result with the fourth element returned, +and continues until the iterable is exhausted. If the iterable returns no +values at all, a :exc:`TypeError` exception is raised. If the initial value is +supplied, it's used as a starting point and ``func(initial_value, A)`` is the +first calculation. + +:: + + import operator + reduce(operator.concat, ['A', 'BB', 'C']) => + 'ABBC' + reduce(operator.concat, []) => + TypeError: reduce() of empty sequence with no initial value + reduce(operator.mul, [1,2,3], 1) => + 6 + reduce(operator.mul, [], 1) => + 1 + +If you use :func:`operator.add` with :func:`reduce`, you'll add up all the +elements of the iterable. This case is so common that there's a special +built-in called :func:`sum` to compute it:: + + reduce(operator.add, [1,2,3,4], 0) => + 10 + sum([1,2,3,4]) => + 10 + sum([]) => + 0 + +For many uses of :func:`reduce`, though, it can be clearer to just write the +obvious :keyword:`for` loop:: + + # Instead of: + product = reduce(operator.mul, [1,2,3], 1) + + # You can write: + product = 1 + for i in [1,2,3]: + product *= i + + +``enumerate(iter)`` counts off the elements in the iterable, returning 2-tuples +containing the count and each element. + +:: + + enumerate(['subject', 'verb', 'object']) => + (0, 'subject'), (1, 'verb'), (2, 'object') + +:func:`enumerate` is often used when looping through a list and recording the +indexes at which certain conditions are met:: + + f = open('data.txt', 'r') + for i, line in enumerate(f): + if line.strip() == '': + print 'Blank line at line #%i' % i + +``sorted(iterable, [cmp=None], [key=None], [reverse=False)`` collects all the +elements of the iterable into a list, sorts the list, and returns the sorted +result. The ``cmp``, ``key``, and ``reverse`` arguments are passed through to +the constructed list's ``.sort()`` method. + +:: + + import random + # Generate 8 random numbers between [0, 10000) + rand_list = random.sample(range(10000), 8) + rand_list => + [769, 7953, 9828, 6431, 8442, 9878, 6213, 2207] + sorted(rand_list) => + [769, 2207, 6213, 6431, 7953, 8442, 9828, 9878] + sorted(rand_list, reverse=True) => + [9878, 9828, 8442, 7953, 6431, 6213, 2207, 769] + +(For a more detailed discussion of sorting, see the Sorting mini-HOWTO in the +Python wiki at http://wiki.python.org/moin/HowTo/Sorting.) + +The ``any(iter)`` and ``all(iter)`` built-ins look at the truth values of an +iterable's contents. :func:`any` returns True if any element in the iterable is +a true value, and :func:`all` returns True if all of the elements are true +values:: + + any([0,1,0]) => + True + any([0,0,0]) => + False + any([1,1,1]) => + True + all([0,1,0]) => + False + all([0,0,0]) => + False + all([1,1,1]) => + True + + +Small functions and the lambda expression +========================================= + +When writing functional-style programs, you'll often need little functions that +act as predicates or that combine elements in some way. + +If there's a Python built-in or a module function that's suitable, you don't +need to define a new function at all:: + + stripped_lines = [line.strip() for line in lines] + existing_files = filter(os.path.exists, file_list) + +If the function you need doesn't exist, you need to write it. One way to write +small functions is to use the ``lambda`` statement. ``lambda`` takes a number +of parameters and an expression combining these parameters, and creates a small +function that returns the value of the expression:: + + lowercase = lambda x: x.lower() + + print_assign = lambda name, value: name + '=' + str(value) + + adder = lambda x, y: x+y + +An alternative is to just use the ``def`` statement and define a function in the +usual way:: + + def lowercase(x): + return x.lower() + + def print_assign(name, value): + return name + '=' + str(value) + + def adder(x,y): + return x + y + +Which alternative is preferable? That's a style question; my usual course is to +avoid using ``lambda``. + +One reason for my preference is that ``lambda`` is quite limited in the +functions it can define. The result has to be computable as a single +expression, which means you can't have multiway ``if... elif... else`` +comparisons or ``try... except`` statements. If you try to do too much in a +``lambda`` statement, you'll end up with an overly complicated expression that's +hard to read. Quick, what's the following code doing? + +:: + + total = reduce(lambda a, b: (0, a[1] + b[1]), items)[1] + +You can figure it out, but it takes time to disentangle the expression to figure +out what's going on. Using a short nested ``def`` statements makes things a +little bit better:: + + def combine (a, b): + return 0, a[1] + b[1] + + total = reduce(combine, items)[1] + +But it would be best of all if I had simply used a ``for`` loop:: + + total = 0 + for a, b in items: + total += b + +Or the :func:`sum` built-in and a generator expression:: + + total = sum(b for a,b in items) + +Many uses of :func:`reduce` are clearer when written as ``for`` loops. + +Fredrik Lundh once suggested the following set of rules for refactoring uses of +``lambda``: + +1) Write a lambda function. +2) Write a comment explaining what the heck that lambda does. +3) Study the comment for a while, and think of a name that captures the essence + of the comment. +4) Convert the lambda to a def statement, using that name. +5) Remove the comment. + +I really like these rules, but you're free to disagree that this lambda-free +style is better. + + +The itertools module +==================== + +The :mod:`itertools` module contains a number of commonly-used iterators as well +as functions for combining several iterators. This section will introduce the +module's contents by showing small examples. + +The module's functions fall into a few broad classes: + +* Functions that create a new iterator based on an existing iterator. +* Functions for treating an iterator's elements as function arguments. +* Functions for selecting portions of an iterator's output. +* A function for grouping an iterator's output. + +Creating new iterators +---------------------- + +``itertools.count(n)`` returns an infinite stream of integers, increasing by 1 +each time. You can optionally supply the starting number, which defaults to 0:: + + itertools.count() => + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ... + itertools.count(10) => + 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, ... + +``itertools.cycle(iter)`` saves a copy of the contents of a provided iterable +and returns a new iterator that returns its elements from first to last. The +new iterator will repeat these elements infinitely. + +:: + + itertools.cycle([1,2,3,4,5]) => + 1, 2, 3, 4, 5, 1, 2, 3, 4, 5, ... + +``itertools.repeat(elem, [n])`` returns the provided element ``n`` times, or +returns the element endlessly if ``n`` is not provided. + +:: + + itertools.repeat('abc') => + abc, abc, abc, abc, abc, abc, abc, abc, abc, abc, ... + itertools.repeat('abc', 5) => + abc, abc, abc, abc, abc + +``itertools.chain(iterA, iterB, ...)`` takes an arbitrary number of iterables as +input, and returns all the elements of the first iterator, then all the elements +of the second, and so on, until all of the iterables have been exhausted. + +:: + + itertools.chain(['a', 'b', 'c'], (1, 2, 3)) => + a, b, c, 1, 2, 3 + +``itertools.izip(iterA, iterB, ...)`` takes one element from each iterable and +returns them in a tuple:: + + itertools.izip(['a', 'b', 'c'], (1, 2, 3)) => + ('a', 1), ('b', 2), ('c', 3) + +It's similiar to the built-in :func:`zip` function, but doesn't construct an +in-memory list and exhaust all the input iterators before returning; instead +tuples are constructed and returned only if they're requested. (The technical +term for this behaviour is `lazy evaluation +`__.) + +This iterator is intended to be used with iterables that are all of the same +length. If the iterables are of different lengths, the resulting stream will be +the same length as the shortest iterable. + +:: + + itertools.izip(['a', 'b'], (1, 2, 3)) => + ('a', 1), ('b', 2) + +You should avoid doing this, though, because an element may be taken from the +longer iterators and discarded. This means you can't go on to use the iterators +further because you risk skipping a discarded element. + +``itertools.islice(iter, [start], stop, [step])`` returns a stream that's a +slice of the iterator. With a single ``stop`` argument, it will return the +first ``stop`` elements. If you supply a starting index, you'll get +``stop-start`` elements, and if you supply a value for ``step``, elements will +be skipped accordingly. Unlike Python's string and list slicing, you can't use +negative values for ``start``, ``stop``, or ``step``. + +:: + + itertools.islice(range(10), 8) => + 0, 1, 2, 3, 4, 5, 6, 7 + itertools.islice(range(10), 2, 8) => + 2, 3, 4, 5, 6, 7 + itertools.islice(range(10), 2, 8, 2) => + 2, 4, 6 + +``itertools.tee(iter, [n])`` replicates an iterator; it returns ``n`` +independent iterators that will all return the contents of the source iterator. +If you don't supply a value for ``n``, the default is 2. Replicating iterators +requires saving some of the contents of the source iterator, so this can consume +significant memory if the iterator is large and one of the new iterators is +consumed more than the others. + +:: + + itertools.tee( itertools.count() ) => + iterA, iterB + + where iterA -> + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ... + + and iterB -> + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ... + + +Calling functions on elements +----------------------------- + +Two functions are used for calling other functions on the contents of an +iterable. + +``itertools.imap(f, iterA, iterB, ...)`` returns a stream containing +``f(iterA[0], iterB[0]), f(iterA[1], iterB[1]), f(iterA[2], iterB[2]), ...``:: + + itertools.imap(operator.add, [5, 6, 5], [1, 2, 3]) => + 6, 8, 8 + +The ``operator`` module contains a set of functions corresponding to Python's +operators. Some examples are ``operator.add(a, b)`` (adds two values), +``operator.ne(a, b)`` (same as ``a!=b``), and ``operator.attrgetter('id')`` +(returns a callable that fetches the ``"id"`` attribute). + +``itertools.starmap(func, iter)`` assumes that the iterable will return a stream +of tuples, and calls ``f()`` using these tuples as the arguments:: + + itertools.starmap(os.path.join, + [('/usr', 'bin', 'java'), ('/bin', 'python'), + ('/usr', 'bin', 'perl'),('/usr', 'bin', 'ruby')]) + => + /usr/bin/java, /bin/python, /usr/bin/perl, /usr/bin/ruby + + +Selecting elements +------------------ + +Another group of functions chooses a subset of an iterator's elements based on a +predicate. + +``itertools.ifilter(predicate, iter)`` returns all the elements for which the +predicate returns true:: + + def is_even(x): + return (x % 2) == 0 + + itertools.ifilter(is_even, itertools.count()) => + 0, 2, 4, 6, 8, 10, 12, 14, ... + +``itertools.ifilterfalse(predicate, iter)`` is the opposite, returning all +elements for which the predicate returns false:: + + itertools.ifilterfalse(is_even, itertools.count()) => + 1, 3, 5, 7, 9, 11, 13, 15, ... + +``itertools.takewhile(predicate, iter)`` returns elements for as long as the +predicate returns true. Once the predicate returns false, the iterator will +signal the end of its results. + +:: + + def less_than_10(x): + return (x < 10) + + itertools.takewhile(less_than_10, itertools.count()) => + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 + + itertools.takewhile(is_even, itertools.count()) => + 0 + +``itertools.dropwhile(predicate, iter)`` discards elements while the predicate +returns true, and then returns the rest of the iterable's results. + +:: + + itertools.dropwhile(less_than_10, itertools.count()) => + 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, ... + + itertools.dropwhile(is_even, itertools.count()) => + 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ... + + +Grouping elements +''''''''''''''''' + +The last function I'll discuss, ``itertools.groupby(iter, key_func=None)``, is +the most complicated. ``key_func(elem)`` is a function that can compute a key +value for each element returned by the iterable. If you don't supply a key +function, the key is simply each element itself. + +``groupby()`` collects all the consecutive elements from the underlying iterable +that have the same key value, and returns a stream of 2-tuples containing a key +value and an iterator for the elements with that key. + +:: + + city_list = [('Decatur', 'AL'), ('Huntsville', 'AL'), ('Selma', 'AL'), + ('Anchorage', 'AK'), ('Nome', 'AK'), + ('Flagstaff', 'AZ'), ('Phoenix', 'AZ'), ('Tucson', 'AZ'), + ... + ] + + def get_state ((city, state)): + return state + + itertools.groupby(city_list, get_state) => + ('AL', iterator-1), + ('AK', iterator-2), + ('AZ', iterator-3), ... + + where + iterator-1 => + ('Decatur', 'AL'), ('Huntsville', 'AL'), ('Selma', 'AL') + iterator-2 => + ('Anchorage', 'AK'), ('Nome', 'AK') + iterator-3 => + ('Flagstaff', 'AZ'), ('Phoenix', 'AZ'), ('Tucson', 'AZ') + +``groupby()`` assumes that the underlying iterable's contents will already be +sorted based on the key. Note that the returned iterators also use the +underlying iterable, so you have to consume the results of iterator-1 before +requesting iterator-2 and its corresponding key. + + +The functools module +==================== + +The :mod:`functools` module in Python 2.5 contains some higher-order functions. +A **higher-order function** takes one or more functions as input and returns a +new function. The most useful tool in this module is the +:func:`functools.partial` function. + +For programs written in a functional style, you'll sometimes want to construct +variants of existing functions that have some of the parameters filled in. +Consider a Python function ``f(a, b, c)``; you may wish to create a new function +``g(b, c)`` that's equivalent to ``f(1, b, c)``; you're filling in a value for +one of ``f()``'s parameters. This is called "partial function application". + +The constructor for ``partial`` takes the arguments ``(function, arg1, arg2, +... kwarg1=value1, kwarg2=value2)``. The resulting object is callable, so you +can just call it to invoke ``function`` with the filled-in arguments. + +Here's a small but realistic example:: + + import functools + + def log (message, subsystem): + "Write the contents of 'message' to the specified subsystem." + print '%s: %s' % (subsystem, message) + ... + + server_log = functools.partial(log, subsystem='server') + server_log('Unable to open socket') + + +The operator module +------------------- + +The :mod:`operator` module was mentioned earlier. It contains a set of +functions corresponding to Python's operators. These functions are often useful +in functional-style code because they save you from writing trivial functions +that perform a single operation. + +Some of the functions in this module are: + +* Math operations: ``add()``, ``sub()``, ``mul()``, ``div()``, ``floordiv()``, + ``abs()``, ... +* Logical operations: ``not_()``, ``truth()``. +* Bitwise operations: ``and_()``, ``or_()``, ``invert()``. +* Comparisons: ``eq()``, ``ne()``, ``lt()``, ``le()``, ``gt()``, and ``ge()``. +* Object identity: ``is_()``, ``is_not()``. + +Consult the operator module's documentation for a complete list. + + + +The functional module +--------------------- + +Collin Winter's `functional module `__ +provides a number of more advanced tools for functional programming. It also +reimplements several Python built-ins, trying to make them more intuitive to +those used to functional programming in other languages. + +This section contains an introduction to some of the most important functions in +``functional``; full documentation can be found at `the project's website +`__. + +``compose(outer, inner, unpack=False)`` + +The ``compose()`` function implements function composition. In other words, it +returns a wrapper around the ``outer`` and ``inner`` callables, such that the +return value from ``inner`` is fed directly to ``outer``. That is, + +:: + + >>> def add(a, b): + ... return a + b + ... + >>> def double(a): + ... return 2 * a + ... + >>> compose(double, add)(5, 6) + 22 + +is equivalent to + +:: + + >>> double(add(5, 6)) + 22 + +The ``unpack`` keyword is provided to work around the fact that Python functions +are not always `fully curried `__. By +default, it is expected that the ``inner`` function will return a single object +and that the ``outer`` function will take a single argument. Setting the +``unpack`` argument causes ``compose`` to expect a tuple from ``inner`` which +will be expanded before being passed to ``outer``. Put simply, + +:: + + compose(f, g)(5, 6) + +is equivalent to:: + + f(g(5, 6)) + +while + +:: + + compose(f, g, unpack=True)(5, 6) + +is equivalent to:: + + f(*g(5, 6)) + +Even though ``compose()`` only accepts two functions, it's trivial to build up a +version that will compose any number of functions. We'll use ``reduce()``, +``compose()`` and ``partial()`` (the last of which is provided by both +``functional`` and ``functools``). + +:: + + from functional import compose, partial + + multi_compose = partial(reduce, compose) + + +We can also use ``map()``, ``compose()`` and ``partial()`` to craft a version of +``"".join(...)`` that converts its arguments to string:: + + from functional import compose, partial + + join = compose("".join, partial(map, str)) + + +``flip(func)`` + +``flip()`` wraps the callable in ``func`` and causes it to receive its +non-keyword arguments in reverse order. + +:: + + >>> def triple(a, b, c): + ... return (a, b, c) + ... + >>> triple(5, 6, 7) + (5, 6, 7) + >>> + >>> flipped_triple = flip(triple) + >>> flipped_triple(5, 6, 7) + (7, 6, 5) + +``foldl(func, start, iterable)`` + +``foldl()`` takes a binary function, a starting value (usually some kind of +'zero'), and an iterable. The function is applied to the starting value and the +first element of the list, then the result of that and the second element of the +list, then the result of that and the third element of the list, and so on. + +This means that a call such as:: + + foldl(f, 0, [1, 2, 3]) + +is equivalent to:: + + f(f(f(0, 1), 2), 3) + + +``foldl()`` is roughly equivalent to the following recursive function:: + + def foldl(func, start, seq): + if len(seq) == 0: + return start + + return foldl(func, func(start, seq[0]), seq[1:]) + +Speaking of equivalence, the above ``foldl`` call can be expressed in terms of +the built-in ``reduce`` like so:: + + reduce(f, [1, 2, 3], 0) + + +We can use ``foldl()``, ``operator.concat()`` and ``partial()`` to write a +cleaner, more aesthetically-pleasing version of Python's ``"".join(...)`` +idiom:: + + from functional import foldl, partial + from operator import concat + + join = partial(foldl, concat, "") + + +Revision History and Acknowledgements +===================================== + +The author would like to thank the following people for offering suggestions, +corrections and assistance with various drafts of this article: Ian Bicking, +Nick Coghlan, Nick Efford, Raymond Hettinger, Jim Jewett, Mike Krell, Leandro +Lameiro, Jussi Salmela, Collin Winter, Blake Winton. + +Version 0.1: posted June 30 2006. + +Version 0.11: posted July 1 2006. Typo fixes. + +Version 0.2: posted July 10 2006. Merged genexp and listcomp sections into one. +Typo fixes. + +Version 0.21: Added more references suggested on the tutor mailing list. + +Version 0.30: Adds a section on the ``functional`` module written by Collin +Winter; adds short section on the operator module; a few other edits. + + +References +========== + +General +------- + +**Structure and Interpretation of Computer Programs**, by Harold Abelson and +Gerald Jay Sussman with Julie Sussman. Full text at +http://mitpress.mit.edu/sicp/. In this classic textbook of computer science, +chapters 2 and 3 discuss the use of sequences and streams to organize the data +flow inside a program. The book uses Scheme for its examples, but many of the +design approaches described in these chapters are applicable to functional-style +Python code. + +http://www.defmacro.org/ramblings/fp.html: A general introduction to functional +programming that uses Java examples and has a lengthy historical introduction. + +http://en.wikipedia.org/wiki/Functional_programming: General Wikipedia entry +describing functional programming. + +http://en.wikipedia.org/wiki/Coroutine: Entry for coroutines. + +http://en.wikipedia.org/wiki/Currying: Entry for the concept of currying. + +Python-specific +--------------- + +http://gnosis.cx/TPiP/: The first chapter of David Mertz's book +:title-reference:`Text Processing in Python` discusses functional programming +for text processing, in the section titled "Utilizing Higher-Order Functions in +Text Processing". + +Mertz also wrote a 3-part series of articles on functional programming +for IBM's DeveloperWorks site; see +`part 1 `__, +`part 2 `__, and +`part 3 `__, + + +Python documentation +-------------------- + +Documentation for the :mod:`itertools` module. + +Documentation for the :mod:`operator` module. + +:pep:`289`: "Generator Expressions" + +:pep:`342`: "Coroutines via Enhanced Generators" describes the new generator +features in Python 2.5. + +.. comment + + Topics to place + ----------------------------- + + XXX os.walk() + + XXX Need a large example. + + But will an example add much? I'll post a first draft and see + what the comments say. + +.. comment + + Original outline: + Introduction + Idea of FP + Programs built out of functions + Functions are strictly input-output, no internal state + Opposed to OO programming, where objects have state + + Why FP? + Formal provability + Assignment is difficult to reason about + Not very relevant to Python + Modularity + Small functions that do one thing + Debuggability: + Easy to test due to lack of state + Easy to verify output from intermediate steps + Composability + You assemble a toolbox of functions that can be mixed + + Tackling a problem + Need a significant example + + Iterators + Generators + The itertools module + List comprehensions + Small functions and the lambda statement + Built-in functions + map + filter + reduce + +.. comment + + Handy little function for printing part of an iterator -- used + while writing this document. + + import itertools + def print_iter(it): + slice = itertools.islice(it, 10) + for elem in slice[:-1]: + sys.stdout.write(str(elem)) + sys.stdout.write(', ') + print elem[-1] + + Added: doctools/trunk/Doc-3k/howto/index.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-3k/howto/index.rst Thu Aug 2 23:31:34 2007 @@ -0,0 +1,24 @@ +*************** + Python HOWTOs +*************** + +Python HOWTOs are documents that cover a single, specific topic, +and attempt to cover it fairly completely. Modelled on the Linux +Documentation Project's HOWTO collection, this collection is an +effort to foster documentation that's more detailed than the +Python Library Reference. + +Currently, the HOWTOs are: + +.. toctree:: + :maxdepth: 1 + + advocacy.rst + curses.rst + doanddont.rst + functional.rst + regex.rst + sockets.rst + unicode.rst + urllib2.rst + Added: doctools/trunk/Doc-3k/howto/regex.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-3k/howto/regex.rst Thu Aug 2 23:31:34 2007 @@ -0,0 +1,1377 @@ +**************************** + Regular Expression HOWTO +**************************** + +:Author: A.M. Kuchling +:Release: 0.05 + +.. % TODO: +.. % Document lookbehind assertions +.. % Better way of displaying a RE, a string, and what it matches +.. % Mention optional argument to match.groups() +.. % Unicode (at least a reference) + + +.. topic:: Abstract + + This document is an introductory tutorial to using regular expressions in Python + with the :mod:`re` module. It provides a gentler introduction than the + corresponding section in the Library Reference. + + +Introduction +============ + +The :mod:`re` module was added in Python 1.5, and provides Perl-style regular +expression patterns. Earlier versions of Python came with the :mod:`regex` +module, which provided Emacs-style patterns. The :mod:`regex` module was +removed completely in Python 2.5. + +Regular expressions (called REs, or regexes, or regex patterns) are essentially +a tiny, highly specialized programming language embedded inside Python and made +available through the :mod:`re` module. Using this little language, you specify +the rules for the set of possible strings that you want to match; this set might +contain English sentences, or e-mail addresses, or TeX commands, or anything you +like. You can then ask questions such as "Does this string match the pattern?", +or "Is there a match for the pattern anywhere in this string?". You can also +use REs to modify a string or to split it apart in various ways. + +Regular expression patterns are compiled into a series of bytecodes which are +then executed by a matching engine written in C. For advanced use, it may be +necessary to pay careful attention to how the engine will execute a given RE, +and write the RE in a certain way in order to produce bytecode that runs faster. +Optimization isn't covered in this document, because it requires that you have a +good understanding of the matching engine's internals. + +The regular expression language is relatively small and restricted, so not all +possible string processing tasks can be done using regular expressions. There +are also tasks that *can* be done with regular expressions, but the expressions +turn out to be very complicated. In these cases, you may be better off writing +Python code to do the processing; while Python code will be slower than an +elaborate regular expression, it will also probably be more understandable. + + +Simple Patterns +=============== + +We'll start by learning about the simplest possible regular expressions. Since +regular expressions are used to operate on strings, we'll begin with the most +common task: matching characters. + +For a detailed explanation of the computer science underlying regular +expressions (deterministic and non-deterministic finite automata), you can refer +to almost any textbook on writing compilers. + + +Matching Characters +------------------- + +Most letters and characters will simply match themselves. For example, the +regular expression ``test`` will match the string ``test`` exactly. (You can +enable a case-insensitive mode that would let this RE match ``Test`` or ``TEST`` +as well; more about this later.) + +There are exceptions to this rule; some characters are special +:dfn:`metacharacters`, and don't match themselves. Instead, they signal that +some out-of-the-ordinary thing should be matched, or they affect other portions +of the RE by repeating them or changing their meaning. Much of this document is +devoted to discussing various metacharacters and what they do. + +Here's a complete list of the metacharacters; their meanings will be discussed +in the rest of this HOWTO. :: + + . ^ $ * + ? { [ ] \ | ( ) + +The first metacharacters we'll look at are ``[`` and ``]``. They're used for +specifying a character class, which is a set of characters that you wish to +match. Characters can be listed individually, or a range of characters can be +indicated by giving two characters and separating them by a ``'-'``. For +example, ``[abc]`` will match any of the characters ``a``, ``b``, or ``c``; this +is the same as ``[a-c]``, which uses a range to express the same set of +characters. If you wanted to match only lowercase letters, your RE would be +``[a-z]``. + +.. % $ + +Metacharacters are not active inside classes. For example, ``[akm$]`` will +match any of the characters ``'a'``, ``'k'``, ``'m'``, or ``'$'``; ``'$'`` is +usually a metacharacter, but inside a character class it's stripped of its +special nature. + +You can match the characters not listed within the class by :dfn:`complementing` +the set. This is indicated by including a ``'^'`` as the first character of the +class; ``'^'`` outside a character class will simply match the ``'^'`` +character. For example, ``[^5]`` will match any character except ``'5'``. + +Perhaps the most important metacharacter is the backslash, ``\``. As in Python +string literals, the backslash can be followed by various characters to signal +various special sequences. It's also used to escape all the metacharacters so +you can still match them in patterns; for example, if you need to match a ``[`` +or ``\``, you can precede them with a backslash to remove their special +meaning: ``\[`` or ``\\``. + +Some of the special sequences beginning with ``'\'`` represent predefined sets +of characters that are often useful, such as the set of digits, the set of +letters, or the set of anything that isn't whitespace. The following predefined +special sequences are available: + +``\d`` + Matches any decimal digit; this is equivalent to the class ``[0-9]``. + +``\D`` + Matches any non-digit character; this is equivalent to the class ``[^0-9]``. + +``\s`` + Matches any whitespace character; this is equivalent to the class ``[ + \t\n\r\f\v]``. + +``\S`` + Matches any non-whitespace character; this is equivalent to the class ``[^ + \t\n\r\f\v]``. + +``\w`` + Matches any alphanumeric character; this is equivalent to the class + ``[a-zA-Z0-9_]``. + +``\W`` + Matches any non-alphanumeric character; this is equivalent to the class + ``[^a-zA-Z0-9_]``. + +These sequences can be included inside a character class. For example, +``[\s,.]`` is a character class that will match any whitespace character, or +``','`` or ``'.'``. + +The final metacharacter in this section is ``.``. It matches anything except a +newline character, and there's an alternate mode (``re.DOTALL``) where it will +match even a newline. ``'.'`` is often used where you want to match "any +character". + + +Repeating Things +---------------- + +Being able to match varying sets of characters is the first thing regular +expressions can do that isn't already possible with the methods available on +strings. However, if that was the only additional capability of regexes, they +wouldn't be much of an advance. Another capability is that you can specify that +portions of the RE must be repeated a certain number of times. + +The first metacharacter for repeating things that we'll look at is ``*``. ``*`` +doesn't match the literal character ``*``; instead, it specifies that the +previous character can be matched zero or more times, instead of exactly once. + +For example, ``ca*t`` will match ``ct`` (0 ``a`` characters), ``cat`` (1 ``a``), +``caaat`` (3 ``a`` characters), and so forth. The RE engine has various +internal limitations stemming from the size of C's ``int`` type that will +prevent it from matching over 2 billion ``a`` characters; you probably don't +have enough memory to construct a string that large, so you shouldn't run into +that limit. + +Repetitions such as ``*`` are :dfn:`greedy`; when repeating a RE, the matching +engine will try to repeat it as many times as possible. If later portions of the +pattern don't match, the matching engine will then back up and try again with +few repetitions. + +A step-by-step example will make this more obvious. Let's consider the +expression ``a[bcd]*b``. This matches the letter ``'a'``, zero or more letters +from the class ``[bcd]``, and finally ends with a ``'b'``. Now imagine matching +this RE against the string ``abcbd``. + ++------+-----------+---------------------------------+ +| Step | Matched | Explanation | ++======+===========+=================================+ +| 1 | ``a`` | The ``a`` in the RE matches. | ++------+-----------+---------------------------------+ +| 2 | ``abcbd`` | The engine matches ``[bcd]*``, | +| | | going as far as it can, which | +| | | is to the end of the string. | ++------+-----------+---------------------------------+ +| 3 | *Failure* | The engine tries to match | +| | | ``b``, but the current position | +| | | is at the end of the string, so | +| | | it fails. | ++------+-----------+---------------------------------+ +| 4 | ``abcb`` | Back up, so that ``[bcd]*`` | +| | | matches one less character. | ++------+-----------+---------------------------------+ +| 5 | *Failure* | Try ``b`` again, but the | +| | | current position is at the last | +| | | character, which is a ``'d'``. | ++------+-----------+---------------------------------+ +| 6 | ``abc`` | Back up again, so that | +| | | ``[bcd]*`` is only matching | +| | | ``bc``. | ++------+-----------+---------------------------------+ +| 6 | ``abcb`` | Try ``b`` again. This time | +| | | but the character at the | +| | | current position is ``'b'``, so | +| | | it succeeds. | ++------+-----------+---------------------------------+ + +The end of the RE has now been reached, and it has matched ``abcb``. This +demonstrates how the matching engine goes as far as it can at first, and if no +match is found it will then progressively back up and retry the rest of the RE +again and again. It will back up until it has tried zero matches for +``[bcd]*``, and if that subsequently fails, the engine will conclude that the +string doesn't match the RE at all. + +Another repeating metacharacter is ``+``, which matches one or more times. Pay +careful attention to the difference between ``*`` and ``+``; ``*`` matches +*zero* or more times, so whatever's being repeated may not be present at all, +while ``+`` requires at least *one* occurrence. To use a similar example, +``ca+t`` will match ``cat`` (1 ``a``), ``caaat`` (3 ``a``'s), but won't match +``ct``. + +There are two more repeating qualifiers. The question mark character, ``?``, +matches either once or zero times; you can think of it as marking something as +being optional. For example, ``home-?brew`` matches either ``homebrew`` or +``home-brew``. + +The most complicated repeated qualifier is ``{m,n}``, where *m* and *n* are +decimal integers. This qualifier means there must be at least *m* repetitions, +and at most *n*. For example, ``a/{1,3}b`` will match ``a/b``, ``a//b``, and +``a///b``. It won't match ``ab``, which has no slashes, or ``a////b``, which +has four. + +You can omit either *m* or *n*; in that case, a reasonable value is assumed for +the missing value. Omitting *m* is interpreted as a lower limit of 0, while +omitting *n* results in an upper bound of infinity --- actually, the upper bound +is the 2-billion limit mentioned earlier, but that might as well be infinity. + +Readers of a reductionist bent may notice that the three other qualifiers can +all be expressed using this notation. ``{0,}`` is the same as ``*``, ``{1,}`` +is equivalent to ``+``, and ``{0,1}`` is the same as ``?``. It's better to use +``*``, ``+``, or ``?`` when you can, simply because they're shorter and easier +to read. + + +Using Regular Expressions +========================= + +Now that we've looked at some simple regular expressions, how do we actually use +them in Python? The :mod:`re` module provides an interface to the regular +expression engine, allowing you to compile REs into objects and then perform +matches with them. + + +Compiling Regular Expressions +----------------------------- + +Regular expressions are compiled into :class:`RegexObject` instances, which have +methods for various operations such as searching for pattern matches or +performing string substitutions. :: + + >>> import re + >>> p = re.compile('ab*') + >>> print p + + +:func:`re.compile` also accepts an optional *flags* argument, used to enable +various special features and syntax variations. We'll go over the available +settings later, but for now a single example will do:: + + >>> p = re.compile('ab*', re.IGNORECASE) + +The RE is passed to :func:`re.compile` as a string. REs are handled as strings +because regular expressions aren't part of the core Python language, and no +special syntax was created for expressing them. (There are applications that +don't need REs at all, so there's no need to bloat the language specification by +including them.) Instead, the :mod:`re` module is simply a C extension module +included with Python, just like the :mod:`socket` or :mod:`zlib` modules. + +Putting REs in strings keeps the Python language simpler, but has one +disadvantage which is the topic of the next section. + + +The Backslash Plague +-------------------- + +As stated earlier, regular expressions use the backslash character (``'\'``) to +indicate special forms or to allow special characters to be used without +invoking their special meaning. This conflicts with Python's usage of the same +character for the same purpose in string literals. + +Let's say you want to write a RE that matches the string ``\section``, which +might be found in a LaTeX file. To figure out what to write in the program +code, start with the desired string to be matched. Next, you must escape any +backslashes and other metacharacters by preceding them with a backslash, +resulting in the string ``\\section``. The resulting string that must be passed +to :func:`re.compile` must be ``\\section``. However, to express this as a +Python string literal, both backslashes must be escaped *again*. + ++-------------------+------------------------------------------+ +| Characters | Stage | ++===================+==========================================+ +| ``\section`` | Text string to be matched | ++-------------------+------------------------------------------+ +| ``\\section`` | Escaped backslash for :func:`re.compile` | ++-------------------+------------------------------------------+ +| ``"\\\\section"`` | Escaped backslashes for a string literal | ++-------------------+------------------------------------------+ + +In short, to match a literal backslash, one has to write ``'\\\\'`` as the RE +string, because the regular expression must be ``\\``, and each backslash must +be expressed as ``\\`` inside a regular Python string literal. In REs that +feature backslashes repeatedly, this leads to lots of repeated backslashes and +makes the resulting strings difficult to understand. + +The solution is to use Python's raw string notation for regular expressions; +backslashes are not handled in any special way in a string literal prefixed with +``'r'``, so ``r"\n"`` is a two-character string containing ``'\'`` and ``'n'``, +while ``"\n"`` is a one-character string containing a newline. Regular +expressions will often be written in Python code using this raw string notation. + ++-------------------+------------------+ +| Regular String | Raw string | ++===================+==================+ +| ``"ab*"`` | ``r"ab*"`` | ++-------------------+------------------+ +| ``"\\\\section"`` | ``r"\\section"`` | ++-------------------+------------------+ +| ``"\\w+\\s+\\1"`` | ``r"\w+\s+\1"`` | ++-------------------+------------------+ + + +Performing Matches +------------------ + +Once you have an object representing a compiled regular expression, what do you +do with it? :class:`RegexObject` instances have several methods and attributes. +Only the most significant ones will be covered here; consult `the Library +Reference `_ for a complete +listing. + ++------------------+-----------------------------------------------+ +| Method/Attribute | Purpose | ++==================+===============================================+ +| ``match()`` | Determine if the RE matches at the beginning | +| | of the string. | ++------------------+-----------------------------------------------+ +| ``search()`` | Scan through a string, looking for any | +| | location where this RE matches. | ++------------------+-----------------------------------------------+ +| ``findall()`` | Find all substrings where the RE matches, and | +| | returns them as a list. | ++------------------+-----------------------------------------------+ +| ``finditer()`` | Find all substrings where the RE matches, and | +| | returns them as an iterator. | ++------------------+-----------------------------------------------+ + +:meth:`match` and :meth:`search` return ``None`` if no match can be found. If +they're successful, a ``MatchObject`` instance is returned, containing +information about the match: where it starts and ends, the substring it matched, +and more. + +You can learn about this by interactively experimenting with the :mod:`re` +module. If you have Tkinter available, you may also want to look at +:file:`Tools/scripts/redemo.py`, a demonstration program included with the +Python distribution. It allows you to enter REs and strings, and displays +whether the RE matches or fails. :file:`redemo.py` can be quite useful when +trying to debug a complicated RE. Phil Schwartz's `Kodos `_ is also an interactive tool for developing and testing +RE patterns. + +This HOWTO uses the standard Python interpreter for its examples. First, run the +Python interpreter, import the :mod:`re` module, and compile a RE:: + + Python 2.2.2 (#1, Feb 10 2003, 12:57:01) + >>> import re + >>> p = re.compile('[a-z]+') + >>> p + <_sre.SRE_Pattern object at 80c3c28> + +Now, you can try matching various strings against the RE ``[a-z]+``. An empty +string shouldn't match at all, since ``+`` means 'one or more repetitions'. +:meth:`match` should return ``None`` in this case, which will cause the +interpreter to print no output. You can explicitly print the result of +:meth:`match` to make this clear. :: + + >>> p.match("") + >>> print p.match("") + None + +Now, let's try it on a string that it should match, such as ``tempo``. In this +case, :meth:`match` will return a :class:`MatchObject`, so you should store the +result in a variable for later use. :: + + >>> m = p.match('tempo') + >>> print m + <_sre.SRE_Match object at 80c4f68> + +Now you can query the :class:`MatchObject` for information about the matching +string. :class:`MatchObject` instances also have several methods and +attributes; the most important ones are: + ++------------------+--------------------------------------------+ +| Method/Attribute | Purpose | ++==================+============================================+ +| ``group()`` | Return the string matched by the RE | ++------------------+--------------------------------------------+ +| ``start()`` | Return the starting position of the match | ++------------------+--------------------------------------------+ +| ``end()`` | Return the ending position of the match | ++------------------+--------------------------------------------+ +| ``span()`` | Return a tuple containing the (start, end) | +| | positions of the match | ++------------------+--------------------------------------------+ + +Trying these methods will soon clarify their meaning:: + + >>> m.group() + 'tempo' + >>> m.start(), m.end() + (0, 5) + >>> m.span() + (0, 5) + +:meth:`group` returns the substring that was matched by the RE. :meth:`start` +and :meth:`end` return the starting and ending index of the match. :meth:`span` +returns both start and end indexes in a single tuple. Since the :meth:`match` +method only checks if the RE matches at the start of a string, :meth:`start` +will always be zero. However, the :meth:`search` method of :class:`RegexObject` +instances scans through the string, so the match may not start at zero in that +case. :: + + >>> print p.match('::: message') + None + >>> m = p.search('::: message') ; print m + + >>> m.group() + 'message' + >>> m.span() + (4, 11) + +In actual programs, the most common style is to store the :class:`MatchObject` +in a variable, and then check if it was ``None``. This usually looks like:: + + p = re.compile( ... ) + m = p.match( 'string goes here' ) + if m: + print 'Match found: ', m.group() + else: + print 'No match' + +Two :class:`RegexObject` methods return all of the matches for a pattern. +:meth:`findall` returns a list of matching strings:: + + >>> p = re.compile('\d+') + >>> p.findall('12 drummers drumming, 11 pipers piping, 10 lords a-leaping') + ['12', '11', '10'] + +:meth:`findall` has to create the entire list before it can be returned as the +result. The :meth:`finditer` method returns a sequence of :class:`MatchObject` +instances as an iterator. [#]_ :: + + >>> iterator = p.finditer('12 drummers drumming, 11 ... 10 ...') + >>> iterator + + >>> for match in iterator: + ... print match.span() + ... + (0, 2) + (22, 24) + (29, 31) + + +Module-Level Functions +---------------------- + +You don't have to create a :class:`RegexObject` and call its methods; the +:mod:`re` module also provides top-level functions called :func:`match`, +:func:`search`, :func:`findall`, :func:`sub`, and so forth. These functions +take the same arguments as the corresponding :class:`RegexObject` method, with +the RE string added as the first argument, and still return either ``None`` or a +:class:`MatchObject` instance. :: + + >>> print re.match(r'From\s+', 'Fromage amk') + None + >>> re.match(r'From\s+', 'From amk Thu May 14 19:12:10 1998') + + +Under the hood, these functions simply produce a :class:`RegexObject` for you +and call the appropriate method on it. They also store the compiled object in a +cache, so future calls using the same RE are faster. + +Should you use these module-level functions, or should you get the +:class:`RegexObject` and call its methods yourself? That choice depends on how +frequently the RE will be used, and on your personal coding style. If the RE is +being used at only one point in the code, then the module functions are probably +more convenient. If a program contains a lot of regular expressions, or re-uses +the same ones in several locations, then it might be worthwhile to collect all +the definitions in one place, in a section of code that compiles all the REs +ahead of time. To take an example from the standard library, here's an extract +from :file:`xmllib.py`:: + + ref = re.compile( ... ) + entityref = re.compile( ... ) + charref = re.compile( ... ) + starttagopen = re.compile( ... ) + +I generally prefer to work with the compiled object, even for one-time uses, but +few people will be as much of a purist about this as I am. + + +Compilation Flags +----------------- + +Compilation flags let you modify some aspects of how regular expressions work. +Flags are available in the :mod:`re` module under two names, a long name such as +:const:`IGNORECASE` and a short, one-letter form such as :const:`I`. (If you're +familiar with Perl's pattern modifiers, the one-letter forms use the same +letters; the short form of :const:`re.VERBOSE` is :const:`re.X`, for example.) +Multiple flags can be specified by bitwise OR-ing them; ``re.I | re.M`` sets +both the :const:`I` and :const:`M` flags, for example. + +Here's a table of the available flags, followed by a more detailed explanation +of each one. + ++---------------------------------+--------------------------------------------+ +| Flag | Meaning | ++=================================+============================================+ +| :const:`DOTALL`, :const:`S` | Make ``.`` match any character, including | +| | newlines | ++---------------------------------+--------------------------------------------+ +| :const:`IGNORECASE`, :const:`I` | Do case-insensitive matches | ++---------------------------------+--------------------------------------------+ +| :const:`LOCALE`, :const:`L` | Do a locale-aware match | ++---------------------------------+--------------------------------------------+ +| :const:`MULTILINE`, :const:`M` | Multi-line matching, affecting ``^`` and | +| | ``$`` | ++---------------------------------+--------------------------------------------+ +| :const:`VERBOSE`, :const:`X` | Enable verbose REs, which can be organized | +| | more cleanly and understandably. | ++---------------------------------+--------------------------------------------+ + + +.. data:: I + IGNORECASE + :noindex: + + Perform case-insensitive matching; character class and literal strings will + match letters by ignoring case. For example, ``[A-Z]`` will match lowercase + letters, too, and ``Spam`` will match ``Spam``, ``spam``, or ``spAM``. This + lowercasing doesn't take the current locale into account; it will if you also + set the :const:`LOCALE` flag. + + +.. data:: L + LOCALE + :noindex: + + Make ``\w``, ``\W``, ``\b``, and ``\B``, dependent on the current locale. + + Locales are a feature of the C library intended to help in writing programs that + take account of language differences. For example, if you're processing French + text, you'd want to be able to write ``\w+`` to match words, but ``\w`` only + matches the character class ``[A-Za-z]``; it won't match ``'?'`` or ``'?'``. If + your system is configured properly and a French locale is selected, certain C + functions will tell the program that ``'?'`` should also be considered a letter. + Setting the :const:`LOCALE` flag when compiling a regular expression will cause + the resulting compiled object to use these C functions for ``\w``; this is + slower, but also enables ``\w+`` to match French words as you'd expect. + + +.. data:: M + MULTILINE + :noindex: + + (``^`` and ``$`` haven't been explained yet; they'll be introduced in section + :ref:`more-metacharacters`.) + + Usually ``^`` matches only at the beginning of the string, and ``$`` matches + only at the end of the string and immediately before the newline (if any) at the + end of the string. When this flag is specified, ``^`` matches at the beginning + of the string and at the beginning of each line within the string, immediately + following each newline. Similarly, the ``$`` metacharacter matches either at + the end of the string and at the end of each line (immediately preceding each + newline). + + +.. data:: S + DOTALL + :noindex: + + Makes the ``'.'`` special character match any character at all, including a + newline; without this flag, ``'.'`` will match anything *except* a newline. + + +.. data:: X + VERBOSE + :noindex: + + This flag allows you to write regular expressions that are more readable by + granting you more flexibility in how you can format them. When this flag has + been specified, whitespace within the RE string is ignored, except when the + whitespace is in a character class or preceded by an unescaped backslash; this + lets you organize and indent the RE more clearly. This flag also lets you put + comments within a RE that will be ignored by the engine; comments are marked by + a ``'#'`` that's neither in a character class or preceded by an unescaped + backslash. + + For example, here's a RE that uses :const:`re.VERBOSE`; see how much easier it + is to read? :: + + charref = re.compile(r""" + &[#] # Start of a numeric entity reference + ( + 0[0-7]+ # Octal form + | [0-9]+ # Decimal form + | x[0-9a-fA-F]+ # Hexadecimal form + ) + ; # Trailing semicolon + """, re.VERBOSE) + + Without the verbose setting, the RE would look like this:: + + charref = re.compile("&#(0[0-7]+" + "|[0-9]+" + "|x[0-9a-fA-F]+);") + + In the above example, Python's automatic concatenation of string literals has + been used to break up the RE into smaller pieces, but it's still more difficult + to understand than the version using :const:`re.VERBOSE`. + + +More Pattern Power +================== + +So far we've only covered a part of the features of regular expressions. In +this section, we'll cover some new metacharacters, and how to use groups to +retrieve portions of the text that was matched. + + +.. _more-metacharacters: + +More Metacharacters +------------------- + +There are some metacharacters that we haven't covered yet. Most of them will be +covered in this section. + +Some of the remaining metacharacters to be discussed are :dfn:`zero-width +assertions`. They don't cause the engine to advance through the string; +instead, they consume no characters at all, and simply succeed or fail. For +example, ``\b`` is an assertion that the current position is located at a word +boundary; the position isn't changed by the ``\b`` at all. This means that +zero-width assertions should never be repeated, because if they match once at a +given location, they can obviously be matched an infinite number of times. + +``|`` + Alternation, or the "or" operator. If A and B are regular expressions, + ``A|B`` will match any string that matches either ``A`` or ``B``. ``|`` has very + low precedence in order to make it work reasonably when you're alternating + multi-character strings. ``Crow|Servo`` will match either ``Crow`` or ``Servo``, + not ``Cro``, a ``'w'`` or an ``'S'``, and ``ervo``. + + To match a literal ``'|'``, use ``\|``, or enclose it inside a character class, + as in ``[|]``. + +``^`` + Matches at the beginning of lines. Unless the :const:`MULTILINE` flag has been + set, this will only match at the beginning of the string. In :const:`MULTILINE` + mode, this also matches immediately after each newline within the string. + + For example, if you wish to match the word ``From`` only at the beginning of a + line, the RE to use is ``^From``. :: + + >>> print re.search('^From', 'From Here to Eternity') + + >>> print re.search('^From', 'Reciting From Memory') + None + + .. % To match a literal \character{\^}, use \regexp{\e\^} or enclose it + .. % inside a character class, as in \regexp{[{\e}\^]}. + +``$`` + Matches at the end of a line, which is defined as either the end of the string, + or any location followed by a newline character. :: + + >>> print re.search('}$', '{block}') + + >>> print re.search('}$', '{block} ') + None + >>> print re.search('}$', '{block}\n') + + + To match a literal ``'$'``, use ``\$`` or enclose it inside a character class, + as in ``[$]``. + + .. % $ + +``\A`` + Matches only at the start of the string. When not in :const:`MULTILINE` mode, + ``\A`` and ``^`` are effectively the same. In :const:`MULTILINE` mode, they're + different: ``\A`` still matches only at the beginning of the string, but ``^`` + may match at any location inside the string that follows a newline character. + +``\Z`` + Matches only at the end of the string. + +``\b`` + Word boundary. This is a zero-width assertion that matches only at the + beginning or end of a word. A word is defined as a sequence of alphanumeric + characters, so the end of a word is indicated by whitespace or a non- + alphanumeric character. + + The following example matches ``class`` only when it's a complete word; it won't + match when it's contained inside another word. :: + + >>> p = re.compile(r'\bclass\b') + >>> print p.search('no class at all') + + >>> print p.search('the declassified algorithm') + None + >>> print p.search('one subclass is') + None + + There are two subtleties you should remember when using this special sequence. + First, this is the worst collision between Python's string literals and regular + expression sequences. In Python's string literals, ``\b`` is the backspace + character, ASCII value 8. If you're not using raw strings, then Python will + convert the ``\b`` to a backspace, and your RE won't match as you expect it to. + The following example looks the same as our previous RE, but omits the ``'r'`` + in front of the RE string. :: + + >>> p = re.compile('\bclass\b') + >>> print p.search('no class at all') + None + >>> print p.search('\b' + 'class' + '\b') + + + Second, inside a character class, where there's no use for this assertion, + ``\b`` represents the backspace character, for compatibility with Python's + string literals. + +``\B`` + Another zero-width assertion, this is the opposite of ``\b``, only matching when + the current position is not at a word boundary. + + +Grouping +-------- + +Frequently you need to obtain more information than just whether the RE matched +or not. Regular expressions are often used to dissect strings by writing a RE +divided into several subgroups which match different components of interest. +For example, an RFC-822 header line is divided into a header name and a value, +separated by a ``':'``, like this:: + + From: author at example.com + User-Agent: Thunderbird 1.5.0.9 (X11/20061227) + MIME-Version: 1.0 + To: editor at example.com + +This can be handled by writing a regular expression which matches an entire +header line, and has one group which matches the header name, and another group +which matches the header's value. + +Groups are marked by the ``'('``, ``')'`` metacharacters. ``'('`` and ``')'`` +have much the same meaning as they do in mathematical expressions; they group +together the expressions contained inside them, and you can repeat the contents +of a group with a repeating qualifier, such as ``*``, ``+``, ``?``, or +``{m,n}``. For example, ``(ab)*`` will match zero or more repetitions of +``ab``. :: + + >>> p = re.compile('(ab)*') + >>> print p.match('ababababab').span() + (0, 10) + +Groups indicated with ``'('``, ``')'`` also capture the starting and ending +index of the text that they match; this can be retrieved by passing an argument +to :meth:`group`, :meth:`start`, :meth:`end`, and :meth:`span`. Groups are +numbered starting with 0. Group 0 is always present; it's the whole RE, so +:class:`MatchObject` methods all have group 0 as their default argument. Later +we'll see how to express groups that don't capture the span of text that they +match. :: + + >>> p = re.compile('(a)b') + >>> m = p.match('ab') + >>> m.group() + 'ab' + >>> m.group(0) + 'ab' + +Subgroups are numbered from left to right, from 1 upward. Groups can be nested; +to determine the number, just count the opening parenthesis characters, going +from left to right. :: + + >>> p = re.compile('(a(b)c)d') + >>> m = p.match('abcd') + >>> m.group(0) + 'abcd' + >>> m.group(1) + 'abc' + >>> m.group(2) + 'b' + +:meth:`group` can be passed multiple group numbers at a time, in which case it +will return a tuple containing the corresponding values for those groups. :: + + >>> m.group(2,1,2) + ('b', 'abc', 'b') + +The :meth:`groups` method returns a tuple containing the strings for all the +subgroups, from 1 up to however many there are. :: + + >>> m.groups() + ('abc', 'b') + +Backreferences in a pattern allow you to specify that the contents of an earlier +capturing group must also be found at the current location in the string. For +example, ``\1`` will succeed if the exact contents of group 1 can be found at +the current position, and fails otherwise. Remember that Python's string +literals also use a backslash followed by numbers to allow including arbitrary +characters in a string, so be sure to use a raw string when incorporating +backreferences in a RE. + +For example, the following RE detects doubled words in a string. :: + + >>> p = re.compile(r'(\b\w+)\s+\1') + >>> p.search('Paris in the the spring').group() + 'the the' + +Backreferences like this aren't often useful for just searching through a string +--- there are few text formats which repeat data in this way --- but you'll soon +find out that they're *very* useful when performing string substitutions. + + +Non-capturing and Named Groups +------------------------------ + +Elaborate REs may use many groups, both to capture substrings of interest, and +to group and structure the RE itself. In complex REs, it becomes difficult to +keep track of the group numbers. There are two features which help with this +problem. Both of them use a common syntax for regular expression extensions, so +we'll look at that first. + +Perl 5 added several additional features to standard regular expressions, and +the Python :mod:`re` module supports most of them. It would have been +difficult to choose new single-keystroke metacharacters or new special sequences +beginning with ``\`` to represent the new features without making Perl's regular +expressions confusingly different from standard REs. If you chose ``&`` as a +new metacharacter, for example, old expressions would be assuming that ``&`` was +a regular character and wouldn't have escaped it by writing ``\&`` or ``[&]``. + +The solution chosen by the Perl developers was to use ``(?...)`` as the +extension syntax. ``?`` immediately after a parenthesis was a syntax error +because the ``?`` would have nothing to repeat, so this didn't introduce any +compatibility problems. The characters immediately after the ``?`` indicate +what extension is being used, so ``(?=foo)`` is one thing (a positive lookahead +assertion) and ``(?:foo)`` is something else (a non-capturing group containing +the subexpression ``foo``). + +Python adds an extension syntax to Perl's extension syntax. If the first +character after the question mark is a ``P``, you know that it's an extension +that's specific to Python. Currently there are two such extensions: +``(?P...)`` defines a named group, and ``(?P=name)`` is a backreference to +a named group. If future versions of Perl 5 add similar features using a +different syntax, the :mod:`re` module will be changed to support the new +syntax, while preserving the Python-specific syntax for compatibility's sake. + +Now that we've looked at the general extension syntax, we can return to the +features that simplify working with groups in complex REs. Since groups are +numbered from left to right and a complex expression may use many groups, it can +become difficult to keep track of the correct numbering. Modifying such a +complex RE is annoying, too: insert a new group near the beginning and you +change the numbers of everything that follows it. + +Sometimes you'll want to use a group to collect a part of a regular expression, +but aren't interested in retrieving the group's contents. You can make this fact +explicit by using a non-capturing group: ``(?:...)``, where you can replace the +``...`` with any other regular expression. :: + + >>> m = re.match("([abc])+", "abc") + >>> m.groups() + ('c',) + >>> m = re.match("(?:[abc])+", "abc") + >>> m.groups() + () + +Except for the fact that you can't retrieve the contents of what the group +matched, a non-capturing group behaves exactly the same as a capturing group; +you can put anything inside it, repeat it with a repetition metacharacter such +as ``*``, and nest it within other groups (capturing or non-capturing). +``(?:...)`` is particularly useful when modifying an existing pattern, since you +can add new groups without changing how all the other groups are numbered. It +should be mentioned that there's no performance difference in searching between +capturing and non-capturing groups; neither form is any faster than the other. + +A more significant feature is named groups: instead of referring to them by +numbers, groups can be referenced by a name. + +The syntax for a named group is one of the Python-specific extensions: +``(?P...)``. *name* is, obviously, the name of the group. Named groups +also behave exactly like capturing groups, and additionally associate a name +with a group. The :class:`MatchObject` methods that deal with capturing groups +all accept either integers that refer to the group by number or strings that +contain the desired group's name. Named groups are still given numbers, so you +can retrieve information about a group in two ways:: + + >>> p = re.compile(r'(?P\b\w+\b)') + >>> m = p.search( '(((( Lots of punctuation )))' ) + >>> m.group('word') + 'Lots' + >>> m.group(1) + 'Lots' + +Named groups are handy because they let you use easily-remembered names, instead +of having to remember numbers. Here's an example RE from the :mod:`imaplib` +module:: + + InternalDate = re.compile(r'INTERNALDATE "' + r'(?P[ 123][0-9])-(?P[A-Z][a-z][a-z])-' + r'(?P[0-9][0-9][0-9][0-9])' + r' (?P[0-9][0-9]):(?P[0-9][0-9]):(?P[0-9][0-9])' + r' (?P[-+])(?P[0-9][0-9])(?P[0-9][0-9])' + r'"') + +It's obviously much easier to retrieve ``m.group('zonem')``, instead of having +to remember to retrieve group 9. + +The syntax for backreferences in an expression such as ``(...)\1`` refers to the +number of the group. There's naturally a variant that uses the group name +instead of the number. This is another Python extension: ``(?P=name)`` indicates +that the contents of the group called *name* should again be matched at the +current point. The regular expression for finding doubled words, +``(\b\w+)\s+\1`` can also be written as ``(?P\b\w+)\s+(?P=word)``:: + + >>> p = re.compile(r'(?P\b\w+)\s+(?P=word)') + >>> p.search('Paris in the the spring').group() + 'the the' + + +Lookahead Assertions +-------------------- + +Another zero-width assertion is the lookahead assertion. Lookahead assertions +are available in both positive and negative form, and look like this: + +``(?=...)`` + Positive lookahead assertion. This succeeds if the contained regular + expression, represented here by ``...``, successfully matches at the current + location, and fails otherwise. But, once the contained expression has been + tried, the matching engine doesn't advance at all; the rest of the pattern is + tried right where the assertion started. + +``(?!...)`` + Negative lookahead assertion. This is the opposite of the positive assertion; + it succeeds if the contained expression *doesn't* match at the current position + in the string. + +To make this concrete, let's look at a case where a lookahead is useful. +Consider a simple pattern to match a filename and split it apart into a base +name and an extension, separated by a ``.``. For example, in ``news.rc``, +``news`` is the base name, and ``rc`` is the filename's extension. + +The pattern to match this is quite simple: + +``.*[.].*$`` + +Notice that the ``.`` needs to be treated specially because it's a +metacharacter; I've put it inside a character class. Also notice the trailing +``$``; this is added to ensure that all the rest of the string must be included +in the extension. This regular expression matches ``foo.bar`` and +``autoexec.bat`` and ``sendmail.cf`` and ``printers.conf``. + +Now, consider complicating the problem a bit; what if you want to match +filenames where the extension is not ``bat``? Some incorrect attempts: + +``.*[.][^b].*$`` The first attempt above tries to exclude ``bat`` by requiring +that the first character of the extension is not a ``b``. This is wrong, +because the pattern also doesn't match ``foo.bar``. + +.. % $ + +``.*[.]([^b]..|.[^a].|..[^t])$`` + +.. % Messes up the HTML without the curly braces around \^ + +The expression gets messier when you try to patch up the first solution by +requiring one of the following cases to match: the first character of the +extension isn't ``b``; the second character isn't ``a``; or the third character +isn't ``t``. This accepts ``foo.bar`` and rejects ``autoexec.bat``, but it +requires a three-letter extension and won't accept a filename with a two-letter +extension such as ``sendmail.cf``. We'll complicate the pattern again in an +effort to fix it. + +``.*[.]([^b].?.?|.[^a]?.?|..?[^t]?)$`` + +In the third attempt, the second and third letters are all made optional in +order to allow matching extensions shorter than three characters, such as +``sendmail.cf``. + +The pattern's getting really complicated now, which makes it hard to read and +understand. Worse, if the problem changes and you want to exclude both ``bat`` +and ``exe`` as extensions, the pattern would get even more complicated and +confusing. + +A negative lookahead cuts through all this confusion: + +``.*[.](?!bat$).*$`` The negative lookahead means: if the expression ``bat`` +doesn't match at this point, try the rest of the pattern; if ``bat$`` does +match, the whole pattern will fail. The trailing ``$`` is required to ensure +that something like ``sample.batch``, where the extension only starts with +``bat``, will be allowed. + +.. % $ + +Excluding another filename extension is now easy; simply add it as an +alternative inside the assertion. The following pattern excludes filenames that +end in either ``bat`` or ``exe``: + +``.*[.](?!bat$|exe$).*$`` + +.. % $ + + +Modifying Strings +================= + +Up to this point, we've simply performed searches against a static string. +Regular expressions are also commonly used to modify strings in various ways, +using the following :class:`RegexObject` methods: + ++------------------+-----------------------------------------------+ +| Method/Attribute | Purpose | ++==================+===============================================+ +| ``split()`` | Split the string into a list, splitting it | +| | wherever the RE matches | ++------------------+-----------------------------------------------+ +| ``sub()`` | Find all substrings where the RE matches, and | +| | replace them with a different string | ++------------------+-----------------------------------------------+ +| ``subn()`` | Does the same thing as :meth:`sub`, but | +| | returns the new string and the number of | +| | replacements | ++------------------+-----------------------------------------------+ + + +Splitting Strings +----------------- + +The :meth:`split` method of a :class:`RegexObject` splits a string apart +wherever the RE matches, returning a list of the pieces. It's similar to the +:meth:`split` method of strings but provides much more generality in the +delimiters that you can split by; :meth:`split` only supports splitting by +whitespace or by a fixed string. As you'd expect, there's a module-level +:func:`re.split` function, too. + + +.. method:: .split(string [, maxsplit\ ``= 0``]) + :noindex: + + Split *string* by the matches of the regular expression. If capturing + parentheses are used in the RE, then their contents will also be returned as + part of the resulting list. If *maxsplit* is nonzero, at most *maxsplit* splits + are performed. + +You can limit the number of splits made, by passing a value for *maxsplit*. +When *maxsplit* is nonzero, at most *maxsplit* splits will be made, and the +remainder of the string is returned as the final element of the list. In the +following example, the delimiter is any sequence of non-alphanumeric characters. +:: + + >>> p = re.compile(r'\W+') + >>> p.split('This is a test, short and sweet, of split().') + ['This', 'is', 'a', 'test', 'short', 'and', 'sweet', 'of', 'split', ''] + >>> p.split('This is a test, short and sweet, of split().', 3) + ['This', 'is', 'a', 'test, short and sweet, of split().'] + +Sometimes you're not only interested in what the text between delimiters is, but +also need to know what the delimiter was. If capturing parentheses are used in +the RE, then their values are also returned as part of the list. Compare the +following calls:: + + >>> p = re.compile(r'\W+') + >>> p2 = re.compile(r'(\W+)') + >>> p.split('This... is a test.') + ['This', 'is', 'a', 'test', ''] + >>> p2.split('This... is a test.') + ['This', '... ', 'is', ' ', 'a', ' ', 'test', '.', ''] + +The module-level function :func:`re.split` adds the RE to be used as the first +argument, but is otherwise the same. :: + + >>> re.split('[\W]+', 'Words, words, words.') + ['Words', 'words', 'words', ''] + >>> re.split('([\W]+)', 'Words, words, words.') + ['Words', ', ', 'words', ', ', 'words', '.', ''] + >>> re.split('[\W]+', 'Words, words, words.', 1) + ['Words', 'words, words.'] + + +Search and Replace +------------------ + +Another common task is to find all the matches for a pattern, and replace them +with a different string. The :meth:`sub` method takes a replacement value, +which can be either a string or a function, and the string to be processed. + + +.. method:: .sub(replacement, string[, count\ ``= 0``]) + :noindex: + + Returns the string obtained by replacing the leftmost non-overlapping + occurrences of the RE in *string* by the replacement *replacement*. If the + pattern isn't found, *string* is returned unchanged. + + The optional argument *count* is the maximum number of pattern occurrences to be + replaced; *count* must be a non-negative integer. The default value of 0 means + to replace all occurrences. + +Here's a simple example of using the :meth:`sub` method. It replaces colour +names with the word ``colour``:: + + >>> p = re.compile( '(blue|white|red)') + >>> p.sub( 'colour', 'blue socks and red shoes') + 'colour socks and colour shoes' + >>> p.sub( 'colour', 'blue socks and red shoes', count=1) + 'colour socks and red shoes' + +The :meth:`subn` method does the same work, but returns a 2-tuple containing the +new string value and the number of replacements that were performed:: + + >>> p = re.compile( '(blue|white|red)') + >>> p.subn( 'colour', 'blue socks and red shoes') + ('colour socks and colour shoes', 2) + >>> p.subn( 'colour', 'no colours at all') + ('no colours at all', 0) + +Empty matches are replaced only when they're not adjacent to a previous match. +:: + + >>> p = re.compile('x*') + >>> p.sub('-', 'abxd') + '-a-b-d-' + +If *replacement* is a string, any backslash escapes in it are processed. That +is, ``\n`` is converted to a single newline character, ``\r`` is converted to a +carriage return, and so forth. Unknown escapes such as ``\j`` are left alone. +Backreferences, such as ``\6``, are replaced with the substring matched by the +corresponding group in the RE. This lets you incorporate portions of the +original text in the resulting replacement string. + +This example matches the word ``section`` followed by a string enclosed in +``{``, ``}``, and changes ``section`` to ``subsection``:: + + >>> p = re.compile('section{ ( [^}]* ) }', re.VERBOSE) + >>> p.sub(r'subsection{\1}','section{First} section{second}') + 'subsection{First} subsection{second}' + +There's also a syntax for referring to named groups as defined by the +``(?P...)`` syntax. ``\g`` will use the substring matched by the +group named ``name``, and ``\g`` uses the corresponding group number. +``\g<2>`` is therefore equivalent to ``\2``, but isn't ambiguous in a +replacement string such as ``\g<2>0``. (``\20`` would be interpreted as a +reference to group 20, not a reference to group 2 followed by the literal +character ``'0'``.) The following substitutions are all equivalent, but use all +three variations of the replacement string. :: + + >>> p = re.compile('section{ (?P [^}]* ) }', re.VERBOSE) + >>> p.sub(r'subsection{\1}','section{First}') + 'subsection{First}' + >>> p.sub(r'subsection{\g<1>}','section{First}') + 'subsection{First}' + >>> p.sub(r'subsection{\g}','section{First}') + 'subsection{First}' + +*replacement* can also be a function, which gives you even more control. If +*replacement* is a function, the function is called for every non-overlapping +occurrence of *pattern*. On each call, the function is passed a +:class:`MatchObject` argument for the match and can use this information to +compute the desired replacement string and return it. + +In the following example, the replacement function translates decimals into +hexadecimal:: + + >>> def hexrepl( match ): + ... "Return the hex string for a decimal number" + ... value = int( match.group() ) + ... return hex(value) + ... + >>> p = re.compile(r'\d+') + >>> p.sub(hexrepl, 'Call 65490 for printing, 49152 for user code.') + 'Call 0xffd2 for printing, 0xc000 for user code.' + +When using the module-level :func:`re.sub` function, the pattern is passed as +the first argument. The pattern may be a string or a :class:`RegexObject`; if +you need to specify regular expression flags, you must either use a +:class:`RegexObject` as the first parameter, or use embedded modifiers in the +pattern, e.g. ``sub("(?i)b+", "x", "bbbb BBBB")`` returns ``'x x'``. + + +Common Problems +=============== + +Regular expressions are a powerful tool for some applications, but in some ways +their behaviour isn't intuitive and at times they don't behave the way you may +expect them to. This section will point out some of the most common pitfalls. + + +Use String Methods +------------------ + +Sometimes using the :mod:`re` module is a mistake. If you're matching a fixed +string, or a single character class, and you're not using any :mod:`re` features +such as the :const:`IGNORECASE` flag, then the full power of regular expressions +may not be required. Strings have several methods for performing operations with +fixed strings and they're usually much faster, because the implementation is a +single small C loop that's been optimized for the purpose, instead of the large, +more generalized regular expression engine. + +One example might be replacing a single fixed string with another one; for +example, you might replace ``word`` with ``deed``. ``re.sub()`` seems like the +function to use for this, but consider the :meth:`replace` method. Note that +:func:`replace` will also replace ``word`` inside words, turning ``swordfish`` +into ``sdeedfish``, but the naive RE ``word`` would have done that, too. (To +avoid performing the substitution on parts of words, the pattern would have to +be ``\bword\b``, in order to require that ``word`` have a word boundary on +either side. This takes the job beyond :meth:`replace`'s abilities.) + +Another common task is deleting every occurrence of a single character from a +string or replacing it with another single character. You might do this with +something like ``re.sub('\n', ' ', S)``, but :meth:`translate` is capable of +doing both tasks and will be faster than any regular expression operation can +be. + +In short, before turning to the :mod:`re` module, consider whether your problem +can be solved with a faster and simpler string method. + + +match() versus search() +----------------------- + +The :func:`match` function only checks if the RE matches at the beginning of the +string while :func:`search` will scan forward through the string for a match. +It's important to keep this distinction in mind. Remember, :func:`match` will +only report a successful match which will start at 0; if the match wouldn't +start at zero, :func:`match` will *not* report it. :: + + >>> print re.match('super', 'superstition').span() + (0, 5) + >>> print re.match('super', 'insuperable') + None + +On the other hand, :func:`search` will scan forward through the string, +reporting the first match it finds. :: + + >>> print re.search('super', 'superstition').span() + (0, 5) + >>> print re.search('super', 'insuperable').span() + (2, 7) + +Sometimes you'll be tempted to keep using :func:`re.match`, and just add ``.*`` +to the front of your RE. Resist this temptation and use :func:`re.search` +instead. The regular expression compiler does some analysis of REs in order to +speed up the process of looking for a match. One such analysis figures out what +the first character of a match must be; for example, a pattern starting with +``Crow`` must match starting with a ``'C'``. The analysis lets the engine +quickly scan through the string looking for the starting character, only trying +the full match if a ``'C'`` is found. + +Adding ``.*`` defeats this optimization, requiring scanning to the end of the +string and then backtracking to find a match for the rest of the RE. Use +:func:`re.search` instead. + + +Greedy versus Non-Greedy +------------------------ + +When repeating a regular expression, as in ``a*``, the resulting action is to +consume as much of the pattern as possible. This fact often bites you when +you're trying to match a pair of balanced delimiters, such as the angle brackets +surrounding an HTML tag. The naive pattern for matching a single HTML tag +doesn't work because of the greedy nature of ``.*``. :: + + >>> s = 'Title' + >>> len(s) + 32 + >>> print re.match('<.*>', s).span() + (0, 32) + >>> print re.match('<.*>', s).group() + Title + +The RE matches the ``'<'`` in ````, and the ``.*`` consumes the rest of +the string. There's still more left in the RE, though, and the ``>`` can't +match at the end of the string, so the regular expression engine has to +backtrack character by character until it finds a match for the ``>``. The +final match extends from the ``'<'`` in ```` to the ``'>'`` in +````, which isn't what you want. + +In this case, the solution is to use the non-greedy qualifiers ``*?``, ``+?``, +``??``, or ``{m,n}?``, which match as *little* text as possible. In the above +example, the ``'>'`` is tried immediately after the first ``'<'`` matches, and +when it fails, the engine advances a character at a time, retrying the ``'>'`` +at every step. This produces just the right result:: + + >>> print re.match('<.*?>', s).group() + + +(Note that parsing HTML or XML with regular expressions is painful. Quick-and- +dirty patterns will handle common cases, but HTML and XML have special cases +that will break the obvious regular expression; by the time you've written a +regular expression that handles all of the possible cases, the patterns will be +*very* complicated. Use an HTML or XML parser module for such tasks.) + + +Not Using re.VERBOSE +-------------------- + +By now you've probably noticed that regular expressions are a very compact +notation, but they're not terribly readable. REs of moderate complexity can +become lengthy collections of backslashes, parentheses, and metacharacters, +making them difficult to read and understand. + +For such REs, specifying the ``re.VERBOSE`` flag when compiling the regular +expression can be helpful, because it allows you to format the regular +expression more clearly. + +The ``re.VERBOSE`` flag has several effects. Whitespace in the regular +expression that *isn't* inside a character class is ignored. This means that an +expression such as ``dog | cat`` is equivalent to the less readable ``dog|cat``, +but ``[a b]`` will still match the characters ``'a'``, ``'b'``, or a space. In +addition, you can also put comments inside a RE; comments extend from a ``#`` +character to the next newline. When used with triple-quoted strings, this +enables REs to be formatted more neatly:: + + pat = re.compile(r""" + \s* # Skip leading whitespace + (?P
      [^:]+) # Header name + \s* : # Whitespace, and a colon + (?P.*?) # The header's value -- *? used to + # lose the following trailing whitespace + \s*$ # Trailing whitespace to end-of-line + """, re.VERBOSE) + +This is far more readable than: + +.. % $ + +:: + + pat = re.compile(r"\s*(?P
      [^:]+)\s*:(?P.*?)\s*$") + +.. % $ + + +Feedback +======== + +Regular expressions are a complicated topic. Did this document help you +understand them? Were there parts that were unclear, or Problems you +encountered that weren't covered here? If so, please send suggestions for +improvements to the author. + +The most complete book on regular expressions is almost certainly Jeffrey +Friedl's Mastering Regular Expressions, published by O'Reilly. Unfortunately, +it exclusively concentrates on Perl and Java's flavours of regular expressions, +and doesn't contain any Python material at all, so it won't be useful as a +reference for programming in Python. (The first edition covered Python's now- +removed :mod:`regex` module, which won't help you much.) Consider checking it +out from your library. + + +.. rubric:: Footnotes + +.. [#] Introduced in Python 2.2.2. + Added: doctools/trunk/Doc-3k/howto/sockets.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-3k/howto/sockets.rst Thu Aug 2 23:31:34 2007 @@ -0,0 +1,421 @@ +**************************** + Socket Programming HOWTO +**************************** + +:Author: Gordon McMillan + + +.. topic:: Abstract + + Sockets are used nearly everywhere, but are one of the most severely + misunderstood technologies around. This is a 10,000 foot overview of sockets. + It's not really a tutorial - you'll still have work to do in getting things + operational. It doesn't cover the fine points (and there are a lot of them), but + I hope it will give you enough background to begin using them decently. + + +Sockets +======= + +Sockets are used nearly everywhere, but are one of the most severely +misunderstood technologies around. This is a 10,000 foot overview of sockets. +It's not really a tutorial - you'll still have work to do in getting things +working. It doesn't cover the fine points (and there are a lot of them), but I +hope it will give you enough background to begin using them decently. + +I'm only going to talk about INET sockets, but they account for at least 99% of +the sockets in use. And I'll only talk about STREAM sockets - unless you really +know what you're doing (in which case this HOWTO isn't for you!), you'll get +better behavior and performance from a STREAM socket than anything else. I will +try to clear up the mystery of what a socket is, as well as some hints on how to +work with blocking and non-blocking sockets. But I'll start by talking about +blocking sockets. You'll need to know how they work before dealing with non- +blocking sockets. + +Part of the trouble with understanding these things is that "socket" can mean a +number of subtly different things, depending on context. So first, let's make a +distinction between a "client" socket - an endpoint of a conversation, and a +"server" socket, which is more like a switchboard operator. The client +application (your browser, for example) uses "client" sockets exclusively; the +web server it's talking to uses both "server" sockets and "client" sockets. + + +History +------- + +Of the various forms of IPC (*Inter Process Communication*), sockets are by far +the most popular. On any given platform, there are likely to be other forms of +IPC that are faster, but for cross-platform communication, sockets are about the +only game in town. + +They were invented in Berkeley as part of the BSD flavor of Unix. They spread +like wildfire with the Internet. With good reason --- the combination of sockets +with INET makes talking to arbitrary machines around the world unbelievably easy +(at least compared to other schemes). + + +Creating a Socket +================= + +Roughly speaking, when you clicked on the link that brought you to this page, +your browser did something like the following:: + + #create an INET, STREAMing socket + s = socket.socket( + socket.AF_INET, socket.SOCK_STREAM) + #now connect to the web server on port 80 + # - the normal http port + s.connect(("www.mcmillan-inc.com", 80)) + +When the ``connect`` completes, the socket ``s`` can now be used to send in a +request for the text of this page. The same socket will read the reply, and then +be destroyed. That's right - destroyed. Client sockets are normally only used +for one exchange (or a small set of sequential exchanges). + +What happens in the web server is a bit more complex. First, the web server +creates a "server socket". :: + + #create an INET, STREAMing socket + serversocket = socket.socket( + socket.AF_INET, socket.SOCK_STREAM) + #bind the socket to a public host, + # and a well-known port + serversocket.bind((socket.gethostname(), 80)) + #become a server socket + serversocket.listen(5) + +A couple things to notice: we used ``socket.gethostname()`` so that the socket +would be visible to the outside world. If we had used ``s.bind(('', 80))`` or +``s.bind(('localhost', 80))`` or ``s.bind(('127.0.0.1', 80))`` we would still +have a "server" socket, but one that was only visible within the same machine. + +A second thing to note: low number ports are usually reserved for "well known" +services (HTTP, SNMP etc). If you're playing around, use a nice high number (4 +digits). + +Finally, the argument to ``listen`` tells the socket library that we want it to +queue up as many as 5 connect requests (the normal max) before refusing outside +connections. If the rest of the code is written properly, that should be plenty. + +OK, now we have a "server" socket, listening on port 80. Now we enter the +mainloop of the web server:: + + while 1: + #accept connections from outside + (clientsocket, address) = serversocket.accept() + #now do something with the clientsocket + #in this case, we'll pretend this is a threaded server + ct = client_thread(clientsocket) + ct.run() + +There's actually 3 general ways in which this loop could work - dispatching a +thread to handle ``clientsocket``, create a new process to handle +``clientsocket``, or restructure this app to use non-blocking sockets, and +mulitplex between our "server" socket and any active ``clientsocket``\ s using +``select``. More about that later. The important thing to understand now is +this: this is *all* a "server" socket does. It doesn't send any data. It doesn't +receive any data. It just produces "client" sockets. Each ``clientsocket`` is +created in response to some *other* "client" socket doing a ``connect()`` to the +host and port we're bound to. As soon as we've created that ``clientsocket``, we +go back to listening for more connections. The two "clients" are free to chat it +up - they are using some dynamically allocated port which will be recycled when +the conversation ends. + + +IPC +--- + +If you need fast IPC between two processes on one machine, you should look into +whatever form of shared memory the platform offers. A simple protocol based +around shared memory and locks or semaphores is by far the fastest technique. + +If you do decide to use sockets, bind the "server" socket to ``'localhost'``. On +most platforms, this will take a shortcut around a couple of layers of network +code and be quite a bit faster. + + +Using a Socket +============== + +The first thing to note, is that the web browser's "client" socket and the web +server's "client" socket are identical beasts. That is, this is a "peer to peer" +conversation. Or to put it another way, *as the designer, you will have to +decide what the rules of etiquette are for a conversation*. Normally, the +``connect``\ ing socket starts the conversation, by sending in a request, or +perhaps a signon. But that's a design decision - it's not a rule of sockets. + +Now there are two sets of verbs to use for communication. You can use ``send`` +and ``recv``, or you can transform your client socket into a file-like beast and +use ``read`` and ``write``. The latter is the way Java presents their sockets. +I'm not going to talk about it here, except to warn you that you need to use +``flush`` on sockets. These are buffered "files", and a common mistake is to +``write`` something, and then ``read`` for a reply. Without a ``flush`` in +there, you may wait forever for the reply, because the request may still be in +your output buffer. + +Now we come the major stumbling block of sockets - ``send`` and ``recv`` operate +on the network buffers. They do not necessarily handle all the bytes you hand +them (or expect from them), because their major focus is handling the network +buffers. In general, they return when the associated network buffers have been +filled (``send``) or emptied (``recv``). They then tell you how many bytes they +handled. It is *your* responsibility to call them again until your message has +been completely dealt with. + +When a ``recv`` returns 0 bytes, it means the other side has closed (or is in +the process of closing) the connection. You will not receive any more data on +this connection. Ever. You may be able to send data successfully; I'll talk +about that some on the next page. + +A protocol like HTTP uses a socket for only one transfer. The client sends a +request, the reads a reply. That's it. The socket is discarded. This means that +a client can detect the end of the reply by receiving 0 bytes. + +But if you plan to reuse your socket for further transfers, you need to realize +that *there is no "EOT" (End of Transfer) on a socket.* I repeat: if a socket +``send`` or ``recv`` returns after handling 0 bytes, the connection has been +broken. If the connection has *not* been broken, you may wait on a ``recv`` +forever, because the socket will *not* tell you that there's nothing more to +read (for now). Now if you think about that a bit, you'll come to realize a +fundamental truth of sockets: *messages must either be fixed length* (yuck), *or +be delimited* (shrug), *or indicate how long they are* (much better), *or end by +shutting down the connection*. The choice is entirely yours, (but some ways are +righter than others). + +Assuming you don't want to end the connection, the simplest solution is a fixed +length message:: + + class mysocket: + '''demonstration class only + - coded for clarity, not efficiency + ''' + + def __init__(self, sock=None): + if sock is None: + self.sock = socket.socket( + socket.AF_INET, socket.SOCK_STREAM) + else: + self.sock = sock + + def connect(self, host, port): + self.sock.connect((host, port)) + + def mysend(self, msg): + totalsent = 0 + while totalsent < MSGLEN: + sent = self.sock.send(msg[totalsent:]) + if sent == 0: + raise RuntimeError, \\ + "socket connection broken" + totalsent = totalsent + sent + + def myreceive(self): + msg = '' + while len(msg) < MSGLEN: + chunk = self.sock.recv(MSGLEN-len(msg)) + if chunk == '': + raise RuntimeError, \\ + "socket connection broken" + msg = msg + chunk + return msg + +The sending code here is usable for almost any messaging scheme - in Python you +send strings, and you can use ``len()`` to determine its length (even if it has +embedded ``\0`` characters). It's mostly the receiving code that gets more +complex. (And in C, it's not much worse, except you can't use ``strlen`` if the +message has embedded ``\0``\ s.) + +The easiest enhancement is to make the first character of the message an +indicator of message type, and have the type determine the length. Now you have +two ``recv``\ s - the first to get (at least) that first character so you can +look up the length, and the second in a loop to get the rest. If you decide to +go the delimited route, you'll be receiving in some arbitrary chunk size, (4096 +or 8192 is frequently a good match for network buffer sizes), and scanning what +you've received for a delimiter. + +One complication to be aware of: if your conversational protocol allows multiple +messages to be sent back to back (without some kind of reply), and you pass +``recv`` an arbitrary chunk size, you may end up reading the start of a +following message. You'll need to put that aside and hold onto it, until it's +needed. + +Prefixing the message with it's length (say, as 5 numeric characters) gets more +complex, because (believe it or not), you may not get all 5 characters in one +``recv``. In playing around, you'll get away with it; but in high network loads, +your code will very quickly break unless you use two ``recv`` loops - the first +to determine the length, the second to get the data part of the message. Nasty. +This is also when you'll discover that ``send`` does not always manage to get +rid of everything in one pass. And despite having read this, you will eventually +get bit by it! + +In the interests of space, building your character, (and preserving my +competitive position), these enhancements are left as an exercise for the +reader. Lets move on to cleaning up. + + +Binary Data +----------- + +It is perfectly possible to send binary data over a socket. The major problem is +that not all machines use the same formats for binary data. For example, a +Motorola chip will represent a 16 bit integer with the value 1 as the two hex +bytes 00 01. Intel and DEC, however, are byte-reversed - that same 1 is 01 00. +Socket libraries have calls for converting 16 and 32 bit integers - ``ntohl, +htonl, ntohs, htons`` where "n" means *network* and "h" means *host*, "s" means +*short* and "l" means *long*. Where network order is host order, these do +nothing, but where the machine is byte-reversed, these swap the bytes around +appropriately. + +In these days of 32 bit machines, the ascii representation of binary data is +frequently smaller than the binary representation. That's because a surprising +amount of the time, all those longs have the value 0, or maybe 1. The string "0" +would be two bytes, while binary is four. Of course, this doesn't fit well with +fixed-length messages. Decisions, decisions. + + +Disconnecting +============= + +Strictly speaking, you're supposed to use ``shutdown`` on a socket before you +``close`` it. The ``shutdown`` is an advisory to the socket at the other end. +Depending on the argument you pass it, it can mean "I'm not going to send +anymore, but I'll still listen", or "I'm not listening, good riddance!". Most +socket libraries, however, are so used to programmers neglecting to use this +piece of etiquette that normally a ``close`` is the same as ``shutdown(); +close()``. So in most situations, an explicit ``shutdown`` is not needed. + +One way to use ``shutdown`` effectively is in an HTTP-like exchange. The client +sends a request and then does a ``shutdown(1)``. This tells the server "This +client is done sending, but can still receive." The server can detect "EOF" by +a receive of 0 bytes. It can assume it has the complete request. The server +sends a reply. If the ``send`` completes successfully then, indeed, the client +was still receiving. + +Python takes the automatic shutdown a step further, and says that when a socket +is garbage collected, it will automatically do a ``close`` if it's needed. But +relying on this is a very bad habit. If your socket just disappears without +doing a ``close``, the socket at the other end may hang indefinitely, thinking +you're just being slow. *Please* ``close`` your sockets when you're done. + + +When Sockets Die +---------------- + +Probably the worst thing about using blocking sockets is what happens when the +other side comes down hard (without doing a ``close``). Your socket is likely to +hang. SOCKSTREAM is a reliable protocol, and it will wait a long, long time +before giving up on a connection. If you're using threads, the entire thread is +essentially dead. There's not much you can do about it. As long as you aren't +doing something dumb, like holding a lock while doing a blocking read, the +thread isn't really consuming much in the way of resources. Do *not* try to kill +the thread - part of the reason that threads are more efficient than processes +is that they avoid the overhead associated with the automatic recycling of +resources. In other words, if you do manage to kill the thread, your whole +process is likely to be screwed up. + + +Non-blocking Sockets +==================== + +If you've understood the preceeding, you already know most of what you need to +know about the mechanics of using sockets. You'll still use the same calls, in +much the same ways. It's just that, if you do it right, your app will be almost +inside-out. + +In Python, you use ``socket.setblocking(0)`` to make it non-blocking. In C, it's +more complex, (for one thing, you'll need to choose between the BSD flavor +``O_NONBLOCK`` and the almost indistinguishable Posix flavor ``O_NDELAY``, which +is completely different from ``TCP_NODELAY``), but it's the exact same idea. You +do this after creating the socket, but before using it. (Actually, if you're +nuts, you can switch back and forth.) + +The major mechanical difference is that ``send``, ``recv``, ``connect`` and +``accept`` can return without having done anything. You have (of course) a +number of choices. You can check return code and error codes and generally drive +yourself crazy. If you don't believe me, try it sometime. Your app will grow +large, buggy and suck CPU. So let's skip the brain-dead solutions and do it +right. + +Use ``select``. + +In C, coding ``select`` is fairly complex. In Python, it's a piece of cake, but +it's close enough to the C version that if you understand ``select`` in Python, +you'll have little trouble with it in C. :: + + ready_to_read, ready_to_write, in_error = \\ + select.select( + potential_readers, + potential_writers, + potential_errs, + timeout) + +You pass ``select`` three lists: the first contains all sockets that you might +want to try reading; the second all the sockets you might want to try writing +to, and the last (normally left empty) those that you want to check for errors. +You should note that a socket can go into more than one list. The ``select`` +call is blocking, but you can give it a timeout. This is generally a sensible +thing to do - give it a nice long timeout (say a minute) unless you have good +reason to do otherwise. + +In return, you will get three lists. They have the sockets that are actually +readable, writable and in error. Each of these lists is a subset (possbily +empty) of the corresponding list you passed in. And if you put a socket in more +than one input list, it will only be (at most) in one output list. + +If a socket is in the output readable list, you can be as-close-to-certain-as- +we-ever-get-in-this-business that a ``recv`` on that socket will return +*something*. Same idea for the writable list. You'll be able to send +*something*. Maybe not all you want to, but *something* is better than nothing. +(Actually, any reasonably healthy socket will return as writable - it just means +outbound network buffer space is available.) + +If you have a "server" socket, put it in the potential_readers list. If it comes +out in the readable list, your ``accept`` will (almost certainly) work. If you +have created a new socket to ``connect`` to someone else, put it in the +ptoential_writers list. If it shows up in the writable list, you have a decent +chance that it has connected. + +One very nasty problem with ``select``: if somewhere in those input lists of +sockets is one which has died a nasty death, the ``select`` will fail. You then +need to loop through every single damn socket in all those lists and do a +``select([sock],[],[],0)`` until you find the bad one. That timeout of 0 means +it won't take long, but it's ugly. + +Actually, ``select`` can be handy even with blocking sockets. It's one way of +determining whether you will block - the socket returns as readable when there's +something in the buffers. However, this still doesn't help with the problem of +determining whether the other end is done, or just busy with something else. + +**Portability alert**: On Unix, ``select`` works both with the sockets and +files. Don't try this on Windows. On Windows, ``select`` works with sockets +only. Also note that in C, many of the more advanced socket options are done +differently on Windows. In fact, on Windows I usually use threads (which work +very, very well) with my sockets. Face it, if you want any kind of performance, +your code will look very different on Windows than on Unix. (I haven't the +foggiest how you do this stuff on a Mac.) + + +Performance +----------- + +There's no question that the fastest sockets code uses non-blocking sockets and +select to multiplex them. You can put together something that will saturate a +LAN connection without putting any strain on the CPU. The trouble is that an app +written this way can't do much of anything else - it needs to be ready to +shuffle bytes around at all times. + +Assuming that your app is actually supposed to do something more than that, +threading is the optimal solution, (and using non-blocking sockets will be +faster than using blocking sockets). Unfortunately, threading support in Unixes +varies both in API and quality. So the normal Unix solution is to fork a +subprocess to deal with each connection. The overhead for this is significant +(and don't do this on Windows - the overhead of process creation is enormous +there). It also means that unless each subprocess is completely independent, +you'll need to use another form of IPC, say a pipe, or shared memory and +semaphores, to communicate between the parent and child processes. + +Finally, remember that even though blocking sockets are somewhat slower than +non-blocking, in many cases they are the "right" solution. After all, if your +app is driven by the data it receives over a socket, there's not much sense in +complicating the logic just so your app can wait on ``select`` instead of +``recv``. + Added: doctools/trunk/Doc-3k/howto/unicode.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-3k/howto/unicode.rst Thu Aug 2 23:31:34 2007 @@ -0,0 +1,732 @@ +***************** + Unicode HOWTO +***************** + +:Release: 1.02 + +This HOWTO discusses Python's support for Unicode, and explains various problems +that people commonly encounter when trying to work with Unicode. + +Introduction to Unicode +======================= + +History of Character Codes +-------------------------- + +In 1968, the American Standard Code for Information Interchange, better known by +its acronym ASCII, was standardized. ASCII defined numeric codes for various +characters, with the numeric values running from 0 to +127. For example, the lowercase letter 'a' is assigned 97 as its code +value. + +ASCII was an American-developed standard, so it only defined unaccented +characters. There was an 'e', but no '?' or '?'. This meant that languages +which required accented characters couldn't be faithfully represented in ASCII. +(Actually the missing accents matter for English, too, which contains words such +as 'na?ve' and 'caf?', and some publications have house styles which require +spellings such as 'co?perate'.) + +For a while people just wrote programs that didn't display accents. I remember +looking at Apple ][ BASIC programs, published in French-language publications in +the mid-1980s, that had lines like these:: + + PRINT "FICHER EST COMPLETE." + PRINT "CARACTERE NON ACCEPTE." + +Those messages should contain accents, and they just look wrong to someone who +can read French. + +In the 1980s, almost all personal computers were 8-bit, meaning that bytes could +hold values ranging from 0 to 255. ASCII codes only went up to 127, so some +machines assigned values between 128 and 255 to accented characters. Different +machines had different codes, however, which led to problems exchanging files. +Eventually various commonly used sets of values for the 128-255 range emerged. +Some were true standards, defined by the International Standards Organization, +and some were **de facto** conventions that were invented by one company or +another and managed to catch on. + +255 characters aren't very many. For example, you can't fit both the accented +characters used in Western Europe and the Cyrillic alphabet used for Russian +into the 128-255 range because there are more than 127 such characters. + +You could write files using different codes (all your Russian files in a coding +system called KOI8, all your French files in a different coding system called +Latin1), but what if you wanted to write a French document that quotes some +Russian text? In the 1980s people began to want to solve this problem, and the +Unicode standardization effort began. + +Unicode started out using 16-bit characters instead of 8-bit characters. 16 +bits means you have 2^16 = 65,536 distinct values available, making it possible +to represent many different characters from many different alphabets; an initial +goal was to have Unicode contain the alphabets for every single human language. +It turns out that even 16 bits isn't enough to meet that goal, and the modern +Unicode specification uses a wider range of codes, 0-1,114,111 (0x10ffff in +base-16). + +There's a related ISO standard, ISO 10646. Unicode and ISO 10646 were +originally separate efforts, but the specifications were merged with the 1.1 +revision of Unicode. + +(This discussion of Unicode's history is highly simplified. I don't think the +average Python programmer needs to worry about the historical details; consult +the Unicode consortium site listed in the References for more information.) + + +Definitions +----------- + +A **character** is the smallest possible component of a text. 'A', 'B', 'C', +etc., are all different characters. So are '?' and '?'. Characters are +abstractions, and vary depending on the language or context you're talking +about. For example, the symbol for ohms (?) is usually drawn much like the +capital letter omega (?) in the Greek alphabet (they may even be the same in +some fonts), but these are two different characters that have different +meanings. + +The Unicode standard describes how characters are represented by **code +points**. A code point is an integer value, usually denoted in base 16. In the +standard, a code point is written using the notation U+12ca to mean the +character with value 0x12ca (4810 decimal). The Unicode standard contains a lot +of tables listing characters and their corresponding code points:: + + 0061 'a'; LATIN SMALL LETTER A + 0062 'b'; LATIN SMALL LETTER B + 0063 'c'; LATIN SMALL LETTER C + ... + 007B '{'; LEFT CURLY BRACKET + +Strictly, these definitions imply that it's meaningless to say 'this is +character U+12ca'. U+12ca is a code point, which represents some particular +character; in this case, it represents the character 'ETHIOPIC SYLLABLE WI'. In +informal contexts, this distinction between code points and characters will +sometimes be forgotten. + +A character is represented on a screen or on paper by a set of graphical +elements that's called a **glyph**. The glyph for an uppercase A, for example, +is two diagonal strokes and a horizontal stroke, though the exact details will +depend on the font being used. Most Python code doesn't need to worry about +glyphs; figuring out the correct glyph to display is generally the job of a GUI +toolkit or a terminal's font renderer. + + +Encodings +--------- + +To summarize the previous section: a Unicode string is a sequence of code +points, which are numbers from 0 to 0x10ffff. This sequence needs to be +represented as a set of bytes (meaning, values from 0-255) in memory. The rules +for translating a Unicode string into a sequence of bytes are called an +**encoding**. + +The first encoding you might think of is an array of 32-bit integers. In this +representation, the string "Python" would look like this:: + + P y t h o n + 0x50 00 00 00 79 00 00 00 74 00 00 00 68 00 00 00 6f 00 00 00 6e 00 00 00 + 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 + +This representation is straightforward but using it presents a number of +problems. + +1. It's not portable; different processors order the bytes differently. + +2. It's very wasteful of space. In most texts, the majority of the code points + are less than 127, or less than 255, so a lot of space is occupied by zero + bytes. The above string takes 24 bytes compared to the 6 bytes needed for an + ASCII representation. Increased RAM usage doesn't matter too much (desktop + computers have megabytes of RAM, and strings aren't usually that large), but + expanding our usage of disk and network bandwidth by a factor of 4 is + intolerable. + +3. It's not compatible with existing C functions such as ``strlen()``, so a new + family of wide string functions would need to be used. + +4. Many Internet standards are defined in terms of textual data, and can't + handle content with embedded zero bytes. + +Generally people don't use this encoding, instead choosing other encodings that +are more efficient and convenient. + +Encodings don't have to handle every possible Unicode character, and most +encodings don't. For example, Python's default encoding is the 'ascii' +encoding. The rules for converting a Unicode string into the ASCII encoding are +simple; for each code point: + +1. If the code point is < 128, each byte is the same as the value of the code + point. + +2. If the code point is 128 or greater, the Unicode string can't be represented + in this encoding. (Python raises a :exc:`UnicodeEncodeError` exception in this + case.) + +Latin-1, also known as ISO-8859-1, is a similar encoding. Unicode code points +0-255 are identical to the Latin-1 values, so converting to this encoding simply +requires converting code points to byte values; if a code point larger than 255 +is encountered, the string can't be encoded into Latin-1. + +Encodings don't have to be simple one-to-one mappings like Latin-1. Consider +IBM's EBCDIC, which was used on IBM mainframes. Letter values weren't in one +block: 'a' through 'i' had values from 129 to 137, but 'j' through 'r' were 145 +through 153. If you wanted to use EBCDIC as an encoding, you'd probably use +some sort of lookup table to perform the conversion, but this is largely an +internal detail. + +UTF-8 is one of the most commonly used encodings. UTF stands for "Unicode +Transformation Format", and the '8' means that 8-bit numbers are used in the +encoding. (There's also a UTF-16 encoding, but it's less frequently used than +UTF-8.) UTF-8 uses the following rules: + +1. If the code point is <128, it's represented by the corresponding byte value. +2. If the code point is between 128 and 0x7ff, it's turned into two byte values + between 128 and 255. +3. Code points >0x7ff are turned into three- or four-byte sequences, where each + byte of the sequence is between 128 and 255. + +UTF-8 has several convenient properties: + +1. It can handle any Unicode code point. +2. A Unicode string is turned into a string of bytes containing no embedded zero + bytes. This avoids byte-ordering issues, and means UTF-8 strings can be + processed by C functions such as ``strcpy()`` and sent through protocols that + can't handle zero bytes. +3. A string of ASCII text is also valid UTF-8 text. +4. UTF-8 is fairly compact; the majority of code points are turned into two + bytes, and values less than 128 occupy only a single byte. +5. If bytes are corrupted or lost, it's possible to determine the start of the + next UTF-8-encoded code point and resynchronize. It's also unlikely that + random 8-bit data will look like valid UTF-8. + + + +References +---------- + +The Unicode Consortium site at has character charts, a +glossary, and PDF versions of the Unicode specification. Be prepared for some +difficult reading. is a chronology of the +origin and development of Unicode. + +To help understand the standard, Jukka Korpela has written an introductory guide +to reading the Unicode character tables, available at +. + +Roman Czyborra wrote another explanation of Unicode's basic principles; it's at +. Czyborra has written a number of +other Unicode-related documentation, available from . + +Two other good introductory articles were written by Joel Spolsky + and Jason Orendorff +. If this introduction didn't make +things clear to you, you should try reading one of these alternate articles +before continuing. + +Wikipedia entries are often helpful; see the entries for "character encoding" + and UTF-8 +, for example. + + +Python's Unicode Support +======================== + +Now that you've learned the rudiments of Unicode, we can look at Python's +Unicode features. + + +The Unicode Type +---------------- + +Unicode strings are expressed as instances of the :class:`unicode` type, one of +Python's repertoire of built-in types. It derives from an abstract type called +:class:`basestring`, which is also an ancestor of the :class:`str` type; you can +therefore check if a value is a string type with ``isinstance(value, +basestring)``. Under the hood, Python represents Unicode strings as either 16- +or 32-bit integers, depending on how the Python interpreter was compiled. + +The :func:`unicode` constructor has the signature ``unicode(string[, encoding, +errors])``. All of its arguments should be 8-bit strings. The first argument +is converted to Unicode using the specified encoding; if you leave off the +``encoding`` argument, the ASCII encoding is used for the conversion, so +characters greater than 127 will be treated as errors:: + + >>> unicode('abcdef') + u'abcdef' + >>> s = unicode('abcdef') + >>> type(s) + + >>> unicode('abcdef' + chr(255)) + Traceback (most recent call last): + File "", line 1, in ? + UnicodeDecodeError: 'ascii' codec can't decode byte 0xff in position 6: + ordinal not in range(128) + +The ``errors`` argument specifies the response when the input string can't be +converted according to the encoding's rules. Legal values for this argument are +'strict' (raise a ``UnicodeDecodeError`` exception), 'replace' (add U+FFFD, +'REPLACEMENT CHARACTER'), or 'ignore' (just leave the character out of the +Unicode result). The following examples show the differences:: + + >>> unicode('\x80abc', errors='strict') + Traceback (most recent call last): + File "", line 1, in ? + UnicodeDecodeError: 'ascii' codec can't decode byte 0x80 in position 0: + ordinal not in range(128) + >>> unicode('\x80abc', errors='replace') + u'\ufffdabc' + >>> unicode('\x80abc', errors='ignore') + u'abc' + +Encodings are specified as strings containing the encoding's name. Python 2.4 +comes with roughly 100 different encodings; see the Python Library Reference at + for a list. Some encodings +have multiple names; for example, 'latin-1', 'iso_8859_1' and '8859' are all +synonyms for the same encoding. + +One-character Unicode strings can also be created with the :func:`unichr` +built-in function, which takes integers and returns a Unicode string of length 1 +that contains the corresponding code point. The reverse operation is the +built-in :func:`ord` function that takes a one-character Unicode string and +returns the code point value:: + + >>> unichr(40960) + u'\ua000' + >>> ord(u'\ua000') + 40960 + +Instances of the :class:`unicode` type have many of the same methods as the +8-bit string type for operations such as searching and formatting:: + + >>> s = u'Was ever feather so lightly blown to and fro as this multitude?' + >>> s.count('e') + 5 + >>> s.find('feather') + 9 + >>> s.find('bird') + -1 + >>> s.replace('feather', 'sand') + u'Was ever sand so lightly blown to and fro as this multitude?' + >>> s.upper() + u'WAS EVER FEATHER SO LIGHTLY BLOWN TO AND FRO AS THIS MULTITUDE?' + +Note that the arguments to these methods can be Unicode strings or 8-bit +strings. 8-bit strings will be converted to Unicode before carrying out the +operation; Python's default ASCII encoding will be used, so characters greater +than 127 will cause an exception:: + + >>> s.find('Was\x9f') + Traceback (most recent call last): + File "", line 1, in ? + UnicodeDecodeError: 'ascii' codec can't decode byte 0x9f in position 3: ordinal not in range(128) + >>> s.find(u'Was\x9f') + -1 + +Much Python code that operates on strings will therefore work with Unicode +strings without requiring any changes to the code. (Input and output code needs +more updating for Unicode; more on this later.) + +Another important method is ``.encode([encoding], [errors='strict'])``, which +returns an 8-bit string version of the Unicode string, encoded in the requested +encoding. The ``errors`` parameter is the same as the parameter of the +``unicode()`` constructor, with one additional possibility; as well as 'strict', +'ignore', and 'replace', you can also pass 'xmlcharrefreplace' which uses XML's +character references. The following example shows the different results:: + + >>> u = unichr(40960) + u'abcd' + unichr(1972) + >>> u.encode('utf-8') + '\xea\x80\x80abcd\xde\xb4' + >>> u.encode('ascii') + Traceback (most recent call last): + File "", line 1, in ? + UnicodeEncodeError: 'ascii' codec can't encode character '\ua000' in position 0: ordinal not in range(128) + >>> u.encode('ascii', 'ignore') + 'abcd' + >>> u.encode('ascii', 'replace') + '?abcd?' + >>> u.encode('ascii', 'xmlcharrefreplace') + 'ꀀabcd޴' + +Python's 8-bit strings have a ``.decode([encoding], [errors])`` method that +interprets the string using the given encoding:: + + >>> u = unichr(40960) + u'abcd' + unichr(1972) # Assemble a string + >>> utf8_version = u.encode('utf-8') # Encode as UTF-8 + >>> type(utf8_version), utf8_version + (, '\xea\x80\x80abcd\xde\xb4') + >>> u2 = utf8_version.decode('utf-8') # Decode using UTF-8 + >>> u == u2 # The two strings match + True + +The low-level routines for registering and accessing the available encodings are +found in the :mod:`codecs` module. However, the encoding and decoding functions +returned by this module are usually more low-level than is comfortable, so I'm +not going to describe the :mod:`codecs` module here. If you need to implement a +completely new encoding, you'll need to learn about the :mod:`codecs` module +interfaces, but implementing encodings is a specialized task that also won't be +covered here. Consult the Python documentation to learn more about this module. + +The most commonly used part of the :mod:`codecs` module is the +:func:`codecs.open` function which will be discussed in the section on input and +output. + + +Unicode Literals in Python Source Code +-------------------------------------- + +In Python source code, Unicode literals are written as strings prefixed with the +'u' or 'U' character: ``u'abcdefghijk'``. Specific code points can be written +using the ``\u`` escape sequence, which is followed by four hex digits giving +the code point. The ``\U`` escape sequence is similar, but expects 8 hex +digits, not 4. + +Unicode literals can also use the same escape sequences as 8-bit strings, +including ``\x``, but ``\x`` only takes two hex digits so it can't express an +arbitrary code point. Octal escapes can go up to U+01ff, which is octal 777. + +:: + + >>> s = u"a\xac\u1234\u20ac\U00008000" + ^^^^ two-digit hex escape + ^^^^^^ four-digit Unicode escape + ^^^^^^^^^^ eight-digit Unicode escape + >>> for c in s: print ord(c), + ... + 97 172 4660 8364 32768 + +Using escape sequences for code points greater than 127 is fine in small doses, +but becomes an annoyance if you're using many accented characters, as you would +in a program with messages in French or some other accent-using language. You +can also assemble strings using the :func:`unichr` built-in function, but this is +even more tedious. + +Ideally, you'd want to be able to write literals in your language's natural +encoding. You could then edit Python source code with your favorite editor +which would display the accented characters naturally, and have the right +characters used at runtime. + +Python supports writing Unicode literals in any encoding, but you have to +declare the encoding being used. This is done by including a special comment as +either the first or second line of the source file:: + + #!/usr/bin/env python + # -*- coding: latin-1 -*- + + u = u'abcd?' + print ord(u[-1]) + +The syntax is inspired by Emacs's notation for specifying variables local to a +file. Emacs supports many different variables, but Python only supports +'coding'. The ``-*-`` symbols indicate that the comment is special; within +them, you must supply the name ``coding`` and the name of your chosen encoding, +separated by ``':'``. + +If you don't include such a comment, the default encoding used will be ASCII. +Versions of Python before 2.4 were Euro-centric and assumed Latin-1 as a default +encoding for string literals; in Python 2.4, characters greater than 127 still +work but result in a warning. For example, the following program has no +encoding declaration:: + + #!/usr/bin/env python + u = u'abcd?' + print ord(u[-1]) + +When you run it with Python 2.4, it will output the following warning:: + + amk:~$ python p263.py + sys:1: DeprecationWarning: Non-ASCII character '\xe9' + in file p263.py on line 2, but no encoding declared; + see http://www.python.org/peps/pep-0263.html for details + + +Unicode Properties +------------------ + +The Unicode specification includes a database of information about code points. +For each code point that's defined, the information includes the character's +name, its category, the numeric value if applicable (Unicode has characters +representing the Roman numerals and fractions such as one-third and +four-fifths). There are also properties related to the code point's use in +bidirectional text and other display-related properties. + +The following program displays some information about several characters, and +prints the numeric value of one particular character:: + + import unicodedata + + u = unichr(233) + unichr(0x0bf2) + unichr(3972) + unichr(6000) + unichr(13231) + + for i, c in enumerate(u): + print i, '%04x' % ord(c), unicodedata.category(c), + print unicodedata.name(c) + + # Get numeric value of second character + print unicodedata.numeric(u[1]) + +When run, this prints:: + + 0 00e9 Ll LATIN SMALL LETTER E WITH ACUTE + 1 0bf2 No TAMIL NUMBER ONE THOUSAND + 2 0f84 Mn TIBETAN MARK HALANTA + 3 1770 Lo TAGBANWA LETTER SA + 4 33af So SQUARE RAD OVER S SQUARED + 1000.0 + +The category codes are abbreviations describing the nature of the character. +These are grouped into categories such as "Letter", "Number", "Punctuation", or +"Symbol", which in turn are broken up into subcategories. To take the codes +from the above output, ``'Ll'`` means 'Letter, lowercase', ``'No'`` means +"Number, other", ``'Mn'`` is "Mark, nonspacing", and ``'So'`` is "Symbol, +other". See + for a +list of category codes. + +References +---------- + +The Unicode and 8-bit string types are described in the Python library reference +at :ref:`typesseq`. + +The documentation for the :mod:`unicodedata` module. + +The documentation for the :mod:`codecs` module. + +Marc-Andr? Lemburg gave a presentation at EuroPython 2002 titled "Python and +Unicode". A PDF version of his slides is available at +, and is an +excellent overview of the design of Python's Unicode features. + + +Reading and Writing Unicode Data +================================ + +Once you've written some code that works with Unicode data, the next problem is +input/output. How do you get Unicode strings into your program, and how do you +convert Unicode into a form suitable for storage or transmission? + +It's possible that you may not need to do anything depending on your input +sources and output destinations; you should check whether the libraries used in +your application support Unicode natively. XML parsers often return Unicode +data, for example. Many relational databases also support Unicode-valued +columns and can return Unicode values from an SQL query. + +Unicode data is usually converted to a particular encoding before it gets +written to disk or sent over a socket. It's possible to do all the work +yourself: open a file, read an 8-bit string from it, and convert the string with +``unicode(str, encoding)``. However, the manual approach is not recommended. + +One problem is the multi-byte nature of encodings; one Unicode character can be +represented by several bytes. If you want to read the file in arbitrary-sized +chunks (say, 1K or 4K), you need to write error-handling code to catch the case +where only part of the bytes encoding a single Unicode character are read at the +end of a chunk. One solution would be to read the entire file into memory and +then perform the decoding, but that prevents you from working with files that +are extremely large; if you need to read a 2Gb file, you need 2Gb of RAM. +(More, really, since for at least a moment you'd need to have both the encoded +string and its Unicode version in memory.) + +The solution would be to use the low-level decoding interface to catch the case +of partial coding sequences. The work of implementing this has already been +done for you: the :mod:`codecs` module includes a version of the :func:`open` +function that returns a file-like object that assumes the file's contents are in +a specified encoding and accepts Unicode parameters for methods such as +``.read()`` and ``.write()``. + +The function's parameters are ``open(filename, mode='rb', encoding=None, +errors='strict', buffering=1)``. ``mode`` can be ``'r'``, ``'w'``, or ``'a'``, +just like the corresponding parameter to the regular built-in ``open()`` +function; add a ``'+'`` to update the file. ``buffering`` is similarly parallel +to the standard function's parameter. ``encoding`` is a string giving the +encoding to use; if it's left as ``None``, a regular Python file object that +accepts 8-bit strings is returned. Otherwise, a wrapper object is returned, and +data written to or read from the wrapper object will be converted as needed. +``errors`` specifies the action for encoding errors and can be one of the usual +values of 'strict', 'ignore', and 'replace'. + +Reading Unicode from a file is therefore simple:: + + import codecs + f = codecs.open('unicode.rst', encoding='utf-8') + for line in f: + print repr(line) + +It's also possible to open files in update mode, allowing both reading and +writing:: + + f = codecs.open('test', encoding='utf-8', mode='w+') + f.write(u'\u4500 blah blah blah\n') + f.seek(0) + print repr(f.readline()[:1]) + f.close() + +Unicode character U+FEFF is used as a byte-order mark (BOM), and is often +written as the first character of a file in order to assist with autodetection +of the file's byte ordering. Some encodings, such as UTF-16, expect a BOM to be +present at the start of a file; when such an encoding is used, the BOM will be +automatically written as the first character and will be silently dropped when +the file is read. There are variants of these encodings, such as 'utf-16-le' +and 'utf-16-be' for little-endian and big-endian encodings, that specify one +particular byte ordering and don't skip the BOM. + + +Unicode filenames +----------------- + +Most of the operating systems in common use today support filenames that contain +arbitrary Unicode characters. Usually this is implemented by converting the +Unicode string into some encoding that varies depending on the system. For +example, MacOS X uses UTF-8 while Windows uses a configurable encoding; on +Windows, Python uses the name "mbcs" to refer to whatever the currently +configured encoding is. On Unix systems, there will only be a filesystem +encoding if you've set the ``LANG`` or ``LC_CTYPE`` environment variables; if +you haven't, the default encoding is ASCII. + +The :func:`sys.getfilesystemencoding` function returns the encoding to use on +your current system, in case you want to do the encoding manually, but there's +not much reason to bother. When opening a file for reading or writing, you can +usually just provide the Unicode string as the filename, and it will be +automatically converted to the right encoding for you:: + + filename = u'filename\u4500abc' + f = open(filename, 'w') + f.write('blah\n') + f.close() + +Functions in the :mod:`os` module such as :func:`os.stat` will also accept Unicode +filenames. + +:func:`os.listdir`, which returns filenames, raises an issue: should it return +the Unicode version of filenames, or should it return 8-bit strings containing +the encoded versions? :func:`os.listdir` will do both, depending on whether you +provided the directory path as an 8-bit string or a Unicode string. If you pass +a Unicode string as the path, filenames will be decoded using the filesystem's +encoding and a list of Unicode strings will be returned, while passing an 8-bit +path will return the 8-bit versions of the filenames. For example, assuming the +default filesystem encoding is UTF-8, running the following program:: + + fn = u'filename\u4500abc' + f = open(fn, 'w') + f.close() + + import os + print os.listdir('.') + print os.listdir(u'.') + +will produce the following output:: + + amk:~$ python t.py + ['.svn', 'filename\xe4\x94\x80abc', ...] + [u'.svn', u'filename\u4500abc', ...] + +The first list contains UTF-8-encoded filenames, and the second list contains +the Unicode versions. + + + +Tips for Writing Unicode-aware Programs +--------------------------------------- + +This section provides some suggestions on writing software that deals with +Unicode. + +The most important tip is: + + Software should only work with Unicode strings internally, converting to a + particular encoding on output. + +If you attempt to write processing functions that accept both Unicode and 8-bit +strings, you will find your program vulnerable to bugs wherever you combine the +two different kinds of strings. Python's default encoding is ASCII, so whenever +a character with an ASCII value > 127 is in the input data, you'll get a +:exc:`UnicodeDecodeError` because that character can't be handled by the ASCII +encoding. + +It's easy to miss such problems if you only test your software with data that +doesn't contain any accents; everything will seem to work, but there's actually +a bug in your program waiting for the first user who attempts to use characters +> 127. A second tip, therefore, is: + + Include characters > 127 and, even better, characters > 255 in your test + data. + +When using data coming from a web browser or some other untrusted source, a +common technique is to check for illegal characters in a string before using the +string in a generated command line or storing it in a database. If you're doing +this, be careful to check the string once it's in the form that will be used or +stored; it's possible for encodings to be used to disguise characters. This is +especially true if the input data also specifies the encoding; many encodings +leave the commonly checked-for characters alone, but Python includes some +encodings such as ``'base64'`` that modify every single character. + +For example, let's say you have a content management system that takes a Unicode +filename, and you want to disallow paths with a '/' character. You might write +this code:: + + def read_file (filename, encoding): + if '/' in filename: + raise ValueError("'/' not allowed in filenames") + unicode_name = filename.decode(encoding) + f = open(unicode_name, 'r') + # ... return contents of file ... + +However, if an attacker could specify the ``'base64'`` encoding, they could pass +``'L2V0Yy9wYXNzd2Q='``, which is the base-64 encoded form of the string +``'/etc/passwd'``, to read a system file. The above code looks for ``'/'`` +characters in the encoded form and misses the dangerous character in the +resulting decoded form. + +References +---------- + +The PDF slides for Marc-Andr? Lemburg's presentation "Writing Unicode-aware +Applications in Python" are available at + +and discuss questions of character encodings as well as how to internationalize +and localize an application. + + +Revision History and Acknowledgements +===================================== + +Thanks to the following people who have noted errors or offered suggestions on +this article: Nicholas Bastin, Marius Gedminas, Kent Johnson, Ken Krugler, +Marc-Andr? Lemburg, Martin von L?wis, Chad Whitacre. + +Version 1.0: posted August 5 2005. + +Version 1.01: posted August 7 2005. Corrects factual and markup errors; adds +several links. + +Version 1.02: posted August 16 2005. Corrects factual errors. + + +.. comment Additional topic: building Python w/ UCS2 or UCS4 support +.. comment Describe obscure -U switch somewhere? +.. comment Describe use of codecs.StreamRecoder and StreamReaderWriter + +.. comment + Original outline: + + - [ ] Unicode introduction + - [ ] ASCII + - [ ] Terms + - [ ] Character + - [ ] Code point + - [ ] Encodings + - [ ] Common encodings: ASCII, Latin-1, UTF-8 + - [ ] Unicode Python type + - [ ] Writing unicode literals + - [ ] Obscurity: -U switch + - [ ] Built-ins + - [ ] unichr() + - [ ] ord() + - [ ] unicode() constructor + - [ ] Unicode type + - [ ] encode(), decode() methods + - [ ] Unicodedata module for character properties + - [ ] I/O + - [ ] Reading/writing Unicode data into files + - [ ] Byte-order marks + - [ ] Unicode filenames + - [ ] Writing Unicode programs + - [ ] Do everything in Unicode + - [ ] Declaring source code encodings (PEP 263) + - [ ] Other issues + - [ ] Building Python (UCS2, UCS4) Added: doctools/trunk/Doc-3k/howto/urllib2.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-3k/howto/urllib2.rst Thu Aug 2 23:31:34 2007 @@ -0,0 +1,573 @@ +************************************************ + HOWTO Fetch Internet Resources Using urllib2 +************************************************ + +:Author: `Michael Foord `_ + +.. note:: + + There is an French translation of an earlier revision of this + HOWTO, available at `urllib2 - Le Manuel manquant + `_. + + + +Introduction +============ + +.. sidebar:: Related Articles + + You may also find useful the following article on fetching web resources + with Python : + + * `Basic Authentication `_ + + A tutorial on *Basic Authentication*, with examples in Python. + +**urllib2** is a `Python `_ module for fetching URLs +(Uniform Resource Locators). It offers a very simple interface, in the form of +the *urlopen* function. This is capable of fetching URLs using a variety of +different protocols. It also offers a slightly more complex interface for +handling common situations - like basic authentication, cookies, proxies and so +on. These are provided by objects called handlers and openers. + +urllib2 supports fetching URLs for many "URL schemes" (identified by the string +before the ":" in URL - for example "ftp" is the URL scheme of +"ftp://python.org/") using their associated network protocols (e.g. FTP, HTTP). +This tutorial focuses on the most common case, HTTP. + +For straightforward situations *urlopen* is very easy to use. But as soon as you +encounter errors or non-trivial cases when opening HTTP URLs, you will need some +understanding of the HyperText Transfer Protocol. The most comprehensive and +authoritative reference to HTTP is :rfc:`2616`. This is a technical document and +not intended to be easy to read. This HOWTO aims to illustrate using *urllib2*, +with enough detail about HTTP to help you through. It is not intended to replace +the :mod:`urllib2` docs, but is supplementary to them. + + +Fetching URLs +============= + +The simplest way to use urllib2 is as follows:: + + import urllib2 + response = urllib2.urlopen('http://python.org/') + html = response.read() + +Many uses of urllib2 will be that simple (note that instead of an 'http:' URL we +could have used an URL starting with 'ftp:', 'file:', etc.). However, it's the +purpose of this tutorial to explain the more complicated cases, concentrating on +HTTP. + +HTTP is based on requests and responses - the client makes requests and servers +send responses. urllib2 mirrors this with a ``Request`` object which represents +the HTTP request you are making. In its simplest form you create a Request +object that specifies the URL you want to fetch. Calling ``urlopen`` with this +Request object returns a response object for the URL requested. This response is +a file-like object, which means you can for example call ``.read()`` on the +response:: + + import urllib2 + + req = urllib2.Request('http://www.voidspace.org.uk') + response = urllib2.urlopen(req) + the_page = response.read() + +Note that urllib2 makes use of the same Request interface to handle all URL +schemes. For example, you can make an FTP request like so:: + + req = urllib2.Request('ftp://example.com/') + +In the case of HTTP, there are two extra things that Request objects allow you +to do: First, you can pass data to be sent to the server. Second, you can pass +extra information ("metadata") *about* the data or the about request itself, to +the server - this information is sent as HTTP "headers". Let's look at each of +these in turn. + +Data +---- + +Sometimes you want to send data to a URL (often the URL will refer to a CGI +(Common Gateway Interface) script [#]_ or other web application). With HTTP, +this is often done using what's known as a **POST** request. This is often what +your browser does when you submit a HTML form that you filled in on the web. Not +all POSTs have to come from forms: you can use a POST to transmit arbitrary data +to your own application. In the common case of HTML forms, the data needs to be +encoded in a standard way, and then passed to the Request object as the ``data`` +argument. The encoding is done using a function from the ``urllib`` library +*not* from ``urllib2``. :: + + import urllib + import urllib2 + + url = 'http://www.someserver.com/cgi-bin/register.cgi' + values = {'name' : 'Michael Foord', + 'location' : 'Northampton', + 'language' : 'Python' } + + data = urllib.urlencode(values) + req = urllib2.Request(url, data) + response = urllib2.urlopen(req) + the_page = response.read() + +Note that other encodings are sometimes required (e.g. for file upload from HTML +forms - see `HTML Specification, Form Submission +`_ for more +details). + +If you do not pass the ``data`` argument, urllib2 uses a **GET** request. One +way in which GET and POST requests differ is that POST requests often have +"side-effects": they change the state of the system in some way (for example by +placing an order with the website for a hundredweight of tinned spam to be +delivered to your door). Though the HTTP standard makes it clear that POSTs are +intended to *always* cause side-effects, and GET requests *never* to cause +side-effects, nothing prevents a GET request from having side-effects, nor a +POST requests from having no side-effects. Data can also be passed in an HTTP +GET request by encoding it in the URL itself. + +This is done as follows:: + + >>> import urllib2 + >>> import urllib + >>> data = {} + >>> data['name'] = 'Somebody Here' + >>> data['location'] = 'Northampton' + >>> data['language'] = 'Python' + >>> url_values = urllib.urlencode(data) + >>> print url_values + name=Somebody+Here&language=Python&location=Northampton + >>> url = 'http://www.example.com/example.cgi' + >>> full_url = url + '?' + url_values + >>> data = urllib2.open(full_url) + +Notice that the full URL is created by adding a ``?`` to the URL, followed by +the encoded values. + +Headers +------- + +We'll discuss here one particular HTTP header, to illustrate how to add headers +to your HTTP request. + +Some websites [#]_ dislike being browsed by programs, or send different versions +to different browsers [#]_ . By default urllib2 identifies itself as +``Python-urllib/x.y`` (where ``x`` and ``y`` are the major and minor version +numbers of the Python release, +e.g. ``Python-urllib/2.5``), which may confuse the site, or just plain +not work. The way a browser identifies itself is through the +``User-Agent`` header [#]_. When you create a Request object you can +pass a dictionary of headers in. The following example makes the same +request as above, but identifies itself as a version of Internet +Explorer [#]_. :: + + import urllib + import urllib2 + + url = 'http://www.someserver.com/cgi-bin/register.cgi' + user_agent = 'Mozilla/4.0 (compatible; MSIE 5.5; Windows NT)' + values = {'name' : 'Michael Foord', + 'location' : 'Northampton', + 'language' : 'Python' } + headers = { 'User-Agent' : user_agent } + + data = urllib.urlencode(values) + req = urllib2.Request(url, data, headers) + response = urllib2.urlopen(req) + the_page = response.read() + +The response also has two useful methods. See the section on `info and geturl`_ +which comes after we have a look at what happens when things go wrong. + + +Handling Exceptions +=================== + +*urlopen* raises ``URLError`` when it cannot handle a response (though as usual +with Python APIs, builtin exceptions such as ValueError, TypeError etc. may also +be raised). + +``HTTPError`` is the subclass of ``URLError`` raised in the specific case of +HTTP URLs. + +URLError +-------- + +Often, URLError is raised because there is no network connection (no route to +the specified server), or the specified server doesn't exist. In this case, the +exception raised will have a 'reason' attribute, which is a tuple containing an +error code and a text error message. + +e.g. :: + + >>> req = urllib2.Request('http://www.pretend_server.org') + >>> try: urllib2.urlopen(req) + >>> except URLError, e: + >>> print e.reason + >>> + (4, 'getaddrinfo failed') + + +HTTPError +--------- + +Every HTTP response from the server contains a numeric "status code". Sometimes +the status code indicates that the server is unable to fulfil the request. The +default handlers will handle some of these responses for you (for example, if +the response is a "redirection" that requests the client fetch the document from +a different URL, urllib2 will handle that for you). For those it can't handle, +urlopen will raise an ``HTTPError``. Typical errors include '404' (page not +found), '403' (request forbidden), and '401' (authentication required). + +See section 10 of RFC 2616 for a reference on all the HTTP error codes. + +The ``HTTPError`` instance raised will have an integer 'code' attribute, which +corresponds to the error sent by the server. + +Error Codes +~~~~~~~~~~~ + +Because the default handlers handle redirects (codes in the 300 range), and +codes in the 100-299 range indicate success, you will usually only see error +codes in the 400-599 range. + +``BaseHTTPServer.BaseHTTPRequestHandler.responses`` is a useful dictionary of +response codes in that shows all the response codes used by RFC 2616. The +dictionary is reproduced here for convenience :: + + # Table mapping response codes to messages; entries have the + # form {code: (shortmessage, longmessage)}. + responses = { + 100: ('Continue', 'Request received, please continue'), + 101: ('Switching Protocols', + 'Switching to new protocol; obey Upgrade header'), + + 200: ('OK', 'Request fulfilled, document follows'), + 201: ('Created', 'Document created, URL follows'), + 202: ('Accepted', + 'Request accepted, processing continues off-line'), + 203: ('Non-Authoritative Information', 'Request fulfilled from cache'), + 204: ('No Content', 'Request fulfilled, nothing follows'), + 205: ('Reset Content', 'Clear input form for further input.'), + 206: ('Partial Content', 'Partial content follows.'), + + 300: ('Multiple Choices', + 'Object has several resources -- see URI list'), + 301: ('Moved Permanently', 'Object moved permanently -- see URI list'), + 302: ('Found', 'Object moved temporarily -- see URI list'), + 303: ('See Other', 'Object moved -- see Method and URL list'), + 304: ('Not Modified', + 'Document has not changed since given time'), + 305: ('Use Proxy', + 'You must use proxy specified in Location to access this ' + 'resource.'), + 307: ('Temporary Redirect', + 'Object moved temporarily -- see URI list'), + + 400: ('Bad Request', + 'Bad request syntax or unsupported method'), + 401: ('Unauthorized', + 'No permission -- see authorization schemes'), + 402: ('Payment Required', + 'No payment -- see charging schemes'), + 403: ('Forbidden', + 'Request forbidden -- authorization will not help'), + 404: ('Not Found', 'Nothing matches the given URI'), + 405: ('Method Not Allowed', + 'Specified method is invalid for this server.'), + 406: ('Not Acceptable', 'URI not available in preferred format.'), + 407: ('Proxy Authentication Required', 'You must authenticate with ' + 'this proxy before proceeding.'), + 408: ('Request Timeout', 'Request timed out; try again later.'), + 409: ('Conflict', 'Request conflict.'), + 410: ('Gone', + 'URI no longer exists and has been permanently removed.'), + 411: ('Length Required', 'Client must specify Content-Length.'), + 412: ('Precondition Failed', 'Precondition in headers is false.'), + 413: ('Request Entity Too Large', 'Entity is too large.'), + 414: ('Request-URI Too Long', 'URI is too long.'), + 415: ('Unsupported Media Type', 'Entity body in unsupported format.'), + 416: ('Requested Range Not Satisfiable', + 'Cannot satisfy request range.'), + 417: ('Expectation Failed', + 'Expect condition could not be satisfied.'), + + 500: ('Internal Server Error', 'Server got itself in trouble'), + 501: ('Not Implemented', + 'Server does not support this operation'), + 502: ('Bad Gateway', 'Invalid responses from another server/proxy.'), + 503: ('Service Unavailable', + 'The server cannot process the request due to a high load'), + 504: ('Gateway Timeout', + 'The gateway server did not receive a timely response'), + 505: ('HTTP Version Not Supported', 'Cannot fulfill request.'), + } + +When an error is raised the server responds by returning an HTTP error code +*and* an error page. You can use the ``HTTPError`` instance as a response on the +page returned. This means that as well as the code attribute, it also has read, +geturl, and info, methods. :: + + >>> req = urllib2.Request('http://www.python.org/fish.html') + >>> try: + >>> urllib2.urlopen(req) + >>> except URLError, e: + >>> print e.code + >>> print e.read() + >>> + 404 + + + Error 404: File Not Found + ...... etc... + +Wrapping it Up +-------------- + +So if you want to be prepared for ``HTTPError`` *or* ``URLError`` there are two +basic approaches. I prefer the second approach. + +Number 1 +~~~~~~~~ + +:: + + + from urllib2 import Request, urlopen, URLError, HTTPError + req = Request(someurl) + try: + response = urlopen(req) + except HTTPError, e: + print 'The server couldn\'t fulfill the request.' + print 'Error code: ', e.code + except URLError, e: + print 'We failed to reach a server.' + print 'Reason: ', e.reason + else: + # everything is fine + + +.. note:: + + The ``except HTTPError`` *must* come first, otherwise ``except URLError`` + will *also* catch an ``HTTPError``. + +Number 2 +~~~~~~~~ + +:: + + from urllib2 import Request, urlopen, URLError + req = Request(someurl) + try: + response = urlopen(req) + except URLError, e: + if hasattr(e, 'reason'): + print 'We failed to reach a server.' + print 'Reason: ', e.reason + elif hasattr(e, 'code'): + print 'The server couldn\'t fulfill the request.' + print 'Error code: ', e.code + else: + # everything is fine + + +info and geturl +=============== + +The response returned by urlopen (or the ``HTTPError`` instance) has two useful +methods ``info`` and ``geturl``. + +**geturl** - this returns the real URL of the page fetched. This is useful +because ``urlopen`` (or the opener object used) may have followed a +redirect. The URL of the page fetched may not be the same as the URL requested. + +**info** - this returns a dictionary-like object that describes the page +fetched, particularly the headers sent by the server. It is currently an +``httplib.HTTPMessage`` instance. + +Typical headers include 'Content-length', 'Content-type', and so on. See the +`Quick Reference to HTTP Headers `_ +for a useful listing of HTTP headers with brief explanations of their meaning +and use. + + +Openers and Handlers +==================== + +When you fetch a URL you use an opener (an instance of the perhaps +confusingly-named :class:`urllib2.OpenerDirector`). Normally we have been using +the default opener - via ``urlopen`` - but you can create custom +openers. Openers use handlers. All the "heavy lifting" is done by the +handlers. Each handler knows how to open URLs for a particular URL scheme (http, +ftp, etc.), or how to handle an aspect of URL opening, for example HTTP +redirections or HTTP cookies. + +You will want to create openers if you want to fetch URLs with specific handlers +installed, for example to get an opener that handles cookies, or to get an +opener that does not handle redirections. + +To create an opener, instantiate an ``OpenerDirector``, and then call +``.add_handler(some_handler_instance)`` repeatedly. + +Alternatively, you can use ``build_opener``, which is a convenience function for +creating opener objects with a single function call. ``build_opener`` adds +several handlers by default, but provides a quick way to add more and/or +override the default handlers. + +Other sorts of handlers you might want to can handle proxies, authentication, +and other common but slightly specialised situations. + +``install_opener`` can be used to make an ``opener`` object the (global) default +opener. This means that calls to ``urlopen`` will use the opener you have +installed. + +Opener objects have an ``open`` method, which can be called directly to fetch +urls in the same way as the ``urlopen`` function: there's no need to call +``install_opener``, except as a convenience. + + +Basic Authentication +==================== + +To illustrate creating and installing a handler we will use the +``HTTPBasicAuthHandler``. For a more detailed discussion of this subject - +including an explanation of how Basic Authentication works - see the `Basic +Authentication Tutorial +`_. + +When authentication is required, the server sends a header (as well as the 401 +error code) requesting authentication. This specifies the authentication scheme +and a 'realm'. The header looks like : ``Www-authenticate: SCHEME +realm="REALM"``. + +e.g. :: + + Www-authenticate: Basic realm="cPanel Users" + + +The client should then retry the request with the appropriate name and password +for the realm included as a header in the request. This is 'basic +authentication'. In order to simplify this process we can create an instance of +``HTTPBasicAuthHandler`` and an opener to use this handler. + +The ``HTTPBasicAuthHandler`` uses an object called a password manager to handle +the mapping of URLs and realms to passwords and usernames. If you know what the +realm is (from the authentication header sent by the server), then you can use a +``HTTPPasswordMgr``. Frequently one doesn't care what the realm is. In that +case, it is convenient to use ``HTTPPasswordMgrWithDefaultRealm``. This allows +you to specify a default username and password for a URL. This will be supplied +in the absence of you providing an alternative combination for a specific +realm. We indicate this by providing ``None`` as the realm argument to the +``add_password`` method. + +The top-level URL is the first URL that requires authentication. URLs "deeper" +than the URL you pass to .add_password() will also match. :: + + # create a password manager + password_mgr = urllib2.HTTPPasswordMgrWithDefaultRealm() + + # Add the username and password. + # If we knew the realm, we could use it instead of ``None``. + top_level_url = "http://example.com/foo/" + password_mgr.add_password(None, top_level_url, username, password) + + handler = urllib2.HTTPBasicAuthHandler(password_mgr) + + # create "opener" (OpenerDirector instance) + opener = urllib2.build_opener(handler) + + # use the opener to fetch a URL + opener.open(a_url) + + # Install the opener. + # Now all calls to urllib2.urlopen use our opener. + urllib2.install_opener(opener) + +.. note:: + + In the above example we only supplied our ``HHTPBasicAuthHandler`` to + ``build_opener``. By default openers have the handlers for normal situations + -- ``ProxyHandler``, ``UnknownHandler``, ``HTTPHandler``, + ``HTTPDefaultErrorHandler``, ``HTTPRedirectHandler``, ``FTPHandler``, + ``FileHandler``, ``HTTPErrorProcessor``. + +``top_level_url`` is in fact *either* a full URL (including the 'http:' scheme +component and the hostname and optionally the port number) +e.g. "http://example.com/" *or* an "authority" (i.e. the hostname, +optionally including the port number) e.g. "example.com" or "example.com:8080" +(the latter example includes a port number). The authority, if present, must +NOT contain the "userinfo" component - for example "joe at password:example.com" is +not correct. + + +Proxies +======= + +**urllib2** will auto-detect your proxy settings and use those. This is through +the ``ProxyHandler`` which is part of the normal handler chain. Normally that's +a good thing, but there are occasions when it may not be helpful [#]_. One way +to do this is to setup our own ``ProxyHandler``, with no proxies defined. This +is done using similar steps to setting up a `Basic Authentication`_ handler : :: + + >>> proxy_support = urllib2.ProxyHandler({}) + >>> opener = urllib2.build_opener(proxy_support) + >>> urllib2.install_opener(opener) + +.. note:: + + Currently ``urllib2`` *does not* support fetching of ``https`` locations + through a proxy. This can be a problem. + +Sockets and Layers +================== + +The Python support for fetching resources from the web is layered. urllib2 uses +the httplib library, which in turn uses the socket library. + +As of Python 2.3 you can specify how long a socket should wait for a response +before timing out. This can be useful in applications which have to fetch web +pages. By default the socket module has *no timeout* and can hang. Currently, +the socket timeout is not exposed at the httplib or urllib2 levels. However, +you can set the default timeout globally for all sockets using :: + + import socket + import urllib2 + + # timeout in seconds + timeout = 10 + socket.setdefaulttimeout(timeout) + + # this call to urllib2.urlopen now uses the default timeout + # we have set in the socket module + req = urllib2.Request('http://www.voidspace.org.uk') + response = urllib2.urlopen(req) + + +------- + + +Footnotes +========= + +This document was reviewed and revised by John Lee. + +.. [#] For an introduction to the CGI protocol see + `Writing Web Applications in Python `_. +.. [#] Like Google for example. The *proper* way to use google from a program + is to use `PyGoogle `_ of course. See + `Voidspace Google `_ + for some examples of using the Google API. +.. [#] Browser sniffing is a very bad practise for website design - building + sites using web standards is much more sensible. Unfortunately a lot of + sites still send different versions to different browsers. +.. [#] The user agent for MSIE 6 is + *'Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 1.1.4322)'* +.. [#] For details of more HTTP request headers, see + `Quick Reference to HTTP Headers`_. +.. [#] In my case I have to use a proxy to access the internet at work. If you + attempt to fetch *localhost* URLs through this proxy it blocks them. IE + is set to use the proxy, which urllib2 picks up on. In order to test + scripts with a localhost server, I have to prevent urllib2 from using + the proxy. Modified: doctools/trunk/sphinx/templates/index.html ============================================================================== --- doctools/trunk/sphinx/templates/index.html (original) +++ doctools/trunk/sphinx/templates/index.html Thu Aug 2 23:31:34 2007 @@ -24,6 +24,8 @@ keep this under your pillow

      Macintosh Library Modules
      this too, if you use a Macintosh

      +

      Python HOWTOs
      + in-depth documents on specific topics

      \n' + + TR = ('' + '' + '') + + f = file(output, 'w') + table = '\n'.join(TABLE % fname + + '\n'.join(TR % (no % 2,) % entry + for no, entry in enumerate(store[fname])) + for fname in sorted(store)) + f.write(HTML % (', '.join(map(abspath, args)), table)) + f.close() + + print "Report written to %s." % output + return 0 + +if __name__ == '__main__': + sys.exit(main()) Added: external/Pygments-0.8.1/scripts/find_error.py ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/scripts/find_error.py Thu Aug 9 17:43:13 2007 @@ -0,0 +1,51 @@ +#!/usr/bin/python +# -*- coding: utf-8 -*- +""" + Lexing error finder + ~~~~~~~~~~~~~~~~~~~ + + For the source files given on the command line, display + the text where Error tokens are being generated, along + with some context. + + :copyright: 2006-2007 by Tim Hatch . + :license: BSD, see LICENSE for more details. +""" + +import sys, os + +try: + import pygments +except ImportError: + # try parent path + sys.path.append(os.path.join(os.path.dirname(__file__), "..")) + +from pygments import highlight +from pygments.lexers import get_lexer_for_filename, get_lexer_by_name +from pygments.token import Error + +def main(fn): + try: + lx = get_lexer_for_filename(fn) + except ValueError: + try: + name, rest = fn.split("_", 1) + lx = get_lexer_by_name(name) + except ValueError: + raise AssertionError('no lexer found for file %r' % fn) + text = file(fn, 'U').read() + text = text.strip('\n') + '\n' + text = text.decode('latin1') + ntext = [] + for type, val in lx.get_tokens(text): + if type == Error: + print "Error parsing", fn + print "\n".join([' ' + repr(x) for x in ntext[-5:]]) + print `val` + "<<<" + return + ntext.append((type,val)) + + +if __name__ == "__main__": + for f in sys.argv[1:]: + main(f) Added: external/Pygments-0.8.1/scripts/fix_epydoc_markup.py ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/scripts/fix_epydoc_markup.py Thu Aug 9 17:43:13 2007 @@ -0,0 +1,46 @@ +#!/usr/bin/env python +# -*- coding: utf-8 -*- +""" + fix_epydoc_tables + ~~~~~~~~~~~~~~~~~ + + Fix epydoc "summary" tables. + + :copyright: 2006-2007 by Georg Brandl. + :license: GNU GPL, see LICENSE for more details. +""" + +import sys, os +from os.path import join + +path = sys.argv[1] + +for fn in os.listdir(path): + fn = join(path, fn) + if not fn.endswith(".html"): + continue + + ll = list(file(fn)) + c = False + d = False + n = False + + for i, l in enumerate(ll): + if " + + + + ... + + + ... + + +--> + + + +%HTML4.dtd; \ No newline at end of file Added: external/Pygments-0.8.1/tests/dtds/HTML4-s.dtd ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/dtds/HTML4-s.dtd Thu Aug 9 17:43:13 2007 @@ -0,0 +1,869 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +%HTMLlat1; + + +%HTMLsymbol; + + +%HTMLspecial; + + + + + + + + + + + + + +]]> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Added: external/Pygments-0.8.1/tests/dtds/HTML4.dcl ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/dtds/HTML4.dcl Thu Aug 9 17:43:13 2007 @@ -0,0 +1,88 @@ + \ No newline at end of file Added: external/Pygments-0.8.1/tests/dtds/HTML4.dtd ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/dtds/HTML4.dtd Thu Aug 9 17:43:13 2007 @@ -0,0 +1,1092 @@ + + + + + ... + + + ... + + + + The URI used as a system identifier with the public identifier allows + the user agent to download the DTD and entity sets as needed. + + The FPI for the Strict HTML 4.0 DTD is: + + "-//W3C//DTD HTML 4.0//EN" + + and its URI is: + + http://www.w3.org/TR/REC-html40/strict.dtd + + Authors should use the Strict DTD unless they need the + presentation control for user agents that don't (adequately) + support style sheets. + + If you are writing a document that includes frames, use + the following FPI: + + "-//W3C//DTD HTML 4.0 Frameset//EN" + + with the URI: + + http://www.w3.org/TR/REC-html40/frameset.dtd + + The following URIs are supported in relation to HTML 4.0 + + "http://www.w3.org/TR/REC-html40/strict.dtd" (Strict DTD) + "http://www.w3.org/TR/REC-html40/loose.dtd" (Loose DTD) + "http://www.w3.org/TR/REC-html40/frameset.dtd" (Frameset DTD) + "http://www.w3.org/TR/REC-html40/HTMLlat1.ent" (Latin-1 entities) + "http://www.w3.org/TR/REC-html40/HTMLsymbol.ent" (Symbol entities) + "http://www.w3.org/TR/REC-html40/HTMLspecial.ent" (Special entities) + + These URIs point to the latest version of each file. To reference + this specific revision use the following URIs: + + "http://www.w3.org/TR/REC-html40-971218/strict.dtd" + "http://www.w3.org/TR/REC-html40-971218/loose.dtd" + "http://www.w3.org/TR/REC-html40-971218/frameset.dtd" + "http://www.w3.org/TR/REC-html40-971218/HTMLlat1.ent" + "http://www.w3.org/TR/REC-html40-971218/HTMLsymbol.ent" + "http://www.w3.org/TR/REC-html40-971218/HTMLspecial.ent" + +--> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +%HTMLlat1; + + +%HTMLsymbol; + + +%HTMLspecial; + + + + + + + + + + + + + +]]> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +]]> + + + + +]]> + + + + + +]]> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +]]> + + + + + Added: external/Pygments-0.8.1/tests/dtds/HTML4.soc ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/dtds/HTML4.soc Thu Aug 9 17:43:13 2007 @@ -0,0 +1,9 @@ +OVERRIDE YES +SGMLDECL HTML4.dcl +DOCTYPE HTML HTML4.dtd +PUBLIC "-//W3C//DTD HTML 4.0//EN" HTML4-s.dtd +PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" HTML4.dtd +PUBLIC "-//W3C//DTD HTML 4.0 Frameset//EN" HTML4-f.dtd +PUBLIC "-//W3C//ENTITIES Latin1//EN//HTML" HTMLlat1.ent +PUBLIC "-//W3C//ENTITIES Special//EN//HTML" HTMLspec.ent +PUBLIC "-//W3C//ENTITIES Symbols//EN//HTML" HTMLsym.ent Added: external/Pygments-0.8.1/tests/dtds/HTMLlat1.ent ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/dtds/HTMLlat1.ent Thu Aug 9 17:43:13 2007 @@ -0,0 +1,195 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file Added: external/Pygments-0.8.1/tests/dtds/HTMLspec.ent ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/dtds/HTMLspec.ent Thu Aug 9 17:43:13 2007 @@ -0,0 +1,77 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file Added: external/Pygments-0.8.1/tests/dtds/HTMLsym.ent ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/dtds/HTMLsym.ent Thu Aug 9 17:43:13 2007 @@ -0,0 +1,241 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file Added: external/Pygments-0.8.1/tests/examplefiles/AlternatingGroup.mu ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/AlternatingGroup.mu Thu Aug 9 17:43:13 2007 @@ -0,0 +1,102 @@ +/*++ $Id: AlternatingGroup.mu,v 1.4 2003/09/08 15:00:47 nthiery Exp $ + +Dom::AlternatingGroup(n) -- the Alternating Group of {1..n} + +n - integer >= 1 + +Elements are represented as in Dom::PermutationGroup(n) + +Author: Nicolas M. Thi?ry +License: LGPL +Created: August 8th, 1999 +Last update: $Date: 2003/09/08 15:00:47 $ +++*/ + +domain Dom::AlternatingGroup(n: Type::PosInt) + inherits Dom::PermutationGroup(n,toBeDefined); + category Cat::PermutationGroup; + axiom Ax::canonicalRep; + +/*-- + size + + Size of the group. +--*/ + + size := fact(n)/2; + +/*-- + generators + + A list of generators of the group + + The first 3-cycle (1,2,3), and a maximal even cycle (1,...,n) or + (2,...,n) depending on the parity of n + +--*/ + + generators := + if n<=2 then generators:=[dom([[1]])]; + elif n=3 then generators:=[dom([[1,2,3]])]; + elif n mod 2=0 then generators:=[dom([[1,2,3]]), dom([[$2..n]])]; + else generators:=[dom([[1,2,3]]), dom([[$1..n]])]; + end_if; + +/*-- + allElements + + List of all the elements of the group +--*/ + + allElements := + proc() + option remember; + local p; + begin + [new(dom,p) $ p in select(combinat::permutations(n), + p->bool(combinat::permutations::sign(p)=1))]; + end_proc; + +/*-- + cycleTypes: + + Count the elements of the group by cycle type. + (Cf Cat::PermutationGroupModule). + + Same algorithm as for Dom::SymmetricGroup, but only even permutations + are considered. This is done by disregarding partitions p such + that n-length(p) is odd. +--*/ + + cycleTypes := + proc() + option remember; + local t, p, gen; + begin + userinfo(3, "cycleTypes: starting computation"); + t:=table(); + + gen := combinat::partitions::generator(n); + while (p:=gen()) <> FAIL do + userinfo(5, "working on partition", p); + if(n-nops(p) mod 2=0) then + // Compute the size of the conjugacy class of Sn indexed by p + // and the cycle type of a permutation in this conjugacy class + t[combinat::partitions::toExp(p,n)] + := combinat::partitions::conjugacyClassSize(p); + end_if; + end_while; + t; + end_proc; + +begin + if testargs() then + if args(0) <> 1 then error("wrong no of args"); end_if; + if not testtype(n,DOM_INT) then + error("argument must be integer") + end_if; + if n < 1 then + error("argument must be positive") + end_if; + end_if; +end_domain: Added: external/Pygments-0.8.1/tests/examplefiles/Intro.java ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/Intro.java Thu Aug 9 17:43:13 2007 @@ -0,0 +1,1660 @@ +/* + * Copyright (c) 2003 Sun Microsystems, Inc. All Rights Reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * -Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * -Redistribution in binary form must reproduct the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the distribution. + * + * Neither the name of Sun Microsystems, Inc. or the names of contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * This software is provided "AS IS," without a warranty of any kind. ALL + * EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING + * ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE + * OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN AND ITS LICENSORS SHALL NOT + * BE LIABLE FOR ANY DAMAGES OR LIABILITIES SUFFERED BY LICENSEE AS A RESULT + * OF OR RELATING TO USE, MODIFICATION OR DISTRIBUTION OF THE SOFTWARE OR ITS + * DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY LOST + * REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, + * INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY + * OF LIABILITY, ARISING OUT OF THE USE OF OR INABILITY TO USE SOFTWARE, EVEN + * IF SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + * + * You acknowledge that Software is not designed, licensed or intended for + * use in the design, construction, operation or maintenance of any nuclear + * facility. + */ + + +package java2d; + +import java.awt.*; +import java.awt.event.*; +import java.awt.geom.*; +import java.awt.image.BufferedImage; +import java.awt.image.DataBuffer; +import java.awt.font.*; +import javax.swing.*; +import javax.swing.border.*; +import javax.swing.table.*; +import javax.swing.event.*; +import java.util.Vector; +import java.util.List; +import java.util.Arrays; + + + +/** + * Introduction to the Java2Demo. + * + * @version @(#)Intro.java 1.19 03/06/26 + * @author Brian Lichtenwalter + */ +public class Intro extends JPanel { + + static Color black = new Color(20, 20, 20); + static Color white = new Color(240, 240, 255); + static Color red = new Color(149, 43, 42); + static Color blue = new Color(94, 105, 176); + static Color yellow = new Color(255, 255, 140); + + static Surface surface; + private ScenesTable scenesTable; + private boolean doTable; + + + public Intro() { + EmptyBorder eb = new EmptyBorder(80,110,80,110); + BevelBorder bb = new BevelBorder(BevelBorder.LOWERED); + setBorder(new CompoundBorder(eb,bb)); + setLayout(new BorderLayout()); + setBackground(Color.gray); + setToolTipText("click for scene table"); + add(surface = new Surface()); + addMouseListener(new MouseAdapter() { + public void mouseClicked(MouseEvent e) { + removeAll(); + if ((doTable = !doTable)) { + setToolTipText("click for animation"); + surface.stop(); + if (scenesTable == null) { + scenesTable = new ScenesTable(); + } + add(scenesTable); + } else { + setToolTipText("click for scene table"); + surface.start(); + add(surface); + } + revalidate(); + repaint(); + } + }); + } + + + public void start() { + if (!doTable) { + surface.start(); + } + } + + + public void stop() { + if (!doTable) { + surface.stop(); + } + } + + + public static void main(String argv[]) { + final Intro intro = new Intro(); + WindowListener l = new WindowAdapter() { + public void windowClosing(WindowEvent e) {System.exit(0);} + public void windowDeiconified(WindowEvent e) { intro.start(); } + public void windowIconified(WindowEvent e) { intro.stop(); } + }; + JFrame f = new JFrame("Java2D Demo - Intro"); + f.addWindowListener(l); + f.getContentPane().add("Center", intro); + f.pack(); + Dimension screenSize = Toolkit.getDefaultToolkit().getScreenSize(); + int w = 720; + int h = 510; + f.setLocation(screenSize.width/2 - w/2, screenSize.height/2 - h/2); + f.setSize(w, h); + f.setVisible(true); + intro.start(); + } + + + /** + * ScenesTable is the list of scenes known to the Director. + * Scene participation, scene name and scene pause amount columns. + * Global animation delay for scene's steps. + */ + static class ScenesTable extends JPanel implements ActionListener, ChangeListener { + + private JTable table; + private TableModel dataModel; + + public ScenesTable() { + setBackground(Color.white); + setLayout(new BorderLayout()); + final String[] names = { "", "Scenes", "Pause" }; + + dataModel = new AbstractTableModel() { + public int getColumnCount() { return names.length; } + public int getRowCount() { return surface.director.size();} + public Object getValueAt(int row, int col) { + Surface.Scene scene = (Surface.Scene) surface.director.get(row); + if (col == 0) { + return scene.participate; + } else if (col == 1) { + return scene.name; + } else { + return scene.pauseAmt; + } + } + public String getColumnName(int col) {return names[col]; } + public Class getColumnClass(int c) { + return getValueAt(0, c).getClass(); + } + public boolean isCellEditable(int row, int col) { + return col != 1 ? true : false; + } + public void setValueAt(Object aValue, int row, int col) { + Surface.Scene scene = (Surface.Scene) surface.director.get(row); + if (col == 0) { + scene.participate = aValue; + } else if (col == 1) { + scene.name = aValue; + } else { + scene.pauseAmt = aValue; + } + } + }; + + table = new JTable(dataModel); + TableColumn col = table.getColumn(""); + col.setWidth(16); + col.setMinWidth(16); + col.setMaxWidth(20); + col = table.getColumn("Pause"); + col.setWidth(60); + col.setMinWidth(60); + col.setMaxWidth(60); + table.sizeColumnsToFit(0); + + JScrollPane scrollpane = new JScrollPane(table); + add(scrollpane); + + JPanel panel = new JPanel(new BorderLayout()); + JButton b = new JButton("Unselect All"); + b.setHorizontalAlignment(JButton.LEFT); + Font font = new Font("serif", Font.PLAIN, 10); + b.setFont(font); + b.addActionListener(this); + panel.add("West", b); + + JSlider slider = new JSlider(JSlider.HORIZONTAL, 0, 200, (int) surface.sleepAmt); + slider.addChangeListener(this); + TitledBorder tb = new TitledBorder(new EtchedBorder()); + tb.setTitleFont(font); + tb.setTitle("Anim delay = " + String.valueOf(surface.sleepAmt) + " ms"); + slider.setBorder(tb); + slider.setPreferredSize(new Dimension(140,40)); + slider.setMinimumSize(new Dimension(100,40)); + slider.setMaximumSize(new Dimension(180,40)); + panel.add("East", slider); + + add("South", panel); + } + + + public void actionPerformed(ActionEvent e) { + JButton b = (JButton) e.getSource(); + b.setSelected(!b.isSelected()); + b.setText(b.isSelected() ? "Select All" : "Unselect All"); + for (int i = 0; i < surface.director.size(); i++) { + Surface.Scene scene = (Surface.Scene) surface.director.get(i); + scene.participate = new Boolean(!b.isSelected()); + } + table.tableChanged(new TableModelEvent(dataModel)); + } + + + public void stateChanged(ChangeEvent e) { + JSlider slider = (JSlider) e.getSource(); + int value = slider.getValue(); + TitledBorder tb = (TitledBorder) slider.getBorder(); + tb.setTitle("Anim delay = " + String.valueOf(value) + " ms"); + surface.sleepAmt = (long) value; + slider.repaint(); + } + } // End ScenesTable class + + + + /** + * Surface is the stage where the Director plays its scenes. + */ + static class Surface extends JPanel implements Runnable { + + static Surface surf; + static Image cupanim, java_logo; + static BufferedImage bimg; + public Director director; + public int index; + public long sleepAmt = 30; + private Thread thread; + + + public Surface() { + surf = this; + setBackground(black); + setLayout(new BorderLayout()); + addMouseListener(new MouseAdapter() { + public void mouseClicked(MouseEvent e) { + if (thread == null) start(); else stop(); + } + }); + cupanim = DemoImages.getImage("cupanim.gif", this); + java_logo = DemoImages.getImage("java_logo.png", this); + director = new Director(); + } + + + static FontMetrics getMetrics(Font font) { + return surf.getFontMetrics(font); + } + + + public void paint(Graphics g) { + Dimension d = getSize(); + if (d.width <= 0 || d.height <= 0) { + return; + } + if (bimg == null || bimg.getWidth() != d.width || bimg.getHeight() != d.height) { + bimg = getGraphicsConfiguration().createCompatibleImage(d.width, d.height); + // reset future scenes + for (int i = index+1; i < director.size(); i++) { + ((Scene) director.get(i)).reset(d.width, d.height); + } + } + + Scene scene = (Scene) director.get(index); + if (scene.index <= scene.length) { + if (thread != null) { + scene.step(d.width, d.height); + } + + Graphics2D g2 = bimg.createGraphics(); + g2.setRenderingHint(RenderingHints.KEY_ANTIALIASING, + RenderingHints.VALUE_ANTIALIAS_ON); + g2.setBackground(getBackground()); + g2.clearRect(0, 0, d.width, d.height); + + scene.render(d.width, d.height, g2); + + if (thread != null) { + // increment scene.index after scene.render + scene.index++; + } + g2.dispose(); + } + g.drawImage(bimg, 0, 0, this); + } + + + + public void start() { + if (thread == null) { + thread = new Thread(this); + thread.setPriority(Thread.MIN_PRIORITY); + thread.setName("Intro"); + thread.start(); + } + } + + + public synchronized void stop() { + if (thread != null) { + thread.interrupt(); + } + thread = null; + notifyAll(); + } + + + public void reset() { + index = 0; + Dimension d = getSize(); + for (int i = 0; i < director.size(); i++) { + ((Scene) director.get(i)).reset(d.width, d.height); + } + } + + + public void run() { + + Thread me = Thread.currentThread(); + + while (thread == me && !isShowing() || getSize().width <= 0) { + try { + thread.sleep(500); + } catch (InterruptedException e) { return; } + } + + if (index == 0) { + reset(); + } + + while (thread == me) { + Scene scene = (Scene) director.get(index); + if (((Boolean) scene.participate).booleanValue()) { + repaint(); + try { + thread.sleep(sleepAmt); + } catch (InterruptedException e) { break; } + if (scene.index > scene.length) { + scene.pause(thread); + if (++index >= director.size()) { + reset(); + } + } + } else { + if (++index >= director.size()) { + reset(); + } + } + } + thread = null; + } + + + + /** + * Part is a piece of the scene. Classes must implement Part + * inorder to participate in a scene. + */ + interface Part { + public void reset(int newwidth, int newheight); + public void step(int w, int h); + public void render(int w, int h, Graphics2D g2); + public int getBegin(); + public int getEnd(); + } + + + + /** + * Director is the holder of the scenes, their names & pause amounts + * between scenes. + */ + static class Director extends Vector { + + GradientPaint gp = new GradientPaint(0,40,blue,38,2,black); + Font f1 = new Font("serif", Font.PLAIN, 200); + Font f2 = new Font("serif", Font.PLAIN, 120); + Font f3 = new Font("serif", Font.PLAIN, 72); + Object parts[][][] = { + { { "J - scale text on gradient", "0" }, + { new GpE(GpE.BURI, black, blue, 0, 20), + new TxE("J", f1, TxE.SCI, yellow, 2, 20) } }, + { { "2 - scale & rotate text on gradient" , "0" }, + { new GpE(GpE.BURI, blue, black, 0, 22), + new TxE("2", f1, TxE.RI | TxE.SCI, yellow, 2, 22) } }, + { { "D - scale text on gradient", "0" }, + { new GpE(GpE.BURI, black, blue, 0, 20), + new TxE("D", f1, TxE.SCI, yellow, 2, 20) } }, + { { "Java2D - scale & rotate text on gradient", "1000" }, + { new GpE(GpE.SIH, blue, black, 0, 40), + new TxE("Java2D", f2, TxE.RI | TxE.SCI, yellow, 0, 40) }}, + { { "Previous scene dither dissolve out", "0"}, + { new DdE(0, 20, 1) }}, + { { "Graphics Features", "999" }, + { new Temp(Temp.RECT, null, 0, 15), + new Temp(Temp.IMG, java_logo, 2, 15), + new Temp(Temp.RNA | Temp.INA, java_logo, 16, 130), + new Features(Features.GRAPHICS, 16, 130) }}, + { { "Java2D - texture text on gradient", "1000"}, + { new GpE(GpE.WI, blue, black, 0, 20), + new GpE(GpE.WD, blue, black, 21, 40), + new TpE(TpE.OI | TpE.NF, black, yellow, 4, 0, 10), + new TpE(TpE.OD | TpE.NF, black, yellow, 4, 11, 20), + new TpE(TpE.OI | TpE.NF | TpE.HAF, black, yellow,5,21,40), + new TxE("Java2D", f2, 0, null, 0, 40) }}, + { { "Previous scene random close out", "0"}, + { new CoE(CoE.RAND, 0, 20) } }, + { { "Text Features", "999" }, + { new Temp(Temp.RECT, null, 0, 15), + new Temp(Temp.IMG, java_logo, 2, 15), + new Temp(Temp.RNA | Temp.INA, java_logo, 16, 130), + new Features(Features.TEXT, 16, 130) }}, + { { "Java2D - composite text on texture", "1000"}, + { new TpE(TpE.RI, black, gp, 40, 0, 20), + new TpE(TpE.RD, black, gp, 40, 21, 40), + new TpE(TpE.RI, black, gp, 40, 41, 60), + new TxE("Java2D", f2, TxE.AC, yellow, 0, 60) }}, + { { "Previous scene dither dissolve out", "0"}, + { new DdE(0, 20, 4) }}, + { { "Imaging Features", "999" }, + { new Temp(Temp.RECT, null, 0, 15), + new Temp(Temp.IMG, java_logo, 2, 15), + new Temp(Temp.RNA | Temp.INA, java_logo, 16, 130), + new Features(Features.IMAGES, 16, 130) }}, + { { "Java2D - text on gradient", "1000" }, + { new GpE(GpE.SDH, blue, black, 0, 20), + new GpE(GpE.SIH, blue, black, 21, 40), + new GpE(GpE.SDH, blue, black, 41, 50), + new GpE(GpE.INC | GpE.NF, red, yellow, 0, 50), + new TxE("Java2D", f2, TxE.NOP, null, 0, 50) }}, + { { "Previous scene ellipse close out", "0"}, + { new CoE(CoE.OVAL, 0, 20) } }, + { { "Color Features", "999" }, + { new Temp(Temp.RECT, null, 0, 15), + new Temp(Temp.IMG, java_logo, 2, 15), + new Temp(Temp.RNA | Temp.INA, java_logo, 16, 99), + new Features(Features.COLOR, 16, 99) }}, + { { "Java2D - composite and rotate text on paints", "2000" }, + { new GpE(GpE.BURI, black, blue, 0, 20), + new GpE(GpE.BURD, black, blue, 21, 30), + new TpE(TpE.OI | TpE.HAF, black, blue, 10, 31, 40), + new TxE("Java2D", f2, TxE.AC | TxE.RI, yellow, 0, 40) }}, + { { "Previous scene subimage transform out", "0" }, + { new SiE(60, 60, 0, 40) }}, + { { "CREDITS - transform in", "1000" }, + { new LnE(LnE.ACI | LnE.ZOOMI | LnE.RI, 0, 60), + new TxE("CREDITS", f3, TxE.AC | TxE.SCI, Color.red,20,30), + new TxE("CREDITS", f3, TxE.SCXD, Color.red, 31, 38), + new TxE("CREDITS", f3, TxE.SCXI, Color.red, 39, 48), + new TxE("CREDITS", f3, TxE.SCXD, Color.red, 49, 54), + new TxE("CREDITS", f3, TxE.SCXI, Color.red, 55, 60) }}, + { { "CREDITS - transform out", "0" }, + { new LnE(LnE.ACD | LnE.ZOOMD | LnE.RD, 0, 45), + new TxE("CREDITS", f3, 0, Color.red, 0, 9), + new TxE("CREDITS", f3, TxE.SCD | TxE.RD, Color.red,10,30)}}, + { { "Contributors", "1000" }, + { new Temp(Temp.RECT, null, 0, 30), + new Temp(Temp.IMG, cupanim, 4, 30), + new Temp(Temp.RNA | Temp.INA, cupanim, 31, 200), + new Contributors(34, 200) } }, + }; + + + public Director() { + for (int i = 0; i < parts.length; i++) { + Vector v = new Vector(); + for (int j = 0; j < parts[i][1].length; j++) { + v.addElement(parts[i][1][j]); + } + addElement(new Scene(v, parts[i][0][0], parts[i][0][1])); + } + } + } + + + + /** + * Scene is the manager of the parts. + */ + static class Scene extends Object { + public Object name; + public Object participate = new Boolean(true); + public Object pauseAmt; + public Vector parts; + public int index; + public int length; + + public Scene(Vector parts, Object name, Object pauseAmt) { + this.name = name; + this.parts = parts; + this.pauseAmt = pauseAmt; + for (int i = 0; i < parts.size(); i++) { + if (((Part) parts.get(i)).getEnd() > length) { + length = ((Part) parts.get(i)).getEnd(); + } + } + } + + public void reset(int w, int h) { + index = 0; + for (int i = 0; i < parts.size(); i++) { + ((Part) parts.get(i)).reset(w, h); + } + } + + public void step(int w, int h) { + for (int i = 0; i < parts.size(); i++) { + Part part = (Part) parts.get(i); + if (index >= part.getBegin() && index <= part.getEnd()) { + part.step(w, h); + } + } + } + + public void render(int w, int h, Graphics2D g2) { + for (int i = 0; i < parts.size(); i++) { + Part part = (Part) parts.get(i); + if (index >= part.getBegin() && index <= part.getEnd()) { + part.render(w, h, g2); + } + } + } + + public void pause(Thread thread) { + try { + thread.sleep(Long.parseLong((String) pauseAmt)); + } catch (Exception e) { } + System.gc(); + } + } // End Scene class + + + + /** + * Text Effect. Transformation of characters. Clip or fill. + */ + static class TxE implements Part { + + static final int INC = 1; + static final int DEC = 2; + static final int R = 4; // rotate + static final int RI = R | INC; + static final int RD = R | DEC; + static final int SC = 8; // scale + static final int SCI = SC | INC; + static final int SCD = SC | DEC; + static final int SCX = 16; // scale invert x + static final int SCXI = SCX | SC | INC; + static final int SCXD = SCX | SC | DEC; + static final int SCY = 32; // scale invert y + static final int SCYI = SCY | SC | INC; + static final int SCYD = SCY | SC | DEC; + static final int AC = 64; // AlphaComposite + static final int CLIP = 128; // Clipping + static final int NOP = 512; // No Paint + private int beginning, ending; + private int type; + private double rIncr, sIncr; + private double sx, sy, rotate; + private Shape shapes[], txShapes[]; + private int sw; + private int numRev; + private Paint paint; + + + public TxE(String text, + Font font, + int type, + Paint paint, + int beg, + int end) { + this.type = type; + this.paint = paint; + this.beginning = beg; + this.ending = end; + + setIncrements(2); + + char[] chars = text.toCharArray(); + shapes = new Shape[chars.length]; + txShapes = new Shape[chars.length]; + FontRenderContext frc = new FontRenderContext(null,true,true); + TextLayout tl = new TextLayout(text, font, frc); + sw = (int) tl.getOutline(null).getBounds().getWidth(); + for (int j = 0; j < chars.length; j++) { + String s = String.valueOf(chars[j]); + shapes[j] = new TextLayout(s, font, frc).getOutline(null); + } + } + + + public void setIncrements(double numRevolutions) { + this.numRev = (int) numRevolutions; + rIncr = 360.0 / ((ending - beginning) / numRevolutions); + sIncr = 1.0 / (ending - beginning); + if ((type & SCX) != 0 || (type & SCY) != 0) { + sIncr *= 2; + } + if ((type & DEC) != 0) { + rIncr = -rIncr; + sIncr = -sIncr; + } + } + + + public void reset(int w, int h) { + if (type == SCXI) { + sx = -1.0; sy = 1.0; + } else if (type == SCYI) { + sx = 1.0; sy = -1.0; + } else { + sx = sy = (type & DEC) != 0 ? 1.0 : 0.0; + } + rotate = 0; + } + + + public void step(int w, int h) { + + float charWidth = w/2-sw/2; + + for (int i = 0; i < shapes.length; i++) { + AffineTransform at = new AffineTransform(); + Rectangle2D maxBounds = shapes[i].getBounds(); + at.translate(charWidth, h/2+maxBounds.getHeight()/2); + charWidth += (float) maxBounds.getWidth() + 1; + Shape shape = at.createTransformedShape(shapes[i]); + Rectangle2D b1 = shape.getBounds2D(); + + if ((type & R) != 0) { + at.rotate(Math.toRadians(rotate)); + } + if ((type & SC) != 0) { + at.scale(sx, sy); + } + shape = at.createTransformedShape(shapes[i]); + Rectangle2D b2 = shape.getBounds2D(); + + double xx = (b1.getX()+b1.getWidth()/2) + - (b2.getX()+b2.getWidth()/2); + double yy = (b1.getY()+b1.getHeight()/2) + - (b2.getY()+b2.getHeight()/2); + AffineTransform toCenterAT = new AffineTransform(); + toCenterAT.translate(xx, yy); + toCenterAT.concatenate(at); + txShapes[i] = toCenterAT.createTransformedShape(shapes[i]); + } + // avoid over rotation + if (Math.abs(rotate) <= numRev * 360) { + rotate += rIncr; + if ((type & SCX) != 0) { + sx += sIncr; + } else if ((type & SCY) != 0) { + sy += sIncr; + } else { + sx += sIncr; sy += sIncr; + } + } + } + + + public void render(int w, int h, Graphics2D g2) { + Composite saveAC = null; + if ((type & AC) != 0 && sx > 0 && sx < 1) { + saveAC = g2.getComposite(); + g2.setComposite(AlphaComposite.getInstance(AlphaComposite.SRC_OVER, (float) sx)); + } + GeneralPath path = null; + if ((type & CLIP) != 0) { + path = new GeneralPath(); + } + if (paint != null) { + g2.setPaint(paint); + } + for (int i = 0; i < txShapes.length; i++) { + if ((type & CLIP) != 0) { + path.append(txShapes[i], false); + } else { + g2.fill(txShapes[i]); + } + } + if ((type & CLIP) != 0) { + g2.clip(path); + } + if (saveAC != null) { + g2.setComposite(saveAC); + } + } + + + public int getBegin() { + return beginning; + } + + public int getEnd() { + return ending; + } + } // End TxE class + + + + + /** + * GradientPaint Effect. Burst, split, horizontal and + * vertical gradient fill effects. + */ + static class GpE implements Part { + + static final int INC = 1; // increasing + static final int DEC = 2; // decreasing + static final int CNT = 4; // center + static final int WID = 8; // width + static final int WI = WID | INC; + static final int WD = WID | DEC; + static final int HEI = 16; // height + static final int HI = HEI | INC; + static final int HD = HEI | DEC; + static final int SPL = 32 | CNT; // split + static final int SIW = SPL | INC | WID; + static final int SDW = SPL | DEC | WID; + static final int SIH = SPL | INC | HEI; + static final int SDH = SPL | DEC | HEI; + static final int BUR = 64 | CNT; // burst + static final int BURI = BUR | INC; + static final int BURD = BUR | DEC; + static final int NF = 128; // no fill + private Color c1, c2; + private int beginning, ending; + private float incr, index; + private Vector rect = new Vector(); + private Vector grad = new Vector(); + private int type; + + + public GpE(int type, Color c1, Color c2, int beg, int end) { + this.type = type; + this.c1 = c1; + this.c2 = c2; + this.beginning = beg; + this.ending = end; + } + + + public void reset(int w, int h) { + incr = 1.0f / (ending - beginning); + if ((type & CNT) != 0) { + incr /= 2.3f; + } + if ((type & CNT) != 0 && (type & INC) != 0) { + index = 0.5f; + } else if ((type & DEC) != 0) { + index = 1.0f; + incr = -incr; + } else { + index = 0.0f; + } + index += incr; + } + + + public void step(int w, int h) { + rect.clear(); + grad.clear(); + + if ((type & WID) != 0) { + float w2 = 0, x1 = 0, x2 = 0; + if ((type & SPL) != 0) { + w2 = w * 0.5f; + x1 = w * (1.0f - index); + x2 = w * index; + } else { + w2 = w * index; + x1 = x2 = w2; + } + rect.addElement(new Rectangle2D.Float(0, 0, w2, h)); + rect.addElement(new Rectangle2D.Float(w2, 0, w-w2, h)); + grad.addElement(new GradientPaint(0,0,c1,x1,0,c2)); + grad.addElement(new GradientPaint(x2,0,c2,w,0,c1)); + } else if ((type & HEI) != 0) { + float h2 = 0, y1 = 0, y2 = 0; + if ((type & SPL) != 0) { + h2 = h * 0.5f; + y1 = h * (1.0f - index); + y2 = h * index; + } else { + h2 = h * index; + y1 = y2 = h2; + } + rect.addElement(new Rectangle2D.Float(0, 0, w, h2)); + rect.addElement(new Rectangle2D.Float(0, h2, w, h-h2)); + grad.addElement(new GradientPaint(0,0,c1,0,y1,c2)); + grad.addElement(new GradientPaint(0,y2,c2,0,h,c1)); + } else if ((type & BUR) != 0) { + + float w2 = w/2; + float h2 = h/2; + + rect.addElement(new Rectangle2D.Float(0, 0, w2, h2)); + rect.addElement(new Rectangle2D.Float(w2, 0, w2, h2)); + rect.addElement(new Rectangle2D.Float(0, h2, w2, h2)); + rect.addElement(new Rectangle2D.Float(w2, h2, w2, h2)); + + float x1 = w * (1.0f - index); + float x2 = w * index; + float y1 = h * (1.0f - index); + float y2 = h * index; + + grad.addElement(new GradientPaint(0,0,c1,x1,y1,c2)); + grad.addElement(new GradientPaint(w,0,c1,x2,y1,c2)); + grad.addElement(new GradientPaint(0,h,c1,x1,y2,c2)); + grad.addElement(new GradientPaint(w,h,c1,x2,y2,c2)); + } else if ((type & NF) != 0) { + float x = w * index; + float y = h * index; + grad.addElement(new GradientPaint(0,0,c1,0,y,c2)); + } + + if ((type & INC) != 0 || (type & DEC) != 0) { + index += incr; + } + } + + + public void render(int w, int h, Graphics2D g2) { + g2.setRenderingHint(RenderingHints.KEY_ANTIALIASING, + RenderingHints.VALUE_ANTIALIAS_OFF); + for (int i = 0; i < grad.size(); i++) { + g2.setPaint((GradientPaint) grad.get(i)); + if ((type & NF) == 0) { + g2.fill((Rectangle2D) rect.get(i)); + } + } + g2.setRenderingHint(RenderingHints.KEY_ANTIALIASING, + RenderingHints.VALUE_ANTIALIAS_ON); + } + + public int getBegin() { + return beginning; + } + + public int getEnd() { + return ending; + } + } // End GpE class + + + + /** + * TexturePaint Effect. Expand and collapse a texture. + */ + static class TpE implements Part { + + static final int INC = 1; // increasing + static final int DEC = 2; // decreasing + static final int OVAL = 4; // oval + static final int RECT = 8; // rectangle + static final int HAF = 16; // half oval or rect size + static final int OI = OVAL | INC; + static final int OD = OVAL | DEC; + static final int RI = RECT | INC; + static final int RD = RECT | DEC; + static final int NF = 32; // no fill + private Paint p1, p2; + private int beginning, ending; + private float incr, index; + private TexturePaint texture; + private int type; + private int size; + private BufferedImage bimg; + private Rectangle rect; + + + public TpE(int type, Paint p1, Paint p2, int size, + int beg, int end) { + this.type = type; + this.p1 = p1; + this.p2 = p2; + this.beginning = beg; + this.ending = end; + setTextureSize(size); + } + + + public void setTextureSize(int size) { + this.size = size; + bimg = new BufferedImage(size,size,BufferedImage.TYPE_INT_RGB); + rect = new Rectangle(0,0,size,size); + } + + + public void reset(int w, int h) { + incr = (float) (size) / (float) (ending - beginning); + if ((type & HAF) != 0) { + incr /= 2; + } + if ((type & DEC) != 0) { + index = size; + if ((type & HAF) != 0) { + index /= 2; + } + incr = -incr; + } else { + index = 0.0f; + } + index += incr; + } + + + public void step(int w, int h) { + Graphics2D g2 = bimg.createGraphics(); + g2.setPaint(p1); + g2.fillRect(0,0,size,size); + g2.setPaint(p2); + if ((type & OVAL) != 0) { + g2.fill(new Ellipse2D.Float(0,0,index,index)); + } else if ((type & RECT) != 0) { + g2.fill(new Rectangle2D.Float(0,0,index,index)); + } + texture = new TexturePaint(bimg, rect); + g2.dispose(); + index += incr; + } + + + public void render(int w, int h, Graphics2D g2) { + g2.setPaint(texture); + if ((type & NF) == 0) { + g2.fillRect(0, 0, w, h); + } + } + + public int getBegin() { + return beginning; + } + + public int getEnd() { + return ending; + } + } // End TpE class + + + + /** + * Close out effect. Close out the buffered image with different + * geometry shapes. + */ + static class CoE implements Part { + + static final int WID = 1; + static final int HEI = 2; + static final int OVAL = 4; + static final int RECT = 8; + static final int RAND = 16; + static final int ARC = 32; + private int type; + private int beginning, ending; + private BufferedImage bimg; + private Shape shape; + private double zoom, extent; + private double zIncr, eIncr; + private boolean doRandom; + + + public CoE(int type, int beg, int end) { + this.type = type; + this.beginning = beg; + this.ending = end; + zIncr = -(2.0 / (ending - beginning)); + eIncr = 360.0 / (ending - beginning); + doRandom = (type & RAND) != 0; + } + + + public void reset(int w, int h) { + if (doRandom) { + int num = (int) (Math.random() * 5.0); + switch (num) { + case 0 : type = OVAL; break; + case 1 : type = RECT; break; + case 2 : type = RECT | WID; break; + case 3 : type = RECT | HEI; break; + case 4 : type = ARC; break; + default : type = OVAL; + } + } + shape = null; + bimg = null; + extent = 360.0; + zoom = 2.0; + } + + + public void step(int w, int h) { + if (bimg == null) { + int biw = Surface.bimg.getWidth(); + int bih = Surface.bimg.getHeight(); + bimg = new BufferedImage(biw, bih, BufferedImage.TYPE_INT_RGB); + Graphics2D big = bimg.createGraphics(); + big.drawImage(Surface.bimg, 0, 0, null); + } + double z = Math.min(w, h) * zoom; + if ((type & OVAL) != 0) { + shape = new Ellipse2D.Double(w/2-z/2,h/2-z/2,z,z); + } else if ((type & ARC) != 0) { + shape = new Arc2D.Double(-100,-100,w+200,h+200,90,extent,Arc2D.PIE); + extent -= eIncr; + } else if ((type & RECT) != 0) { + if ((type & WID) != 0) { + shape = new Rectangle2D.Double(w/2-z/2,0,z,h); + } else if ((type & HEI) != 0) { + shape = new Rectangle2D.Double(0,h/2-z/2,w,z); + } else { + shape = new Rectangle2D.Double(w/2-z/2,h/2-z/2,z,z); + } + } + zoom += zIncr; + } + + + public void render(int w, int h, Graphics2D g2) { + g2.clip(shape); + g2.drawImage(bimg, 0, 0, null); + } + + public int getBegin() { + return beginning; + } + + public int getEnd() { + return ending; + } + } // End CoE class + + + + /** + * Dither Dissolve Effect. For each successive step in the animation, + * a pseudo-random starting horizontal position is chosen using list, + * and then the corresponding points created from xlist and ylist are + * blacked out for the current "chunk". The x and y chunk starting + * positions are each incremented by the associated chunk size, and + * this process is repeated for the number of "steps" in the + * animation, causing an equal number of pseudo-randomly picked + * "blocks" to be blacked out during each step of the animation. + */ + static class DdE implements Part { + + private int beginning, ending; + private BufferedImage bimg; + private Graphics2D big; + private List list, xlist, ylist; + private int xeNum, yeNum; // element number + private int xcSize, ycSize; // chunk size + private int inc; + private int blocksize; + + + public DdE(int beg, int end, int blocksize) { + this.beginning = beg; + this.ending = end; + this.blocksize = blocksize; + } + + private void createShuffledLists() { + int width = bimg.getWidth(); + int height = bimg.getHeight(); + Integer xarray[] = new Integer[width]; + Integer yarray[] = new Integer[height]; + Integer array[] = new Integer[ending - beginning + 1]; + for (int i = 0; i < xarray.length; i++) { + xarray[i] = new Integer(i); + } + for (int j = 0; j < yarray.length; j++) { + yarray[j] = new Integer(j); + } + for (int k = 0; k < array.length; k++) { + array[k] = new Integer(k); + } + java.util.Collections.shuffle(xlist = Arrays.asList(xarray)); + java.util.Collections.shuffle(ylist = Arrays.asList(yarray)); + java.util.Collections.shuffle(list = Arrays.asList(array)); + } + + public void reset(int w, int h) { + bimg = null; + } + + public void step(int w, int h) { + if (bimg == null) { + int biw = Surface.bimg.getWidth(); + int bih = Surface.bimg.getHeight(); + bimg = new BufferedImage(biw, bih, BufferedImage.TYPE_INT_RGB); + createShuffledLists(); + big = bimg.createGraphics(); + big.drawImage(Surface.bimg, 0, 0, null); + xcSize = (xlist.size() / (ending - beginning)) + 1; + ycSize = (ylist.size() / (ending - beginning)) + 1; + xeNum = 0; + inc = 0; + } + xeNum = xcSize * ((Integer)list.get(inc)).intValue(); + yeNum = -ycSize; + inc++; + } + + + public void render(int w, int h, Graphics2D g2) { + big.setColor(black); + + for (int k = 0; k <= (ending - beginning); k++) { + if ((xeNum + xcSize) > xlist.size()) { + xeNum = 0; + } else { + xeNum += xcSize; + } + yeNum += ycSize; + + for (int i = xeNum; i < xeNum+xcSize && i < xlist.size(); i++) { + for (int j = yeNum; j < yeNum+ycSize && j < ylist.size(); j++) { + int xval = ((Integer)xlist.get(i)).intValue(); + int yval = ((Integer)ylist.get(j)).intValue(); + if (((xval % blocksize) == 0) && + ((yval % blocksize) == 0)) { + big.fillRect(xval, yval, blocksize, blocksize); + } + } + } + } + + g2.drawImage(bimg, 0, 0, null); + } + + public int getBegin() { + return beginning; + } + + public int getEnd() { + return ending; + } + } // End DdE class + + + /** + * Subimage effect. Subimage the scene's buffered + * image then rotate and scale down the subimages. + */ + static class SiE implements Part { + + private int beginning, ending; + private BufferedImage bimg; + private double rIncr, sIncr; + private double scale, rotate; + private int siw, sih; + private Vector subs = new Vector(20); + private Vector pts = new Vector(20); + + + public SiE(int siw, int sih, int beg, int end) { + this.siw = siw; + this.sih = sih; + this.beginning = beg; + this.ending = end; + rIncr = 360.0 / (ending - beginning); + sIncr = 1.0 / (ending - beginning); + } + + + public void reset(int w, int h) { + scale = 1.0; + rotate = 0.0; + bimg = null; + subs.clear(); + pts.clear(); + } + + + public void step(int w, int h) { + if (bimg == null) { + int biw = Surface.bimg.getWidth(); + int bih = Surface.bimg.getHeight(); + bimg = new BufferedImage(biw, bih, BufferedImage.TYPE_INT_RGB); + Graphics2D big = bimg.createGraphics(); + big.drawImage(Surface.bimg, 0, 0, null); + for (int x = 0; x < w && scale > 0.0; x+=siw) { + int ww = x+siw < w ? siw : w-x; + for (int y = 0; y < h; y+=sih) { + int hh = y+sih < h ? sih : h-y; + subs.addElement(bimg.getSubimage(x,y,ww,hh)); + pts.addElement(new Point(x, y)); + } + } + } + + rotate += rIncr; + scale -= sIncr; + } + + + public void render(int w, int h, Graphics2D g2) { + AffineTransform saveTx = g2.getTransform(); + g2.setColor(blue); + for (int i = 0; i < subs.size() && scale > 0.0; i++) { + BufferedImage bi = (BufferedImage) subs.get(i); + Point p = (Point) pts.get(i); + int ww = bi.getWidth(); + int hh = bi.getHeight(); + AffineTransform at = new AffineTransform(); + at.rotate(Math.toRadians(rotate), p.x+ww/2, p.y+hh/2); + at.translate(p.x, p.y); + at.scale(scale, scale); + + Rectangle b1 = new Rectangle(0, 0, ww, hh); + Shape shape = at.createTransformedShape(b1); + Rectangle2D b2 = shape.getBounds2D(); + double xx = (p.x+ww/2) - (b2.getX()+b2.getWidth()/2); + double yy = (p.y+hh/2) - (b2.getY()+b2.getHeight()/2); + AffineTransform toCenterAT = new AffineTransform(); + toCenterAT.translate(xx, yy); + toCenterAT.concatenate(at); + + g2.setTransform(toCenterAT); + g2.drawImage(bi, 0, 0, null); + g2.draw(b1); + } + g2.setTransform(saveTx); + } + + public int getBegin() { + return beginning; + } + + public int getEnd() { + return ending; + } + } // End SiE class + + + + + /** + * Line Effect. Flattened ellipse with lines from the center + * to the edge. Expand or collapse the ellipse. Fade in or out + * the lines. + */ + static class LnE implements Part { + + static final int INC = 1; + static final int DEC = 2; + static final int R = 4; // rotate + static final int RI = R | INC; + static final int RD = R | DEC; + static final int ZOOM = 8; // zoom + static final int ZOOMI = ZOOM | INC; + static final int ZOOMD = ZOOM | DEC; + static final int AC = 32; // AlphaComposite + static final int ACI = 32 | INC; + static final int ACD = 32 | DEC; + private int beginning, ending; + private double rIncr, rotate; + private double zIncr, zoom; + private Vector pts = new Vector(); + private float alpha, aIncr; + private int type; + + + public LnE(int type, int beg, int end) { + this.type = type; + this.beginning = beg; + this.ending = end; + rIncr = 360.0 / (ending - beginning); + aIncr = 0.9f / (ending - beginning); + zIncr = 2.0 / (ending - beginning); + if ((type & DEC) != 0) { + rIncr = -rIncr; + aIncr = -aIncr; + zIncr = -zIncr; + } + } + + + public void generatePts(int w, int h, double sizeF) { + pts.clear(); + double size = Math.min(w, h) * sizeF; + Ellipse2D ellipse = new Ellipse2D.Double(w/2-size/2,h/2-size/2,size,size); + PathIterator pi = ellipse.getPathIterator(null, 0.8); + while ( !pi.isDone() ) { + double[] pt = new double[6]; + switch ( pi.currentSegment(pt) ) { + case FlatteningPathIterator.SEG_MOVETO: + case FlatteningPathIterator.SEG_LINETO: + pts.addElement(new Point2D.Double(pt[0], pt[1])); + } + pi.next(); + } + } + + + public void reset(int w, int h) { + if ((type & DEC) != 0) { + rotate = 360; + alpha = 1.0f; + zoom = 2.0; + } else { + rotate = alpha = 0; + zoom = 0; + } + if ((type & ZOOM) == 0) { + generatePts(w, h, 0.5); + } + } + + + public void step(int w, int h) { + if ((type & ZOOM) != 0) { + generatePts(w, h, zoom += zIncr); + } + if ((type & RI) != 0 || (type & RI) != 0) { + rotate += rIncr; + } + if ((type & ACI) != 0 || (type & ACD) != 0) { + alpha += aIncr; + } + } + + + public void render(int w, int h, Graphics2D g2) { + Composite saveAC = null; + if ((type & AC) != 0 && alpha >= 0 && alpha <= 1) { + saveAC = g2.getComposite(); + g2.setComposite(AlphaComposite.getInstance(AlphaComposite.SRC_OVER, alpha)); + } + AffineTransform saveTx = null; + if ((type & R) != 0) { + saveTx = g2.getTransform(); + AffineTransform at = new AffineTransform(); + at.rotate(Math.toRadians(rotate), w/2, h/2); + g2.setTransform(at); + } + Point2D p1 = new Point2D.Double(w/2, h/2); + g2.setColor(Color.yellow); + for (int i = 0; i < pts.size()-1; i++) { + g2.draw(new Line2D.Float(p1, (Point2D) pts.get(i))); + } + if (saveTx != null) { + g2.setTransform(saveTx); + } + if (saveAC != null) { + g2.setComposite(saveAC); + } + } + + public int getBegin() { + return beginning; + } + + public int getEnd() { + return ending; + } + } // End LnE class + + + + /** + * Template for Features & Contributors consisting of translating + * blue and red rectangles and an image going from transparent to + * opaque. + */ + static class Temp implements Part { + static final int NOANIM = 1; + static final int RECT = 2; + static final int RNA = RECT | NOANIM; + static final int IMG = 4; + static final int INA = IMG | NOANIM; + private int beginning, ending; + private float alpha, aIncr; + private int type; + private Rectangle rect1, rect2; + private int x, y, xIncr, yIncr; + private Image img; + + + public Temp(int type, Image img, int beg, int end) { + this.type = type; + this.img = img; + this.beginning = beg; + this.ending = end; + aIncr = 0.9f / (ending - beginning); + if ((type & NOANIM) != 0) { + alpha = 1.0f; + } + } + + + + public void reset(int w, int h) { + rect1 = new Rectangle(8, 20, w-20, 30); + rect2 = new Rectangle(20, 8, 30, h-20); + if ((type & NOANIM) == 0) { + alpha = 0.0f; + xIncr = w / (ending - beginning); + yIncr = h / (ending - beginning); + x = w+(int)(xIncr*1.4); + y = h+(int)(yIncr*1.4); + } + } + + + public void step(int w, int h) { + if ((type & NOANIM) != 0) { + return; + } + if ((type & RECT) != 0) { + rect1.setLocation(x-=xIncr, 20); + rect2.setLocation(20, y-=yIncr); + } + if ((type & IMG) != 0) { + alpha += aIncr; + } + } + + + public void render(int w, int h, Graphics2D g2) { + if ((type & RECT) != 0) { + g2.setColor(blue); + g2.fill(rect1); + g2.setColor(red); + g2.fill(rect2); + } + if ((type & IMG) != 0) { + Composite saveAC = g2.getComposite(); + if (alpha >= 0 && alpha <= 1) { + g2.setComposite(AlphaComposite.getInstance(AlphaComposite.SRC_OVER, alpha)); + } + g2.drawImage(img, 30, 30, null); + g2.setComposite(saveAC); + } + } + + public int getBegin() { + return beginning; + } + + public int getEnd() { + return ending; + } + } // End Temp class + + + + /** + * Features of Java2D. Single character advancement effect. + */ + static class Features implements Part { + + static final int GRAPHICS = 0; + static final int TEXT = 1; + static final int IMAGES = 2; + static final int COLOR = 3; + static Font font1 = new Font("serif", Font.BOLD, 38); + static Font font2 = new Font("serif", Font.PLAIN, 24); + static FontMetrics fm1 = Surface.getMetrics(font1); + static FontMetrics fm2 = Surface.getMetrics(font2); + static String table[][] = + {{ "Graphics", "Antialiased rendering", "Bezier paths", + "Transforms", "Compositing", "Stroking parameters" }, + { "Text", "Extended font support", + "Advanced text layout", "Dynamic font loading", + "AttributeSets for font customization" }, + { "Images", "Flexible image layouts", + "Extended imaging operations", + " Convolutions, Lookup Tables", + "RenderableImage interface"}, + { "Color", "ICC profile support", "Color conversion", + "Arbitrary color spaces"} }; + private String list[]; + private int beginning, ending; + private int strH; + private int endIndex, listIndex; + private Vector v = new Vector(); + + + public Features(int type, int beg, int end) { + list = table[type]; + this.beginning = beg; + this.ending = end; + } + + + public void reset(int w, int h) { + strH = (int) (fm2.getAscent()+fm2.getDescent()); + endIndex = 1; + listIndex = 0; + v.clear(); + v.addElement(list[listIndex].substring(0,endIndex)); + } + + + public void step(int w, int h) { + if (listIndex < list.length) { + if (++endIndex > list[listIndex].length()) { + if (++listIndex < list.length) { + endIndex = 1; + v.addElement(list[listIndex].substring(0,endIndex)); + } + } else { + v.set(listIndex, list[listIndex].substring(0,endIndex)); + } + } + } + + + public void render(int w, int h, Graphics2D g2) { + g2.setColor(white); + g2.setFont(font1); + g2.drawString((String) v.get(0), 90, 85); + g2.setFont(font2); + for (int i = 1, y = 90; i < v.size(); i++) { + g2.drawString((String) v.get(i), 120, y += strH); + } + } + + public int getBegin() { + return beginning; + } + + public int getEnd() { + return ending; + } + } // End Features class + + + + /** + * Scrolling text of Java2D contributors. + */ + static class Contributors implements Part { + + static String members[] = + { + "Brian Lichtenwalter", "Jeannette Hung", + "Thanh Nguyen", "Jim Graham", "Jerry Evans", + "John Raley", "Michael Peirce", "Robert Kim", + "Jennifer Ball", "Deborah Adair", "Paul Charlton", + "Dmitry Feld", "Gregory Stone", "Richard Blanchard", + "Link Perry", "Phil Race", "Vincent Hardy", + "Parry Kejriwal", "Doug Felt", "Rekha Rangarajan", + "Paula Patel", "Michael Bundschuh", "Joe Warzecha", + "Joey Beheler", "Aastha Bhardwaj", "Daniel Rice", + "Chris Campbell", "Shinsuke Fukuda", "Dmitri Trembovetski", + "Chet Haase", "Jennifer Godinez", "Nicholas Talian", + "Raul Vera", "Ankit Patel", "Ilya Bagrak" + }; + static Font font = new Font("serif", Font.PLAIN, 26); + static FontMetrics fm = Surface.getMetrics(font); + private int beginning, ending; + private int nStrs, strH, index, yh, height; + private Vector v = new Vector(); + private Vector cast = new Vector(members.length+3); + private int counter, cntMod; + private GradientPaint gp; + + + public Contributors(int beg, int end) { + this.beginning = beg; + this.ending = end; + java.util.Arrays.sort(members); + cast.addElement("CONTRIBUTORS"); + cast.addElement(" "); + for (int i = 0; i < members.length; i++) { + cast.addElement(members[i]); + } + cast.addElement(" "); cast.addElement(" "); + cntMod = (ending - beginning) / cast.size() - 1; + } + + + public void reset(int w, int h) { + v.clear(); + strH = (int) (fm.getAscent()+fm.getDescent()); + nStrs = (h-40)/strH + 1; + height = strH * (nStrs-1) + 48; + index = 0; + gp = new GradientPaint(0,h/2,Color.white,0,h+20,Color.black); + counter = 0; + } + + + public void step(int w, int h) { + if (counter++%cntMod == 0) { + if (index < cast.size()) { + v.addElement(cast.get(index)); + } + if ((v.size() == nStrs || index >= cast.size()) && v.size() != 0) { + v.removeElementAt(0); + } + ++index; + } + } + + + public void render(int w, int h, Graphics2D g2) { + g2.setPaint(gp); + g2.setFont(font); + double remainder = counter%cntMod; + double incr = 1.0-remainder/cntMod; + incr = incr == 1.0 ? 0 : incr; + int y = (int) (incr * strH); + + if (index >= cast.size()) { + y = yh + y; + } else { + y = yh = height - v.size() * strH + y; + } + for (int i = 0; i < v.size(); i++) { + String s = (String) v.get(i); + g2.drawString(s, w/2-fm.stringWidth(s)/2, y += strH); + } + } + + public int getBegin() { + return beginning; + } + + public int getEnd() { + return ending; + } + } // End Contributors class + + } // End Surface class +} // End Intro class Added: external/Pygments-0.8.1/tests/examplefiles/Makefile ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/Makefile Thu Aug 9 17:43:13 2007 @@ -0,0 +1,1131 @@ +# Generated automatically from Makefile.pre by makesetup. +# Top-level Makefile for Python +# +# As distributed, this file is called Makefile.pre.in; it is processed +# into the real Makefile by running the script ./configure, which +# replaces things like @spam@ with values appropriate for your system. +# This means that if you edit Makefile, your changes get lost the next +# time you run the configure script. Ideally, you can do: +# +# ./configure +# make +# make test +# make install +# +# If you have a previous version of Python installed that you don't +# want to overwrite, you can use "make altinstall" instead of "make +# install". Refer to the "Installing" section in the README file for +# additional details. +# +# See also the section "Build instructions" in the README file. + +# === Variables set by makesetup === + +MODOBJS= Modules/threadmodule.o Modules/signalmodule.o Modules/posixmodule.o Modules/errnomodule.o Modules/pwdmodule.o Modules/_sre.o Modules/_codecsmodule.o Modules/zipimport.o Modules/symtablemodule.o Modules/xxsubtype.o +MODLIBS= $(LOCALMODLIBS) $(BASEMODLIBS) + +# === Variables set by configure +VERSION= 2.6 +srcdir= . + + +CC= gcc -pthread +CXX= g++ -pthread +MAINCC= $(CC) +LINKCC= $(PURIFY) $(MAINCC) +AR= ar +RANLIB= ranlib +SVNVERSION= svnversion $(srcdir) + +# Shell used by make (some versions default to the login shell, which is bad) +SHELL= /bin/sh + +# Use this to make a link between python$(VERSION) and python in $(BINDIR) +LN= ln + +# Portable install script (configure doesn't always guess right) +INSTALL= /usr/bin/install -c +INSTALL_PROGRAM=${INSTALL} +INSTALL_SCRIPT= ${INSTALL} +INSTALL_DATA= ${INSTALL} -m 644 +# Shared libraries must be installed with executable mode on some systems; +# rather than figuring out exactly which, we always give them executable mode. +# Also, making them read-only seems to be a good idea... +INSTALL_SHARED= ${INSTALL} -m 555 + +MAKESETUP= $(srcdir)/Modules/makesetup + +# Compiler options +OPT= -g -Wall -Wstrict-prototypes +BASECFLAGS= -fno-strict-aliasing +CFLAGS= $(BASECFLAGS) $(OPT) $(EXTRA_CFLAGS) +# Both CPPFLAGS and LDFLAGS need to contain the shell's value for setup.py to +# be able to build extension modules using the directories specified in the +# environment variables +CPPFLAGS= -I. -I$(srcdir)/Include +LDFLAGS= +LDLAST= +SGI_ABI= +CCSHARED= -fPIC +LINKFORSHARED= -Xlinker -export-dynamic +# Extra C flags added for building the interpreter object files. +CFLAGSFORSHARED= +# C flags used for building the interpreter object files +PY_CFLAGS= $(CFLAGS) $(CPPFLAGS) $(CFLAGSFORSHARED) -DPy_BUILD_CORE + + +# Machine-dependent subdirectories +MACHDEP= linux2 + +# Install prefix for architecture-independent files +prefix= /usr/local + +# Install prefix for architecture-dependent files +exec_prefix= ${prefix} + +# Expanded directories +BINDIR= $(exec_prefix)/bin +LIBDIR= $(exec_prefix)/lib +MANDIR= ${prefix}/man +INCLUDEDIR= ${prefix}/include +CONFINCLUDEDIR= $(exec_prefix)/include +SCRIPTDIR= $(prefix)/lib + +# Detailed destination directories +BINLIBDEST= $(LIBDIR)/python$(VERSION) +LIBDEST= $(SCRIPTDIR)/python$(VERSION) +INCLUDEPY= $(INCLUDEDIR)/python$(VERSION) +CONFINCLUDEPY= $(CONFINCLUDEDIR)/python$(VERSION) +LIBP= $(LIBDIR)/python$(VERSION) + +# Symbols used for using shared libraries +SO= .so +LDSHARED= $(CC) -shared +BLDSHARED= $(CC) -shared +DESTSHARED= $(BINLIBDEST)/lib-dynload + +# Executable suffix (.exe on Windows and Mac OS X) +EXE= +BUILDEXE= + +# Short name and location for Mac OS X Python framework +UNIVERSALSDK= +PYTHONFRAMEWORK= +PYTHONFRAMEWORKDIR= no-framework +PYTHONFRAMEWORKPREFIX= +PYTHONFRAMEWORKINSTALLDIR= +# Deployment target selected during configure, to be checked +# by distutils. The export statement is needed to ensure that the +# deployment target is active during build. +MACOSX_DEPLOYMENT_TARGET= +#export MACOSX_DEPLOYMENT_TARGET + +# Options to enable prebinding (for fast startup prior to Mac OS X 10.3) +OTHER_LIBTOOL_OPT= + +# Environment to run shared python without installed libraries +RUNSHARED= + +# Modes for directories, executables and data files created by the +# install process. Default to user-only-writable for all file types. +DIRMODE= 755 +EXEMODE= 755 +FILEMODE= 644 + +# configure script arguments +CONFIG_ARGS= '--with-pydebug' + + +# Subdirectories with code +SRCDIRS= Parser Grammar Objects Python Modules Mac + +# Other subdirectories +SUBDIRSTOO= Include Lib Misc Demo + +# Files and directories to be distributed +CONFIGFILES= configure configure.in acconfig.h pyconfig.h.in Makefile.pre.in +DISTFILES= README ChangeLog $(CONFIGFILES) +DISTDIRS= $(SUBDIRS) $(SUBDIRSTOO) Ext-dummy +DIST= $(DISTFILES) $(DISTDIRS) + + +LIBRARY= libpython$(VERSION).a +LDLIBRARY= libpython$(VERSION).a +BLDLIBRARY= $(LDLIBRARY) +DLLLIBRARY= +LDLIBRARYDIR= +INSTSONAME= $(LDLIBRARY) + + +LIBS= -lpthread -ldl -lutil +LIBM= -lm +LIBC= +SYSLIBS= $(LIBM) $(LIBC) +SHLIBS= $(LIBS) + +THREADOBJ= Python/thread.o +DLINCLDIR= . +DYNLOADFILE= dynload_shlib.o +MACHDEP_OBJS= +UNICODE_OBJS= Objects/unicodeobject.o Objects/unicodectype.o + +PYTHON= python$(EXE) +BUILDPYTHON= python$(BUILDEXE) + +# === Definitions added by makesetup === + +LOCALMODLIBS= +BASEMODLIBS= +GLHACK=-Dclear=__GLclear +PYTHONPATH=$(COREPYTHONPATH) +COREPYTHONPATH=$(DESTPATH)$(SITEPATH)$(TESTPATH)$(MACHDEPPATH)$(EXTRAMACHDEPPATH)$(TKPATH) +TKPATH=:lib-tk +EXTRAMACHDEPPATH= +MACHDEPPATH=:plat-$(MACHDEP) +TESTPATH= +SITEPATH= +DESTPATH= +MACHDESTLIB=$(BINLIBDEST) +DESTLIB=$(LIBDEST) + + + +########################################################################## +# Modules +MODULE_OBJS= \ + Modules/config.o \ + Modules/getpath.o \ + Modules/main.o \ + Modules/gcmodule.o + +# Used of signalmodule.o is not available +SIGNAL_OBJS= + + +########################################################################## +# Grammar +GRAMMAR_H= $(srcdir)/Include/graminit.h +GRAMMAR_C= $(srcdir)/Python/graminit.c +GRAMMAR_INPUT= $(srcdir)/Grammar/Grammar + + +########################################################################## +# Parser +PGEN= Parser/pgen$(EXE) + +POBJS= \ + Parser/acceler.o \ + Parser/grammar1.o \ + Parser/listnode.o \ + Parser/node.o \ + Parser/parser.o \ + Parser/parsetok.o \ + Parser/bitset.o \ + Parser/metagrammar.o \ + Parser/firstsets.o \ + Parser/grammar.o \ + Parser/pgen.o + +PARSER_OBJS= $(POBJS) Parser/myreadline.o Parser/tokenizer.o + +PGOBJS= \ + Objects/obmalloc.o \ + Python/mysnprintf.o \ + Parser/tokenizer_pgen.o \ + Parser/printgrammar.o \ + Parser/pgenmain.o + +PGENOBJS= $(PGENMAIN) $(POBJS) $(PGOBJS) + +########################################################################## +# AST +AST_H_DIR= $(srcdir)/Include +AST_H= $(AST_H_DIR)/Python-ast.h +AST_C_DIR= $(srcdir)/Python +AST_C= $(AST_C_DIR)/Python-ast.c +AST_ASDL= $(srcdir)/Parser/Python.asdl + +ASDLGEN_FILES= $(srcdir)/Parser/asdl.py $(srcdir)/Parser/asdl_c.py +# XXX Note that a build now requires Python exist before the build starts +ASDLGEN= $(srcdir)/Parser/asdl_c.py + +########################################################################## +# Python +PYTHON_OBJS= \ + Python/Python-ast.o \ + Python/asdl.o \ + Python/ast.o \ + Python/bltinmodule.o \ + Python/ceval.o \ + Python/compile.o \ + Python/codecs.o \ + Python/errors.o \ + Python/frozen.o \ + Python/frozenmain.o \ + Python/future.o \ + Python/getargs.o \ + Python/getcompiler.o \ + Python/getcopyright.o \ + Python/getmtime.o \ + Python/getplatform.o \ + Python/getversion.o \ + Python/graminit.o \ + Python/import.o \ + Python/importdl.o \ + Python/marshal.o \ + Python/modsupport.o \ + Python/mystrtoul.o \ + Python/mysnprintf.o \ + Python/peephole.o \ + Python/pyarena.o \ + Python/pyfpe.o \ + Python/pystate.o \ + Python/pythonrun.o \ + Python/structmember.o \ + Python/symtable.o \ + Python/sysmodule.o \ + Python/traceback.o \ + Python/getopt.o \ + Python/pystrtod.o \ + Python/$(DYNLOADFILE) \ + $(MACHDEP_OBJS) \ + $(THREADOBJ) + + +########################################################################## +# Objects +OBJECT_OBJS= \ + Objects/abstract.o \ + Objects/boolobject.o \ + Objects/bufferobject.o \ + Objects/cellobject.o \ + Objects/classobject.o \ + Objects/cobject.o \ + Objects/codeobject.o \ + Objects/complexobject.o \ + Objects/descrobject.o \ + Objects/enumobject.o \ + Objects/exceptions.o \ + Objects/genobject.o \ + Objects/fileobject.o \ + Objects/floatobject.o \ + Objects/frameobject.o \ + Objects/funcobject.o \ + Objects/intobject.o \ + Objects/iterobject.o \ + Objects/listobject.o \ + Objects/longobject.o \ + Objects/dictobject.o \ + Objects/methodobject.o \ + Objects/moduleobject.o \ + Objects/object.o \ + Objects/obmalloc.o \ + Objects/rangeobject.o \ + Objects/setobject.o \ + Objects/sliceobject.o \ + Objects/stringobject.o \ + Objects/structseq.o \ + Objects/tupleobject.o \ + Objects/typeobject.o \ + Objects/weakrefobject.o \ + $(UNICODE_OBJS) + + +########################################################################## +# objects that get linked into the Python library +LIBRARY_OBJS= \ + Modules/_typesmodule.o \ + Modules/getbuildinfo.o \ + $(PARSER_OBJS) \ + $(OBJECT_OBJS) \ + $(PYTHON_OBJS) \ + $(MODULE_OBJS) \ + $(SIGNAL_OBJS) \ + $(MODOBJS) + +######################################################################### +# Rules + +# Default target +all: $(BUILDPYTHON) oldsharedmods sharedmods + +# Build the interpreter +$(BUILDPYTHON): Modules/python.o $(LIBRARY) $(LDLIBRARY) + $(LINKCC) $(LDFLAGS) $(LINKFORSHARED) -o $@ \ + Modules/python.o \ + $(BLDLIBRARY) $(LIBS) $(MODLIBS) $(SYSLIBS) $(LDLAST) + +platform: $(BUILDPYTHON) + $(RUNSHARED) ./$(BUILDPYTHON) -E -c 'import sys ; from distutils.util import get_platform ; print get_platform()+"-"+sys.version[0:3]' >platform + + +# Build the shared modules +sharedmods: $(BUILDPYTHON) + @case $$MAKEFLAGS in \ + *-s*) $(RUNSHARED) CC='$(CC)' LDSHARED='$(BLDSHARED)' OPT='$(OPT)' ./$(BUILDPYTHON) -E $(srcdir)/setup.py -q build;; \ + *) $(RUNSHARED) CC='$(CC)' LDSHARED='$(BLDSHARED)' OPT='$(OPT)' ./$(BUILDPYTHON) -E $(srcdir)/setup.py build;; \ + esac + +# Build static library +# avoid long command lines, same as LIBRARY_OBJS +$(LIBRARY): $(LIBRARY_OBJS) + -rm -f $@ + $(AR) cr $@ Modules/getbuildinfo.o + $(AR) cr $@ Modules/_typesmodule.o + $(AR) cr $@ $(PARSER_OBJS) + $(AR) cr $@ $(OBJECT_OBJS) + $(AR) cr $@ $(PYTHON_OBJS) + $(AR) cr $@ $(MODULE_OBJS) $(SIGNAL_OBJS) + $(AR) cr $@ $(MODOBJS) + $(RANLIB) $@ + +libpython$(VERSION).so: $(LIBRARY_OBJS) + if test $(INSTSONAME) != $(LDLIBRARY); then \ + $(LDSHARED) -Wl,-h$(INSTSONAME) -o $(INSTSONAME) $(LIBRARY_OBJS) $(SHLIBS) $(LIBC) $(LIBM); \ + $(LN) -f $(INSTSONAME) $@; \ + else\ + $(LDSHARED) -o $@ $(LIBRARY_OBJS) $(SHLIBS) $(LIBC) $(LIBM); \ + fi + +libpython$(VERSION).sl: $(LIBRARY_OBJS) + $(LDSHARED) -o $@ $(LIBRARY_OBJS) $(SHLIBS) $(LIBC) $(LIBM) + +# This rule is here for OPENSTEP/Rhapsody/MacOSX. It builds a temporary +# minimal framework (not including the Lib directory and such) in the current +# directory. +RESSRCDIR=$(srcdir)/Mac/Resources/framework +$(PYTHONFRAMEWORKDIR)/Versions/$(VERSION)/$(PYTHONFRAMEWORK): \ + $(LIBRARY) \ + $(RESSRCDIR)/Info.plist \ + $(RESSRCDIR)/version.plist \ + $(RESSRCDIR)/English.lproj/InfoPlist.strings + $(INSTALL) -d -m $(DIRMODE) $(PYTHONFRAMEWORKDIR)/Versions/$(VERSION) + if test "${UNIVERSALSDK}"; then \ + $(CC) -o $(LDLIBRARY) -arch i386 -arch ppc -dynamiclib \ + -isysroot "${UNIVERSALSDK}" \ + -all_load $(LIBRARY) -Wl,-single_module \ + -install_name $(DESTDIR)$(PYTHONFRAMEWORKINSTALLDIR)/Versions/$(VERSION)/Python \ + -compatibility_version $(VERSION) \ + -current_version $(VERSION); \ + else \ + libtool -o $(LDLIBRARY) -dynamic $(OTHER_LIBTOOL_OPT) $(LIBRARY) \ + ;\ + fi + $(INSTALL) -d -m $(DIRMODE) \ + $(PYTHONFRAMEWORKDIR)/Versions/$(VERSION)/Resources/English.lproj + $(INSTALL_DATA) $(RESSRCDIR)/Info.plist \ + $(PYTHONFRAMEWORKDIR)/Versions/$(VERSION)/Resources/Info.plist + $(INSTALL_DATA) $(RESSRCDIR)/version.plist \ + $(PYTHONFRAMEWORKDIR)/Versions/$(VERSION)/Resources/version.plist + $(INSTALL_DATA) $(RESSRCDIR)/English.lproj/InfoPlist.strings \ + $(PYTHONFRAMEWORKDIR)/Versions/$(VERSION)/Resources/English.lproj/InfoPlist.strings + $(LN) -fsn $(VERSION) $(PYTHONFRAMEWORKDIR)/Versions/Current + $(LN) -fsn Versions/Current/$(PYTHONFRAMEWORK) $(PYTHONFRAMEWORKDIR)/$(PYTHONFRAMEWORK) + $(LN) -fsn Versions/Current/Headers $(PYTHONFRAMEWORKDIR)/Headers + $(LN) -fsn Versions/Current/Resources $(PYTHONFRAMEWORKDIR)/Resources + +# This rule builds the Cygwin Python DLL and import library if configured +# for a shared core library; otherwise, this rule is a noop. +$(DLLLIBRARY) libpython$(VERSION).dll.a: $(LIBRARY_OBJS) + if test -n "$(DLLLIBRARY)"; then \ + $(LDSHARED) -Wl,--out-implib=$@ -o $(DLLLIBRARY) $^ \ + $(LIBS) $(MODLIBS) $(SYSLIBS); \ + else true; \ + fi + + +oldsharedmods: $(SHAREDMODS) + + +Makefile Modules/config.c: Makefile.pre \ + $(srcdir)/Modules/config.c.in \ + $(MAKESETUP) \ + Modules/Setup.config \ + Modules/Setup \ + Modules/Setup.local + $(SHELL) $(MAKESETUP) -c $(srcdir)/Modules/config.c.in \ + -s Modules \ + Modules/Setup.config \ + Modules/Setup.local \ + Modules/Setup + @mv config.c Modules + @echo "The Makefile was updated, you may need to re-run make." + + +Modules/Setup: $(srcdir)/Modules/Setup.dist + @if test -f Modules/Setup; then \ + echo "-----------------------------------------------"; \ + echo "Modules/Setup.dist is newer than Modules/Setup;"; \ + echo "check to make sure you have all the updates you"; \ + echo "need in your Modules/Setup file."; \ + echo "Usually, copying Setup.dist to Setup will work."; \ + echo "-----------------------------------------------"; \ + fi + +############################################################################ +# Special rules for object files + +Modules/getbuildinfo.o: $(PARSER_OBJS) \ + $(OBJECT_OBJS) \ + $(PYTHON_OBJS) \ + $(MODULE_OBJS) \ + $(SIGNAL_OBJS) \ + $(MODOBJS) \ + $(srcdir)/Modules/getbuildinfo.c + $(CC) -c $(PY_CFLAGS) -DSVNVERSION=\"`LC_ALL=C $(SVNVERSION)`\" -o $@ $(srcdir)/Modules/getbuildinfo.c + +Modules/getpath.o: $(srcdir)/Modules/getpath.c Makefile + $(CC) -c $(PY_CFLAGS) -DPYTHONPATH='"$(PYTHONPATH)"' \ + -DPREFIX='"$(prefix)"' \ + -DEXEC_PREFIX='"$(exec_prefix)"' \ + -DVERSION='"$(VERSION)"' \ + -DVPATH='"$(VPATH)"' \ + -o $@ $(srcdir)/Modules/getpath.c + +Modules/python.o: $(srcdir)/Modules/python.c + $(MAINCC) -c $(PY_CFLAGS) -o $@ $(srcdir)/Modules/python.c + + +$(GRAMMAR_H) $(GRAMMAR_C): $(PGEN) $(GRAMMAR_INPUT) + -$(PGEN) $(GRAMMAR_INPUT) $(GRAMMAR_H) $(GRAMMAR_C) + +$(PGEN): $(PGENOBJS) + $(CC) $(OPT) $(LDFLAGS) $(PGENOBJS) $(LIBS) -o $(PGEN) + +Parser/grammar.o: $(srcdir)/Parser/grammar.c \ + $(srcdir)/Include/token.h \ + $(srcdir)/Include/grammar.h +Parser/metagrammar.o: $(srcdir)/Parser/metagrammar.c + +Parser/tokenizer_pgen.o: $(srcdir)/Parser/tokenizer.c + +Parser/pgenmain.o: $(srcdir)/Include/parsetok.h + +$(AST_H): $(AST_ASDL) $(ASDLGEN_FILES) + $(ASDLGEN) -h $(AST_H_DIR) $(AST_ASDL) + +$(AST_C): $(AST_ASDL) $(ASDLGEN_FILES) + $(ASDLGEN) -c $(AST_C_DIR) $(AST_ASDL) + +Python/compile.o Python/symtable.o: $(GRAMMAR_H) $(AST_H) + +Python/getplatform.o: $(srcdir)/Python/getplatform.c + $(CC) -c $(PY_CFLAGS) -DPLATFORM='"$(MACHDEP)"' -o $@ $(srcdir)/Python/getplatform.c + +Python/importdl.o: $(srcdir)/Python/importdl.c + $(CC) -c $(PY_CFLAGS) -I$(DLINCLDIR) -o $@ $(srcdir)/Python/importdl.c + +Objects/unicodectype.o: $(srcdir)/Objects/unicodectype.c \ + $(srcdir)/Objects/unicodetype_db.h + +############################################################################ +# Header files + +PYTHON_HEADERS= \ + Include/Python.h \ + Include/Python-ast.h \ + Include/asdl.h \ + Include/abstract.h \ + Include/boolobject.h \ + Include/bufferobject.h \ + Include/ceval.h \ + Include/classobject.h \ + Include/cobject.h \ + Include/code.h \ + Include/codecs.h \ + Include/compile.h \ + Include/complexobject.h \ + Include/descrobject.h \ + Include/dictobject.h \ + Include/enumobject.h \ + Include/genobject.h \ + Include/fileobject.h \ + Include/floatobject.h \ + Include/funcobject.h \ + Include/import.h \ + Include/intobject.h \ + Include/intrcheck.h \ + Include/iterobject.h \ + Include/listobject.h \ + Include/longobject.h \ + Include/methodobject.h \ + Include/modsupport.h \ + Include/moduleobject.h \ + Include/object.h \ + Include/objimpl.h \ + Include/parsetok.h \ + Include/patchlevel.h \ + Include/pyarena.h \ + Include/pydebug.h \ + Include/pyerrors.h \ + Include/pyfpe.h \ + Include/pymem.h \ + Include/pyport.h \ + Include/pystate.h \ + Include/pythonrun.h \ + Include/rangeobject.h \ + Include/setobject.h \ + Include/sliceobject.h \ + Include/stringobject.h \ + Include/structseq.h \ + Include/structmember.h \ + Include/symtable.h \ + Include/sysmodule.h \ + Include/traceback.h \ + Include/tupleobject.h \ + Include/unicodeobject.h \ + Include/weakrefobject.h \ + pyconfig.h + +$(LIBRARY_OBJS) $(MODOBJS) Modules/python.o: $(PYTHON_HEADERS) + + +###################################################################### + +# Test the interpreter (twice, once without .pyc files, once with) +# In the past, we've had problems where bugs in the marshalling or +# elsewhere caused bytecode read from .pyc files to behave differently +# than bytecode generated directly from a .py source file. Sometimes +# the bytecode read from a .pyc file had the bug, somtimes the directly +# generated bytecode. This is sometimes a very shy bug needing a lot of +# sample data. + +TESTOPTS= -l $(EXTRATESTOPTS) +TESTPROG= $(srcdir)/Lib/test/regrtest.py +TESTPYTHON= $(RUNSHARED) ./$(BUILDPYTHON) -E -tt +test: all platform + -find $(srcdir)/Lib -name '*.py[co]' -print | xargs rm -f + -$(TESTPYTHON) $(TESTPROG) $(TESTOPTS) + $(TESTPYTHON) $(TESTPROG) $(TESTOPTS) + +testall: all platform + -find $(srcdir)/Lib -name '*.py[co]' -print | xargs rm -f + -$(TESTPYTHON) $(TESTPROG) $(TESTOPTS) -uall + $(TESTPYTHON) $(TESTPROG) $(TESTOPTS) -uall + +# Run the unitests for both architectures in a Universal build on OSX +# Must be run on an Intel box. +testuniversal: all platform + if [ `arch` != 'i386' ];then \ + echo "This can only be used on OSX/i386" ;\ + exit 1 ;\ + fi + -find $(srcdir)/Lib -name '*.py[co]' -print | xargs rm -f + -$(TESTPYTHON) $(TESTPROG) $(TESTOPTS) -uall + $(TESTPYTHON) $(TESTPROG) $(TESTOPTS) -uall + $(RUNSHARED) /usr/libexec/oah/translate ./$(BUILDPYTHON) -E -tt $(TESTPROG) $(TESTOPTS) -uall + + +# Like testall, but with a single pass only +buildbottest: all platform + $(TESTPYTHON) $(TESTPROG) $(TESTOPTS) -uall -rw + +QUICKTESTOPTS= $(TESTOPTS) -x test_thread test_signal test_strftime \ + test_unicodedata test_re test_sre test_select test_poll \ + test_linuxaudiodev test_struct test_sunaudiodev test_zlib +quicktest: all platform + -find $(srcdir)/Lib -name '*.py[co]' -print | xargs rm -f + -$(TESTPYTHON) $(TESTPROG) $(QUICKTESTOPTS) + $(TESTPYTHON) $(TESTPROG) $(QUICKTESTOPTS) + +MEMTESTOPTS= $(QUICKTESTOPTS) -x test_dl test___all__ test_fork1 \ + test_longexp +memtest: all platform + -rm -f $(srcdir)/Lib/test/*.py[co] + -$(TESTPYTHON) $(TESTPROG) $(MEMTESTOPTS) + $(TESTPYTHON) $(TESTPROG) $(MEMTESTOPTS) + +# Install everything +install: altinstall bininstall maninstall + +# Install almost everything without disturbing previous versions +altinstall: altbininstall libinstall inclinstall libainstall \ + sharedinstall oldsharedinstall + +# Install shared libraries enabled by Setup +DESTDIRS= $(exec_prefix) $(LIBDIR) $(BINLIBDEST) $(DESTSHARED) + +oldsharedinstall: $(DESTSHARED) $(SHAREDMODS) + @for i in X $(SHAREDMODS); do \ + if test $$i != X; then \ + echo $(INSTALL_SHARED) $$i $(DESTSHARED)/`basename $$i`; \ + $(INSTALL_SHARED) $$i $(DESTDIR)$(DESTSHARED)/`basename $$i`; \ + fi; \ + done + +$(DESTSHARED): + @for i in $(DESTDIRS); \ + do \ + if test ! -d $(DESTDIR)$$i; then \ + echo "Creating directory $$i"; \ + $(INSTALL) -d -m $(DIRMODE) $(DESTDIR)$$i; \ + else true; \ + fi; \ + done + + +# Install the interpreter (by creating a hard link to python$(VERSION)) +bininstall: altbininstall + -if test -f $(DESTDIR)$(BINDIR)/$(PYTHON) -o -h $(DESTDIR)$(BINDIR)/$(PYTHON); \ + then rm -f $(DESTDIR)$(BINDIR)/$(PYTHON); \ + else true; \ + fi + (cd $(DESTDIR)$(BINDIR); $(LN) python$(VERSION)$(EXE) $(PYTHON)) + (cd $(DESTDIR)$(BINDIR); $(LN) -sf python$(VERSION)-config python-config) + +# Install the interpreter with $(VERSION) affixed +# This goes into $(exec_prefix) +altbininstall: $(BUILDPYTHON) + @for i in $(BINDIR) $(LIBDIR); \ + do \ + if test ! -d $(DESTDIR)$$i; then \ + echo "Creating directory $$i"; \ + $(INSTALL) -d -m $(DIRMODE) $(DESTDIR)$$i; \ + else true; \ + fi; \ + done + $(INSTALL_PROGRAM) $(BUILDPYTHON) $(DESTDIR)$(BINDIR)/python$(VERSION)$(EXE) + if test -f libpython$(VERSION)$(SO); then \ + if test "$(SO)" = .dll; then \ + $(INSTALL_SHARED) libpython$(VERSION)$(SO) $(DESTDIR)$(BINDIR); \ + else \ + $(INSTALL_SHARED) libpython$(VERSION)$(SO) $(DESTDIR)$(LIBDIR)/$(INSTSONAME); \ + if test libpython$(VERSION)$(SO) != $(INSTSONAME); then \ + (cd $(DESTDIR)$(LIBDIR); $(LN) -sf $(INSTSONAME) libpython$(VERSION)$(SO)); \ + fi \ + fi; \ + else true; \ + fi + +# Install the manual page +maninstall: + @for i in $(MANDIR) $(MANDIR)/man1; \ + do \ + if test ! -d $(DESTDIR)$$i; then \ + echo "Creating directory $$i"; \ + $(INSTALL) -d -m $(DIRMODE) $(DESTDIR)$$i; \ + else true; \ + fi; \ + done + $(INSTALL_DATA) $(srcdir)/Misc/python.man \ + $(DESTDIR)$(MANDIR)/man1/python.1 + +# Install the library +PLATDIR= plat-$(MACHDEP) +EXTRAPLATDIR= +EXTRAMACHDEPPATH= +MACHDEPS= $(PLATDIR) $(EXTRAPLATDIR) +XMLLIBSUBDIRS= xml xml/dom xml/etree xml/parsers xml/sax +PLATMACDIRS= plat-mac plat-mac/Carbon plat-mac/lib-scriptpackages \ + plat-mac/lib-scriptpackages/_builtinSuites \ + plat-mac/lib-scriptpackages/CodeWarrior \ + plat-mac/lib-scriptpackages/Explorer \ + plat-mac/lib-scriptpackages/Finder \ + plat-mac/lib-scriptpackages/Netscape \ + plat-mac/lib-scriptpackages/StdSuites \ + plat-mac/lib-scriptpackages/SystemEvents \ + plat-mac/lib-scriptpackages/Terminal +PLATMACPATH=:plat-mac:plat-mac/lib-scriptpackages +LIBSUBDIRS= lib-tk site-packages test test/output test/data \ + test/decimaltestdata \ + encodings compiler hotshot \ + email email/mime email/test email/test/data \ + sqlite3 sqlite3/test \ + logging bsddb bsddb/test csv wsgiref \ + ctypes ctypes/test ctypes/macholib idlelib idlelib/Icons \ + distutils distutils/command distutils/tests $(XMLLIBSUBDIRS) \ + setuptools setuptools/command setuptools/tests setuptools.egg-info \ + curses $(MACHDEPS) +libinstall: $(BUILDPYTHON) $(srcdir)/Lib/$(PLATDIR) + @for i in $(SCRIPTDIR) $(LIBDEST); \ + do \ + if test ! -d $(DESTDIR)$$i; then \ + echo "Creating directory $$i"; \ + $(INSTALL) -d -m $(DIRMODE) $(DESTDIR)$$i; \ + else true; \ + fi; \ + done + @for d in $(LIBSUBDIRS); \ + do \ + a=$(srcdir)/Lib/$$d; \ + if test ! -d $$a; then continue; else true; fi; \ + b=$(LIBDEST)/$$d; \ + if test ! -d $(DESTDIR)$$b; then \ + echo "Creating directory $$b"; \ + $(INSTALL) -d -m $(DIRMODE) $(DESTDIR)$$b; \ + else true; \ + fi; \ + done + @for i in $(srcdir)/Lib/*.py $(srcdir)/Lib/*.doc $(srcdir)/Lib/*.egg-info ; \ + do \ + if test -x $$i; then \ + $(INSTALL_SCRIPT) $$i $(DESTDIR)$(LIBDEST); \ + echo $(INSTALL_SCRIPT) $$i $(LIBDEST); \ + else \ + $(INSTALL_DATA) $$i $(DESTDIR)$(LIBDEST); \ + echo $(INSTALL_DATA) $$i $(LIBDEST); \ + fi; \ + done + @for d in $(LIBSUBDIRS); \ + do \ + a=$(srcdir)/Lib/$$d; \ + if test ! -d $$a; then continue; else true; fi; \ + if test `ls $$a | wc -l` -lt 1; then continue; fi; \ + b=$(LIBDEST)/$$d; \ + for i in $$a/*; \ + do \ + case $$i in \ + *CVS) ;; \ + *.py[co]) ;; \ + *.orig) ;; \ + *~) ;; \ + *) \ + if test -d $$i; then continue; fi; \ + if test -x $$i; then \ + echo $(INSTALL_SCRIPT) $$i $$b; \ + $(INSTALL_SCRIPT) $$i $(DESTDIR)$$b; \ + else \ + echo $(INSTALL_DATA) $$i $$b; \ + $(INSTALL_DATA) $$i $(DESTDIR)$$b; \ + fi;; \ + esac; \ + done; \ + done + $(INSTALL_DATA) $(srcdir)/LICENSE $(DESTDIR)$(LIBDEST)/LICENSE.txt + PYTHONPATH=$(DESTDIR)$(LIBDEST) $(RUNSHARED) \ + ./$(BUILDPYTHON) -Wi -tt $(DESTDIR)$(LIBDEST)/compileall.py \ + -d $(LIBDEST) -f \ + -x 'bad_coding|badsyntax|site-packages' $(DESTDIR)$(LIBDEST) + PYTHONPATH=$(DESTDIR)$(LIBDEST) $(RUNSHARED) \ + ./$(BUILDPYTHON) -Wi -tt -O $(DESTDIR)$(LIBDEST)/compileall.py \ + -d $(LIBDEST) -f \ + -x 'bad_coding|badsyntax|site-packages' $(DESTDIR)$(LIBDEST) + -PYTHONPATH=$(DESTDIR)$(LIBDEST) $(RUNSHARED) \ + ./$(BUILDPYTHON) -Wi -t $(DESTDIR)$(LIBDEST)/compileall.py \ + -d $(LIBDEST)/site-packages -f \ + -x badsyntax $(DESTDIR)$(LIBDEST)/site-packages + -PYTHONPATH=$(DESTDIR)$(LIBDEST) $(RUNSHARED) \ + ./$(BUILDPYTHON) -Wi -t -O $(DESTDIR)$(LIBDEST)/compileall.py \ + -d $(LIBDEST)/site-packages -f \ + -x badsyntax $(DESTDIR)$(LIBDEST)/site-packages + +# Create the PLATDIR source directory, if one wasn't distributed.. +$(srcdir)/Lib/$(PLATDIR): + mkdir $(srcdir)/Lib/$(PLATDIR) + cp $(srcdir)/Lib/plat-generic/regen $(srcdir)/Lib/$(PLATDIR)/regen + export PATH; PATH="`pwd`:$$PATH"; \ + export PYTHONPATH; PYTHONPATH="`pwd`/Lib"; \ + export DYLD_FRAMEWORK_PATH; DYLD_FRAMEWORK_PATH="`pwd`"; \ + export EXE; EXE="$(BUILDEXE)"; \ + cd $(srcdir)/Lib/$(PLATDIR); ./regen + +# Install the include files +INCLDIRSTOMAKE=$(INCLUDEDIR) $(CONFINCLUDEDIR) $(INCLUDEPY) $(CONFINCLUDEPY) +inclinstall: + @for i in $(INCLDIRSTOMAKE); \ + do \ + if test ! -d $(DESTDIR)$$i; then \ + echo "Creating directory $$i"; \ + $(INSTALL) -d -m $(DIRMODE) $(DESTDIR)$$i; \ + else true; \ + fi; \ + done + @for i in $(srcdir)/Include/*.h; \ + do \ + echo $(INSTALL_DATA) $$i $(INCLUDEPY); \ + $(INSTALL_DATA) $$i $(DESTDIR)$(INCLUDEPY); \ + done + $(INSTALL_DATA) pyconfig.h $(DESTDIR)$(CONFINCLUDEPY)/pyconfig.h + +# Install the library and miscellaneous stuff needed for extending/embedding +# This goes into $(exec_prefix) +LIBPL= $(LIBP)/config +libainstall: all + @for i in $(LIBDIR) $(LIBP) $(LIBPL); \ + do \ + if test ! -d $(DESTDIR)$$i; then \ + echo "Creating directory $$i"; \ + $(INSTALL) -d -m $(DIRMODE) $(DESTDIR)$$i; \ + else true; \ + fi; \ + done + @if test -d $(LIBRARY); then :; else \ + if test "$(PYTHONFRAMEWORKDIR)" = no-framework; then \ + if test "$(SO)" = .dll; then \ + $(INSTALL_DATA) $(LDLIBRARY) $(DESTDIR)$(LIBPL) ; \ + else \ + $(INSTALL_DATA) $(LIBRARY) $(DESTDIR)$(LIBPL)/$(LIBRARY) ; \ + $(RANLIB) $(DESTDIR)$(LIBPL)/$(LIBRARY) ; \ + fi; \ + else \ + echo Skip install of $(LIBRARY) - use make frameworkinstall; \ + fi; \ + fi + $(INSTALL_DATA) Modules/config.c $(DESTDIR)$(LIBPL)/config.c + $(INSTALL_DATA) Modules/python.o $(DESTDIR)$(LIBPL)/python.o + $(INSTALL_DATA) $(srcdir)/Modules/config.c.in $(DESTDIR)$(LIBPL)/config.c.in + $(INSTALL_DATA) Makefile $(DESTDIR)$(LIBPL)/Makefile + $(INSTALL_DATA) Modules/Setup $(DESTDIR)$(LIBPL)/Setup + $(INSTALL_DATA) Modules/Setup.local $(DESTDIR)$(LIBPL)/Setup.local + $(INSTALL_DATA) Modules/Setup.config $(DESTDIR)$(LIBPL)/Setup.config + $(INSTALL_SCRIPT) $(srcdir)/Modules/makesetup $(DESTDIR)$(LIBPL)/makesetup + $(INSTALL_SCRIPT) $(srcdir)/install-sh $(DESTDIR)$(LIBPL)/install-sh + # Substitution happens here, as the completely-expanded BINDIR + # is not available in configure + sed -e "s, at EXENAME@,$(BINDIR)/python$(VERSION)$(EXE)," < $(srcdir)/Misc/python-config.in >python-config + $(INSTALL_SCRIPT) python-config $(DESTDIR)$(BINDIR)/python$(VERSION)-config + rm python-config + @if [ -s Modules/python.exp -a \ + "`echo $(MACHDEP) | sed 's/^\(...\).*/\1/'`" = "aix" ]; then \ + echo; echo "Installing support files for building shared extension modules on AIX:"; \ + $(INSTALL_DATA) Modules/python.exp \ + $(DESTDIR)$(LIBPL)/python.exp; \ + echo; echo "$(LIBPL)/python.exp"; \ + $(INSTALL_SCRIPT) $(srcdir)/Modules/makexp_aix \ + $(DESTDIR)$(LIBPL)/makexp_aix; \ + echo "$(LIBPL)/makexp_aix"; \ + $(INSTALL_SCRIPT) $(srcdir)/Modules/ld_so_aix \ + $(DESTDIR)$(LIBPL)/ld_so_aix; \ + echo "$(LIBPL)/ld_so_aix"; \ + echo; echo "See Misc/AIX-NOTES for details."; \ + else true; \ + fi + @case "$(MACHDEP)" in beos*) \ + echo; echo "Installing support files for building shared extension modules on BeOS:"; \ + $(INSTALL_DATA) Misc/BeOS-NOTES $(DESTDIR)$(LIBPL)/README; \ + echo; echo "$(LIBPL)/README"; \ + $(INSTALL_SCRIPT) Modules/ar_beos $(DESTDIR)$(LIBPL)/ar_beos; \ + echo "$(LIBPL)/ar_beos"; \ + $(INSTALL_SCRIPT) Modules/ld_so_beos $(DESTDIR)$(LIBPL)/ld_so_beos; \ + echo "$(LIBPL)/ld_so_beos"; \ + echo; echo "See Misc/BeOS-NOTES for details."; \ + ;; \ + esac + +# Install the dynamically loadable modules +# This goes into $(exec_prefix) +sharedinstall: + $(RUNSHARED) ./$(BUILDPYTHON) -E $(srcdir)/setup.py install \ + --prefix=$(prefix) \ + --install-scripts=$(BINDIR) \ + --install-platlib=$(DESTSHARED) \ + --root=/$(DESTDIR) + +# Here are a couple of targets for MacOSX again, to install a full +# framework-based Python. frameworkinstall installs everything, the +# subtargets install specific parts. Much of the actual work is offloaded to +# the Makefile in Mac +# +# +# This target is here for backward compatiblity, previous versions of Python +# hadn't integrated framework installation in the normal install process. +frameworkinstall: install + +# On install, we re-make the framework +# structure in the install location, /Library/Frameworks/ or the argument to +# --enable-framework. If --enable-framework has been specified then we have +# automatically set prefix to the location deep down in the framework, so we +# only have to cater for the structural bits of the framework. + +frameworkinstallframework: frameworkinstallstructure install frameworkinstallmaclib + +frameworkinstallstructure: $(LDLIBRARY) + @if test "$(PYTHONFRAMEWORKDIR)" = no-framework; then \ + echo Not configured with --enable-framework; \ + exit 1; \ + else true; \ + fi + @for i in $(prefix)/Resources/English.lproj $(prefix)/lib; do\ + if test ! -d $(DESTDIR)$$i; then \ + echo "Creating directory $(DESTDIR)$$i"; \ + $(INSTALL) -d -m $(DIRMODE) $(DESTDIR)$$i; \ + else true; \ + fi; \ + done + $(LN) -fsn include/python$(VERSION) $(DESTDIR)$(prefix)/Headers + $(INSTALL_DATA) $(RESSRCDIR)/Info.plist $(DESTDIR)$(prefix)/Resources/Info.plist + $(INSTALL_DATA) $(RESSRCDIR)/version.plist $(DESTDIR)$(prefix)/Resources/version.plist + $(INSTALL_DATA) $(RESSRCDIR)/English.lproj/InfoPlist.strings \ + $(DESTDIR)$(prefix)/Resources/English.lproj/InfoPlist.strings + $(LN) -fsn $(VERSION) $(DESTDIR)$(PYTHONFRAMEWORKINSTALLDIR)/Versions/Current + $(LN) -fsn Versions/Current/Python $(DESTDIR)$(PYTHONFRAMEWORKINSTALLDIR)/Python + $(LN) -fsn Versions/Current/Headers $(DESTDIR)$(PYTHONFRAMEWORKINSTALLDIR)/Headers + $(LN) -fsn Versions/Current/Resources $(DESTDIR)$(PYTHONFRAMEWORKINSTALLDIR)/Resources + $(INSTALL_SHARED) $(LDLIBRARY) $(DESTDIR)$(PYTHONFRAMEWORKPREFIX)/$(LDLIBRARY) + +# This installs Mac/Lib into the framework +# Install a number of symlinks to keep software that expects a normal unix +# install (which includes python-config) happy. +frameworkinstallmaclib: + ln -fs "../../../Python" "$(DESTDIR)$(prefix)/lib/python$(VERSION)/config/libpython$(VERSION).a" + cd Mac && $(MAKE) installmacsubtree DESTDIR="$(DESTDIR)" + +# This installs the IDE, the Launcher and other apps into /Applications +frameworkinstallapps: + cd Mac && $(MAKE) installapps DESTDIR="$(DESTDIR)" + +# This install the unix python and pythonw tools in /usr/local/bin +frameworkinstallunixtools: + cd Mac && $(MAKE) installunixtools DESTDIR="$(DESTDIR)" + +frameworkaltinstallunixtools: + cd Mac && $(MAKE) altinstallunixtools DESTDIR="$(DESTDIR)" + +# This installs the Demos and Tools into the applications directory. +# It is not part of a normal frameworkinstall +frameworkinstallextras: + cd Mac && Make installextras DESTDIR="$(DESTDIR)" + +# This installs a few of the useful scripts in Tools/scripts +scriptsinstall: + SRCDIR=$(srcdir) $(RUNSHARED) \ + ./$(BUILDPYTHON) $(srcdir)/Tools/scripts/setup.py install \ + --prefix=$(prefix) \ + --install-scripts=$(BINDIR) \ + --root=/$(DESTDIR) + +# Build the toplevel Makefile +Makefile.pre: Makefile.pre.in config.status + CONFIG_FILES=Makefile.pre CONFIG_HEADERS= $(SHELL) config.status + $(MAKE) -f Makefile.pre Makefile + +# Run the configure script. +config.status: $(srcdir)/configure + $(SHELL) $(srcdir)/configure $(CONFIG_ARGS) + +.PRECIOUS: config.status $(BUILDPYTHON) Makefile Makefile.pre + +# Some make's put the object file in the current directory +.c.o: + $(CC) -c $(PY_CFLAGS) -o $@ $< + +# Run reindent on the library +reindent: + ./python$(EXEEXT) $(srcdir)/Tools/scripts/reindent.py -r $(srcdir)/Lib + +# Rerun configure with the same options as it was run last time, +# provided the config.status script exists +recheck: + $(SHELL) config.status --recheck + $(SHELL) config.status + +# Rebuild the configure script from configure.in; also rebuild pyconfig.h.in +autoconf: + (cd $(srcdir); autoconf) + (cd $(srcdir); autoheader) + +# Create a tags file for vi +tags:: + cd $(srcdir); \ + ctags -w -t Include/*.h; \ + for i in $(SRCDIRS); do ctags -w -t -a $$i/*.[ch]; \ + done; \ + sort -o tags tags + +# Create a tags file for GNU Emacs +TAGS:: + cd $(srcdir); \ + etags Include/*.h; \ + for i in $(SRCDIRS); do etags -a $$i/*.[ch]; done + +# Sanitation targets -- clean leaves libraries, executables and tags +# files, which clobber removes those as well +pycremoval: + find $(srcdir) -name '*.py[co]' -exec rm -f {} ';' + +clean: pycremoval + find . -name '*.o' -exec rm -f {} ';' + find . -name '*.s[ol]' -exec rm -f {} ';' + find $(srcdir)/build -name 'fficonfig.h' -exec rm -f {} ';' || true + find $(srcdir)/build -name 'fficonfig.py' -exec rm -f {} ';' || true + +clobber: clean + -rm -f $(BUILDPYTHON) $(PGEN) $(LIBRARY) $(LDLIBRARY) $(DLLLIBRARY) \ + tags TAGS \ + config.cache config.log pyconfig.h Modules/config.c + -rm -rf build platform + -rm -rf $(PYTHONFRAMEWORKDIR) + +# Make things extra clean, before making a distribution: +# remove all generated files, even Makefile[.pre] +# Keep configure and Python-ast.[ch], it's possible they can't be generated +distclean: clobber + -rm -f core Makefile Makefile.pre config.status \ + Modules/Setup Modules/Setup.local Modules/Setup.config + find $(srcdir) '(' -name '*.fdc' -o -name '*~' \ + -o -name '[@,#]*' -o -name '*.old' \ + -o -name '*.orig' -o -name '*.rej' \ + -o -name '*.bak' ')' \ + -exec rm -f {} ';' + +# Check for smelly exported symbols (not starting with Py/_Py) +smelly: all + nm -p $(LIBRARY) | \ + sed -n "/ [TDB] /s/.* //p" | grep -v "^_*Py" | sort -u; \ + +# Find files with funny names +funny: + find $(DISTDIRS) -type d \ + -o -name '*.[chs]' \ + -o -name '*.py' \ + -o -name '*.doc' \ + -o -name '*.sty' \ + -o -name '*.bib' \ + -o -name '*.dat' \ + -o -name '*.el' \ + -o -name '*.fd' \ + -o -name '*.in' \ + -o -name '*.tex' \ + -o -name '*,[vpt]' \ + -o -name 'Setup' \ + -o -name 'Setup.*' \ + -o -name README \ + -o -name Makefile \ + -o -name ChangeLog \ + -o -name Repository \ + -o -name Root \ + -o -name Entries \ + -o -name Tag \ + -o -name tags \ + -o -name TAGS \ + -o -name .cvsignore \ + -o -name MANIFEST \ + -o -print + +# Dependencies + +Python/thread.o: $(srcdir)/Python/thread_atheos.h $(srcdir)/Python/thread_beos.h $(srcdir)/Python/thread_cthread.h $(srcdir)/Python/thread_foobar.h $(srcdir)/Python/thread_lwp.h $(srcdir)/Python/thread_nt.h $(srcdir)/Python/thread_os2.h $(srcdir)/Python/thread_pth.h $(srcdir)/Python/thread_pthread.h $(srcdir)/Python/thread_sgi.h $(srcdir)/Python/thread_solaris.h $(srcdir)/Python/thread_wince.h + +# Declare targets that aren't real files +.PHONY: all sharedmods oldsharedmods test quicktest memtest +.PHONY: install altinstall oldsharedinstall bininstall altbininstall +.PHONY: maninstall libinstall inclinstall libainstall sharedinstall +.PHONY: frameworkinstall frameworkinstallframework frameworkinstallstructure +.PHONY: frameworkinstallmaclib frameworkinstallapps frameworkinstallunixtools +.PHONY: frameworkaltinstallunixtools recheck autoconf clean clobber distclean +.PHONY: smelly funny + +# IF YOU PUT ANYTHING HERE IT WILL GO AWAY + +# Rules appended by makedepend + +Modules/threadmodule.o: $(srcdir)/Modules/threadmodule.c; $(CC) $(PY_CFLAGS) -c $(srcdir)/Modules/threadmodule.c -o Modules/threadmodule.o +Modules/threadmodule$(SO): Modules/threadmodule.o; $(LDSHARED) Modules/threadmodule.o -o Modules/threadmodule$(SO) +Modules/signalmodule.o: $(srcdir)/Modules/signalmodule.c; $(CC) $(PY_CFLAGS) -c $(srcdir)/Modules/signalmodule.c -o Modules/signalmodule.o +Modules/signalmodule$(SO): Modules/signalmodule.o; $(LDSHARED) Modules/signalmodule.o -o Modules/signalmodule$(SO) +Modules/posixmodule.o: $(srcdir)/Modules/posixmodule.c; $(CC) $(PY_CFLAGS) -c $(srcdir)/Modules/posixmodule.c -o Modules/posixmodule.o +Modules/posixmodule$(SO): Modules/posixmodule.o; $(LDSHARED) Modules/posixmodule.o -o Modules/posixmodule$(SO) +Modules/errnomodule.o: $(srcdir)/Modules/errnomodule.c; $(CC) $(PY_CFLAGS) -c $(srcdir)/Modules/errnomodule.c -o Modules/errnomodule.o +Modules/errnomodule$(SO): Modules/errnomodule.o; $(LDSHARED) Modules/errnomodule.o -o Modules/errnomodule$(SO) +Modules/pwdmodule.o: $(srcdir)/Modules/pwdmodule.c; $(CC) $(PY_CFLAGS) -c $(srcdir)/Modules/pwdmodule.c -o Modules/pwdmodule.o +Modules/pwdmodule$(SO): Modules/pwdmodule.o; $(LDSHARED) Modules/pwdmodule.o -o Modules/pwdmodule$(SO) +Modules/_sre.o: $(srcdir)/Modules/_sre.c; $(CC) $(PY_CFLAGS) -c $(srcdir)/Modules/_sre.c -o Modules/_sre.o +Modules/_sre$(SO): Modules/_sre.o; $(LDSHARED) Modules/_sre.o -o Modules/_sre$(SO) +Modules/_codecsmodule.o: $(srcdir)/Modules/_codecsmodule.c; $(CC) $(PY_CFLAGS) -c $(srcdir)/Modules/_codecsmodule.c -o Modules/_codecsmodule.o +Modules/_codecsmodule$(SO): Modules/_codecsmodule.o; $(LDSHARED) Modules/_codecsmodule.o -o Modules/_codecsmodule$(SO) +Modules/zipimport.o: $(srcdir)/Modules/zipimport.c; $(CC) $(PY_CFLAGS) -c $(srcdir)/Modules/zipimport.c -o Modules/zipimport.o +Modules/zipimport$(SO): Modules/zipimport.o; $(LDSHARED) Modules/zipimport.o -o Modules/zipimport$(SO) +Modules/symtablemodule.o: $(srcdir)/Modules/symtablemodule.c; $(CC) $(PY_CFLAGS) -c $(srcdir)/Modules/symtablemodule.c -o Modules/symtablemodule.o +Modules/_symtablemodule$(SO): Modules/symtablemodule.o; $(LDSHARED) Modules/symtablemodule.o -o Modules/_symtablemodule$(SO) +Modules/xxsubtype.o: $(srcdir)/Modules/xxsubtype.c; $(CC) $(PY_CFLAGS) -c $(srcdir)/Modules/xxsubtype.c -o Modules/xxsubtype.o +Modules/xxsubtype$(SO): Modules/xxsubtype.o; $(LDSHARED) Modules/xxsubtype.o -o Modules/xxsubtype$(SO) Added: external/Pygments-0.8.1/tests/examplefiles/SmallCheck.hs ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/SmallCheck.hs Thu Aug 9 17:43:13 2007 @@ -0,0 +1,378 @@ +--------------------------------------------------------------------- +-- SmallCheck: another lightweight testing library. +-- Colin Runciman, August 2006 +-- Version 0.2 (November 2006) +-- +-- After QuickCheck, by Koen Claessen and John Hughes (2000-2004). +--------------------------------------------------------------------- + +module SmallCheck ( + smallCheck, depthCheck, + Property, Testable, + forAll, forAllElem, + exists, existsDeeperBy, thereExists, thereExistsElem, + (==>), + Series, Serial(..), + (\/), (><), two, three, four, + cons0, cons1, cons2, cons3, cons4, + alts0, alts1, alts2, alts3, alts4, + N(..), Nat, Natural, + depth, inc, dec + ) where + +import Data.List (intersperse) +import Control.Monad (when) +import System.IO (stdout, hFlush) + +------------------ ----------------- + +-- Series arguments should be interpreted as a depth bound (>=0) +-- Series results should have finite length + +type Series a = Int -> [a] + +-- sum +infixr 7 \/ +(\/) :: Series a -> Series a -> Series a +s1 \/ s2 = \d -> s1 d ++ s2 d + +-- product +infixr 8 >< +(><) :: Series a -> Series b -> Series (a,b) +s1 >< s2 = \d -> [(x,y) | x <- s1 d, y <- s2 d] + +------------------- ------------------ + +-- enumerated data values should be finite and fully defined +-- enumerated functional values should be total and strict + +-- bounds: +-- for data values, the depth of nested constructor applications +-- for functional values, both the depth of nested case analysis +-- and the depth of results + +class Serial a where + series :: Series a + coseries :: Serial b => Series (a->b) + +instance Serial () where + series _ = [()] + coseries d = [ \() -> b + | b <- series d ] + +instance Serial Int where + series d = [(-d)..d] + coseries d = [ \i -> if i > 0 then f (N (i - 1)) + else if i < 0 then g (N (abs i - 1)) + else z + | z <- alts0 d, f <- alts1 d, g <- alts1 d ] + +instance Serial Integer where + series d = [ toInteger (i :: Int) + | i <- series d ] + coseries d = [ f . (fromInteger :: Integer->Int) + | f <- series d ] + +newtype N a = N a + +instance Show a => Show (N a) where + show (N i) = show i + +instance (Integral a, Serial a) => Serial (N a) where + series d = map N [0..d'] + where + d' = fromInteger (toInteger d) + coseries d = [ \(N i) -> if i > 0 then f (N (i - 1)) + else z + | z <- alts0 d, f <- alts1 d ] + +type Nat = N Int +type Natural = N Integer + +instance Serial Float where + series d = [ encodeFloat sig exp + | (sig,exp) <- series d, + odd sig || sig==0 && exp==0 ] + coseries d = [ f . decodeFloat + | f <- series d ] + +instance Serial Double where + series d = [ frac (x :: Float) + | x <- series d ] + coseries d = [ f . (frac :: Double->Float) + | f <- series d ] + +frac :: (Real a, Fractional a, Real b, Fractional b) => a -> b +frac = fromRational . toRational + +instance Serial Char where + series d = take (d+1) ['a'..'z'] + coseries d = [ \c -> f (N (fromEnum c - fromEnum 'a')) + | f <- series d ] + +instance (Serial a, Serial b) => + Serial (a,b) where + series = series >< series + coseries = map uncurry . coseries + +instance (Serial a, Serial b, Serial c) => + Serial (a,b,c) where + series = \d -> [(a,b,c) | (a,(b,c)) <- series d] + coseries = map uncurry3 . coseries + +instance (Serial a, Serial b, Serial c, Serial d) => + Serial (a,b,c,d) where + series = \d -> [(a,b,c,d) | (a,(b,(c,d))) <- series d] + coseries = map uncurry4 . coseries + +uncurry3 :: (a->b->c->d) -> ((a,b,c)->d) +uncurry3 f (x,y,z) = f x y z + +uncurry4 :: (a->b->c->d->e) -> ((a,b,c,d)->e) +uncurry4 f (w,x,y,z) = f w x y z + +two :: Series a -> Series (a,a) +two s = s >< s + +three :: Series a -> Series (a,a,a) +three s = \d -> [(x,y,z) | (x,(y,z)) <- (s >< s >< s) d] + +four :: Series a -> Series (a,a,a,a) +four s = \d -> [(w,x,y,z) | (w,(x,(y,z))) <- (s >< s >< s >< s) d] + +cons0 :: + a -> Series a +cons0 c _ = [c] + +cons1 :: Serial a => + (a->b) -> Series b +cons1 c d = [c z | d > 0, z <- series (d-1)] + +cons2 :: (Serial a, Serial b) => + (a->b->c) -> Series c +cons2 c d = [c y z | d > 0, (y,z) <- series (d-1)] + +cons3 :: (Serial a, Serial b, Serial c) => + (a->b->c->d) -> Series d +cons3 c d = [c x y z | d > 0, (x,y,z) <- series (d-1)] + +cons4 :: (Serial a, Serial b, Serial c, Serial d) => + (a->b->c->d->e) -> Series e +cons4 c d = [c w x y z | d > 0, (w,x,y,z) <- series (d-1)] + +alts0 :: Serial a => + Series a +alts0 d = series d + +alts1 :: (Serial a, Serial b) => + Series (a->b) +alts1 d = if d > 0 then series (dec d) + else [\_ -> x | x <- series d] + +alts2 :: (Serial a, Serial b, Serial c) => + Series (a->b->c) +alts2 d = if d > 0 then series (dec d) + else [\_ _ -> x | x <- series d] + +alts3 :: (Serial a, Serial b, Serial c, Serial d) => + Series (a->b->c->d) +alts3 d = if d > 0 then series (dec d) + else [\_ _ _ -> x | x <- series d] + +alts4 :: (Serial a, Serial b, Serial c, Serial d, Serial e) => + Series (a->b->c->d->e) +alts4 d = if d > 0 then series (dec d) + else [\_ _ _ _ -> x | x <- series d] + +instance Serial Bool where + series = cons0 True \/ cons0 False + coseries d = [ \x -> if x then b1 else b2 + | (b1,b2) <- series d ] + +instance Serial a => Serial (Maybe a) where + series = cons0 Nothing \/ cons1 Just + coseries d = [ \m -> case m of + Nothing -> z + Just x -> f x + | z <- alts0 d , + f <- alts1 d ] + +instance (Serial a, Serial b) => Serial (Either a b) where + series = cons1 Left \/ cons1 Right + coseries d = [ \e -> case e of + Left x -> f x + Right y -> g y + | f <- alts1 d , + g <- alts1 d ] + +instance Serial a => Serial [a] where + series = cons0 [] \/ cons2 (:) + coseries d = [ \xs -> case xs of + [] -> y + (x:xs') -> f x xs' + | y <- alts0 d , + f <- alts2 d ] + +-- Warning: the coseries instance here may generate duplicates. +instance (Serial a, Serial b) => Serial (a->b) where + series = coseries + coseries d = [ \f -> g [f x | x <- series d] + | g <- series d ] + +-- For customising the depth measure. Use with care! + +depth :: Int -> Int -> Int +depth d d' | d >= 0 = d'+1-d + | otherwise = error "SmallCheck.depth: argument < 0" + +dec :: Int -> Int +dec d | d > 0 = d-1 + | otherwise = error "SmallCheck.dec: argument <= 0" + +inc :: Int -> Int +inc d = d+1 + +-- show the extension of a function (in part, bounded both by +-- the number and depth of arguments) +instance (Serial a, Show a, Show b) => Show (a->b) where + show f = + if maxarheight == 1 + && sumarwidth + length ars * length "->;" < widthLimit then + "{"++( + concat $ intersperse ";" $ [a++"->"++r | (a,r) <- ars] + )++"}" + else + concat $ [a++"->\n"++indent r | (a,r) <- ars] + where + ars = take lengthLimit [ (show x, show (f x)) + | x <- series depthLimit ] + maxarheight = maximum [ max (height a) (height r) + | (a,r) <- ars ] + sumarwidth = sum [ length a + length r + | (a,r) <- ars] + indent = unlines . map (" "++) . lines + height = length . lines + (widthLimit,lengthLimit,depthLimit) = (80,20,3)::(Int,Int,Int) + +---------------- ------------------ + +-- adapted from QuickCheck originals: here results come in lists, +-- properties have depth arguments, stamps (for classifying random +-- tests) are omitted, existentials are introduced + +newtype PR = Prop [Result] + +data Result = Result {ok :: Maybe Bool, arguments :: [String]} + +nothing :: Result +nothing = Result {ok = Nothing, arguments = []} + +result :: Result -> PR +result res = Prop [res] + +newtype Property = Property (Int -> PR) + +class Testable a where + property :: a -> Int -> PR + +instance Testable Bool where + property b _ = Prop [Result (Just b) []] + +instance Testable PR where + property prop _ = prop + +instance (Serial a, Show a, Testable b) => Testable (a->b) where + property f = f' where Property f' = forAll series f + +instance Testable Property where + property (Property f) d = f d + +evaluate :: Testable a => a -> Series Result +evaluate x d = rs where Prop rs = property x d + +forAll :: (Show a, Testable b) => Series a -> (a->b) -> Property +forAll xs f = Property $ \d -> Prop $ + [ r{arguments = show x : arguments r} + | x <- xs d, r <- evaluate (f x) d ] + +forAllElem :: (Show a, Testable b) => [a] -> (a->b) -> Property +forAllElem xs = forAll (const xs) + +thereExists :: Testable b => Series a -> (a->b) -> Property +thereExists xs f = Property $ \d -> Prop $ + [ Result + ( Just $ or [ all pass (evaluate (f x) d) + | x <- xs d ] ) + [] ] + where + pass (Result Nothing _) = True + pass (Result (Just b) _) = b + +thereExistsElem :: Testable b => [a] -> (a->b) -> Property +thereExistsElem xs = thereExists (const xs) + +exists :: (Serial a, Testable b) => + (a->b) -> Property +exists = thereExists series + +existsDeeperBy :: (Serial a, Testable b) => + (Int->Int) -> (a->b) -> Property +existsDeeperBy f = thereExists (series . f) + +infixr 0 ==> + +(==>) :: Testable a => Bool -> a -> Property +True ==> x = Property (property x) +False ==> x = Property (const (result nothing)) + +--------------------- ---------------------- + +-- similar in spirit to QuickCheck but with iterative deepening + +-- test for values of depths 0..d stopping when a property +-- fails or when it has been checked for all these values +smallCheck :: Testable a => Int -> a -> IO String +smallCheck d = iterCheck 0 (Just d) + +depthCheck :: Testable a => Int -> a -> IO String +depthCheck d = iterCheck d (Just d) + +iterCheck :: Testable a => Int -> Maybe Int -> a -> IO String +iterCheck dFrom mdTo t = iter dFrom + where + iter :: Int -> IO String + iter d = do + let Prop results = property t d + (ok,s) <- check (mdTo==Nothing) 0 0 True results + maybe (iter (d+1)) + (\dTo -> if ok && d < dTo + then iter (d+1) + else return s) + mdTo + +check :: Bool -> Int -> Int -> Bool -> [Result] -> IO (Bool, String) +check i n x ok rs | null rs = do + let s = " Completed "++show n++" test(s)" + y = if i then "." else " without failure." + z | x > 0 = " But "++show x++" did not meet ==> condition." + | otherwise = "" + return (ok, s ++ y ++ z) + +check i n x ok (Result Nothing _ : rs) = do + progressReport i n x + check i (n+1) (x+1) ok rs + +check i n x f (Result (Just True) _ : rs) = do + progressReport i n x + check i (n+1) x f rs + +check i n x f (Result (Just False) args : rs) = do + let s = " Failed test no. "++show (n+1)++". Test values follow." + s' = s ++ ": " ++ concat (intersperse ", " args) + if i then + check i (n+1) x False rs + else + return (False, s') + +progressReport :: Bool -> Int -> Int -> IO () +progressReport _ _ _ = return () Added: external/Pygments-0.8.1/tests/examplefiles/apache2.conf ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/apache2.conf Thu Aug 9 17:43:13 2007 @@ -0,0 +1,393 @@ +# Based upon the NCSA server configuration files originally by Rob McCool. +# Changed extensively for the Debian package by Daniel Stone +# and also by Thom May . + +# ServerRoot: The top of the directory tree under which the server's +# configuration, error, and log files are kept. +# +# NOTE! If you intend to place this on an NFS (or otherwise network) +# mounted filesystem then please read the LockFile documentation +# (available at ); +# you will save yourself a lot of trouble. + +ServerRoot "/etc/apache2" + +# The LockFile directive sets the path to the lockfile used when Apache +# is compiled with either USE_FCNTL_SERIALIZED_ACCEPT or +# USE_FLOCK_SERIALIZED_ACCEPT. This directive should normally be left at +# its default value. The main reason for changing it is if the logs +# directory is NFS mounted, since the lockfile MUST BE STORED ON A LOCAL +# DISK. The PID of the main server process is automatically appended to +# the filename. + +LockFile /var/lock/apache2/accept.lock + +# PidFile: The file in which the server should record its process +# identification number when it starts. + +PidFile /var/run/apache2.pid + +# Timeout: The number of seconds before receives and sends time out. + +Timeout 300 + +# KeepAlive: Whether or not to allow persistent connections (more than +# one request per connection). Set to "Off" to deactivate. + +KeepAlive On + +# MaxKeepAliveRequests: The maximum number of requests to allow +# during a persistent connection. Set to 0 to allow an unlimited amount. +# We recommend you leave this number high, for maximum performance. + +MaxKeepAliveRequests 100 + +# KeepAliveTimeout: Number of seconds to wait for the next request from the +# same client on the same connection. + +KeepAliveTimeout 15 + +## +## Server-Pool Size Regulation (MPM specific) +## + +# prefork MPM +# StartServers ......... number of server processes to start +# MinSpareServers ...... minimum number of server processes which are kept spare +# MaxSpareServers ...... maximum number of server processes which are kept spare +# MaxClients ........... maximum number of server processes allowed to start +# MaxRequestsPerChild .. maximum number of requests a server process serves + +StartServers 5 +MinSpareServers 5 +MaxSpareServers 10 +MaxClients 20 +MaxRequestsPerChild 0 + + +# pthread MPM +# StartServers ......... initial number of server processes to start +# MaxClients ........... maximum number of server processes allowed to start +# MinSpareThreads ...... minimum number of worker threads which are kept spare +# MaxSpareThreads ...... maximum number of worker threads which are kept spare +# ThreadsPerChild ...... constant number of worker threads in each server process +# MaxRequestsPerChild .. maximum number of requests a server process serves + +StartServers 2 +MaxClients 150 +MinSpareThreads 25 +MaxSpareThreads 75 +ThreadsPerChild 25 +MaxRequestsPerChild 0 + + +# perchild MPM +# NumServers ........... constant number of server processes +# StartThreads ......... initial number of worker threads in each server process +# MinSpareThreads ...... minimum number of worker threads which are kept spare +# MaxSpareThreads ...... maximum number of worker threads which are kept spare +# MaxThreadsPerChild ... maximum number of worker threads in each server process +# MaxRequestsPerChild .. maximum number of connections per server process (then it dies) + +NumServers 5 +StartThreads 5 +MinSpareThreads 5 +MaxSpareThreads 10 +MaxThreadsPerChild 20 +MaxRequestsPerChild 0 +AcceptMutex fcntl + + +User www-data +Group www-data + +# The following directives define some format nicknames for use with +# a CustomLog directive (see below). +LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined +LogFormat "%h %l %u %t \"%r\" %>s %b" common +LogFormat "%{Referer}i -> %U" referer +LogFormat "%{User-agent}i" agent + + +# Global error log. +ErrorLog /var/log/apache2/error.log + +# Include module configuration: +Include /etc/apache2/mods-enabled/*.load +Include /etc/apache2/mods-enabled/*.conf + +# Include all the user configurations: +Include /etc/apache2/httpd.conf + +# Include ports listing +Include /etc/apache2/ports.conf + +# Include generic snippets of statements +Include /etc/apache2/conf.d/[^.#]* + +#Let's have some Icons, shall we? +Alias /icons/ "/usr/share/apache2/icons/" + + Options Indexes MultiViews + AllowOverride None + Order allow,deny + Allow from all + + +# Set up the default error docs. +# +# Customizable error responses come in three flavors: +# 1) plain text 2) local redirects 3) external redirects +# +# Some examples: +#ErrorDocument 500 "The server made a boo boo." +#ErrorDocument 404 /missing.html +#ErrorDocument 404 "/cgi-bin/missing_handler.pl" +#ErrorDocument 402 http://www.example.com/subscription_info.html +# + +# +# Putting this all together, we can Internationalize error responses. +# +# We use Alias to redirect any /error/HTTP_.html.var response to +# our collection of by-error message multi-language collections. We use +# includes to substitute the appropriate text. +# +# You can modify the messages' appearance without changing any of the +# default HTTP_.html.var files by adding the line; +# +# Alias /error/include/ "/your/include/path/" +# +# which allows you to create your own set of files by starting with the +# /usr/local/apache2/error/include/ files and +# copying them to /your/include/path/, even on a per-VirtualHost basis. +# + + + + Alias /error/ "/usr/share/apache2/error/" + + + AllowOverride None + Options IncludesNoExec + AddOutputFilter Includes html + AddHandler type-map var + Order allow,deny + Allow from all + LanguagePriority en es de fr + ForceLanguagePriority Prefer Fallback + + + ErrorDocument 400 /error/HTTP_BAD_REQUEST.html.var + ErrorDocument 401 /error/HTTP_UNAUTHORIZED.html.var + ErrorDocument 403 /error/HTTP_FORBIDDEN.html.var + ErrorDocument 404 /error/HTTP_NOT_FOUND.html.var + ErrorDocument 405 /error/HTTP_METHOD_NOT_ALLOWED.html.var + ErrorDocument 408 /error/HTTP_REQUEST_TIME_OUT.html.var + ErrorDocument 410 /error/HTTP_GONE.html.var + ErrorDocument 411 /error/HTTP_LENGTH_REQUIRED.html.var + ErrorDocument 412 /error/HTTP_PRECONDITION_FAILED.html.var + ErrorDocument 413 /error/HTTP_REQUEST_ENTITY_TOO_LARGE.html.var + ErrorDocument 414 /error/HTTP_REQUEST_URI_TOO_LARGE.html.var + ErrorDocument 415 /error/HTTP_SERVICE_UNAVAILABLE.html.var + ErrorDocument 500 /error/HTTP_INTERNAL_SERVER_ERROR.html.var + ErrorDocument 501 /error/HTTP_NOT_IMPLEMENTED.html.var + ErrorDocument 502 /error/HTTP_BAD_GATEWAY.html.var + ErrorDocument 503 /error/HTTP_SERVICE_UNAVAILABLE.html.var + ErrorDocument 506 /error/HTTP_VARIANT_ALSO_VARIES.html.var + + + + +DirectoryIndex index.html index.cgi index.pl index.php index.xhtml + +# UserDir is now a module +#UserDir public_html +#UserDir disabled root + +# +# AllowOverride FileInfo AuthConfig Limit +# Options Indexes SymLinksIfOwnerMatch IncludesNoExec +# + +AccessFileName .htaccess + + + Order allow,deny + Deny from all + + +UseCanonicalName Off + +TypesConfig /etc/mime.types +DefaultType text/plain + +HostnameLookups Off + +IndexOptions FancyIndexing VersionSort + +AddIconByEncoding (CMP,/icons/compressed.gif) x-compress x-gzip + +AddIconByType (TXT,/icons/text.gif) text/* +AddIconByType (IMG,/icons/image2.gif) image/* +AddIconByType (SND,/icons/sound2.gif) audio/* +AddIconByType (VID,/icons/movie.gif) video/* + +# This really should be .jpg. + +AddIcon /icons/binary.gif .bin .exe +AddIcon /icons/binhex.gif .hqx +AddIcon /icons/tar.gif .tar +AddIcon /icons/world2.gif .wrl .wrl.gz .vrml .vrm .iv +AddIcon /icons/compressed.gif .Z .z .tgz .gz .zip +AddIcon /icons/a.gif .ps .ai .eps +AddIcon /icons/layout.gif .html .shtml .htm .pdf +AddIcon /icons/text.gif .txt +AddIcon /icons/c.gif .c +AddIcon /icons/p.gif .pl .py +AddIcon /icons/f.gif .for +AddIcon /icons/dvi.gif .dvi +AddIcon /icons/uuencoded.gif .uu +AddIcon /icons/script.gif .conf .sh .shar .csh .ksh .tcl +AddIcon /icons/tex.gif .tex +AddIcon /icons/bomb.gif core + +AddIcon /icons/back.gif .. +AddIcon /icons/hand.right.gif README +AddIcon /icons/folder.gif ^^DIRECTORY^^ +AddIcon /icons/blank.gif ^^BLANKICON^^ + + +# This is from Matty J's patch. Anyone want to make the icons? +#AddIcon /icons/dirsymlink.jpg ^^SYMDIR^^ +#AddIcon /icons/symlink.jpg ^^SYMLINK^^ + +DefaultIcon /icons/unknown.gif + +ReadmeName README.html +HeaderName HEADER.html + +IndexIgnore .??* *~ *# HEADER* RCS CVS *,t + +AddEncoding x-compress Z +AddEncoding x-gzip gz tgz + +AddLanguage da .dk +AddLanguage nl .nl +AddLanguage en .en +AddLanguage et .et +AddLanguage fr .fr +AddLanguage de .de +AddLanguage el .el +AddLanguage it .it +AddLanguage ja .ja +AddLanguage pl .po +AddLanguage ko .ko +AddLanguage pt .pt +AddLanguage no .no +AddLanguage pt-br .pt-br +AddLanguage ltz .ltz +AddLanguage ca .ca +AddLanguage es .es +AddLanguage sv .se +AddLanguage cz .cz +AddLanguage ru .ru +AddLanguage tw .tw +AddLanguage zh-tw .tw + +LanguagePriority en da nl et fr de el it ja ko no pl pt pt-br ltz ca es sv tw + + +#AddDefaultCharset ISO-8859-1 + +AddCharset ISO-8859-1 .iso8859-1 .latin1 +AddCharset ISO-8859-2 .iso8859-2 .latin2 .cen +AddCharset ISO-8859-3 .iso8859-3 .latin3 +AddCharset ISO-8859-4 .iso8859-4 .latin4 +AddCharset ISO-8859-5 .iso8859-5 .latin5 .cyr .iso-ru +AddCharset ISO-8859-6 .iso8859-6 .latin6 .arb +AddCharset ISO-8859-7 .iso8859-7 .latin7 .grk +AddCharset ISO-8859-8 .iso8859-8 .latin8 .heb +AddCharset ISO-8859-9 .iso8859-9 .latin9 .trk +AddCharset ISO-2022-JP .iso2022-jp .jis +AddCharset ISO-2022-KR .iso2022-kr .kis +AddCharset ISO-2022-CN .iso2022-cn .cis +AddCharset Big5 .Big5 .big5 +# For russian, more than one charset is used (depends on client, mostly): +AddCharset WINDOWS-1251 .cp-1251 .win-1251 +AddCharset CP866 .cp866 +AddCharset KOI8-r .koi8-r .koi8-ru +AddCharset KOI8-ru .koi8-uk .ua +AddCharset ISO-10646-UCS-2 .ucs2 +AddCharset ISO-10646-UCS-4 .ucs4 +AddCharset UTF-8 .utf8 + +AddCharset GB2312 .gb2312 .gb +AddCharset utf-7 .utf7 +AddCharset utf-8 .utf8 +AddCharset big5 .big5 .b5 +AddCharset EUC-TW .euc-tw +AddCharset EUC-JP .euc-jp +AddCharset EUC-KR .euc-kr +AddCharset shift_jis .sjis + +#AddType application/x-httpd-php .php +#AddType application/x-httpd-php-source .phps + +AddType application/x-tar .tgz + +# To use CGI scripts outside /cgi-bin/: +# +#AddHandler cgi-script .cgi + +# To use server-parsed HTML files +# + + SetOutputFilter INCLUDES + + +# If you wish to use server-parsed imagemap files, use +# +#AddHandler imap-file map + +BrowserMatch "Mozilla/2" nokeepalive +BrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0 force-response-1.0 +BrowserMatch "RealPlayer 4\.0" force-response-1.0 +BrowserMatch "Java/1\.0" force-response-1.0 +BrowserMatch "JDK/1\.0" force-response-1.0 + +# +# The following directive disables redirects on non-GET requests for +# a directory that does not include the trailing slash. This fixes a +# problem with Microsoft WebFolders which does not appropriately handle +# redirects for folders with DAV methods. +# + +BrowserMatch "Microsoft Data Access Internet Publishing Provider" redirect-carefully +BrowserMatch "^WebDrive" redirect-carefully +BrowserMatch "^gnome-vfs" redirect-carefully +BrowserMatch "^WebDAVFS/1.[012]" redirect-carefully + +# Allow server status reports, with the URL of http://servername/server-status +# Change the ".your_domain.com" to match your domain to enable. +# +# +# SetHandler server-status +# Order deny,allow +# Deny from all +# Allow from .your_domain.com +# + +# Allow remote server configuration reports, with the URL of +# http://servername/server-info (requires that mod_info.c be loaded). +# Change the ".your_domain.com" to match your domain to enable. +# +# +# SetHandler server-info +# Order deny,allow +# Deny from all +# Allow from .your_domain.com +# + +# Include the virtual host configurations: +Include /etc/apache2/sites-enabled/[^.#]* Added: external/Pygments-0.8.1/tests/examplefiles/batchfile.bat ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/batchfile.bat Thu Aug 9 17:43:13 2007 @@ -0,0 +1,46 @@ +rem this is a demo file. + at rem + at echo off + +call c:\temp.bat somearg +call :lab somearg +rem This next one is wrong in the vim lexer! +call c:temp.bat + +echo "Hi!" +echo hi +echo on +echo off +echo. + at echo off +if exist *.log echo The log file has arrived. +rem These are all escapes, also done incorrectly by the vim lexer +echo ^^ ^> ^< ^| + +x=beginning +setlocal +x = new text +endlocal + +for %%var in (*.jpg) do echo %%var +for /D %%var in (a b c) do echo %%var +for /R C:\temp %%var in (*.jpg) do iexplore.exe %%var +rem Vim has this one wrong too. +for /L %%var in (10,-1,1) do echo %%var +for /F %%var in ("hi!") do echo %%var +for /F "eol=c,skip=1,usebackq" %%var in (`command`) do echo %%var %~l %~fl %~dl %~pl %~nl %~xl %~sl %~al %~tl %~zl %~$PATH:l %~dpl %~dp$PATH:l %~ftzal + +echo some file ?! > somefile.txt + +set PATH=%PATH%;c:\windows + +goto answer%errorlevel% + :answer0 + echo Hi it's zero + :answer1 + echo New + +if exist a del a +else echo A is missing! + + Added: external/Pygments-0.8.1/tests/examplefiles/boot-9.scm ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/boot-9.scm Thu Aug 9 17:43:13 2007 @@ -0,0 +1,1557 @@ +;;; installed-scm-file + +;;;; Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. +;;;; +;;;; This program is free software; you can redistribute it and/or modify +;;;; it under the terms of the GNU General Public License as published by +;;;; the Free Software Foundation; either version 2, or (at your option) +;;;; any later version. +;;;; +;;;; This program is distributed in the hope that it will be useful, +;;;; but WITHOUT ANY WARRANTY; without even the implied warranty of +;;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +;;;; GNU General Public License for more details. +;;;; +;;;; You should have received a copy of the GNU General Public License +;;;; along with this software; see the file COPYING. If not, write to +;;;; the Free Software Foundation, Inc., 59 Temple Place, Suite 330, +;;;; Boston, MA 02111-1307 USA +;;;; +;;;; As a special exception, the Free Software Foundation gives permission +;;;; for additional uses of the text contained in its release of GUILE. +;;;; +;;;; The exception is that, if you link the GUILE library with other files +;;;; to produce an executable, this does not by itself cause the +;;;; resulting executable to be covered by the GNU General Public License. +;;;; Your use of that executable is in no way restricted on account of +;;;; linking the GUILE library code into it. +;;;; +;;;; This exception does not however invalidate any other reasons why +;;;; the executable file might be covered by the GNU General Public License. +;;;; +;;;; This exception applies only to the code released by the +;;;; Free Software Foundation under the name GUILE. If you copy +;;;; code from other Free Software Foundation releases into a copy of +;;;; GUILE, as the General Public License permits, the exception does +;;;; not apply to the code that you add in this way. To avoid misleading +;;;; anyone as to the status of such modified files, you must delete +;;;; this exception notice from them. +;;;; +;;;; If you write modifications of your own for GUILE, it is your choice +;;;; whether to permit this exception to apply to your modifications. +;;;; If you do not wish that, delete this exception notice. +;;;; + + +;;; Commentary: + +;;; This file is the first thing loaded into Guile. It adds many mundane +;;; definitions and a few that are interesting. +;;; +;;; The module system (hence the hierarchical namespace) are defined in this +;;; file. +;;; + +;;; Code: + + +;;; {Deprecation} +;;; + +;; We don't have macros here, but we do want to define +;; `begin-deprecated' early. + +(define begin-deprecated + (procedure->memoizing-macro + (lambda (exp env) + (if (include-deprecated-features) + `(begin ,@(cdr exp)) + `#f)))) + + +;;; {Features} +;; + +(define (provide sym) + (if (not (memq sym *features*)) + (set! *features* (cons sym *features*)))) + +;;; Return #t iff FEATURE is available to this Guile interpreter. +;;; In SLIB, provided? also checks to see if the module is available. +;;; We should do that too, but don't. +(define (provided? feature) + (and (memq feature *features*) #t)) + +(begin-deprecated + (define (feature? sym) + (issue-deprecation-warning + "`feature?' is deprecated. Use `provided?' instead.") + (provided? sym))) + +;;; let format alias simple-format until the more complete version is loaded +(define format simple-format) + + +;;; {R4RS compliance} + +(primitive-load-path "ice-9/r4rs.scm") + + +;;; {Simple Debugging Tools} +;; + + +;; peek takes any number of arguments, writes them to the +;; current ouput port, and returns the last argument. +;; It is handy to wrap around an expression to look at +;; a value each time is evaluated, e.g.: +;; +;; (+ 10 (troublesome-fn)) +;; => (+ 10 (pk 'troublesome-fn-returned (troublesome-fn))) +;; + +(define (peek . stuff) + (newline) + (display ";;; ") + (write stuff) + (newline) + (car (last-pair stuff))) + +(define pk peek) + +(define (warn . stuff) + (with-output-to-port (current-error-port) + (lambda () + (newline) + (display ";;; WARNING ") + (display stuff) + (newline) + (car (last-pair stuff))))) + + +;;; {Trivial Functions} +;;; + +(define (identity x) x) +(define (1+ n) (+ n 1)) +(define (1- n) (+ n -1)) +(define (and=> value procedure) (and value (procedure value))) +(define (make-hash-table k) (make-vector k '())) + +(begin-deprecated + (define (id x) + (issue-deprecation-warning "`id' is deprecated. Use `identity' instead.") + (identity x)) + (define (-1+ n) + (issue-deprecation-warning "`-1+' is deprecated. Use `1-' instead.") + (1- n)) + (define (return-it . args) + (issue-deprecation-warning "`return-it' is deprecated. Use `noop' instead.") + (apply noop args))) + +;;; apply-to-args is functionally redundant with apply and, worse, +;;; is less general than apply since it only takes two arguments. +;;; +;;; On the other hand, apply-to-args is a syntacticly convenient way to +;;; perform binding in many circumstances when the "let" family of +;;; of forms don't cut it. E.g.: +;;; +;;; (apply-to-args (return-3d-mouse-coords) +;;; (lambda (x y z) +;;; ...)) +;;; + +(define (apply-to-args args fn) (apply fn args)) + + + +;;; {Integer Math} +;;; + +(define (ipow-by-squaring x k acc proc) + (cond ((zero? k) acc) + ((= 1 k) (proc acc x)) + (else (ipow-by-squaring (proc x x) + (quotient k 2) + (if (even? k) acc (proc acc x)) + proc)))) + +(begin-deprecated + (define (string-character-length s) + (issue-deprecation-warning "`string-character-length' is deprecated. Use `string-length' instead.") + (string-length s)) + (define (flags . args) + (issue-deprecation-warning "`flags' is deprecated. Use `logior' instead.") + (apply logior args))) + + +;;; {Symbol Properties} +;;; + +(define (symbol-property sym prop) + (let ((pair (assoc prop (symbol-pref sym)))) + (and pair (cdr pair)))) + +(define (set-symbol-property! sym prop val) + (let ((pair (assoc prop (symbol-pref sym)))) + (if pair + (set-cdr! pair val) + (symbol-pset! sym (acons prop val (symbol-pref sym)))))) + +(define (symbol-property-remove! sym prop) + (let ((pair (assoc prop (symbol-pref sym)))) + (if pair + (symbol-pset! sym (delq! pair (symbol-pref sym)))))) + +;;; {General Properties} +;;; + +;; This is a more modern interface to properties. It will replace all +;; other property-like things eventually. + +(define (make-object-property) + (let ((prop (primitive-make-property #f))) + (make-procedure-with-setter + (lambda (obj) (primitive-property-ref prop obj)) + (lambda (obj val) (primitive-property-set! prop obj val))))) + + + +;;; {Arrays} +;;; + +(if (provided? 'array) + (primitive-load-path "ice-9/arrays.scm")) + + +;;; {Keywords} +;;; + +(define (symbol->keyword symbol) + (make-keyword-from-dash-symbol (symbol-append '- symbol))) + +(define (keyword->symbol kw) + (let ((sym (symbol->string (keyword-dash-symbol kw)))) + (string->symbol (substring sym 1 (string-length sym))))) + +(define (kw-arg-ref args kw) + (let ((rem (member kw args))) + (and rem (pair? (cdr rem)) (cadr rem)))) + + + +;;; {Structs} + +(define (struct-layout s) + (struct-ref (struct-vtable s) vtable-index-layout)) + + + +;;; Environments + +(define the-environment + (procedure->syntax + (lambda (x e) + e))) + +(define the-root-environment (the-environment)) + +(define (environment-module env) + (let ((closure (and (pair? env) (car (last-pair env))))) + (and closure (procedure-property closure 'module)))) + + +;;; {Records} +;;; + +;; Printing records: by default, records are printed as +;; +;; # +;; +;; You can change that by giving a custom printing function to +;; MAKE-RECORD-TYPE (after the list of field symbols). This function +;; will be called like +;; +;; ( object port) +;; +;; It should print OBJECT to PORT. + +(define (inherit-print-state old-port new-port) + (if (get-print-state old-port) + (port-with-print-state new-port (get-print-state old-port)) + new-port)) + +;; 0: type-name, 1: fields +(define record-type-vtable + (make-vtable-vtable "prpr" 0 + (lambda (s p) + (cond ((eq? s record-type-vtable) + (display "#" p)) + (else + (display "#" p)))))) + +(define (record-type? obj) + (and (struct? obj) (eq? record-type-vtable (struct-vtable obj)))) + +(define (make-record-type type-name fields . opt) + (let ((printer-fn (and (pair? opt) (car opt)))) + (let ((struct (make-struct record-type-vtable 0 + (make-struct-layout + (apply string-append + (map (lambda (f) "pw") fields))) + (or printer-fn + (lambda (s p) + (display "#<" p) + (display type-name p) + (let loop ((fields fields) + (off 0)) + (cond + ((not (null? fields)) + (display " " p) + (display (car fields) p) + (display ": " p) + (display (struct-ref s off) p) + (loop (cdr fields) (+ 1 off))))) + (display ">" p))) + type-name + (copy-tree fields)))) + ;; Temporary solution: Associate a name to the record type descriptor + ;; so that the object system can create a wrapper class for it. + (set-struct-vtable-name! struct (if (symbol? type-name) + type-name + (string->symbol type-name))) + struct))) + +(define (record-type-name obj) + (if (record-type? obj) + (struct-ref obj vtable-offset-user) + (error 'not-a-record-type obj))) + +(define (record-type-fields obj) + (if (record-type? obj) + (struct-ref obj (+ 1 vtable-offset-user)) + (error 'not-a-record-type obj))) + +(define (record-constructor rtd . opt) + (let ((field-names (if (pair? opt) (car opt) (record-type-fields rtd)))) + (local-eval `(lambda ,field-names + (make-struct ',rtd 0 ,@(map (lambda (f) + (if (memq f field-names) + f + #f)) + (record-type-fields rtd)))) + the-root-environment))) + +(define (record-predicate rtd) + (lambda (obj) (and (struct? obj) (eq? rtd (struct-vtable obj))))) + +(define (record-accessor rtd field-name) + (let* ((pos (list-index (record-type-fields rtd) field-name))) + (if (not pos) + (error 'no-such-field field-name)) + (local-eval `(lambda (obj) + (and (eq? ',rtd (record-type-descriptor obj)) + (struct-ref obj ,pos))) + the-root-environment))) + +(define (record-modifier rtd field-name) + (let* ((pos (list-index (record-type-fields rtd) field-name))) + (if (not pos) + (error 'no-such-field field-name)) + (local-eval `(lambda (obj val) + (and (eq? ',rtd (record-type-descriptor obj)) + (struct-set! obj ,pos val))) + the-root-environment))) + + +(define (record? obj) + (and (struct? obj) (record-type? (struct-vtable obj)))) + +(define (record-type-descriptor obj) + (if (struct? obj) + (struct-vtable obj) + (error 'not-a-record obj))) + +(provide 'record) + + +;;; {Booleans} +;;; + +(define (->bool x) (not (not x))) + + +;;; {Symbols} +;;; + +(define (symbol-append . args) + (string->symbol (apply string-append (map symbol->string args)))) + +(define (list->symbol . args) + (string->symbol (apply list->string args))) + +(define (symbol . args) + (string->symbol (apply string args))) + + +;;; {Lists} +;;; + +(define (list-index l k) + (let loop ((n 0) + (l l)) + (and (not (null? l)) + (if (eq? (car l) k) + n + (loop (+ n 1) (cdr l)))))) + +(define (make-list n . init) + (if (pair? init) (set! init (car init))) + (let loop ((answer '()) + (n n)) + (if (<= n 0) + answer + (loop (cons init answer) (- n 1))))) + + +;;; {and-map and or-map} +;;; +;;; (and-map fn lst) is like (and (fn (car lst)) (fn (cadr lst)) (fn...) ...) +;;; (or-map fn lst) is like (or (fn (car lst)) (fn (cadr lst)) (fn...) ...) +;;; + +;; and-map f l +;; +;; Apply f to successive elements of l until exhaustion or f returns #f. +;; If returning early, return #f. Otherwise, return the last value returned +;; by f. If f has never been called because l is empty, return #t. +;; +(define (and-map f lst) + (let loop ((result #t) + (l lst)) + (and result + (or (and (null? l) + result) + (loop (f (car l)) (cdr l)))))) + +;; or-map f l +;; +;; Apply f to successive elements of l until exhaustion or while f returns #f. +;; If returning early, return the return value of f. +;; +(define (or-map f lst) + (let loop ((result #f) + (l lst)) + (or result + (and (not (null? l)) + (loop (f (car l)) (cdr l)))))) + + + +(if (provided? 'posix) + (primitive-load-path "ice-9/posix.scm")) + +(if (provided? 'socket) + (primitive-load-path "ice-9/networking.scm")) + +(define file-exists? + (if (provided? 'posix) + (lambda (str) + (->bool (false-if-exception (stat str)))) + (lambda (str) + (let ((port (catch 'system-error (lambda () (open-file str OPEN_READ)) + (lambda args #f)))) + (if port (begin (close-port port) #t) + #f))))) + +(define file-is-directory? + (if (provided? 'posix) + (lambda (str) + (eq? (stat:type (stat str)) 'directory)) + (lambda (str) + (let ((port (catch 'system-error + (lambda () (open-file (string-append str "/.") + OPEN_READ)) + (lambda args #f)))) + (if port (begin (close-port port) #t) + #f))))) + +(define (has-suffix? str suffix) + (let ((sufl (string-length suffix)) + (sl (string-length str))) + (and (> sl sufl) + (string=? (substring str (- sl sufl) sl) suffix)))) + +(define (system-error-errno args) + (if (eq? (car args) 'system-error) + (car (list-ref args 4)) + #f)) + + +;;; {Error Handling} +;;; + +(define (error . args) + (save-stack) + (if (null? args) + (scm-error 'misc-error #f "?" #f #f) + (let loop ((msg "~A") + (rest (cdr args))) + (if (not (null? rest)) + (loop (string-append msg " ~S") + (cdr rest)) + (scm-error 'misc-error #f msg args #f))))) + +;; bad-throw is the hook that is called upon a throw to a an unhandled +;; key (unless the throw has four arguments, in which case +;; it's usually interpreted as an error throw.) +;; If the key has a default handler (a throw-handler-default property), +;; it is applied to the throw. +;; +(define (bad-throw key . args) + (let ((default (symbol-property key 'throw-handler-default))) + (or (and default (apply default key args)) + (apply error "unhandled-exception:" key args)))) + + + +(define (tm:sec obj) (vector-ref obj 0)) +(define (tm:min obj) (vector-ref obj 1)) +(define (tm:hour obj) (vector-ref obj 2)) +(define (tm:mday obj) (vector-ref obj 3)) +(define (tm:mon obj) (vector-ref obj 4)) +(define (tm:year obj) (vector-ref obj 5)) +(define (tm:wday obj) (vector-ref obj 6)) +(define (tm:yday obj) (vector-ref obj 7)) +(define (tm:isdst obj) (vector-ref obj 8)) +(define (tm:gmtoff obj) (vector-ref obj 9)) +(define (tm:zone obj) (vector-ref obj 10)) + +(define (set-tm:sec obj val) (vector-set! obj 0 val)) +(define (set-tm:min obj val) (vector-set! obj 1 val)) +(define (set-tm:hour obj val) (vector-set! obj 2 val)) +(define (set-tm:mday obj val) (vector-set! obj 3 val)) +(define (set-tm:mon obj val) (vector-set! obj 4 val)) +(define (set-tm:year obj val) (vector-set! obj 5 val)) +(define (set-tm:wday obj val) (vector-set! obj 6 val)) +(define (set-tm:yday obj val) (vector-set! obj 7 val)) +(define (set-tm:isdst obj val) (vector-set! obj 8 val)) +(define (set-tm:gmtoff obj val) (vector-set! obj 9 val)) +(define (set-tm:zone obj val) (vector-set! obj 10 val)) + +(define (tms:clock obj) (vector-ref obj 0)) +(define (tms:utime obj) (vector-ref obj 1)) +(define (tms:stime obj) (vector-ref obj 2)) +(define (tms:cutime obj) (vector-ref obj 3)) +(define (tms:cstime obj) (vector-ref obj 4)) + +(define file-position ftell) +(define (file-set-position port offset . whence) + (let ((whence (if (eq? whence '()) SEEK_SET (car whence)))) + (seek port offset whence))) + +(define (move->fdes fd/port fd) + (cond ((integer? fd/port) + (dup->fdes fd/port fd) + (close fd/port) + fd) + (else + (primitive-move->fdes fd/port fd) + (set-port-revealed! fd/port 1) + fd/port))) + +(define (release-port-handle port) + (let ((revealed (port-revealed port))) + (if (> revealed 0) + (set-port-revealed! port (- revealed 1))))) + +(define (dup->port port/fd mode . maybe-fd) + (let ((port (fdopen (apply dup->fdes port/fd maybe-fd) + mode))) + (if (pair? maybe-fd) + (set-port-revealed! port 1)) + port)) + +(define (dup->inport port/fd . maybe-fd) + (apply dup->port port/fd "r" maybe-fd)) + +(define (dup->outport port/fd . maybe-fd) + (apply dup->port port/fd "w" maybe-fd)) + +(define (dup port/fd . maybe-fd) + (if (integer? port/fd) + (apply dup->fdes port/fd maybe-fd) + (apply dup->port port/fd (port-mode port/fd) maybe-fd))) + +(define (duplicate-port port modes) + (dup->port port modes)) + +(define (fdes->inport fdes) + (let loop ((rest-ports (fdes->ports fdes))) + (cond ((null? rest-ports) + (let ((result (fdopen fdes "r"))) + (set-port-revealed! result 1) + result)) + ((input-port? (car rest-ports)) + (set-port-revealed! (car rest-ports) + (+ (port-revealed (car rest-ports)) 1)) + (car rest-ports)) + (else + (loop (cdr rest-ports)))))) + +(define (fdes->outport fdes) + (let loop ((rest-ports (fdes->ports fdes))) + (cond ((null? rest-ports) + (let ((result (fdopen fdes "w"))) + (set-port-revealed! result 1) + result)) + ((output-port? (car rest-ports)) + (set-port-revealed! (car rest-ports) + (+ (port-revealed (car rest-ports)) 1)) + (car rest-ports)) + (else + (loop (cdr rest-ports)))))) + +(define (port->fdes port) + (set-port-revealed! port (+ (port-revealed port) 1)) + (fileno port)) + +(define (setenv name value) + (if value + (putenv (string-append name "=" value)) + (putenv name))) + + +;;; {Load Paths} +;;; + +;;; Here for backward compatability +;; +(define scheme-file-suffix (lambda () ".scm")) + +(define (in-vicinity vicinity file) + (let ((tail (let ((len (string-length vicinity))) + (if (zero? len) + #f + (string-ref vicinity (- len 1)))))) + (string-append vicinity + (if (or (not tail) + (eq? tail #\/)) + "" + "/") + file))) + + +;;; {Help for scm_shell} +;;; The argument-processing code used by Guile-based shells generates +;;; Scheme code based on the argument list. This page contains help +;;; functions for the code it generates. + +(define (command-line) (program-arguments)) + +;; This is mostly for the internal use of the code generated by +;; scm_compile_shell_switches. +(define (load-user-init) + (let* ((home (or (getenv "HOME") + (false-if-exception (passwd:dir (getpwuid (getuid)))) + "/")) ;; fallback for cygwin etc. + (init-file (in-vicinity home ".guile"))) + (if (file-exists? init-file) + (primitive-load init-file)))) + + +;;; {Loading by paths} + +;;; Load a Scheme source file named NAME, searching for it in the +;;; directories listed in %load-path, and applying each of the file +;;; name extensions listed in %load-extensions. +(define (load-from-path name) + (start-stack 'load-stack + (primitive-load-path name))) + + + +;;; {Transcendental Functions} +;;; +;;; Derived from "Transcen.scm", Complex trancendental functions for SCM. +;;; Written by Jerry D. Hedden, (C) FSF. +;;; See the file `COPYING' for terms applying to this program. +;;; + +(define (exp z) + (if (real? z) ($exp z) + (make-polar ($exp (real-part z)) (imag-part z)))) + +(define (log z) + (if (and (real? z) (>= z 0)) + ($log z) + (make-rectangular ($log (magnitude z)) (angle z)))) + +(define (sqrt z) + (if (real? z) + (if (negative? z) (make-rectangular 0 ($sqrt (- z))) + ($sqrt z)) + (make-polar ($sqrt (magnitude z)) (/ (angle z) 2)))) + +(define expt + (let ((integer-expt integer-expt)) + (lambda (z1 z2) + (cond ((integer? z2) + (if (negative? z2) + (/ 1 (integer-expt z1 (- z2))) + (integer-expt z1 z2))) + ((and (real? z2) (real? z1) (>= z1 0)) + ($expt z1 z2)) + (else + (exp (* z2 (log z1)))))))) + +(define (sinh z) + (if (real? z) ($sinh z) + (let ((x (real-part z)) (y (imag-part z))) + (make-rectangular (* ($sinh x) ($cos y)) + (* ($cosh x) ($sin y)))))) +(define (cosh z) + (if (real? z) ($cosh z) + (let ((x (real-part z)) (y (imag-part z))) + (make-rectangular (* ($cosh x) ($cos y)) + (* ($sinh x) ($sin y)))))) +(define (tanh z) + (if (real? z) ($tanh z) + (let* ((x (* 2 (real-part z))) + (y (* 2 (imag-part z))) + (w (+ ($cosh x) ($cos y)))) + (make-rectangular (/ ($sinh x) w) (/ ($sin y) w))))) + +(define (asinh z) + (if (real? z) ($asinh z) + (log (+ z (sqrt (+ (* z z) 1)))))) + +(define (acosh z) + (if (and (real? z) (>= z 1)) + ($acosh z) + (log (+ z (sqrt (- (* z z) 1)))))) + +(define (atanh z) + (if (and (real? z) (> z -1) (< z 1)) + ($atanh z) + (/ (log (/ (+ 1 z) (- 1 z))) 2))) + +(define (sin z) + (if (real? z) ($sin z) + (let ((x (real-part z)) (y (imag-part z))) + (make-rectangular (* ($sin x) ($cosh y)) + (* ($cos x) ($sinh y)))))) +(define (cos z) + (if (real? z) ($cos z) + (let ((x (real-part z)) (y (imag-part z))) + (make-rectangular (* ($cos x) ($cosh y)) + (- (* ($sin x) ($sinh y))))))) +(define (tan z) + (if (real? z) ($tan z) + (let* ((x (* 2 (real-part z))) + (y (* 2 (imag-part z))) + (w (+ ($cos x) ($cosh y)))) + (make-rectangular (/ ($sin x) w) (/ ($sinh y) w))))) + +(define (asin z) + (if (and (real? z) (>= z -1) (<= z 1)) + ($asin z) + (* -i (asinh (* +i z))))) + +(define (acos z) + (if (and (real? z) (>= z -1) (<= z 1)) + ($acos z) + (+ (/ (angle -1) 2) (* +i (asinh (* +i z)))))) + +(define (atan z . y) + (if (null? y) + (if (real? z) ($atan z) + (/ (log (/ (- +i z) (+ +i z))) +2i)) + ($atan2 z (car y)))) + +(define (log10 arg) + (/ (log arg) (log 10))) + + + +;;; {Reader Extensions} +;;; + +;;; Reader code for various "#c" forms. +;;; + +(read-hash-extend #\' (lambda (c port) + (read port))) + +(define read-eval? (make-fluid)) +(fluid-set! read-eval? #f) +(read-hash-extend #\. + (lambda (c port) + (if (fluid-ref read-eval?) + (eval (read port) (interaction-environment)) + (error + "#. read expansion found and read-eval? is #f.")))) + + +;;; {Command Line Options} +;;; + +(define (get-option argv kw-opts kw-args return) + (cond + ((null? argv) + (return #f #f argv)) + + ((or (not (eq? #\- (string-ref (car argv) 0))) + (eq? (string-length (car argv)) 1)) + (return 'normal-arg (car argv) (cdr argv))) + + ((eq? #\- (string-ref (car argv) 1)) + (let* ((kw-arg-pos (or (string-index (car argv) #\=) + (string-length (car argv)))) + (kw (symbol->keyword (substring (car argv) 2 kw-arg-pos))) + (kw-opt? (member kw kw-opts)) + (kw-arg? (member kw kw-args)) + (arg (or (and (not (eq? kw-arg-pos (string-length (car argv)))) + (substring (car argv) + (+ kw-arg-pos 1) + (string-length (car argv)))) + (and kw-arg? + (begin (set! argv (cdr argv)) (car argv)))))) + (if (or kw-opt? kw-arg?) + (return kw arg (cdr argv)) + (return 'usage-error kw (cdr argv))))) + + (else + (let* ((char (substring (car argv) 1 2)) + (kw (symbol->keyword char))) + (cond + + ((member kw kw-opts) + (let* ((rest-car (substring (car argv) 2 (string-length (car argv)))) + (new-argv (if (= 0 (string-length rest-car)) + (cdr argv) + (cons (string-append "-" rest-car) (cdr argv))))) + (return kw #f new-argv))) + + ((member kw kw-args) + (let* ((rest-car (substring (car argv) 2 (string-length (car argv)))) + (arg (if (= 0 (string-length rest-car)) + (cadr argv) + rest-car)) + (new-argv (if (= 0 (string-length rest-car)) + (cddr argv) + (cdr argv)))) + (return kw arg new-argv))) + + (else (return 'usage-error kw argv))))))) + +(define (for-next-option proc argv kw-opts kw-args) + (let loop ((argv argv)) + (get-option argv kw-opts kw-args + (lambda (opt opt-arg argv) + (and opt (proc opt opt-arg argv loop)))))) + +(define (display-usage-report kw-desc) + (for-each + (lambda (kw) + (or (eq? (car kw) #t) + (eq? (car kw) 'else) + (let* ((opt-desc kw) + (help (cadr opt-desc)) + (opts (car opt-desc)) + (opts-proper (if (string? (car opts)) (cdr opts) opts)) + (arg-name (if (string? (car opts)) + (string-append "<" (car opts) ">") + "")) + (left-part (string-append + (with-output-to-string + (lambda () + (map (lambda (x) (display (keyword->symbol x)) (display " ")) + opts-proper))) + arg-name)) + (middle-part (if (and (< (string-length left-part) 30) + (< (string-length help) 40)) + (make-string (- 30 (string-length left-part)) #\ ) + "\n\t"))) + (display left-part) + (display middle-part) + (display help) + (newline)))) + kw-desc)) + + + +(define (transform-usage-lambda cases) + (let* ((raw-usage (delq! 'else (map car cases))) + (usage-sans-specials (map (lambda (x) + (or (and (not (list? x)) x) + (and (symbol? (car x)) #t) + (and (boolean? (car x)) #t) + x)) + raw-usage)) + (usage-desc (delq! #t usage-sans-specials)) + (kw-desc (map car usage-desc)) + (kw-opts (apply append (map (lambda (x) (and (not (string? (car x))) x)) kw-desc))) + (kw-args (apply append (map (lambda (x) (and (string? (car x)) (cdr x))) kw-desc))) + (transmogrified-cases (map (lambda (case) + (cons (let ((opts (car case))) + (if (or (boolean? opts) (eq? 'else opts)) + opts + (cond + ((symbol? (car opts)) opts) + ((boolean? (car opts)) opts) + ((string? (caar opts)) (cdar opts)) + (else (car opts))))) + (cdr case))) + cases))) + `(let ((%display-usage (lambda () (display-usage-report ',usage-desc)))) + (lambda (%argv) + (let %next-arg ((%argv %argv)) + (get-option %argv + ',kw-opts + ',kw-args + (lambda (%opt %arg %new-argv) + (case %opt + ,@ transmogrified-cases)))))))) + + + + +;;; {Low Level Modules} +;;; +;;; These are the low level data structures for modules. +;;; +;;; !!! warning: The interface to lazy binder procedures is going +;;; to be changed in an incompatible way to permit all the basic +;;; module ops to be virtualized. +;;; +;;; (make-module size use-list lazy-binding-proc) => module +;;; module-{obarray,uses,binder}[|-set!] +;;; (module? obj) => [#t|#f] +;;; (module-locally-bound? module symbol) => [#t|#f] +;;; (module-bound? module symbol) => [#t|#f] +;;; (module-symbol-locally-interned? module symbol) => [#t|#f] +;;; (module-symbol-interned? module symbol) => [#t|#f] +;;; (module-local-variable module symbol) => [# | #f] +;;; (module-variable module symbol) => [# | #f] +;;; (module-symbol-binding module symbol opt-value) +;;; => [ | opt-value | an error occurs ] +;;; (module-make-local-var! module symbol) => # +;;; (module-add! module symbol var) => unspecified +;;; (module-remove! module symbol) => unspecified +;;; (module-for-each proc module) => unspecified +;;; (make-scm-module) => module ; a lazy copy of the symhash module +;;; (set-current-module module) => unspecified +;;; (current-module) => # +;;; +;;; + + +;;; {Printing Modules} +;; This is how modules are printed. You can re-define it. +;; (Redefining is actually more complicated than simply redefining +;; %print-module because that would only change the binding and not +;; the value stored in the vtable that determines how record are +;; printed. Sigh.) + +(define (%print-module mod port) ; unused args: depth length style table) + (display "#<" port) + (display (or (module-kind mod) "module") port) + (let ((name (module-name mod))) + (if name + (begin + (display " " port) + (display name port)))) + (display " " port) + (display (number->string (object-address mod) 16) port) + (display ">" port)) + +;; module-type +;; +;; A module is characterized by an obarray in which local symbols +;; are interned, a list of modules, "uses", from which non-local +;; bindings can be inherited, and an optional lazy-binder which +;; is a (CLOSURE module symbol) which, as a last resort, can provide +;; bindings that would otherwise not be found locally in the module. +;; +;; NOTE: If you change here, you also need to change libguile/modules.h. +;; +(define module-type + (make-record-type 'module + '(obarray uses binder eval-closure transformer name kind + observers weak-observers observer-id) + %print-module)) + +;; make-module &opt size uses binder +;; +;; Create a new module, perhaps with a particular size of obarray, +;; initial uses list, or binding procedure. +;; +(define make-module + (lambda args + + (define (parse-arg index default) + (if (> (length args) index) + (list-ref args index) + default)) + + (if (> (length args) 3) + (error "Too many args to make-module." args)) + + (let ((size (parse-arg 0 1021)) + (uses (parse-arg 1 '())) + (binder (parse-arg 2 #f))) + + (if (not (integer? size)) + (error "Illegal size to make-module." size)) + (if (not (and (list? uses) + (and-map module? uses))) + (error "Incorrect use list." uses)) + (if (and binder (not (procedure? binder))) + (error + "Lazy-binder expected to be a procedure or #f." binder)) + + (let ((module (module-constructor (make-vector size '()) + uses binder #f #f #f #f + '() + (make-weak-value-hash-table 31) + 0))) + + ;; We can't pass this as an argument to module-constructor, + ;; because we need it to close over a pointer to the module + ;; itself. + (set-module-eval-closure! module (standard-eval-closure module)) + + module)))) + +(define module-constructor (record-constructor module-type)) +(define module-obarray (record-accessor module-type 'obarray)) +(define set-module-obarray! (record-modifier module-type 'obarray)) +(define module-uses (record-accessor module-type 'uses)) +(define set-module-uses! (record-modifier module-type 'uses)) +(define module-binder (record-accessor module-type 'binder)) +(define set-module-binder! (record-modifier module-type 'binder)) + +;; NOTE: This binding is used in libguile/modules.c. +(define module-eval-closure (record-accessor module-type 'eval-closure)) + +(define module-transformer (record-accessor module-type 'transformer)) +(define set-module-transformer! (record-modifier module-type 'transformer)) +(define module-name (record-accessor module-type 'name)) +(define set-module-name! (record-modifier module-type 'name)) +(define module-kind (record-accessor module-type 'kind)) +(define set-module-kind! (record-modifier module-type 'kind)) +(define module-observers (record-accessor module-type 'observers)) +(define set-module-observers! (record-modifier module-type 'observers)) +(define module-weak-observers (record-accessor module-type 'weak-observers)) +(define module-observer-id (record-accessor module-type 'observer-id)) +(define set-module-observer-id! (record-modifier module-type 'observer-id)) +(define module? (record-predicate module-type)) + +(define set-module-eval-closure! + (let ((setter (record-modifier module-type 'eval-closure))) + (lambda (module closure) + (setter module closure) + ;; Make it possible to lookup the module from the environment. + ;; This implementation is correct since an eval closure can belong + ;; to maximally one module. + (set-procedure-property! closure 'module module)))) + +(begin-deprecated + (define (eval-in-module exp mod) + (issue-deprecation-warning + "`eval-in-module' is deprecated. Use `eval' instead.") + (eval exp mod))) + + +;;; {Observer protocol} +;;; + +(define (module-observe module proc) + (set-module-observers! module (cons proc (module-observers module))) + (cons module proc)) + +(define (module-observe-weak module proc) + (let ((id (module-observer-id module))) + (hash-set! (module-weak-observers module) id proc) + (set-module-observer-id! module (+ 1 id)) + (cons module id))) + +(define (module-unobserve token) + (let ((module (car token)) + (id (cdr token))) + (if (integer? id) + (hash-remove! (module-weak-observers module) id) + (set-module-observers! module (delq1! id (module-observers module))))) + *unspecified*) + +(define (module-modified m) + (for-each (lambda (proc) (proc m)) (module-observers m)) + (hash-fold (lambda (id proc res) (proc m)) #f (module-weak-observers m))) + + +;;; {Module Searching in General} +;;; +;;; We sometimes want to look for properties of a symbol +;;; just within the obarray of one module. If the property +;;; holds, then it is said to hold ``locally'' as in, ``The symbol +;;; DISPLAY is locally rebound in the module `safe-guile'.'' +;;; +;;; +;;; Other times, we want to test for a symbol property in the obarray +;;; of M and, if it is not found there, try each of the modules in the +;;; uses list of M. This is the normal way of testing for some +;;; property, so we state these properties without qualification as +;;; in: ``The symbol 'fnord is interned in module M because it is +;;; interned locally in module M2 which is a member of the uses list +;;; of M.'' +;;; + +;; module-search fn m +;; +;; return the first non-#f result of FN applied to M and then to +;; the modules in the uses of m, and so on recursively. If all applications +;; return #f, then so does this function. +;; +(define (module-search fn m v) + (define (loop pos) + (and (pair? pos) + (or (module-search fn (car pos) v) + (loop (cdr pos))))) + (or (fn m v) + (loop (module-uses m)))) + + +;;; {Is a symbol bound in a module?} +;;; +;;; Symbol S in Module M is bound if S is interned in M and if the binding +;;; of S in M has been set to some well-defined value. +;;; + +;; module-locally-bound? module symbol +;; +;; Is a symbol bound (interned and defined) locally in a given module? +;; +(define (module-locally-bound? m v) + (let ((var (module-local-variable m v))) + (and var + (variable-bound? var)))) + +;; module-bound? module symbol +;; +;; Is a symbol bound (interned and defined) anywhere in a given module +;; or its uses? +;; +(define (module-bound? m v) + (module-search module-locally-bound? m v)) + +;;; {Is a symbol interned in a module?} +;;; +;;; Symbol S in Module M is interned if S occurs in +;;; of S in M has been set to some well-defined value. +;;; +;;; It is possible to intern a symbol in a module without providing +;;; an initial binding for the corresponding variable. This is done +;;; with: +;;; (module-add! module symbol (make-undefined-variable)) +;;; +;;; In that case, the symbol is interned in the module, but not +;;; bound there. The unbound symbol shadows any binding for that +;;; symbol that might otherwise be inherited from a member of the uses list. +;;; + +(define (module-obarray-get-handle ob key) + ((if (symbol? key) hashq-get-handle hash-get-handle) ob key)) + +(define (module-obarray-ref ob key) + ((if (symbol? key) hashq-ref hash-ref) ob key)) + +(define (module-obarray-set! ob key val) + ((if (symbol? key) hashq-set! hash-set!) ob key val)) + +(define (module-obarray-remove! ob key) + ((if (symbol? key) hashq-remove! hash-remove!) ob key)) + +;; module-symbol-locally-interned? module symbol +;; +;; is a symbol interned (not neccessarily defined) locally in a given module +;; or its uses? Interned symbols shadow inherited bindings even if +;; they are not themselves bound to a defined value. +;; +(define (module-symbol-locally-interned? m v) + (not (not (module-obarray-get-handle (module-obarray m) v)))) + +;; module-symbol-interned? module symbol +;; +;; is a symbol interned (not neccessarily defined) anywhere in a given module +;; or its uses? Interned symbols shadow inherited bindings even if +;; they are not themselves bound to a defined value. +;; +(define (module-symbol-interned? m v) + (module-search module-symbol-locally-interned? m v)) + + +;;; {Mapping modules x symbols --> variables} +;;; + +;; module-local-variable module symbol +;; return the local variable associated with a MODULE and SYMBOL. +;; +;;; This function is very important. It is the only function that can +;;; return a variable from a module other than the mutators that store +;;; new variables in modules. Therefore, this function is the location +;;; of the "lazy binder" hack. +;;; +;;; If symbol is defined in MODULE, and if the definition binds symbol +;;; to a variable, return that variable object. +;;; +;;; If the symbols is not found at first, but the module has a lazy binder, +;;; then try the binder. +;;; +;;; If the symbol is not found at all, return #f. +;;; +(define (module-local-variable m v) +; (caddr +; (list m v + (let ((b (module-obarray-ref (module-obarray m) v))) + (or (and (variable? b) b) + (and (module-binder m) + ((module-binder m) m v #f))))) +;)) + +;; module-variable module symbol +;; +;; like module-local-variable, except search the uses in the +;; case V is not found in M. +;; +;; NOTE: This function is superseded with C code (see modules.c) +;;; when using the standard eval closure. +;; +(define (module-variable m v) + (module-search module-local-variable m v)) + + +;;; {Mapping modules x symbols --> bindings} +;;; +;;; These are similar to the mapping to variables, except that the +;;; variable is dereferenced. +;;; + +;; module-symbol-binding module symbol opt-value +;; +;; return the binding of a variable specified by name within +;; a given module, signalling an error if the variable is unbound. +;; If the OPT-VALUE is passed, then instead of signalling an error, +;; return OPT-VALUE. +;; +(define (module-symbol-local-binding m v . opt-val) + (let ((var (module-local-variable m v))) + (if var + (variable-ref var) + (if (not (null? opt-val)) + (car opt-val) + (error "Locally unbound variable." v))))) + +;; module-symbol-binding module symbol opt-value +;; +;; return the binding of a variable specified by name within +;; a given module, signalling an error if the variable is unbound. +;; If the OPT-VALUE is passed, then instead of signalling an error, +;; return OPT-VALUE. +;; +(define (module-symbol-binding m v . opt-val) + (let ((var (module-variable m v))) + (if var + (variable-ref var) + (if (not (null? opt-val)) + (car opt-val) + (error "Unbound variable." v))))) + + + +;;; {Adding Variables to Modules} +;;; +;;; + + +;; module-make-local-var! module symbol +;; +;; ensure a variable for V in the local namespace of M. +;; If no variable was already there, then create a new and uninitialzied +;; variable. +;; +(define (module-make-local-var! m v) + (or (let ((b (module-obarray-ref (module-obarray m) v))) + (and (variable? b) + (begin + (module-modified m) + b))) + (and (module-binder m) + ((module-binder m) m v #t)) + (begin + (let ((answer (make-undefined-variable))) + (variable-set-name-hint! answer v) + (module-obarray-set! (module-obarray m) v answer) + (module-modified m) + answer)))) + +;; module-ensure-local-variable! module symbol +;; +;; Ensure that there is a local variable in MODULE for SYMBOL. If +;; there is no binding for SYMBOL, create a new uninitialized +;; variable. Return the local variable. +;; +(define (module-ensure-local-variable! module symbol) + (or (module-local-variable module symbol) + (let ((var (make-undefined-variable))) + (variable-set-name-hint! var symbol) + (module-add! module symbol var) + var))) + +;; module-add! module symbol var +;; +;; ensure a particular variable for V in the local namespace of M. +;; +(define (module-add! m v var) + (if (not (variable? var)) + (error "Bad variable to module-add!" var)) + (module-obarray-set! (module-obarray m) v var) + (module-modified m)) + +;; module-remove! +;; +;; make sure that a symbol is undefined in the local namespace of M. +;; +(define (module-remove! m v) + (module-obarray-remove! (module-obarray m) v) + (module-modified m)) + +(define (module-clear! m) + (vector-fill! (module-obarray m) '()) + (module-modified m)) + +;; MODULE-FOR-EACH -- exported +;; +;; Call PROC on each symbol in MODULE, with arguments of (SYMBOL VARIABLE). +;; +(define (module-for-each proc module) + (let ((obarray (module-obarray module))) + (do ((index 0 (+ index 1)) + (end (vector-length obarray))) + ((= index end)) + (for-each + (lambda (bucket) + (proc (car bucket) (cdr bucket))) + (vector-ref obarray index))))) + + +(define (module-map proc module) + (let* ((obarray (module-obarray module)) + (end (vector-length obarray))) + + (let loop ((i 0) + (answer '())) + (if (= i end) + answer + (loop (+ 1 i) + (append! + (map (lambda (bucket) + (proc (car bucket) (cdr bucket))) + (vector-ref obarray i)) + answer)))))) + + +;;; {Low Level Bootstrapping} +;;; + +;; make-root-module + +;; A root module uses the pre-modules-obarray as its obarray. This +;; special obarray accumulates all bindings that have been established +;; before the module system is fully booted. +;; +;; (The obarray continues to be used by code that has been closed over +;; before the module system has been booted.) + +(define (make-root-module) + (let ((m (make-module 0))) + (set-module-obarray! m (%get-pre-modules-obarray)) + m)) + +;; make-scm-module + +;; The root interface is a module that uses the same obarray as the +;; root module. It does not allow new definitions, tho. + +(define (make-scm-module) + (let ((m (make-module 0))) + (set-module-obarray! m (%get-pre-modules-obarray)) + (set-module-eval-closure! m (standard-interface-eval-closure m)) + m)) + + + +;;; {Module-based Loading} +;;; + +(define (save-module-excursion thunk) + (let ((inner-module (current-module)) + (outer-module #f)) + (dynamic-wind (lambda () + (set! outer-module (current-module)) + (set-current-module inner-module) + (set! inner-module #f)) + thunk + (lambda () + (set! inner-module (current-module)) + (set-current-module outer-module) + (set! outer-module #f))))) + +(define basic-load load) + +(define (load-module filename) + (save-module-excursion + (lambda () + (let ((oldname (and (current-load-port) + (port-filename (current-load-port))))) + (basic-load (if (and oldname + (> (string-length filename) 0) + (not (char=? (string-ref filename 0) #\/)) + (not (string=? (dirname oldname) "."))) + (string-append (dirname oldname) "/" filename) + filename)))))) + + + +;;; {MODULE-REF -- exported} +;; +;; Returns the value of a variable called NAME in MODULE or any of its +;; used modules. If there is no such variable, then if the optional third +;; argument DEFAULT is present, it is returned; otherwise an error is signaled. +;; +(define (module-ref module name . rest) + (let ((variable (module-variable module name))) + (if (and variable (variable-bound? variable)) + (variable-ref variable) + (if (null? rest) + (error "No variable named" name 'in module) + (car rest) ; default value + )))) + +;; MODULE-SET! -- exported +;; +;; Sets the variable called NAME in MODULE (or in a module that MODULE uses) +;; to VALUE; if there is no such variable, an error is signaled. +;; +(define (module-set! module name value) + (let ((variable (module-variable module name))) + (if variable + (variable-set! variable value) + (error "No variable named" name 'in module)))) + +;; MODULE-DEFINE! -- exported +;; +;; Sets the variable called NAME in MODULE to VALUE; if there is no such +;; variable, it is added first. +;; +(define (module-define! module name value) + (let ((variable (module-local-variable module name))) + (if variable + (begin + (variable-set! variable value) + (module-modified module)) + (let ((variable (make-variable value))) + (variable-set-name-hint! variable name) + (module-add! module name variable))))) + +;; MODULE-DEFINED? -- exported +;; +;; Return #t iff NAME is defined in MODULE (or in a module that MODULE +;; uses) +;; +(define (module-defined? module name) + (let ((variable (module-variable module name))) + (and variable (variable-bound? variable)))) + +;; MODULE-USE! module interface +;; +;; Add INTERFACE to the list of interfaces used by MODULE. +;; +(define (module-use! module interface) + (set-module-uses! module + (cons interface (delq! interface (module-uses module)))) + (module-modified module)) + + +;;; {Recursive Namespaces} +;;; +;;; +;;; A hierarchical namespace emerges if we consider some module to be +;;; root, and variables bound to modules as nested namespaces. +;;; +;;; The routines in this file manage variable names in hierarchical namespace. +;;; Each variable name is a list of elements, looked up in successively nested +;;; modules. +;;; +;;; (nested-ref some-root-module '(foo bar baz)) +;;; => +;;; +;;; +;;; There are: +;;; +;;; ;; a-root is a module +;;; ;; name is a list of symbols +;;; +;;; nested-ref a-root name +;;; nested-set! a-root name val +;;; nested-define! a-root name val +;;; nested-remove! a-root name +;;; +;;; +;;; (current-module) is a natural choice for a-root so for convenience there are +;;; also: +;;; +;;; local-ref name == nested-ref (current-module) name +;;; local-set! name val == nested-set! (current-module) name val +;;; local-define! name val == nested-define! (current-module) name val +;;; local-remove! name == nested-remove! (current-module) name +;;; + + +(define (nested-ref root names) + (let loop ((cur root) + (elts names)) + (cond + ((null? elts) cur) + ((not (module? cur)) #f) + (else (loop (module-ref cur (car elts) #f) (cdr elts)))))) + +(define (nested-set! root names val) + (let loop ((cur root) + (elts names)) + (if (null? (cdr elts)) + (module-set! cur (car elts) val) + (loop (module-ref cur (car elts)) (cdr elts))))) + +(define (nested-define! root names val) + (let loop ((cur root) + (elts names)) + (if (null? (cdr elts)) + (module-define! cur (car elts) val) + (loop (module-ref cur (car elts)) (cdr elts))))) + +(define (nested-remove! root names) + (let loop ((cur root) + (elts names)) + (if (null? (cdr elts)) + (module-remove! cur (car elts)) + (loop (module-ref cur (car elts)) (cdr elts))))) + +(define (local-ref names) (nested-ref (current-module) names)) +(define (local-set! names val) (nested-set! (current-module) names val)) +(define (local-define names val) (nested-define! (current-module) names val)) +(define (local-remove names) (nested-remove! (current-module) names)) +;;; boot-9.scm ends here Added: external/Pygments-0.8.1/tests/examplefiles/ceval.c ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/ceval.c Thu Aug 9 17:43:13 2007 @@ -0,0 +1,2604 @@ + +/* Execute compiled code */ + +/* XXX TO DO: + XXX speed up searching for keywords by using a dictionary + XXX document it! + */ + +/* enable more aggressive intra-module optimizations, where available */ +#define PY_LOCAL_AGGRESSIVE + +#include "Python.h" + +#include "code.h" +#include "frameobject.h" +#include "eval.h" +#include "opcode.h" +#include "structmember.h" + +#include + +#ifndef WITH_TSC + +#define READ_TIMESTAMP(var) + +#else + +typedef unsigned long long uint64; + +#if defined(__ppc__) /* <- Don't know if this is the correct symbol; this + section should work for GCC on any PowerPC platform, + irrespective of OS. POWER? Who knows :-) */ + +#define READ_TIMESTAMP(var) ppc_getcounter(&var) + +static void +ppc_getcounter(uint64 *v) +{ + register unsigned long tbu, tb, tbu2; + + loop: + asm volatile ("mftbu %0" : "=r" (tbu) ); + asm volatile ("mftb %0" : "=r" (tb) ); + asm volatile ("mftbu %0" : "=r" (tbu2)); + if (__builtin_expect(tbu != tbu2, 0)) goto loop; + + /* The slightly peculiar way of writing the next lines is + compiled better by GCC than any other way I tried. */ + ((long*)(v))[0] = tbu; + ((long*)(v))[1] = tb; +} + +#else /* this is for linux/x86 (and probably any other GCC/x86 combo) */ + +#define READ_TIMESTAMP(val) \ + __asm__ __volatile__("rdtsc" : "=A" (val)) + +#endif + +void dump_tsc(int opcode, int ticked, uint64 inst0, uint64 inst1, + uint64 loop0, uint64 loop1, uint64 intr0, uint64 intr1) +{ + uint64 intr, inst, loop; + PyThreadState *tstate = PyThreadState_Get(); + if (!tstate->interp->tscdump) + return; + intr = intr1 - intr0; + inst = inst1 - inst0 - intr; + loop = loop1 - loop0 - intr; + fprintf(stderr, "opcode=%03d t=%d inst=%06lld loop=%06lld\n", + opcode, ticked, inst, loop); +} + +#endif + +/* Turn this on if your compiler chokes on the big switch: */ +/* #define CASE_TOO_BIG 1 */ + +#ifdef Py_DEBUG +/* For debugging the interpreter: */ +#define LLTRACE 1 /* Low-level trace feature */ +#define CHECKEXC 1 /* Double-check exception checking */ +#endif + +typedef PyObject *(*callproc)(PyObject *, PyObject *, PyObject *); + +/* Forward declarations */ +#ifdef WITH_TSC +static PyObject * call_function(PyObject ***, int, uint64*, uint64*); +#else +static PyObject * call_function(PyObject ***, int); +#endif +static PyObject * fast_function(PyObject *, PyObject ***, int, int, int); +static PyObject * do_call(PyObject *, PyObject ***, int, int); +static PyObject * ext_do_call(PyObject *, PyObject ***, int, int, int); +static PyObject * update_keyword_args(PyObject *, int, PyObject ***,PyObject *); +static PyObject * update_star_args(int, int, PyObject *, PyObject ***); +static PyObject * load_args(PyObject ***, int); +#define CALL_FLAG_VAR 1 +#define CALL_FLAG_KW 2 + +#ifdef LLTRACE +static int lltrace; +static int prtrace(PyObject *, char *); +#endif +static int call_trace(Py_tracefunc, PyObject *, PyFrameObject *, + int, PyObject *); +static void call_trace_protected(Py_tracefunc, PyObject *, + PyFrameObject *, int, PyObject *); +static void call_exc_trace(Py_tracefunc, PyObject *, PyFrameObject *); +static int maybe_call_line_trace(Py_tracefunc, PyObject *, + PyFrameObject *, int *, int *, int *); + +static PyObject * apply_slice(PyObject *, PyObject *, PyObject *); +static int assign_slice(PyObject *, PyObject *, + PyObject *, PyObject *); +static PyObject * cmp_outcome(int, PyObject *, PyObject *); +static PyObject * import_from(PyObject *, PyObject *); +static int import_all_from(PyObject *, PyObject *); +static PyObject * build_class(PyObject *, PyObject *, PyObject *); +static int exec_statement(PyFrameObject *, + PyObject *, PyObject *, PyObject *); +static void set_exc_info(PyThreadState *, PyObject *, PyObject *, PyObject *); +static void reset_exc_info(PyThreadState *); +static void format_exc_check_arg(PyObject *, char *, PyObject *); +static PyObject * string_concatenate(PyObject *, PyObject *, + PyFrameObject *, unsigned char *); + +#define NAME_ERROR_MSG \ + "name '%.200s' is not defined" +#define GLOBAL_NAME_ERROR_MSG \ + "global name '%.200s' is not defined" +#define UNBOUNDLOCAL_ERROR_MSG \ + "local variable '%.200s' referenced before assignment" +#define UNBOUNDFREE_ERROR_MSG \ + "free variable '%.200s' referenced before assignment" \ + " in enclosing scope" + +/* Dynamic execution profile */ +#ifdef DYNAMIC_EXECUTION_PROFILE +#ifdef DXPAIRS +static long dxpairs[257][256]; +#define dxp dxpairs[256] +#else +static long dxp[256]; +#endif +#endif + +/* Function call profile */ +#ifdef CALL_PROFILE +#define PCALL_NUM 11 +static int pcall[PCALL_NUM]; + +#define PCALL_ALL 0 +#define PCALL_FUNCTION 1 +#define PCALL_FAST_FUNCTION 2 +#define PCALL_FASTER_FUNCTION 3 +#define PCALL_METHOD 4 +#define PCALL_BOUND_METHOD 5 +#define PCALL_CFUNCTION 6 +#define PCALL_TYPE 7 +#define PCALL_GENERATOR 8 +#define PCALL_OTHER 9 +#define PCALL_POP 10 + +/* Notes about the statistics + + PCALL_FAST stats + + FAST_FUNCTION means no argument tuple needs to be created. + FASTER_FUNCTION means that the fast-path frame setup code is used. + + If there is a method call where the call can be optimized by changing + the argument tuple and calling the function directly, it gets recorded + twice. + + As a result, the relationship among the statistics appears to be + PCALL_ALL == PCALL_FUNCTION + PCALL_METHOD - PCALL_BOUND_METHOD + + PCALL_CFUNCTION + PCALL_TYPE + PCALL_GENERATOR + PCALL_OTHER + PCALL_FUNCTION > PCALL_FAST_FUNCTION > PCALL_FASTER_FUNCTION + PCALL_METHOD > PCALL_BOUND_METHOD +*/ + +#define PCALL(POS) pcall[POS]++ + +PyObject * +PyEval_GetCallStats(PyObject *self) +{ + return Py_BuildValue("iiiiiiiiii", + pcall[0], pcall[1], pcall[2], pcall[3], + pcall[4], pcall[5], pcall[6], pcall[7], + pcall[8], pcall[9]); +} +#else +#define PCALL(O) + +PyObject * +PyEval_GetCallStats(PyObject *self) +{ + Py_INCREF(Py_None); + return Py_None; +} +#endif + + +#ifdef WITH_THREAD + +#ifdef HAVE_ERRNO_H +#include +#endif +#include "pythread.h" + +static PyThread_type_lock interpreter_lock = 0; /* This is the GIL */ +static long main_thread = 0; + +int +PyEval_ThreadsInitialized(void) +{ + return interpreter_lock != 0; +} + +void +PyEval_InitThreads(void) +{ + if (interpreter_lock) + return; + interpreter_lock = PyThread_allocate_lock(); + PyThread_acquire_lock(interpreter_lock, 1); + main_thread = PyThread_get_thread_ident(); +} + +void +PyEval_AcquireLock(void) +{ + PyThread_acquire_lock(interpreter_lock, 1); +} + +void +PyEval_ReleaseLock(void) +{ + PyThread_release_lock(interpreter_lock); +} + +void +PyEval_AcquireThread(PyThreadState *tstate) +{ + if (tstate == NULL) + Py_FatalError("PyEval_AcquireThread: NULL new thread state"); + /* Check someone has called PyEval_InitThreads() to create the lock */ + assert(interpreter_lock); + PyThread_acquire_lock(interpreter_lock, 1); + if (PyThreadState_Swap(tstate) != NULL) + Py_FatalError( + "PyEval_AcquireThread: non-NULL old thread state"); +} + +void +PyEval_ReleaseThread(PyThreadState *tstate) +{ + if (tstate == NULL) + Py_FatalError("PyEval_ReleaseThread: NULL thread state"); + if (PyThreadState_Swap(NULL) != tstate) + Py_FatalError("PyEval_ReleaseThread: wrong thread state"); + PyThread_release_lock(interpreter_lock); +} + +/* This function is called from PyOS_AfterFork to ensure that newly + created child processes don't hold locks referring to threads which + are not running in the child process. (This could also be done using + pthread_atfork mechanism, at least for the pthreads implementation.) */ + +void +PyEval_ReInitThreads(void) +{ + if (!interpreter_lock) + return; + /*XXX Can't use PyThread_free_lock here because it does too + much error-checking. Doing this cleanly would require + adding a new function to each thread_*.h. Instead, just + create a new lock and waste a little bit of memory */ + interpreter_lock = PyThread_allocate_lock(); + PyThread_acquire_lock(interpreter_lock, 1); + main_thread = PyThread_get_thread_ident(); +} +#endif + +/* Functions save_thread and restore_thread are always defined so + dynamically loaded modules needn't be compiled separately for use + with and without threads: */ + +PyThreadState * +PyEval_SaveThread(void) +{ + PyThreadState *tstate = PyThreadState_Swap(NULL); + if (tstate == NULL) + Py_FatalError("PyEval_SaveThread: NULL tstate"); +#ifdef WITH_THREAD + if (interpreter_lock) + PyThread_release_lock(interpreter_lock); +#endif + return tstate; +} + +void +PyEval_RestoreThread(PyThreadState *tstate) +{ + if (tstate == NULL) + Py_FatalError("PyEval_RestoreThread: NULL tstate"); +#ifdef WITH_THREAD + if (interpreter_lock) { + int err = errno; + PyThread_acquire_lock(interpreter_lock, 1); + errno = err; + } +#endif + PyThreadState_Swap(tstate); +} + + +/* Mechanism whereby asynchronously executing callbacks (e.g. UNIX + signal handlers or Mac I/O completion routines) can schedule calls + to a function to be called synchronously. + The synchronous function is called with one void* argument. + It should return 0 for success or -1 for failure -- failure should + be accompanied by an exception. + + If registry succeeds, the registry function returns 0; if it fails + (e.g. due to too many pending calls) it returns -1 (without setting + an exception condition). + + Note that because registry may occur from within signal handlers, + or other asynchronous events, calling malloc() is unsafe! + +#ifdef WITH_THREAD + Any thread can schedule pending calls, but only the main thread + will execute them. +#endif + + XXX WARNING! ASYNCHRONOUSLY EXECUTING CODE! + There are two possible race conditions: + (1) nested asynchronous registry calls; + (2) registry calls made while pending calls are being processed. + While (1) is very unlikely, (2) is a real possibility. + The current code is safe against (2), but not against (1). + The safety against (2) is derived from the fact that only one + thread (the main thread) ever takes things out of the queue. + + XXX Darn! With the advent of thread state, we should have an array + of pending calls per thread in the thread state! Later... +*/ + +#define NPENDINGCALLS 32 +static struct { + int (*func)(void *); + void *arg; +} pendingcalls[NPENDINGCALLS]; +static volatile int pendingfirst = 0; +static volatile int pendinglast = 0; +static volatile int things_to_do = 0; + +int +Py_AddPendingCall(int (*func)(void *), void *arg) +{ + static volatile int busy = 0; + int i, j; + /* XXX Begin critical section */ + /* XXX If you want this to be safe against nested + XXX asynchronous calls, you'll have to work harder! */ + if (busy) + return -1; + busy = 1; + i = pendinglast; + j = (i + 1) % NPENDINGCALLS; + if (j == pendingfirst) { + busy = 0; + return -1; /* Queue full */ + } + pendingcalls[i].func = func; + pendingcalls[i].arg = arg; + pendinglast = j; + + _Py_Ticker = 0; + things_to_do = 1; /* Signal main loop */ + busy = 0; + /* XXX End critical section */ + return 0; +} + +int +Py_MakePendingCalls(void) +{ + static int busy = 0; +#ifdef WITH_THREAD + if (main_thread && PyThread_get_thread_ident() != main_thread) + return 0; +#endif + if (busy) + return 0; + busy = 1; + things_to_do = 0; + for (;;) { + int i; + int (*func)(void *); + void *arg; + i = pendingfirst; + if (i == pendinglast) + break; /* Queue empty */ + func = pendingcalls[i].func; + arg = pendingcalls[i].arg; + pendingfirst = (i + 1) % NPENDINGCALLS; + if (func(arg) < 0) { + busy = 0; + things_to_do = 1; /* We're not done yet */ + return -1; + } + } + busy = 0; + return 0; +} + + +/* The interpreter's recursion limit */ + +#ifndef Py_DEFAULT_RECURSION_LIMIT +#define Py_DEFAULT_RECURSION_LIMIT 1000 +#endif +static int recursion_limit = Py_DEFAULT_RECURSION_LIMIT; +int _Py_CheckRecursionLimit = Py_DEFAULT_RECURSION_LIMIT; + +int +Py_GetRecursionLimit(void) +{ + return recursion_limit; +} + +void +Py_SetRecursionLimit(int new_limit) +{ + recursion_limit = new_limit; + _Py_CheckRecursionLimit = recursion_limit; +} + +/* the macro Py_EnterRecursiveCall() only calls _Py_CheckRecursiveCall() + if the recursion_depth reaches _Py_CheckRecursionLimit. + If USE_STACKCHECK, the macro decrements _Py_CheckRecursionLimit + to guarantee that _Py_CheckRecursiveCall() is regularly called. + Without USE_STACKCHECK, there is no need for this. */ +int +_Py_CheckRecursiveCall(char *where) +{ + PyThreadState *tstate = PyThreadState_GET(); + +#ifdef USE_STACKCHECK + if (PyOS_CheckStack()) { + --tstate->recursion_depth; + PyErr_SetString(PyExc_MemoryError, "Stack overflow"); + return -1; + } +#endif + if (tstate->recursion_depth > recursion_limit) { + --tstate->recursion_depth; + PyErr_Format(PyExc_RuntimeError, + "maximum recursion depth exceeded%s", + where); + return -1; + } + _Py_CheckRecursionLimit = recursion_limit; + return 0; +} + +/* Status code for main loop (reason for stack unwind) */ +enum why_code { + WHY_NOT = 0x0001, /* No error */ + WHY_EXCEPTION = 0x0002, /* Exception occurred */ + WHY_RERAISE = 0x0004, /* Exception re-raised by 'finally' */ + WHY_RETURN = 0x0008, /* 'return' statement */ + WHY_BREAK = 0x0010, /* 'break' statement */ + WHY_CONTINUE = 0x0020, /* 'continue' statement */ + WHY_YIELD = 0x0040 /* 'yield' operator */ +}; + +static enum why_code do_raise(PyObject *, PyObject *, PyObject *); +static int unpack_iterable(PyObject *, int, PyObject **); + +/* for manipulating the thread switch and periodic "stuff" - used to be + per thread, now just a pair o' globals */ +int _Py_CheckInterval = 100; +volatile int _Py_Ticker = 100; + +PyObject * +PyEval_EvalCode(PyCodeObject *co, PyObject *globals, PyObject *locals) +{ + /* XXX raise SystemError if globals is NULL */ + return PyEval_EvalCodeEx(co, + globals, locals, + (PyObject **)NULL, 0, + (PyObject **)NULL, 0, + (PyObject **)NULL, 0, + NULL); +} + + +/* Interpreter main loop */ + +PyObject * +PyEval_EvalFrame(PyFrameObject *f) { + /* This is for backward compatibility with extension modules that + used this API; core interpreter code should call PyEval_EvalFrameEx() */ + return PyEval_EvalFrameEx(f, 0); +} + +PyObject * +PyEval_EvalFrameEx(PyFrameObject *f, int throwflag) +{ +#ifdef DXPAIRS + int lastopcode = 0; +#endif + register PyObject **stack_pointer; /* Next free slot in value stack */ + register unsigned char *next_instr; + register int opcode; /* Current opcode */ + register int oparg; /* Current opcode argument, if any */ + register enum why_code why; /* Reason for block stack unwind */ + register int err; /* Error status -- nonzero if error */ + register PyObject *x; /* Result object -- NULL if error */ + register PyObject *v; /* Temporary objects popped off stack */ + register PyObject *w; + register PyObject *u; + register PyObject *t; + register PyObject *stream = NULL; /* for PRINT opcodes */ + register PyObject **fastlocals, **freevars; + PyObject *retval = NULL; /* Return value */ + PyThreadState *tstate = PyThreadState_GET(); + PyCodeObject *co; + + /* when tracing we set things up so that + + not (instr_lb <= current_bytecode_offset < instr_ub) + + is true when the line being executed has changed. The + initial values are such as to make this false the first + time it is tested. */ + int instr_ub = -1, instr_lb = 0, instr_prev = -1; + + unsigned char *first_instr; + PyObject *names; + PyObject *consts; +#if defined(Py_DEBUG) || defined(LLTRACE) + /* Make it easier to find out where we are with a debugger */ + char *filename; +#endif + +/* Tuple access macros */ + +#ifndef Py_DEBUG +#define GETITEM(v, i) PyTuple_GET_ITEM((PyTupleObject *)(v), (i)) +#else +#define GETITEM(v, i) PyTuple_GetItem((v), (i)) +#endif + +#ifdef WITH_TSC +/* Use Pentium timestamp counter to mark certain events: + inst0 -- beginning of switch statement for opcode dispatch + inst1 -- end of switch statement (may be skipped) + loop0 -- the top of the mainloop + loop1 -- place where control returns again to top of mainloop + (may be skipped) + intr1 -- beginning of long interruption + intr2 -- end of long interruption + + Many opcodes call out to helper C functions. In some cases, the + time in those functions should be counted towards the time for the + opcode, but not in all cases. For example, a CALL_FUNCTION opcode + calls another Python function; there's no point in charge all the + bytecode executed by the called function to the caller. + + It's hard to make a useful judgement statically. In the presence + of operator overloading, it's impossible to tell if a call will + execute new Python code or not. + + It's a case-by-case judgement. I'll use intr1 for the following + cases: + + EXEC_STMT + IMPORT_STAR + IMPORT_FROM + CALL_FUNCTION (and friends) + + */ + uint64 inst0, inst1, loop0, loop1, intr0 = 0, intr1 = 0; + int ticked = 0; + + READ_TIMESTAMP(inst0); + READ_TIMESTAMP(inst1); + READ_TIMESTAMP(loop0); + READ_TIMESTAMP(loop1); + + /* shut up the compiler */ + opcode = 0; +#endif + +/* Code access macros */ + +#define INSTR_OFFSET() ((int)(next_instr - first_instr)) +#define NEXTOP() (*next_instr++) +#define NEXTARG() (next_instr += 2, (next_instr[-1]<<8) + next_instr[-2]) +#define PEEKARG() ((next_instr[2]<<8) + next_instr[1]) +#define JUMPTO(x) (next_instr = first_instr + (x)) +#define JUMPBY(x) (next_instr += (x)) + +/* OpCode prediction macros + Some opcodes tend to come in pairs thus making it possible to predict + the second code when the first is run. For example, COMPARE_OP is often + followed by JUMP_IF_FALSE or JUMP_IF_TRUE. And, those opcodes are often + followed by a POP_TOP. + + Verifying the prediction costs a single high-speed test of register + variable against a constant. If the pairing was good, then the + processor has a high likelihood of making its own successful branch + prediction which results in a nearly zero overhead transition to the + next opcode. + + A successful prediction saves a trip through the eval-loop including + its two unpredictable branches, the HASARG test and the switch-case. + + If collecting opcode statistics, turn off prediction so that + statistics are accurately maintained (the predictions bypass + the opcode frequency counter updates). +*/ + +#ifdef DYNAMIC_EXECUTION_PROFILE +#define PREDICT(op) if (0) goto PRED_##op +#else +#define PREDICT(op) if (*next_instr == op) goto PRED_##op +#endif + +#define PREDICTED(op) PRED_##op: next_instr++ +#define PREDICTED_WITH_ARG(op) PRED_##op: oparg = PEEKARG(); next_instr += 3 + +/* Stack manipulation macros */ + +/* The stack can grow at most MAXINT deep, as co_nlocals and + co_stacksize are ints. */ +#define STACK_LEVEL() ((int)(stack_pointer - f->f_valuestack)) +#define EMPTY() (STACK_LEVEL() == 0) +#define TOP() (stack_pointer[-1]) +#define SECOND() (stack_pointer[-2]) +#define THIRD() (stack_pointer[-3]) +#define FOURTH() (stack_pointer[-4]) +#define SET_TOP(v) (stack_pointer[-1] = (v)) +#define SET_SECOND(v) (stack_pointer[-2] = (v)) +#define SET_THIRD(v) (stack_pointer[-3] = (v)) +#define SET_FOURTH(v) (stack_pointer[-4] = (v)) +#define BASIC_STACKADJ(n) (stack_pointer += n) +#define BASIC_PUSH(v) (*stack_pointer++ = (v)) +#define BASIC_POP() (*--stack_pointer) + +#ifdef LLTRACE +#define PUSH(v) { (void)(BASIC_PUSH(v), \ + lltrace && prtrace(TOP(), "push")); \ + assert(STACK_LEVEL() <= co->co_stacksize); } +#define POP() ((void)(lltrace && prtrace(TOP(), "pop")), BASIC_POP()) +#define STACKADJ(n) { (void)(BASIC_STACKADJ(n), \ + lltrace && prtrace(TOP(), "stackadj")); \ + assert(STACK_LEVEL() <= co->co_stacksize); } +#define EXT_POP(STACK_POINTER) (lltrace && prtrace(*(STACK_POINTER), "ext_pop"), *--(STACK_POINTER)) +#else +#define PUSH(v) BASIC_PUSH(v) +#define POP() BASIC_POP() +#define STACKADJ(n) BASIC_STACKADJ(n) +#define EXT_POP(STACK_POINTER) (*--(STACK_POINTER)) +#endif + +/* Local variable macros */ + +#define GETLOCAL(i) (fastlocals[i]) + +/* The SETLOCAL() macro must not DECREF the local variable in-place and + then store the new value; it must copy the old value to a temporary + value, then store the new value, and then DECREF the temporary value. + This is because it is possible that during the DECREF the frame is + accessed by other code (e.g. a __del__ method or gc.collect()) and the + variable would be pointing to already-freed memory. */ +#define SETLOCAL(i, value) do { PyObject *tmp = GETLOCAL(i); \ + GETLOCAL(i) = value; \ + Py_XDECREF(tmp); } while (0) + +/* Start of code */ + + if (f == NULL) + return NULL; + + /* push frame */ + if (Py_EnterRecursiveCall("")) + return NULL; + + tstate->frame = f; + + if (tstate->use_tracing) { + if (tstate->c_tracefunc != NULL) { + /* tstate->c_tracefunc, if defined, is a + function that will be called on *every* entry + to a code block. Its return value, if not + None, is a function that will be called at + the start of each executed line of code. + (Actually, the function must return itself + in order to continue tracing.) The trace + functions are called with three arguments: + a pointer to the current frame, a string + indicating why the function is called, and + an argument which depends on the situation. + The global trace function is also called + whenever an exception is detected. */ + if (call_trace(tstate->c_tracefunc, tstate->c_traceobj, + f, PyTrace_CALL, Py_None)) { + /* Trace function raised an error */ + goto exit_eval_frame; + } + } + if (tstate->c_profilefunc != NULL) { + /* Similar for c_profilefunc, except it needn't + return itself and isn't called for "line" events */ + if (call_trace(tstate->c_profilefunc, + tstate->c_profileobj, + f, PyTrace_CALL, Py_None)) { + /* Profile function raised an error */ + goto exit_eval_frame; + } + } + } + + co = f->f_code; + names = co->co_names; + consts = co->co_consts; + fastlocals = f->f_localsplus; + freevars = f->f_localsplus + co->co_nlocals; + first_instr = (unsigned char*) PyString_AS_STRING(co->co_code); + /* An explanation is in order for the next line. + + f->f_lasti now refers to the index of the last instruction + executed. You might think this was obvious from the name, but + this wasn't always true before 2.3! PyFrame_New now sets + f->f_lasti to -1 (i.e. the index *before* the first instruction) + and YIELD_VALUE doesn't fiddle with f_lasti any more. So this + does work. Promise. */ + next_instr = first_instr + f->f_lasti + 1; + stack_pointer = f->f_stacktop; + assert(stack_pointer != NULL); + f->f_stacktop = NULL; /* remains NULL unless yield suspends frame */ + +#ifdef LLTRACE + lltrace = PyDict_GetItemString(f->f_globals, "__lltrace__") != NULL; +#endif +#if defined(Py_DEBUG) || defined(LLTRACE) + filename = PyString_AsString(co->co_filename); +#endif + + why = WHY_NOT; + err = 0; + x = Py_None; /* Not a reference, just anything non-NULL */ + w = NULL; + + if (throwflag) { /* support for generator.throw() */ + why = WHY_EXCEPTION; + goto on_error; + } + + for (;;) { +#ifdef WITH_TSC + if (inst1 == 0) { + /* Almost surely, the opcode executed a break + or a continue, preventing inst1 from being set + on the way out of the loop. + */ + READ_TIMESTAMP(inst1); + loop1 = inst1; + } + dump_tsc(opcode, ticked, inst0, inst1, loop0, loop1, + intr0, intr1); + ticked = 0; + inst1 = 0; + intr0 = 0; + intr1 = 0; + READ_TIMESTAMP(loop0); +#endif + assert(stack_pointer >= f->f_valuestack); /* else underflow */ + assert(STACK_LEVEL() <= co->co_stacksize); /* else overflow */ + + /* Do periodic things. Doing this every time through + the loop would add too much overhead, so we do it + only every Nth instruction. We also do it if + ``things_to_do'' is set, i.e. when an asynchronous + event needs attention (e.g. a signal handler or + async I/O handler); see Py_AddPendingCall() and + Py_MakePendingCalls() above. */ + + if (--_Py_Ticker < 0) { + if (*next_instr == SETUP_FINALLY) { + /* Make the last opcode before + a try: finally: block uninterruptable. */ + goto fast_next_opcode; + } + _Py_Ticker = _Py_CheckInterval; + tstate->tick_counter++; +#ifdef WITH_TSC + ticked = 1; +#endif + if (things_to_do) { + if (Py_MakePendingCalls() < 0) { + why = WHY_EXCEPTION; + goto on_error; + } + if (things_to_do) + /* MakePendingCalls() didn't succeed. + Force early re-execution of this + "periodic" code, possibly after + a thread switch */ + _Py_Ticker = 0; + } +#ifdef WITH_THREAD + if (interpreter_lock) { + /* Give another thread a chance */ + + if (PyThreadState_Swap(NULL) != tstate) + Py_FatalError("ceval: tstate mix-up"); + PyThread_release_lock(interpreter_lock); + + /* Other threads may run now */ + + PyThread_acquire_lock(interpreter_lock, 1); + if (PyThreadState_Swap(tstate) != NULL) + Py_FatalError("ceval: orphan tstate"); + + /* Check for thread interrupts */ + + if (tstate->async_exc != NULL) { + x = tstate->async_exc; + tstate->async_exc = NULL; + PyErr_SetNone(x); + Py_DECREF(x); + why = WHY_EXCEPTION; + goto on_error; + } + } +#endif + } + + fast_next_opcode: + f->f_lasti = INSTR_OFFSET(); + + /* line-by-line tracing support */ + + if (tstate->c_tracefunc != NULL && !tstate->tracing) { + /* see maybe_call_line_trace + for expository comments */ + f->f_stacktop = stack_pointer; + + err = maybe_call_line_trace(tstate->c_tracefunc, + tstate->c_traceobj, + f, &instr_lb, &instr_ub, + &instr_prev); + /* Reload possibly changed frame fields */ + JUMPTO(f->f_lasti); + if (f->f_stacktop != NULL) { + stack_pointer = f->f_stacktop; + f->f_stacktop = NULL; + } + if (err) { + /* trace function raised an exception */ + goto on_error; + } + } + + /* Extract opcode and argument */ + + opcode = NEXTOP(); + oparg = 0; /* allows oparg to be stored in a register because + it doesn't have to be remembered across a full loop */ + if (HAS_ARG(opcode)) + oparg = NEXTARG(); + dispatch_opcode: +#ifdef DYNAMIC_EXECUTION_PROFILE +#ifdef DXPAIRS + dxpairs[lastopcode][opcode]++; + lastopcode = opcode; +#endif + dxp[opcode]++; +#endif + +#ifdef LLTRACE + /* Instruction tracing */ + + if (lltrace) { + if (HAS_ARG(opcode)) { + printf("%d: %d, %d\n", + f->f_lasti, opcode, oparg); + } + else { + printf("%d: %d\n", + f->f_lasti, opcode); + } + } +#endif + + /* Main switch on opcode */ + READ_TIMESTAMP(inst0); + + switch (opcode) { + + /* BEWARE! + It is essential that any operation that fails sets either + x to NULL, err to nonzero, or why to anything but WHY_NOT, + and that no operation that succeeds does this! */ + + /* case STOP_CODE: this is an error! */ + + case NOP: + goto fast_next_opcode; + + case LOAD_FAST: + x = GETLOCAL(oparg); + if (x != NULL) { + Py_INCREF(x); + PUSH(x); + goto fast_next_opcode; + } + format_exc_check_arg(PyExc_UnboundLocalError, + UNBOUNDLOCAL_ERROR_MSG, + PyTuple_GetItem(co->co_varnames, oparg)); + break; + + case LOAD_CONST: + x = GETITEM(consts, oparg); + Py_INCREF(x); + PUSH(x); + goto fast_next_opcode; + + PREDICTED_WITH_ARG(STORE_FAST); + case STORE_FAST: + v = POP(); + SETLOCAL(oparg, v); + goto fast_next_opcode; + + PREDICTED(POP_TOP); + case POP_TOP: + v = POP(); + Py_DECREF(v); + goto fast_next_opcode; + + case ROT_TWO: + v = TOP(); + w = SECOND(); + SET_TOP(w); + SET_SECOND(v); + goto fast_next_opcode; + + case ROT_THREE: + v = TOP(); + w = SECOND(); + x = THIRD(); + SET_TOP(w); + SET_SECOND(x); + SET_THIRD(v); + goto fast_next_opcode; + + case ROT_FOUR: + u = TOP(); + v = SECOND(); + w = THIRD(); + x = FOURTH(); + SET_TOP(v); + SET_SECOND(w); + SET_THIRD(x); + SET_FOURTH(u); + goto fast_next_opcode; + + case DUP_TOP: + v = TOP(); + Py_INCREF(v); + PUSH(v); + goto fast_next_opcode; + + case DUP_TOPX: + if (oparg == 2) { + x = TOP(); + Py_INCREF(x); + w = SECOND(); + Py_INCREF(w); + STACKADJ(2); + SET_TOP(x); + SET_SECOND(w); + goto fast_next_opcode; + } else if (oparg == 3) { + x = TOP(); + Py_INCREF(x); + w = SECOND(); + Py_INCREF(w); + v = THIRD(); + Py_INCREF(v); + STACKADJ(3); + SET_TOP(x); + SET_SECOND(w); + SET_THIRD(v); + goto fast_next_opcode; + } + Py_FatalError("invalid argument to DUP_TOPX" + " (bytecode corruption?)"); + break; + + case UNARY_POSITIVE: + v = TOP(); + x = PyNumber_Positive(v); + Py_DECREF(v); + SET_TOP(x); + if (x != NULL) continue; + break; + + case UNARY_NEGATIVE: + v = TOP(); + x = PyNumber_Negative(v); + Py_DECREF(v); + SET_TOP(x); + if (x != NULL) continue; + break; + + case UNARY_NOT: + v = TOP(); + err = PyObject_IsTrue(v); + Py_DECREF(v); + if (err == 0) { + Py_INCREF(Py_True); + SET_TOP(Py_True); + continue; + } + else if (err > 0) { + Py_INCREF(Py_False); + SET_TOP(Py_False); + err = 0; + continue; + } + STACKADJ(-1); + break; + + case UNARY_CONVERT: + v = TOP(); + x = PyObject_Repr(v); + Py_DECREF(v); + SET_TOP(x); + if (x != NULL) continue; + break; + + case UNARY_INVERT: + v = TOP(); + x = PyNumber_Invert(v); + Py_DECREF(v); + SET_TOP(x); + if (x != NULL) continue; + break; + + case BINARY_POWER: + w = POP(); + v = TOP(); + x = PyNumber_Power(v, w, Py_None); + Py_DECREF(v); + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case BINARY_MULTIPLY: + w = POP(); + v = TOP(); + x = PyNumber_Multiply(v, w); + Py_DECREF(v); + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case BINARY_DIVIDE: + if (!_Py_QnewFlag) { + w = POP(); + v = TOP(); + x = PyNumber_Divide(v, w); + Py_DECREF(v); + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + } + /* -Qnew is in effect: fall through to + BINARY_TRUE_DIVIDE */ + case BINARY_TRUE_DIVIDE: + w = POP(); + v = TOP(); + x = PyNumber_TrueDivide(v, w); + Py_DECREF(v); + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case BINARY_FLOOR_DIVIDE: + w = POP(); + v = TOP(); + x = PyNumber_FloorDivide(v, w); + Py_DECREF(v); + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case BINARY_MODULO: + w = POP(); + v = TOP(); + x = PyNumber_Remainder(v, w); + Py_DECREF(v); + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case BINARY_ADD: + w = POP(); + v = TOP(); + if (PyInt_CheckExact(v) && PyInt_CheckExact(w)) { + /* INLINE: int + int */ + register long a, b, i; + a = PyInt_AS_LONG(v); + b = PyInt_AS_LONG(w); + i = a + b; + if ((i^a) < 0 && (i^b) < 0) + goto slow_add; + x = PyInt_FromLong(i); + } + else if (PyString_CheckExact(v) && + PyString_CheckExact(w)) { + x = string_concatenate(v, w, f, next_instr); + /* string_concatenate consumed the ref to v */ + goto skip_decref_vx; + } + else { + slow_add: + x = PyNumber_Add(v, w); + } + Py_DECREF(v); + skip_decref_vx: + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case BINARY_SUBTRACT: + w = POP(); + v = TOP(); + if (PyInt_CheckExact(v) && PyInt_CheckExact(w)) { + /* INLINE: int - int */ + register long a, b, i; + a = PyInt_AS_LONG(v); + b = PyInt_AS_LONG(w); + i = a - b; + if ((i^a) < 0 && (i^~b) < 0) + goto slow_sub; + x = PyInt_FromLong(i); + } + else { + slow_sub: + x = PyNumber_Subtract(v, w); + } + Py_DECREF(v); + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case BINARY_SUBSCR: + w = POP(); + v = TOP(); + if (PyList_CheckExact(v) && PyInt_CheckExact(w)) { + /* INLINE: list[int] */ + Py_ssize_t i = PyInt_AsSsize_t(w); + if (i < 0) + i += PyList_GET_SIZE(v); + if (i >= 0 && i < PyList_GET_SIZE(v)) { + x = PyList_GET_ITEM(v, i); + Py_INCREF(x); + } + else + goto slow_get; + } + else + slow_get: + x = PyObject_GetItem(v, w); + Py_DECREF(v); + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case BINARY_LSHIFT: + w = POP(); + v = TOP(); + x = PyNumber_Lshift(v, w); + Py_DECREF(v); + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case BINARY_RSHIFT: + w = POP(); + v = TOP(); + x = PyNumber_Rshift(v, w); + Py_DECREF(v); + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case BINARY_AND: + w = POP(); + v = TOP(); + x = PyNumber_And(v, w); + Py_DECREF(v); + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case BINARY_XOR: + w = POP(); + v = TOP(); + x = PyNumber_Xor(v, w); + Py_DECREF(v); + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case BINARY_OR: + w = POP(); + v = TOP(); + x = PyNumber_Or(v, w); + Py_DECREF(v); + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case LIST_APPEND: + w = POP(); + v = POP(); + err = PyList_Append(v, w); + Py_DECREF(v); + Py_DECREF(w); + if (err == 0) { + PREDICT(JUMP_ABSOLUTE); + continue; + } + break; + + case INPLACE_POWER: + w = POP(); + v = TOP(); + x = PyNumber_InPlacePower(v, w, Py_None); + Py_DECREF(v); + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case INPLACE_MULTIPLY: + w = POP(); + v = TOP(); + x = PyNumber_InPlaceMultiply(v, w); + Py_DECREF(v); + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case INPLACE_DIVIDE: + if (!_Py_QnewFlag) { + w = POP(); + v = TOP(); + x = PyNumber_InPlaceDivide(v, w); + Py_DECREF(v); + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + } + /* -Qnew is in effect: fall through to + INPLACE_TRUE_DIVIDE */ + case INPLACE_TRUE_DIVIDE: + w = POP(); + v = TOP(); + x = PyNumber_InPlaceTrueDivide(v, w); + Py_DECREF(v); + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case INPLACE_FLOOR_DIVIDE: + w = POP(); + v = TOP(); + x = PyNumber_InPlaceFloorDivide(v, w); + Py_DECREF(v); + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case INPLACE_MODULO: + w = POP(); + v = TOP(); + x = PyNumber_InPlaceRemainder(v, w); + Py_DECREF(v); + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case INPLACE_ADD: + w = POP(); + v = TOP(); + if (PyInt_CheckExact(v) && PyInt_CheckExact(w)) { + /* INLINE: int + int */ + register long a, b, i; + a = PyInt_AS_LONG(v); + b = PyInt_AS_LONG(w); + i = a + b; + if ((i^a) < 0 && (i^b) < 0) + goto slow_iadd; + x = PyInt_FromLong(i); + } + else if (PyString_CheckExact(v) && + PyString_CheckExact(w)) { + x = string_concatenate(v, w, f, next_instr); + /* string_concatenate consumed the ref to v */ + goto skip_decref_v; + } + else { + slow_iadd: + x = PyNumber_InPlaceAdd(v, w); + } + Py_DECREF(v); + skip_decref_v: + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case INPLACE_SUBTRACT: + w = POP(); + v = TOP(); + if (PyInt_CheckExact(v) && PyInt_CheckExact(w)) { + /* INLINE: int - int */ + register long a, b, i; + a = PyInt_AS_LONG(v); + b = PyInt_AS_LONG(w); + i = a - b; + if ((i^a) < 0 && (i^~b) < 0) + goto slow_isub; + x = PyInt_FromLong(i); + } + else { + slow_isub: + x = PyNumber_InPlaceSubtract(v, w); + } + Py_DECREF(v); + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case INPLACE_LSHIFT: + w = POP(); + v = TOP(); + x = PyNumber_InPlaceLshift(v, w); + Py_DECREF(v); + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case INPLACE_RSHIFT: + w = POP(); + v = TOP(); + x = PyNumber_InPlaceRshift(v, w); + Py_DECREF(v); + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case INPLACE_AND: + w = POP(); + v = TOP(); + x = PyNumber_InPlaceAnd(v, w); + Py_DECREF(v); + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case INPLACE_XOR: + w = POP(); + v = TOP(); + x = PyNumber_InPlaceXor(v, w); + Py_DECREF(v); + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case INPLACE_OR: + w = POP(); + v = TOP(); + x = PyNumber_InPlaceOr(v, w); + Py_DECREF(v); + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case SLICE+0: + case SLICE+1: + case SLICE+2: + case SLICE+3: + if ((opcode-SLICE) & 2) + w = POP(); + else + w = NULL; + if ((opcode-SLICE) & 1) + v = POP(); + else + v = NULL; + u = TOP(); + x = apply_slice(u, v, w); + Py_DECREF(u); + Py_XDECREF(v); + Py_XDECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case STORE_SLICE+0: + case STORE_SLICE+1: + case STORE_SLICE+2: + case STORE_SLICE+3: + if ((opcode-STORE_SLICE) & 2) + w = POP(); + else + w = NULL; + if ((opcode-STORE_SLICE) & 1) + v = POP(); + else + v = NULL; + u = POP(); + t = POP(); + err = assign_slice(u, v, w, t); /* u[v:w] = t */ + Py_DECREF(t); + Py_DECREF(u); + Py_XDECREF(v); + Py_XDECREF(w); + if (err == 0) continue; + break; + + case DELETE_SLICE+0: + case DELETE_SLICE+1: + case DELETE_SLICE+2: + case DELETE_SLICE+3: + if ((opcode-DELETE_SLICE) & 2) + w = POP(); + else + w = NULL; + if ((opcode-DELETE_SLICE) & 1) + v = POP(); + else + v = NULL; + u = POP(); + err = assign_slice(u, v, w, (PyObject *)NULL); + /* del u[v:w] */ + Py_DECREF(u); + Py_XDECREF(v); + Py_XDECREF(w); + if (err == 0) continue; + break; + + case STORE_SUBSCR: + w = TOP(); + v = SECOND(); + u = THIRD(); + STACKADJ(-3); + /* v[w] = u */ + err = PyObject_SetItem(v, w, u); + Py_DECREF(u); + Py_DECREF(v); + Py_DECREF(w); + if (err == 0) continue; + break; + + case DELETE_SUBSCR: + w = TOP(); + v = SECOND(); + STACKADJ(-2); + /* del v[w] */ + err = PyObject_DelItem(v, w); + Py_DECREF(v); + Py_DECREF(w); + if (err == 0) continue; + break; + + case PRINT_EXPR: + v = POP(); + w = PySys_GetObject("displayhook"); + if (w == NULL) { + PyErr_SetString(PyExc_RuntimeError, + "lost sys.displayhook"); + err = -1; + x = NULL; + } + if (err == 0) { + x = PyTuple_Pack(1, v); + if (x == NULL) + err = -1; + } + if (err == 0) { + w = PyEval_CallObject(w, x); + Py_XDECREF(w); + if (w == NULL) + err = -1; + } + Py_DECREF(v); + Py_XDECREF(x); + break; + + case PRINT_ITEM_TO: + w = stream = POP(); + /* fall through to PRINT_ITEM */ + + case PRINT_ITEM: + v = POP(); + if (stream == NULL || stream == Py_None) { + w = PySys_GetObject("stdout"); + if (w == NULL) { + PyErr_SetString(PyExc_RuntimeError, + "lost sys.stdout"); + err = -1; + } + } + /* PyFile_SoftSpace() can exececute arbitrary code + if sys.stdout is an instance with a __getattr__. + If __getattr__ raises an exception, w will + be freed, so we need to prevent that temporarily. */ + Py_XINCREF(w); + if (w != NULL && PyFile_SoftSpace(w, 0)) + err = PyFile_WriteString(" ", w); + if (err == 0) + err = PyFile_WriteObject(v, w, Py_PRINT_RAW); + if (err == 0) { + /* XXX move into writeobject() ? */ + if (PyString_Check(v)) { + char *s = PyString_AS_STRING(v); + Py_ssize_t len = PyString_GET_SIZE(v); + if (len == 0 || + !isspace(Py_CHARMASK(s[len-1])) || + s[len-1] == ' ') + PyFile_SoftSpace(w, 1); + } +#ifdef Py_USING_UNICODE + else if (PyUnicode_Check(v)) { + Py_UNICODE *s = PyUnicode_AS_UNICODE(v); + Py_ssize_t len = PyUnicode_GET_SIZE(v); + if (len == 0 || + !Py_UNICODE_ISSPACE(s[len-1]) || + s[len-1] == ' ') + PyFile_SoftSpace(w, 1); + } +#endif + else + PyFile_SoftSpace(w, 1); + } + Py_XDECREF(w); + Py_DECREF(v); + Py_XDECREF(stream); + stream = NULL; + if (err == 0) + continue; + break; + + case PRINT_NEWLINE_TO: + w = stream = POP(); + /* fall through to PRINT_NEWLINE */ + + case PRINT_NEWLINE: + if (stream == NULL || stream == Py_None) { + w = PySys_GetObject("stdout"); + if (w == NULL) + PyErr_SetString(PyExc_RuntimeError, + "lost sys.stdout"); + } + if (w != NULL) { + err = PyFile_WriteString("\n", w); + if (err == 0) + PyFile_SoftSpace(w, 0); + } + Py_XDECREF(stream); + stream = NULL; + break; + + +#ifdef CASE_TOO_BIG + default: switch (opcode) { +#endif + case RAISE_VARARGS: + u = v = w = NULL; + switch (oparg) { + case 3: + u = POP(); /* traceback */ + /* Fallthrough */ + case 2: + v = POP(); /* value */ + /* Fallthrough */ + case 1: + w = POP(); /* exc */ + case 0: /* Fallthrough */ + why = do_raise(w, v, u); + break; + default: + PyErr_SetString(PyExc_SystemError, + "bad RAISE_VARARGS oparg"); + why = WHY_EXCEPTION; + break; + } + break; + + case LOAD_LOCALS: + if ((x = f->f_locals) != NULL) { + Py_INCREF(x); + PUSH(x); + continue; + } + PyErr_SetString(PyExc_SystemError, "no locals"); + break; + + case RETURN_VALUE: + retval = POP(); + why = WHY_RETURN; + goto fast_block_end; + + case YIELD_VALUE: + retval = POP(); + f->f_stacktop = stack_pointer; + why = WHY_YIELD; + goto fast_yield; + + case EXEC_STMT: + w = TOP(); + v = SECOND(); + u = THIRD(); + STACKADJ(-3); + READ_TIMESTAMP(intr0); + err = exec_statement(f, u, v, w); + READ_TIMESTAMP(intr1); + Py_DECREF(u); + Py_DECREF(v); + Py_DECREF(w); + break; + + case POP_BLOCK: + { + PyTryBlock *b = PyFrame_BlockPop(f); + while (STACK_LEVEL() > b->b_level) { + v = POP(); + Py_DECREF(v); + } + } + continue; + + case END_FINALLY: + v = POP(); + if (PyInt_Check(v)) { + why = (enum why_code) PyInt_AS_LONG(v); + assert(why != WHY_YIELD); + if (why == WHY_RETURN || + why == WHY_CONTINUE) + retval = POP(); + } + else if (PyExceptionClass_Check(v) || PyString_Check(v)) { + w = POP(); + u = POP(); + PyErr_Restore(v, w, u); + why = WHY_RERAISE; + break; + } + else if (v != Py_None) { + PyErr_SetString(PyExc_SystemError, + "'finally' pops bad exception"); + why = WHY_EXCEPTION; + } + Py_DECREF(v); + break; + + case BUILD_CLASS: + u = TOP(); + v = SECOND(); + w = THIRD(); + STACKADJ(-2); + x = build_class(u, v, w); + SET_TOP(x); + Py_DECREF(u); + Py_DECREF(v); + Py_DECREF(w); + break; + + case STORE_NAME: + w = GETITEM(names, oparg); + v = POP(); + if ((x = f->f_locals) != NULL) { + if (PyDict_CheckExact(x)) + err = PyDict_SetItem(x, w, v); + else + err = PyObject_SetItem(x, w, v); + Py_DECREF(v); + if (err == 0) continue; + break; + } + PyErr_Format(PyExc_SystemError, + "no locals found when storing %s", + PyObject_REPR(w)); + break; + + case DELETE_NAME: + w = GETITEM(names, oparg); + if ((x = f->f_locals) != NULL) { + if ((err = PyObject_DelItem(x, w)) != 0) + format_exc_check_arg(PyExc_NameError, + NAME_ERROR_MSG ,w); + break; + } + PyErr_Format(PyExc_SystemError, + "no locals when deleting %s", + PyObject_REPR(w)); + break; + + PREDICTED_WITH_ARG(UNPACK_SEQUENCE); + case UNPACK_SEQUENCE: + v = POP(); + if (PyTuple_CheckExact(v) && PyTuple_GET_SIZE(v) == oparg) { + PyObject **items = ((PyTupleObject *)v)->ob_item; + while (oparg--) { + w = items[oparg]; + Py_INCREF(w); + PUSH(w); + } + Py_DECREF(v); + continue; + } else if (PyList_CheckExact(v) && PyList_GET_SIZE(v) == oparg) { + PyObject **items = ((PyListObject *)v)->ob_item; + while (oparg--) { + w = items[oparg]; + Py_INCREF(w); + PUSH(w); + } + } else if (unpack_iterable(v, oparg, + stack_pointer + oparg)) + stack_pointer += oparg; + else { + if (PyErr_ExceptionMatches(PyExc_TypeError)) + PyErr_SetString(PyExc_TypeError, + "unpack non-sequence"); + why = WHY_EXCEPTION; + } + Py_DECREF(v); + break; + + case STORE_ATTR: + w = GETITEM(names, oparg); + v = TOP(); + u = SECOND(); + STACKADJ(-2); + err = PyObject_SetAttr(v, w, u); /* v.w = u */ + Py_DECREF(v); + Py_DECREF(u); + if (err == 0) continue; + break; + + case DELETE_ATTR: + w = GETITEM(names, oparg); + v = POP(); + err = PyObject_SetAttr(v, w, (PyObject *)NULL); + /* del v.w */ + Py_DECREF(v); + break; + + case STORE_GLOBAL: + w = GETITEM(names, oparg); + v = POP(); + err = PyDict_SetItem(f->f_globals, w, v); + Py_DECREF(v); + if (err == 0) continue; + break; + + case DELETE_GLOBAL: + w = GETITEM(names, oparg); + if ((err = PyDict_DelItem(f->f_globals, w)) != 0) + format_exc_check_arg( + PyExc_NameError, GLOBAL_NAME_ERROR_MSG, w); + break; + + case LOAD_NAME: + w = GETITEM(names, oparg); + if ((v = f->f_locals) == NULL) { + PyErr_Format(PyExc_SystemError, + "no locals when loading %s", + PyObject_REPR(w)); + break; + } + if (PyDict_CheckExact(v)) { + x = PyDict_GetItem(v, w); + Py_XINCREF(x); + } + else { + x = PyObject_GetItem(v, w); + if (x == NULL && PyErr_Occurred()) { + if (!PyErr_ExceptionMatches(PyExc_KeyError)) + break; + PyErr_Clear(); + } + } + if (x == NULL) { + x = PyDict_GetItem(f->f_globals, w); + if (x == NULL) { + x = PyDict_GetItem(f->f_builtins, w); + if (x == NULL) { + format_exc_check_arg( + PyExc_NameError, + NAME_ERROR_MSG ,w); + break; + } + } + Py_INCREF(x); + } + PUSH(x); + continue; + + case LOAD_GLOBAL: + w = GETITEM(names, oparg); + if (PyString_CheckExact(w)) { + /* Inline the PyDict_GetItem() calls. + WARNING: this is an extreme speed hack. + Do not try this at home. */ + long hash = ((PyStringObject *)w)->ob_shash; + if (hash != -1) { + PyDictObject *d; + PyDictEntry *e; + d = (PyDictObject *)(f->f_globals); + e = d->ma_lookup(d, w, hash); + if (e == NULL) { + x = NULL; + break; + } + x = e->me_value; + if (x != NULL) { + Py_INCREF(x); + PUSH(x); + continue; + } + d = (PyDictObject *)(f->f_builtins); + e = d->ma_lookup(d, w, hash); + if (e == NULL) { + x = NULL; + break; + } + x = e->me_value; + if (x != NULL) { + Py_INCREF(x); + PUSH(x); + continue; + } + goto load_global_error; + } + } + /* This is the un-inlined version of the code above */ + x = PyDict_GetItem(f->f_globals, w); + if (x == NULL) { + x = PyDict_GetItem(f->f_builtins, w); + if (x == NULL) { + load_global_error: + format_exc_check_arg( + PyExc_NameError, + GLOBAL_NAME_ERROR_MSG, w); + break; + } + } + Py_INCREF(x); + PUSH(x); + continue; + + case DELETE_FAST: + x = GETLOCAL(oparg); + if (x != NULL) { + SETLOCAL(oparg, NULL); + continue; + } + format_exc_check_arg( + PyExc_UnboundLocalError, + UNBOUNDLOCAL_ERROR_MSG, + PyTuple_GetItem(co->co_varnames, oparg) + ); + break; + + case LOAD_CLOSURE: + x = freevars[oparg]; + Py_INCREF(x); + PUSH(x); + if (x != NULL) continue; + break; + + case LOAD_DEREF: + x = freevars[oparg]; + w = PyCell_Get(x); + if (w != NULL) { + PUSH(w); + continue; + } + err = -1; + /* Don't stomp existing exception */ + if (PyErr_Occurred()) + break; + if (oparg < PyTuple_GET_SIZE(co->co_cellvars)) { + v = PyTuple_GET_ITEM(co->co_cellvars, + oparg); + format_exc_check_arg( + PyExc_UnboundLocalError, + UNBOUNDLOCAL_ERROR_MSG, + v); + } else { + v = PyTuple_GET_ITEM( + co->co_freevars, + oparg - PyTuple_GET_SIZE(co->co_cellvars)); + format_exc_check_arg( + PyExc_NameError, + UNBOUNDFREE_ERROR_MSG, + v); + } + break; + + case STORE_DEREF: + w = POP(); + x = freevars[oparg]; + PyCell_Set(x, w); + Py_DECREF(w); + continue; + + case BUILD_TUPLE: + x = PyTuple_New(oparg); + if (x != NULL) { + for (; --oparg >= 0;) { + w = POP(); + PyTuple_SET_ITEM(x, oparg, w); + } + PUSH(x); + continue; + } + break; + + case BUILD_LIST: + x = PyList_New(oparg); + if (x != NULL) { + for (; --oparg >= 0;) { + w = POP(); + PyList_SET_ITEM(x, oparg, w); + } + PUSH(x); + continue; + } + break; + + case BUILD_MAP: + x = PyDict_New(); + PUSH(x); + if (x != NULL) continue; + break; + + case LOAD_ATTR: + w = GETITEM(names, oparg); + v = TOP(); + x = PyObject_GetAttr(v, w); + Py_DECREF(v); + SET_TOP(x); + if (x != NULL) continue; + break; + + case COMPARE_OP: + w = POP(); + v = TOP(); + if (PyInt_CheckExact(w) && PyInt_CheckExact(v)) { + /* INLINE: cmp(int, int) */ + register long a, b; + register int res; + a = PyInt_AS_LONG(v); + b = PyInt_AS_LONG(w); + switch (oparg) { + case PyCmp_LT: res = a < b; break; + case PyCmp_LE: res = a <= b; break; + case PyCmp_EQ: res = a == b; break; + case PyCmp_NE: res = a != b; break; + case PyCmp_GT: res = a > b; break; + case PyCmp_GE: res = a >= b; break; + case PyCmp_IS: res = v == w; break; + case PyCmp_IS_NOT: res = v != w; break; + default: goto slow_compare; + } + x = res ? Py_True : Py_False; + Py_INCREF(x); + } + else { + slow_compare: + x = cmp_outcome(oparg, v, w); + } + Py_DECREF(v); + Py_DECREF(w); + SET_TOP(x); + if (x == NULL) break; + PREDICT(JUMP_IF_FALSE); + PREDICT(JUMP_IF_TRUE); + continue; + + case IMPORT_NAME: + w = GETITEM(names, oparg); + x = PyDict_GetItemString(f->f_builtins, "__import__"); + if (x == NULL) { + PyErr_SetString(PyExc_ImportError, + "__import__ not found"); + break; + } + v = POP(); + u = TOP(); + if (PyInt_AsLong(u) != -1 || PyErr_Occurred()) + w = PyTuple_Pack(5, + w, + f->f_globals, + f->f_locals == NULL ? + Py_None : f->f_locals, + v, + u); + else + w = PyTuple_Pack(4, + w, + f->f_globals, + f->f_locals == NULL ? + Py_None : f->f_locals, + v); + Py_DECREF(v); + Py_DECREF(u); + if (w == NULL) { + u = POP(); + x = NULL; + break; + } + READ_TIMESTAMP(intr0); + x = PyEval_CallObject(x, w); + READ_TIMESTAMP(intr1); + Py_DECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case IMPORT_STAR: + v = POP(); + PyFrame_FastToLocals(f); + if ((x = f->f_locals) == NULL) { + PyErr_SetString(PyExc_SystemError, + "no locals found during 'import *'"); + break; + } + READ_TIMESTAMP(intr0); + err = import_all_from(x, v); + READ_TIMESTAMP(intr1); + PyFrame_LocalsToFast(f, 0); + Py_DECREF(v); + if (err == 0) continue; + break; + + case IMPORT_FROM: + w = GETITEM(names, oparg); + v = TOP(); + READ_TIMESTAMP(intr0); + x = import_from(v, w); + READ_TIMESTAMP(intr1); + PUSH(x); + if (x != NULL) continue; + break; + + case JUMP_FORWARD: + JUMPBY(oparg); + goto fast_next_opcode; + + PREDICTED_WITH_ARG(JUMP_IF_FALSE); + case JUMP_IF_FALSE: + w = TOP(); + if (w == Py_True) { + PREDICT(POP_TOP); + goto fast_next_opcode; + } + if (w == Py_False) { + JUMPBY(oparg); + goto fast_next_opcode; + } + err = PyObject_IsTrue(w); + if (err > 0) + err = 0; + else if (err == 0) + JUMPBY(oparg); + else + break; + continue; + + PREDICTED_WITH_ARG(JUMP_IF_TRUE); + case JUMP_IF_TRUE: + w = TOP(); + if (w == Py_False) { + PREDICT(POP_TOP); + goto fast_next_opcode; + } + if (w == Py_True) { + JUMPBY(oparg); + goto fast_next_opcode; + } + err = PyObject_IsTrue(w); + if (err > 0) { + err = 0; + JUMPBY(oparg); + } + else if (err == 0) + ; + else + break; + continue; + + PREDICTED_WITH_ARG(JUMP_ABSOLUTE); + case JUMP_ABSOLUTE: + JUMPTO(oparg); + continue; + + case GET_ITER: + /* before: [obj]; after [getiter(obj)] */ + v = TOP(); + x = PyObject_GetIter(v); + Py_DECREF(v); + if (x != NULL) { + SET_TOP(x); + PREDICT(FOR_ITER); + continue; + } + STACKADJ(-1); + break; + + PREDICTED_WITH_ARG(FOR_ITER); + case FOR_ITER: + /* before: [iter]; after: [iter, iter()] *or* [] */ + v = TOP(); + x = (*v->ob_type->tp_iternext)(v); + if (x != NULL) { + PUSH(x); + PREDICT(STORE_FAST); + PREDICT(UNPACK_SEQUENCE); + continue; + } + if (PyErr_Occurred()) { + if (!PyErr_ExceptionMatches(PyExc_StopIteration)) + break; + PyErr_Clear(); + } + /* iterator ended normally */ + x = v = POP(); + Py_DECREF(v); + JUMPBY(oparg); + continue; + + case BREAK_LOOP: + why = WHY_BREAK; + goto fast_block_end; + + case CONTINUE_LOOP: + retval = PyInt_FromLong(oparg); + if (!retval) { + x = NULL; + break; + } + why = WHY_CONTINUE; + goto fast_block_end; + + case SETUP_LOOP: + case SETUP_EXCEPT: + case SETUP_FINALLY: + /* NOTE: If you add any new block-setup opcodes that are not try/except/finally + handlers, you may need to update the PyGen_NeedsFinalizing() function. */ + + PyFrame_BlockSetup(f, opcode, INSTR_OFFSET() + oparg, + STACK_LEVEL()); + continue; + + case WITH_CLEANUP: + { + /* TOP is the context.__exit__ bound method. + Below that are 1-3 values indicating how/why + we entered the finally clause: + - SECOND = None + - (SECOND, THIRD) = (WHY_{RETURN,CONTINUE}), retval + - SECOND = WHY_*; no retval below it + - (SECOND, THIRD, FOURTH) = exc_info() + In the last case, we must call + TOP(SECOND, THIRD, FOURTH) + otherwise we must call + TOP(None, None, None) + + In addition, if the stack represents an exception, + *and* the function call returns a 'true' value, we + "zap" this information, to prevent END_FINALLY from + re-raising the exception. (But non-local gotos + should still be resumed.) + */ + + x = TOP(); + u = SECOND(); + if (PyInt_Check(u) || u == Py_None) { + u = v = w = Py_None; + } + else { + v = THIRD(); + w = FOURTH(); + } + /* XXX Not the fastest way to call it... */ + x = PyObject_CallFunctionObjArgs(x, u, v, w, NULL); + if (x == NULL) + break; /* Go to error exit */ + if (u != Py_None && PyObject_IsTrue(x)) { + /* There was an exception and a true return */ + Py_DECREF(x); + x = TOP(); /* Again */ + STACKADJ(-3); + Py_INCREF(Py_None); + SET_TOP(Py_None); + Py_DECREF(x); + Py_DECREF(u); + Py_DECREF(v); + Py_DECREF(w); + } else { + /* Let END_FINALLY do its thing */ + Py_DECREF(x); + x = POP(); + Py_DECREF(x); + } + break; + } + + case CALL_FUNCTION: + { + PyObject **sp; + PCALL(PCALL_ALL); + sp = stack_pointer; +#ifdef WITH_TSC + x = call_function(&sp, oparg, &intr0, &intr1); +#else + x = call_function(&sp, oparg); +#endif + stack_pointer = sp; + PUSH(x); + if (x != NULL) + continue; + break; + } + + case CALL_FUNCTION_VAR: + case CALL_FUNCTION_KW: + case CALL_FUNCTION_VAR_KW: + { + int na = oparg & 0xff; + int nk = (oparg>>8) & 0xff; + int flags = (opcode - CALL_FUNCTION) & 3; + int n = na + 2 * nk; + PyObject **pfunc, *func, **sp; + PCALL(PCALL_ALL); + if (flags & CALL_FLAG_VAR) + n++; + if (flags & CALL_FLAG_KW) + n++; + pfunc = stack_pointer - n - 1; + func = *pfunc; + + if (PyMethod_Check(func) + && PyMethod_GET_SELF(func) != NULL) { + PyObject *self = PyMethod_GET_SELF(func); + Py_INCREF(self); + func = PyMethod_GET_FUNCTION(func); + Py_INCREF(func); + Py_DECREF(*pfunc); + *pfunc = self; + na++; + n++; + } else + Py_INCREF(func); + sp = stack_pointer; + READ_TIMESTAMP(intr0); + x = ext_do_call(func, &sp, flags, na, nk); + READ_TIMESTAMP(intr1); + stack_pointer = sp; + Py_DECREF(func); + + while (stack_pointer > pfunc) { + w = POP(); + Py_DECREF(w); + } + PUSH(x); + if (x != NULL) + continue; + break; + } + + case MAKE_FUNCTION: + v = POP(); /* code object */ + x = PyFunction_New(v, f->f_globals); + Py_DECREF(v); + /* XXX Maybe this should be a separate opcode? */ + if (x != NULL && oparg > 0) { + v = PyTuple_New(oparg); + if (v == NULL) { + Py_DECREF(x); + x = NULL; + break; + } + while (--oparg >= 0) { + w = POP(); + PyTuple_SET_ITEM(v, oparg, w); + } + err = PyFunction_SetDefaults(x, v); + Py_DECREF(v); + } + PUSH(x); + break; + + case MAKE_CLOSURE: + { + v = POP(); /* code object */ + x = PyFunction_New(v, f->f_globals); + Py_DECREF(v); + if (x != NULL) { + v = POP(); + err = PyFunction_SetClosure(x, v); + Py_DECREF(v); + } + if (x != NULL && oparg > 0) { + v = PyTuple_New(oparg); + if (v == NULL) { + Py_DECREF(x); + x = NULL; + break; + } + while (--oparg >= 0) { + w = POP(); + PyTuple_SET_ITEM(v, oparg, w); + } + err = PyFunction_SetDefaults(x, v); + Py_DECREF(v); + } + PUSH(x); + break; + } + + case BUILD_SLICE: + if (oparg == 3) + w = POP(); + else + w = NULL; + v = POP(); + u = TOP(); + x = PySlice_New(u, v, w); + Py_DECREF(u); + Py_DECREF(v); + Py_XDECREF(w); + SET_TOP(x); + if (x != NULL) continue; + break; + + case EXTENDED_ARG: + opcode = NEXTOP(); + oparg = oparg<<16 | NEXTARG(); + goto dispatch_opcode; + + default: + fprintf(stderr, + "XXX lineno: %d, opcode: %d\n", + PyCode_Addr2Line(f->f_code, f->f_lasti), + opcode); + PyErr_SetString(PyExc_SystemError, "unknown opcode"); + why = WHY_EXCEPTION; + break; + +#ifdef CASE_TOO_BIG + } +#endif + + } /* switch */ + + on_error: + + READ_TIMESTAMP(inst1); + + /* Quickly continue if no error occurred */ + + if (why == WHY_NOT) { + if (err == 0 && x != NULL) { +#ifdef CHECKEXC + /* This check is expensive! */ + if (PyErr_Occurred()) + fprintf(stderr, + "XXX undetected error\n"); + else { +#endif + READ_TIMESTAMP(loop1); + continue; /* Normal, fast path */ +#ifdef CHECKEXC + } +#endif + } + why = WHY_EXCEPTION; + x = Py_None; + err = 0; + } + + /* Double-check exception status */ + + if (why == WHY_EXCEPTION || why == WHY_RERAISE) { + if (!PyErr_Occurred()) { + PyErr_SetString(PyExc_SystemError, + "error return without exception set"); + why = WHY_EXCEPTION; + } + } +#ifdef CHECKEXC + else { + /* This check is expensive! */ + if (PyErr_Occurred()) { + char buf[1024]; + sprintf(buf, "Stack unwind with exception " + "set and why=%d", why); + Py_FatalError(buf); + } + } +#endif + + /* Log traceback info if this is a real exception */ + + if (why == WHY_EXCEPTION) { + PyTraceBack_Here(f); + + if (tstate->c_tracefunc != NULL) + call_exc_trace(tstate->c_tracefunc, + tstate->c_traceobj, f); + } + + /* For the rest, treat WHY_RERAISE as WHY_EXCEPTION */ + + if (why == WHY_RERAISE) + why = WHY_EXCEPTION; + + /* Unwind stacks if a (pseudo) exception occurred */ + +fast_block_end: + while (why != WHY_NOT && f->f_iblock > 0) { + PyTryBlock *b = PyFrame_BlockPop(f); + + assert(why != WHY_YIELD); + if (b->b_type == SETUP_LOOP && why == WHY_CONTINUE) { + /* For a continue inside a try block, + don't pop the block for the loop. */ + PyFrame_BlockSetup(f, b->b_type, b->b_handler, + b->b_level); + why = WHY_NOT; + JUMPTO(PyInt_AS_LONG(retval)); + Py_DECREF(retval); + break; + } + + while (STACK_LEVEL() > b->b_level) { + v = POP(); + Py_XDECREF(v); + } + if (b->b_type == SETUP_LOOP && why == WHY_BREAK) { + why = WHY_NOT; + JUMPTO(b->b_handler); + break; + } + if (b->b_type == SETUP_FINALLY || + (b->b_type == SETUP_EXCEPT && + why == WHY_EXCEPTION)) { + if (why == WHY_EXCEPTION) { + PyObject *exc, *val, *tb; + PyErr_Fetch(&exc, &val, &tb); + if (val == NULL) { + val = Py_None; + Py_INCREF(val); + } + /* Make the raw exception data + available to the handler, + so a program can emulate the + Python main loop. Don't do + this for 'finally'. */ + if (b->b_type == SETUP_EXCEPT) { + PyErr_NormalizeException( + &exc, &val, &tb); + set_exc_info(tstate, + exc, val, tb); + } + if (tb == NULL) { + Py_INCREF(Py_None); + PUSH(Py_None); + } else + PUSH(tb); + PUSH(val); + PUSH(exc); + } + else { + if (why & (WHY_RETURN | WHY_CONTINUE)) + PUSH(retval); + v = PyInt_FromLong((long)why); + PUSH(v); + } + why = WHY_NOT; + JUMPTO(b->b_handler); + break; + } + } /* unwind stack */ + + /* End the loop if we still have an error (or return) */ + + if (why != WHY_NOT) + break; + READ_TIMESTAMP(loop1); + + } /* main loop */ + + assert(why != WHY_YIELD); + /* Pop remaining stack entries. */ + while (!EMPTY()) { + v = POP(); + Py_XDECREF(v); + } + + if (why != WHY_RETURN) + retval = NULL; + +fast_yield: + if (tstate->use_tracing) { + if (tstate->c_tracefunc) { + if (why == WHY_RETURN || why == WHY_YIELD) { + if (call_trace(tstate->c_tracefunc, + tstate->c_traceobj, f, + PyTrace_RETURN, retval)) { + Py_XDECREF(retval); + retval = NULL; + why = WHY_EXCEPTION; + } + } + else if (why == WHY_EXCEPTION) { + call_trace_protected(tstate->c_tracefunc, + tstate->c_traceobj, f, + PyTrace_RETURN, NULL); + } + } + if (tstate->c_profilefunc) { + if (why == WHY_EXCEPTION) + call_trace_protected(tstate->c_profilefunc, + tstate->c_profileobj, f, + PyTrace_RETURN, NULL); + else if (call_trace(tstate->c_profilefunc, + tstate->c_profileobj, f, + PyTrace_RETURN, retval)) { + Py_XDECREF(retval); + retval = NULL; + why = WHY_EXCEPTION; + } + } + } + + if (tstate->frame->f_exc_type != NULL) + reset_exc_info(tstate); + else { + assert(tstate->frame->f_exc_value == NULL); + assert(tstate->frame->f_exc_traceback == NULL); + } + + /* pop frame */ + exit_eval_frame: + Py_LeaveRecursiveCall(); + tstate->frame = f->f_back; + + return retval; +} + Added: external/Pygments-0.8.1/tests/examplefiles/classes.dylan ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/classes.dylan Thu Aug 9 17:43:13 2007 @@ -0,0 +1,20 @@ +define class () + slot serial-number :: = unique-serial-number(); + slot model-name :: , + required-init-keyword: model:; + slot has-sunroof? :: , + init-keyword: sunroof?:, + init-value: #f; +end class ; + +define variable *unique-serial-number* = 0; + +define function unique-serial-number() => (usn :: ) + let serial = *unique-serial-number*; + *unique-serial-number* := *unique-serial-number* + 1; + serial; +end function; + +define constant $blue-car = make(, model: "Viper"); +define constant $black-car = make(, model: "Town Car", sunroof?: #t); +define constant $red-car = make(, model: "F40", sunroof?: #f); Added: external/Pygments-0.8.1/tests/examplefiles/condensed_ruby.rb ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/condensed_ruby.rb Thu Aug 9 17:43:13 2007 @@ -0,0 +1,10 @@ +# Server: ruby p2p.rb password server server-uri merge-servers +# Sample: ruby p2p.rb foobar server druby://localhost:1337 druby://foo.bar:1337 +# Client: ruby p2p.rb password client server-uri download-pattern +# Sample: ruby p2p.rb foobar client druby://localhost:1337 *.rb +require'drb';F,D,C,P,M,U,*O=File,Class,Dir,*ARGV;def s(p)F.split(p[/[^|].*/])[-1 +]end;def c(u);DRbObject.new((),u)end;def x(u)[P,u].hash;end;M=="client"&&c(U).f( +x(U)).each{|n|p,c=x(n),c(n);(c.f(p,O[0],0).map{|f|s f}-D["*"]).each{|f|F.open(f, +"w"){|o|o< +{% for js in javascript_imports %}{% include_admin_script js %}{% endfor %} +{% endblock %} +{% block stylesheet %}{% admin_media_prefix %}css/forms.css{% endblock %} +{% block coltype %}{% if ordered_objects %}colMS{% else %}colM{% endif %}{% endblock %} +{% block bodyclass %}{{ opts.app_label }}-{{ opts.object_name.lower }} change-form{% endblock %} +{% block userlinks %}{% trans 'Documentation' %} / {% trans 'Change password' %} / {% trans 'Log out' %}{% endblock %} +{% block breadcrumbs %}{% if not is_popup %} +
      + {% trans "Home" %} › + {{ opts.verbose_name_plural|capfirst|escape }} › + {% if add %}{% trans "Add" %} {{ opts.verbose_name|escape }}{% else %}{{ original|truncatewords:"18"|escape }}{% endif %} +
      +{% endif %}{% endblock %} +{% block content %}
      +{% if change %}{% if not is_popup %} + +{% endif %}{% endif %} +{% block form_top %}{% endblock %} +
      +{% if is_popup %}{% endif %} +{% if opts.admin.save_on_top %}{% submit_row %}{% endif %} +{% if form.error_dict %} +

      + {% blocktrans count form.error_dict.items|length as counter %}Please correct the error below.{% plural %}Please correct the errors below.{% endblocktrans %} +

      +{% endif %} +{% for bound_field_set in bound_field_sets %} +
      + {% if bound_field_set.name %}

      {{ bound_field_set.name }}

      {% endif %} + {% if bound_field_set.description %}
      {{ bound_field_set.description }}
      {% endif %} + {% for bound_field_line in bound_field_set %} + {% admin_field_line bound_field_line %} + {% for bound_field in bound_field_line %} + {% filter_interface_script_maybe bound_field %} + {% endfor %} + {% endfor %} +
      +{% endfor %} +{% block after_field_sets %}{% endblock %} +{% if change %} + {% if ordered_objects %} +

      {% trans "Ordering" %}

      +
      + {% if form.order_.errors %}{{ form.order_.html_error_list }}{% endif %} +

      {{ form.order_ }}

      +
      + {% endif %} +{% endif %} +{% for related_object in inline_related_objects %}{% edit_inline related_object %}{% endfor %} +{% block after_related_objects %}{% endblock %} +{% submit_row %} +{% if add %} + +{% endif %} +{% if auto_populated_fields %} + +{% endif %} +
      +
      +{% endblock %} Added: external/Pygments-0.8.1/tests/examplefiles/dwarf.cw ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/dwarf.cw Thu Aug 9 17:43:13 2007 @@ -0,0 +1,17 @@ +;redcode +;name Dwarf +;author A. K. Dewdney +;version 94.1 +;date April 29, 1993 +;strategy Bombs every fourth instruction. + ORG start ; Indicates the instruction with + ; the label "start" should be the + ; first to execute. +step EQU 4 ; Replaces all occurrences of "step" + ; with the character "4". +target DAT.F #0, #0 ; Pointer to target instruction. +start ADD.AB #step, target ; Increments pointer by step. + MOV.AB #0, @target ; Bombs target instruction. + JMP.A start ; Same as JMP.A -2. Loops back to + ; the instruction labelled "start". + END Added: external/Pygments-0.8.1/tests/examplefiles/example.c ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/example.c Thu Aug 9 17:43:13 2007 @@ -0,0 +1,2080 @@ +#include +#include +#include +#include "codegen.h" +#include "symboltable.h" +#include "stringbuffer.h" + +extern void yyerror(char* msg); + +static stringBuffer* staticVariableBuffer; +static stringBuffer* classInitBuffer; +static stringBuffer* currentMethodBuffer; +static stringBuffer* finishedMethodsBuffer; +static stringBuffer* mainBuffer; + +static int currentMethodBufferIndex; +static int currentMethodStackSize; +static int currentMethodStackSizeMax; +static int currentMethodNumberOfLocals; + +static int classInitBufferIndex; +static int classInitStackSize; +static int classInitStackSizeMax; + +static int labelCounter = 0; +static int global = 1; + +char tempString[MAX_LENGTH_OF_COMMAND]; + +extern char* className; /* from minako-syntax.y */ + +/* forward declarations */ +static void increaseStackby(int stackdiff); +char convertType(int type); + +void codegenInit() { + staticVariableBuffer = newStringBuffer(); + classInitBuffer = newStringBuffer(); + currentMethodBuffer = 0; + finishedMethodsBuffer = newStringBuffer(); + mainBuffer = newStringBuffer(); + + stringBufferAppend(mainBuffer, "; ------- Header --------------------------------------------"); + sprintf(tempString, ".class public synchronized %s", className); + stringBufferAppend(mainBuffer, tempString); + stringBufferAppend(mainBuffer, ".super java/lang/Object"); + stringBufferAppend(mainBuffer, "; -----------------------------------------------------------"); + stringBufferAppend(mainBuffer, ""); + + stringBufferAppend(finishedMethodsBuffer, "; ------- Constructor ---------------------------------------"); + stringBufferAppend(finishedMethodsBuffer, ".method public ()V"); + stringBufferAppend(finishedMethodsBuffer, "\t.limit stack 1"); + stringBufferAppend(finishedMethodsBuffer, "\t.limit locals 1"); + stringBufferAppend(finishedMethodsBuffer, "\taload_0"); + stringBufferAppend(finishedMethodsBuffer, "\tinvokenonvirtual java/lang/Object/()V"); + stringBufferAppend(finishedMethodsBuffer, "\treturn"); + stringBufferAppend(finishedMethodsBuffer, ".end method"); + stringBufferAppend(finishedMethodsBuffer, "; -----------------------------------------------------------"); + stringBufferAppend(finishedMethodsBuffer, ""); + + stringBufferAppend(staticVariableBuffer, "; ------- Class Variables -----------------------------------"); + + stringBufferAppend(classInitBuffer, "; ------- Class Initializer ---------------------------------"); + stringBufferAppend(classInitBuffer, ".method static ()V"); + classInitBufferIndex = classInitBuffer->numberOfNextElement; + stringBufferAppend(classInitBuffer, "\t.limit locals 0"); + +} + +void codegenAppendCommand(char* cmd, int stackdiff) { + char tempString[MAX_LENGTH_OF_COMMAND]; + sprintf(tempString, "\t%s", cmd); + if (global) stringBufferAppend(classInitBuffer, tempString); + else stringBufferAppend(currentMethodBuffer, tempString); + increaseStackby(stackdiff); +} + +void codegenInsertCommand(int address, char* cmd, int stackdiff) { + char tempString[MAX_LENGTH_OF_COMMAND]; + sprintf(tempString, "\t%s", cmd); + if (global) stringBufferInsert(classInitBuffer, address, tempString); + else stringBufferInsert(currentMethodBuffer, address, tempString); + increaseStackby(stackdiff); +} + +void codegenAppendLabel(int label) { + char tempString[MAX_LENGTH_OF_COMMAND]; + sprintf(tempString, "Label%d:", label); + if (global) stringBufferAppend(classInitBuffer, tempString); + else stringBufferAppend(currentMethodBuffer, tempString); +} + +void codegenAddVariable(char* name, int type) { + /*fprintf(stderr, "add variable %s(%d) global=%d ", name, convertType(type), global);*/ + if (global) { + if (type == TYPE_INT) sprintf(tempString, ".field static %s %c", name, 'I'); + else if (type == TYPE_FLOAT) sprintf(tempString, ".field static %s %c", name, 'F'); + else if (type == TYPE_BOOLEAN) sprintf(tempString, ".field static %s %c", name, 'Z'); + else yyerror("compiler-intern error in codegenAddGlobalVariable().\n"); + stringBufferAppend(staticVariableBuffer, tempString); + } + else { + currentMethodNumberOfLocals++; + } +} + +int codegenGetNextLabel() { + return labelCounter++; +} + +int codegenGetCurrentAddress() { + if (global) return classInitBuffer->numberOfNextElement; + else return currentMethodBuffer->numberOfNextElement; +} + +void codegenEnterFunction(symtabEntry* entry) { + currentMethodBuffer = newStringBuffer(); + currentMethodStackSize = 0; + currentMethodStackSizeMax = 0; + labelCounter = 1; + global = 0; + + if (strcmp(entry->name, "main") == 0) { + if (entry->idtype != TYPE_VOID) yyerror("main has to be void.\n"); + currentMethodNumberOfLocals = 1; + symtabInsert(strdup("#main-param#"), TYPE_VOID, CLASS_FUNC); + stringBufferAppend(currentMethodBuffer, "; ------- Methode ---- void main() --------------------------"); + stringBufferAppend(currentMethodBuffer, ".method public static main([Ljava/lang/String;)V"); + } + else { + int i; + currentMethodNumberOfLocals = entry->paramIndex; + stringBufferAppend(currentMethodBuffer, "; ------- Methode -------------------------------------------"); + sprintf(tempString, ".method public static %s(", entry->name); + for (i=entry->paramIndex-1; i>=0; i--) { + int type = entry->params[i]->idtype; + tempString[strlen(tempString)+1] = 0; + tempString[strlen(tempString)] = convertType(type); + } + tempString[strlen(tempString)+2] = 0; + tempString[strlen(tempString)+1] = convertType(entry->idtype); + tempString[strlen(tempString)] = ')'; + stringBufferAppend(currentMethodBuffer, tempString); + } + currentMethodBufferIndex = currentMethodBuffer->numberOfNextElement; +} + +void codegenLeaveFunction() { + global = 1; + sprintf(tempString, "\t.limit locals %d", currentMethodNumberOfLocals); + stringBufferInsert(currentMethodBuffer, currentMethodBufferIndex, tempString); + sprintf(tempString, "\t.limit stack %d", currentMethodStackSizeMax); + stringBufferInsert(currentMethodBuffer, currentMethodBufferIndex, tempString); + stringBufferAppend(currentMethodBuffer, "\treturn"); + stringBufferAppend(currentMethodBuffer, ".end method"); + stringBufferAppend(currentMethodBuffer, "; -----------------------------------------------------------"); + stringBufferAppend(currentMethodBuffer, ""); + + stringBufferConcatenate(finishedMethodsBuffer, currentMethodBuffer); +} + + + +void codegenFinishCode() { + stringBufferAppend(staticVariableBuffer, "; -----------------------------------------------------------"); + stringBufferAppend(staticVariableBuffer, ""); + + sprintf(tempString, "\t.limit stack %d", classInitStackSizeMax); + stringBufferInsert(classInitBuffer, classInitBufferIndex, tempString); + stringBufferAppend(classInitBuffer, "\treturn"); + stringBufferAppend(classInitBuffer, ".end method"); + stringBufferAppend(classInitBuffer, "; -----------------------------------------------------------"); + + stringBufferConcatenate(mainBuffer, staticVariableBuffer); + stringBufferConcatenate(mainBuffer, finishedMethodsBuffer); + stringBufferConcatenate(mainBuffer, classInitBuffer); + + stringBufferPrint(mainBuffer); +} + +static void increaseStackby(int stackdiff) { + if (global) { + classInitStackSize += stackdiff; + if (classInitStackSize > classInitStackSizeMax) classInitStackSizeMax = classInitStackSize; + } + else { + currentMethodStackSize += stackdiff; + if (currentMethodStackSize > currentMethodStackSizeMax) currentMethodStackSizeMax = currentMethodStackSize; + } +} + +char convertType(int type) { + switch(type) { + case TYPE_VOID: return 'V'; + case TYPE_INT: return 'I'; + case TYPE_FLOAT: return 'F'; + case TYPE_BOOLEAN: return 'Z'; + default: yyerror("compiler-intern error in convertType().\n"); + } + return 0; /* to avoid compiler-warning */ +} + + +//#include +//#include + +int main() { + int a = 12, b = 44; + while (a != b) { + if (a > b) + a -= b; + else + b -= a; + } + printf("%d\n%d", a, 0X0);\ +} + + +/********************************************************************** + + array.c - + + $Author: murphy $ + $Date: 2005-11-05 04:33:55 +0100 (Sa, 05 Nov 2005) $ + created at: Fri Aug 6 09:46:12 JST 1993 + + Copyright (C) 1993-2003 Yukihiro Matsumoto + Copyright (C) 2000 Network Applied Communication Laboratory, Inc. + Copyright (C) 2000 Information-technology Promotion Agency, Japan + +**********************************************************************/ + +#include "ruby.h" +#include "util.h" +#include "st.h" +#include "node.h" + +VALUE rb_cArray, rb_cValues; + +static ID id_cmp; + +#define ARY_DEFAULT_SIZE 16 + + +void +rb_mem_clear(mem, size) + register VALUE *mem; + register long size; +{ + while (size--) { + *mem++ = Qnil; + } +} + +static inline void +memfill(mem, size, val) + register VALUE *mem; + register long size; + register VALUE val; +{ + while (size--) { + *mem++ = val; + } +} + +#define ARY_TMPLOCK FL_USER1 + +static inline void +rb_ary_modify_check(ary) + VALUE ary; +{ + if (OBJ_FROZEN(ary)) rb_error_frozen("array"); + if (FL_TEST(ary, ARY_TMPLOCK)) + rb_raise(rb_eRuntimeError, "can't modify array during iteration"); + if (!OBJ_TAINTED(ary) && rb_safe_level() >= 4) + rb_raise(rb_eSecurityError, "Insecure: can't modify array"); +} + +static void +rb_ary_modify(ary) + VALUE ary; +{ + VALUE *ptr; + + rb_ary_modify_check(ary); + if (FL_TEST(ary, ELTS_SHARED)) { + ptr = ALLOC_N(VALUE, RARRAY(ary)->len); + FL_UNSET(ary, ELTS_SHARED); + RARRAY(ary)->aux.capa = RARRAY(ary)->len; + MEMCPY(ptr, RARRAY(ary)->ptr, VALUE, RARRAY(ary)->len); + RARRAY(ary)->ptr = ptr; + } +} + +VALUE +rb_ary_freeze(ary) + VALUE ary; +{ + return rb_obj_freeze(ary); +} + +/* + * call-seq: + * array.frozen? -> true or false + * + * Return true if this array is frozen (or temporarily frozen + * while being sorted). + */ + +static VALUE +rb_ary_frozen_p(ary) + VALUE ary; +{ + if (OBJ_FROZEN(ary)) return Qtrue; + if (FL_TEST(ary, ARY_TMPLOCK)) return Qtrue; + return Qfalse; +} + +static VALUE ary_alloc(VALUE); +static VALUE +ary_alloc(klass) + VALUE klass; +{ + NEWOBJ(ary, struct RArray); + OBJSETUP(ary, klass, T_ARRAY); + + ary->len = 0; + ary->ptr = 0; + ary->aux.capa = 0; + + return (VALUE)ary; +} + +static VALUE +ary_new(klass, len) + VALUE klass; + long len; +{ + VALUE ary; + + if (len < 0) { + rb_raise(rb_eArgError, "negative array size (or size too big)"); + } + if (len > 0 && len * sizeof(VALUE) <= len) { + rb_raise(rb_eArgError, "array size too big"); + } + if (len == 0) len++; + + ary = ary_alloc(klass); + RARRAY(ary)->ptr = ALLOC_N(VALUE, len); + RARRAY(ary)->aux.capa = len; + + return ary; +} + +VALUE +rb_ary_new2(len) + long len; +{ + return ary_new(rb_cArray, len); +} + + +VALUE +rb_ary_new() +{ + return rb_ary_new2(ARY_DEFAULT_SIZE); +} + +#ifdef HAVE_STDARG_PROTOTYPES +#include +#define va_init_list(a,b) va_start(a,b) +#else +#include +#define va_init_list(a,b) va_start(a) +#endif + +VALUE +#ifdef HAVE_STDARG_PROTOTYPES +rb_ary_new3(long n, ...) +#else +rb_ary_new3(n, va_alist) + long n; + va_dcl +#endif +{ + va_list ar; + VALUE ary; + long i; + + ary = rb_ary_new2(n); + + va_init_list(ar, n); + for (i=0; iptr[i] = va_arg(ar, VALUE); + } + va_end(ar); + + RARRAY(ary)->len = n; + return ary; +} + +VALUE +rb_ary_new4(n, elts) + long n; + const VALUE *elts; +{ + VALUE ary; + + ary = rb_ary_new2(n); + if (n > 0 && elts) { + MEMCPY(RARRAY(ary)->ptr, elts, VALUE, n); + } + RARRAY(ary)->len = n; + + return ary; +} + +VALUE +#ifdef HAVE_STDARG_PROTOTYPES +rb_values_new(long n, ...) +#else +rb_values_new(n, va_alist) + long n; + va_dcl +#endif +{ + va_list ar; + VALUE val; + long i; + + val = ary_new(rb_cValues, n); + va_init_list(ar, n); + for (i=0; iptr[i] = va_arg(ar, VALUE); + } + va_end(ar); + RARRAY(val)->len = n; + + return val; +} + +VALUE +rb_values_new2(n, elts) + long n; + const VALUE *elts; +{ + VALUE val; + + val = ary_new(rb_cValues, n); + if (n > 0 && elts) { + RARRAY(val)->len = n; + MEMCPY(RARRAY(val)->ptr, elts, VALUE, n); + } + + return val; +} + +static VALUE +ary_make_shared(ary) + VALUE ary; +{ + if (!FL_TEST(ary, ELTS_SHARED)) { + NEWOBJ(shared, struct RArray); + OBJSETUP(shared, rb_cArray, T_ARRAY); + + shared->len = RARRAY(ary)->len; + shared->ptr = RARRAY(ary)->ptr; + shared->aux.capa = RARRAY(ary)->aux.capa; + RARRAY(ary)->aux.shared = (VALUE)shared; + FL_SET(ary, ELTS_SHARED); + OBJ_FREEZE(shared); + return (VALUE)shared; + } + else { + return RARRAY(ary)->aux.shared; + } +} + +static VALUE +ary_shared_array(klass, ary) + VALUE klass, ary; +{ + VALUE val = ary_alloc(klass); + + ary_make_shared(ary); + RARRAY(val)->ptr = RARRAY(ary)->ptr; + RARRAY(val)->len = RARRAY(ary)->len; + RARRAY(val)->aux.shared = RARRAY(ary)->aux.shared; + FL_SET(val, ELTS_SHARED); + return val; +} + +VALUE +rb_values_from_ary(ary) + VALUE ary; +{ + return ary_shared_array(rb_cValues, ary); +} + +VALUE +rb_ary_from_values(val) + VALUE val; +{ + return ary_shared_array(rb_cArray, val); +} + +VALUE +rb_assoc_new(car, cdr) + VALUE car, cdr; +{ + return rb_values_new(2, car, cdr); +} + +static VALUE +to_ary(ary) + VALUE ary; +{ + return rb_convert_type(ary, T_ARRAY, "Array", "to_ary"); +} + +static VALUE +to_a(ary) + VALUE ary; +{ + return rb_convert_type(ary, T_ARRAY, "Array", "to_a"); +} + +VALUE +rb_check_array_type(ary) + VALUE ary; +{ + return rb_check_convert_type(ary, T_ARRAY, "Array", "to_ary"); +} + +static VALUE rb_ary_replace _((VALUE, VALUE)); + +/* + * call-seq: + * Array.new(size=0, obj=nil) + * Array.new(array) + * Array.new(size) {|index| block } + * + * Returns a new array. In the first form, the new array is + * empty. In the second it is created with _size_ copies of _obj_ + * (that is, _size_ references to the same + * _obj_). The third form creates a copy of the array + * passed as a parameter (the array is generated by calling + * to_ary on the parameter). In the last form, an array + * of the given size is created. Each element in this array is + * calculated by passing the element's index to the given block and + * storing the return value. + * + * Array.new + * Array.new(2) + * Array.new(5, "A") + * + * # only one copy of the object is created + * a = Array.new(2, Hash.new) + * a[0]['cat'] = 'feline' + * a + * a[1]['cat'] = 'Felix' + * a + * + * # here multiple copies are created + * a = Array.new(2) { Hash.new } + * a[0]['cat'] = 'feline' + * a + * + * squares = Array.new(5) {|i| i*i} + * squares + * + * copy = Array.new(squares) + */ + +static VALUE +rb_ary_initialize(argc, argv, ary) + int argc; + VALUE *argv; + VALUE ary; +{ + long len; + VALUE size, val; + + if (rb_scan_args(argc, argv, "02", &size, &val) == 0) { + RARRAY(ary)->len = 0; + if (rb_block_given_p()) { + rb_warning("given block not used"); + } + return ary; + } + + if (argc == 1 && !FIXNUM_P(size)) { + val = rb_check_array_type(size); + if (!NIL_P(val)) { + rb_ary_replace(ary, val); + return ary; + } + } + + len = NUM2LONG(size); + if (len < 0) { + rb_raise(rb_eArgError, "negative array size"); + } + if (len > 0 && len * (long)sizeof(VALUE) <= len) { + rb_raise(rb_eArgError, "array size too big"); + } + rb_ary_modify(ary); + if (len > RARRAY(ary)->aux.capa) { + REALLOC_N(RARRAY(ary)->ptr, VALUE, len); + RARRAY(ary)->aux.capa = len; + } + if (rb_block_given_p()) { + long i; + + if (argc == 2) { + rb_warn("block supersedes default value argument"); + } + for (i=0; ilen = i + 1; + } + } + else { + memfill(RARRAY(ary)->ptr, len, val); + RARRAY(ary)->len = len; + } + + return ary; +} + + +/* +* Returns a new array populated with the given objects. +* +* Array.[]( 1, 'a', /^A/ ) +* Array[ 1, 'a', /^A/ ] +* [ 1, 'a', /^A/ ] +*/ + +static VALUE +rb_ary_s_create(argc, argv, klass) + int argc; + VALUE *argv; + VALUE klass; +{ + VALUE ary = ary_alloc(klass); + + if (argc > 0) { + RARRAY(ary)->ptr = ALLOC_N(VALUE, argc); + MEMCPY(RARRAY(ary)->ptr, argv, VALUE, argc); + } + RARRAY(ary)->len = RARRAY(ary)->aux.capa = argc; + + return ary; +} + +void +rb_ary_store(ary, idx, val) + VALUE ary; + long idx; + VALUE val; +{ + if (idx < 0) { + idx += RARRAY(ary)->len; + if (idx < 0) { + rb_raise(rb_eIndexError, "index %ld out of array", + idx - RARRAY(ary)->len); + } + } + + rb_ary_modify(ary); + if (idx >= RARRAY(ary)->aux.capa) { + long new_capa = RARRAY(ary)->aux.capa / 2; + + if (new_capa < ARY_DEFAULT_SIZE) { + new_capa = ARY_DEFAULT_SIZE; + } + new_capa += idx; + if (new_capa * (long)sizeof(VALUE) <= new_capa) { + rb_raise(rb_eArgError, "index too big"); + } + REALLOC_N(RARRAY(ary)->ptr, VALUE, new_capa); + RARRAY(ary)->aux.capa = new_capa; + } + if (idx > RARRAY(ary)->len) { + rb_mem_clear(RARRAY(ary)->ptr + RARRAY(ary)->len, + idx-RARRAY(ary)->len + 1); + } + + if (idx >= RARRAY(ary)->len) { + RARRAY(ary)->len = idx + 1; + } + RARRAY(ary)->ptr[idx] = val; +} + +static VALUE +ary_shared_first(argc, argv, ary) + int argc; + VALUE *argv; + VALUE ary; +{ + VALUE nv, result; + long n; + + rb_scan_args(argc, argv, "1", &nv); + n = NUM2LONG(nv); + if (n > RARRAY(ary)->len) { + n = RARRAY(ary)->len; + } + else if (n < 0) { + rb_raise(rb_eArgError, "negative array size"); + } + result = ary_shared_array(rb_cArray, ary); + RARRAY(result)->len = n; + return result; +} + +static VALUE +ary_shared_last(argc, argv, ary) + int argc; + VALUE *argv; + VALUE ary; +{ + VALUE result = ary_shared_first(argc, argv, ary); + + RARRAY(result)->ptr += RARRAY(ary)->len - RARRAY(result)->len; + return result; +} + +/* + * call-seq: + * array << obj -> array + * + * Append---Pushes the given object on to the end of this array. This + * expression returns the array itself, so several appends + * may be chained together. + * + * [ 1, 2 ] << "c" << "d" << [ 3, 4 ] + * #=> [ 1, 2, "c", "d", [ 3, 4 ] ] + * + */ + +VALUE +rb_ary_push(ary, item) + VALUE ary; + VALUE item; +{ + rb_ary_store(ary, RARRAY(ary)->len, item); + return ary; +} + +/* + * call-seq: + * array.push(obj, ... ) -> array + * + * Append---Pushes the given object(s) on to the end of this array. This + * expression returns the array itself, so several appends + * may be chained together. + * + * a = [ "a", "b", "c" ] + * a.push("d", "e", "f") + * #=> ["a", "b", "c", "d", "e", "f"] + */ + +static VALUE +rb_ary_push_m(argc, argv, ary) + int argc; + VALUE *argv; + VALUE ary; +{ + while (argc--) { + rb_ary_push(ary, *argv++); + } + return ary; +} + +VALUE +rb_ary_pop(ary) + VALUE ary; +{ + rb_ary_modify_check(ary); + if (RARRAY(ary)->len == 0) return Qnil; + if (!FL_TEST(ary, ELTS_SHARED) && + RARRAY(ary)->len * 2 < RARRAY(ary)->aux.capa && + RARRAY(ary)->aux.capa > ARY_DEFAULT_SIZE) { + RARRAY(ary)->aux.capa = RARRAY(ary)->len * 2; + REALLOC_N(RARRAY(ary)->ptr, VALUE, RARRAY(ary)->aux.capa); + } + return RARRAY(ary)->ptr[--RARRAY(ary)->len]; +} + +/* + * call-seq: + * array.pop -> obj or nil + * + * Removes the last element from self and returns it, or + * nil if the array is empty. + * + * a = [ "a", "b", "c", "d" ] + * a.pop #=> "d" + * a.pop(2) #=> ["b", "c"] + * a #=> ["a"] + */ + +static VALUE +rb_ary_pop_m(argc, argv, ary) + int argc; + VALUE *argv; + VALUE ary; +{ + VALUE result; + + if (argc == 0) { + return rb_ary_pop(ary); + } + + rb_ary_modify_check(ary); + + result = ary_shared_last(argc, argv, ary); + RARRAY(ary)->len -= RARRAY(result)->len; + return result; +} + +VALUE +rb_ary_shift(ary) + VALUE ary; +{ + VALUE top; + + rb_ary_modify_check(ary); + if (RARRAY(ary)->len == 0) return Qnil; + top = RARRAY(ary)->ptr[0]; + ary_make_shared(ary); + RARRAY(ary)->ptr++; /* shift ptr */ + RARRAY(ary)->len--; + + return top; +} + +/* + * call-seq: + * array.shift -> obj or nil + * + * Returns the first element of self and removes it (shifting all + * other elements down by one). Returns nil if the array + * is empty. + * + * args = [ "-m", "-q", "filename" ] + * args.shift #=> "-m" + * args #=> ["-q", "filename"] + * + * args = [ "-m", "-q", "filename" ] + * args.shift(2) #=> ["-m", "-q"] + * args #=> ["filename"] + */ + +static VALUE +rb_ary_shift_m(argc, argv, ary) + int argc; + VALUE *argv; + VALUE ary; +{ + VALUE result; + long n; + + if (argc == 0) { + return rb_ary_shift(ary); + } + + rb_ary_modify_check(ary); + + result = ary_shared_first(argc, argv, ary); + n = RARRAY(result)->len; + RARRAY(ary)->ptr += n; + RARRAY(ary)->len -= n; + + return result; +} + +VALUE +rb_ary_unshift(ary, item) + VALUE ary, item; +{ + rb_ary_modify(ary); + if (RARRAY(ary)->len == RARRAY(ary)->aux.capa) { + long capa_inc = RARRAY(ary)->aux.capa / 2; + if (capa_inc < ARY_DEFAULT_SIZE) { + capa_inc = ARY_DEFAULT_SIZE; + } + RARRAY(ary)->aux.capa += capa_inc; + REALLOC_N(RARRAY(ary)->ptr, VALUE, RARRAY(ary)->aux.capa); + } + + /* sliding items */ + MEMMOVE(RARRAY(ary)->ptr + 1, RARRAY(ary)->ptr, VALUE, RARRAY(ary)->len); + + RARRAY(ary)->len++; + RARRAY(ary)->ptr[0] = item; + + return ary; +} + +/* + * call-seq: + * array.unshift(obj, ...) -> array + * + * Prepends objects to the front of array. + * other elements up one. + * + * a = [ "b", "c", "d" ] + * a.unshift("a") #=> ["a", "b", "c", "d"] + * a.unshift(1, 2) #=> [ 1, 2, "a", "b", "c", "d"] + */ + +static VALUE +rb_ary_unshift_m(argc, argv, ary) + int argc; + VALUE *argv; + VALUE ary; +{ + long len = RARRAY(ary)->len; + + if (argc == 0) return ary; + + /* make rooms by setting the last item */ + rb_ary_store(ary, len + argc - 1, Qnil); + + /* sliding items */ + MEMMOVE(RARRAY(ary)->ptr + argc, RARRAY(ary)->ptr, VALUE, len); + MEMCPY(RARRAY(ary)->ptr, argv, VALUE, argc); + + return ary; +} + +/* faster version - use this if you don't need to treat negative offset */ +static inline VALUE +rb_ary_elt(ary, offset) + VALUE ary; + long offset; +{ + if (RARRAY(ary)->len == 0) return Qnil; + if (offset < 0 || RARRAY(ary)->len <= offset) { + return Qnil; + } + return RARRAY(ary)->ptr[offset]; +} + +VALUE +rb_ary_entry(ary, offset) + VALUE ary; + long offset; +{ + if (offset < 0) { + offset += RARRAY(ary)->len; + } + return rb_ary_elt(ary, offset); +} + +static VALUE +rb_ary_subseq(ary, beg, len) + VALUE ary; + long beg, len; +{ + VALUE klass, ary2, shared; + VALUE *ptr; + + if (beg > RARRAY(ary)->len) return Qnil; + if (beg < 0 || len < 0) return Qnil; + + if (beg + len > RARRAY(ary)->len) { + len = RARRAY(ary)->len - beg; + if (len < 0) + len = 0; + } + klass = rb_obj_class(ary); + if (len == 0) return ary_new(klass, 0); + + shared = ary_make_shared(ary); + ptr = RARRAY(ary)->ptr; + ary2 = ary_alloc(klass); + RARRAY(ary2)->ptr = ptr + beg; + RARRAY(ary2)->len = len; + RARRAY(ary2)->aux.shared = shared; + FL_SET(ary2, ELTS_SHARED); + + return ary2; +} + +/* + * call-seq: + * array[index] -> obj or nil + * array[start, length] -> an_array or nil + * array[range] -> an_array or nil + * array.slice(index) -> obj or nil + * array.slice(start, length) -> an_array or nil + * array.slice(range) -> an_array or nil + * + * Element Reference---Returns the element at _index_, + * or returns a subarray starting at _start_ and + * continuing for _length_ elements, or returns a subarray + * specified by _range_. + * Negative indices count backward from the end of the + * array (-1 is the last element). Returns nil if the index + * (or starting index) are out of range. + * + * a = [ "a", "b", "c", "d", "e" ] + * a[2] + a[0] + a[1] #=> "cab" + * a[6] #=> nil + * a[1, 2] #=> [ "b", "c" ] + * a[1..3] #=> [ "b", "c", "d" ] + * a[4..7] #=> [ "e" ] + * a[6..10] #=> nil + * a[-3, 3] #=> [ "c", "d", "e" ] + * # special cases + * a[5] #=> nil + * a[5, 1] #=> [] + * a[5..10] #=> [] + * + */ + +VALUE +rb_ary_aref(argc, argv, ary) + int argc; + VALUE *argv; + VALUE ary; +{ + VALUE arg; + long beg, len; + + if (argc == 2) { + beg = NUM2LONG(argv[0]); + len = NUM2LONG(argv[1]); + if (beg < 0) { + beg += RARRAY(ary)->len; + } + return rb_ary_subseq(ary, beg, len); + } + if (argc != 1) { + rb_scan_args(argc, argv, "11", 0, 0); + } + arg = argv[0]; + /* special case - speeding up */ + if (FIXNUM_P(arg)) { + return rb_ary_entry(ary, FIX2LONG(arg)); + } + /* check if idx is Range */ + switch (rb_range_beg_len(arg, &beg, &len, RARRAY(ary)->len, 0)) { + case Qfalse: + break; + case Qnil: + return Qnil; + default: + return rb_ary_subseq(ary, beg, len); + } + return rb_ary_entry(ary, NUM2LONG(arg)); +} + +/* + * call-seq: + * array.at(index) -> obj or nil + * + * Returns the element at _index_. A + * negative index counts from the end of _self_. Returns +nil+ + * if the index is out of range. See also Array#[]. + * (Array#at is slightly faster than Array#[], + * as it does not accept ranges and so on.) + * + * a = [ "a", "b", "c", "d", "e" ] + * a.at(0) #=> "a" + * a.at(-1) #=> "e" + */ + +static VALUE +rb_ary_at(ary, pos) + VALUE ary, pos; +{ + return rb_ary_entry(ary, NUM2LONG(pos)); +} + +/* + * call-seq: + * array.first -> obj or nil + * array.first(n) -> an_array + * + * Returns the first element of the array. If the array is empty, + * returns nil. + * + * a = [ "q", "r", "s", "t" ] + * a.first #=> "q" + * a.first(2) #=> ["q", "r"] + */ + +static VALUE +rb_ary_first(argc, argv, ary) + int argc; + VALUE *argv; + VALUE ary; +{ + if (argc == 0) { + if (RARRAY(ary)->len == 0) return Qnil; + return RARRAY(ary)->ptr[0]; + } + else { + return ary_shared_first(argc, argv, ary); + } +} + +/* + * call-seq: + * array.last -> obj or nil + * array.last(n) -> an_array + * + * Returns the last element(s) of self. If the array is empty, + * the first form returns nil. + * + * a = [ "w", "x", "y", "z" ] + * a.last #=> "z" + * a.last(2) #=> ["y", "z"] + */ + +static VALUE +rb_ary_last(argc, argv, ary) + int argc; + VALUE *argv; + VALUE ary; +{ + if (argc == 0) { + if (RARRAY(ary)->len == 0) return Qnil; + return RARRAY(ary)->ptr[RARRAY(ary)->len-1]; + } + else { + return ary_shared_last(argc, argv, ary); + } +} + +/* + * call-seq: + * array.fetch(index) -> obj + * array.fetch(index, default ) -> obj + * array.fetch(index) {|index| block } -> obj + * + * Tries to return the element at position index. If the index + * lies outside the array, the first form throws an + * IndexError exception, the second form returns + * default, and the third form returns the value of invoking + * the block, passing in the index. Negative values of index + * count from the end of the array. + * + * a = [ 11, 22, 33, 44 ] + * a.fetch(1) #=> 22 + * a.fetch(-1) #=> 44 + * a.fetch(4, 'cat') #=> "cat" + * a.fetch(4) { |i| i*i } #=> 16 + */ + +static VALUE +rb_ary_fetch(argc, argv, ary) + int argc; + VALUE *argv; + VALUE ary; +{ + VALUE pos, ifnone; + long block_given; + long idx; + + rb_scan_args(argc, argv, "11", &pos, &ifnone); + block_given = rb_block_given_p(); + if (block_given && argc == 2) { + rb_warn("block supersedes default value argument"); + } + idx = NUM2LONG(pos); + + if (idx < 0) { + idx += RARRAY(ary)->len; + } + if (idx < 0 || RARRAY(ary)->len <= idx) { + if (block_given) return rb_yield(pos); + if (argc == 1) { + rb_raise(rb_eIndexError, "index %ld out of array", idx); + } + return ifnone; + } + return RARRAY(ary)->ptr[idx]; +} + +/* + * call-seq: + * array.index(obj) -> int or nil + * array.index {|item| block} -> int or nil + * + * Returns the index of the first object in self such that is + * == to obj. If a block is given instead of an + * argument, returns first object for which block is true. + * Returns nil if no match is found. + * + * a = [ "a", "b", "c" ] + * a.index("b") #=> 1 + * a.index("z") #=> nil + * a.index{|x|x=="b"} #=> 1 + */ + +static VALUE +rb_ary_index(argc, argv, ary) + int argc; + VALUE *argv; + VALUE ary; +{ + VALUE val; + long i; + + if (rb_scan_args(argc, argv, "01", &val) == 0) { + for (i=0; ilen; i++) { + if (RTEST(rb_yield(RARRAY(ary)->ptr[i]))) { + return LONG2NUM(i); + } + } + } + else { + for (i=0; ilen; i++) { + if (rb_equal(RARRAY(ary)->ptr[i], val)) + return LONG2NUM(i); + } + } + return Qnil; +} + +/* + * call-seq: + * array.rindex(obj) -> int or nil + * + * Returns the index of the last object in array + * == to obj. If a block is given instead of an + * argument, returns first object for which block is + * true. Returns nil if no match is found. + * + * a = [ "a", "b", "b", "b", "c" ] + * a.rindex("b") #=> 3 + * a.rindex("z") #=> nil + * a.rindex{|x|x=="b"} #=> 3 + */ + +static VALUE +rb_ary_rindex(argc, argv, ary) + int argc; + VALUE *argv; + VALUE ary; +{ + VALUE val; + long i = RARRAY(ary)->len; + + if (rb_scan_args(argc, argv, "01", &val) == 0) { + while (i--) { + if (RTEST(rb_yield(RARRAY(ary)->ptr[i]))) + return LONG2NUM(i); + if (i > RARRAY(ary)->len) { + i = RARRAY(ary)->len; + } + } + } + else { + while (i--) { + if (rb_equal(RARRAY(ary)->ptr[i], val)) + return LONG2NUM(i); + if (i > RARRAY(ary)->len) { + i = RARRAY(ary)->len; + } + } + } + return Qnil; +} + +VALUE +rb_ary_to_ary(obj) + VALUE obj; +{ + if (TYPE(obj) == T_ARRAY) { + return obj; + } + if (rb_respond_to(obj, rb_intern("to_ary"))) { + return to_ary(obj); + } + return rb_ary_new3(1, obj); +} + +static void +rb_ary_splice(ary, beg, len, rpl) + VALUE ary; + long beg, len; + VALUE rpl; +{ + long rlen; + + if (len < 0) rb_raise(rb_eIndexError, "negative length (%ld)", len); + if (beg < 0) { + beg += RARRAY(ary)->len; + if (beg < 0) { + beg -= RARRAY(ary)->len; + rb_raise(rb_eIndexError, "index %ld out of array", beg); + } + } + if (beg + len > RARRAY(ary)->len) { + len = RARRAY(ary)->len - beg; + } + + if (rpl == Qundef) { + rlen = 0; + } + else { + rpl = rb_ary_to_ary(rpl); + rlen = RARRAY(rpl)->len; + } + rb_ary_modify(ary); + + if (beg >= RARRAY(ary)->len) { + len = beg + rlen; + if (len >= RARRAY(ary)->aux.capa) { + REALLOC_N(RARRAY(ary)->ptr, VALUE, len); + RARRAY(ary)->aux.capa = len; + } + rb_mem_clear(RARRAY(ary)->ptr + RARRAY(ary)->len, beg - RARRAY(ary)->len); + if (rlen > 0) { + MEMCPY(RARRAY(ary)->ptr + beg, RARRAY(rpl)->ptr, VALUE, rlen); + } + RARRAY(ary)->len = len; + } + else { + long alen; + + if (beg + len > RARRAY(ary)->len) { + len = RARRAY(ary)->len - beg; + } + + alen = RARRAY(ary)->len + rlen - len; + if (alen >= RARRAY(ary)->aux.capa) { + REALLOC_N(RARRAY(ary)->ptr, VALUE, alen); + RARRAY(ary)->aux.capa = alen; + } + + if (len != rlen) { + MEMMOVE(RARRAY(ary)->ptr + beg + rlen, RARRAY(ary)->ptr + beg + len, + VALUE, RARRAY(ary)->len - (beg + len)); + RARRAY(ary)->len = alen; + } + if (rlen > 0) { + MEMMOVE(RARRAY(ary)->ptr + beg, RARRAY(rpl)->ptr, VALUE, rlen); + } + } +} + +/* + * call-seq: + * array[index] = obj -> obj + * array[start, length] = obj or an_array or nil -> obj or an_array or nil + * array[range] = obj or an_array or nil -> obj or an_array or nil + * + * Element Assignment---Sets the element at _index_, + * or replaces a subarray starting at _start_ and + * continuing for _length_ elements, or replaces a subarray + * specified by _range_. If indices are greater than + * the current capacity of the array, the array grows + * automatically. A negative indices will count backward + * from the end of the array. Inserts elements if _length_ is + * zero. An +IndexError+ is raised if a negative index points + * past the beginning of the array. See also + * Array#push, and Array#unshift. + * + * a = Array.new + * a[4] = "4"; #=> [nil, nil, nil, nil, "4"] + * a[0, 3] = [ 'a', 'b', 'c' ] #=> ["a", "b", "c", nil, "4"] + * a[1..2] = [ 1, 2 ] #=> ["a", 1, 2, nil, "4"] + * a[0, 2] = "?" #=> ["?", 2, nil, "4"] + * a[0..2] = "A" #=> ["A", "4"] + * a[-1] = "Z" #=> ["A", "Z"] + * a[1..-1] = nil #=> ["A", nil] + * a[1..-1] = [] #=> ["A"] + */ + +static VALUE +rb_ary_aset(argc, argv, ary) + int argc; + VALUE *argv; + VALUE ary; +{ + long offset, beg, len; + + if (argc == 3) { + rb_ary_splice(ary, NUM2LONG(argv[0]), NUM2LONG(argv[1]), argv[2]); + return argv[2]; + } + if (argc != 2) { + rb_raise(rb_eArgError, "wrong number of arguments (%d for 2)", argc); + } + if (FIXNUM_P(argv[0])) { + offset = FIX2LONG(argv[0]); + goto fixnum; + } + if (rb_range_beg_len(argv[0], &beg, &len, RARRAY(ary)->len, 1)) { + /* check if idx is Range */ + rb_ary_splice(ary, beg, len, argv[1]); + return argv[1]; + } + + offset = NUM2LONG(argv[0]); +fixnum: + rb_ary_store(ary, offset, argv[1]); + return argv[1]; +} + +/* + * call-seq: + * array.insert(index, obj...) -> array + * + * Inserts the given values before the element with the given index + * (which may be negative). + * + * a = %w{ a b c d } + * a.insert(2, 99) #=> ["a", "b", 99, "c", "d"] + * a.insert(-2, 1, 2, 3) #=> ["a", "b", 99, "c", 1, 2, 3, "d"] + */ + +static VALUE +rb_ary_insert(argc, argv, ary) + int argc; + VALUE *argv; + VALUE ary; +{ + long pos; + + if (argc < 1) { + rb_raise(rb_eArgError, "wrong number of arguments (at least 1)"); + } + pos = NUM2LONG(argv[0]); + if (pos == -1) { + pos = RARRAY(ary)->len; + } + else if (pos < 0) { + pos++; + } + + if (argc == 1) return ary; + rb_ary_splice(ary, pos, 0, rb_ary_new4(argc - 1, argv + 1)); + return ary; +} + +/* + * call-seq: + * array.each {|item| block } -> array + * + * Calls block once for each element in self, passing that + * element as a parameter. + * + * a = [ "a", "b", "c" ] + * a.each {|x| print x, " -- " } + * + * produces: + * + * a -- b -- c -- + */ + +VALUE +rb_ary_each(ary) + VALUE ary; +{ + long i; + + for (i=0; ilen; i++) { + rb_yield(RARRAY(ary)->ptr[i]); + } + return ary; +} + +/* + * call-seq: + * array.each_index {|index| block } -> array + * + * Same as Array#each, but passes the index of the element + * instead of the element itself. + * + * a = [ "a", "b", "c" ] + * a.each_index {|x| print x, " -- " } + * + * produces: + * + * 0 -- 1 -- 2 -- + */ + +static VALUE +rb_ary_each_index(ary) + VALUE ary; +{ + long i; + + for (i=0; ilen; i++) { + rb_yield(LONG2NUM(i)); + } + return ary; +} + +/* + * call-seq: + * array.reverse_each {|item| block } + * + * Same as Array#each, but traverses self in reverse + * order. + * + * a = [ "a", "b", "c" ] + * a.reverse_each {|x| print x, " " } + * + * produces: + * + * c b a + */ + +static VALUE +rb_ary_reverse_each(ary) + VALUE ary; +{ + long len = RARRAY(ary)->len; + + while (len--) { + rb_yield(RARRAY(ary)->ptr[len]); + if (RARRAY(ary)->len < len) { + len = RARRAY(ary)->len; + } + } + return ary; +} + +/* + * call-seq: + * array.length -> int + * + * Returns the number of elements in self. May be zero. + * + * [ 1, 2, 3, 4, 5 ].length #=> 5 + */ + +static VALUE +rb_ary_length(ary) + VALUE ary; +{ + return LONG2NUM(RARRAY(ary)->len); +} + +/* + * call-seq: + * array.empty? -> true or false + * + * Returns true if self array contains no elements. + * + * [].empty? #=> true + */ + +static VALUE +rb_ary_empty_p(ary) + VALUE ary; +{ + if (RARRAY(ary)->len == 0) + return Qtrue; + return Qfalse; +} + +VALUE +rb_ary_dup(ary) + VALUE ary; +{ + VALUE dup = rb_ary_new2(RARRAY(ary)->len); + + DUPSETUP(dup, ary); + MEMCPY(RARRAY(dup)->ptr, RARRAY(ary)->ptr, VALUE, RARRAY(ary)->len); + RARRAY(dup)->len = RARRAY(ary)->len; + return dup; +} + +extern VALUE rb_output_fs; + +static VALUE +recursive_join(ary, arg, recur) + VALUE ary; + VALUE *arg; + int recur; +{ + if (recur) { + return rb_str_new2("[...]"); + } + return rb_ary_join(arg[0], arg[1]); +} + +VALUE +rb_ary_join(ary, sep) + VALUE ary, sep; +{ + long len = 1, i; + int taint = Qfalse; + VALUE result, tmp; + + if (RARRAY(ary)->len == 0) return rb_str_new(0, 0); + if (OBJ_TAINTED(ary) || OBJ_TAINTED(sep)) taint = Qtrue; + + for (i=0; ilen; i++) { + tmp = rb_check_string_type(RARRAY(ary)->ptr[i]); + len += NIL_P(tmp) ? 10 : RSTRING(tmp)->len; + } + if (!NIL_P(sep)) { + StringValue(sep); + len += RSTRING(sep)->len * (RARRAY(ary)->len - 1); + } + result = rb_str_buf_new(len); + for (i=0; ilen; i++) { + tmp = RARRAY(ary)->ptr[i]; + switch (TYPE(tmp)) { + case T_STRING: + break; + case T_ARRAY: + { + VALUE args[2]; + + args[0] = tmp; + args[1] = sep; + tmp = rb_exec_recursive(recursive_join, ary, (VALUE)args); + } + break; + default: + tmp = rb_obj_as_string(tmp); + } + if (i > 0 && !NIL_P(sep)) + rb_str_buf_append(result, sep); + rb_str_buf_append(result, tmp); + if (OBJ_TAINTED(tmp)) taint = Qtrue; + } + + if (taint) OBJ_TAINT(result); + return result; +} + +/* + * call-seq: + * array.join(sep=$,) -> str + * + * Returns a string created by converting each element of the array to + * a string, separated by sep. + * + * [ "a", "b", "c" ].join #=> "abc" + * [ "a", "b", "c" ].join("-") #=> "a-b-c" + */ + +static VALUE +rb_ary_join_m(argc, argv, ary) + int argc; + VALUE *argv; + VALUE ary; +{ + VALUE sep; + + rb_scan_args(argc, argv, "01", &sep); + if (NIL_P(sep)) sep = rb_output_fs; + + return rb_ary_join(ary, sep); +} + +/* + * call-seq: + * array.to_s -> string + * + * Returns _self_.join. + * + * [ "a", "e", "i", "o" ].to_s #=> "aeio" + * + */ + +VALUE +rb_ary_to_s(ary) + VALUE ary; +{ + if (RARRAY(ary)->len == 0) return rb_str_new(0, 0); + + return rb_ary_join(ary, rb_output_fs); +} + +static VALUE +inspect_ary(ary, dummy, recur) + VALUE ary; + VALUE dummy; + int recur; +{ + int tainted = OBJ_TAINTED(ary); + long i; + VALUE s, str; + + if (recur) return rb_tainted_str_new2("[...]"); + str = rb_str_buf_new2("["); + for (i=0; ilen; i++) { + s = rb_inspect(RARRAY(ary)->ptr[i]); + if (OBJ_TAINTED(s)) tainted = Qtrue; + if (i > 0) rb_str_buf_cat2(str, ", "); + rb_str_buf_append(str, s); + } + rb_str_buf_cat2(str, "]"); + if (tainted) OBJ_TAINT(str); + return str; +} + +/* + * call-seq: + * array.inspect -> string + * + * Create a printable version of array. + */ + +static VALUE +rb_ary_inspect(ary) + VALUE ary; +{ + if (RARRAY(ary)->len == 0) return rb_str_new2("[]"); + return rb_exec_recursive(inspect_ary, ary, 0); +} + +/* + * call-seq: + * array.to_a -> array + * + * Returns _self_. If called on a subclass of Array, converts + * the receiver to an Array object. + */ + +static VALUE +rb_ary_to_a(ary) + VALUE ary; +{ + if (rb_obj_class(ary) != rb_cArray) { + VALUE dup = rb_ary_new2(RARRAY(ary)->len); + rb_ary_replace(dup, ary); + return dup; + } + return ary; +} + +/* + * call-seq: + * array.to_ary -> array + * + * Returns _self_. + */ + +static VALUE +rb_ary_to_ary_m(ary) + VALUE ary; +{ + return ary; +} + +VALUE +rb_ary_reverse(ary) + VALUE ary; +{ + VALUE *p1, *p2; + VALUE tmp; + + rb_ary_modify(ary); + if (RARRAY(ary)->len > 1) { + p1 = RARRAY(ary)->ptr; + p2 = p1 + RARRAY(ary)->len - 1; /* points last item */ + + while (p1 < p2) { + tmp = *p1; + *p1++ = *p2; + *p2-- = tmp; + } + } + return ary; +} + +/* + * call-seq: + * array.reverse! -> array + * + * Reverses _self_ in place. + * + * a = [ "a", "b", "c" ] + * a.reverse! #=> ["c", "b", "a"] + * a #=> ["c", "b", "a"] + */ + +static VALUE +rb_ary_reverse_bang(ary) + VALUE ary; +{ + return rb_ary_reverse(ary); +} + +/* + * call-seq: + * array.reverse -> an_array + * + * Returns a new array containing self's elements in reverse order. + * + * [ "a", "b", "c" ].reverse #=> ["c", "b", "a"] + * [ 1 ].reverse #=> [1] + */ + +static VALUE +rb_ary_reverse_m(ary) + VALUE ary; +{ + return rb_ary_reverse(rb_ary_dup(ary)); +} + +struct ary_sort_data { + VALUE ary; + VALUE *ptr; + long len; +}; + +static void +ary_sort_check(data) + struct ary_sort_data *data; +{ + if (RARRAY(data->ary)->ptr != data->ptr || RARRAY(data->ary)->len != data->len) { + rb_raise(rb_eRuntimeError, "array modified during sort"); + } +} + +static int +sort_1(a, b, data) + VALUE *a, *b; + struct ary_sort_data *data; +{ + VALUE retval = rb_yield_values(2, *a, *b); + int n; + + n = rb_cmpint(retval, *a, *b); + ary_sort_check(data); + return n; +} + +static int +sort_2(ap, bp, data) + VALUE *ap, *bp; + struct ary_sort_data *data; +{ + VALUE retval; + VALUE a = *ap, b = *bp; + int n; + + if (FIXNUM_P(a) && FIXNUM_P(b)) { + if ((long)a > (long)b) return 1; + if ((long)a < (long)b) return -1; + return 0; + } + if (TYPE(a) == T_STRING && TYPE(b) == T_STRING) { + return rb_str_cmp(a, b); + } + + retval = rb_funcall(a, id_cmp, 1, b); + n = rb_cmpint(retval, a, b); + ary_sort_check(data); + + return n; +} + +static VALUE +sort_internal(ary) + VALUE ary; +{ + struct ary_sort_data data; + + data.ary = ary; + data.ptr = RARRAY(ary)->ptr; data.len = RARRAY(ary)->len; + qsort(RARRAY(ary)->ptr, RARRAY(ary)->len, sizeof(VALUE), + rb_block_given_p()?sort_1:sort_2, &data); + return ary; +} + +static VALUE +sort_unlock(ary) + VALUE ary; +{ + FL_UNSET(ary, ARY_TMPLOCK); + return ary; +} + +/* + * call-seq: + * array.sort! -> array + * array.sort! {| a,b | block } -> array + * + * Sorts _self_. Comparisons for + * the sort will be done using the <=> operator or using + * an optional code block. The block implements a comparison between + * a and b, returning -1, 0, or +1. See also + * Enumerable#sort_by. + * + * a = [ "d", "a", "e", "c", "b" ] + * a.sort #=> ["a", "b", "c", "d", "e"] + * a.sort {|x,y| y <=> x } #=> ["e", "d", "c", "b", "a"] + */ + +VALUE +rb_ary_sort_bang(ary) + VALUE ary; +{ + rb_ary_modify(ary); + if (RARRAY(ary)->len > 1) { + FL_SET(ary, ARY_TMPLOCK); /* prohibit modification during sort */ + rb_ensure(sort_internal, ary, sort_unlock, ary); + } + return ary; +} + +/* + * call-seq: + * array.sort -> an_array + * array.sort {| a,b | block } -> an_array + * + * Returns a new array created by sorting self. Comparisons for + * the sort will be done using the <=> operator or using + * an optional code block. The block implements a comparison between + * a and b, returning -1, 0, or +1. See also + * Enumerable#sort_by. + * + * a = [ "d", "a", "e", "c", "b" ] + * a.sort #=> ["a", "b", "c", "d", "e"] + * a.sort {|x,y| y <=> x } #=> ["e", "d", "c", "b", "a"] + */ + +VALUE +rb_ary_sort(ary) + VALUE ary; +{ + ary = rb_ary_dup(ary); + rb_ary_sort_bang(ary); + return ary; +} + +/* + * call-seq: + * array.collect {|item| block } -> an_array + * array.map {|item| block } -> an_array + * + * Invokes block once for each element of self. Creates a + * new array containing the values returned by the block. + * See also Enumerable#collect. + * + * a = [ "a", "b", "c", "d" ] + * a.collect {|x| x + "!" } #=> ["a!", "b!", "c!", "d!"] + * a #=> ["a", "b", "c", "d"] + */ + +static VALUE +rb_ary_collect(ary) + VALUE ary; +{ + long i; + VALUE collect; + + if (!rb_block_given_p()) { + return rb_ary_new4(RARRAY(ary)->len, RARRAY(ary)->ptr); + } + + collect = rb_ary_new2(RARRAY(ary)->len); + for (i = 0; i < RARRAY(ary)->len; i++) { + rb_ary_push(collect, rb_yield(RARRAY(ary)->ptr[i])); + } + return collect; +} + +/* + * call-seq: + * array.collect! {|item| block } -> array + * array.map! {|item| block } -> array + * + * Invokes the block once for each element of _self_, replacing the + * element with the value returned by _block_. + * See also Enumerable#collect. + * + * a = [ "a", "b", "c", "d" ] + * a.collect! {|x| x + "!" } + * a #=> [ "a!", "b!", "c!", "d!" ] + */ + +static VALUE +rb_ary_collect_bang(ary) + VALUE ary; +{ + long i; + + rb_ary_modify(ary); + for (i = 0; i < RARRAY(ary)->len; i++) { + rb_ary_store(ary, i, rb_yield(RARRAY(ary)->ptr[i])); + } + return ary; +} + +VALUE +rb_get_values_at(obj, olen, argc, argv, func) + VALUE obj; + long olen; + int argc; + VALUE *argv; + VALUE (*func) _((VALUE,long)); +{ + VALUE result = rb_ary_new2(argc); + long beg, len, i, j; + + for (i=0; i an_array + * + * Returns an array containing the elements in + * _self_ corresponding to the given selector(s). The selectors + * may be either integer indices or ranges. + * See also Array#select. + * + * a = %w{ a b c d e f } + * a.values_at(1, 3, 5) + * a.values_at(1, 3, 5, 7) + * a.values_at(-1, -3, -5, -7) + * a.values_at(1..3, 2...5) + */ + +static VALUE +rb_ary_values_at(argc, argv, ary) + int argc; + VALUE *argv; + VALUE ary; +{ + return rb_get_values_at(ary, RARRAY(ary)->len, argc, argv, rb_ary_entry); +} + +/* + * call-seq: + * array.select {|item| block } -> an_array + * + * Invokes the block passing in successive elements from array, + * returning an array containing those elements for which the block + * returns a true value (equivalent to Enumerable#select). + * + * a = %w{ a b c d e f } + * a.select {|v| v =~ /[aeiou]/} #=> ["a", "e"] + */ + +static VALUE +rb_ary_select(ary) + VALUE ary; +{ + VALUE result; + long i; + + result = rb_ary_new2(RARRAY(ary)->len); + for (i = 0; i < RARRAY(ary)->len; i++) { + if (RTEST(rb_yield(RARRAY(ary)->ptr[i]))) { + rb_ary_push(result, rb_ary_elt(ary, i)); + } + } + return result; +} + Added: external/Pygments-0.8.1/tests/examplefiles/example.cpp ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/example.cpp Thu Aug 9 17:43:13 2007 @@ -0,0 +1,2363 @@ +/*************************************************************************** + ansigenerator.cpp - description + ------------------- + begin : Jul 5 2004 + copyright : (C) 2004 by Andr? Simon + email : andre.simon1 at gmx.de + ***************************************************************************/ + +/*************************************************************************** + * * + * This program is free software; you can redistribute it and/or modify * + * it under the terms of the GNU General Public License as published by * + * the Free Software Foundation; either version 2 of the License, or * + * (at your option) any later version. * + * * + ***************************************************************************/ + +#include "ansigenerator.h" + +using namespace std; + +namespace highlight { + + +string AnsiGenerator::getOpenTag(const string&font, + const string&fgCol, const string&bgCol) { + ostringstream s; + s << "\033["< +#include +#include +#include + +#include "codegenerator.h" +#include "charcodes.h" +#include "version.h" + +namespace highlight { + +/** + \brief This class generates ANSI escape sequences. + + It contains information about the resulting document structure (document + header and footer), the colour system, white space handling and text + formatting attributes. + +* @author Andre Simon +*/ + +class AnsiGenerator : public highlight::CodeGenerator + { + public: + + /** Constructor + \param colourTheme Name of Colour theme to use + */ + AnsiGenerator( const string &colourTheme); + AnsiGenerator(); + ~AnsiGenerator(); + + /** prints document header + \param title Title of the document + */ + string getHeader(const string & title); + + /** Prints document footer*/ + string getFooter(); + + /** Prints document body*/ + void printBody(); + + private: + + /** \return escaped character*/ + virtual string maskCharacter(unsigned char ); + + + /** gibt ANSI-"Tags" zurueck (Farbindex+bold+kursiv)*/ + string getOpenTag(const string&font, + const string&fgCol, const string&bgCol=""); + + + + string getMatchingOpenTag(unsigned int styleID); + string getMatchingCloseTag(unsigned int styleID); + }; + +} +#endif +/* + * Copyright (c) 1998,1999,2000,2001,2002 Tal Davidson. All rights reserved. + * + * ASBeautifier.cpp + * by Tal Davidson (davidsont at bigfoot.com) + * This file is a part of "Artistic Style" - an indentater and reformatter + * of C, C, C# and Java source files. + * + * The "Artistic Style" project, including all files needed to compile it, + * is free software; you can redistribute it and/or use it and/or modify it + * under the terms of the GNU General Public License as published + * by the Free Software Foundation; either version 2 of the License, + * or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + * + * You should have received a copy of the GNU General Public + * License along with this program. + * + * Patches: + * 18 March 1999 - Brian Rampel - + * Fixed inverse insertion of spaces vs. tabs when in -t mode. + * 08 may 2004 + * applied ASBeautifier.cpp.BITFIELD.patch.bz2 + */ + +#include "compiler_defines.h" +#include "ASBeautifier.h" + +#include +#include +#include +#include +#include + + +#define INIT_CONTAINER(container, value) {if ( (container) != NULL ) delete (container); (container) = (value); } +#define DELETE_CONTAINER(container) {if ( (container) != NULL ) delete (container) ; } + +#ifdef USES_NAMESPACE +using namespace std; +#endif + + + + +#ifdef USES_NAMESPACE +namespace astyle + { +#endif + + bool ASBeautifier::calledInitStatic = false; + + vector ASBeautifier::headers; + vector ASBeautifier::nonParenHeaders; + vector ASBeautifier::preBlockStatements; + vector ASBeautifier::assignmentOperators; + vector ASBeautifier::nonAssignmentOperators; + + /* + * initialize the static vars + */ + void ASBeautifier::initStatic() + { + if (calledInitStatic) + return; + + calledInitStatic = true; + + headers.push_back(&AS_IF); + headers.push_back(&AS_ELSE); + headers.push_back(&AS_FOR); + headers.push_back(&AS_WHILE); + headers.push_back(&AS_DO); + headers.push_back(&AS_TRY); + headers.push_back(&AS_CATCH); + headers.push_back(&AS_FINALLY); + headers.push_back(&AS_SYNCHRONIZED); + headers.push_back(&AS_SWITCH); + headers.push_back(&AS_CASE); + headers.push_back(&AS_DEFAULT); + headers.push_back(&AS_FOREACH); + headers.push_back(&AS_LOCK); + headers.push_back(&AS_UNSAFE); + headers.push_back(&AS_FIXED); + headers.push_back(&AS_GET); + headers.push_back(&AS_SET); + headers.push_back(&AS_ADD); + headers.push_back(&AS_REMOVE); + //headers.push_back(&AS_PUBLIC); + //headers.push_back(&AS_PRIVATE); + //headers.push_back(&AS_PROTECTED); + + //headers.push_back(&AS_OPERATOR); + headers.push_back(&AS_TEMPLATE); + headers.push_back(&AS_CONST); + /**/ + headers.push_back(&AS_STATIC); + headers.push_back(&AS_EXTERN); + + nonParenHeaders.push_back(&AS_ELSE); + nonParenHeaders.push_back(&AS_DO); + nonParenHeaders.push_back(&AS_TRY); + nonParenHeaders.push_back(&AS_FINALLY); + nonParenHeaders.push_back(&AS_STATIC); + nonParenHeaders.push_back(&AS_CONST); + nonParenHeaders.push_back(&AS_EXTERN); + nonParenHeaders.push_back(&AS_CASE); + nonParenHeaders.push_back(&AS_DEFAULT); + nonParenHeaders.push_back(&AS_UNSAFE); + nonParenHeaders.push_back(&AS_GET); + nonParenHeaders.push_back(&AS_SET); + nonParenHeaders.push_back(&AS_ADD); + nonParenHeaders.push_back(&AS_REMOVE); + + + + nonParenHeaders.push_back(&AS_PUBLIC); + nonParenHeaders.push_back(&AS_PRIVATE); + nonParenHeaders.push_back(&AS_PROTECTED); + nonParenHeaders.push_back(&AS_TEMPLATE); + nonParenHeaders.push_back(&AS_CONST); + /// nonParenHeaders.push_back(&AS_ASM); + + preBlockStatements.push_back(&AS_CLASS); + preBlockStatements.push_back(&AS_STRUCT); + preBlockStatements.push_back(&AS_UNION); + preBlockStatements.push_back(&AS_INTERFACE); + preBlockStatements.push_back(&AS_NAMESPACE); + preBlockStatements.push_back(&AS_THROWS); + preBlockStatements.push_back(&AS_EXTERN); + + assignmentOperators.push_back(&AS_ASSIGN); + assignmentOperators.push_back(&AS_PLUS_ASSIGN); + assignmentOperators.push_back(&AS_MINUS_ASSIGN); + assignmentOperators.push_back(&AS_MULT_ASSIGN); + assignmentOperators.push_back(&AS_DIV_ASSIGN); + assignmentOperators.push_back(&AS_MOD_ASSIGN); + assignmentOperators.push_back(&AS_OR_ASSIGN); + assignmentOperators.push_back(&AS_AND_ASSIGN); + assignmentOperators.push_back(&AS_XOR_ASSIGN); + assignmentOperators.push_back(&AS_GR_GR_GR_ASSIGN); + assignmentOperators.push_back(&AS_GR_GR_ASSIGN); + assignmentOperators.push_back(&AS_LS_LS_LS_ASSIGN); + assignmentOperators.push_back(&AS_LS_LS_ASSIGN); + + assignmentOperators.push_back(&AS_RETURN); + + nonAssignmentOperators.push_back(&AS_EQUAL); + nonAssignmentOperators.push_back(&AS_PLUS_PLUS); + nonAssignmentOperators.push_back(&AS_MINUS_MINUS); + nonAssignmentOperators.push_back(&AS_NOT_EQUAL); + nonAssignmentOperators.push_back(&AS_GR_EQUAL); + nonAssignmentOperators.push_back(&AS_GR_GR_GR); + nonAssignmentOperators.push_back(&AS_GR_GR); + nonAssignmentOperators.push_back(&AS_LS_EQUAL); + nonAssignmentOperators.push_back(&AS_LS_LS_LS); + nonAssignmentOperators.push_back(&AS_LS_LS); + nonAssignmentOperators.push_back(&AS_ARROW); + nonAssignmentOperators.push_back(&AS_AND); + nonAssignmentOperators.push_back(&AS_OR); + } + + /** + * ASBeautifier's constructor + */ + ASBeautifier::ASBeautifier() + { + initStatic(); + + waitingBeautifierStack = NULL; + activeBeautifierStack = NULL; + waitingBeautifierStackLengthStack = NULL; + activeBeautifierStackLengthStack = NULL; + + headerStack = NULL; + tempStacks = NULL; + blockParenDepthStack = NULL; + blockStatementStack = NULL; + parenStatementStack = NULL; + bracketBlockStateStack = NULL; + inStatementIndentStack = NULL; + inStatementIndentStackSizeStack = NULL; + parenIndentStack = NULL; + sourceIterator = NULL; + + isMinimalConditinalIndentSet = false; + shouldForceTabIndentation = false; + + setSpaceIndentation(4); + setMaxInStatementIndentLength(40); + setClassIndent(false); + setSwitchIndent(false); + setCaseIndent(false); + setBlockIndent(false); + setBracketIndent(false); + setNamespaceIndent(false); + setLabelIndent(false); + setEmptyLineFill(false); + setCStyle(); + setPreprocessorIndent(false); + } + + ASBeautifier::ASBeautifier(const ASBeautifier &other) + { + waitingBeautifierStack = NULL; + activeBeautifierStack = NULL; + waitingBeautifierStackLengthStack = NULL; + activeBeautifierStackLengthStack = NULL; + + headerStack = new vector; + *headerStack = *other.headerStack; + + tempStacks = new vector< vector* >; + vector< vector* >::iterator iter; + for (iter = other.tempStacks->begin(); + iter != other.tempStacks->end(); + ++iter) + { + vector *newVec = new vector; + *newVec = **iter; + tempStacks->push_back(newVec); + } + blockParenDepthStack = new vector; + *blockParenDepthStack = *other.blockParenDepthStack; + + blockStatementStack = new vector; + *blockStatementStack = *other.blockStatementStack; + + parenStatementStack = new vector; + *parenStatementStack = *other.parenStatementStack; + + bracketBlockStateStack = new vector; + *bracketBlockStateStack = *other.bracketBlockStateStack; + + inStatementIndentStack = new vector; + *inStatementIndentStack = *other.inStatementIndentStack; + + inStatementIndentStackSizeStack = new vector; + *inStatementIndentStackSizeStack = *other.inStatementIndentStackSizeStack; + + parenIndentStack = new vector; + *parenIndentStack = *other.parenIndentStack; + + sourceIterator = other.sourceIterator; + + indentString = other.indentString; + currentHeader = other.currentHeader; + previousLastLineHeader = other.previousLastLineHeader; + immediatelyPreviousAssignmentOp = other.immediatelyPreviousAssignmentOp; + isInQuote = other.isInQuote; + isInComment = other.isInComment; + isInCase = other.isInCase; + isInQuestion = other.isInQuestion; + isInStatement =other. isInStatement; + isInHeader = other.isInHeader; + isCStyle = other.isCStyle; + isInOperator = other.isInOperator; + isInTemplate = other.isInTemplate; + isInConst = other.isInConst; + classIndent = other.classIndent; + isInClassHeader = other.isInClassHeader; + isInClassHeaderTab = other.isInClassHeaderTab; + switchIndent = other.switchIndent; + caseIndent = other.caseIndent; + namespaceIndent = other.namespaceIndent; + bracketIndent = other.bracketIndent; + blockIndent = other.blockIndent; + labelIndent = other.labelIndent; + preprocessorIndent = other.preprocessorIndent; + parenDepth = other.parenDepth; + indentLength = other.indentLength; + blockTabCount = other.blockTabCount; + leadingWhiteSpaces = other.leadingWhiteSpaces; + maxInStatementIndent = other.maxInStatementIndent; + templateDepth = other.templateDepth; + quoteChar = other.quoteChar; + prevNonSpaceCh = other.prevNonSpaceCh; + currentNonSpaceCh = other.currentNonSpaceCh; + currentNonLegalCh = other.currentNonLegalCh; + prevNonLegalCh = other.prevNonLegalCh; + isInConditional = other.isInConditional; + minConditionalIndent = other.minConditionalIndent; + prevFinalLineSpaceTabCount = other.prevFinalLineSpaceTabCount; + prevFinalLineTabCount = other.prevFinalLineTabCount; + emptyLineFill = other.emptyLineFill; + probationHeader = other.probationHeader; + isInDefine = other.isInDefine; + isInDefineDefinition = other.isInDefineDefinition; + backslashEndsPrevLine = other.backslashEndsPrevLine; + defineTabCount = other.defineTabCount; + } + + /** + * ASBeautifier's destructor + */ + ASBeautifier::~ASBeautifier() + { + DELETE_CONTAINER( headerStack ); + DELETE_CONTAINER( tempStacks ); + DELETE_CONTAINER( blockParenDepthStack ); + DELETE_CONTAINER( blockStatementStack ); + DELETE_CONTAINER( parenStatementStack ); + DELETE_CONTAINER( bracketBlockStateStack ); + DELETE_CONTAINER( inStatementIndentStack ); + DELETE_CONTAINER( inStatementIndentStackSizeStack ); + DELETE_CONTAINER( parenIndentStack ); + + // DELETE_CONTAINER( sourceIterator ); + } + + /** + * initialize the ASBeautifier. + * + * init() should be called every time a ABeautifier object is to start + * beautifying a NEW source file. + * init() recieves a pointer to a DYNAMICALLY CREATED ASSourceIterator object + * that will be used to iterate through the source code. This object will be + * deleted during the ASBeautifier's destruction, and thus should not be + * deleted elsewhere. + * + * @param iter a pointer to the DYNAMICALLY CREATED ASSourceIterator object. + */ + void ASBeautifier::init(ASSourceIterator *iter) + + { + sourceIterator = iter; + init(); + } + + /** + * initialize the ASBeautifier. + */ + void ASBeautifier::init() + { + INIT_CONTAINER( waitingBeautifierStack, new vector ); + INIT_CONTAINER( activeBeautifierStack, new vector ); + + INIT_CONTAINER( waitingBeautifierStackLengthStack, new vector ); + INIT_CONTAINER( activeBeautifierStackLengthStack, new vector ); + + INIT_CONTAINER( headerStack, new vector ); + INIT_CONTAINER( tempStacks, new vector< vector* > ); + tempStacks->push_back(new vector); + + INIT_CONTAINER( blockParenDepthStack, new vector ); + INIT_CONTAINER( blockStatementStack, new vector ); + INIT_CONTAINER( parenStatementStack, new vector ); + + INIT_CONTAINER( bracketBlockStateStack, new vector ); + bracketBlockStateStack->push_back(true); + + INIT_CONTAINER( inStatementIndentStack, new vector ); + INIT_CONTAINER( inStatementIndentStackSizeStack, new vector ); + inStatementIndentStackSizeStack->push_back(0); + INIT_CONTAINER( parenIndentStack, new vector ); + + immediatelyPreviousAssignmentOp = NULL; + previousLastLineHeader = NULL; + + isInQuote = false; + isInComment = false; + isInStatement = false; + isInCase = false; + isInQuestion = false; + isInClassHeader = false; + isInClassHeaderTab = false; + isInHeader = false; + isInOperator = false; + isInTemplate = false; + isInConst = false; + isInConditional = false; + templateDepth = 0; + parenDepth=0; + blockTabCount = 0; + leadingWhiteSpaces = 0; + prevNonSpaceCh = '{'; + currentNonSpaceCh = '{'; + prevNonLegalCh = '{'; + currentNonLegalCh = '{'; + prevFinalLineSpaceTabCount = 0; + prevFinalLineTabCount = 0; + probationHeader = NULL; + backslashEndsPrevLine = false; + isInDefine = false; + isInDefineDefinition = false; + defineTabCount = 0; + } + + /** + * set indentation style to ANSI C/C++. + */ + void ASBeautifier::setCStyle() + { + isCStyle = true; + } + + /** + * set indentation style to Java / K&R. + */ + void ASBeautifier::setJavaStyle() + { + isCStyle = false; + } + + /** + * indent using one tab per indentation + */ + void ASBeautifier::setTabIndentation(int length, bool forceTabs) + { + indentString = "\t"; + indentLength = length; + shouldForceTabIndentation = forceTabs; + + if (!isMinimalConditinalIndentSet) + minConditionalIndent = indentLength * 2; + } + + /** + + * indent using a number of spaces per indentation. + * + * @param length number of spaces per indent. + */ + void ASBeautifier::setSpaceIndentation(int length) + { + indentString=string(length, ' '); + indentLength = length; + + if (!isMinimalConditinalIndentSet) + minConditionalIndent = indentLength * 2; + } + + /** + * set the maximum indentation between two lines in a multi-line statement. + * + * @param max maximum indentation length. + */ + void ASBeautifier::setMaxInStatementIndentLength(int max) + { + maxInStatementIndent = max; + } + + /** + * set the minimum indentation between two lines in a multi-line condition. + * + * @param min minimal indentation length. + */ + void ASBeautifier::setMinConditionalIndentLength(int min) + { + minConditionalIndent = min; + isMinimalConditinalIndentSet = true; + } + + /** + * set the state of the bracket indentation option. If true, brackets will + * be indented one additional indent. + * + * @param state state of option. + */ + void ASBeautifier::setBracketIndent(bool state) + { + bracketIndent = state; + } + + /** + * set the state of the block indentation option. If true, entire blocks + * will be indented one additional indent, similar to the GNU indent style. + * + * @param state state of option. + */ + void ASBeautifier::setBlockIndent(bool state) + { + if (state) + setBracketIndent(false); // so that we don't have both bracket and block indent + blockIndent = state; + } + + /** + * set the state of the class indentation option. If true, C++ class + * definitions will be indented one additional indent. + * + * @param state state of option. + */ + void ASBeautifier::setClassIndent(bool state) + { + classIndent = state; + } + + /** + * set the state of the switch indentation option. If true, blocks of 'switch' + * statements will be indented one additional indent. + * + * @param state state of option. + */ + void ASBeautifier::setSwitchIndent(bool state) + { + switchIndent = state; + } + + /** + * set the state of the case indentation option. If true, lines of 'case' + * statements will be indented one additional indent. + * + * @param state state of option. + */ + void ASBeautifier::setCaseIndent(bool state) + { + caseIndent = state; + } + /** + * set the state of the namespace indentation option. + * If true, blocks of 'namespace' statements will be indented one + * additional indent. Otherwise, NO indentation will be added. + * + * @param state state of option. + */ + void ASBeautifier::setNamespaceIndent(bool state) + { + namespaceIndent = state; + } + + /** + * set the state of the label indentation option. + * If true, labels will be indented one indent LESS than the + * current indentation level. + * If false, labels will be flushed to the left with NO + * indent at all. + * + * @param state state of option. + */ + void ASBeautifier::setLabelIndent(bool state) + { + labelIndent = state; + } + + /** + * set the state of the preprocessor indentation option. + * If true, multiline #define statements will be indented. + * + * @param state state of option. + */ + void ASBeautifier::setPreprocessorIndent(bool state) + { + preprocessorIndent = state; + } + + /** + * set the state of the empty line fill option. + * If true, empty lines will be filled with the whitespace. + * of their previous lines. + * If false, these lines will remain empty. + * + * @param state state of option. + */ + void ASBeautifier::setEmptyLineFill(bool state) + { + emptyLineFill = state; + } + + /** + * check if there are any indented lines ready to be read by nextLine() + * + * @return are there any indented lines ready? + */ + bool ASBeautifier::hasMoreLines() const + { + return sourceIterator->hasMoreLines(); + } + + /** + * get the next indented line. + * + * @return indented line. + */ + string ASBeautifier::nextLine() + { + return beautify(sourceIterator->nextLine()); + } + + /** + * beautify a line of source code. + * every line of source code in a source code file should be sent + * one after the other to the beautify method. + * + * @return the indented line. + * @param originalLine the original unindented line. + */ + string ASBeautifier::beautify(const string &originalLine) + { + string line; + bool isInLineComment = false; + bool lineStartsInComment = false; + bool isInClass = false; + bool isInSwitch = false; + bool isImmediatelyAfterConst = false; + bool isSpecialChar = false; + + char ch = ' '; + char prevCh; + string outBuffer; // the newly idented line is bufferd here + int tabCount = 0; + const string *lastLineHeader = NULL; + bool closingBracketReached = false; + int spaceTabCount = 0; + char tempCh; + unsigned int headerStackSize = headerStack->size(); + //bool isLineInStatement = isInStatement; + bool shouldIndentBrackettedLine = true; + int lineOpeningBlocksNum = 0; + int lineClosingBlocksNum = 0; + bool previousLineProbation = (probationHeader != NULL); + unsigned int i; + + currentHeader = NULL; + + lineStartsInComment = isInComment; + + // handle and remove white spaces around the line: + // If not in comment, first find out size of white space before line, + // so that possible comments starting in the line continue in + // relation to the preliminary white-space. + if (!isInComment) + { + leadingWhiteSpaces = 0; + while (leadingWhiteSpacesinit(); + //defineBeautifier->isInDefineDefinition = true; + //defineBeautifier->beautify(""); + activeBeautifierStack->push_back(defineBeautifier); + } + else + { + // the is the cloned beautifier that is in charge of indenting the #define. + isInDefine = true; + } + } + else if (preproc.COMPARE(0, 2, string("if")) == 0) + { + // push a new beautifier into the stack + waitingBeautifierStackLengthStack->push_back(waitingBeautifierStack->size()); + activeBeautifierStackLengthStack->push_back(activeBeautifierStack->size()); + waitingBeautifierStack->push_back(new ASBeautifier(*this)); + } + else if (preproc.COMPARE(0, 4/*2*/, string("else")) == 0) + { + if (!waitingBeautifierStack->empty()) + { + // MOVE current waiting beautifier to active stack. + activeBeautifierStack->push_back(waitingBeautifierStack->back()); + waitingBeautifierStack->pop_back(); + } + } + else if (preproc.COMPARE(0, 4, string("elif")) == 0) + { + if (!waitingBeautifierStack->empty()) + { + // append a COPY current waiting beautifier to active stack, WITHOUT deleting the original. + activeBeautifierStack->push_back( new ASBeautifier( *(waitingBeautifierStack->back()) ) ); + } + } + else if (preproc.COMPARE(0, 5, string("endif")) == 0) + { + unsigned int stackLength; + ASBeautifier *beautifier; + + if (!waitingBeautifierStackLengthStack->empty()) + { + stackLength = waitingBeautifierStackLengthStack->back(); + waitingBeautifierStackLengthStack->pop_back(); + while (waitingBeautifierStack->size() > stackLength) + { + beautifier = waitingBeautifierStack->back(); + waitingBeautifierStack->pop_back(); + delete beautifier; + } + } + + if (!activeBeautifierStackLengthStack->empty()) + { + stackLength = activeBeautifierStackLengthStack->back(); + activeBeautifierStackLengthStack->pop_back(); + while (activeBeautifierStack->size() > stackLength) + { + beautifier = activeBeautifierStack->back(); + activeBeautifierStack->pop_back(); + delete beautifier; + } + } + + + } + } + + // check if the last char is a backslash + if(line.length() > 0) + backslashEndsPrevLine = (line[line.length() - 1] == '\\'); + else + backslashEndsPrevLine = false; + + // check if this line ends a multi-line #define + // if so, use the #define's cloned beautifier for the line's indentation + // and then remove it from the active beautifier stack and delete it. + if (!backslashEndsPrevLine && isInDefineDefinition && !isInDefine) + { + string beautifiedLine; + ASBeautifier *defineBeautifier; + + isInDefineDefinition = false; + defineBeautifier = activeBeautifierStack->back(); + activeBeautifierStack->pop_back(); + + beautifiedLine = defineBeautifier->beautify(line); + delete defineBeautifier; + return beautifiedLine; + } + + // unless this is a multi-line #define, return this precompiler line as is. + if (!isInDefine && !isInDefineDefinition) + return originalLine; + } + + // if there exists any worker beautifier in the activeBeautifierStack, + // then use it instead of me to indent the current line. + if (!isInDefine && activeBeautifierStack != NULL && !activeBeautifierStack->empty()) + { + return activeBeautifierStack->back()->beautify(line); + } + + // calculate preliminary indentation based on data from past lines + if (!inStatementIndentStack->empty()) + spaceTabCount = inStatementIndentStack->back(); + + + for (i=0; i0 && (*headerStack)[i-1] != &AS_OPEN_BRACKET + && (*headerStack)[i] == &AS_OPEN_BRACKET))) + ++tabCount; + + if (isCStyle && !namespaceIndent && i >= 1 + && (*headerStack)[i-1] == &AS_NAMESPACE + && (*headerStack)[i] == &AS_OPEN_BRACKET) + --tabCount; + + if (isCStyle && i >= 1 + && (*headerStack)[i-1] == &AS_CLASS + && (*headerStack)[i] == &AS_OPEN_BRACKET ) + { + if (classIndent) + ++tabCount; + isInClass = true; + } + + // is the switchIndent option is on, indent switch statements an additional indent. + else if (switchIndent && i > 1 && + (*headerStack)[i-1] == &AS_SWITCH && + (*headerStack)[i] == &AS_OPEN_BRACKET + ) + { + ++tabCount; + isInSwitch = true; + } + + } + + if (!lineStartsInComment + && isCStyle + && isInClass + && classIndent + && headerStackSize >= 2 + &&(*headerStack)[headerStackSize-2] == &AS_CLASS + && (*headerStack)[headerStackSize-1] == &AS_OPEN_BRACKET + && line[0] == '}') + --tabCount; + + else if (!lineStartsInComment + && isInSwitch + && switchIndent + && headerStackSize >= 2 + && (*headerStack)[headerStackSize-2] == &AS_SWITCH + && (*headerStack)[headerStackSize-1] == &AS_OPEN_BRACKET + && line[0] == '}') + --tabCount; + + if (isInClassHeader) + { + isInClassHeaderTab = true; + tabCount += 2; + } + + if (isInConditional) + { + --tabCount; + } + + + // parse characters in the current line. + + for (i=0; ipush_back(probationHeader); + + // handle the specific probation header + isInConditional = (probationHeader == &AS_SYNCHRONIZED); + if (probationHeader == &AS_CONST) + isImmediatelyAfterConst = true; + // isInConst = true; + /* TODO: + * There is actually no more need for the global isInConst variable. + * The only reason for checking const is to see if there is a const + * immediately before an open-bracket. + * Since CONST is now put into probation and is checked during itspost-char, + * isImmediatelyAfterConst can be set by its own... + */ + + isInStatement = false; + // if the probation comes from the previous line, then indent by 1 tab count. + if (previousLineProbation && ch == '{') + tabCount++; + previousLineProbation = false; + } + + // dismiss the probation header + probationHeader = NULL; + } + + prevNonSpaceCh = currentNonSpaceCh; + currentNonSpaceCh = ch; + if (!isLegalNameChar(ch) && ch != ',' && ch != ';' ) + { + prevNonLegalCh = currentNonLegalCh; + currentNonLegalCh = ch; + } + + //if (isInConst) + //{ + // isInConst = false; + // isImmediatelyAfterConst = true; + //} + + if (isInHeader) + { + isInHeader = false; + currentHeader = headerStack->back(); + } + else + currentHeader = NULL; + + if (isCStyle && isInTemplate + && (ch == '<' || ch == '>') + && findHeader(line, i, nonAssignmentOperators) == NULL) //; + { + if (ch == '<') + { + ++templateDepth; + } + else if (ch == '>') + { + if (--templateDepth <= 0) + { + if (isInTemplate) + ch = ';'; + else + ch = 't'; + isInTemplate = false; + templateDepth = 0; + } + + } + } + + // handle parenthesies + if (ch == '(' || ch == '[' || ch == ')' || ch == ']') + { + if (ch == '(' || ch == '[') + { + if (parenDepth == 0) + { + parenStatementStack->push_back(isInStatement); + isInStatement = true; + } + parenDepth++; + + inStatementIndentStackSizeStack->push_back(inStatementIndentStack->size()); + + if (currentHeader != NULL) + registerInStatementIndent(line, i, spaceTabCount, minConditionalIndent/*indentLength*2*/, true); + else + registerInStatementIndent(line, i, spaceTabCount, 0, true); + } + else if (ch == ')' || ch == ']') + { + parenDepth--; + if (parenDepth == 0) + { + isInStatement = parenStatementStack->back(); + parenStatementStack->pop_back(); + ch = ' '; + + isInConditional = false; + } + + if (!inStatementIndentStackSizeStack->empty()) + { + unsigned int previousIndentStackSize = inStatementIndentStackSizeStack->back(); + inStatementIndentStackSizeStack->pop_back(); + while (previousIndentStackSize < inStatementIndentStack->size()) + inStatementIndentStack->pop_back(); + + if (!parenIndentStack->empty()) + { + int poppedIndent = parenIndentStack->back(); + parenIndentStack->pop_back(); + + if (i == 0) + spaceTabCount = poppedIndent; + } + } + } + + continue; + } + + + if (ch == '{') + { + bool isBlockOpener = false; + + // first, check if '{' is a block-opener or an static-array opener + isBlockOpener = ( (prevNonSpaceCh == '{' && bracketBlockStateStack->back()) + || prevNonSpaceCh == '}' + || prevNonSpaceCh == ')' + || prevNonSpaceCh == ';' + || isInClassHeader + || isBlockOpener + || isImmediatelyAfterConst + || (isInDefine && + (prevNonSpaceCh == '(' + || prevNonSpaceCh == '_' + || isalnum(prevNonSpaceCh))) ); + + isInClassHeader = false; + if (!isBlockOpener && currentHeader != NULL) + { + for (unsigned int n=0; n < nonParenHeaders.size(); n++) + if (currentHeader == nonParenHeaders[n]) + { + isBlockOpener = true; + break; + } + } + bracketBlockStateStack->push_back(isBlockOpener); + if (!isBlockOpener) + { + inStatementIndentStackSizeStack->push_back(inStatementIndentStack->size()); + registerInStatementIndent(line, i, spaceTabCount, 0, true); + parenDepth++; + if (i == 0) + shouldIndentBrackettedLine = false; + + continue; + } + + // this bracket is a block opener... + + ++lineOpeningBlocksNum; + + if (isInClassHeader) + isInClassHeader = false; + if (isInClassHeaderTab) + { + isInClassHeaderTab = false; + tabCount -= 2; + } + + blockParenDepthStack->push_back(parenDepth); + blockStatementStack->push_back(isInStatement); + + inStatementIndentStackSizeStack->push_back(inStatementIndentStack->size()); + + blockTabCount += isInStatement? 1 : 0; + parenDepth = 0; + isInStatement = false; + + tempStacks->push_back(new vector); + headerStack->push_back(&AS_OPEN_BRACKET); + lastLineHeader = &AS_OPEN_BRACKET; // <------ + + continue; + } + + //check if a header has been reached + if (prevCh == ' ') + { + bool isIndentableHeader = true; + const string *newHeader = findHeader(line, i, headers); + if (newHeader != NULL) + { + // if we reached here, then this is a header... + isInHeader = true; + + vector *lastTempStack; + if (tempStacks->empty()) + lastTempStack = NULL; + else + lastTempStack = tempStacks->back(); + + // if a new block is opened, push a new stack into tempStacks to hold the + // future list of headers in the new block. + + // take care of the special case: 'else if (...)' + if (newHeader == &AS_IF && lastLineHeader == &AS_ELSE) + { + //spaceTabCount += indentLength; // to counter the opposite addition that occurs when the 'if' is registered below... + headerStack->pop_back(); + } + + // take care of 'else' + else if (newHeader == &AS_ELSE) + { + if (lastTempStack != NULL) + { + int indexOfIf = indexOf(*lastTempStack, &AS_IF); // <--- + if (indexOfIf != -1) + { + // recreate the header list in headerStack up to the previous 'if' + // from the temporary snapshot stored in lastTempStack. + int restackSize = lastTempStack->size() - indexOfIf - 1; + for (int r=0; rpush_back(lastTempStack->back()); + lastTempStack->pop_back(); + } + if (!closingBracketReached) + tabCount += restackSize; + } + /* + * If the above if is not true, i.e. no 'if' before the 'else', + * then nothing beautiful will come out of this... + * I should think about inserting an Exception here to notify the caller of this... + */ + } + } + + // check if 'while' closes a previous 'do' + else if (newHeader == &AS_WHILE) + { + if (lastTempStack != NULL) + { + int indexOfDo = indexOf(*lastTempStack, &AS_DO); // <--- + if (indexOfDo != -1) + { + // recreate the header list in headerStack up to the previous 'do' + // from the temporary snapshot stored in lastTempStack. + int restackSize = lastTempStack->size() - indexOfDo - 1; + for (int r=0; rpush_back(lastTempStack->back()); + lastTempStack->pop_back(); + } + if (!closingBracketReached) + tabCount += restackSize; + } + } + } + // check if 'catch' closes a previous 'try' or 'catch' + else if (newHeader == &AS_CATCH || newHeader == &AS_FINALLY) + { + if (lastTempStack != NULL) + { + int indexOfTry = indexOf(*lastTempStack, &AS_TRY); + if (indexOfTry == -1) + indexOfTry = indexOf(*lastTempStack, &AS_CATCH); + if (indexOfTry != -1) + { + // recreate the header list in headerStack up to the previous 'try' + // from the temporary snapshot stored in lastTempStack. + int restackSize = lastTempStack->size() - indexOfTry - 1; + for (int r=0; rpush_back(lastTempStack->back()); + lastTempStack->pop_back(); + } + + if (!closingBracketReached) + tabCount += restackSize; + } + } + } + else if (newHeader == &AS_CASE) + { + isInCase = true; + if (!caseIndent) + --tabCount; + } + else if(newHeader == &AS_DEFAULT) + { + isInCase = true; + if (!caseIndent) + --tabCount; + } + else if (newHeader == &AS_PUBLIC || newHeader == &AS_PROTECTED || newHeader == &AS_PRIVATE) + { + if (isCStyle && !isInClassHeader) + --tabCount; + isIndentableHeader = false; + } + //else if ((newHeader == &STATIC || newHeader == &SYNCHRONIZED) && + // !headerStack->empty() && + // (headerStack->back() == &STATIC || headerStack->back() == &SYNCHRONIZED)) + //{ + // isIndentableHeader = false; + //} + else if (newHeader == &AS_STATIC + || newHeader == &AS_SYNCHRONIZED + || (newHeader == &AS_CONST && isCStyle)) + { + if (!headerStack->empty() && + (headerStack->back() == &AS_STATIC + || headerStack->back() == &AS_SYNCHRONIZED + || headerStack->back() == &AS_CONST)) + { + isIndentableHeader = false; + } + else + { + isIndentableHeader = false; + probationHeader = newHeader; + } + } + else if (newHeader == &AS_CONST) + { + // this will be entered only if NOT in C style + // since otherwise the CONST would be found to be a probstion header... + + //if (isCStyle) + // isInConst = true; + isIndentableHeader = false; + } + /* + else if (newHeader == &OPERATOR) + { + if (isCStyle) + isInOperator = true; + isIndentableHeader = false; + } + */ + else if (newHeader == &AS_TEMPLATE) + { + if (isCStyle) + isInTemplate = true; + isIndentableHeader = false; + } + + + if (isIndentableHeader) + { + // 3.2.99 + //spaceTabCount-=indentLength; + headerStack->push_back(newHeader); + isInStatement = false; + if (indexOf(nonParenHeaders, newHeader) == -1) + { + isInConditional = true; + } + lastLineHeader = newHeader; + } + else + isInHeader = false; + + //lastLineHeader = newHeader; + + outBuffer.append(newHeader->substr(1)); + i += newHeader->length() - 1; + + continue; + } + } + + if (isCStyle && !isalpha(prevCh) + && line.COMPARE(i, 8, AS_OPERATOR) == 0 && !isalnum(line[i+8])) + { + isInOperator = true; + outBuffer.append(AS_OPERATOR.substr(1)); + i += 7; + continue; + } + + if (ch == '?') + isInQuestion = true; + + + // special handling of 'case' statements + if (ch == ':') + { + if (line.length() > i+1 && line[i+1] == ':') // look for :: + { + ++i; + outBuffer.append(1, ':'); + ch = ' '; + continue; + } + + else if (isCStyle && isInClass && prevNonSpaceCh != ')') + { + // BEGIN Content of ASBeautifier.cpp.BITFIELD.patch: + + unsigned int chIndex; + char nextCh = 0; + for (chIndex = i+1; chIndex < line.length(); chIndex++) + if (!isWhiteSpace(line[chIndex])) + break; + if (chIndex< line.length()) + nextCh = line[chIndex]; + int nWord =0; + for (chIndex = 0; chIndex < i; chIndex++) + { + if (!isWhiteSpace(line[chIndex])) + { + nWord ++; + while (!isWhiteSpace(line[++chIndex])); + } + } + if ((nextCh >= '0' && nextCh <= '9') || (nWord >1)) + continue; + // END Content of ASBeautifier.cpp.BITFIELD.patch: + + --tabCount; + // found a 'private:' or 'public:' inside a class definition + // so do nothing special + } + + else if (isCStyle && isInClassHeader) + { + + // found a 'class A : public B' definition + // so do nothing special + } + + else if (isInQuestion) + { + isInQuestion = false; + } + else if (isCStyle && prevNonSpaceCh == ')') + { + isInClassHeader = true; + if (i==0) + tabCount += 2; + } + else + { + currentNonSpaceCh = ';'; // so that brackets after the ':' will appear as block-openers + if (isInCase) + { + isInCase = false; + ch = ';'; // from here on, treat char as ';' + } + // BEGIN content of ASBeautifier.cpp.BITFIELD.patch.bz2 + else // bitfield or labels + { + unsigned int chIndex; + char nextCh = 0; + for (chIndex = i+1; (isCStyle && chIndex < line.length()); chIndex++) + if (!isWhiteSpace(line[chIndex])) + break; + if (chIndex< line.length()) + nextCh = line[chIndex]; + + int nWord =0; + for (chIndex = 0; chIndex < i; chIndex++) + { + if (!isWhiteSpace(line[chIndex])) + { + nWord ++; + while (!isWhiteSpace(line[++chIndex])); + } + } + if (isCStyle && (nextCh >= '0' && nextCh <= '9') || (nWord >1)) + { + continue; + } + // END content of ASASBeautifier.cpp.BITFIELD.patch.bz2 + + else // is in a label (e.g. 'label1:') + { + if (labelIndent) + --tabCount; // unindent label by one indent + else + tabCount = 0; // completely flush indent to left + } + + // BEGIN content of ASASBeautifier.cpp.BITFIELD.patch.bz2 + } + // END content of ASASBeautifier.cpp.BITFIELD.patch.bz2 + + } + } + + if ((ch == ';' || (parenDepth>0 && ch == ',')) && !inStatementIndentStackSizeStack->empty()) + while ((unsigned int)inStatementIndentStackSizeStack->back() + (parenDepth>0 ? 1 : 0) < inStatementIndentStack->size()) + inStatementIndentStack->pop_back(); + + + // handle ends of statements + if ( (ch == ';' && parenDepth == 0) || ch == '}'/* || (ch == ',' && parenDepth == 0)*/) + { + if (ch == '}') + { + // first check if this '}' closes a previous block, or a static array... + if (!bracketBlockStateStack->empty()) + { + bool bracketBlockState = bracketBlockStateStack->back(); + bracketBlockStateStack->pop_back(); + if (!bracketBlockState) + { + if (!inStatementIndentStackSizeStack->empty()) + { + // this bracket is a static array + + unsigned int previousIndentStackSize = inStatementIndentStackSizeStack->back(); + inStatementIndentStackSizeStack->pop_back(); + while (previousIndentStackSize < inStatementIndentStack->size()) + inStatementIndentStack->pop_back(); + parenDepth--; + if (i == 0) + shouldIndentBrackettedLine = false; + + if (!parenIndentStack->empty()) + { + int poppedIndent = parenIndentStack->back(); + parenIndentStack->pop_back(); + if (i == 0) + spaceTabCount = poppedIndent; + } + } + continue; + } + } + + // this bracket is block closer... + + ++lineClosingBlocksNum; + + if(!inStatementIndentStackSizeStack->empty()) + inStatementIndentStackSizeStack->pop_back(); + + if (!blockParenDepthStack->empty()) + { + parenDepth = blockParenDepthStack->back(); + blockParenDepthStack->pop_back(); + isInStatement = blockStatementStack->back(); + blockStatementStack->pop_back(); + + if (isInStatement) + blockTabCount--; + } + + closingBracketReached = true; + int headerPlace = indexOf(*headerStack, &AS_OPEN_BRACKET); // <--- + if (headerPlace != -1) + { + const string *popped = headerStack->back(); + while (popped != &AS_OPEN_BRACKET) + { + headerStack->pop_back(); + popped = headerStack->back(); + } + headerStack->pop_back(); + + if (!tempStacks->empty()) + { + vector *temp = tempStacks->back(); + tempStacks->pop_back(); + delete temp; + } + } + + + ch = ' '; // needed due to cases such as '}else{', so that headers ('else' tn tih case) will be identified... + } + + /* + * Create a temporary snapshot of the current block's header-list in the + * uppermost inner stack in tempStacks, and clear the headerStack up to + * the begining of the block. + * Thus, the next future statement will think it comes one indent past + * the block's '{' unless it specifically checks for a companion-header + * (such as a previous 'if' for an 'else' header) within the tempStacks, + * and recreates the temporary snapshot by manipulating the tempStacks. + */ + if (!tempStacks->back()->empty()) + while (!tempStacks->back()->empty()) + tempStacks->back()->pop_back(); + while (!headerStack->empty() && headerStack->back() != &AS_OPEN_BRACKET) + { + tempStacks->back()->push_back(headerStack->back()); + headerStack->pop_back(); + } + + if (parenDepth == 0 && ch == ';') + isInStatement=false; + + isInClassHeader = false; + + continue; + } + + + // check for preBlockStatements ONLY if not within parenthesies + // (otherwise 'struct XXX' statements would be wrongly interpreted...) + if (prevCh == ' ' && !isInTemplate && parenDepth == 0) + { + const string *newHeader = findHeader(line, i, preBlockStatements); + if (newHeader != NULL) + { + isInClassHeader = true; + outBuffer.append(newHeader->substr(1)); + i += newHeader->length() - 1; + //if (isCStyle) + headerStack->push_back(newHeader); + } + } + + // Handle operators + // + + //// // PRECHECK if a '==' or '--' or '++' operator was reached. + //// // If not, then register an indent IF an assignment operator was reached. + //// // The precheck is important, so that statements such as 'i--==2' are not recognized + //// // to have assignment operators (here, '-=') in them . . . + + const string *foundAssignmentOp = NULL; + const string *foundNonAssignmentOp = NULL; + + immediatelyPreviousAssignmentOp = NULL; + + // Check if an operator has been reached. + foundAssignmentOp = findHeader(line, i, assignmentOperators, false); + foundNonAssignmentOp = findHeader(line, i, nonAssignmentOperators, false); + + // Since findHeader's boundry checking was not used above, it is possible + // that both an assignment op and a non-assignment op where found, + // e.g. '>>' and '>>='. If this is the case, treat the LONGER one as the + // found operator. + if (foundAssignmentOp != NULL && foundNonAssignmentOp != NULL) + if (foundAssignmentOp->length() < foundNonAssignmentOp->length()) + foundAssignmentOp = NULL; + else + foundNonAssignmentOp = NULL; + + if (foundNonAssignmentOp != NULL) + { + if (foundNonAssignmentOp->length() > 1) + { + outBuffer.append(foundNonAssignmentOp->substr(1)); + i += foundNonAssignmentOp->length() - 1; + } + } + + else if (foundAssignmentOp != NULL) + + { + if (foundAssignmentOp->length() > 1) + { + outBuffer.append(foundAssignmentOp->substr(1)); + i += foundAssignmentOp->length() - 1; + } + + if (!isInOperator && !isInTemplate) + { + registerInStatementIndent(line, i, spaceTabCount, 0, false); + immediatelyPreviousAssignmentOp = foundAssignmentOp; + isInStatement = true; + } + } + + /* + immediatelyPreviousAssignmentOp = NULL; + bool isNonAssingmentOperator = false; + for (int n = 0; n < nonAssignmentOperators.size(); n++) + if (line.COMPARE(i, nonAssignmentOperators[n]->length(), *(nonAssignmentOperators[n])) == 0) + { + if (nonAssignmentOperators[n]->length() > 1) + { + outBuffer.append(nonAssignmentOperators[n]->substr(1)); + i += nonAssignmentOperators[n]->length() - 1; + } + isNonAssingmentOperator = true; + break; + } + if (!isNonAssingmentOperator) + { + for (int a = 0; a < assignmentOperators.size(); a++) + if (line.COMPARE(i, assignmentOperators[a]->length(), *(assignmentOperators[a])) == 0) + { + if (assignmentOperators[a]->length() > 1) + { + outBuffer.append(assignmentOperators[a]->substr(1)); + i += assignmentOperators[a]->length() - 1; + } + + if (!isInOperator && !isInTemplate) + { + registerInStatementIndent(line, i, spaceTabCount, 0, false); + immediatelyPreviousAssignmentOp = assignmentOperators[a]; + isInStatement = true; + } + break; + } + } + */ + + if (isInOperator) + isInOperator = false; + } + + // handle special cases of unindentation: + + /* + * if '{' doesn't follow an immediately previous '{' in the headerStack + * (but rather another header such as "for" or "if", then unindent it + * by one indentation relative to its block. + */ + // cerr << endl << lineOpeningBlocksNum << " " << lineClosingBlocksNum << " " << previousLastLineHeader << endl; + + // indent #define lines with one less tab + //if (isInDefine) + // tabCount -= defineTabCount-1; + + + if (!lineStartsInComment + && !blockIndent + && outBuffer.length()>0 + && outBuffer[0]=='{' + && !(lineOpeningBlocksNum > 0 && lineOpeningBlocksNum == lineClosingBlocksNum) + && !(headerStack->size() > 1 && (*headerStack)[headerStack->size()-2] == &AS_OPEN_BRACKET) + && shouldIndentBrackettedLine) + --tabCount; + + else if (!lineStartsInComment + && outBuffer.length()>0 + && outBuffer[0]=='}' + && shouldIndentBrackettedLine ) + --tabCount; + + // correctly indent one-line-blocks... + else if (!lineStartsInComment + && outBuffer.length()>0 + && lineOpeningBlocksNum > 0 + && lineOpeningBlocksNum == lineClosingBlocksNum + && previousLastLineHeader != NULL + && previousLastLineHeader != &AS_OPEN_BRACKET) + tabCount -= 1; //lineOpeningBlocksNum - (blockIndent ? 1 : 0); + + if (tabCount < 0) + tabCount = 0; + + // take care of extra bracket indentatation option... + if (bracketIndent && outBuffer.length()>0 && shouldIndentBrackettedLine) + if (outBuffer[0]=='{' || outBuffer[0]=='}') + tabCount++; + + + if (isInDefine) + { + if (outBuffer[0] == '#') + { + string preproc = trim(string(outBuffer.c_str() + 1)); + if (preproc.COMPARE(0, 6, string("define")) == 0) + { + if (!inStatementIndentStack->empty() + && inStatementIndentStack->back() > 0) + { + defineTabCount = tabCount; + } + else + { + defineTabCount = tabCount - 1; + tabCount--; + } + } + } + + tabCount -= defineTabCount; + } + + if (tabCount < 0) + tabCount = 0; + + + // finally, insert indentations into begining of line + + prevFinalLineSpaceTabCount = spaceTabCount; + prevFinalLineTabCount = tabCount; + + if (shouldForceTabIndentation) + { + tabCount += spaceTabCount / indentLength; + spaceTabCount = spaceTabCount % indentLength; + } + + outBuffer = preLineWS(spaceTabCount,tabCount) + outBuffer; + + if (lastLineHeader != NULL) + previousLastLineHeader = lastLineHeader; + + return outBuffer; + } + + + string ASBeautifier::preLineWS(int spaceTabCount, int tabCount) + { + string ws; + + for (int i=0; i 0) + ws += string(" "); + + return ws; + + } + + /** + * register an in-statement indent. + */ + void ASBeautifier::registerInStatementIndent(const string &line, int i, int spaceTabCount, + int minIndent, bool updateParenStack) + { + int inStatementIndent; + int remainingCharNum = line.length() - i; + int nextNonWSChar = 1; + + nextNonWSChar = getNextProgramCharDistance(line, i); + + // if indent is around the last char in the line, indent instead 2 spaces from the previous indent + if (nextNonWSChar == remainingCharNum) + { + int previousIndent = spaceTabCount; + if (!inStatementIndentStack->empty()) + previousIndent = inStatementIndentStack->back(); + + inStatementIndentStack->push_back(/*2*/ indentLength + previousIndent ); + if (updateParenStack) + parenIndentStack->push_back( previousIndent ); + return; + } + + if (updateParenStack) + parenIndentStack->push_back(i+spaceTabCount); + + inStatementIndent = i + nextNonWSChar + spaceTabCount; + + if (i + nextNonWSChar < minIndent) + inStatementIndent = minIndent + spaceTabCount; + + if (i + nextNonWSChar > maxInStatementIndent) + inStatementIndent = indentLength*2 + spaceTabCount; + + + + if (!inStatementIndentStack->empty() && + inStatementIndent < inStatementIndentStack->back()) + inStatementIndent = inStatementIndentStack->back(); + + inStatementIndentStack->push_back(inStatementIndent); + } + + /** + * get distance to the next non-white sspace, non-comment character in the line. + * if no such character exists, return the length remaining to the end of the line. + */ + int ASBeautifier::getNextProgramCharDistance(const string &line, int i) + { + bool inComment = false; + int remainingCharNum = line.length() - i; + int charDistance = 1; + int ch; + + for (charDistance = 1; charDistance < remainingCharNum; charDistance++) + { + ch = line[i + charDistance]; + if (inComment) + { + if (line.COMPARE(i + charDistance, 2, AS_CLOSE_COMMENT) == 0) + { + charDistance++; + inComment = false; + } + continue; + } + else if (isWhiteSpace(ch)) + continue; + else if (ch == '/') + { + if (line.COMPARE(i + charDistance, 2, AS_OPEN_LINE_COMMENT) == 0) + return remainingCharNum; + else if (line.COMPARE(i + charDistance, 2, AS_OPEN_COMMENT) == 0) + { + charDistance++; + inComment = true; + } + } + else + return charDistance; + } + + return charDistance; + } + + + /** + * check if a specific character can be used in a legal variable/method/class name + * + * @return legality of the char. + * @param ch the character to be checked. + */ + bool ASBeautifier::isLegalNameChar(char ch) const + { + return (isalnum(ch) //(ch>='a' && ch<='z') || (ch>='A' && ch<='Z') || (ch>='0' && ch<='9') || + || ch=='.' || ch=='_' || (!isCStyle && ch=='$') || (isCStyle && ch=='~')); + } + + + /** + * check if a specific line position contains a header, out of several possible headers. + * + * @return a pointer to the found header. if no header was found then return NULL. + */ + const string *ASBeautifier::findHeader(const string &line, int i, const vector &possibleHeaders, bool checkBoundry) + { + int maxHeaders = possibleHeaders.size(); + const string *header = NULL; + int p; + + for (p=0; p < maxHeaders; p++) + { + header = possibleHeaders[p]; + + if (line.COMPARE(i, header->length(), *header) == 0) + { + // check that this is a header and not a part of a longer word + // (e.g. not at its begining, not at its middle...) + + int lineLength = line.length(); + int headerEnd = i + header->length(); + char startCh = (*header)[0]; // first char of header + char endCh = 0; // char just after header + char prevCh = 0; // char just before header + + if (headerEnd < lineLength) + { + endCh = line[headerEnd]; + } + if (i > 0) + { + prevCh = line[i-1]; + } + + if (!checkBoundry) + { + return header; + } + else if (prevCh != 0 + && isLegalNameChar(startCh) + && isLegalNameChar(prevCh)) + { + return NULL; + } + else if (headerEnd >= lineLength + || !isLegalNameChar(startCh) + || !isLegalNameChar(endCh)) + { + return header; + } + else + { + return NULL; + } + } + } + + return NULL; + } + + + /** + * check if a specific character can be used in a legal variable/method/class name + * + * @return legality of the char. + * @param ch the character to be checked. + */ + bool ASBeautifier::isWhiteSpace(char ch) const + { + return (ch == ' ' || ch == '\t'); + } + + /** + * find the index number of a string element in a container of strings + * + * @return the index number of element in the ocntainer. -1 if element not found. + * @param container a vector of strings. + * @param element the element to find . + */ + int ASBeautifier::indexOf(vector &container, const string *element) + { + vector::const_iterator where; + + where= find(container.begin(), container.end(), element); + if (where == container.end()) + return -1; + else + return where - container.begin(); + } + + /** + * trim removes the white space surrounding a line. + * + * @return the trimmed line. + * @param str the line to trim. + */ + string ASBeautifier::trim(const string &str) + { + + int start = 0; + int end = str.length() - 1; + + while (start < end && isWhiteSpace(str[start])) + start++; + + while (start <= end && isWhiteSpace(str[end])) + end--; + + string returnStr(str, start, end+1-start); + return returnStr; + } + +#ifdef USES_NAMESPACE +} +#endif +/* + * Copyright (c) 1998,1999,2000,2001,2002 Tal Davidson. All rights reserved. + * + * compiler_defines.h (1 January 1999) + * by Tal Davidson (davidsont at bigfoot.com) + * This file is a part of "Artistic Style" - an indentater and reformatter + * of C, C++, C# and Java source files. + * + * The "Artistic Style" project, including all files needed to compile it, + * is free software; you can redistribute it and/or use it and/or modify it + * under the terms of the GNU General Public License as published + * by the Free Software Foundation; either version 2 of the License, + * or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + * + * You should have received a copy of the GNU General Public + * License along with this program. + */ + + +#ifndef ASBEAUTIFIER_H +#define ASBEAUTIFIER_H + +#include "ASResource.h" +#include "compiler_defines.h" +#include "ASSourceIterator.h" + +#include +#include + + +using namespace std; + +namespace astyle + { + + enum BracketMode { NONE_MODE, ATTACH_MODE, BREAK_MODE, BDAC_MODE }; + enum BracketType { NULL_TYPE = 0, + DEFINITION_TYPE = 1, + COMMAND_TYPE = 2, + ARRAY_TYPE = 4, + SINGLE_LINE_TYPE = 8}; + + + class ASBeautifier : protected ASResource + { + public: + ASBeautifier(); + virtual ~ASBeautifier(); + virtual void init(ASSourceIterator* iter); // pointer to dynamically created iterator. + virtual void init(); + virtual bool hasMoreLines() const; + virtual string nextLine(); + virtual string beautify(const string &line); + void setTabIndentation(int length = 4, bool forceTabs = false); + void setSpaceIndentation(int length = 4); + void setMaxInStatementIndentLength(int max); + void setMinConditionalIndentLength(int min); + void setClassIndent(bool state); + void setSwitchIndent(bool state); + void setCaseIndent(bool state); + void setBracketIndent(bool state); + void setBlockIndent(bool state); + void setNamespaceIndent(bool state); + void setLabelIndent(bool state); + void setCStyle(); + void setJavaStyle(); + void setEmptyLineFill(bool state); + void setPreprocessorIndent(bool state); + + + protected: + int getNextProgramCharDistance(const string &line, int i); + bool isLegalNameChar(char ch) const; + bool isWhiteSpace(char ch) const; + const string *findHeader(const string &line, int i, + const vector &possibleHeaders, + bool checkBoundry = true); + string trim(const string &str); + int indexOf(vector &container, const string *element); + + private: + ASBeautifier(const ASBeautifier ©); + void operator=(ASBeautifier&); // not to be implemented + + void initStatic(); + void registerInStatementIndent(const string &line, int i, int spaceTabCount, + int minIndent, bool updateParenStack); + string preLineWS(int spaceTabCount, int tabCount); + + static vector headers; + static vector nonParenHeaders; + static vector preprocessorHeaders; + static vector preBlockStatements; + static vector assignmentOperators; + static vector nonAssignmentOperators; + + static bool calledInitStatic; + + ASSourceIterator *sourceIterator; + vector *waitingBeautifierStack; + vector *activeBeautifierStack; + vector *waitingBeautifierStackLengthStack; + vector *activeBeautifierStackLengthStack; + vector *headerStack; + vector< vector* > *tempStacks; + vector *blockParenDepthStack; + vector *blockStatementStack; + vector *parenStatementStack; + vector *inStatementIndentStack; + vector *inStatementIndentStackSizeStack; + vector *parenIndentStack; + vector *bracketBlockStateStack; + string indentString; + const string *currentHeader; + const string *previousLastLineHeader; + const string *immediatelyPreviousAssignmentOp; + const string *probationHeader; + bool isInQuote; + bool isInComment; + bool isInCase; + bool isInQuestion; + bool isInStatement; + bool isInHeader; + bool isCStyle; + bool isInOperator; + bool isInTemplate; + bool isInConst; + bool isInDefine; + bool isInDefineDefinition; + bool classIndent; + bool isInClassHeader; + bool isInClassHeaderTab; + bool switchIndent; + bool caseIndent; + bool namespaceIndent; + bool bracketIndent; + bool blockIndent; + bool labelIndent; + bool preprocessorIndent; + bool isInConditional; + bool isMinimalConditinalIndentSet; + bool shouldForceTabIndentation; + int minConditionalIndent; + int parenDepth; + int indentLength; + int blockTabCount; + unsigned int leadingWhiteSpaces; + int maxInStatementIndent; + int templateDepth; + char quoteChar; + char prevNonSpaceCh; + char currentNonSpaceCh; + char currentNonLegalCh; + char prevNonLegalCh; + int prevFinalLineSpaceTabCount; + int prevFinalLineTabCount; + bool emptyLineFill; + bool backslashEndsPrevLine; + int defineTabCount; + }; +} + +#endif +/* + * Copyright (c) 1998,1999,2000,2001,2002 Tal Davidson. All rights reserved. + * + * ASFormatter.cpp + * by Tal Davidson (davidsont at bigfoot.com) + * This file is a part of "Artistic Style" - an indentater and reformatter + * of C, C++, C# and Java source files. + * + * The "Artistic Style" project, including all files needed to compile it, + * is free software; you can redistribute it and/or use it and/or modify it + * under the terms of the GNU General Public License as published + * by the Free Software Foundation; either version 2 of the License, + * or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + * + * You should have received a copy of the GNU General Public + * License along with this program. + * + * + * Patches: + * 26 November 1998 - Richard Bullington - + * A correction of line-breaking in headers following '}', + + * was created using a variation of a patch by Richard Bullington. + * 08 May 2004 + * applied ASFormatter450670.patch.bz2, ASFormatter.cpp.patch.bz2, + * patch1_ssvb_patch.tar.gz + */ + +#include "compiler_defines.h" +#include "ASFormatter.h" + + +#include +#include +#include +#include +#include + + +#define INIT_CONTAINER(container, value) {if ( (container) != NULL ) delete (container); (container) = (value); } +#define DELETE_CONTAINER(container) {if ( (container) != NULL ) delete (container) ; } +#define IS_A(a,b) ( ((a) & (b)) == (b)) +#ifdef USES_NAMESPACE +using namespace std; + Added: external/Pygments-0.8.1/tests/examplefiles/example.pas ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/example.pas Thu Aug 9 17:43:13 2007 @@ -0,0 +1,2708 @@ +// vim:ft=pascal + +unit YTools; + +{=============================================================================== + + cYcnus.YTools 1.0.3 Beta for Delphi 4+ + by licenser and Murphy + + ?2000-2003 by cYcnus + visit www.cYcnus.de + + licenser at cYcnus.de (Heinz N. Gies) + murphy at cYcnus.de (Kornelius Kalnbach) + + this unit is published under the terms of the GPL + +===============================================================================} + +interface + +uses + Windows, SysUtils, Classes, YTypes; + +const + BackSpace = #8; + Tab = #9; + LF = #10; //Line Feed + CR = #13; //Carriage Return + Space = #32; + EOLChars = [CR, LF]; +{$IFNDEF VER140} + sLineBreak = #13#10; + SwitchChars = ['/', '-']; +{$ENDIF} + EOL = sLineBreak; + MaxCard = High(Cardinal); + AllChars = [#0..#255]; + Alphabetical = ['A'..'Z', 'a'..'z']; + DecimalChars = ['0'..'9']; + AlphaNumerical = Alphabetical + DecimalChars; + StrangeChars = [#0..#31, #127, #129, #141..#144, #157, #158]; + + HexadecimalChars = DecimalChars + ['A'..'F', 'a'..'f']; + OctalChars = ['0'..'7']; + BinaryChars = ['0', '1']; + + QuoteChars = ['''', '"']; + WildCards = ['*', '?']; + FileNameEnemies = WildCards + ['\', '/', ':', '<', '>', '|']; + + HexChar: array[THex] of Char = ( + '0','1','2','3','4','5','6','7','8','9','A','B','C','D','E','F'); + LowerHexChar: array[THex] of Char = ( + '0','1','2','3','4','5','6','7','8','9','a','b','c','d','e','f'); + BaseNChar: array[TBaseN] of Char = ( + '0','1','2','3','4','5','6','7','8','9','A','B','C','D','E','F','G','H', + 'I','J','K','L','M','N','O','P','Q','R','S','T','U','V','W','X','Y','Z'); + + cYcnusOverlayColor = $050001; + + faFindEveryFile = faReadOnly + faHidden + faSysFile + faArchive; + + platWin9x = [VER_PLATFORM_WIN32s, VER_PLATFORM_WIN32_WINDOWS]; + + +{ Debugging } +procedure ClearReport(const ReportName: string); +procedure Report(const ReportName, Text: string); +procedure ReportFmt(const ReportName, Fmt: string; const Args: array of const); + +{ Params } +procedure GetParams(Strings: TStrings); overload; +function GetParams(const Separator: string = ' '): string; overload; + +function ParamNum(const S: string): Integer; +function ParamPrefixNum(const Prefix: string): Integer; +function Param(const S: string): Boolean; +function ParamPrefix(const Prefix: string): Boolean; + +function Switch(const Switch: string; const PrefixChars: TCharSet = SwitchChars; + IgnoreCase: Boolean = True): Boolean; +function GetParam(const Prefix: string = ''; const Default: string = ''): string; + +{ Dirs & UserName} +function GetMyDir(FullPath: Boolean = False): string; +function WinDir: string; +function SysDir: string; +function UserName: string; + +{ Strings & Chars} +function FirstChar(const S: string): Char; +function LastChar(const S: string): Char; + +function CharPos(C: Char; const S: string; Offset: Integer = 1): Integer; overload; +function CharPos(C: TCharSet; const S: string; Offset: Integer = 1): Integer; overload; +function CharPosR(C: Char; const S: string; Offset: Integer = -1): Integer; +function PosEx(const SubStr, S: string; Offset: Integer = 1): Integer; +function PosExText(const SubStr, S: string; Offset: Integer = 1): Integer; +function PosExAnsiText(const SubStr, S: string; Offset: Integer = 1): Integer; + +function UntilChar(const S: string; Brake: Char): string; overload; +function UntilChar(const S: string; Brake: TCharSet): string; overload; +function UntilLastChar(const S: string; Brake: Char; + IgnoreNoBrake: Boolean = True): string; + +function FromChar(const S: string; Brake: Char): string; overload; +function FromChar(const S: string; Brake: TCharSet): string; overload; +function FromLastChar(const S: string; Brake: Char; + IgnoreNoBrake: Boolean = False): string; + +function BetweenChars(const S: string; Start, Finish: Char; + Inclusive: Boolean = False): string; + +function UntilStr(const S: string; Brake: string): string; +function FromStr(const S: string; Brake: string): string; + +function StringWrap(const S: string; Width: Integer; const LineEnd: string = EOL): string; + +{ Splitting & Combining } +function Split(const S, Separator: string; IgnoreMultiSep: Boolean = True; + MinCount: Integer = 0): TStrA; overload; +procedure Split(const S, Separator: string; Strings: TStrings; + IgnoreMultiSep: Boolean = True); overload; +function Split(const S: string; Separators: TCharSet; + IgnoreMultiSep: Boolean = True; MinCount: Integer = 0): TStrA; overload; + +procedure TileStr(const S: string; BrakeStart: Integer; BrakeEnd: Integer; + out Left, Right: string); + +function Join(Strings: TStrings; Separator: string = ' '): string; overload; +function Join(StrA: TStrA; Separator: string = ' '): string; overload; + +function MulStr(const S: string; Count: Integer): string; + +{ Strings ausrichten } +function AlignR(const S: string; Width: Integer; Filler: Char = ' '): string; +function MaxStr(const S: string; MaxLen: Integer): string; + +{ Stringing } +function TrimAll(const S: string): string; + +function ControlChar(C: Char): Boolean; +function FriendlyChar(C: Char): Char; + +function FriendlyStr(const S: string): string; overload; +function FriendlyStr(a: TByteA): string; overload; + +function Quote(const S: string; Quoter: Char = '"'): string; +function UnQuote(const S: string): string; +function DeQuote(const S: string): string; + +function StrNumerus(const Value: Integer; const Singular, Plural: string; + const Zero: string = '0'): string; + +function MakeStr(const Items: array of const; Separator: string = ''): string; +procedure ShowText(const Items: array of const; Separator: string = ''); + +{ Delete } +function DeleteChars(const S: string; C: Char): string; overload; +function DeleteChars(const S: string; C: TCharSet): string; overload; +function ExtractChars(const S: string; C: TCharSet): string; + +{ Find } +function CharCount(const S: string; C: Char): Integer; + +function CharIn(const S: string; C: Char): Boolean; overload; +function CharIn(const S: string; C: TCharSet): Boolean; overload; + +function StrAtPos(const S: string; Pos: Integer; const Str: string): Boolean; +function StrAtBegin(const S, Str: string): Boolean; +function StrIn(const S, SubStr: string): Boolean; overload; +function StrIn(A: TStrA; const S: string): Boolean; overload; +function StrIn(SL: TStrings; const S: string): Boolean; overload; +function StrIndex(A: TStrA; const S: string): Integer; overload; +function StrIndex(SL: TStrings; const S: string): Integer; overload; + +function TextAtPos(const S: string; Pos: Integer; const Text: string): Boolean; +function TextAtBegin(const S, Text: string): Boolean; +function TextIn(const S, Text: string): Boolean; overload; +function TextIn(A: TStrA; const Text: string): Boolean; overload; +function TextIn(SL: TStrings; const Text: string): Boolean; overload; +function TextIndex(A: TStrA; const Text: string): Integer; overload; +function TextIndex(SL: TStrings; const Text: string): Integer; overload; + +{ Replace } +function ReplaceChars(const S: string; Old, New: Char): string; overload; +function ReplaceChars(const S: string; Old: TCharSet; New: Char): string; overload; + +function Replace(const S, Old, New: string): string; + +{ TStrings } +function SLOfFile(const FileName: string): TStringList; +function ContainsEmptyLines(SL: TStrings): Boolean; +procedure DeleteEmptyLines(SL: TStrings); +procedure DeleteCommentLines(SL: TStrings; const CommentSign: string = '//'); +procedure WriteSL(Strings: TStrings; const Prefix: string = ''; + const Suffix: string = ''); + +function FindLine(SL: TStrings; const S: string): Integer; + +procedure QuickSortSL(SL: TStringList); + +{ TStrA } +function IncStrA(StrA: TStrA): Integer; + +{ TByteA } +function StrOfByteA(a: TByteA): string; +function ByteAOfStr(const S: string): TByteA; +function ByteAOfInt(i: Integer): TByteA; +function IntOfByteA(A: TByteA): Integer; +function ByteAOfHex(const Hex: string): TByteA; + +function SameByteA(const A, B: TByteA): Boolean; +function Reverse(a: TByteA): TByteA; +function SaveByteA(Data: TByteA; const FileName: string; Overwrite: Boolean = True): Boolean; +function LoadByteA(const FileName: string): TByteA; + +function Endian(i: Integer): Integer; + +{ Files } +function SizeOfFile(const FileName: string): Integer; +function FileEx(const FileName: string; AllowFolders: Boolean = False): Boolean; +function LWPSolve(const Dir: string): string; +function LWPSlash(const Dir: string): string; + +function ExtractDrive(const FileName: string): string; +function ExtractPath(const FileName: string): string; +function ExtractPrefix(const FileName: string): string; +function ExtractSuffix(const FileName: string): string; + +function IsValidFileName(const FileName: string): Boolean; +function MakeValidFileName(FileName: string; const Default: string = 'File'): string; + +{ Converting } +function IsValidInteger(const S: string): Boolean; +function IsValidCardinal(const S: string): Boolean; + +function StrOfBool(flag: Boolean; const TrueStr: string = 'True'; + const FalseStr: string = 'False'): string; +function StrOfInt(i: Integer): string; +function CardOfStr(const S: string): Cardinal; + +function HexOrd(Hex: Char): THex; +function ByteOfHex(Hex: THexByteStr): Byte; + +function DecOfHex(const Hex: string): string; +function HexOfByte(b: Byte): THexByteStr; +function HexOfCard(i: Cardinal): string; overload; +function HexOfCard(i: Cardinal; Digits: Integer): string; overload; + +function PascalHexArray(a: TByteA; Name: string): string; + +function HexOfByteA(a: TByteA; Blocks: Integer = 1; + const Splitter: string = ' '): string; +function BinOfByteA(a: TByteA; Blocks: Integer = 4; + const Splitter: string = ' '): string; + +function CardOfHex(Hex: string): Cardinal; +function IntOfBin(Bin: string): Cardinal; + +function BinOfIntFill(n: cardinal; MinCount: Integer = 8): string; +function BinOfInt(n: cardinal): string; + +function BaseNOfInt(I: Cardinal; B: TBaseN): string; +function IntOfBaseN(V: string; B: TBaseN): Cardinal; + +{ Ranges } +function KeepIn(i, Bottom, Top: Variant): Variant; +function InRange(Value, Bottom, Top: Variant): Boolean; +function InStrictRange(Value, Bottom, Top: Variant): Boolean; +function Min(const A, B: Integer): Integer; overload; +function Min(const A: TIntA): Integer; overload; +function Max(const A, B: Integer): Integer; overload; +function Max(const A: TIntA): Integer; overload; + +const + RangesSeparator = ','; + RangeInnerSeparator = '-'; + RangeInfinite = '*'; + RangeSpecialChars = [RangesSeparator, RangeInnerSeparator, RangeInfinite]; + +function RangesOfStr(const S: string): TRanges; +function InRanges(Ranges: TRanges; TestValue: Cardinal): Boolean; + +function Success(Res: Integer; ResultOnSuccess: Integer = ERROR_SUCCESS): Boolean; +function Failure(Res: Integer; ResultOnSuccess: Integer = ERROR_SUCCESS): Boolean; + +function ExpandString(const S: string): string; + +{ Files } +procedure DeleteFiles(const Mask: string; ScanSubDirs: Boolean = True; + Attributes: Integer = faFindEveryFile); +procedure FileNew(const FileName: string); +function DateTimeOfFileTime(const FileTime: TFileTime): TDateTime; + +{ FileNames } +function GetFileNew(FileName: string; NoFloppyDrives: Boolean = True): string; + +{ Finding Files } +function FindAll(Strings: TStrings; const Mask: string; + ScanSubDirs: Boolean = True; Attributes: Integer = faFindEveryFile; + FileReturn: TFileNameFunc = nil): Boolean; +function FindAllFirst(const Mask: string; ScanSubDirs: Boolean = True; + Attributes: Integer = faFindEveryFile): string; + +function FullOSInfo: string; +function Win32PlatformStr: string; +function Win9x: Boolean; +function WinNT: Boolean; +function Win2000: Boolean; +function WinXP: Boolean; + +var + MyDir: string = ''; + LastSuccessRes: Integer = 0; + +{ Backward compatibility } +{$IFNDEF VER130} +function SameText(const S1, S2: string): Boolean; +{$ENDIF} + +implementation +{$IFNDEF VER140} +uses FileCtrl; +{$ENDIF} + +{$IFNDEF VER130} +function SameText(const S1, S2: string): Boolean; +begin + Result := CompareText(S1, S2) = 0; +end; +{$ENDIF} + +procedure Report(const ReportName, Text: string); +var + F: TextFile; + FileName: string; +begin + FileName := MyDir + ReportName + '.rep'; + Assign(F, FileName); + try + if not FileExists(FileName) then + Rewrite(F) + else + Append(F); + WriteLn(F, Text); + finally + Close(F); + end; +end; + +procedure ClearReport(const ReportName: string); +var + FileName: string; +begin + FileName := MyDir + ReportName + '.rep'; + DeleteFile(FileName); +end; + +procedure ReportFmt(const ReportName, Fmt: string; const Args: array of const); +begin + Report(ReportName, Format(Fmt, Args)); +end; + +procedure GetParams(Strings: TStrings); +var + P: PChar; + Param: string; + + function GetParamStr(var P: PChar; var Param: string): Boolean; + var + Quoted: Boolean; + begin + Param := ''; + + repeat + while (P[0] <> #0) and (P[0] <= ' ') do + Inc(P); + + Quoted := False; + while P[0] <> #0 do begin + if P[0] = '"' then begin + Quoted := not Quoted; + Inc(P); + Continue; end; + if (P[0] <= ' ') and not Quoted then + Break; + Param := Param + P[0]; + Inc(P); + end; + until (Param <> '') or (P[0] = #0); + + Result := Param <> ''; + end; + +begin + Strings.Clear; + P := GetCommandLine; + GetParamStr(P, Param); + while GetParamStr(P, Param) do + Strings.Add(Param); +end; + +function GetParams(const Separator: string = ' '): string; +var + SL: TStringList; +begin + SL := TStringList.Create; + GetParams(SL); + Result := Join(SL, Separator); + SL.Free; +end; + +function Switch(const Switch: string; const PrefixChars: TCharSet = SwitchChars; + IgnoreCase: Boolean = True): Boolean; +//= SysUtils.FindCmdLineSwitch +var + i: Integer; + s: string; +begin + Result := True; + + for i := 1 to ParamCount do begin + s := ParamStr(i); + + if (s <> '') and (s[1] in PrefixChars) then begin + //i know that always s <> '', but this is saver + s := Copy(s, 2, MaxInt); + if (s = Switch) or (IgnoreCase and (0=AnsiCompareText(s, Switch))) then + Exit; + end; + end; + + Result := False; +end; + +function ParamNum(const S: string): Integer; +begin + for Result := 1 to ParamCount do + if 0=AnsiCompareText(ParamStr(Result), S) then + Exit; + + Result := 0; +end; + +function ParamPrefixNum(const Prefix: string): Integer; +var + Len: Integer; +begin + Len := Length(Prefix); + for Result := 1 to ParamCount do + if 0=AnsiCompareText(Copy(ParamStr(Result), 1, Len), Prefix) then + Exit; + + Result := 0; +end; + +function Param(const S: string): Boolean; +begin + Result := ParamNum(S) > 0; +end; + +function ParamPrefix(const Prefix: string): Boolean; +begin + Result := ParamPrefixNum(Prefix) > 0; +end; + +function GetParam(const Prefix: string = ''; const Default: string = ''): string; +var + i: Integer; +begin + Result := Default; + + if Prefix = '' then begin + Result := ParamStr(1); + Exit; end; + + i := ParamPrefixNum(Prefix); + if i > 0 then + Result := Copy(ParamStr(i), Length(Prefix) + 1, MaxInt); +end; + +function GetMyDir(FullPath: Boolean = False): string; +var + Buffer: array[0..260] of Char; +begin + Result := ''; + SetString(Result, Buffer, GetModuleFileName(0, Buffer, SizeOf(Buffer))); + if FullPath then + Result := GetFileNew(Result); + Result := ExtractPath(Result); +end; + +function WinDir: string; +var + Res: PChar; +begin + Result := '\'; + GetMem(Res, MAX_PATH); + GetWindowsDirectory(Res, MAX_PATH); + Result := Res + '\'; + FreeMem(Res, MAX_PATH); +end; + +function SysDir: string; +var + Res: PChar; +begin + Result := '\'; + GetMem(Res, MAX_PATH); + GetSystemDirectory(Res, MAX_PATH); + Result := Res + '\'; + FreeMem(Res, MAX_PATH); +end; + +function UserName: string; +var + Len: Cardinal; + Res: PChar; +begin + Result := ''; + GetMem(Res, MAX_PATH); + Len := MAX_PATH; + GetUserName(Res, Len); + Result := Res; + FreeMem(Res, MAX_PATH); +end; + +function FirstChar(const S: string): Char; +begin + if s = '' then + Result := #0 + else + Result := s[1]; +end; + +function LastChar(const S: string): Char; +begin + if s = '' then + Result := #0 + else + Result := s[Length(s)]; +end; + +function CharPos(C: Char; const S: string; Offset: Integer = 1): Integer; +var + MaxPosToSearch: Integer; +begin + Result := Offset; + MaxPosToSearch := Length(S); + + while Result <= MaxPosToSearch do begin + if S[Result] = C then + Exit; + Inc(Result); + end; + + Result := 0; +end; + +function CharPos(C: TCharSet; const S: string; Offset: Integer = 1): Integer; +var + MaxPosToSearch: Integer; +begin + Result := Offset; + MaxPosToSearch := Length(S); + + while Result <= MaxPosToSearch do begin + if S[Result] in C then + Exit; + Inc(Result); + end; + + Result := 0; +end; + +function CharPosR(C: Char; const S: string; Offset: Integer = -1): Integer; +begin + if Offset < 0 then + Result := Length(S) + 1 - Offset + else + Result := Offset; + if Result > Length(S) then + Result := Length(S); + + while Result > 0 do begin + if S[Result] = C then + Exit; + Dec(Result); + end; +end; + +function PosEx(const SubStr, S: string; Offset: Integer = 1): Integer; +var + MaxPosToSearch, LenSubStr, i: Integer; +begin + if SubStr = '' then begin + Result := 0; + Exit; end; + + if Offset < 1 then + Result := 1 + else + Result := Offset; + + LenSubStr := Length(SubStr); + MaxPosToSearch := Length(S) - LenSubStr + 1; + + while Result <= MaxPosToSearch do begin + if S[Result] = SubStr[1] then begin + i := 1; + + while (i < LenSubStr) + and (S[Result + i] = SubStr[i + 1]) do + Inc(i); + + if i = LenSubStr then + Exit; + end; + Inc(Result); + end; + + Result := 0; +end; + +function PosExText(const SubStr, S: string; Offset: Integer = 1): Integer; +var + MaxPosToSearch, LenSubStr, i: Integer; + + function SameChar(a, b: Char): Boolean; + begin + Result := UpCase(a) = UpCase(b) + end; + +begin + if SubStr = '' then begin + Result := 0; + Exit; end; + + if Offset < 1 then + Result := 1 + else + Result := Offset; + + LenSubStr := Length(SubStr); + MaxPosToSearch := Length(S) - LenSubStr + 1; + + while Result <= MaxPosToSearch do begin + if SameChar(S[Result], SubStr[1]) then begin + i := 1; + + while (i < LenSubStr) + and (SameChar(S[Result + i], SubStr[i + 1])) do + Inc(i); + + if i = LenSubStr then + Exit; + end; + Inc(Result); + end; + + Result := 0; +end; + +function PosExAnsiText(const SubStr, S: string; Offset: Integer = 1): Integer; +var + MaxPosToSearch, LenSubStr, i: Integer; + + function SameChar(a, b: Char): Boolean; + begin + Result := CharLower(PChar(a)) = CharLower(PChar(b)); + end; + +begin + if SubStr = '' then begin + Result := 0; + Exit; end; + + if Offset < 1 then + Result := 1 + else + Result := Offset; + + LenSubStr := Length(SubStr); + MaxPosToSearch := Length(S) - LenSubStr + 1; + + while Result <= MaxPosToSearch do begin + if SameChar(S[Result], SubStr[1]) then begin + i := 1; + + while (i < LenSubStr) + and (SameChar(S[Result + i], SubStr[i + 1])) do + Inc(i); + + if i = LenSubStr then + Exit; + end; + Inc(Result); + end; + + Result := 0; +end; + +function UntilChar(const S: string; Brake: Char): string; +var + p: Integer; +begin + p := CharPos(Brake, S); + + if p > 0 then + Result := Copy(S, 1, p - 1) + else + Result := S; +end; + +function UntilChar(const S: string; Brake: TCharSet): string; +var + p: Integer; +begin + Result := ''; + p := CharPos(Brake, S); + + if p > 0 then + Result := Copy(S, 1, p - 1) + else + Result := S; +end; + +function UntilLastChar(const S: string; Brake: Char; + IgnoreNoBrake: Boolean = True): string; +var + p: Integer; +begin + Result := ''; + p := CharPosR(Brake, S); + + if p > 0 then + Result := Copy(S, 1, p - 1) + else if IgnoreNoBrake then + Result := S; +end; + +function FromChar(const S: string; Brake: Char): string; +var + p: Integer; +begin + Result := ''; + p := CharPos(Brake, S); + + if p > 0 then + Result := Copy(S, p + 1, Length(S) - p); +end; + +function FromChar(const S: string; Brake: TCharSet): string; +var + p: Integer; +begin + Result := ''; + p := CharPos(Brake, S); + + if p > 0 then + Result := Copy(S, p + 1, Length(S) - p); +end; + +function FromLastChar(const S: string; Brake: Char; + IgnoreNoBrake: Boolean = False): string; +var + p: Integer; +begin + Result := ''; + p := CharPosR(Brake, S); + + if p > 0 then + Result := Copy(S, p + 1, Length(S) - p) + else if IgnoreNoBrake then + Result := S; +end; + +function BetweenChars(const S: string; Start, Finish: Char; + Inclusive: Boolean = False): string; +var + p, fin: Integer; +begin + Result := ''; + + p := CharPos(Start, S); + if p = 0 then + Exit; + + fin := CharPos(Finish, S, p + 1); + if fin = 0 then + Exit; + + if not Inclusive then begin + Inc(p); + Dec(fin); + end; + + Result := Copy(S, p, fin - p + 1); +end; + +function UntilStr(const S: string; Brake: string): string; +var + p: Integer; +begin + if Length(Brake) = 1 then begin + Result := UntilChar(S, Brake[1]); + Exit; end; + + p := PosEx(Brake, S); + + if p > 0 then + Result := Copy(S, 1, p - 1) + else + Result := S; +end; + +function FromStr(const S: string; Brake: string): string; +var + p: Integer; +begin + if Length(Brake) = 1 then begin + Result := FromChar(S, Brake[1]); + Exit; end; + + Result := ''; + p := PosEx(Brake, s); + + if p > 0 then begin + Inc(p, Length(Brake)); + Result := Copy(S, p, Length(S) - p + 1); + end; +end; + +function StringWrap(const S: string; Width: Integer; const LineEnd: string = EOL): string; +var + i: Integer; +begin + Result := ''; + if (S = '') or (Width < 1) then + Exit; + + i := 1; + while True do begin + Result := Result + Copy(S, i, Width); + Inc(i, Width); + if i <= Length(S) then + Result := Result + LineEnd + else + Exit; + end; +end; + +function Split(const S, Separator: string; IgnoreMultiSep: Boolean = True; + MinCount: Integer = 0): TStrA; +var + p, fin, SepLen: Integer; + + procedure Add(const S: string); + begin + if IgnoreMultiSep and (S = '') then + Exit; + SetLength(Result, Length(Result) + 1); + Result[High(Result)] := S; + end; + +begin + if S = '' then begin + if Length(Result) < MinCount then + SetLength(Result, MinCount); + Exit; end; + + Result := nil; + SepLen := Length(Separator); + + p := 1; + fin := PosEx(Separator, S); + while fin > 0 do begin + Add(Copy(S, p, fin - p)); + p := fin + SepLen; + fin := PosEx(Separator, S, p); + end; + Add(Copy(S, p, Length(S) - p + 1)); + + if Length(Result) < MinCount then + SetLength(Result, MinCount); +end; + +procedure Split(const S, Separator: string; Strings: TStrings; + IgnoreMultiSep: Boolean = True); +var + p, fin, SepLen: Integer; + + procedure Add(const S: string); + begin + if IgnoreMultiSep and (S = '') then + Exit; + Strings.Add(S); + end; + +begin + if S = '' then + Exit; + + Strings.BeginUpdate; + SepLen := Length(Separator); + p := 1; + fin := PosEx(Separator, S); + while fin > 0 do begin + Add(Copy(S, p, fin - p)); + p := fin + SepLen; + fin := PosEx(Separator, S, p); + end; + Add(Copy(S, p, Length(S) - p + 1)); + Strings.EndUpdate; +end; + +function Split(const S: string; Separators: TCharSet; + IgnoreMultiSep: Boolean = True; MinCount: Integer = 0): TStrA; +var + p, fin: Integer; + + procedure Add(const S: string); + begin + if IgnoreMultiSep and (S = '') then + Exit; + SetLength(Result, Length(Result) + 1); + Result[High(Result)] := S; + end; + +begin + if S = '' then begin + if Length(Result) < MinCount then + SetLength(Result, MinCount); + Exit; end; + + Result := nil; + + p := 1; + fin := CharPos(Separators, S); + while fin > 0 do begin + Add(Copy(S, p, fin - p)); + p := fin + 1; + fin := CharPos(Separators, S, p); + end; + Add(Copy(S, p, Length(S) - p + 1)); + + if Length(Result) < MinCount then + SetLength(Result, MinCount); +end; + +procedure TileStr(const S: string; BrakeStart: Integer; BrakeEnd: Integer; + out Left, Right: string); +begin + Left := Copy(S, 1, BrakeStart-1); + Right := Copy(S, BrakeEnd + 1, MaxInt); +end; + +function Join(Strings: TStrings; Separator: string = ' '): string; +var + i, imax: Integer; +begin + Result := ''; + imax := Strings.Count-1; + for i := 0 to imax do begin + Result := Result + Strings[i]; + if i < imax then + Result := Result + Separator; + end; +end; + +function Join(StrA: TStrA; Separator: string = ' '): string; overload; +var + i: Integer; +begin + Result := ''; + for i := 0 to High(StrA) do begin + Result := Result + StrA[i]; + if i < High(StrA) then + Result := Result + Separator; + end; +end; + +function MulStr(const S: string; Count: Integer): string; +var + P: PChar; + Len, i: Integer; +begin + Result := ''; + if Count = 0 then + Exit; + + Len := Length(S); + SetLength(Result, Len * Count); + + P := Pointer(Result); + for i := 1 to Count do begin + Move(Pointer(S)^, P^, Len); + Inc(P, Len); + end; +end; + +function AlignR(const S: string; Width: Integer; Filler: Char = ' '): string; +begin + Result := MulStr(Filler, Width - Length(S)) + S; +end; + +function MaxStr(const S: string; MaxLen: Integer): string; +var + Len: Integer; +begin + Len := Length(S); + if Len <= MaxLen then begin + Result := S; + Exit end; + + Result := Copy(S, 1, MaxLen - 3) + '...'; +end; + +function TrimAll(const S: string): string; +var + i: Integer; +begin + for i := 1 to Length(S) do + if S[i] > #32 then + Result := Result + S[i]; +end; + +function ControlChar(C: Char): Boolean; +begin + Result := C in StrangeChars; +end; + +function FriendlyChar(C: Char): Char; +begin + case C of + #0: Result := '.'; + #1..#31: Result := '?'; + #255: Result := '#'; + else + Result := C; + end; +end; + +function FriendlyStr(const S: string): string; +var + i: Integer; +begin + SetLength(Result, Length(S)); + for i := 1 to Length(S) do + Result[i] := FriendlyChar(S[i]); +end; + +function FriendlyStr(a: TByteA): string; +var + i: Integer; +begin + SetLength(Result, Length(a)); + for i := 0 to High(a) do + Result[i + 1] := FriendlyChar(Char(a[i])); +end; + +function Quote(const S: string; Quoter: Char = '"'): string; +begin + Result := S; + + if FirstChar(S) <> Quoter then + Result := Quoter + Result; + + if LastChar(S) <> Quoter then + Result := Result + Quoter; +end; + +function DeQuote(const S: string): string; +begin + Result := ''; + if Length(S) > 2 then + Result := Copy(S, 2, Length(S) - 2); +end; + +function UnQuote(const S: string): string; +var + Start, Len: Integer; +begin + Start := 1; + Len := Length(S); + + if (S <> '') and (S[1] in ([#0..#32] + QuoteChars)) then begin + if (LastChar(S) = S[1]) then + Dec(Len); + Inc(Start); + end; + + Result := Copy(S, Start, Len - Start + 1); +end; + +function StrNumerus(const Value: Integer; const Singular, Plural: string; + const Zero: string = '0'): string; +begin + if Abs(Value) = 1 then + Result := IntToStr(Value) + ' ' + Singular + else if Value = 0 then + Result := Zero + ' ' + Plural + else + Result := IntToStr(Value) + ' ' + Plural; +end; + +function MakeStr(const Items: array of const; Separator: string = ''): string; +const + BoolStrings: array[Boolean] of string = ('False', 'True'); + +var + i: Integer; + + function StrOfP(P: Pointer): string; + begin + if P = nil then + Result := '[nil]' + else + Result := '[' + IntToStr(Cardinal(P)) + ']'; + end; + + procedure Add(const S: string); + begin + Result := Result + s + Separator; + end; + +begin + Result := ''; + for i := 0 to High(Items) do + with Items[i] do + case VType of + vtString: Add(VString^); + vtInteger: Add(IntToStr(VInteger)); + vtBoolean: Add(BoolStrings[VBoolean]); + vtChar: Add(VChar); + vtPChar: Add(VPChar); + vtExtended: Add(FloatToStr(VExtended^)); + vtObject: if VObject is TComponent then + Add(TComponent(VObject).Name) + else + Add(VObject.ClassName); + vtClass: Add(VClass.ClassName); + vtAnsiString: Add(string(VAnsiString)); + vtCurrency: Add(CurrToStr(VCurrency^)); + vtInt64: Add(IntToStr(VInt64^)); + vtVariant: Add(string(VVariant^)); + + vtWideChar: Add(VWideChar); + vtPWideChar: Add(VPWideChar); + vtInterface: Add(StrOfP(VInterface)); + vtPointer: Add(StrOfP(VPointer)); + vtWideString: Add(WideString(VWideString)); + end; + if Result <> '' then + SetLength(result, Length(Result) - Length(Separator)); +end; + +procedure ShowText(const Items: array of const; Separator: string = ''); +var + Text: string; +begin + Text := MakeStr(Items, Separator); + + MessageBox(0, PChar(Text), 'Info', MB_OK and MB_APPLMODAL); +end; + +function DeleteChars(const S: string; C: Char): string; +var + i: Integer; +begin + Result := ''; + for i := 1 to Length(S) do + if S[i] <> C then + Result := Result + S[i]; +end; + +function DeleteChars(const S: string; C: TCharSet): string; +var + i: Integer; +begin + Result := ''; + for i := 1 to Length(S) do + if not (S[i] in C) then + Result := Result + S[i]; +end; + +function ExtractChars(const S: string; C: TCharSet): string; +var + i: Integer; +begin + Result := ''; + for i := 1 to Length(S) do + if S[i] in C then + Result := Result + S[i]; +end; + +function CharCount(const S: string; C: Char): Integer; +var + i: Integer; +begin + Result := 0; + for i := 1 to Length(S) do + if S[i] = C then + Inc(Result); +end; + +function StrAtPos(const S: string; Pos: Integer; const Str: string): Boolean; +begin + Result := (Str <> '') and (Str = Copy(S, Pos, Length(Str))); +end; + +function TextAtPos(const S: string; Pos: Integer; const Text: string): Boolean; +begin + Result := (Text <> '') and SameText(Text, Copy(S, Pos, Length(Text))); +end; + +function StrAtBegin(const S, Str: string): Boolean; +begin + Result := StrAtPos(S, 1, Str); +end; + +function TextAtBegin(const S, Text: string): Boolean; +begin + Result := TextAtPos(S, 1, Text); +end; + +function CharIn(const S: string; C: Char): Boolean; +var + i: Integer; +begin + Result := True; + for i := 1 to Length(S) do + if S[i] = C then Exit; + Result := False; +end; + +function CharIn(const S: string; C: TCharSet): Boolean; +var + i: Integer; +begin + Result := False; + for i := 1 to Length(S) do begin + Result := S[i] in C; + if Result then + Exit; + end; +end; + +function StrIn(const S, SubStr: string): Boolean; +begin + Result := PosEx(SubStr, S) > 0; +end; + +function StrIn(SL: TStrings; const S: string): Boolean; +var + i: Integer; +begin + Result := False; + for i := 0 to SL.Count-1 do begin + Result := (S = SL[i]); + if Result then + Exit; + end; +end; + +function StrIn(A: TStrA; const S: string): Boolean; +var + i: Integer; +begin + Result := False; + for i := Low(A) to High(A) do begin + Result := (S = A[i]); + if Result then + Exit; + end; +end; + +function TextIn(const S, Text: string): Boolean; +begin + Result := PosExText(Text, S) > 0; +end; + +function TextIn(SL: TStrings; const Text: string): Boolean; +var + i: Integer; +begin + Result := False; + for i := 0 to SL.Count-1 do begin + Result := SameText(Text, SL[i]); + if Result then + Exit; + end; +end; + +function TextIn(A: TStrA; const Text: string): Boolean; +var + i: Integer; +begin + Result := False; + for i := Low(A) to High(A) do begin + Result := SameText(Text, A[i]); + if Result then + Exit; + end; +end; + +function StrIndex(SL: TStrings; const S: string): Integer; +begin + for Result := 0 to SL.Count-1 do + if S = SL[Result] then + Exit; + Result := -1; +end; + +function StrIndex(A: TStrA; const S: string): Integer; +begin + for Result := Low(A) to High(A) do + if S = A[Result] then + Exit; + Result := -1; +end; + +function TextIndex(SL: TStrings; const Text: string): Integer; +begin + for Result := 0 to SL.Count-1 do + if SameText(Text, SL[Result]) then + Exit; + Result := -1; +end; + +function TextIndex(A: TStrA; const Text: string): Integer; +begin + for Result := Low(A) to High(A) do + if SameText(Text, A[Result]) then + Exit; + Result := -1; +end; + +function ReplaceChars(const S: string; Old, New: Char): string; +var + i: Integer; +begin + Result := S; + for i := 1 to Length(Result) do + if Result[i] = Old then + Result[i] := New; +end; + +function ReplaceChars(const S: string; Old: TCharSet; New: Char): string; +var + i: Integer; +begin + Result := S; + for i := 1 to Length(Result) do + if Result[i] in Old then + Result[i] := New; +end; + +function Replace(const S, Old, New: string): string; +var + oldp, ps: Integer; +begin + ps := 1; + Result := ''; + while True do begin + oldp := ps; + ps := PosEx(Old, S, oldp); + if ps = 0 then begin + Result := Result + Copy(S, oldp, Length(S) - oldp + 1); + Exit; end; + Result := Result + Copy(S, oldp, ps - oldp) + New; + Inc(ps, Length(Old)); + end; +end; + +function SLOfFile(const FileName: string): TStringList; +begin + Result := TStringList.Create; + if FileExists(FileName) then + Result.LoadFromFile(FileName); +end; + +function ContainsEmptyLines(SL: TStrings): Boolean; +begin + Result := StrIn(SL, ''); +end; + +procedure DeleteEmptyLines(SL: TStrings); +var + i: Integer; +begin + i := 0; + while i < SL.Count do begin + if SL[i] = '' then + SL.Delete(i) + else + Inc(i); + end; +end; + +procedure DeleteCommentLines(SL: TStrings; const CommentSign: string = '//'); +var + i: Integer; +begin + i := 0; + while i < SL.Count do begin + if (SL[i] = '') or (StrAtBegin(TrimLeft(SL[i]), CommentSign)) then + SL.Delete(i) + else + Inc(i); + end; +end; + +function FindLine(SL: TStrings; const S: string): Integer; +begin + for Result := 0 to SL.Count-1 do + if TextAtBegin(SL[Result], S) then + Exit; + Result := -1; +end; + +procedure QuickSortSL(SL: TStringList); + + procedure Sort(l, r: Integer); + var + i,j: Integer; + z,x: string; + begin + i := l; + j := r; + x := SL[(j + i) div 2]; + repeat + while SL[i] < x do Inc(i); + while SL[j] > x do Dec(j); + if i <= j then begin + z := SL[i]; + SL[i] := SL[j]; + SL[j] := z; + Inc(i); Dec(j); + end; + until i > j; + if j > l then Sort(l, j); + if i < r then Sort(i, r); + end; + +begin + if SL.Count > 0 then + Sort(0, SL.Count-1); +end; + +function IncStrA(StrA: TStrA): Integer; +begin + SetLength(StrA, Length(StrA) + 1); + Result := High(StrA); +end; + +function StrOfByteA(a: TByteA): string; +begin + Result := string(Copy(a, 0, Length(a))); +end; + +function ByteAOfStr(const S: string): TByteA; +begin + Result := TByteA(Copy(S, 1, Length(s))); +end; + +function ByteAOfInt(i: Integer): TByteA; +begin + SetLength(Result, SizeOf(Integer)); + Move(i, Pointer(Result)^, SizeOf(Integer)); +end; + +function IntOfByteA(A: TByteA): Integer; +begin + Result := 0; + Move(Pointer(A)^, Result, Min(Length(A), SizeOf(Integer))); +end; + +function ByteAOfHex(const Hex: string): TByteA; +var + i: Integer; + h: string; +begin + h := ExtractChars(Hex, HexadecimalChars); + SetLength(Result, Length(h) div 2); + for i := 0 to High(Result) do + Result[i] := ByteOfHex(Copy(h, (i shl 1) + 1, 2)); +end; + +function SizeOfFile(const FileName: string): Integer; +var + F: file; +begin + AssignFile(F, FileName); + {$I-}Reset(F, 1);{$I+} + if IOResult = 0 then begin + Result := FileSize(F); + CloseFile(F); + end else + Result := 0; +end; + +function FileEx(const FileName: string; AllowFolders: Boolean = False): Boolean; +var + FindData: TWin32FindData; +begin + if FileName = '' then begin + Result := False; + Exit; end; + + Result := (AllowFolders and DirectoryExists(FileName)) or + (FindFirstFile(PChar(FileName), FindData) <> INVALID_HANDLE_VALUE); + Result := Result and not CharIn(FileName, WildCards); + Result := Result and (AllowFolders + or ((FindData.dwFileAttributes and FILE_ATTRIBUTE_DIRECTORY) = 0)); +end; + +function LWPSolve(const Dir: string): string; +begin + if (Dir <> '') and (Dir[Length(Dir)] = '\') then begin + Result := Copy(Dir, 1, Length(Dir) - 1); + end else + Result := Dir; +end; + +function LWPSlash(const Dir: string): string; +begin + if (Dir <> '') and (Dir[Length(Dir)] = '\') then begin + Result := Copy(Dir, 1, Length(Dir)); + end else + Result := Dir + '\'; +end; + +function ExtractDrive(const FileName: string): string; +begin + Result := ''; + if (Length(FileName) >= 2) and (FileName[2] = ':') then + Result := UpperCase(FileName[1] + ':\'); +end; + +function ExtractPath(const FileName: string): string; +var + p: Integer; +begin + p := CharPosR('\', FileName); + if P > 0 then + Result := Copy(FileName, 1, p) + else + Result := FileName; +end; + +function ExtractPrefix(const FileName: string): string; +begin + Result := UntilLastChar(ExtractFileName(FileName), '.'); +end; + +function ExtractSuffix(const FileName: string): string; +begin + Result := FromLastChar(ExtractFileName(FileName), '.'); +end; + +function SameByteA(const A, B: TByteA): Boolean; +begin + Result := (A = B) or ((Length(A) = Length(B)) and CompareMem(A, B, Length(A))); +end; + +function Reverse(A: TByteA): TByteA; +var + i: Integer; +begin + SetLength(Result, Length(A)); + + for i := 0 to High(A) do + Result[High(Result) - i] := A[i]; +end; + +function Endian(i: Integer): Integer; +type + EndianArray = packed array[0..3] of Byte; +var + a, b: EndianArray; +begin + a := EndianArray(i); + b[0] := a[3]; + b[1] := a[2]; + b[2] := a[1]; + b[3] := a[0]; + Result := Integer(b); +end; + +function SaveByteA(Data: TByteA; const FileName: string; + Overwrite: Boolean = True): Boolean; +var + F: file; +begin + if FileExists(FileName) and not Overwrite then begin + Result := False; + Exit end; + + AssignFile(F, FileName); + {$I-}Rewrite(F, 1);{$I+} + if IOResult = 0 then begin + if Length(Data) > 0 then + BlockWrite(F, Data[0], Length(Data)); + CloseFile(F); + Result := True; + end else + Result := False; +end; + +function LoadByteA(const FileName: string): TByteA; +var + F: file; +begin + AssignFile(F, FileName); + {$I-}Reset(F, 1);{$I+} + if IOResult = 0 then begin + SetLength(Result, FileSize(F)); + if Length(Result) > 0 then + BlockRead(F, Result[0], FileSize(F)); + CloseFile(F); + end else + SetLength(Result, 0); +end; + +function IsValidFileName(const FileName: string): Boolean; +begin + Result := (FileName <> '') and not CharIn(FileName, FileNameEnemies) + and CharIn(Trim(FileName), AllChars - ['.']); +end; + +function MakeValidFileName(FileName: string; const Default: string = 'File'): string; +begin + if FileName = '' then + FileName := Default; + + if CharIn(FileName, FileNameEnemies) then + Result := ReplaceChars(FileName, FileNameEnemies, '_') + else if not CharIn(Trim(FileName), AllChars - ['.']) then + Result := Default + else + Result := FileName; +end; + +function IsValidInteger(const S: string): Boolean; +{const + LowInt = '2147483648'; + HighInt = '2147483647'; +var + len, RealLen, i, o: Integer; + c: Char; +begin + Result := False; + if S = '' then + Exit; + + len := Length(S); + o := 1; + + if S[1] = '-' then begin + if len = 1 then + Exit; + Inc(o); + while (o <= len) and (S[o] = '0') do + Inc(o); + if o > len then + Exit; + if o < len then begin + RealLen := len - o + 1; + if RealLen > Length(LowInt) then + Exit + else if RealLen = Length(LowInt) then begin + for i := 1 to Length(LowInt) do begin + c := S[i + o - 1]; + if (c < '0') or (c > LowInt[i]) then + Exit; + if c in ['0'..Char((Byte(LowInt[i])-1))] then + Break; + end; + Inc(o, i); + end; + end; + end else begin + while (o <= len) and (S[o] = '0') do + Inc(o); + if o <= len then begin + RealLen := len - o + 1; + if RealLen > Length(HighInt) then + Exit + else if RealLen = Length(HighInt) then begin + for i := 1 to Length(HighInt) do begin + c := S[i + o - 1]; + if (c < '0') or (c > HighInt[i]) then + Exit; + if c in ['0'..Char((Byte(HighInt[i])-1))] then + Break; + end; + Inc(o, i); + end; + end; + end; + + for i := o to len do + if not (S[i] in ['0'..'9']) then + Exit; + + Result := True; } +var + i: Int64; +begin + i := StrToInt64Def(S, High(Int64)); + Result := (i >= Low(Integer)) and (i <= High(Integer)); +end; + +function IsValidCardinal(const S: string): Boolean; +{const + HighCard = '4294967295'; +var + len, RealLen, i, o: Integer; +begin + Result := False; + if S = '' then + Exit; + + len := Length(S); + o := 1; + + while (o <= len) and (S[o] = '0') do + Inc(o); + if o <= len then begin + RealLen := len - o + 1; + if RealLen > Length(HighCard) then + Exit + else if RealLen = Length(HighCard) then begin + for i := 1 to Length(HighCard) do begin + if S[i + o - 1] > HighCard[i] then + Exit; + if S[i + o - 1] in ['0'..Char((Byte(HighCard[i])-1))] then + Break; + end; + Inc(o, i); + end; + end; + + for i := o to len do + if not (S[i] in ['0'..'9']) then + Exit; + + Result := True; } +var + i: Int64; +begin + i := StrToInt64Def(S, -1); + Result := (i >= 0) and (i <= High(Cardinal)); +end; + +function StrOfBool(flag: Boolean; const TrueStr: string = 'True'; + const FalseStr: string = 'False'): string; +begin + if Flag then + Result := TrueStr + else + Result := FalseStr; +end; + +function StrOfInt(i: Integer): string; +begin +{ if i = 0 then begin + Result := '0'; + Exit end; + + while i > 0 do begin + Result := Char(Byte('0') + (i mod 10)) + Result; + i := i div 10; + end;} + Result := IntToStr(i); +end; + +function CardOfStr(const S: string): Cardinal; +var + Res: Int64; +begin + Res := StrToInt64Def(S, -1); + if Res > High(Cardinal) then + Res := High(Cardinal) + else if Res < 0 then + Res := 0; + Result := Cardinal(Res); +end; + +function HexOrd(Hex: Char): THex; +begin + case Hex of + '0'..'9': + Result := Byte(Hex) - 48; + 'A'..'F': + Result := Byte(Hex) - 55; + 'a'..'f': + Result := Byte(Hex) - 87; + else + Result := 0; + end; +end; + +function ByteOfHex(Hex: THexByteStr): Byte; +begin + Result := (HexOrd(Hex[1]) shl 4) + HexOrd(Hex[2]); +end; + +function DecOfHex(const Hex: string): string; +begin + Result := IntToStr(CardOfHex(Hex)); +end; + +function HexOfByte(b: Byte): THexByteStr; +begin + Result := HexChar[(b and $F0) shr 4] + + HexChar[ b and $0F ]; +end; + +{function HexOfCard2(c: Cardinal): string; +var + Data: array[0..(1 shl 4) - 1] of Char; + i: Integer; +begin + for i := 0 to (1 shl 4) - 1 do + if i < 10 then + Data[i] := Char(Ord('0') + i) + else + Data[i] := Char(Ord('A') + i - 10); + + Result := Data[(c and (((1 shl (1 shl 2)) - 1) shl (7 shl 2))) shr (7 shl 2)] + + Data[(c and (((1 shl (1 shl 2)) - 1) shl (6 shl 2))) shr (6 shl 2)] + + Data[(c and (((1 shl (1 shl 2)) - 1) shl (5 shl 2))) shr (5 shl 2)] + + Data[(c and (((1 shl (1 shl 2)) - 1) shl (4 shl 2))) shr (4 shl 2)] + + Data[(c and (((1 shl (1 shl 2)) - 1) shl (3 shl 2))) shr (3 shl 2)] + + Data[(c and (((1 shl (1 shl 2)) - 1) shl (2 shl 2))) shr (2 shl 2)] + + Data[(c and (((1 shl (1 shl 2)) - 1) shl (1 shl 2))) shr (1 shl 2)] + + Data[(c and (((1 shl (1 shl 2)) - 1) shl (0 shl 2))) shr (0 shl 2)]; +end; } + +function HexOfCard(i: Cardinal): string; +var + a: Cardinal; +begin + Result := ''; + while i > 0 do begin + a := i and $F; + Result := HexChar[a] + Result; + i := i shr 4; + end; +end; + +function HexOfCard(i: Cardinal; Digits: Integer): string; +var + a: Cardinal; +begin + Result := ''; + while i > 0 do begin + a := i and $F; + Result := HexChar[a] + Result; + i := i shr 4; + end; + Result := MulStr('0', Digits - Length(Result)) + Result; +end; + +function PascalHexArray(a: TByteA; Name: string): string; +var + i, len: Integer; +begin + Result := 'const' + EOL + + ' ' + Name + ': array[0..' + IntToStr(High(a)) + '] of Byte = ('; + + len := Length(a); + for i := 0 to len-1 do begin + if (i mod 19) = 0 then + Result := Result + EOL + ' ' + ' '; + Result := Result + '$' + HexOfByte(a[i]); + if i < len-1 then + Result := Result + ','; + end; + Result := Result + EOL + ' );'; +end; + +function HexOfByteA(a: TByteA; Blocks: Integer = 1; + const Splitter: string = ' '): string; +var + i: Integer; +begin + Result := ''; + + if Blocks > 0 then + for i := 0 to High(a) do begin + Result := Result + HexOfByte(a[i]); + if i < High(a) then + if ((i+1) mod Blocks) = 0 then + Result := Result + Splitter; + end + else + for i := 0 to High(a) do + Result := Result + HexOfByte(a[i]); +end; + +function BinOfByteA(a: TByteA; Blocks: Integer = 4; + const Splitter: string = ' '): string; +var + i, max: Integer; + Bit: Boolean; +begin + Result := ''; + + if Blocks > 0 then begin + max := 8 * (High(a)) + 7; + for i := 0 to max do begin + Bit := 7-(i mod 8) in TBitSet(a[i div 8]); + Result := Result + Char(Byte('0') + Byte(Bit)); + if i < max then + if ((i+1) mod Blocks) = 0 then + Result := Result + Splitter; + end; + end else + for i := 0 to High(a) do + Result := Result + Char(Byte('0') + a[i] shr (i and 8)); +end; + +function CardOfHex(Hex: string): Cardinal; +var + i: Integer; +begin + Result := 0; + Hex := Copy(ExtractChars(Hex, HexadecimalChars), 1, 8); + + for i := 1 to Length(Hex) do + if Hex[i] <> '0' then + Inc(Result, HexOrd(Hex[i]) shl ((Length(Hex) - i) shl 2)); +end; + +function IntOfBin(Bin: string): Cardinal; +var + i: Integer; +begin + Result := 0; + Bin := Copy(ExtractChars(Bin, BinaryChars), 1, 32); + + for i := Length(Bin) downto 1 do + if Bin[i] = '1' then + Inc(Result, 1 shl (Length(Bin) - i)); +end; + +function BinOfInt(n: Cardinal): string; +var + a: Integer; +begin + if n = 0 then begin + Result := '0'; + exit; end; + + Result := ''; + while n > 0 do begin + a := n and 1; + Result := Char(a + Byte('0')) + Result; + n := n shr 1; + end; +end; + +function BinOfIntFill(n: Cardinal; MinCount: Integer = 8): string; +var + a: Integer; +begin + if n = 0 then begin + Result := MulStr('0', MinCount); + Exit; end; + + Result := ''; + while n > 0 do begin + a := n and 1; + Result := Char(a + Byte('0')) + Result; + n := n shr 1; + end; + Result := MulStr('0', MinCount - Length(Result)) + Result; +end; + +function BaseNOfInt(I: Cardinal; B: TBaseN): string; +var + a: Integer; +begin + if (B < 2) or (i = 0) then begin + Result := '0'; + Exit; end; + + Result := ''; + while i > 0 do begin + a := i mod B; + Result := BaseNChar[a] + Result; + i := i div B; + end; +end; + +function IntOfBaseN(V: string; B: TBaseN): Cardinal; +var + i: Integer; + F: Cardinal; + c: Byte; +begin + Result := 0; + V := TrimAll(V); + F := 1; + for i := Length(V) downto 1 do begin + c := Byte(UpCase(V[i])); + case Char(c) of + '0'..'9': c := c - 48; + 'A'..'Z': c := c - 55; + end; + if c < B then + Result := Result + Byte(c) * F; + F := F * B; + end; +end; + +function KeepIn(i, Bottom, Top: Variant): Variant; +begin + Result := i; + if Result > Top then + Result := Top + else if Result < Bottom then + Result := Bottom; +end; + +function InRange(Value, Bottom, Top: Variant): Boolean; +begin + Result := (Value >= Bottom) and (Value <= Top); +end; + +function InStrictRange(Value, Bottom, Top: Variant): Boolean; +begin + Result := (Value > Bottom) and (Value < Top); +end; + +function Min(const A, B: Integer): Integer; +begin + if A < B then + Result := A + else + Result := B; +end; + +function Min(const A: TIntA): Integer; +var + i: Integer; +begin + Result := 0; + if Length(A) = 0 then + Exit; + + Result := A[0]; + for i := 1 to High(A) do + if A[i] < Result then + Result := A[i]; +end; + +function Max(const A, B: Integer): Integer; +begin + if A > B then + Result := A + else + Result := B; +end; + +function Max(const A: TIntA): Integer; +var + i: Integer; +begin + Result := 0; + if Length(A) = 0 then + Exit; + + Result := A[0]; + for i := 1 to High(A) do + if A[i] > Result then + Result := A[i]; +end; + +function RangesOfStr(const S: string): TRanges; +var + SL: TStringList; + r, b, t: string; + i, p: Integer; + + function TryStrToCard(const S: string; out Value: Cardinal): Boolean; + var + E: Integer; + begin + Val(S, Value, E); + Result := E = 0; + end; + +begin + Result := nil; + SL := TStringList.Create; + try + Split(S, RangesSeparator, SL); + SetLength(Result, SL.Count); + for i := 0 to SL.Count-1 do begin + r := SL[i]; + with Result[i] do begin + p := CharPos(RangeInnerSeparator, r); + Simple := p = 0; // no '-' found + if Simple then begin + if r = RangeInfinite then begin // * --> *-* + Simple := False; + Bottom := Low(Bottom); + Top := High(Top); + end else if not TryStrToCard(r, Value) then + Break; + + end else begin + TileStr(r, p, p, b, t); + + if b = RangeInfinite then + Bottom := Low(Bottom) + else if not TryStrToCard(b, Bottom) then + Break; + + if t = RangeInfinite then + Top := High(Top) + else if not TryStrToCard(t, Top) then + Break; + if Bottom > Top then begin + p := Bottom; Bottom := Top; Top := p; + end; + end; + end; + end; + + if i <> SL.Count then + Result := nil; + + finally + SL.Free; + end; +end; + +function InRanges(Ranges: TRanges; TestValue: Cardinal): Boolean; +var + i: Integer; +begin + Result := True; + + for i := 0 to High(Ranges) do + with Ranges[i] do + if Simple then begin + if TestValue = Value then + Exit; + end else begin + if InRange(TestValue, Bottom, Top) then + Exit; + end; + + Result := False; +end; + +procedure WriteSL(Strings: TStrings; const Prefix: string = ''; + const Suffix: string = ''); +var + i: Integer; +begin + for i := 0 to Strings.Count-1 do + WriteLn(Prefix + Strings[i] + Suffix); +end; + +function Success(Res: Integer; ResultOnSuccess: Integer = ERROR_SUCCESS): Boolean; +begin + Result := (Res = ResultOnSuccess); + LastSuccessRes := Res; +end; + +function Failure(Res: Integer; ResultOnSuccess: Integer = ERROR_SUCCESS): Boolean; +begin + Result := not Success(Res, ResultOnSuccess); +end; + +function ExpandString(const S: string): string; +var + Len: Integer; + P, Res: PChar; +begin + Result := ''; + P := PChar(S); + Len := ExpandEnvironmentStrings(P, nil, 0); + if Len = 0 then + Exit; + + GetMem(Res, Len); + ExpandEnvironmentStrings(P, Res, Len); + + Result := Res; + FreeMem(Res, Len); +end; + +function FindAll(Strings: TStrings; const Mask: string; + ScanSubDirs: Boolean = True; Attributes: Integer = faFindEveryFile; + FileReturn: TFileNameFunc = nil): Boolean; +var + Path, FileName: string; + + procedure ScanDir(const Path, FileName: string); + var + PSR: TSearchRec; + Res: Integer; + + procedure Add(const S: string); + begin + if S <> '' then + Strings.Add(S); + end; + + begin + Res := FindFirst(Path + FileName, Attributes, PSR); + while Success(Res, 0) do begin + if Assigned(FileReturn) then + Add(FileReturn(Path + PSR.Name)) + else + Add(Path + PSR.Name); + Res := FindNext(PSR); + end; + FindClose(PSR); + if not ScanSubDirs then + Exit; + + Res := FindFirst(Path + '*', faDirectory, PSR); + while Success(Res, 0) do begin + if (PSR.Attr and faDirectory > 0) + and (PSR.Name <> '.') and (PSR.Name <> '..') then + ScanDir(Path + PSR.Name + '\', FileName); + Res := FindNext(PSR); + end; + FindClose(PSR); + end; + +begin + Strings.Clear; + Path := ExtractPath(Mask); + FileName := ExtractFileName(Mask); + ScanDir(Path, FileName); + Result := Strings.Count > 0; +end; + +function FindAllFirst(const Mask: string; ScanSubDirs: Boolean = True; + Attributes: Integer = faFindEveryFile): string; +var + Path, FileName: string; + + function ScanDir(const Path, FileName: string): Boolean; + var + PSR: TSearchRec; + Res: Integer; + begin + Result := False; + if Success(FindFirst(Path + FileName, Attributes, PSR), 0) then begin + FindAllFirst := Path + PSR.Name; + Result := True; + FindClose(PSR); + Exit; end; + if not ScanSubDirs then + Exit; + + Res := FindFirst(Path + '*', faDirectory, PSR); + while not Result and Success(Res, 0) do begin + if (PSR.Attr and faDirectory > 0) + and (PSR.Name <> '.') and (PSR.Name <> '..') then + Result := ScanDir(Path + PSR.Name + '\', FileName); + Res := FindNext(PSR); + end; + FindClose(PSR); + end; +begin + Result := ''; + Path := ExtractPath(Mask); + FileName := ExtractFileName(Mask); + ScanDir(Path, FileName); +end; + +procedure DeleteFiles(const Mask: string; ScanSubDirs: Boolean = True; + Attributes: Integer = faFindEveryFile); +var + Path, FileName: string; + + procedure ScanDir(const Path, FileName: string); + var + PSR: TSearchRec; + Res: Integer; + + procedure TryDeleteFile(const FileName: string); + begin + try + DeleteFile(Path + PSR.Name); + except + end; + end; + + begin + Res := FindFirst(Path + FileName, Attributes, PSR); + while Success(Res, 0) do begin + TryDeleteFile(Path + PSR.Name); + Res := FindNext(PSR); + end; + FindClose(PSR); + if not ScanSubDirs then + Exit; + + Res := FindFirst(Path + '*', faDirectory, PSR); + while Success(Res, 0) do begin + if (PSR.Attr and faDirectory > 0) + and (PSR.Name <> '.') and (PSR.Name <> '..') then begin + ScanDir(Path + PSR.Name + '\', FileName); + TryDeleteFile(Path + PSR.Name); + end; + Res := FindNext(PSR); + end; + FindClose(PSR); + end; +begin + Path := ExtractPath(Mask); + FileName := ExtractFileName(Mask); + ScanDir(Path, FileName); +end; + +function GetFileNew(FileName: string; NoFloppyDrives: Boolean = True): string; +var + Drive: string; + pf, pd, Len: Integer; + PSR: TSearchRec; +begin + Result := ''; + FileName := Trim(FileName); + if Length(FileName) < 2 then + Exit; + + Drive := ExtractDrive(FileName); + if not DirectoryExists(Drive) then + Exit; + + if NoFloppyDrives and (Drive[1] in ['A', 'B']) then + Exit; + + Len := Length(FileName); + Result := Drive; + pf := Length(Drive) + 1; + while pf <= Len do begin + if FileName[pf] = '\' then begin + Result := Result + '\'; + Inc(pf); + Continue; end; + + pd := CharPos('\', FileName, pf); + if pd = 0 then begin + if 0=FindFirst(Result + Copy(FileName, pf, MaxInt), faFindEveryFile, PSR) then begin + Result := Result + PSR.Name; + Break; end else begin + FindClose(PSR); + if 0=FindFirst(Result + Copy(FileName, pf, MaxInt), faDirectory, PSR) then + Result := Result + PSR.Name + '\' + else + Result := ''; + FindClose(PSR); + if Result = '' then + Break; + end; + end; + + if 0=FindFirst(Result + Copy(FileName, pf, pd - pf), faDirectory, PSR) then + Result := Result + PSR.Name + '\' + else + Result := ''; + FindClose(PSR); + if Result = '' then + Break; + + pf := pd + 1; + end; + + if (Result <> '') and not FileEx(Result, True) then + Result := ''; +end; + +function DateTimeOfFileTime(const FileTime: TFileTime): TDateTime; +var + LocalFileTime: TFileTime; + Res: Integer; +begin + Result := 0; + + FileTimeToLocalFileTime(FileTime, LocalFileTime); + if not FileTimeToDosDateTime(LocalFileTime, LongRec(Res).Hi, + LongRec(Res).Lo) then + Res := -1; + + if (Res = -1) or (Res = 0) then + Exit; + try + Result := FileDateToDateTime(Res); + except + end; +end; + +procedure FileNew(const FileName: string); +var + Handle: Integer; +begin + Handle := FileCreate(FileName); + FileClose(Handle); +end; + +function Win32PlatformStr: string; +const + PlatformStrings: array[VER_PLATFORM_WIN32s..VER_PLATFORM_WIN32_NT] of string = + ('VER_PLATFORM_WIN32s', 'VER_PLATFORM_WIN32_WINDOWS', 'VER_PLATFORM_WIN32_NT'); +begin + Result := PlatformStrings[Win32Platform]; +end; + +function FullOSInfo: string; +begin + Result := Format( + 'Platform: %s' + EOL + + 'Version: %d.%d Build %d' + EOL + + 'CSD: %s', + [ + Win32PlatformStr, + Win32MajorVersion, Win32MinorVersion, Win32BuildNumber, + Win32CSDVersion + ] + ); +end; + +function Win9x: Boolean; +begin + Result := Win32Platform = VER_PLATFORM_WIN32_WINDOWS; +end; + +function WinNT: Boolean; +begin + Result := Win32Platform = VER_PLATFORM_WIN32_NT; +end; + +function Win2000: Boolean; +begin + Result := (Win32Platform = VER_PLATFORM_WIN32_NT) + and (Win32MajorVersion = 4); +end; + +function WinXP: Boolean; +begin + Result := Win32MajorVersion >= 5; +end; + +initialization + MyDir := GetMyDir; + +end. + +unit FifoStream; + +interface + +uses Classes, windows, Dialogs; + +const + DefaultChunksize = 32768; // 32kb per chunk as default. + +type + PMemChunk = ^TMemChunk; + TMemChunk = record + Filled: Longword; + Read: Longword; + Data: pointer; + end; + + TFifo = class + private + FBuffers: TList; + FChunksize: Longword; + FCritSect: TRTLCriticalSection; + FIsWinNT: boolean; + FBytesInFifo: LongWord; + protected + function GetBytesInFifo: LongWord; + public + constructor Create; + destructor Destroy; override; + procedure Write(Data: pointer; Size: LongWord); + procedure Read(Buff: pointer; var ReqSize: LongWord); + procedure PeekData(Buff: pointer; var ReqSize: LongWord); + published + property BytesInFifo: LongWord read FBytesInFifo; + end; + +implementation + +constructor TFifo.Create; +begin + inherited; + FBuffers := TList.Create; + // set default chunksize... + FChunksize := DefaultChunksize; + InitializeCriticalSection(FCritSect); +end; + +destructor TFifo.Destroy; +var + I: Integer; +begin + EnterCriticalSection(FCritSect); + for I := 0 to FBuffers.count - 1 do + begin + FreeMem(PMemChunk(Fbuffers[I]).Data); + Dispose(PMemChunk(Fbuffers[I])); + end; + FBuffers.Clear; + FBuffers.Free; + LeaveCriticalSection(FCritSect); + + DeleteCriticalSection(FCritSect); + inherited; +end; + +function TFifo.GetBytesInFifo: LongWord; +begin + Result := 0; + if FBuffers.Count = 0 then + begin + exit; + end + else + begin + if FBuffers.Count > 1 then + Inc(Result, (FBuffers.Count - 1) * FChunkSize); + Inc(Result, PMemChunk(FBuffers[Fbuffers.Count - 1]).Filled); + Dec(Result, PMemChunk(FBuffers[0]).Read); + end; +end; + +procedure TFifo.Write(Data: pointer; Size: LongWord); +var + Privpointer: pointer; + PrivSize: LongWord; + Chunk: PMemChunk; + PosInChunk: pointer; +begin + if LongWord(Data) = 0 then + begin + // null pointer? somebody is trying to fool us, get out... + Exit; + end; + EnterCriticalSection(FCritSect); + PrivPointer := Data; + PrivSize := 0; + // are already buffers there? + if FBuffers.count > 0 then + begin + // is the last one of them not completely filled? + if PMemChunk(FBuffers[FBuffers.count - 1]).filled < FChunksize then + // not completely filled, so fill up the buffer. + begin + Chunk := PMemChunk(FBuffers[FBuffers.count - 1]); + // fetch chunkdata. + PosInChunk := Chunk.Data; + // move to current fill pos... + Inc(LongWord(PosInChunk), Chunk.Filled); + // can we fill the chunk completely? + if Size > FChunksize - Chunk.Filled then + begin + // yes we can. + Move(PrivPointer^, PosInChunk^, FChunksize - Chunk.Filled); + Inc(PrivSize, FChunksize - Chunk.Filled); + Inc(LongWord(PrivPointer), FChunksize - Chunk.Filled); + Chunk.Filled := FChunkSize; + end + else + // we have to less data for filling the chunk completely, + // just put everything in. + begin + Move(PrivPointer^, PosInChunk^, Size); + Inc(PrivSize, Size); + Inc(Chunk.Filled, Size); + end; + end; + end; + // as long as we have remaining stuff put it into new chunks. + while (PrivSize < Size) do + begin + new(Chunk); + GetMem(Chunk.Data, FChunksize); + Chunk.Read := 0; + // can we fill an entire chunk with the remaining data? + if Privsize + FChunksize < Size then + begin + // yes we can, so put the stuff in. + Move(Privpointer^, Chunk.Data^, FChunksize); + Inc(LongWord(PrivPointer), FChunksize); + Inc(PrivSize, FChunksize); + Chunk.Filled := FChunksize; + end + else // we have to less data to fill the entire chunk, just put the remaining stuff in. + begin + Move(Privpointer^, Chunk.Data^, Size - Privsize); + Chunk.Filled := Size - Privsize; + Inc(PrivSize, Size - Privsize); + end; + Fbuffers.Add(Chunk); + end; + if Size <> Privsize then + Showmessage('miscalculation in TFifo.write'); + FBytesInFifo := GetBytesInFifo; + LeaveCriticalSection(FCritSect); +end; + +procedure TFifo.Read(Buff: pointer; var ReqSize: LongWord); +var + PrivSize: Integer; + Privpos: pointer; + Chunk: PMemChunk; + ChunkPos: pointer; +begin + if LongWord(Buff) = 0 then + begin + // null pointer? somebody is trying to fool us, get out... + Exit; + end; + EnterCriticalSection(FCritSect); + PrivSize := 0; + Privpos := Buff; + while FBuffers.Count > 0 do + begin + Chunk := PMemChunk(FBuffers[0]); + ChunkPos := Chunk.data; + Inc(LongWord(ChunkPos), Chunk.Read); + // does the remaining part of the chunk fit into the buffer? + if PrivSize + (Chunk.Filled - Chunk.read) < ReqSize then + begin // yep, it fits + Move(ChunkPos^, Privpos^, Chunk.Filled - Chunk.read); + Inc(PrivSize, Chunk.Filled - Chunk.read); + FreeMem(Chunk.Data); + Dispose(Chunk); + FBuffers.Delete(0); + end + else // remaining part didn't fit, get as much as we can and increment the + // read attribute. + begin + Move(ChunkPos^, Privpos^, ReqSize - PrivSize); + Inc(Chunk.read, ReqSize - PrivSize); + Inc(PrivSize, ReqSize - PrivSize); + // as we filled the buffer, we'll have to break here. + break; + end; + end; + FBytesInFifo := GetBytesInFifo; + LeaveCriticalSection(FCritSect); + ReqSize := PrivSize; +end; + +// read Data from Stream without removing it from the Stream... + +procedure TFifo.PeekData(Buff: pointer; var ReqSize: LongWord); +var + PrivSize: Integer; + Privpos: pointer; + Chunk: PMemChunk; + ChunkPos: pointer; + ChunkNr: Integer; +begin + if LongWord(Buff) = 0 then + begin + // null pointer? somebody is trying to fool us, get out... + Exit; + end; + EnterCriticalSection(FCritSect); + PrivSize := 0; + Privpos := Buff; + ChunkNr := 0; + while FBuffers.Count > ChunkNr do + begin + Chunk := PMemChunk(FBuffers[ChunkNr]); + ChunkPos := Chunk.data; + Inc(LongWord(ChunkPos), Chunk.Read); + // does the remaining part of the chunk fit into the buffer? + if PrivSize + (Chunk.Filled - Chunk.read) < ReqSize then + begin // yep, it fits + Move(ChunkPos^, Privpos^, Chunk.Filled - Chunk.read); + Inc(PrivSize, Chunk.Filled - Chunk.read); + Inc(ChunkNr); + end + else // remaining part didn't fit, get as much as we can and increment the + // read attribute. + begin + Move(ChunkPos^, Privpos^, ReqSize - PrivSize); + Inc(PrivSize, ReqSize - PrivSize); + // as we filled the buffer, we'll have to break here. + break; + end; + end; + LeaveCriticalSection(FCritSect); + ReqSize := PrivSize; +end; + +end. Added: external/Pygments-0.8.1/tests/examplefiles/example.rb ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/example.rb Thu Aug 9 17:43:13 2007 @@ -0,0 +1,1852 @@ +module CodeRay + module Scanners + +class Ruby < Scanner + + RESERVED_WORDS = [ + 'and', 'def', 'end', 'in', 'or', 'unless', 'begin', + 'defined?', 'ensure', 'module', 'redo', 'super', 'until', + 'BEGIN', 'break', 'do', 'next', 'rescue', 'then', + 'when', 'END', 'case', 'else', 'for', 'retry', + 'while', 'alias', 'class', 'elsif', 'if', 'not', 'return', + 'undef', 'yield', + ] + + DEF_KEYWORDS = ['def'] + MODULE_KEYWORDS = ['class', 'module'] + DEF_NEW_STATE = WordList.new(:initial). + add(DEF_KEYWORDS, :def_expected). + add(MODULE_KEYWORDS, :module_expected) + + WORDS_ALLOWING_REGEXP = [ + 'and', 'or', 'not', 'while', 'until', 'unless', 'if', 'elsif', 'when' + ] + REGEXP_ALLOWED = WordList.new(false). + add(WORDS_ALLOWING_REGEXP, :set) + + PREDEFINED_CONSTANTS = [ + 'nil', 'true', 'false', 'self', + 'DATA', 'ARGV', 'ARGF', '__FILE__', '__LINE__', + ] + + IDENT_KIND = WordList.new(:ident). + add(RESERVED_WORDS, :reserved). + add(PREDEFINED_CONSTANTS, :pre_constant) + + METHOD_NAME = / #{IDENT} [?!]? /xo + METHOD_NAME_EX = / + #{METHOD_NAME} # common methods: split, foo=, empty?, gsub! + | \*\*? # multiplication and power + | [-+~]@? # plus, minus + | [\/%&|^`] # division, modulo or format strings, &and, |or, ^xor, `system` + | \[\]=? # array getter and setter + | <=?>? | >=? # comparison, rocket operator + | << | >> # append or shift left, shift right + | ===? # simple equality and case equality + /ox + GLOBAL_VARIABLE = / \$ (?: #{IDENT} | \d+ | [~&+`'=\/,;_.<>!@0$?*":F\\] | -[a-zA-Z_0-9] ) /ox + + DOUBLEQ = / " [^"\#\\]* (?: (?: \#\{.*?\} | \#(?:$")? | \\. ) [^"\#\\]* )* "? /ox + SINGLEQ = / ' [^'\\]* (?: \\. [^'\\]* )* '? /ox + STRING = / #{SINGLEQ} | #{DOUBLEQ} /ox + SHELL = / ` [^`\#\\]* (?: (?: \#\{.*?\} | \#(?:$`)? | \\. ) [^`\#\\]* )* `? /ox + REGEXP = / \/ [^\/\#\\]* (?: (?: \#\{.*?\} | \#(?:$\/)? | \\. ) [^\/\#\\]* )* \/? /ox + + DECIMAL = /\d+(?:_\d+)*/ # doesn't recognize 09 as octal error + OCTAL = /0_?[0-7]+(?:_[0-7]+)*/ + HEXADECIMAL = /0x[0-9A-Fa-f]+(?:_[0-9A-Fa-f]+)*/ + BINARY = /0b[01]+(?:_[01]+)*/ + + EXPONENT = / [eE] [+-]? #{DECIMAL} /ox + FLOAT = / #{DECIMAL} (?: #{EXPONENT} | \. #{DECIMAL} #{EXPONENT}? ) / + INTEGER = /#{OCTAL}|#{HEXADECIMAL}|#{BINARY}|#{DECIMAL}/ + + def reset + super + @regexp_allowed = false + end + + def next_token + return if @scanner.eos? + + kind = :error + if @scanner.scan(/\s+/) # in every state + kind = :space + @regexp_allowed = :set if @regexp_allowed or @scanner.matched.index(?\n) # delayed flag setting + + elsif @state == :def_expected + if @scanner.scan(/ (?: (?:#{IDENT}(?:\.|::))* | (?:@@?|$)? #{IDENT}(?:\.|::) ) #{METHOD_NAME_EX} /ox) + kind = :method + @state = :initial + else + @scanner.getch + end + @state = :initial + + elsif @state == :module_expected + if @scanner.scan(/<#\\\\]*(?:(?:#\{.*?\}|#|\\\\.)[^>#\\\\]*)*>?|([^a-zA-Z\\\\])(?:(?!\1)[^#\\\\])*(?:(?:#\{.*?\}|#|\\\\.)(?:(?!\1)[^#\\\\])*)*\1?)|\([^)#\\\\]*(?:(?:#\{.*?\}|#|\\\\.)[^)#\\\\]*)*\)?|\[[^\]#\\\\]*(?:(?:#\{.*?\}|#|\\\\.)[^\]#\\\\]*)*\]?|\{[^}#\\\\]*(?:(?:#\{.*?\}|#|\\\\.)[^}#\\\\]*)*\}?|<[^>#\\\\]*(?:(?:#\{.*?\}|#|\\\\.)[^>#\\\\]*)*>?|([^a-zA-Z\s\\\\])(?:(?!\2)[^#\\\\])*(?:(?:#\{.*?\}|#|\\\\.)(?:(?!\2)[^#\\\\])*)*\2?|\\\\[^#\\\\]*(?:(?:#\{.*?\}|#)[^#\\\\]*)*\\\\?)/ + elsif @scanner.scan(/:(?:#{GLOBAL_VARIABLE}|#{METHOD_NAME_EX}|#{STRING})/ox) + kind = :symbol + elsif @scanner.scan(/ + \? (?: + [^\s\\] + | + \\ (?:M-\\C-|C-\\M-|M-\\c|c\\M-|c|C-|M-))? (?: \\ (?: . | [0-7]{3} | x[0-9A-Fa-f][0-9A-Fa-f] ) + ) + /mox) + kind = :integer + + elsif @scanner.scan(/ [-+*\/%=<>;,|&!()\[\]{}~?] | \.\.?\.? | ::? /x) + kind = :operator + @regexp_allowed = :set if @scanner.matched[-1,1] =~ /[~=!<>|&^,\(\[+\-\/\*%]\z/ + elsif @scanner.scan(FLOAT) + kind = :float + elsif @scanner.scan(INTEGER) + kind = :integer + else + @scanner.getch + end + end + + token = Token.new @scanner.matched, kind + + if kind == :regexp + token.text << @scanner.scan(/[eimnosux]*/) + end + + @regexp_allowed = (@regexp_allowed == :set) # delayed flag setting + + token + end +end + +register Ruby, 'ruby', 'rb' + + end +end +class Set + include Enumerable + + # Creates a new set containing the given objects. + def self.[](*ary) + new(ary) + end + + # Creates a new set containing the elements of the given enumerable + # object. + # + # If a block is given, the elements of enum are preprocessed by the + # given block. + def initialize(enum = nil, &block) # :yields: o + @hash ||= Hash.new + + enum.nil? and return + + if block + enum.each { |o| add(block[o]) } + else + merge(enum) + end + end + + # Copy internal hash. + def initialize_copy(orig) + @hash = orig.instance_eval{@hash}.dup + end + + # Returns the number of elements. + def size + @hash.size + end + alias length size + + # Returns true if the set contains no elements. + def empty? + @hash.empty? + end + + # Removes all elements and returns self. + def clear + @hash.clear + self + end + + # Replaces the contents of the set with the contents of the given + # enumerable object and returns self. + def replace(enum) + if enum.class == self.class + @hash.replace(enum.instance_eval { @hash }) + else + enum.is_a?(Enumerable) or raise ArgumentError, "value must be enumerable" + clear + enum.each { |o| add(o) } + end + + self + end + + # Converts the set to an array. The order of elements is uncertain. + def to_a + @hash.keys + end + + def flatten_merge(set, seen = Set.new) + set.each { |e| + if e.is_a?(Set) + if seen.include?(e_id = e.object_id) + raise ArgumentError, "tried to flatten recursive Set" + end + + seen.add(e_id) + flatten_merge(e, seen) + seen.delete(e_id) + else + add(e) + end + } + + self + end + protected :flatten_merge + + # Returns a new set that is a copy of the set, flattening each + # containing set recursively. + def flatten + self.class.new.flatten_merge(self) + end + + # Equivalent to Set#flatten, but replaces the receiver with the + # result in place. Returns nil if no modifications were made. + def flatten! + if detect { |e| e.is_a?(Set) } + replace(flatten()) + else + nil + end + end + + # Returns true if the set contains the given object. + def include?(o) + @hash.include?(o) + end + alias member? include? + + # Returns true if the set is a superset of the given set. + def superset?(set) + set.is_a?(Set) or raise ArgumentError, "value must be a set" + return false if size < set.size + set.all? { |o| include?(o) } + end + + # Returns true if the set is a proper superset of the given set. + def proper_superset?(set) + set.is_a?(Set) or raise ArgumentError, "value must be a set" + return false if size <= set.size + set.all? { |o| include?(o) } + end + + # Returns true if the set is a subset of the given set. + def subset?(set) + set.is_a?(Set) or raise ArgumentError, "value must be a set" + return false if set.size < size + all? { |o| set.include?(o) } + end + + # Returns true if the set is a proper subset of the given set. + def proper_subset?(set) + set.is_a?(Set) or raise ArgumentError, "value must be a set" + return false if set.size <= size + all? { |o| set.include?(o) } + end + + # Calls the given block once for each element in the set, passing + # the element as parameter. + def each + @hash.each_key { |o| yield(o) } + self + end + + # Adds the given object to the set and returns self. Use +merge+ to + # add several elements at once. + def add(o) + @hash[o] = true + self + end + alias << add + + # Adds the given object to the set and returns self. If the + # object is already in the set, returns nil. + def add?(o) + if include?(o) + nil + else + add(o) + end + end + + # Deletes the given object from the set and returns self. Use +subtract+ to + # delete several items at once. + def delete(o) + @hash.delete(o) + self + end + + # Deletes the given object from the set and returns self. If the + # object is not in the set, returns nil. + def delete?(o) + if include?(o) + delete(o) + else + nil + end + end + + # Deletes every element of the set for which block evaluates to + # true, and returns self. + def delete_if + @hash.delete_if { |o,| yield(o) } + self + end + + # Do collect() destructively. + def collect! + set = self.class.new + each { |o| set << yield(o) } + replace(set) + end + alias map! collect! + + # Equivalent to Set#delete_if, but returns nil if no changes were + # made. + def reject! + n = size + delete_if { |o| yield(o) } + size == n ? nil : self + end + + # Merges the elements of the given enumerable object to the set and + # returns self. + def merge(enum) + if enum.is_a?(Set) + @hash.update(enum.instance_eval { @hash }) + else + enum.is_a?(Enumerable) or raise ArgumentError, "value must be enumerable" + enum.each { |o| add(o) } + end + + self + end + + # Deletes every element that appears in the given enumerable object + # and returns self. + def subtract(enum) + enum.is_a?(Enumerable) or raise ArgumentError, "value must be enumerable" + enum.each { |o| delete(o) } + self + end + + # Returns a new set built by merging the set and the elements of the + # given enumerable object. + def |(enum) + enum.is_a?(Enumerable) or raise ArgumentError, "value must be enumerable" + dup.merge(enum) + end + alias + | ## + alias union | ## + + # Returns a new set built by duplicating the set, removing every + # element that appears in the given enumerable object. + def -(enum) + enum.is_a?(Enumerable) or raise ArgumentError, "value must be enumerable" + dup.subtract(enum) + end + alias difference - ## + + # Returns a new array containing elements common to the set and the + # given enumerable object. + def &(enum) + enum.is_a?(Enumerable) or raise ArgumentError, "value must be enumerable" + n = self.class.new + enum.each { |o| n.add(o) if include?(o) } + n + end + alias intersection & ## + + # Returns a new array containing elements exclusive between the set + # and the given enumerable object. (set ^ enum) is equivalent to + # ((set | enum) - (set & enum)). + def ^(enum) + enum.is_a?(Enumerable) or raise ArgumentError, "value must be enumerable" + n = dup + enum.each { |o| if n.include?(o) then n.delete(o) else n.add(o) end } + n + end + + # Returns true if two sets are equal. The equality of each couple + # of elements is defined according to Object#eql?. + def ==(set) + equal?(set) and return true + + set.is_a?(Set) && size == set.size or return false + + hash = @hash.dup + set.all? { |o| hash.include?(o) } + end + + def hash # :nodoc: + @hash.hash + end + + def eql?(o) # :nodoc: + return false unless o.is_a?(Set) + @hash.eql?(o.instance_eval{@hash}) + end + + # Classifies the set by the return value of the given block and + # returns a hash of {value => set of elements} pairs. The block is + # called once for each element of the set, passing the element as + # parameter. + # + # e.g.: + # + # require 'set' + # files = Set.new(Dir.glob("*.rb")) + # hash = files.classify { |f| File.mtime(f).year } + # p hash # => {2000=>#, + # # 2001=>#, + # # 2002=>#} + def classify # :yields: o + h = {} + + each { |i| + x = yield(i) + (h[x] ||= self.class.new).add(i) + } + + h + end + + # Divides the set into a set of subsets according to the commonality + # defined by the given block. + # + # If the arity of the block is 2, elements o1 and o2 are in common + # if block.call(o1, o2) is true. Otherwise, elements o1 and o2 are + # in common if block.call(o1) == block.call(o2). + # + # e.g.: + # + # require 'set' + # numbers = Set[1, 3, 4, 6, 9, 10, 11] + # set = numbers.divide { |i,j| (i - j).abs == 1 } + # p set # => #, + # # #, + # # #, + # # #}> + def divide(&func) + if func.arity == 2 + require 'tsort' + + class << dig = {} # :nodoc: + include TSort + + alias tsort_each_node each_key + def tsort_each_child(node, &block) + fetch(node).each(&block) + end + end + + each { |u| + dig[u] = a = [] + each{ |v| func.call(u, v) and a << v } + } + + set = Set.new() + dig.each_strongly_connected_component { |css| + set.add(self.class.new(css)) + } + set + else + Set.new(classify(&func).values) + end + end + + InspectKey = :__inspect_key__ # :nodoc: + + # Returns a string containing a human-readable representation of the + # set. ("#") + def inspect + ids = (Thread.current[InspectKey] ||= []) + + if ids.include?(object_id) + return sprintf('#<%s: {...}>', self.class.name) + end + + begin + ids << object_id + return sprintf('#<%s: {%s}>', self.class, to_a.inspect[1..-2]) + ensure + ids.pop + end + end + + def pretty_print(pp) # :nodoc: + pp.text sprintf('#<%s: {', self.class.name) + pp.nest(1) { + pp.seplist(self) { |o| + pp.pp o + } + } + pp.text "}>" + end + + def pretty_print_cycle(pp) # :nodoc: + pp.text sprintf('#<%s: {%s}>', self.class.name, empty? ? '' : '...') + end +end + +# SortedSet implements a set which elements are sorted in order. See Set. +class SortedSet < Set + @@setup = false + + class << self + def [](*ary) # :nodoc: + new(ary) + end + + def setup # :nodoc: + @@setup and return + + begin + require 'rbtree' + + module_eval %{ + def initialize(*args, &block) + @hash = RBTree.new + super + end + } + rescue LoadError + module_eval %{ + def initialize(*args, &block) + @keys = nil + super + end + + def clear + @keys = nil + super + end + + def replace(enum) + @keys = nil + super + end + + def add(o) + @keys = nil + @hash[o] = true + self + end + alias << add + + def delete(o) + @keys = nil + @hash.delete(o) + self + end + + def delete_if + n = @hash.size + @hash.delete_if { |o,| yield(o) } + @keys = nil if @hash.size != n + self + end + + def merge(enum) + @keys = nil + super + end + + def each + to_a.each { |o| yield(o) } + end + + def to_a + (@keys = @hash.keys).sort! unless @keys + @keys + end + } + end + + @@setup = true + end + end + + def initialize(*args, &block) # :nodoc: + SortedSet.setup + initialize(*args, &block) + end +end + +module Enumerable + # Makes a set from the enumerable object with given arguments. + def to_set(klass = Set, *args, &block) + klass.new(self, *args, &block) + end +end + +# =begin +# == RestricedSet class +# RestricedSet implements a set with restrictions defined by a given +# block. +# +# === Super class +# Set +# +# === Class Methods +# --- RestricedSet::new(enum = nil) { |o| ... } +# --- RestricedSet::new(enum = nil) { |rset, o| ... } +# Creates a new restricted set containing the elements of the given +# enumerable object. Restrictions are defined by the given block. +# +# If the block's arity is 2, it is called with the RestrictedSet +# itself and an object to see if the object is allowed to be put in +# the set. +# +# Otherwise, the block is called with an object to see if the object +# is allowed to be put in the set. +# +# === Instance Methods +# --- restriction_proc +# Returns the restriction procedure of the set. +# +# =end +# +# class RestricedSet < Set +# def initialize(*args, &block) +# @proc = block or raise ArgumentError, "missing a block" +# +# if @proc.arity == 2 +# instance_eval %{ +# def add(o) +# @hash[o] = true if @proc.call(self, o) +# self +# end +# alias << add +# +# def add?(o) +# if include?(o) || !@proc.call(self, o) +# nil +# else +# @hash[o] = true +# self +# end +# end +# +# def replace(enum) +# enum.is_a?(Enumerable) or raise ArgumentError, "value must be enumerable" +# clear +# enum.each { |o| add(o) } +# +# self +# end +# +# def merge(enum) +# enum.is_a?(Enumerable) or raise ArgumentError, "value must be enumerable" +# enum.each { |o| add(o) } +# +# self +# end +# } +# else +# instance_eval %{ +# def add(o) +# if @proc.call(o) +# @hash[o] = true +# end +# self +# end +# alias << add +# +# def add?(o) +# if include?(o) || !@proc.call(o) +# nil +# else +# @hash[o] = true +# self +# end +# end +# } +# end +# +# super(*args) +# end +# +# def restriction_proc +# @proc +# end +# end + +if $0 == __FILE__ + eval DATA.read, nil, $0, __LINE__+4 +end + +# = rweb - CGI Support Library +# +# Author:: Johannes Barre (mailto:rweb at igels.net) +# Copyright:: Copyright (c) 2003, 04 by Johannes Barre +# License:: GNU Lesser General Public License (COPYING, http://www.gnu.org/copyleft/lesser.html) +# Version:: 0.1.0 +# CVS-ID:: $Id: example.rb 39 2005-11-05 03:33:55Z murphy $ +# +# == What is Rweb? +# Rweb is a replacement for the cgi class included in the ruby distribution. +# +# == How to use +# +# === Basics +# +# This class is made to be as easy as possible to use. An example: +# +# require "rweb" +# +# web = Rweb.new +# web.out do +# web.puts "Hello world!" +# end +# +# The visitor will get a simple "Hello World!" in his browser. Please notice, +# that won't set html-tags for you, so you should better do something like this: +# +# require "rweb" +# +# web = Rweb.new +# web.out do +# web.puts "Hello world!" +# end +# +# === Set headers +# Of course, it's also possible to tell the browser, that the content of this +# page is plain text instead of html code: +# +# require "rweb" +# +# web = Rweb.new +# web.out do +# web.header("content-type: text/plain") +# web.puts "Hello plain world!" +# end +# +# Please remember, headers can't be set after the page content has been send. +# You have to set all nessessary headers before the first puts oder print. It's +# possible to cache the content until everything is complete. Doing it this +# way, you can set headers everywhere. +# +# If you set a header twice, the second header will replace the first one. The +# header name is not casesensitive, it will allways converted in to the +# capitalised form suggested by the w3c (http://w3.org) +# +# === Set cookies +# Setting cookies is quite easy: +# include 'rweb' +# +# web = Rweb.new +# Cookie.new("Visits", web.cookies['visits'].to_i +1) +# web.out do +# web.puts "Welcome back! You visited this page #{web.cookies['visits'].to_i +1} times" +# end +# +# See the class Cookie for more details. +# +# === Get form and cookie values +# There are four ways to submit data from the browser to the server and your +# ruby script: via GET, POST, cookies and file upload. Rweb doesn't support +# file upload by now. +# +# include 'rweb' +# +# web = Rweb.new +# web.out do +# web.print "action: #{web.get['action']} " +# web.puts "The value of the cookie 'visits' is #{web.cookies['visits']}" +# web.puts "The post parameter 'test['x']' is #{web.post['test']['x']}" +# end + +RWEB_VERSION = "0.1.0" +RWEB = "rweb/#{RWEB_VERSION}" + +#require 'rwebcookie' -> edit by bunny :-) + +class Rweb + # All parameter submitted via the GET method are available in attribute + # get. This is Hash, where every parameter is available as a key-value + # pair. + # + # If your input tag has a name like this one, it's value will be available + # as web.get["fieldname"] + # + # You can submit values as a Hash + # + # + # will be available as + # web.get["text"]["index"] + # web.get["text"]["index2"] + # Integers are also possible + # + # + # + # will be available as + # web.get["int"][0] # First Field + # web.get["int"][1] # Second one + # Please notice, this doesn'd work like you might expect: + # + # It will not be available as web.get["text"]["index"] but + # web.get["text[index]"] + attr_reader :get + + # All parameters submitted via POST are available in the attribute post. It + # works like the get attribute. + # + # will be available as + # web.post["text"][0] + attr_reader :post + + # All cookies submitted by the browser are available in cookies. This is a + # Hash, where every cookie is a key-value pair. + attr_reader :cookies + + # The name of the browser identification is submitted as USER_AGENT and + # available in this attribute. + attr_reader :user_agent + + # The IP address of the client. + attr_reader :remote_addr + + # Creates a new Rweb object. This should only done once. You can set various + # options via the settings hash. + # + # "cache" => true: Everything you script send to the client will be cached + # until the end of the out block or until flush is called. This way, you + # can modify headers and cookies even after printing something to the client. + # + # "safe" => level: Changes the $SAFE attribute. By default, $SAFE will be set + # to 1. If $SAFE is already higher than this value, it won't be changed. + # + # "silend" => true: Normaly, Rweb adds automaticly a header like this + # "X-Powered-By: Rweb/x.x.x (Ruby/y.y.y)". With the silend option you can + # suppress this. + def initialize (settings = {}) + # {{{ + @header = {} + @cookies = {} + @get = {} + @post = {} + + # Internal attributes + @status = nil + @reasonPhrase = nil + @setcookies = [] + @output_started = false; + @output_allowed = false; + + @mod_ruby = false + @env = ENV.to_hash + + if defined?(MOD_RUBY) + @output_method = "mod_ruby" + @mod_ruby = true + elsif @env['SERVER_SOFTWARE'] =~ /^Microsoft-IIS/i + @output_method = "nph" + else + @output_method = "ph" + end + + unless settings.is_a?(Hash) + raise TypeError, "settings must be a Hash" + end + @settings = settings + + unless @settings.has_key?("safe") + @settings["safe"] = 1 + end + + if $SAFE < @settings["safe"] + $SAFE = @settings["safe"] + end + + unless @settings.has_key?("cache") + @settings["cache"] = false + end + + # mod_ruby sets no QUERY_STRING variable, if no GET-Parameters are given + unless @env.has_key?("QUERY_STRING") + @env["QUERY_STRING"] = "" + end + + # Now we split the QUERY_STRING by the seperators & and ; or, if + # specified, settings['get seperator'] + unless @settings.has_key?("get seperator") + get_args = @env['QUERY_STRING'].split(/[&;]/) + else + get_args = @env['QUERY_STRING'].split(@settings['get seperator']) + end + + get_args.each do | arg | + arg_key, arg_val = arg.split(/=/, 2) + arg_key = Rweb::unescape(arg_key) + arg_val = Rweb::unescape(arg_val) + + # Parse names like name[0], name['text'] or name[] + pattern = /^(.+)\[("[^\]]*"|'[^\]]*'|[0-9]*)\]$/ + keys = [] + while match = pattern.match(arg_key) + arg_key = match[1] + keys = [match[2]] + keys + end + keys = [arg_key] + keys + + akt = @get + last = nil + lastkey = nil + keys.each do |key| + if key == "" + # No key specified (like in "test[]"), so we use the + # lowerst unused Integer as key + key = 0 + while akt.has_key?(key) + key += 1 + end + elsif /^[0-9]*$/ =~ key + # If the index is numerical convert it to an Integer + key = key.to_i + elsif key[0].chr == "'" || key[0].chr == '"' + key = key[1, key.length() -2] + end + if !akt.has_key?(key) || !akt[key].class == Hash + # create an empty Hash if there isn't already one + akt[key] = {} + end + last = akt + lastkey = key + akt = akt[key] + end + last[lastkey] = arg_val + end + + if @env['REQUEST_METHOD'] == "POST" + if @env.has_key?("CONTENT_TYPE") && @env['CONTENT_TYPE'] == "application/x-www-form-urlencoded" && @env.has_key?('CONTENT_LENGTH') + unless @settings.has_key?("post seperator") + post_args = $stdin.read(@env['CONTENT_LENGTH'].to_i).split(/[&;]/) + else + post_args = $stdin.read(@env['CONTENT_LENGTH'].to_i).split(@settings['post seperator']) + end + post_args.each do | arg | + arg_key, arg_val = arg.split(/=/, 2) + arg_key = Rweb::unescape(arg_key) + arg_val = Rweb::unescape(arg_val) + + # Parse names like name[0], name['text'] or name[] + pattern = /^(.+)\[("[^\]]*"|'[^\]]*'|[0-9]*)\]$/ + keys = [] + while match = pattern.match(arg_key) + arg_key = match[1] + keys = [match[2]] + keys + end + keys = [arg_key] + keys + + akt = @post + last = nil + lastkey = nil + keys.each do |key| + if key == "" + # No key specified (like in "test[]"), so we use + # the lowerst unused Integer as key + key = 0 + while akt.has_key?(key) + key += 1 + end + elsif /^[0-9]*$/ =~ key + # If the index is numerical convert it to an Integer + key = key.to_i + elsif key[0].chr == "'" || key[0].chr == '"' + key = key[1, key.length() -2] + end + if !akt.has_key?(key) || !akt[key].class == Hash + # create an empty Hash if there isn't already one + akt[key] = {} + end + last = akt + lastkey = key + akt = akt[key] + end + last[lastkey] = arg_val + end + else + # Maybe we should print a warning here? + $stderr.print("Unidentified form data recived and discarded.") + end + end + + if @env.has_key?("HTTP_COOKIE") + cookie = @env['HTTP_COOKIE'].split(/; ?/) + cookie.each do | c | + cookie_key, cookie_val = c.split(/=/, 2) + + @cookies [Rweb::unescape(cookie_key)] = Rweb::unescape(cookie_val) + end + end + + if defined?(@env['HTTP_USER_AGENT']) + @user_agent = @env['HTTP_USER_AGENT'] + else + @user_agent = nil; + end + + if defined?(@env['REMOTE_ADDR']) + @remote_addr = @env['REMOTE_ADDR'] + else + @remote_addr = nil + end + # }}} + end + + # Prints a String to the client. If caching is enabled, the String will + # buffered until the end of the out block ends. + def print(str = "") + # {{{ + unless @output_allowed + raise "You just can write to output inside of a Rweb::out-block" + end + + if @settings["cache"] + @buffer += [str.to_s] + else + unless @output_started + sendHeaders + end + $stdout.print(str) + end + nil + # }}} + end + + # Prints a String to the client and adds a line break at the end. Please + # remember, that a line break is not visible in HTML, use the
      HTML-Tag + # for this. If caching is enabled, the String will buffered until the end + # of the out block ends. + def puts(str = "") + # {{{ + self.print(str + "\n") + # }}} + end + + # Alias to print. + def write(str = "") + # {{{ + self.print(str) + # }}} + end + + # If caching is enabled, all cached data are send to the cliend and the + # cache emptied. + def flush + # {{{ + unless @output_allowed + raise "You can't use flush outside of a Rweb::out-block" + end + buffer = @buffer.join + + unless @output_started + sendHeaders + end + $stdout.print(buffer) + + @buffer = [] + # }}} + end + + # Sends one or more header to the client. All headers are cached just + # before body data are send to the client. If the same header are set + # twice, only the last value is send. + # + # Example: + # web.header("Last-Modified: Mon, 16 Feb 2004 20:15:41 GMT") + # web.header("Location: http://www.ruby-lang.org") + # + # You can specify more than one header at the time by doing something like + # this: + # web.header("Content-Type: text/plain\nContent-Length: 383") + # or + # web.header(["Content-Type: text/plain", "Content-Length: 383"]) + def header(str) + # {{{ + if @output_started + raise "HTTP-Headers are already send. You can't change them after output has started!" + end + unless @output_allowed + raise "You just can set headers inside of a Rweb::out-block" + end + if str.is_a?Array + str.each do | value | + self.header(value) + end + + elsif str.split(/\n/).length > 1 + str.split(/\n/).each do | value | + self.header(value) + end + + elsif str.is_a? String + str.gsub!(/\r/, "") + + if (str =~ /^HTTP\/1\.[01] [0-9]{3} ?.*$/) == 0 + pattern = /^HTTP\/1.[01] ([0-9]{3}) ?(.*)$/ + + result = pattern.match(str) + self.setstatus(result[0], result[1]) + elsif (str =~ /^status: [0-9]{3} ?.*$/i) == 0 + pattern = /^status: ([0-9]{3}) ?(.*)$/i + + result = pattern.match(str) + self.setstatus(result[0], result[1]) + else + a = str.split(/: ?/, 2) + + @header[a[0].downcase] = a[1] + end + end + # }}} + end + + # Changes the status of this page. There are several codes like "200 OK", + # "302 Found", "404 Not Found" or "500 Internal Server Error". A list of + # all codes is available at + # http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10 + # + # You can just send the code number, the reason phrase will be added + # automaticly with the recommendations from the w3c if not specified. If + # you set the status twice or more, only the last status will be send. + # Examples: + # web.status("401 Unauthorized") + # web.status("410 Sad but true, this lonely page is gone :(") + # web.status(206) + # web.status("400") + # + # The default status is "200 OK". If a "Location" header is set, the + # default status is "302 Found". + def status(str) + # {{{ + if @output_started + raise "HTTP-Headers are already send. You can't change them after output has started!" + end + unless @output_allowed + raise "You just can set headers inside of a Rweb::out-block" + end + if str.is_a?Integer + @status = str + elsif str.is_a?String + p1 = /^([0-9]{3}) ?(.*)$/ + p2 = /^HTTP\/1\.[01] ([0-9]{3}) ?(.*)$/ + p3 = /^status: ([0-9]{3}) ?(.*)$/i + + if (a = p1.match(str)) == nil + if (a = p2.match(str)) == nil + if (a = p3.match(str)) == nil + raise ArgumentError, "Invalid argument", caller + end + end + end + @status = a[1].to_i + if a[2] != "" + @reasonPhrase = a[2] + else + @reasonPhrase = getReasonPhrase(@status) + end + else + raise ArgumentError, "Argument of setstatus must be integer or string", caller + end + # }}} + end + + # Handles the output of your content and rescues all exceptions. Send all + # data in the block to this method. For example: + # web.out do + # web.header("Content-Type: text/plain") + # web.puts("Hello, plain world!") + # end + def out + # {{{ + @output_allowed = true + @buffer = []; # We use an array as buffer, because it's more performant :) + + begin + yield + rescue Exception => exception + $stderr.puts "Ruby exception rescued (#{exception.class}): #{exception.message}" + $stderr.puts exception.backtrace.join("\n") + + unless @output_started + self.setstatus(500) + @header = {} + end + + unless (@settings.has_key?("hide errors") and @settings["hide errors"] == true) + unless @output_started + self.header("Content-Type: text/html") + self.puts "" + self.puts "" + self.puts "" + self.puts "500 Internal Server Error" + self.puts "" + self.puts "" + end + if @header.has_key?("content-type") and (@header["content-type"] =~ /^text\/html/i) == 0 + self.puts "

      Internal Server Error

      " + self.puts "

      The server encountered an exception and was unable to complete your request.

      " + self.puts "

      The exception has provided the following information:

      " + self.puts "
      #{exception.class}: #{exception.message} on"
+                    self.puts
+                    self.puts "#{exception.backtrace.join("\n")}
      " + self.puts "" + self.puts "" + else + self.puts "The server encountered an exception and was unable to complete your request" + self.puts "The exception has provided the following information:" + self.puts "#{exception.class}: #{exception.message}" + self.puts + self.puts exception.backtrace.join("\n") + end + end + end + + if @settings["cache"] + buffer = @buffer.join + + unless @output_started + unless @header.has_key?("content-length") + self.header("content-length: #{buffer.length}") + end + + sendHeaders + end + $stdout.print(buffer) + elsif !@output_started + sendHeaders + end + @output_allowed = false; + # }}} + end + + # Decodes URL encoded data, %20 for example stands for a space. + def Rweb.unescape(str) + # {{{ + if defined? str and str.is_a? String + str.gsub!(/\+/, " ") + str.gsub(/%.{2}/) do | s | + s[1,2].hex.chr + end + end + # }}} + end + + protected + def sendHeaders + # {{{ + + Cookie.disallow # no more cookies can be set or modified + if !(@settings.has_key?("silent") and @settings["silent"] == true) and !@header.has_key?("x-powered-by") + if @mod_ruby + header("x-powered-by: #{RWEB} (Ruby/#{RUBY_VERSION}, #{MOD_RUBY})"); + else + header("x-powered-by: #{RWEB} (Ruby/#{RUBY_VERSION})"); + end + end + + if @output_method == "ph" + if ((@status == nil or @status == 200) and !@header.has_key?("content-type") and !@header.has_key?("location")) + header("content-type: text/html") + end + + if @status != nil + $stdout.print "Status: #{@status} #{@reasonPhrase}\r\n" + end + + @header.each do |key, value| + key = key *1 # "unfreeze" key :) + key[0] = key[0,1].upcase![0] + + key = key.gsub(/-[a-z]/) do |char| + "-" + char[1,1].upcase + end + + $stdout.print "#{key}: #{value}\r\n" + end + cookies = Cookie.getHttpHeader # Get all cookies as an HTTP Header + if cookies + $stdout.print cookies + end + + $stdout.print "\r\n" + + elsif @output_method == "nph" + elsif @output_method == "mod_ruby" + r = Apache.request + + if ((@status == nil or @status == 200) and !@header.has_key?("content-type") and !@header.has_key?("location")) + header("text/html") + end + + if @status != nil + r.status_line = "#{@status} #{@reasonPhrase}" + end + + r.send_http_header + @header.each do |key, value| + key = key *1 # "unfreeze" key :) + + key[0] = key[0,1].upcase![0] + key = key.gsub(/-[a-z]/) do |char| + "-" + char[1,1].upcase + end + puts "#{key}: #{value.class}" + #r.headers_out[key] = value + end + end + @output_started = true + # }}} + end + + def getReasonPhrase (status) + # {{{ + if status == 100 + "Continue" + elsif status == 101 + "Switching Protocols" + elsif status == 200 + "OK" + elsif status == 201 + "Created" + elsif status == 202 + "Accepted" + elsif status == 203 + "Non-Authoritative Information" + elsif status == 204 + "No Content" + elsif status == 205 + "Reset Content" + elsif status == 206 + "Partial Content" + elsif status == 300 + "Multiple Choices" + elsif status == 301 + "Moved Permanently" + elsif status == 302 + "Found" + elsif status == 303 + "See Other" + elsif status == 304 + "Not Modified" + elsif status == 305 + "Use Proxy" + elsif status == 307 + "Temporary Redirect" + elsif status == 400 + "Bad Request" + elsif status == 401 + "Unauthorized" + elsif status == 402 + "Payment Required" + elsif status == 403 + "Forbidden" + elsif status == 404 + "Not Found" + elsif status == 405 + "Method Not Allowed" + elsif status == 406 + "Not Acceptable" + elsif status == 407 + "Proxy Authentication Required" + elsif status == 408 + "Request Time-out" + elsif status == 409 + "Conflict" + elsif status == 410 + "Gone" + elsif status == 411 + "Length Required" + elsif status == 412 + "Precondition Failed" + elsif status == 413 + "Request Entity Too Large" + elsif status == 414 + "Request-URI Too Large" + elsif status == 415 + "Unsupported Media Type" + elsif status == 416 + "Requested range not satisfiable" + elsif status == 417 + "Expectation Failed" + elsif status == 500 + "Internal Server Error" + elsif status == 501 + "Not Implemented" + elsif status == 502 + "Bad Gateway" + elsif status == 503 + "Service Unavailable" + elsif status == 504 + "Gateway Time-out" + elsif status == 505 + "HTTP Version not supported" + else + raise "Unknown Statuscode. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html#sec6.1 for more information." + end + # }}} + end +end + +class Cookie + attr_reader :name, :value, :maxage, :path, :domain, :secure, :comment + + # Sets a cookie. Please see below for details of the attributes. + def initialize (name, value = nil, maxage = nil, path = nil, domain = nil, secure = false) + # {{{ + # HTTP headers (Cookies are a HTTP header) can only set, while no content + # is send. So an exception will be raised, when @@allowed is set to false + # and a new cookie has set. + unless defined?(@@allowed) + @@allowed = true + end + unless @@allowed + raise "You can't set cookies after the HTTP headers are send." + end + + unless defined?(@@list) + @@list = [] + end + @@list += [self] + + unless defined?(@@type) + @@type = "netscape" + end + + unless name.class == String + raise TypeError, "The name of a cookie must be a string", caller + end + if value.class.superclass == Integer || value.class == Float + value = value.to_s + elsif value.class != String && value != nil + raise TypeError, "The value of a cookie must be a string, integer, float or nil", caller + end + if maxage.class == Time + maxage = maxage - Time.now + elsif !maxage.class.superclass == Integer || !maxage == nil + raise TypeError, "The maxage date of a cookie must be an Integer or Time object or nil.", caller + end + unless path.class == String || path == nil + raise TypeError, "The path of a cookie must be nil or a string", caller + end + unless domain.class == String || domain == nil + raise TypeError, "The value of a cookie must be nil or a string", caller + end + unless secure == true || secure == false + raise TypeError, "The secure field of a cookie must be true or false", caller + end + + @name, @value, @maxage, @path, @domain, @secure = name, value, maxage, path, domain, secure + @comment = nil + # }}} + end + + # Modifies the value of this cookie. The information you want to store. If the + # value is nil, the cookie will be deleted by the client. + # + # This attribute can be a String, Integer or Float object or nil. + def value=(value) + # {{{ + if value.class.superclass == Integer || value.class == Float + value = value.to_s + elsif value.class != String && value != nil + raise TypeError, "The value of a cookie must be a string, integer, float or nil", caller + end + @value = value + # }}} + end + + # Modifies the maxage of this cookie. This attribute defines the lifetime of + # the cookie, in seconds. A value of 0 means the cookie should be discarded + # imediatly. If it set to nil, the cookie will be deleted when the browser + # will be closed. + # + # Attention: This is different from other implementations like PHP, where you + # gives the seconds since 1/1/1970 0:00:00 GMT. + # + # This attribute must be an Integer or Time object or nil. + def maxage=(maxage) + # {{{ + if maxage.class == Time + maxage = maxage - Time.now + elsif maxage.class.superclass == Integer || !maxage == nil + raise TypeError, "The maxage of a cookie must be an Interger or Time object or nil.", caller + end + @maxage = maxage + # }}} + end + + # Modifies the path value of this cookie. The client will send this cookie + # only, if the requested document is this directory or a subdirectory of it. + # + # The value of the attribute must be a String object or nil. + def path=(path) + # {{{ + unless path.class == String || path == nil + raise TypeError, "The path of a cookie must be nil or a string", caller + end + @path = path + # }}} + end + + # Modifies the domain value of this cookie. The client will send this cookie + # only if it's connected with this domain (or a subdomain, if the first + # character is a dot like in ".ruby-lang.org") + # + # The value of this attribute must be a String or nil. + def domain=(domain) + # {{{ + unless domain.class == String || domain == nil + raise TypeError, "The domain of a cookie must be a String or nil.", caller + end + @domain = domain + # }}} + end + + # Modifies the secure flag of this cookie. If it's true, the client will only + # send this cookie if it is secured connected with us. + # + # The value od this attribute has to be true or false. + def secure=(secure) + # {{{ + unless secure == true || secure == false + raise TypeError, "The secure field of a cookie must be true or false", caller + end + @secure = secure + # }}} + end + + # Modifies the comment value of this cookie. The comment won't be send, if + # type is "netscape". + def comment=(comment) + # {{{ + unless comment.class == String || comment == nil + raise TypeError, "The comment of a cookie must be a string or nil", caller + end + @comment = comment + # }}} + end + + # Changes the type of all cookies. + # Allowed values are RFC2109 and netscape (default). + def Cookie.type=(type) + # {{{ + unless @@allowed + raise "The cookies are allready send, so you can't change the type anymore." + end + unless type.downcase == "rfc2109" && type.downcase == "netscape" + raise "The type of the cookies must be \"RFC2109\" or \"netscape\"." + end + @@type = type; + # }}} + end + + # After sending this message, no cookies can be set or modified. Use it, when + # HTTP-Headers are send. Rweb does this for you. + def Cookie.disallow + # {{{ + @@allowed = false + true + # }}} + end + + # Returns a HTTP header (type String) with all cookies. Rweb does this for + # you. + def Cookie.getHttpHeader + # {{{ + if defined?(@@list) + if @@type == "netscape" + str = "" + @@list.each do |cookie| + if cookie.value == nil + cookie.maxage = 0 + cookie.value = "" + end + # TODO: Name and value should be escaped! + str += "Set-Cookie: #{cookie.name}=#{cookie.value}" + unless cookie.maxage == nil + expire = Time.now + cookie.maxage + expire.gmtime + str += "; Expire=#{expire.strftime("%a, %d-%b-%Y %H:%M:%S %Z")}" + end + unless cookie.domain == nil + str += "; Domain=#{cookie.domain}" + end + unless cookie.path == nil + str += "; Path=#{cookie.path}" + end + if cookie.secure + str += "; Secure" + end + str += "\r\n" + end + return str + else # type == "RFC2109" + str = "Set-Cookie: " + comma = false; + + @@list.each do |cookie| + if cookie.value == nil + cookie.maxage = 0 + cookie.value = "" + end + if comma + str += "," + end + comma = true + + str += "#{cookie.name}=\"#{cookie.value}\"" + unless cookie.maxage == nil + str += "; Max-Age=\"#{cookie.maxage}\"" + end + unless cookie.domain == nil + str += "; Domain=\"#{cookie.domain}\"" + end + unless cookie.path == nil + str += "; Path=\"#{cookie.path}\"" + end + if cookie.secure + str += "; Secure" + end + unless cookie.comment == nil + str += "; Comment=\"#{cookie.comment}\"" + end + str += "; Version=\"1\"" + end + str + end + else + false + end + # }}} + end +end + +require 'strscan' + +module BBCode + DEBUG = true + + use 'encoder', 'tags', 'tagstack', 'smileys' + +=begin + The Parser class takes care of the encoding. + It scans the given BBCode (as plain text), finds tags + and smilies and also makes links of urls in text. + + Normal text is send directly to the encoder. + + If a tag was found, an instance of a Tag subclass is created + to handle the case. + + The @tagstack manages tag nesting and ensures valid HTML. +=end + + class Parser + class Attribute + # flatten and use only one empty_arg + def self.create attr + attr = flatten attr + return @@empty_attr if attr.empty? + new attr + end + + private_class_method :new + + # remove leading and trailing whitespace; concat lines + def self.flatten attr + attr.strip.gsub(/\n/, ' ') + # -> ^ and $ can only match at begin and end now + end + + ATTRIBUTE_SCAN = / + (?!$) # don't match at end + \s* + ( # $1 = key + [^=\s\]"\\]* + (?: + (?: \\. | "[^"\\]*(?:\\.[^"\\]*)*"? ) + [^=\s\]"\\]* + )* + ) + (?: + = + ( # $2 = value + [^\s\]"\\]* + (?: + (?: \\. | "[^"\\]*(?:\\.[^"\\]*)*"? ) + [^\s\]"\\]* + )* + )? + )? + \s* + /x + + def self.parse source + source = source.dup + # empty_tag: the tag looks like [... /] + # slice!: this deletes the \s*/] at the end + # \s+ because [url=http://rubybb.org/forum/] is NOT an empty tag. + # In RubyBBCode, you can use [url=http://rubybb.org/forum/ /], and this has to be + # interpreted correctly. + empty_tag = source.sub!(/^:/, '=') or source.slice!(/\/$/) + debug 'PARSE: ' + source.inspect + ' => ' + empty_tag.inspect + #-> we have now an attr that's EITHER empty OR begins and ends with non-whitespace. + + attr = Hash.new + attr[:flags] = [] + source.scan(ATTRIBUTE_SCAN) { |key, value| + if not value + attr[:flags] << unescape(key) + else + next if value.empty? and key.empty? + attr[unescape(key)] = unescape(value) + end + } + debug attr.inspect + + return empty_tag, attr + end + + def self.unescape_char esc + esc[1] + end + + def self.unquote qt + qt[1..-1].chomp('"').gsub(/\\./) { |esc| unescape_char esc } + end + + def self.unescape str + str.gsub(/ (\\.) | (" [^"\\]* (?:\\.[^"\\]*)* "?) /x) { + if $1 + unescape_char $1 + else + unquote $2 + end + } + end + + include Enumerable + def each &block + @args.each(&block) + end + + attr_reader :source, :args, :value + + def initialize source + @source = source + debug 'Attribute#new(%p)' % source + @empty_tag, @attr = Attribute.parse source + @value = @attr[''].to_s + end + + def empty? + self == @@empty_attr + end + + def empty_tag? + @empty_tag + end + + def [] *keys + res = @attr[*keys] + end + + def flags + attr[:flags] + end + + def to_s + @attr + end + + def inspect + 'ATTR[' + @attr.inspect + (@empty_tag ? ' | empty tag' : '') + ']' + end + end + class Attribute + @@empty_attr = new '' + end + end + Added: external/Pygments-0.8.1/tests/examplefiles/example.rhtml ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/example.rhtml Thu Aug 9 17:43:13 2007 @@ -0,0 +1,561 @@ +<% @title = 'Moderatoren-Interface' %> + +
      +
      <%= link_to 'Proben', :controller => '/admin/proben' %>
      +
      Die angesetzten Proben des Orchesters
      +
      <%= link_to 'Auftritte', :controller => '/admin/proben' %>
      +
      Die Auftritte des Orchesters
      + <%- if @valid_user and @valid_user.admin? -%> +
      <%= link_to 'Benutzer', :controller => '/admin/user' %>
      +
      Benutzer organisieren (nur f??r den Admin)
      + <%- end -%> +
      +<% @title = 'Anmeldung' %> + +<%= render :partial => 'user_form', :object => @user %> +<% @title = 'Administrator erstellen' %> + +<%= render :partial => 'user_form', :object => @user %> +<%= form_tag %> +

      Extending and Embedding
      tutorial for C/C++ programmers

      From python-checkins at python.org Thu Aug 2 23:33:13 2007 From: python-checkins at python.org (matthias.klose) Date: Thu, 2 Aug 2007 23:33:13 +0200 (CEST) Subject: [Python-checkins] r56681 - in python/trunk: Doc/info/Makefile Misc/NEWS Message-ID: <20070802213313.D9D611E4005@bag.python.org> Author: matthias.klose Date: Thu Aug 2 23:33:13 2007 New Revision: 56681 Modified: python/trunk/Doc/info/Makefile python/trunk/Misc/NEWS Log: - Allow Emacs 22 for building the documentation in info format. Modified: python/trunk/Doc/info/Makefile ============================================================================== --- python/trunk/Doc/info/Makefile (original) +++ python/trunk/Doc/info/Makefile Thu Aug 2 23:33:13 2007 @@ -34,10 +34,10 @@ check-emacs-version: @v="`$(EMACS) --version 2>&1 | egrep '^(GNU |X)Emacs [12]*'`"; \ - if `echo "$$v" | grep '^GNU Emacs 21' >/dev/null 2>&1`; then \ + if `echo "$$v" | grep '^GNU Emacs 2[12]' >/dev/null 2>&1`; then \ echo "Using $(EMACS) to build the info docs"; \ else \ - echo "GNU Emacs 21 is required to build the info docs"; \ + echo "GNU Emacs 21 or 22 is required to build the info docs"; \ echo "Found $$v"; \ false; \ fi Modified: python/trunk/Misc/NEWS ============================================================================== --- python/trunk/Misc/NEWS (original) +++ python/trunk/Misc/NEWS Thu Aug 2 23:33:13 2007 @@ -958,6 +958,7 @@ - Fix the build of the library reference in info format. +- Allow Emacs 22 for building the documentation in info format. C API ----- From python-checkins at python.org Fri Aug 3 04:48:53 2007 From: python-checkins at python.org (facundo.batista) Date: Fri, 3 Aug 2007 04:48:53 +0200 (CEST) Subject: [Python-checkins] r56682 - in python/branches/decimal-branch/Lib: decimal.py test/test_decimal.py Message-ID: <20070803024853.6850D1E4005@bag.python.org> Author: facundo.batista Date: Fri Aug 3 04:48:53 2007 New Revision: 56682 Modified: python/branches/decimal-branch/Lib/decimal.py python/branches/decimal-branch/Lib/test/test_decimal.py Log: Now __cmp__ never returns NotImplemented. Test case added. Thanks Pablo Hoffman for SF bug 1764761. Modified: python/branches/decimal-branch/Lib/decimal.py ============================================================================== --- python/branches/decimal-branch/Lib/decimal.py (original) +++ python/branches/decimal-branch/Lib/decimal.py Fri Aug 3 04:48:53 2007 @@ -706,7 +706,8 @@ def __cmp__(self, other, context=None): other = _convert_other(other) if other is NotImplemented: - return other + # Never return NotImplemented + return 1 if self._is_special or other._is_special: ans = self._check_nans(other, context) Modified: python/branches/decimal-branch/Lib/test/test_decimal.py ============================================================================== --- python/branches/decimal-branch/Lib/test/test_decimal.py (original) +++ python/branches/decimal-branch/Lib/test/test_decimal.py Fri Aug 3 04:48:53 2007 @@ -858,6 +858,10 @@ a.sort() self.assertEqual(a, b) + # with None + self.assertFalse(Decimal(1) < None) + self.assertTrue(Decimal(1) > None) + def test_copy_and_deepcopy_methods(self): d = Decimal('43.24') c = copy.copy(d) From python-checkins at python.org Fri Aug 3 05:41:37 2007 From: python-checkins at python.org (facundo.batista) Date: Fri, 3 Aug 2007 05:41:37 +0200 (CEST) Subject: [Python-checkins] r56683 - python/branches/decimal-branch/Lib/decimal.py Message-ID: <20070803034137.F135C1E4005@bag.python.org> Author: facundo.batista Date: Fri Aug 3 05:41:36 2007 New Revision: 56683 Modified: python/branches/decimal-branch/Lib/decimal.py Log: Coded number_class() function, and is_subnormal() also to support the first. Tests pass ok. Modified: python/branches/decimal-branch/Lib/decimal.py ============================================================================== --- python/branches/decimal-branch/Lib/decimal.py (original) +++ python/branches/decimal-branch/Lib/decimal.py Fri Aug 3 05:41:36 2007 @@ -2398,6 +2398,13 @@ def is_subnormal(self, context=None): """Returns 1 if self is subnormal, otherwise returns 0.""" + if context is None: + context = getcontext() + + r = self._exp + len(self._int) + if r <= context.Emin: + return Decimal(1) + return Decimal(0) def is_zero(self, context=None): """Returns 1 if self is a zero, otherwise returns 0.""" @@ -2667,6 +2674,32 @@ +Normal +Infinity """ + if self.is_snan(): + return "sNaN" + if self.is_qnan(): + return "NaN" + inf = self._isinfinity() + if inf == 1: + return "+Infinity" + if inf == -1: + return "-Infinity" + if self.is_zero(): + if self._sign: + return "-Zero" + else: + return "+Zero" + if context is None: + context = getcontext() + if self.is_subnormal(context=context): + if self._sign: + return "-Subnormal" + else: + return "+Subnormal" + # just a normal, regular, boring number, :) + if self._sign: + return "-Normal" + else: + return "+Normal" def radix(self, context=None): """Just returns 10, as this is Decimal, :)""" From python-checkins at python.org Fri Aug 3 06:50:47 2007 From: python-checkins at python.org (martin.v.loewis) Date: Fri, 3 Aug 2007 06:50:47 +0200 (CEST) Subject: [Python-checkins] r56684 - python/branches/release24-maint/Tools/msi/uuids.py Message-ID: <20070803045047.2F1281E4005@bag.python.org> Author: martin.v.loewis Date: Fri Aug 3 06:50:46 2007 New Revision: 56684 Modified: python/branches/release24-maint/Tools/msi/uuids.py Log: Add uuids for upcoming 2.4.5 release. Modified: python/branches/release24-maint/Tools/msi/uuids.py ============================================================================== --- python/branches/release24-maint/Tools/msi/uuids.py (original) +++ python/branches/release24-maint/Tools/msi/uuids.py Fri Aug 3 06:50:46 2007 @@ -24,4 +24,6 @@ '2.4.3150':'{75e71add-042c-4f30-bfac-a9ec42351313}', # 2.4.3 '2.4.4121':'{cd2862db-22a4-4688-8772-85407ea21550}', # 2.4.4c1 '2.4.4150':'{60e2c8c9-6cf3-4b1a-9618-e304946c94e6}', # 2.4.4 + '2.4.5121':'{b67a2d9f-3555-46a2-bdea-8be2819ed15e}', # 2.4.5c1 + '2.4.5150':'{00ea7f9b-f7a9-4cd6-9a15-e5ed7faab8e6}', # 2.4.5 } From python-checkins at python.org Fri Aug 3 07:24:41 2007 From: python-checkins at python.org (neal.norwitz) Date: Fri, 3 Aug 2007 07:24:41 +0200 (CEST) Subject: [Python-checkins] r56687 - peps/trunk/pep-3108.txt Message-ID: <20070803052441.1B7711E4005@bag.python.org> Author: neal.norwitz Date: Fri Aug 3 07:24:40 2007 New Revision: 56687 Modified: peps/trunk/pep-3108.txt Log: Update with some modules that were (re)moved Modified: peps/trunk/pep-3108.txt ============================================================================== --- peps/trunk/pep-3108.txt (original) +++ peps/trunk/pep-3108.txt Fri Aug 3 07:24:40 2007 @@ -104,6 +104,12 @@ - SGI no longer sells machines with IRIX on them. - Code has not been uniquely edited in 14 years. + + cl [done] + + - Compression library for SGI systems. + - SGI no longer sells machines with IRIX on them. + - Code has not been uniquely edited in 14 years. + + DEVICE/GL/gl/cgen/cgensuport [done] - OpenGL access. @@ -138,7 +144,7 @@ * Solaris - + SUNAUDIODEV/sunaudiodev + + SUNAUDIODEV/sunaudiodev [done] - Access to the sound card on Sun machines. - Code not uniquely edited in over eight years. @@ -199,7 +205,7 @@ can be from how easy it is to implement the functionality from scratch or because the audience for the code is very small. -* audiodev +* audiodev [done] + Undocumented. + Not edited in five years. @@ -234,7 +240,7 @@ + Undocumented. -* toaiff +* toaiff [done, moved to Demo] + Undocumented. + Requires ``sox`` library to be installed on the system. @@ -449,7 +455,6 @@ Current Name Replacement Name ============ =============================== bdb _bdb -cl _cl markupbase _markupbase opcode _opcode dummy_thread _dummy_thread (assuming thread From python-checkins at python.org Fri Aug 3 07:52:44 2007 From: python-checkins at python.org (georg.brandl) Date: Fri, 3 Aug 2007 07:52:44 +0200 (CEST) Subject: [Python-checkins] r56688 - doctools/trunk/Doc-3k/library/audioop.rst doctools/trunk/Doc-3k/library/index.rst doctools/trunk/Doc-3k/library/sun.rst doctools/trunk/Doc-3k/library/sunaudio.rst doctools/trunk/Doc-3k/library/undoc.rst Message-ID: <20070803055244.CE4D21E4005@bag.python.org> Author: georg.brandl Date: Fri Aug 3 07:52:43 2007 New Revision: 56688 Removed: doctools/trunk/Doc-3k/library/sun.rst doctools/trunk/Doc-3k/library/sunaudio.rst Modified: doctools/trunk/Doc-3k/library/audioop.rst doctools/trunk/Doc-3k/library/index.rst doctools/trunk/Doc-3k/library/undoc.rst Log: Merge Doc changes in rev. 56685: Remove several h/w and o/s specific modules that are undocumented, obsolete, and/or not widely used: linuxaudiodev.c, sunaudiodev.c Lib/plat-sunos5/SUNAUDIODEV.py Lib/audiodev.py Tools/audiopy/audiopy Move Lib/toaiff.py to Demo. See PEP 3108 for most of the details. Modified: doctools/trunk/Doc-3k/library/audioop.rst ============================================================================== --- doctools/trunk/Doc-3k/library/audioop.rst (original) +++ doctools/trunk/Doc-3k/library/audioop.rst Fri Aug 3 07:52:43 2007 @@ -8,8 +8,7 @@ The :mod:`audioop` module contains some useful operations on sound fragments. It operates on sound fragments consisting of signed integer samples 8, 16 or 32 -bits wide, stored in Python strings. This is the same format as used by the -:mod:`al` and :mod:`sunaudiodev` modules. All scalar items are integers, unless +bits wide, stored in Python strings. All scalar items are integers, unless specified otherwise. .. index:: Modified: doctools/trunk/Doc-3k/library/index.rst ============================================================================== --- doctools/trunk/Doc-3k/library/index.rst (original) +++ doctools/trunk/Doc-3k/library/index.rst Fri Aug 3 07:52:43 2007 @@ -65,6 +65,5 @@ modules.rst language.rst misc.rst - sun.rst windows.rst undoc.rst Deleted: /doctools/trunk/Doc-3k/library/sun.rst ============================================================================== --- /doctools/trunk/Doc-3k/library/sun.rst Fri Aug 3 07:52:43 2007 +++ (empty file) @@ -1,14 +0,0 @@ - -.. _sunos: - -*********************** -SunOS Specific Services -*********************** - -The modules described in this chapter provide interfaces to features that are -unique to SunOS 5 (also known as Solaris version 2). - - -.. toctree:: - - sunaudio.rst Deleted: /doctools/trunk/Doc-3k/library/sunaudio.rst ============================================================================== --- /doctools/trunk/Doc-3k/library/sunaudio.rst Fri Aug 3 07:52:43 2007 +++ (empty file) @@ -1,156 +0,0 @@ - -:mod:`sunaudiodev` --- Access to Sun audio hardware -=================================================== - -.. module:: sunaudiodev - :platform: SunOS - :synopsis: Access to Sun audio hardware. - - -.. index:: single: u-LAW - -This module allows you to access the Sun audio interface. The Sun audio hardware -is capable of recording and playing back audio data in u-LAW format with a -sample rate of 8K per second. A full description can be found in the -:manpage:`audio(7I)` manual page. - -.. index:: module: SUNAUDIODEV - -The module :mod:`SUNAUDIODEV` defines constants which may be used with this -module. - -This module defines the following variables and functions: - - -.. exception:: error - - This exception is raised on all errors. The argument is a string describing what - went wrong. - - -.. function:: open(mode) - - This function opens the audio device and returns a Sun audio device object. This - object can then be used to do I/O on. The *mode* parameter is one of ``'r'`` for - record-only access, ``'w'`` for play-only access, ``'rw'`` for both and - ``'control'`` for access to the control device. Since only one process is - allowed to have the recorder or player open at the same time it is a good idea - to open the device only for the activity needed. See :manpage:`audio(7I)` for - details. - - As per the manpage, this module first looks in the environment variable - ``AUDIODEV`` for the base audio device filename. If not found, it falls back to - :file:`/dev/audio`. The control device is calculated by appending "ctl" to the - base audio device. - - -.. _audio-device-objects: - -Audio Device Objects --------------------- - -The audio device objects are returned by :func:`open` define the following -methods (except ``control`` objects which only provide :meth:`getinfo`, -:meth:`setinfo`, :meth:`fileno`, and :meth:`drain`): - - -.. method:: audio device.close() - - This method explicitly closes the device. It is useful in situations where - deleting the object does not immediately close it since there are other - references to it. A closed device should not be used again. - - -.. method:: audio device.fileno() - - Returns the file descriptor associated with the device. This can be used to set - up ``SIGPOLL`` notification, as described below. - - -.. method:: audio device.drain() - - This method waits until all pending output is processed and then returns. - Calling this method is often not necessary: destroying the object will - automatically close the audio device and this will do an implicit drain. - - -.. method:: audio device.flush() - - This method discards all pending output. It can be used avoid the slow response - to a user's stop request (due to buffering of up to one second of sound). - - -.. method:: audio device.getinfo() - - This method retrieves status information like input and output volume, etc. and - returns it in the form of an audio status object. This object has no methods but - it contains a number of attributes describing the current device status. The - names and meanings of the attributes are described in ```` and in - the :manpage:`audio(7I)` manual page. Member names are slightly different from - their C counterparts: a status object is only a single structure. Members of the - :cdata:`play` substructure have ``o_`` prepended to their name and members of - the :cdata:`record` structure have ``i_``. So, the C member - :cdata:`play.sample_rate` is accessed as :attr:`o_sample_rate`, - :cdata:`record.gain` as :attr:`i_gain` and :cdata:`monitor_gain` plainly as - :attr:`monitor_gain`. - - -.. method:: audio device.ibufcount() - - This method returns the number of samples that are buffered on the recording - side, i.e. the program will not block on a :func:`read` call of so many samples. - - -.. method:: audio device.obufcount() - - This method returns the number of samples buffered on the playback side. - Unfortunately, this number cannot be used to determine a number of samples that - can be written without blocking since the kernel output queue length seems to be - variable. - - -.. method:: audio device.read(size) - - This method reads *size* samples from the audio input and returns them as a - Python string. The function blocks until enough data is available. - - -.. method:: audio device.setinfo(status) - - This method sets the audio device status parameters. The *status* parameter is - an device status object as returned by :func:`getinfo` and possibly modified by - the program. - - -.. method:: audio device.write(samples) - - Write is passed a Python string containing audio samples to be played. If there - is enough buffer space free it will immediately return, otherwise it will block. - -The audio device supports asynchronous notification of various events, through -the SIGPOLL signal. Here's an example of how you might enable this in Python:: - - def handle_sigpoll(signum, frame): - print 'I got a SIGPOLL update' - - import fcntl, signal, STROPTS - - signal.signal(signal.SIGPOLL, handle_sigpoll) - fcntl.ioctl(audio_obj.fileno(), STROPTS.I_SETSIG, STROPTS.S_MSG) - - -:mod:`SUNAUDIODEV` --- Constants used with :mod:`sunaudiodev` -============================================================= - -.. module:: SUNAUDIODEV - :platform: SunOS - :synopsis: Constants for use with sunaudiodev. - - -.. index:: module: sunaudiodev - -This is a companion module to :mod:`sunaudiodev` which defines useful symbolic -constants like :const:`MIN_GAIN`, :const:`MAX_GAIN`, :const:`SPEAKER`, etc. The -names of the constants are the same names as used in the C include file -````, with the leading string ``AUDIO_`` stripped. - Modified: doctools/trunk/Doc-3k/library/undoc.rst ============================================================================== --- doctools/trunk/Doc-3k/library/undoc.rst (original) +++ doctools/trunk/Doc-3k/library/undoc.rst Fri Aug 3 07:52:43 2007 @@ -51,9 +51,6 @@ Multimedia ========== -:mod:`audiodev` - --- Platform-independent API for playing audio data. - :mod:`linuxaudiodev` --- Play audio data on the Linux audio device. Replaced in Python 2.3 by the :mod:`ossaudiodev` module. @@ -61,10 +58,6 @@ :mod:`sunaudio` --- Interpret Sun audio headers (may become obsolete or a tool/demo). -:mod:`toaiff` - --- Convert "arbitrary" sound files to AIFF files; should probably become a tool - or demo. Requires the external program :program:`sox`. - .. _obsolete-modules: From python-checkins at python.org Fri Aug 3 08:46:30 2007 From: python-checkins at python.org (neal.norwitz) Date: Fri, 3 Aug 2007 08:46:30 +0200 (CEST) Subject: [Python-checkins] r56689 - in python/trunk: Include/structmember.h Misc/NEWS Message-ID: <20070803064630.3E1191E4005@bag.python.org> Author: neal.norwitz Date: Fri Aug 3 08:46:29 2007 New Revision: 56689 Modified: python/trunk/Include/structmember.h python/trunk/Misc/NEWS Log: Py_ssize_t is defined regardless of HAVE_LONG_LONG. Will backport Modified: python/trunk/Include/structmember.h ============================================================================== --- python/trunk/Include/structmember.h (original) +++ python/trunk/Include/structmember.h Fri Aug 3 08:46:29 2007 @@ -68,9 +68,11 @@ #ifdef HAVE_LONG_LONG #define T_LONGLONG 17 #define T_ULONGLONG 18 -#define T_PYSSIZET 19 /* Py_ssize_t */ #endif /* HAVE_LONG_LONG */ +#define T_PYSSIZET 19 /* Py_ssize_t */ + + /* Flags */ #define READONLY 1 #define RO READONLY /* Shorthand */ Modified: python/trunk/Misc/NEWS ============================================================================== --- python/trunk/Misc/NEWS (original) +++ python/trunk/Misc/NEWS Fri Aug 3 08:46:29 2007 @@ -12,6 +12,8 @@ Core and builtins ----------------- +- Py_ssize_t fields work in structmember when HAVE_LONG_LONG is not defined. + - PEP 3123: Provide forward compatibility with Python 3.0, while keeping backwards compatibility. Add Py_Refcnt, Py_Type, Py_Size, and PyVarObject_HEAD_INIT. From nnorwitz at gmail.com Fri Aug 3 08:49:04 2007 From: nnorwitz at gmail.com (Neal Norwitz) Date: Thu, 2 Aug 2007 23:49:04 -0700 Subject: [Python-checkins] r56689 - in python/trunk: Include/structmember.h Misc/NEWS In-Reply-To: <20070803064630.3E1191E4005@bag.python.org> References: <20070803064630.3E1191E4005@bag.python.org> Message-ID: Oops. I won't backport this change as it is new in 2.6. -- n On 8/2/07, neal.norwitz wrote: > Author: neal.norwitz > Date: Fri Aug 3 08:46:29 2007 > New Revision: 56689 > > Modified: > python/trunk/Include/structmember.h > python/trunk/Misc/NEWS > Log: > Py_ssize_t is defined regardless of HAVE_LONG_LONG. Will backport > > Modified: python/trunk/Include/structmember.h > ============================================================================== > --- python/trunk/Include/structmember.h (original) > +++ python/trunk/Include/structmember.h Fri Aug 3 08:46:29 2007 > @@ -68,9 +68,11 @@ > #ifdef HAVE_LONG_LONG > #define T_LONGLONG 17 > #define T_ULONGLONG 18 > -#define T_PYSSIZET 19 /* Py_ssize_t */ > #endif /* HAVE_LONG_LONG */ > > +#define T_PYSSIZET 19 /* Py_ssize_t */ > + > + > /* Flags */ > #define READONLY 1 > #define RO READONLY /* Shorthand */ > > Modified: python/trunk/Misc/NEWS > ============================================================================== > --- python/trunk/Misc/NEWS (original) > +++ python/trunk/Misc/NEWS Fri Aug 3 08:46:29 2007 > @@ -12,6 +12,8 @@ > Core and builtins > ----------------- > > +- Py_ssize_t fields work in structmember when HAVE_LONG_LONG is not defined. > + > - PEP 3123: Provide forward compatibility with Python 3.0, while keeping > backwards compatibility. Add Py_Refcnt, Py_Type, Py_Size, and > PyVarObject_HEAD_INIT. > _______________________________________________ > Python-checkins mailing list > Python-checkins at python.org > http://mail.python.org/mailman/listinfo/python-checkins > From python-checkins at python.org Fri Aug 3 09:32:32 2007 From: python-checkins at python.org (georg.brandl) Date: Fri, 3 Aug 2007 09:32:32 +0200 (CEST) Subject: [Python-checkins] r56690 - in doctools/trunk: Doc-26/c-api/newtypes.rst Doc-26/documenting/markup.rst Doc-26/extending/embedding.rst Doc-26/extending/newtypes.rst Doc-26/library/ast.rst Doc-26/library/datetime.rst Doc-26/library/email-examples.rst Doc-26/library/exceptions.rst Doc-26/library/sqlite3.rst Doc-26/library/xml.dom.minidom.rst Doc-3k/c-api/newtypes.rst Doc-3k/documenting/markup.rst Doc-3k/extending/embedding.rst Doc-3k/extending/newtypes.rst Doc-3k/library/datetime.rst Doc-3k/library/email-examples.rst Doc-3k/library/exceptions.rst Doc-3k/library/sqlite3.rst Doc-3k/library/xml.dom.minidom.rst sphinx/directives.py Message-ID: <20070803073232.09F481E4005@bag.python.org> Author: georg.brandl Date: Fri Aug 3 09:32:31 2007 New Revision: 56690 Modified: doctools/trunk/Doc-26/c-api/newtypes.rst doctools/trunk/Doc-26/documenting/markup.rst doctools/trunk/Doc-26/extending/embedding.rst doctools/trunk/Doc-26/extending/newtypes.rst doctools/trunk/Doc-26/library/ast.rst doctools/trunk/Doc-26/library/datetime.rst doctools/trunk/Doc-26/library/email-examples.rst doctools/trunk/Doc-26/library/exceptions.rst doctools/trunk/Doc-26/library/sqlite3.rst doctools/trunk/Doc-26/library/xml.dom.minidom.rst doctools/trunk/Doc-3k/c-api/newtypes.rst doctools/trunk/Doc-3k/documenting/markup.rst doctools/trunk/Doc-3k/extending/embedding.rst doctools/trunk/Doc-3k/extending/newtypes.rst doctools/trunk/Doc-3k/library/datetime.rst doctools/trunk/Doc-3k/library/email-examples.rst doctools/trunk/Doc-3k/library/exceptions.rst doctools/trunk/Doc-3k/library/sqlite3.rst doctools/trunk/Doc-3k/library/xml.dom.minidom.rst doctools/trunk/sphinx/directives.py Log: Replace .. include by a new .. literalinclude which doesn't raise if the file isn't found. Modified: doctools/trunk/Doc-26/c-api/newtypes.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/newtypes.rst (original) +++ doctools/trunk/Doc-26/c-api/newtypes.rst Fri Aug 3 09:32:31 2007 @@ -356,9 +356,8 @@ :file:`Include/object.h`. For convenience of reference, this repeats the definition found there: +.. literalinclude:: ../includes/typestruct.h -.. include:: ../includes/typestruct.h - :literal: The type object structure extends the :ctype:`PyVarObject` structure. The :attr:`ob_size` field is used for dynamic types (created by :func:`type_new`, Modified: doctools/trunk/Doc-26/documenting/markup.rst ============================================================================== --- doctools/trunk/Doc-26/documenting/markup.rst (original) +++ doctools/trunk/Doc-26/documenting/markup.rst Fri Aug 3 09:32:31 2007 @@ -8,7 +8,7 @@ Documentation for "standard" reST constructs is not included here, though they are used in the Python documentation. -XXX: file-wide metadata +.. XXX: file-wide metadata Meta-information markup ----------------------- @@ -250,11 +250,13 @@ Longer displays of verbatim text may be included by storing the example text in an external file containing only plain text. The file may be included using the -standard ``include`` directive with the ``literal`` option flag. For example, -to include the Python source file :file:`example.py`, use:: +``literalinclude`` directive. [1]_ For example, to include the Python source file +:file:`example.py`, use:: - .. include:: example.py - :literal: + .. literalinclude:: example.py + +The file name is relative to the current file's path. Documentation-specific +include files should be placed in the ``Doc/includes`` subdirectory. Inline markup @@ -741,3 +743,9 @@ Replaced by either today's date, or the date set in the build configuration file. Normally has the format ``April 14, 2007``. + + +.. rubric:: Footnotes + +.. [1] There is a standard ``.. include`` directive, but it raises errors if the + file is not found. This one only emits a warning. Modified: doctools/trunk/Doc-26/extending/embedding.rst ============================================================================== --- doctools/trunk/Doc-26/extending/embedding.rst (original) +++ doctools/trunk/Doc-26/extending/embedding.rst Fri Aug 3 09:32:31 2007 @@ -132,9 +132,8 @@ The code to run a function defined in a Python script is: +.. literalinclude:: ../includes/run-func.c -.. include:: ../includes/run-func.c - :literal: This code loads a Python script using ``argv[1]``, and calls the function named in ``argv[2]``. Its integer arguments are the other values of the ``argv`` Modified: doctools/trunk/Doc-26/extending/newtypes.rst ============================================================================== --- doctools/trunk/Doc-26/extending/newtypes.rst (original) +++ doctools/trunk/Doc-26/extending/newtypes.rst Fri Aug 3 09:32:31 2007 @@ -47,9 +47,8 @@ This sort of thing can only be explained by example, so here's a minimal, but complete, module that defines a new type: +.. literalinclude:: ../includes/noddy.c -.. include:: ../includes/noddy.c - :literal: Now that's quite a bit to take in at once, but hopefully bits will seem familiar from the last chapter. @@ -248,9 +247,8 @@ the type usable as a base class. We'll create a new module, :mod:`noddy2` that adds these capabilities: +.. literalinclude:: ../includes/noddy2.c -.. include:: ../includes/noddy2.c - :literal: This version of the module has a number of changes. @@ -557,9 +555,8 @@ could be set to non-string values or even deleted. We want to make sure that these attributes always contain strings. +.. literalinclude:: ../includes/noddy3.c -.. include:: ../includes/noddy3.c - :literal: To provide greater control, over the :attr:`first` and :attr:`last` attributes, we'll use custom getter and setter functions. Here are the functions for @@ -708,9 +705,8 @@ collection, types need to fill two slots and set a class flag that enables these slots: +.. literalinclude:: ../includes/noddy4.c -.. include:: ../includes/noddy4.c - :literal: The traversal method provides access to subobjects that could participate in cycles:: @@ -839,9 +835,8 @@ >>> print s.increment() 2 +.. literalinclude:: ../includes/shoddy.c -.. include:: ../includes/shoddy.c - :literal: As you can see, the source code closely resembles the :class:`Noddy` examples in previous sections. We will break down the main differences between them. :: @@ -917,9 +912,8 @@ Here is the definition of :ctype:`PyTypeObject`, with some fields only used in debug builds omitted: +.. literalinclude:: ../includes/typestruct.h -.. include:: ../includes/typestruct.h - :literal: Now that's a *lot* of methods. Don't worry too much though - if you have a type you want to define, the chances are very good that you will only implement a Modified: doctools/trunk/Doc-26/library/ast.rst ============================================================================== --- doctools/trunk/Doc-26/library/ast.rst (original) +++ doctools/trunk/Doc-26/library/ast.rst Fri Aug 3 09:32:31 2007 @@ -1,8 +1,7 @@ .. _ast: -********************* Abstract Syntax Trees -********************* +===================== .. module:: _ast @@ -49,12 +48,11 @@ Abstract Grammar -================ +---------------- The module defines a string constant ``__version__`` which is the decimal subversion revision number of the file shown below. The abstract grammar is currently defined as follows: - -.. XXX includefile ../../Parser/Python.asdl +.. literalinclude:: ../../Parser/Python.asdl Modified: doctools/trunk/Doc-26/library/datetime.rst ============================================================================== --- doctools/trunk/Doc-26/library/datetime.rst (original) +++ doctools/trunk/Doc-26/library/datetime.rst Fri Aug 3 09:32:31 2007 @@ -1253,9 +1253,8 @@ Example :class:`tzinfo` classes: +.. literalinclude:: ../includes/tzinfo-examples.py -.. include:: ../includes/tzinfo-examples.py - :literal: Note that there are unavoidable subtleties twice per year in a :class:`tzinfo` subclass accounting for both standard and daylight time, at the DST transition Modified: doctools/trunk/Doc-26/library/email-examples.rst ============================================================================== --- doctools/trunk/Doc-26/library/email-examples.rst (original) +++ doctools/trunk/Doc-26/library/email-examples.rst Fri Aug 3 09:32:31 2007 @@ -6,33 +6,28 @@ First, let's see how to create and send a simple text message: +.. literalinclude:: ../includes/email-simple.py -.. include:: ../includes/email-simple.py - :literal: Here's an example of how to send a MIME message containing a bunch of family pictures that may be residing in a directory: +.. literalinclude:: ../includes/email-mime.py -.. include:: ../includes/email-mime.py - :literal: Here's an example of how to send the entire contents of a directory as an email -message: [#]_ +message: [1]_ +.. literalinclude:: ../includes/email-dir.py -.. include:: ../includes/email-dir.py - :literal: And finally, here's an example of how to unpack a MIME message like the one above, into a directory of files: - -.. include:: ../includes/email-unpack.py - :literal: +.. literalinclude:: ../includes/email-unpack.py .. rubric:: Footnotes -.. [#] Thanks to Matthew Dixon Cowles for the original inspiration and examples. +.. [1] Thanks to Matthew Dixon Cowles for the original inspiration and examples. Modified: doctools/trunk/Doc-26/library/exceptions.rst ============================================================================== --- doctools/trunk/Doc-26/library/exceptions.rst (original) +++ doctools/trunk/Doc-26/library/exceptions.rst Fri Aug 3 09:32:31 2007 @@ -479,4 +479,4 @@ The class hierarchy for built-in exceptions is: -.. XXX includefile ../../Lib/test/exception_hierarchy.txt +.. literalinclude:: ../../Lib/test/exception_hierarchy.txt Modified: doctools/trunk/Doc-26/library/sqlite3.rst ============================================================================== --- doctools/trunk/Doc-26/library/sqlite3.rst (original) +++ doctools/trunk/Doc-26/library/sqlite3.rst Fri Aug 3 09:32:31 2007 @@ -200,8 +200,7 @@ This can be used to build a shell for SQLite, as in the following example: - .. include:: ../includes/sqlite3/complete_statement.py - :literal: + .. literalinclude:: ../includes/sqlite3/complete_statement.py .. function:: enable_callback_tracebacks(flag) @@ -267,9 +266,7 @@ Example: - - .. include:: ../includes/sqlite3/md5func.py - :literal: + .. literalinclude:: ../includes/sqlite3/md5func.py .. method:: Connection.create_aggregate(name, num_params, aggregate_class) @@ -285,9 +282,7 @@ Example: - - .. include:: ../includes/sqlite3/mysumaggr.py - :literal: + .. literalinclude:: ../includes/sqlite3/mysumaggr.py .. method:: Connection.create_collation(name, callable) @@ -303,9 +298,7 @@ The following example shows a custom collation that sorts "the wrong way": - - .. include:: ../includes/sqlite3/collation_reverse.py - :literal: + .. literalinclude:: ../includes/sqlite3/collation_reverse.py To remove a collation, call ``create_collation`` with None as callable:: @@ -349,9 +342,7 @@ Example: - - .. include:: ../includes/sqlite3/row_factory.py - :literal: + .. literalinclude:: ../includes/sqlite3/row_factory.py If returning a tuple doesn't suffice and you want name-based access to columns, you should consider setting :attr:`row_factory` to the highly-optimized @@ -379,9 +370,7 @@ See the following example code for illustration: - - .. include:: ../includes/sqlite3/text_factory.py - :literal: + .. literalinclude:: ../includes/sqlite3/text_factory.py .. attribute:: Connection.total_changes @@ -407,15 +396,11 @@ This example shows how to use parameters with qmark style: - - .. include:: ../includes/sqlite3/execute_1.py - :literal: + .. literalinclude:: ../includes/sqlite3/execute_1.py This example shows how to use the named style: - - .. include:: ../includes/sqlite3/execute_2.py - :literal: + .. literalinclude:: ../includes/sqlite3/execute_2.py :meth:`execute` will only execute a single SQL statement. If you try to execute more than one statement with it, it will raise a Warning. Use @@ -429,15 +414,11 @@ sequence *sql*. The :mod:`sqlite3` module also allows using an iterator yielding parameters instead of a sequence. - - .. include:: ../includes/sqlite3/executemany_1.py - :literal: + .. literalinclude:: ../includes/sqlite3/executemany_1.py Here's a shorter example using a generator: - - .. include:: ../includes/sqlite3/executemany_2.py - :literal: + .. literalinclude:: ../includes/sqlite3/executemany_2.py .. method:: Cursor.executescript(sql_script) @@ -450,9 +431,7 @@ Example: - - .. include:: ../includes/sqlite3/executescript.py - :literal: + .. literalinclude:: ../includes/sqlite3/executescript.py .. attribute:: Cursor.rowcount @@ -559,9 +538,7 @@ to give your class a method ``__conform__(self, protocol)`` which must return the converted value. The parameter *protocol* will be :class:`PrepareProtocol`. - -.. include:: ../includes/sqlite3/adapter_point_1.py - :literal: +.. literalinclude:: ../includes/sqlite3/adapter_point_1.py Registering an adapter callable @@ -575,18 +552,14 @@ The type/class to adapt must be a new-style class, i. e. it must have :class:`object` as one of its bases. - -.. include:: ../includes/sqlite3/adapter_point_2.py - :literal: +.. literalinclude:: ../includes/sqlite3/adapter_point_2.py The :mod:`sqlite3` module has two default adapters for Python's built-in :class:`datetime.date` and :class:`datetime.datetime` types. Now let's suppose we want to store :class:`datetime.datetime` objects not in ISO representation, but as a Unix timestamp. - -.. include:: ../includes/sqlite3/adapter_datetime.py - :literal: +.. literalinclude:: ../includes/sqlite3/adapter_datetime.py Converting SQLite values to custom Python types @@ -630,9 +603,7 @@ The following example illustrates both approaches. - -.. include:: ../includes/sqlite3/converter_point.py - :literal: +.. literalinclude:: ../includes/sqlite3/converter_point.py Default adapters and converters @@ -651,9 +622,7 @@ The following example demonstrates this. - -.. include:: ../includes/sqlite3/pysqlite_datetime.py - :literal: +.. literalinclude:: ../includes/sqlite3/pysqlite_datetime.py .. _sqlite3-controlling-transactions: @@ -704,9 +673,7 @@ objects. This way, you can execute a SELECT statement and iterate over it directly using only a single call on the :class:`Connection` object. - -.. include:: ../includes/sqlite3/shortcut_methods.py - :literal: +.. literalinclude:: ../includes/sqlite3/shortcut_methods.py Accessing columns by name instead of by index @@ -718,7 +685,5 @@ Rows wrapped with this class can be accessed both by index (like tuples) and case-insensitively by name: - -.. include:: ../includes/sqlite3/rowclass.py - :literal: +.. literalinclude:: ../includes/sqlite3/rowclass.py Modified: doctools/trunk/Doc-26/library/xml.dom.minidom.rst ============================================================================== --- doctools/trunk/Doc-26/library/xml.dom.minidom.rst (original) +++ doctools/trunk/Doc-26/library/xml.dom.minidom.rst Fri Aug 3 09:32:31 2007 @@ -193,9 +193,7 @@ This example program is a fairly realistic example of a simple program. In this particular case, we do not take much advantage of the flexibility of the DOM. - -.. include:: ../includes/minidom-example.py - :literal: +.. literalinclude:: ../includes/minidom-example.py .. _minidom-and-dom: Modified: doctools/trunk/Doc-3k/c-api/newtypes.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/newtypes.rst (original) +++ doctools/trunk/Doc-3k/c-api/newtypes.rst Fri Aug 3 09:32:31 2007 @@ -356,9 +356,8 @@ :file:`Include/object.h`. For convenience of reference, this repeats the definition found there: +.. literalinclude:: ../includes/typestruct.h -.. include:: ../includes/typestruct.h - :literal: The type object structure extends the :ctype:`PyVarObject` structure. The :attr:`ob_size` field is used for dynamic types (created by :func:`type_new`, Modified: doctools/trunk/Doc-3k/documenting/markup.rst ============================================================================== --- doctools/trunk/Doc-3k/documenting/markup.rst (original) +++ doctools/trunk/Doc-3k/documenting/markup.rst Fri Aug 3 09:32:31 2007 @@ -8,7 +8,7 @@ Documentation for "standard" reST constructs is not included here, though they are used in the Python documentation. -XXX: file-wide metadata +.. XXX: file-wide metadata Meta-information markup ----------------------- @@ -250,11 +250,13 @@ Longer displays of verbatim text may be included by storing the example text in an external file containing only plain text. The file may be included using the -standard ``include`` directive with the ``literal`` option flag. For example, -to include the Python source file :file:`example.py`, use:: +``literalinclude`` directive. [1]_ For example, to include the Python source file +:file:`example.py`, use:: - .. include:: example.py - :literal: + .. literalinclude:: example.py + +The file name is relative to the current file's path. Documentation-specific +include files should be placed in the ``Doc/includes`` subdirectory. Inline markup @@ -741,3 +743,9 @@ Replaced by either today's date, or the date set in the build configuration file. Normally has the format ``April 14, 2007``. + + +.. rubric:: Footnotes + +.. [1] There is a standard ``.. include`` directive, but it raises errors if the + file is not found. This one only emits a warning. Modified: doctools/trunk/Doc-3k/extending/embedding.rst ============================================================================== --- doctools/trunk/Doc-3k/extending/embedding.rst (original) +++ doctools/trunk/Doc-3k/extending/embedding.rst Fri Aug 3 09:32:31 2007 @@ -132,9 +132,8 @@ The code to run a function defined in a Python script is: +.. literalinclude:: ../includes/run-func.c -.. include:: ../includes/run-func.c - :literal: This code loads a Python script using ``argv[1]``, and calls the function named in ``argv[2]``. Its integer arguments are the other values of the ``argv`` Modified: doctools/trunk/Doc-3k/extending/newtypes.rst ============================================================================== --- doctools/trunk/Doc-3k/extending/newtypes.rst (original) +++ doctools/trunk/Doc-3k/extending/newtypes.rst Fri Aug 3 09:32:31 2007 @@ -47,9 +47,8 @@ This sort of thing can only be explained by example, so here's a minimal, but complete, module that defines a new type: +.. literalinclude:: ../includes/noddy.c -.. include:: ../includes/noddy.c - :literal: Now that's quite a bit to take in at once, but hopefully bits will seem familiar from the last chapter. @@ -248,9 +247,8 @@ the type usable as a base class. We'll create a new module, :mod:`noddy2` that adds these capabilities: +.. literalinclude:: ../includes/noddy2.c -.. include:: ../includes/noddy2.c - :literal: This version of the module has a number of changes. @@ -557,9 +555,8 @@ could be set to non-string values or even deleted. We want to make sure that these attributes always contain strings. +.. literalinclude:: ../includes/noddy3.c -.. include:: ../includes/noddy3.c - :literal: To provide greater control, over the :attr:`first` and :attr:`last` attributes, we'll use custom getter and setter functions. Here are the functions for @@ -708,9 +705,8 @@ collection, types need to fill two slots and set a class flag that enables these slots: +.. literalinclude:: ../includes/noddy4.c -.. include:: ../includes/noddy4.c - :literal: The traversal method provides access to subobjects that could participate in cycles:: @@ -839,9 +835,8 @@ >>> print s.increment() 2 +.. literalinclude:: ../includes/shoddy.c -.. include:: ../includes/shoddy.c - :literal: As you can see, the source code closely resembles the :class:`Noddy` examples in previous sections. We will break down the main differences between them. :: @@ -917,9 +912,8 @@ Here is the definition of :ctype:`PyTypeObject`, with some fields only used in debug builds omitted: +.. literalinclude:: ../includes/typestruct.h -.. include:: ../includes/typestruct.h - :literal: Now that's a *lot* of methods. Don't worry too much though - if you have a type you want to define, the chances are very good that you will only implement a Modified: doctools/trunk/Doc-3k/library/datetime.rst ============================================================================== --- doctools/trunk/Doc-3k/library/datetime.rst (original) +++ doctools/trunk/Doc-3k/library/datetime.rst Fri Aug 3 09:32:31 2007 @@ -1253,9 +1253,8 @@ Example :class:`tzinfo` classes: +.. literalinclude:: ../includes/tzinfo-examples.py -.. include:: ../includes/tzinfo-examples.py - :literal: Note that there are unavoidable subtleties twice per year in a :class:`tzinfo` subclass accounting for both standard and daylight time, at the DST transition Modified: doctools/trunk/Doc-3k/library/email-examples.rst ============================================================================== --- doctools/trunk/Doc-3k/library/email-examples.rst (original) +++ doctools/trunk/Doc-3k/library/email-examples.rst Fri Aug 3 09:32:31 2007 @@ -6,33 +6,28 @@ First, let's see how to create and send a simple text message: +.. literalinclude:: ../includes/email-simple.py -.. include:: ../includes/email-simple.py - :literal: Here's an example of how to send a MIME message containing a bunch of family pictures that may be residing in a directory: +.. literalinclude:: ../includes/email-mime.py -.. include:: ../includes/email-mime.py - :literal: Here's an example of how to send the entire contents of a directory as an email -message: [#]_ +message: [1]_ +.. literalinclude:: ../includes/email-dir.py -.. include:: ../includes/email-dir.py - :literal: And finally, here's an example of how to unpack a MIME message like the one above, into a directory of files: - -.. include:: ../includes/email-unpack.py - :literal: +.. literalinclude:: ../includes/email-unpack.py .. rubric:: Footnotes -.. [#] Thanks to Matthew Dixon Cowles for the original inspiration and examples. +.. [1] Thanks to Matthew Dixon Cowles for the original inspiration and examples. Modified: doctools/trunk/Doc-3k/library/exceptions.rst ============================================================================== --- doctools/trunk/Doc-3k/library/exceptions.rst (original) +++ doctools/trunk/Doc-3k/library/exceptions.rst Fri Aug 3 09:32:31 2007 @@ -472,4 +472,4 @@ The class hierarchy for built-in exceptions is: -.. XXX includefile ../../Lib/test/exception_hierarchy.txt +.. literalinclude:: ../../Lib/test/exception_hierarchy.txt Modified: doctools/trunk/Doc-3k/library/sqlite3.rst ============================================================================== --- doctools/trunk/Doc-3k/library/sqlite3.rst (original) +++ doctools/trunk/Doc-3k/library/sqlite3.rst Fri Aug 3 09:32:31 2007 @@ -200,8 +200,7 @@ This can be used to build a shell for SQLite, as in the following example: - .. include:: ../includes/sqlite3/complete_statement.py - :literal: + .. literalinclude:: ../includes/sqlite3/complete_statement.py .. function:: enable_callback_tracebacks(flag) @@ -267,9 +266,7 @@ Example: - - .. include:: ../includes/sqlite3/md5func.py - :literal: + .. literalinclude:: ../includes/sqlite3/md5func.py .. method:: Connection.create_aggregate(name, num_params, aggregate_class) @@ -285,9 +282,7 @@ Example: - - .. include:: ../includes/sqlite3/mysumaggr.py - :literal: + .. literalinclude:: ../includes/sqlite3/mysumaggr.py .. method:: Connection.create_collation(name, callable) @@ -303,9 +298,7 @@ The following example shows a custom collation that sorts "the wrong way": - - .. include:: ../includes/sqlite3/collation_reverse.py - :literal: + .. literalinclude:: ../includes/sqlite3/collation_reverse.py To remove a collation, call ``create_collation`` with None as callable:: @@ -349,9 +342,7 @@ Example: - - .. include:: ../includes/sqlite3/row_factory.py - :literal: + .. literalinclude:: ../includes/sqlite3/row_factory.py If returning a tuple doesn't suffice and you want name-based access to columns, you should consider setting :attr:`row_factory` to the highly-optimized @@ -379,9 +370,7 @@ See the following example code for illustration: - - .. include:: ../includes/sqlite3/text_factory.py - :literal: + .. literalinclude:: ../includes/sqlite3/text_factory.py .. attribute:: Connection.total_changes @@ -407,15 +396,11 @@ This example shows how to use parameters with qmark style: - - .. include:: ../includes/sqlite3/execute_1.py - :literal: + .. literalinclude:: ../includes/sqlite3/execute_1.py This example shows how to use the named style: - - .. include:: ../includes/sqlite3/execute_2.py - :literal: + .. literalinclude:: ../includes/sqlite3/execute_2.py :meth:`execute` will only execute a single SQL statement. If you try to execute more than one statement with it, it will raise a Warning. Use @@ -429,15 +414,11 @@ sequence *sql*. The :mod:`sqlite3` module also allows using an iterator yielding parameters instead of a sequence. - - .. include:: ../includes/sqlite3/executemany_1.py - :literal: + .. literalinclude:: ../includes/sqlite3/executemany_1.py Here's a shorter example using a generator: - - .. include:: ../includes/sqlite3/executemany_2.py - :literal: + .. literalinclude:: ../includes/sqlite3/executemany_2.py .. method:: Cursor.executescript(sql_script) @@ -450,9 +431,7 @@ Example: - - .. include:: ../includes/sqlite3/executescript.py - :literal: + .. literalinclude:: ../includes/sqlite3/executescript.py .. attribute:: Cursor.rowcount @@ -559,9 +538,7 @@ to give your class a method ``__conform__(self, protocol)`` which must return the converted value. The parameter *protocol* will be :class:`PrepareProtocol`. - -.. include:: ../includes/sqlite3/adapter_point_1.py - :literal: +.. literalinclude:: ../includes/sqlite3/adapter_point_1.py Registering an adapter callable @@ -575,18 +552,14 @@ The type/class to adapt must be a new-style class, i. e. it must have :class:`object` as one of its bases. - -.. include:: ../includes/sqlite3/adapter_point_2.py - :literal: +.. literalinclude:: ../includes/sqlite3/adapter_point_2.py The :mod:`sqlite3` module has two default adapters for Python's built-in :class:`datetime.date` and :class:`datetime.datetime` types. Now let's suppose we want to store :class:`datetime.datetime` objects not in ISO representation, but as a Unix timestamp. - -.. include:: ../includes/sqlite3/adapter_datetime.py - :literal: +.. literalinclude:: ../includes/sqlite3/adapter_datetime.py Converting SQLite values to custom Python types @@ -630,9 +603,7 @@ The following example illustrates both approaches. - -.. include:: ../includes/sqlite3/converter_point.py - :literal: +.. literalinclude:: ../includes/sqlite3/converter_point.py Default adapters and converters @@ -651,9 +622,7 @@ The following example demonstrates this. - -.. include:: ../includes/sqlite3/pysqlite_datetime.py - :literal: +.. literalinclude:: ../includes/sqlite3/pysqlite_datetime.py .. _sqlite3-controlling-transactions: @@ -704,9 +673,7 @@ objects. This way, you can execute a SELECT statement and iterate over it directly using only a single call on the :class:`Connection` object. - -.. include:: ../includes/sqlite3/shortcut_methods.py - :literal: +.. literalinclude:: ../includes/sqlite3/shortcut_methods.py Accessing columns by name instead of by index @@ -718,7 +685,5 @@ Rows wrapped with this class can be accessed both by index (like tuples) and case-insensitively by name: - -.. include:: ../includes/sqlite3/rowclass.py - :literal: +.. literalinclude:: ../includes/sqlite3/rowclass.py Modified: doctools/trunk/Doc-3k/library/xml.dom.minidom.rst ============================================================================== --- doctools/trunk/Doc-3k/library/xml.dom.minidom.rst (original) +++ doctools/trunk/Doc-3k/library/xml.dom.minidom.rst Fri Aug 3 09:32:31 2007 @@ -193,9 +193,7 @@ This example program is a fairly realistic example of a simple program. In this particular case, we do not take much advantage of the flexibility of the DOM. - -.. include:: ../includes/minidom-example.py - :literal: +.. literalinclude:: ../includes/minidom-example.py .. _minidom-and-dom: Modified: doctools/trunk/sphinx/directives.py ============================================================================== --- doctools/trunk/sphinx/directives.py (original) +++ doctools/trunk/sphinx/directives.py Fri Aug 3 09:32:31 2007 @@ -8,6 +8,7 @@ :copyright: 2007 by Georg Brandl. :license: Python license. """ +from __future__ import with_statement import re import string @@ -531,5 +532,33 @@ highlightlang_directive.content = 0 highlightlang_directive.arguments = (1, 0, 0) -directives.register_directive('highlightlang', - highlightlang_directive) +directives.register_directive('highlightlang', highlightlang_directive) + + +# ------ literalinclude directive --------------------------------------------------- + +def literalinclude_directive(name, arguments, options, content, lineno, + content_offset, block_text, state, state_machine): + """Like .. include:: :literal:, but only warns if the include file is not found.""" + if not state.document.settings.file_insertion_enabled: + return [state.document.reporter.warning('File insertion disabled', line=lineno)] + env = state.document.settings.env + fn = arguments[0] + source_dir = path.dirname(path.abspath(state_machine.input_lines.source( + lineno - state_machine.input_offset - 1))) + fn = path.normpath(path.join(source_dir, fn)) + + try: + with open(fn) as f: + text = f.read() + except (IOError, OSError): + retnode = state.document.reporter.warning('Include file %r not found' % + arguments[0], line=lineno) + else: + retnode = nodes.literal_block(text, text, source=fn) + retnode.line = 1 + return [retnode] + +literalinclude_directive.content = 0 +literalinclude_directive.arguments = (1, 0, 0) +directives.register_directive('literalinclude', literalinclude_directive) From python-checkins at python.org Fri Aug 3 09:35:20 2007 From: python-checkins at python.org (georg.brandl) Date: Fri, 3 Aug 2007 09:35:20 +0200 (CEST) Subject: [Python-checkins] r56691 - in doctools/trunk: Doc-26/library/_ast.rst Doc-26/library/ast.rst Doc-26/library/compiler.rst Doc-3k/library/_ast.rst Doc-3k/library/language.rst Message-ID: <20070803073520.4DFC01E4005@bag.python.org> Author: georg.brandl Date: Fri Aug 3 09:35:19 2007 New Revision: 56691 Added: doctools/trunk/Doc-26/library/_ast.rst - copied, changed from r56690, doctools/trunk/Doc-26/library/ast.rst doctools/trunk/Doc-3k/library/_ast.rst Removed: doctools/trunk/Doc-26/library/ast.rst Modified: doctools/trunk/Doc-26/library/compiler.rst doctools/trunk/Doc-3k/library/language.rst Log: Re-add the _ast docs to 3k; rename it accordingly. Copied: doctools/trunk/Doc-26/library/_ast.rst (from r56690, doctools/trunk/Doc-26/library/ast.rst) ============================================================================== --- doctools/trunk/Doc-26/library/ast.rst (original) +++ doctools/trunk/Doc-26/library/_ast.rst Fri Aug 3 09:35:19 2007 @@ -4,6 +4,7 @@ ===================== .. module:: _ast + :synopsis: Abstract Syntax Tree classes. .. sectionauthor:: Martin v. L?wis Deleted: /doctools/trunk/Doc-26/library/ast.rst ============================================================================== --- /doctools/trunk/Doc-26/library/ast.rst Fri Aug 3 09:35:19 2007 +++ (empty file) @@ -1,58 +0,0 @@ -.. _ast: - -Abstract Syntax Trees -===================== - -.. module:: _ast - -.. sectionauthor:: Martin v. L?wis - - -.. versionadded:: 2.5 - -The ``_ast`` module helps Python applications to process trees of the Python -abstract syntax grammar. The Python compiler currently provides read-only access -to such trees, meaning that applications can only create a tree for a given -piece of Python source code; generating byte code from a (potentially modified) -tree is not supported. The abstract syntax itself might change with each Python -release; this module helps to find out programmatically what the current grammar -looks like. - -An abstract syntax tree can be generated by passing ``_ast.PyCF_ONLY_AST`` as a -flag to the :func:`compile` builtin function. The result will be a tree of -objects whose classes all inherit from ``_ast.AST``. - -The actual classes are derived from the ``Parser/Python.asdl`` file, which is -reproduced below. There is one class defined for each left-hand side symbol in -the abstract grammar (for example, ``_ast.stmt`` or ``_ast.expr``). In addition, -there is one class defined for each constructor on the right-hand side; these -classes inherit from the classes for the left-hand side trees. For example, -``_ast.BinOp`` inherits from ``_ast.expr``. For production rules with -alternatives (aka "sums"), the left-hand side class is abstract: only instances -of specific constructor nodes are ever created. - -Each concrete class has an attribute ``_fields`` which gives the names of all -child nodes. - -Each instance of a concrete class has one attribute for each child node, of the -type as defined in the grammar. For example, ``_ast.BinOp`` instances have an -attribute ``left`` of type ``_ast.expr``. Instances of ``_ast.expr`` and -``_ast.stmt`` subclasses also have lineno and col_offset attributes. The lineno -is the line number of source text (1 indexed so the first line is line 1) and -the col_offset is the utf8 byte offset of the first token that generated the -node. The utf8 offset is recorded because the parser uses utf8 internally. - -If these attributes are marked as optional in the grammar (using a question -mark), the value might be ``None``. If the attributes can have zero-or-more -values (marked with an asterisk), the values are represented as Python lists. - - -Abstract Grammar ----------------- - -The module defines a string constant ``__version__`` which is the decimal -subversion revision number of the file shown below. - -The abstract grammar is currently defined as follows: - -.. literalinclude:: ../../Parser/Python.asdl Modified: doctools/trunk/Doc-26/library/compiler.rst ============================================================================== --- doctools/trunk/Doc-26/library/compiler.rst (original) +++ doctools/trunk/Doc-26/library/compiler.rst Fri Aug 3 09:35:19 2007 @@ -30,15 +30,16 @@ The following modules are part of the :mod:`compiler` package: - .. toctree:: - ast.rst + _ast.rst + The basic interface =================== .. module:: compiler + :synopsis: Python code compiler written in Python. The top-level of the package defines four functions. If you import Added: doctools/trunk/Doc-3k/library/_ast.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-3k/library/_ast.rst Fri Aug 3 09:35:19 2007 @@ -0,0 +1,59 @@ +.. _ast: + +Abstract Syntax Trees +===================== + +.. module:: _ast + :synopsis: Abstract Syntax Tree classes. + +.. sectionauthor:: Martin v. L?wis + + +.. versionadded:: 2.5 + +The ``_ast`` module helps Python applications to process trees of the Python +abstract syntax grammar. The Python compiler currently provides read-only access +to such trees, meaning that applications can only create a tree for a given +piece of Python source code; generating byte code from a (potentially modified) +tree is not supported. The abstract syntax itself might change with each Python +release; this module helps to find out programmatically what the current grammar +looks like. + +An abstract syntax tree can be generated by passing ``_ast.PyCF_ONLY_AST`` as a +flag to the :func:`compile` builtin function. The result will be a tree of +objects whose classes all inherit from ``_ast.AST``. + +The actual classes are derived from the ``Parser/Python.asdl`` file, which is +reproduced below. There is one class defined for each left-hand side symbol in +the abstract grammar (for example, ``_ast.stmt`` or ``_ast.expr``). In addition, +there is one class defined for each constructor on the right-hand side; these +classes inherit from the classes for the left-hand side trees. For example, +``_ast.BinOp`` inherits from ``_ast.expr``. For production rules with +alternatives (aka "sums"), the left-hand side class is abstract: only instances +of specific constructor nodes are ever created. + +Each concrete class has an attribute ``_fields`` which gives the names of all +child nodes. + +Each instance of a concrete class has one attribute for each child node, of the +type as defined in the grammar. For example, ``_ast.BinOp`` instances have an +attribute ``left`` of type ``_ast.expr``. Instances of ``_ast.expr`` and +``_ast.stmt`` subclasses also have lineno and col_offset attributes. The lineno +is the line number of source text (1 indexed so the first line is line 1) and +the col_offset is the utf8 byte offset of the first token that generated the +node. The utf8 offset is recorded because the parser uses utf8 internally. + +If these attributes are marked as optional in the grammar (using a question +mark), the value might be ``None``. If the attributes can have zero-or-more +values (marked with an asterisk), the values are represented as Python lists. + + +Abstract Grammar +---------------- + +The module defines a string constant ``__version__`` which is the decimal +subversion revision number of the file shown below. + +The abstract grammar is currently defined as follows: + +.. literalinclude:: ../../Parser/Python.asdl Modified: doctools/trunk/Doc-3k/library/language.rst ============================================================================== --- doctools/trunk/Doc-3k/library/language.rst (original) +++ doctools/trunk/Doc-3k/library/language.rst Fri Aug 3 09:35:19 2007 @@ -15,6 +15,7 @@ .. toctree:: parser.rst + _ast.rst symbol.rst token.rst keyword.rst From python-checkins at python.org Fri Aug 3 09:40:37 2007 From: python-checkins at python.org (georg.brandl) Date: Fri, 3 Aug 2007 09:40:37 +0200 (CEST) Subject: [Python-checkins] r56692 - in doctools/trunk/sphinx: templates/modindex.html web/application.py Message-ID: <20070803074037.37FA61E4005@bag.python.org> Author: georg.brandl Date: Fri Aug 3 09:40:36 2007 New Revision: 56692 Modified: doctools/trunk/sphinx/templates/modindex.html doctools/trunk/sphinx/web/application.py Log: Fix the modindex checkboxes if none is selected. Modified: doctools/trunk/sphinx/templates/modindex.html ============================================================================== --- doctools/trunk/sphinx/templates/modindex.html (original) +++ doctools/trunk/sphinx/templates/modindex.html Fri Aug 3 09:40:36 2007 @@ -19,6 +19,7 @@ {%- if pl in showpf %} checked="checked"{% endif %}> {% endfor %} + {% endif %} Modified: doctools/trunk/sphinx/web/application.py ============================================================================== --- doctools/trunk/sphinx/web/application.py (original) +++ doctools/trunk/sphinx/web/application.py Fri Aug 3 09:40:36 2007 @@ -348,7 +348,7 @@ } for x in sorted(most_frequent)] showpf = None - newpf = req.args.get('pf') + newpf = req.args.get('newpf') sesspf = req.session.get('pf') if newpf or sesspf: yield NoCache From python-checkins at python.org Fri Aug 3 09:46:12 2007 From: python-checkins at python.org (georg.brandl) Date: Fri, 3 Aug 2007 09:46:12 +0200 (CEST) Subject: [Python-checkins] r56693 - in doctools/trunk: Doc-26/c-api/newtypes.rst Doc-26/distutils/configfile.rst Doc-26/extending/embedding.rst Doc-26/tutorial/introduction.rst Doc-26/whatsnew/2.3.rst Doc-26/whatsnew/2.5.rst Doc-3k/c-api/newtypes.rst Doc-3k/distutils/configfile.rst Doc-3k/extending/embedding.rst Doc-3k/tutorial/introduction.rst Doc-3k/whatsnew/2.3.rst Doc-3k/whatsnew/2.5.rst Message-ID: <20070803074612.BC9DF1E4005@bag.python.org> Author: georg.brandl Date: Fri Aug 3 09:46:12 2007 New Revision: 56693 Modified: doctools/trunk/Doc-26/c-api/newtypes.rst doctools/trunk/Doc-26/distutils/configfile.rst doctools/trunk/Doc-26/extending/embedding.rst doctools/trunk/Doc-26/tutorial/introduction.rst doctools/trunk/Doc-26/whatsnew/2.3.rst doctools/trunk/Doc-26/whatsnew/2.5.rst doctools/trunk/Doc-3k/c-api/newtypes.rst doctools/trunk/Doc-3k/distutils/configfile.rst doctools/trunk/Doc-3k/extending/embedding.rst doctools/trunk/Doc-3k/tutorial/introduction.rst doctools/trunk/Doc-3k/whatsnew/2.3.rst doctools/trunk/Doc-3k/whatsnew/2.5.rst Log: Fix remaining references to "../foo" HTML pages. Modified: doctools/trunk/Doc-26/c-api/newtypes.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/newtypes.rst (original) +++ doctools/trunk/Doc-26/c-api/newtypes.rst Fri Aug 3 09:46:12 2007 @@ -1599,7 +1599,7 @@ or strings), do not need to provide any explicit support for garbage collection. .. An example showing the use of these interfaces can be found in "Supporting the -.. Cycle Collector (XXX reference: ../ext/example-cycle-support.html)". +.. Cycle Collector (XXX not found: ../ext/example-cycle-support.html)". To create a container type, the :attr:`tp_flags` field of the type object must include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the Modified: doctools/trunk/Doc-26/distutils/configfile.rst ============================================================================== --- doctools/trunk/Doc-26/distutils/configfile.rst (original) +++ doctools/trunk/Doc-26/distutils/configfile.rst Fri Aug 3 09:46:12 2007 @@ -118,7 +118,7 @@ .. seealso:: - `Installing Python Modules <../inst/config-syntax.html>`_ + :ref:`inst-config-syntax` in "Installing Python Modules" More information on the configuration files is available in the manual for system administrators. Modified: doctools/trunk/Doc-26/extending/embedding.rst ============================================================================== --- doctools/trunk/Doc-26/extending/embedding.rst (original) +++ doctools/trunk/Doc-26/extending/embedding.rst Fri Aug 3 09:46:12 2007 @@ -42,7 +42,7 @@ .. seealso:: - `Python/C API Reference Manual <../api/api.html>`_ + :ref:`c-api-index` The details of Python's C interface are given in this manual. A great deal of necessary information can be found here. Modified: doctools/trunk/Doc-26/tutorial/introduction.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/introduction.rst (original) +++ doctools/trunk/Doc-26/tutorial/introduction.rst Fri Aug 3 09:46:12 2007 @@ -370,17 +370,18 @@ .. seealso:: - `Sequence Types <../lib/typesseq.html>`_ - Strings, and the Unicode strings described in the next section, are examples of - *sequence types*, and support the common operations supported by such types. - - `String Methods <../lib/string-methods.html>`_ - Both strings and Unicode strings support a large number of methods for basic - transformations and searching. - - `String Formatting Operations <../lib/typesseq-strings.html>`_ - The formatting operations invoked when strings and Unicode strings are the left - operand of the ``%`` operator are described in more detail here. + :ref:`typesseq` + Strings, and the Unicode strings described in the next section, are + examples of *sequence types*, and support the common operations supported + by such types. + + :ref:`string-methods` + Both strings and Unicode strings support a large number of methods for + basic transformations and searching. + + :ref:`typesseq-strings` + The formatting operations invoked when strings and Unicode strings are the + left operand of the ``%`` operator are described in more detail here. .. _tut-unicodestrings: Modified: doctools/trunk/Doc-26/whatsnew/2.3.rst ============================================================================== --- doctools/trunk/Doc-26/whatsnew/2.3.rst (original) +++ doctools/trunk/Doc-26/whatsnew/2.3.rst Fri Aug 3 09:46:12 2007 @@ -528,8 +528,7 @@ With all of these features the :mod:`logging` package should provide enough flexibility for even the most complicated applications. This is only an incomplete overview of its features, so please see the package's reference -documentation (XXX reference: ../lib/module-logging.html) for all of the -details. Reading :pep:`282` will also be helpful. +documentation for all of the details. Reading :pep:`282` will also be helpful. .. seealso:: Modified: doctools/trunk/Doc-26/whatsnew/2.5.rst ============================================================================== --- doctools/trunk/Doc-26/whatsnew/2.5.rst (original) +++ doctools/trunk/Doc-26/whatsnew/2.5.rst Fri Aug 3 09:46:12 2007 @@ -801,8 +801,7 @@ ':keyword:`with`' statement, which can be helpful in learning how the statement works. - ../lib/module-contextlib.html - The documentation for the :mod:`contextlib` module. + The documentation for the :mod:`contextlib` module. .. % ====================================================================== @@ -1745,8 +1744,7 @@ http://starship.python.net/crew/theller/ctypes/ The ctypes web page, with a tutorial, reference, and FAQ. - ../lib/module-ctypes.html - The documentation for the :mod:`ctypes` module. + The documentation for the :mod:`ctypes` module. .. % ====================================================================== @@ -1917,8 +1915,7 @@ .. seealso:: - ../lib/module-hashlib.html - The documentation for the :mod:`hashlib` module. + The documentation for the :mod:`hashlib` module. .. % ====================================================================== @@ -2024,8 +2021,7 @@ The SQLite web page; the documentation describes the syntax and the available data types for the supported SQL dialect. - ../lib/module-sqlite3.html - The documentation for the :mod:`sqlite3` module. + The documentation for the :mod:`sqlite3` module. :pep:`249` - Database API Specification 2.0 PEP written by Marc-Andr? Lemburg. Modified: doctools/trunk/Doc-3k/c-api/newtypes.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/newtypes.rst (original) +++ doctools/trunk/Doc-3k/c-api/newtypes.rst Fri Aug 3 09:46:12 2007 @@ -1599,7 +1599,7 @@ or strings), do not need to provide any explicit support for garbage collection. .. An example showing the use of these interfaces can be found in "Supporting the -.. Cycle Collector (XXX reference: ../ext/example-cycle-support.html)". +.. Cycle Collector (XXX not found: ../ext/example-cycle-support.html)". To create a container type, the :attr:`tp_flags` field of the type object must include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the Modified: doctools/trunk/Doc-3k/distutils/configfile.rst ============================================================================== --- doctools/trunk/Doc-3k/distutils/configfile.rst (original) +++ doctools/trunk/Doc-3k/distutils/configfile.rst Fri Aug 3 09:46:12 2007 @@ -118,7 +118,7 @@ .. seealso:: - `Installing Python Modules <../inst/config-syntax.html>`_ + :ref:`inst-config-syntax` in "Installing Python Modules" More information on the configuration files is available in the manual for system administrators. Modified: doctools/trunk/Doc-3k/extending/embedding.rst ============================================================================== --- doctools/trunk/Doc-3k/extending/embedding.rst (original) +++ doctools/trunk/Doc-3k/extending/embedding.rst Fri Aug 3 09:46:12 2007 @@ -42,7 +42,7 @@ .. seealso:: - `Python/C API Reference Manual <../api/api.html>`_ + :ref:`c-api-index` The details of Python's C interface are given in this manual. A great deal of necessary information can be found here. Modified: doctools/trunk/Doc-3k/tutorial/introduction.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/introduction.rst (original) +++ doctools/trunk/Doc-3k/tutorial/introduction.rst Fri Aug 3 09:46:12 2007 @@ -370,17 +370,18 @@ .. seealso:: - `Sequence Types <../lib/typesseq.html>`_ - Strings, and the Unicode strings described in the next section, are examples of - *sequence types*, and support the common operations supported by such types. - - `String Methods <../lib/string-methods.html>`_ - Both strings and Unicode strings support a large number of methods for basic - transformations and searching. - - `String Formatting Operations <../lib/typesseq-strings.html>`_ - The formatting operations invoked when strings and Unicode strings are the left - operand of the ``%`` operator are described in more detail here. + :ref:`typesseq` + Strings, and the Unicode strings described in the next section, are + examples of *sequence types*, and support the common operations supported + by such types. + + :ref:`string-methods` + Both strings and Unicode strings support a large number of methods for + basic transformations and searching. + + :ref:`typesseq-strings` + The formatting operations invoked when strings and Unicode strings are the + left operand of the ``%`` operator are described in more detail here. .. _tut-unicodestrings: Modified: doctools/trunk/Doc-3k/whatsnew/2.3.rst ============================================================================== --- doctools/trunk/Doc-3k/whatsnew/2.3.rst (original) +++ doctools/trunk/Doc-3k/whatsnew/2.3.rst Fri Aug 3 09:46:12 2007 @@ -528,8 +528,7 @@ With all of these features the :mod:`logging` package should provide enough flexibility for even the most complicated applications. This is only an incomplete overview of its features, so please see the package's reference -documentation (XXX reference: ../lib/module-logging.html) for all of the -details. Reading :pep:`282` will also be helpful. +documentation for all of the details. Reading :pep:`282` will also be helpful. .. seealso:: Modified: doctools/trunk/Doc-3k/whatsnew/2.5.rst ============================================================================== --- doctools/trunk/Doc-3k/whatsnew/2.5.rst (original) +++ doctools/trunk/Doc-3k/whatsnew/2.5.rst Fri Aug 3 09:46:12 2007 @@ -790,8 +790,7 @@ ':keyword:`with`' statement, which can be helpful in learning how the statement works. - ../lib/module-contextlib.html - The documentation for the :mod:`contextlib` module. + The documentation for the :mod:`contextlib` module. .. % ====================================================================== @@ -1734,8 +1733,7 @@ http://starship.python.net/crew/theller/ctypes/ The ctypes web page, with a tutorial, reference, and FAQ. - ../lib/module-ctypes.html - The documentation for the :mod:`ctypes` module. + The documentation for the :mod:`ctypes` module. .. % ====================================================================== @@ -1906,8 +1904,7 @@ .. seealso:: - ../lib/module-hashlib.html - The documentation for the :mod:`hashlib` module. + The documentation for the :mod:`hashlib` module. .. % ====================================================================== @@ -2013,8 +2010,7 @@ The SQLite web page; the documentation describes the syntax and the available data types for the supported SQL dialect. - ../lib/module-sqlite3.html - The documentation for the :mod:`sqlite3` module. + The documentation for the :mod:`sqlite3` module. :pep:`249` - Database API Specification 2.0 PEP written by Marc-Andr? Lemburg. From python-checkins at python.org Fri Aug 3 10:15:50 2007 From: python-checkins at python.org (georg.brandl) Date: Fri, 3 Aug 2007 10:15:50 +0200 (CEST) Subject: [Python-checkins] r56694 - in doctools/trunk: Doc-26/ACKS Doc-26/documenting/rest.rst Doc-3k/ACKS Doc-3k/documenting/rest.rst sphinx/environment.py Message-ID: <20070803081550.7823D1E400F@bag.python.org> Author: georg.brandl Date: Fri Aug 3 10:15:50 2007 New Revision: 56694 Modified: doctools/trunk/Doc-26/ACKS doctools/trunk/Doc-26/documenting/rest.rst doctools/trunk/Doc-3k/ACKS doctools/trunk/Doc-3k/documenting/rest.rst doctools/trunk/sphinx/environment.py Log: Disable enumerated lists introduced by alphabetic or roman numerals. Modified: doctools/trunk/Doc-26/ACKS ============================================================================== --- doctools/trunk/Doc-26/ACKS (original) +++ doctools/trunk/Doc-26/ACKS Fri Aug 3 10:15:50 2007 @@ -15,7 +15,7 @@ * Steve Alexander * Jim Ahlstrom * Fred Allen -* \A. Amoroso +* A. Amoroso * Pehr Anderson * Oliver Andrich * Jes?s Cea Avi?n @@ -40,7 +40,7 @@ * Jeremy Craven * Andrew Dalke * Ben Darnell -* \L. Peter Deutsch +* L. Peter Deutsch * Robert Donohue * Fred L. Drake, Jr. * Jeff Epler Modified: doctools/trunk/Doc-26/documenting/rest.rst ============================================================================== --- doctools/trunk/Doc-26/documenting/rest.rst (original) +++ doctools/trunk/Doc-26/documenting/rest.rst Fri Aug 3 10:15:50 2007 @@ -63,9 +63,19 @@ * It has two items, the second item uses two lines. + 1. This is a numbered list. + 2. It has two items too. + #. This is a numbered list. #. It has two items too. +Note that Sphinx disables the use of enumerated lists introduced by alphabetic +or roman numerals, such as :: + + A. First item + B. Second item + + Nested lists are possible, but be aware that they must be separated from the parent list items by blank lines:: @@ -210,12 +220,14 @@ .. [#] Text of the first footnote. .. [#] Text of the second footnote. +You can also explicitly number the footnotes for better context. + Comments -------- Every explicit markup block which isn't a valid markup construct (like the -footnotes above) is regared as a comment. +footnotes above) is regarded as a comment. Source encoding @@ -229,4 +241,13 @@ documents written from them will be in that encoding as well. -XXX: Gotchas +Gotchas +------- + +There are some problems one commonly runs into while authoring reST documents: + +* **Separation of inline markup:** As said above, inline markup spans must be + separated from the surrounding text by non-word characters, you have to use + an escaped space to get around that. + +.. XXX more? \ No newline at end of file Modified: doctools/trunk/Doc-3k/ACKS ============================================================================== --- doctools/trunk/Doc-3k/ACKS (original) +++ doctools/trunk/Doc-3k/ACKS Fri Aug 3 10:15:50 2007 @@ -15,7 +15,7 @@ * Steve Alexander * Jim Ahlstrom * Fred Allen -* \A. Amoroso +* A. Amoroso * Pehr Anderson * Oliver Andrich * Jes?s Cea Avi?n @@ -40,7 +40,7 @@ * Jeremy Craven * Andrew Dalke * Ben Darnell -* \L. Peter Deutsch +* L. Peter Deutsch * Robert Donohue * Fred L. Drake, Jr. * Jeff Epler Modified: doctools/trunk/Doc-3k/documenting/rest.rst ============================================================================== --- doctools/trunk/Doc-3k/documenting/rest.rst (original) +++ doctools/trunk/Doc-3k/documenting/rest.rst Fri Aug 3 10:15:50 2007 @@ -63,9 +63,19 @@ * It has two items, the second item uses two lines. + 1. This is a numbered list. + 2. It has two items too. + #. This is a numbered list. #. It has two items too. +Note that Sphinx disables the use of enumerated lists introduced by alphabetic +or roman numerals, such as :: + + A. First item + B. Second item + + Nested lists are possible, but be aware that they must be separated from the parent list items by blank lines:: @@ -210,12 +220,14 @@ .. [#] Text of the first footnote. .. [#] Text of the second footnote. +You can also explicitly number the footnotes for better context. + Comments -------- Every explicit markup block which isn't a valid markup construct (like the -footnotes above) is regared as a comment. +footnotes above) is regarded as a comment. Source encoding @@ -229,4 +241,13 @@ documents written from them will be in that encoding as well. -XXX: Gotchas +Gotchas +------- + +There are some problems one commonly runs into while authoring reST documents: + +* **Separation of inline markup:** As said above, inline markup spans must be + separated from the surrounding text by non-word characters, you have to use + an escaped space to get around that. + +.. XXX more? \ No newline at end of file Modified: doctools/trunk/sphinx/environment.py ============================================================================== --- doctools/trunk/sphinx/environment.py (original) +++ doctools/trunk/sphinx/environment.py Fri Aug 3 10:15:50 2007 @@ -30,6 +30,13 @@ from docutils.transforms.parts import ContentsFilter from docutils.transforms.universal import FilterMessages +# monkey-patch reST parser to disable alphabetic and roman enumerated lists +from docutils.parsers.rst.states import Body +Body.enum.converters['loweralpha'] = \ + Body.enum.converters['upperalpha'] = \ + Body.enum.converters['lowerroman'] = \ + Body.enum.converters['upperroman'] = lambda x: None + from . import addnodes from .util import get_matching_files from .refcounting import Refcounts From python-checkins at python.org Fri Aug 3 11:09:19 2007 From: python-checkins at python.org (mark.summerfield) Date: Fri, 3 Aug 2007 11:09:19 +0200 (CEST) Subject: [Python-checkins] r56695 - doctools/trunk/Doc-26/library/index.rst Message-ID: <20070803090919.26AF11E4008@bag.python.org> Author: mark.summerfield Date: Fri Aug 3 11:09:18 2007 New Revision: 56695 Modified: doctools/trunk/Doc-26/library/index.rst Log: Made the intro text more positive in tone. Noted that Win & Mac installers normally include the whole library but that Unix users may need to add packages. Added a link to pypy. Modified: doctools/trunk/Doc-26/library/index.rst ============================================================================== --- doctools/trunk/Doc-26/library/index.rst (original) +++ doctools/trunk/Doc-26/library/index.rst Fri Aug 3 11:09:18 2007 @@ -1,28 +1,38 @@ .. _library-index: ############################### - The Python standard library + The Python Standard Library ############################### :Release: |version| :Date: |today| -While :ref:`reference-index` describes the exact syntax and semantics of the -language, it does not describe the standard library that is distributed with the -language, and which greatly enhances its immediate usability. This library -contains built-in modules (written in C) that provide access to system -functionality such as file I/O that would otherwise be inaccessible to Python -programmers, as well as modules written in Python that provide standardized -solutions for many problems that occur in everyday programming. Some of these -modules are explicitly designed to encourage and enhance the portability of -Python programs. - -This library reference manual documents Python's standard library, as well as -many optional library modules (which may or may not be available, depending on -whether the underlying platform supports them and on the configuration choices -made at compile time). It also documents the standard types of the language and -its built-in functions and exceptions, many of which are not or incompletely -documented in the Reference Manual. +While the :ref:`reference-index` describes the exact syntax and +semantics of the Python language, this library reference manual +describes the standard library that is distributed with Python. It also +describes some of the optional components that are commonly included +in Python distributions. + +Python's standard library is very extensive, offering a wide range of +facilities as indicated by the long table of contents listed below. The +library contains built-in modules (written in C) that provide access to +system functionality such as file I/O that would otherwise be +inaccessible to Python programmers, as well as modules written in Python +that provide standardized solutions for many problems that occur in +everyday programming. Some of these modules are explicitly designed to +encourage and enhance the portability of Python programs by abstracting +away platform-specifics into platform-neutral APIs. + +The Python installers for the Windows and Mac platforms usually include +the entire standard library and often also include many additional +components. For Unix-like operating systems Python is normally provided +as a collection of packages, so it may be necessary to use the packaging +tools provided with the operating system to obtain some or all of the +optional components. + +In addition to the standard library, there is a growing collection of +over 2500 additional components available from the `Python Package Index +`_. .. toctree:: From python-checkins at python.org Fri Aug 3 12:31:22 2007 From: python-checkins at python.org (mark.summerfield) Date: Fri, 3 Aug 2007 12:31:22 +0200 (CEST) Subject: [Python-checkins] r56696 - doctools/trunk/Doc-26/library/functions.rst Message-ID: <20070803103122.C6E321E4007@bag.python.org> Author: mark.summerfield Date: Fri Aug 3 12:31:21 2007 New Revision: 56696 Modified: doctools/trunk/Doc-26/library/functions.rst Log: Added a few cross-references and a few more links. Added a note that __import__ is "advanced" since that's the first function that appears and looks scary for newcomers. Added an example for enumerate since I don't think it is immediately obvious how it works. Modified: doctools/trunk/Doc-26/library/functions.rst ============================================================================== --- doctools/trunk/Doc-26/library/functions.rst (original) +++ doctools/trunk/Doc-26/library/functions.rst Fri Aug 3 12:31:21 2007 @@ -16,7 +16,12 @@ module: rexec module: imp - This function is invoked by the :keyword:`import` statement. It mainly exists + .. note:: + + This is an advanced function that is not needed in everyday Python + programming. + + The function is invoked by the :keyword:`import` statement. It mainly exists so that you can replace it with another function that has a compatible interface, in order to change the semantics of the :keyword:`import` statement. For examples of why and how you would do this, see the standard library modules @@ -126,7 +131,8 @@ .. function:: callable(object) - Return true if the *object* argument appears callable, false if not. If this + Return :const:`True` if the *object* argument appears callable, + :const:`False` if not. If this returns true, it is still possible that a call fails, but if it is false, calling *object* will never succeed. Note that classes are callable (calling a class returns a new instance); class instances are callable if they have a @@ -138,7 +144,8 @@ Return a string of one character whose ASCII code is the integer *i*. For example, ``chr(97)`` returns the string ``'a'``. This is the inverse of :func:`ord`. The argument must be in the range [0..255], inclusive; - :exc:`ValueError` will be raised if *i* is outside that range. + :exc:`ValueError` will be raised if *i* is outside that range. See + also :func:`unichr`. .. function:: classmethod(function) @@ -346,7 +353,14 @@ returned by :func:`enumerate` returns a tuple containing a count (from zero) and the corresponding value obtained from iterating over *iterable*. :func:`enumerate` is useful for obtaining an indexed series: ``(0, seq[0])``, - ``(1, seq[1])``, ``(2, seq[2])``, .... + ``(1, seq[1])``, ``(2, seq[2])``, .... For example:: + + >>> for i, season in enumerate(['Spring', 'Summer', 'Fall', 'Winter')]: + >>> print i, season + 0 Spring + 1 Summer + 2 Fall + 3 Winter .. versionadded:: 2.3 @@ -1086,6 +1100,14 @@ acceptable to :func:`eval`; its goal is to return a printable string. If no argument is given, returns the empty string, ``''``. + For more information on strings see :ref:`typesseq` which describes + sequence functionality (strings are sequences), and also the + string-specific methods described in the :ref:`string-methods` + section. To output formatted strings use template strings or the + ``%`` operator described in the :ref:`typesseq-strings` section. In + addition see the :ref:`stringservices` section. See also + :func:`unicode`. + .. function:: sum(iterable[, start]) @@ -1166,7 +1188,8 @@ *i*. For example, ``unichr(97)`` returns the string ``u'a'``. This is the inverse of :func:`ord` for Unicode strings. The valid range for the argument depends how Python was configured -- it may be either UCS2 [0..0xFFFF] or UCS4 - [0..0x10FFFF]. :exc:`ValueError` is raised otherwise. + [0..0x10FFFF]. :exc:`ValueError` is raised otherwise. For ASCII and 8-bit + strings see :func:`chr`. .. versionadded:: 2.0 @@ -1196,6 +1219,14 @@ string version or representation is requested and then converted to a Unicode string using the codec for the default encoding in ``'strict'`` mode. + For more information on Unicode strings see :ref:`typesseq` which describes + sequence functionality (Unicode strings are sequences), and also the + string-specific methods described in the :ref:`string-methods` + section. To output formatted strings use template strings or the + ``%`` operator described in the :ref:`typesseq-strings` section. In + addition see the :ref:`stringservices` section. See also + :func:`str`. + .. versionadded:: 2.0 .. versionchanged:: 2.2 From python-checkins at python.org Fri Aug 3 12:52:06 2007 From: python-checkins at python.org (mark.summerfield) Date: Fri, 3 Aug 2007 12:52:06 +0200 (CEST) Subject: [Python-checkins] r56697 - doctools/trunk/Doc-26/library/stdtypes.rst Message-ID: <20070803105206.A6A811E4005@bag.python.org> Author: mark.summerfield Date: Fri Aug 3 12:52:05 2007 New Revision: 56697 Modified: doctools/trunk/Doc-26/library/stdtypes.rst Log: Addd a few cross-references. Clarified the short-circuit behavior of or and and. Modified: doctools/trunk/Doc-26/library/stdtypes.rst ============================================================================== --- doctools/trunk/Doc-26/library/stdtypes.rst (original) +++ doctools/trunk/Doc-26/library/stdtypes.rst Fri Aug 3 12:52:05 2007 @@ -12,8 +12,8 @@ Historically (until release 2.2), Python's built-in types have differed from user-defined types because it was not possible to use the built-in types as the - basis for object-oriented inheritance. This limitation does not exist any - longer. + basis for object-oriented inheritance. This limitation no longer + exists. .. index:: pair: built-in; types @@ -95,10 +95,10 @@ | ``x or y`` | if *x* is false, then *y*, else | \(1) | | | *x* | | +-------------+---------------------------------+-------+ -| ``x and y`` | if *x* is false, then *x*, else | \(1) | +| ``x and y`` | if *x* is false, then *x*, else | \(2) | | | *y* | | +-------------+---------------------------------+-------+ -| ``not x`` | if *x* is false, then ``True``, | \(2) | +| ``not x`` | if *x* is false, then ``True``, | \(3) | | | else ``False`` | | +-------------+---------------------------------+-------+ @@ -110,9 +110,14 @@ Notes: (1) - These only evaluate their second argument if needed for their outcome. + This is a short-circuit operator, so it only evaluates the second + argument if the first one is :const:`False`. (2) + This is a short-circuit operator, so it only evaluates the second + argument if the first one is :const:`True`. + +(3) ``not`` has a lower priority than non-Boolean operators, so ``not a == b`` is interpreted as ``not (a == b)``, and ``a == not b`` is a syntax error. @@ -147,8 +152,6 @@ +------------+-------------------------+-------+ | ``!=`` | not equal | \(1) | +------------+-------------------------+-------+ -| ``<>`` | not equal | \(1) | -+------------+-------------------------+-------+ | ``is`` | object identity | | +------------+-------------------------+-------+ | ``is not`` | negated object identity | | @@ -165,8 +168,9 @@ Notes: (1) - ``<>`` and ``!=`` are alternate spellings for the same operator. ``!=`` is the - preferred spelling; ``<>`` is obsolescent. + ``!=`` can also be written ``<>``, but this is an obsolete usage + kept for backwards compatibility only. New code should always use + ``!=``. .. index:: pair: object; numeric From python-checkins at python.org Fri Aug 3 13:22:32 2007 From: python-checkins at python.org (mark.summerfield) Date: Fri, 3 Aug 2007 13:22:32 +0200 (CEST) Subject: [Python-checkins] r56698 - doctools/trunk/Doc-26/library/stdtypes.rst Message-ID: <20070803112232.BE5CB1E4005@bag.python.org> Author: mark.summerfield Date: Fri Aug 3 13:22:32 2007 New Revision: 56698 Modified: doctools/trunk/Doc-26/library/stdtypes.rst Log: Added note and cross-reference to close sf bug 1760423. (But can't close the bug because I don't know how.) Modified: doctools/trunk/Doc-26/library/stdtypes.rst ============================================================================== --- doctools/trunk/Doc-26/library/stdtypes.rst (original) +++ doctools/trunk/Doc-26/library/stdtypes.rst Fri Aug 3 13:22:32 2007 @@ -562,6 +562,13 @@ | ``max(s)`` | largest item of *s* | | +------------------+--------------------------------+----------+ +Sequence types also support comparisons. In particular, tuples and lists +are compared lexicographically by comparing corresponding +elements. This means that to compare equal, every element must compare +equal and the two sequences must be of the same type and have the same +length. (For full details see :ref:`comparisons` in the language +reference.) + .. index:: triple: operations on; sequence; types builtin: len From python-checkins at python.org Fri Aug 3 13:33:04 2007 From: python-checkins at python.org (georg.brandl) Date: Fri, 3 Aug 2007 13:33:04 +0200 (CEST) Subject: [Python-checkins] r56699 - in doctools/trunk: Doc-26/library/functions.rst Doc-3k/library/functions.rst Doc-3k/library/index.rst Doc-3k/library/stdtypes.rst sphinx/web/application.py Message-ID: <20070803113304.3BA421E4005@bag.python.org> Author: georg.brandl Date: Fri Aug 3 13:33:03 2007 New Revision: 56699 Modified: doctools/trunk/Doc-26/library/functions.rst doctools/trunk/Doc-3k/library/functions.rst doctools/trunk/Doc-3k/library/index.rst doctools/trunk/Doc-3k/library/stdtypes.rst doctools/trunk/sphinx/web/application.py Log: Merge revs 56695--56698 to 3k tree. Modified: doctools/trunk/Doc-26/library/functions.rst ============================================================================== --- doctools/trunk/Doc-26/library/functions.rst (original) +++ doctools/trunk/Doc-26/library/functions.rst Fri Aug 3 13:33:03 2007 @@ -18,8 +18,8 @@ .. note:: - This is an advanced function that is not needed in everyday Python - programming. + This is an advanced function that is not needed in everyday Python + programming. The function is invoked by the :keyword:`import` statement. It mainly exists so that you can replace it with another function that has a compatible @@ -355,12 +355,12 @@ :func:`enumerate` is useful for obtaining an indexed series: ``(0, seq[0])``, ``(1, seq[1])``, ``(2, seq[2])``, .... For example:: - >>> for i, season in enumerate(['Spring', 'Summer', 'Fall', 'Winter')]: - >>> print i, season - 0 Spring - 1 Summer - 2 Fall - 3 Winter + >>> for i, season in enumerate(['Spring', 'Summer', 'Fall', 'Winter')]: + >>> print i, season + 0 Spring + 1 Summer + 2 Fall + 3 Winter .. versionadded:: 2.3 Modified: doctools/trunk/Doc-3k/library/functions.rst ============================================================================== --- doctools/trunk/Doc-3k/library/functions.rst (original) +++ doctools/trunk/Doc-3k/library/functions.rst Fri Aug 3 13:33:03 2007 @@ -16,7 +16,12 @@ module: rexec module: imp - This function is invoked by the :keyword:`import` statement. It mainly exists + .. note:: + + This is an advanced function that is not needed in everyday Python + programming. + + The function is invoked by the :keyword:`import` statement. It mainly exists so that you can replace it with another function that has a compatible interface, in order to change the semantics of the :keyword:`import` statement. For examples of why and how you would do this, see the standard library modules @@ -138,7 +143,8 @@ Return a string of one character whose ASCII code is the integer *i*. For example, ``chr(97)`` returns the string ``'a'``. This is the inverse of :func:`ord`. The argument must be in the range [0..255], inclusive; - :exc:`ValueError` will be raised if *i* is outside that range. + :exc:`ValueError` will be raised if *i* is outside that range. See + also :func:`unichr`. .. function:: classmethod(function) @@ -346,7 +352,14 @@ iterator returned by :func:`enumerate` returns a tuple containing a count (from zero) and the corresponding value obtained from iterating over *iterable*. :func:`enumerate` is useful for obtaining an indexed series: ``(0, seq[0])``, - ``(1, seq[1])``, ``(2, seq[2])``, .... + ``(1, seq[1])``, ``(2, seq[2])``, .... For example:: + + >>> for i, season in enumerate(['Spring', 'Summer', 'Fall', 'Winter')]: + >>> print i, season + 0 Spring + 1 Summer + 2 Fall + 3 Winter .. versionadded:: 2.3 @@ -1018,6 +1031,14 @@ acceptable to :func:`eval`; its goal is to return a printable string. If no argument is given, returns the empty string, ``''``. + For more information on strings see :ref:`typesseq` which describes + sequence functionality (strings are sequences), and also the + string-specific methods described in the :ref:`string-methods` + section. To output formatted strings use template strings or the + ``%`` operator described in the :ref:`typesseq-strings` section. In + addition see the :ref:`stringservices` section. See also + :func:`unicode`. + .. function:: sum(iterable[, start]) @@ -1097,7 +1118,8 @@ *i*. For example, ``unichr(97)`` returns the string ``u'a'``. This is the inverse of :func:`ord` for Unicode strings. The valid range for the argument depends how Python was configured -- it may be either UCS2 [0..0xFFFF] or UCS4 - [0..0x10FFFF]. :exc:`ValueError` is raised otherwise. + [0..0x10FFFF]. :exc:`ValueError` is raised otherwise. For ASCII and 8-bit + strings see :func:`chr`. .. versionadded:: 2.0 @@ -1127,6 +1149,14 @@ string version or representation is requested and then converted to a Unicode string using the codec for the default encoding in ``'strict'`` mode. + For more information on Unicode strings see :ref:`typesseq` which describes + sequence functionality (Unicode strings are sequences), and also the + string-specific methods described in the :ref:`string-methods` + section. To output formatted strings use template strings or the + ``%`` operator described in the :ref:`typesseq-strings` section. In + addition see the :ref:`stringservices` section. See also + :func:`str`. + .. versionadded:: 2.0 .. versionchanged:: 2.2 Modified: doctools/trunk/Doc-3k/library/index.rst ============================================================================== --- doctools/trunk/Doc-3k/library/index.rst (original) +++ doctools/trunk/Doc-3k/library/index.rst Fri Aug 3 13:33:03 2007 @@ -1,28 +1,38 @@ .. _library-index: ############################### - The Python standard library + The Python Standard Library ############################### :Release: |version| :Date: |today| -While :ref:`reference-index` describes the exact syntax and semantics of the -language, it does not describe the standard library that is distributed with the -language, and which greatly enhances its immediate usability. This library -contains built-in modules (written in C) that provide access to system -functionality such as file I/O that would otherwise be inaccessible to Python -programmers, as well as modules written in Python that provide standardized -solutions for many problems that occur in everyday programming. Some of these -modules are explicitly designed to encourage and enhance the portability of -Python programs. - -This library reference manual documents Python's standard library, as well as -many optional library modules (which may or may not be available, depending on -whether the underlying platform supports them and on the configuration choices -made at compile time). It also documents the standard types of the language and -its built-in functions and exceptions, many of which are not or incompletely -documented in the Reference Manual. +While the :ref:`reference-index` describes the exact syntax and +semantics of the Python language, this library reference manual +describes the standard library that is distributed with Python. It also +describes some of the optional components that are commonly included +in Python distributions. + +Python's standard library is very extensive, offering a wide range of +facilities as indicated by the long table of contents listed below. The +library contains built-in modules (written in C) that provide access to +system functionality such as file I/O that would otherwise be +inaccessible to Python programmers, as well as modules written in Python +that provide standardized solutions for many problems that occur in +everyday programming. Some of these modules are explicitly designed to +encourage and enhance the portability of Python programs by abstracting +away platform-specifics into platform-neutral APIs. + +The Python installers for the Windows and Mac platforms usually include +the entire standard library and often also include many additional +components. For Unix-like operating systems Python is normally provided +as a collection of packages, so it may be necessary to use the packaging +tools provided with the operating system to obtain some or all of the +optional components. + +In addition to the standard library, there is a growing collection of +over 2500 additional components available from the `Python Package Index +`_. .. toctree:: Modified: doctools/trunk/Doc-3k/library/stdtypes.rst ============================================================================== --- doctools/trunk/Doc-3k/library/stdtypes.rst (original) +++ doctools/trunk/Doc-3k/library/stdtypes.rst Fri Aug 3 13:33:03 2007 @@ -12,8 +12,8 @@ Historically (until release 2.2), Python's built-in types have differed from user-defined types because it was not possible to use the built-in types as the - basis for object-oriented inheritance. This limitation does not exist any - longer. + basis for object-oriented inheritance. This limitation no longer + exists. .. index:: pair: built-in; types @@ -95,10 +95,10 @@ | ``x or y`` | if *x* is false, then *y*, else | \(1) | | | *x* | | +-------------+---------------------------------+-------+ -| ``x and y`` | if *x* is false, then *x*, else | \(1) | +| ``x and y`` | if *x* is false, then *x*, else | \(2) | | | *y* | | +-------------+---------------------------------+-------+ -| ``not x`` | if *x* is false, then ``True``, | \(2) | +| ``not x`` | if *x* is false, then ``True``, | \(3) | | | else ``False`` | | +-------------+---------------------------------+-------+ @@ -110,9 +110,14 @@ Notes: (1) - These only evaluate their second argument if needed for their outcome. + This is a short-circuit operator, so it only evaluates the second + argument if the first one is :const:`False`. (2) + This is a short-circuit operator, so it only evaluates the second + argument if the first one is :const:`True`. + +(3) ``not`` has a lower priority than non-Boolean operators, so ``not a == b`` is interpreted as ``not (a == b)``, and ``a == not b`` is a syntax error. @@ -550,6 +555,13 @@ | ``max(s)`` | largest item of *s* | | +------------------+--------------------------------+----------+ +Sequence types also support comparisons. In particular, tuples and lists +are compared lexicographically by comparing corresponding +elements. This means that to compare equal, every element must compare +equal and the two sequences must be of the same type and have the same +length. (For full details see :ref:`comparisons` in the language +reference.) + .. index:: triple: operations on; sequence; types builtin: len Modified: doctools/trunk/sphinx/web/application.py ============================================================================== --- doctools/trunk/sphinx/web/application.py (original) +++ doctools/trunk/sphinx/web/application.py Fri Aug 3 13:33:03 2007 @@ -516,7 +516,7 @@ for modname in self.env.filemodules.get(page_id, ()): self.freqmodules[modname] += 1 # comments enabled? - comments = self.env.metadata[page_id].get('comments_enabled', True) + comments = self.env.metadata[page_id].get('nocomments', False) # how does the user want to view comments? commentmode = req.session.get('comments', 'inline') if comments else '' From python-checkins at python.org Fri Aug 3 13:56:23 2007 From: python-checkins at python.org (georg.brandl) Date: Fri, 3 Aug 2007 13:56:23 +0200 (CEST) Subject: [Python-checkins] r56700 - in doctools/trunk: Doc-26/documenting/markup.rst Doc-26/documenting/rest.rst Doc-26/documenting/sphinx.rst Doc-3k/documenting/markup.rst Doc-3k/documenting/rest.rst Doc-3k/documenting/sphinx.rst Message-ID: <20070803115623.173D61E4005@bag.python.org> Author: georg.brandl Date: Fri Aug 3 13:56:22 2007 New Revision: 56700 Modified: doctools/trunk/Doc-26/documenting/markup.rst doctools/trunk/Doc-26/documenting/rest.rst doctools/trunk/Doc-26/documenting/sphinx.rst doctools/trunk/Doc-3k/documenting/markup.rst doctools/trunk/Doc-3k/documenting/rest.rst doctools/trunk/Doc-3k/documenting/sphinx.rst Log: Write a bit more in "Documenting". Modified: doctools/trunk/Doc-26/documenting/markup.rst ============================================================================== --- doctools/trunk/Doc-26/documenting/markup.rst (original) +++ doctools/trunk/Doc-26/documenting/markup.rst Fri Aug 3 13:56:22 2007 @@ -8,7 +8,25 @@ Documentation for "standard" reST constructs is not included here, though they are used in the Python documentation. -.. XXX: file-wide metadata +File-wide metadata +------------------ + +reST has the concept of "field lists"; these are a sequence of fields marked up +like this:: + + :Field name: Field content + +A field list at the very top of a file is parsed as the "docinfo", which in +normal documents can be used to record the author, date of publication and +other metadata. In Sphinx, the docinfo is used as metadata, too, but not +displayed in the output. + +At the moment, only one metadata field is recognized: + +``nocomments`` + If set, the web application won't display a comment form for a page generated + from this source file. + Meta-information markup ----------------------- @@ -265,9 +283,7 @@ As said before, Sphinx uses interpreted text roles to insert semantic markup in documents. -The default role is ``var``, as that was one of the most common macros used in -the old LaTeX docs. That means that you can use ```var``` to refer to a -variable named "var". +Variable names are an exception, they should be marked simply with ``*var*``. For all other roles, you have to write ``:rolename:`content```. @@ -488,7 +504,7 @@ -------------------- To support cross-referencing to arbitrary sections in the documentation, the -standard reST labels are "abused" a bit: Every label must precede a section +standard reST labels are "abused" a bit: Every label must precede a section title; and every label name must be unique throughout the entire documentation source. Modified: doctools/trunk/Doc-26/documenting/rest.rst ============================================================================== --- doctools/trunk/Doc-26/documenting/rest.rst (original) +++ doctools/trunk/Doc-26/documenting/rest.rst Fri Aug 3 13:56:22 2007 @@ -4,10 +4,9 @@ ======================= This section is a brief introduction to reStructuredText (reST) concepts and -syntax, intended to provide authors with enough information to author -documents productively. -Since reST was designed to be a simple, unobtrusive markup language, this will -not take too long. +syntax, intended to provide authors with enough information to author documents +productively. Since reST was designed to be a simple, unobtrusive markup +language, this will not take too long. .. seealso:: @@ -18,12 +17,13 @@ Paragraphs ---------- -The paragraph is the most basic block in a reST document. -Paragraphs are simply chunks of text -separated by one or more blank lines. As in Python, indentation is significant -in reST, so all lines of the same paragraph must be left-aligned +The paragraph is the most basic block in a reST document. Paragraphs are simply +chunks of text separated by one or more blank lines. As in Python, indentation +is significant in reST, so all lines of the same paragraph must be left-aligned to the same level of indentation. +The Python docs use an indentation of 3 spaces. + Inline markup ------------- Modified: doctools/trunk/Doc-26/documenting/sphinx.rst ============================================================================== --- doctools/trunk/Doc-26/documenting/sphinx.rst (original) +++ doctools/trunk/Doc-26/documenting/sphinx.rst Fri Aug 3 13:56:22 2007 @@ -3,7 +3,7 @@ The Sphinx build system ======================= -XXX: intro... +.. XXX: intro... .. _doc-build-config: Modified: doctools/trunk/Doc-3k/documenting/markup.rst ============================================================================== --- doctools/trunk/Doc-3k/documenting/markup.rst (original) +++ doctools/trunk/Doc-3k/documenting/markup.rst Fri Aug 3 13:56:22 2007 @@ -8,7 +8,25 @@ Documentation for "standard" reST constructs is not included here, though they are used in the Python documentation. -.. XXX: file-wide metadata +File-wide metadata +------------------ + +reST has the concept of "field lists"; these are a sequence of fields marked up +like this:: + + :Field name: Field content + +A field list at the very top of a file is parsed as the "docinfo", which in +normal documents can be used to record the author, date of publication and +other metadata. In Sphinx, the docinfo is used as metadata, too, but not +displayed in the output. + +At the moment, only one metadata field is recognized: + +``nocomments`` + If set, the web application won't display a comment form for a page generated + from this source file. + Meta-information markup ----------------------- @@ -265,9 +283,7 @@ As said before, Sphinx uses interpreted text roles to insert semantic markup in documents. -The default role is ``var``, as that was one of the most common macros used in -the old LaTeX docs. That means that you can use ```var``` to refer to a -variable named "var". +Variable names are an exception, they should be marked simply with ``*var*``. For all other roles, you have to write ``:rolename:`content```. @@ -488,7 +504,7 @@ -------------------- To support cross-referencing to arbitrary sections in the documentation, the -standard reST labels are "abused" a bit: Every label must precede a section +standard reST labels are "abused" a bit: Every label must precede a section title; and every label name must be unique throughout the entire documentation source. Modified: doctools/trunk/Doc-3k/documenting/rest.rst ============================================================================== --- doctools/trunk/Doc-3k/documenting/rest.rst (original) +++ doctools/trunk/Doc-3k/documenting/rest.rst Fri Aug 3 13:56:22 2007 @@ -4,10 +4,9 @@ ======================= This section is a brief introduction to reStructuredText (reST) concepts and -syntax, intended to provide authors with enough information to author -documents productively. -Since reST was designed to be a simple, unobtrusive markup language, this will -not take too long. +syntax, intended to provide authors with enough information to author documents +productively. Since reST was designed to be a simple, unobtrusive markup +language, this will not take too long. .. seealso:: @@ -18,12 +17,13 @@ Paragraphs ---------- -The paragraph is the most basic block in a reST document. -Paragraphs are simply chunks of text -separated by one or more blank lines. As in Python, indentation is significant -in reST, so all lines of the same paragraph must be left-aligned +The paragraph is the most basic block in a reST document. Paragraphs are simply +chunks of text separated by one or more blank lines. As in Python, indentation +is significant in reST, so all lines of the same paragraph must be left-aligned to the same level of indentation. +The Python docs use an indentation of 3 spaces. + Inline markup ------------- Modified: doctools/trunk/Doc-3k/documenting/sphinx.rst ============================================================================== --- doctools/trunk/Doc-3k/documenting/sphinx.rst (original) +++ doctools/trunk/Doc-3k/documenting/sphinx.rst Fri Aug 3 13:56:22 2007 @@ -3,7 +3,7 @@ The Sphinx build system ======================= -XXX: intro... +.. XXX: intro... .. _doc-build-config: From python-checkins at python.org Fri Aug 3 14:08:08 2007 From: python-checkins at python.org (georg.brandl) Date: Fri, 3 Aug 2007 14:08:08 +0200 (CEST) Subject: [Python-checkins] r56701 - in doctools/trunk: Doc-26/TODO Doc-26/contents.rst Doc-26/copyright.rst Doc-26/license.rst Doc-3k/TODO Doc-3k/contents.rst Doc-3k/copyright.rst Doc-3k/license.rst Message-ID: <20070803120808.B20331E4005@bag.python.org> Author: georg.brandl Date: Fri Aug 3 14:08:08 2007 New Revision: 56701 Modified: doctools/trunk/Doc-26/TODO doctools/trunk/Doc-26/contents.rst doctools/trunk/Doc-26/copyright.rst doctools/trunk/Doc-26/license.rst doctools/trunk/Doc-3k/TODO doctools/trunk/Doc-3k/contents.rst doctools/trunk/Doc-3k/copyright.rst doctools/trunk/Doc-3k/license.rst Log: Fix the copyright page. Modified: doctools/trunk/Doc-26/TODO ============================================================================== --- doctools/trunk/Doc-26/TODO (original) +++ doctools/trunk/Doc-26/TODO Fri Aug 3 14:08:08 2007 @@ -5,4 +5,3 @@ * find out which files get "comments disabled" metadata * write "About these documents" * finish "Documenting Python" -* extend copyright.rst Modified: doctools/trunk/Doc-26/contents.rst ============================================================================== --- doctools/trunk/Doc-26/contents.rst (original) +++ doctools/trunk/Doc-26/contents.rst Fri Aug 3 14:08:08 2007 @@ -16,7 +16,7 @@ documenting/index.rst howto/index.rst - bugs.rst about.rst - license.rst + bugs.rst copyright.rst + license.rst Modified: doctools/trunk/Doc-26/copyright.rst ============================================================================== --- doctools/trunk/Doc-26/copyright.rst (original) +++ doctools/trunk/Doc-26/copyright.rst Fri Aug 3 14:08:08 2007 @@ -2,6 +2,8 @@ Copyright ********* +Python and this documentation is: + Copyright ? 2001-2007 Python Software Foundation. All rights reserved. Copyright ? 2000 BeOpen.com. All rights reserved. @@ -11,5 +13,7 @@ Copyright ? 1991-1995 Stichting Mathematisch Centrum. All rights reserved. -See the end of this document for complete license and permissions information. +------- + +See :ref:`history-and-license` for complete license and permissions information. Modified: doctools/trunk/Doc-26/license.rst ============================================================================== --- doctools/trunk/Doc-26/license.rst (original) +++ doctools/trunk/Doc-26/license.rst Fri Aug 3 14:08:08 2007 @@ -1,5 +1,7 @@ .. highlightlang:: none +.. _history-and-license: + ******************* History and License ******************* Modified: doctools/trunk/Doc-3k/TODO ============================================================================== --- doctools/trunk/Doc-3k/TODO (original) +++ doctools/trunk/Doc-3k/TODO Fri Aug 3 14:08:08 2007 @@ -5,4 +5,3 @@ * find out which files get "comments disabled" metadata * write "About these documents" * finish "Documenting Python" -* extend copyright.rst Modified: doctools/trunk/Doc-3k/contents.rst ============================================================================== --- doctools/trunk/Doc-3k/contents.rst (original) +++ doctools/trunk/Doc-3k/contents.rst Fri Aug 3 14:08:08 2007 @@ -16,7 +16,7 @@ documenting/index.rst howto/index.rst - bugs.rst about.rst - license.rst + bugs.rst copyright.rst + license.rst Modified: doctools/trunk/Doc-3k/copyright.rst ============================================================================== --- doctools/trunk/Doc-3k/copyright.rst (original) +++ doctools/trunk/Doc-3k/copyright.rst Fri Aug 3 14:08:08 2007 @@ -2,6 +2,8 @@ Copyright ********* +Python and this documentation is: + Copyright ? 2001-2007 Python Software Foundation. All rights reserved. Copyright ? 2000 BeOpen.com. All rights reserved. @@ -11,5 +13,7 @@ Copyright ? 1991-1995 Stichting Mathematisch Centrum. All rights reserved. -See the end of this document for complete license and permissions information. +------- + +See :ref:`history-and-license` for complete license and permissions information. Modified: doctools/trunk/Doc-3k/license.rst ============================================================================== --- doctools/trunk/Doc-3k/license.rst (original) +++ doctools/trunk/Doc-3k/license.rst Fri Aug 3 14:08:08 2007 @@ -1,5 +1,7 @@ .. highlightlang:: none +.. _history-and-license: + ******************* History and License ******************* From python-checkins at python.org Fri Aug 3 15:20:48 2007 From: python-checkins at python.org (mark.summerfield) Date: Fri, 3 Aug 2007 15:20:48 +0200 (CEST) Subject: [Python-checkins] r56702 - doctools/trunk/Doc-26/library/os.rst Message-ID: <20070803132048.0C2DA1E4008@bag.python.org> Author: mark.summerfield Date: Fri Aug 3 15:20:47 2007 New Revision: 56702 Modified: doctools/trunk/Doc-26/library/os.rst Log: Changed all references to stat module S_* constants to stat.S_* since it is v. confusing that in module os these constants are from the stat module rather than from os. Also added a couple of cross-references to open(). Modified: doctools/trunk/Doc-26/library/os.rst ============================================================================== --- doctools/trunk/Doc-26/library/os.rst (original) +++ doctools/trunk/Doc-26/library/os.rst Fri Aug 3 15:20:47 2007 @@ -8,7 +8,8 @@ This module provides a more portable way of using operating system dependent functionality than importing a operating system dependent built-in module like -:mod:`posix` or :mod:`nt`. +:mod:`posix` or :mod:`nt`. (If you just want to read or write a file see +:func:`open`.) This module searches for an operating system dependent built-in module like :mod:`mac` or :mod:`posix` and exports the same functions and data as found @@ -348,7 +349,7 @@ File Object Creation -------------------- -These functions create new file objects. +These functions create new file objects. (See also :func:`open`.) .. function:: fdopen(fd[, mode[, bufsize]]) @@ -851,51 +852,52 @@ following values (as defined in the :mod:`stat` module) or bitwise or-ed combinations of them: -* ``S_ISUID`` +* ``stat.S_ISUID`` -* ``S_ISGID`` +* ``stat.S_ISGID`` -* ``S_ENFMT`` +* ``stat.S_ENFMT`` -* ``S_ISVTX`` +* ``stat.S_ISVTX`` -* ``S_IREAD`` +* ``stat.S_IREAD`` -* ``S_IWRITE`` +* ``stat.S_IWRITE`` -* ``S_IEXEC`` +* ``stat.S_IEXEC`` -* ``S_IRWXU`` +* ``stat.S_IRWXU`` -* ``S_IRUSR`` +* ``stat.S_IRUSR`` -* ``S_IWUSR`` +* ``stat.S_IWUSR`` -* ``S_IXUSR`` +* ``stat.S_IXUSR`` -* ``S_IRWXG`` +* ``stat.S_IRWXG`` -* ``S_IRGRP`` +* ``stat.S_IRGRP`` -* ``S_IWGRP`` +* ``stat.S_IWGRP`` -* ``S_IXGRP`` +* ``stat.S_IXGRP`` -* ``S_IRWXO`` +* ``stat.S_IRWXO`` -* ``S_IROTH`` +* ``stat.S_IROTH`` -* ``S_IWOTH`` +* ``stat.S_IWOTH`` -* ``S_IXOTH`` +* ``stat.S_IXOTH`` Availability: Macintosh, Unix, Windows. .. note:: Although Windows supports :func:`chmod`, you can only set the file's read-only - flag with it (via the ``S_IWRITE`` and ``S_IREAD`` constants or a corresponding - integer value). All other bits are ignored. + flag with it (via the ``stat.S_IWRITE`` and ``stat.S_IREAD`` + constants or a corresponding integer value). All other bits are + ignored. .. function:: chown(path, uid, gid) @@ -960,9 +962,11 @@ Create a filesystem node (file, device special file or named pipe) named *filename*. *mode* specifies both the permissions to use and the type of node to - be created, being combined (bitwise OR) with one of S_IFREG, S_IFCHR, S_IFBLK, - and S_IFIFO (those constants are available in :mod:`stat`). For S_IFCHR and - S_IFBLK, *device* defines the newly created device special file (probably using + be created, being combined (bitwise OR) with one of ``stat.S_IFREG``, + ``stat.S_IFCHR``, ``stat.S_IFBLK``, + and ``stat.S_IFIFO`` (those constants are available in :mod:`stat`). + For ``stat.S_IFCHR`` and + ``stat.S_IFBLK``, *device* defines the newly created device special file (probably using :func:`os.makedev`), otherwise it is ignored. .. versionadded:: 2.3 From python-checkins at python.org Fri Aug 3 17:46:35 2007 From: python-checkins at python.org (georg.brandl) Date: Fri, 3 Aug 2007 17:46:35 +0200 (CEST) Subject: [Python-checkins] r56705 - doctools/trunk/Doc-26/library/zipfile.rst Message-ID: <20070803154635.537361E400C@bag.python.org> Author: georg.brandl Date: Fri Aug 3 17:46:34 2007 New Revision: 56705 Modified: doctools/trunk/Doc-26/library/zipfile.rst Log: Fix broken link in zipfile docs. Modified: doctools/trunk/Doc-26/library/zipfile.rst ============================================================================== --- doctools/trunk/Doc-26/library/zipfile.rst (original) +++ doctools/trunk/Doc-26/library/zipfile.rst Fri Aug 3 17:46:34 2007 @@ -85,7 +85,7 @@ Documentation on the ZIP file format by Phil Katz, the creator of the format and algorithms used. - `Info-ZIP Home Page `_ + `Info-ZIP Home Page `_ Information about the Info-ZIP project's ZIP archive programs and development libraries. From python-checkins at python.org Fri Aug 3 21:19:46 2007 From: python-checkins at python.org (david.goodger) Date: Fri, 3 Aug 2007 21:19:46 +0200 (CEST) Subject: [Python-checkins] r56710 - peps/trunk/pep-0366.txt Message-ID: <20070803191946.3D1801E4014@bag.python.org> Author: david.goodger Date: Fri Aug 3 21:19:44 2007 New Revision: 56710 Modified: peps/trunk/pep-0366.txt Log: markup fixes Modified: peps/trunk/pep-0366.txt ============================================================================== --- peps/trunk/pep-0366.txt (original) +++ peps/trunk/pep-0366.txt Fri Aug 3 21:19:44 2007 @@ -20,7 +20,7 @@ between PEP 328 and PEP 338. By adding a new module level attribute, this PEP allows relative imports -to work automatically if the module is executed using the ``-m``switch. +to work automatically if the module is executed using the ``-m`` switch. A small amount of boilerplate in the module itself will allow the relative imports to work when the file is executed by name. @@ -48,7 +48,7 @@ ``__package__`` attribute will be set to the empty string. To allow relative imports when the module is executed directly, boilerplate similar to the following would be needed before the first relative -import statement: +import statement:: if __name__ == "__main__" and not __package_name__: __package_name__ = "" @@ -68,9 +68,9 @@ ==================== The current inability to use explicit relative imports from the main -module is the subject of at least one open SF bug report (#1510172)[1], +module is the subject of at least one open SF bug report (#1510172) [1]_, and has most likely been a factor in at least a few queries on -comp.lang.python (such as Alan Isaac's question in [2]). +comp.lang.python (such as Alan Isaac's question in [2]_). This PEP is intended to provide a solution which permits explicit relative imports from main modules, without incurring any significant @@ -85,7 +85,7 @@ Rev 47142 in SVN implemented an early variant of this proposal which stored the main module's real module name in the -'__module_name__' attribute. It was reverted due to the fact +``__module_name__`` attribute. It was reverted due to the fact that 2.5 was already in beta by that time. A new patch will be developed for 2.6, and forward ported to @@ -98,7 +98,7 @@ PEP 3122 proposed addressing this problem by changing the way the main module is identified. That's a significant compatibility cost to incur to fix something that is a pretty minor bug in the overall -scheme of things, and the PEP was rejected [3]. +scheme of things, and the PEP was rejected [3]_. The advantage of the proposal in this PEP is that its only impact on normal code is the small amount of time needed to set the extra From python-checkins at python.org Sat Aug 4 06:10:20 2007 From: python-checkins at python.org (hyeshik.chang) Date: Sat, 4 Aug 2007 06:10:20 +0200 (CEST) Subject: [Python-checkins] r56727 - in python/trunk: Lib/test/test_codecmaps_cn.py Lib/test/test_multibytecodec_support.py Misc/NEWS Modules/cjkcodecs/_codecs_cn.c Message-ID: <20070804041020.052F21E4014@bag.python.org> Author: hyeshik.chang Date: Sat Aug 4 06:10:18 2007 New Revision: 56727 Modified: python/trunk/Lib/test/test_codecmaps_cn.py python/trunk/Lib/test/test_multibytecodec_support.py python/trunk/Misc/NEWS python/trunk/Modules/cjkcodecs/_codecs_cn.c Log: Fix gb18030 codec's bug that doesn't map two-byte characters on GB18030 extension in encoding. (bug reported by Bjorn Stabell) Modified: python/trunk/Lib/test/test_codecmaps_cn.py ============================================================================== --- python/trunk/Lib/test/test_codecmaps_cn.py (original) +++ python/trunk/Lib/test/test_codecmaps_cn.py Sat Aug 4 06:10:18 2007 @@ -19,6 +19,13 @@ mapfileurl = 'http://www.unicode.org/Public/MAPPINGS/VENDORS/' \ 'MICSFT/WINDOWS/CP936.TXT' +class TestGB18030Map(test_multibytecodec_support.TestBase_Mapping, + unittest.TestCase): + encoding = 'gb18030' + mapfileurl = 'http://source.icu-project.org/repos/icu/data/' \ + 'trunk/charset/data/xml/gb-18030-2000.xml' + + def test_main(): test_support.run_unittest(__name__) Modified: python/trunk/Lib/test/test_multibytecodec_support.py ============================================================================== --- python/trunk/Lib/test/test_multibytecodec_support.py (original) +++ python/trunk/Lib/test/test_multibytecodec_support.py Sat Aug 4 06:10:18 2007 @@ -5,7 +5,7 @@ # import sys, codecs, os.path -import unittest +import unittest, re from test import test_support from StringIO import StringIO @@ -272,6 +272,12 @@ return test_support.open_urlresource(self.mapfileurl) def test_mapping_file(self): + if self.mapfileurl.endswith('.xml'): + self._test_mapping_file_ucm() + else: + self._test_mapping_file_plain() + + def _test_mapping_file_plain(self): unichrs = lambda s: u''.join(map(unichr, map(eval, s.split('+')))) urt_wa = {} @@ -303,6 +309,14 @@ self._testpoint(csetch, unich) + def _test_mapping_file_ucm(self): + ucmdata = self.open_mapping_file().read() + uc = re.findall('', ucmdata) + for uni, coded in uc: + unich = unichr(int(uni, 16)) + codech = ''.join(chr(int(c, 16)) for c in coded.split()) + self._testpoint(codech, unich) + def test_mapping_supplemental(self): for mapping in self.supmaps: self._testpoint(*mapping) Modified: python/trunk/Misc/NEWS ============================================================================== --- python/trunk/Misc/NEWS (original) +++ python/trunk/Misc/NEWS Sat Aug 4 06:10:18 2007 @@ -240,6 +240,9 @@ Library ------- +- GB18030 codec now can encode additional two-byte characters that + are missing in GBK. + - Bug #1704793: Return UTF-16 pair if unicodedata.lookup cannot represent the result in a single character. Modified: python/trunk/Modules/cjkcodecs/_codecs_cn.c ============================================================================== --- python/trunk/Modules/cjkcodecs/_codecs_cn.c (original) +++ python/trunk/Modules/cjkcodecs/_codecs_cn.c Sat Aug 4 06:10:18 2007 @@ -197,6 +197,7 @@ REQUIRE_OUTBUF(2) GBK_ENCODE(c, code) + else TRYMAP_ENC(gb18030ext, code, c); else { const struct _gb18030_to_unibmp_ranges *utrrange; From python-checkins at python.org Sat Aug 4 06:15:05 2007 From: python-checkins at python.org (hyeshik.chang) Date: Sat, 4 Aug 2007 06:15:05 +0200 (CEST) Subject: [Python-checkins] r56728 - in python/branches/release25-maint: Lib/test/test_codecmaps_cn.py Lib/test/test_multibytecodec_support.py Misc/NEWS Modules/cjkcodecs/_codecs_cn.c Message-ID: <20070804041505.731BF1E401A@bag.python.org> Author: hyeshik.chang Date: Sat Aug 4 06:15:04 2007 New Revision: 56728 Modified: python/branches/release25-maint/Lib/test/test_codecmaps_cn.py python/branches/release25-maint/Lib/test/test_multibytecodec_support.py python/branches/release25-maint/Misc/NEWS python/branches/release25-maint/Modules/cjkcodecs/_codecs_cn.c Log: Backport from trunk r56727: Fix gb18030 codec's bug that doesn't map two-byte characters on GB18030 extension in encoding. (bug reported by Bjorn Stabell) Modified: python/branches/release25-maint/Lib/test/test_codecmaps_cn.py ============================================================================== --- python/branches/release25-maint/Lib/test/test_codecmaps_cn.py (original) +++ python/branches/release25-maint/Lib/test/test_codecmaps_cn.py Sat Aug 4 06:15:04 2007 @@ -19,10 +19,18 @@ mapfileurl = 'http://www.unicode.org/Public/MAPPINGS/VENDORS/' \ 'MICSFT/WINDOWS/CP936.TXT' +class TestGB18030Map(test_multibytecodec_support.TestBase_Mapping, + unittest.TestCase): + encoding = 'gb18030' + mapfileurl = 'http://source.icu-project.org/repos/icu/data/' \ + 'trunk/charset/data/xml/gb-18030-2000.xml' + + def test_main(): suite = unittest.TestSuite() suite.addTest(unittest.makeSuite(TestGB2312Map)) suite.addTest(unittest.makeSuite(TestGBKMap)) + suite.addTest(unittest.makeSuite(TestGB18030Map)) test_support.run_suite(suite) if __name__ == "__main__": Modified: python/branches/release25-maint/Lib/test/test_multibytecodec_support.py ============================================================================== --- python/branches/release25-maint/Lib/test/test_multibytecodec_support.py (original) +++ python/branches/release25-maint/Lib/test/test_multibytecodec_support.py Sat Aug 4 06:15:04 2007 @@ -5,7 +5,7 @@ # import sys, codecs, os.path -import unittest +import unittest, re from test import test_support from StringIO import StringIO @@ -272,6 +272,12 @@ return test_support.open_urlresource(self.mapfileurl) def test_mapping_file(self): + if self.mapfileurl.endswith('.xml'): + self._test_mapping_file_ucm() + else: + self._test_mapping_file_plain() + + def _test_mapping_file_plain(self): unichrs = lambda s: u''.join(map(unichr, map(eval, s.split('+')))) urt_wa = {} @@ -303,6 +309,14 @@ self._testpoint(csetch, unich) + def _test_mapping_file_ucm(self): + ucmdata = self.open_mapping_file().read() + uc = re.findall('', ucmdata) + for uni, coded in uc: + unich = unichr(int(uni, 16)) + codech = ''.join(chr(int(c, 16)) for c in coded.split()) + self._testpoint(codech, unich) + def test_mapping_supplemental(self): for mapping in self.supmaps: self._testpoint(*mapping) Modified: python/branches/release25-maint/Misc/NEWS ============================================================================== --- python/branches/release25-maint/Misc/NEWS (original) +++ python/branches/release25-maint/Misc/NEWS Sat Aug 4 06:15:04 2007 @@ -26,6 +26,9 @@ Library ------- +- GB18030 codec now can encode additional two-byte characters that + are missing in GBK. + - Bug #1704793: Raise KeyError if unicodedata.lookup cannot represent the result in a single character. Modified: python/branches/release25-maint/Modules/cjkcodecs/_codecs_cn.c ============================================================================== --- python/branches/release25-maint/Modules/cjkcodecs/_codecs_cn.c (original) +++ python/branches/release25-maint/Modules/cjkcodecs/_codecs_cn.c Sat Aug 4 06:15:04 2007 @@ -197,6 +197,7 @@ REQUIRE_OUTBUF(2) GBK_ENCODE(c, code) + else TRYMAP_ENC(gb18030ext, code, c); else { const struct _gb18030_to_unibmp_ranges *utrrange; From buildbot at python.org Sat Aug 4 06:34:46 2007 From: buildbot at python.org (buildbot at python.org) Date: Sat, 04 Aug 2007 04:34:46 +0000 Subject: [Python-checkins] buildbot warnings in x86 gentoo trunk Message-ID: <20070804043446.57ADC1E400B@bag.python.org> The Buildbot has detected a new failure of x86 gentoo trunk. Full details are available at: http://www.python.org/dev/buildbot/all/x86%2520gentoo%2520trunk/builds/2344 Buildbot URL: http://www.python.org/dev/buildbot/all/ Build Reason: Build Source Stamp: [branch trunk] HEAD Blamelist: hyeshik.chang Build had warnings: warnings test Excerpt from the test logfile: 2 tests failed: test_timeout test_urllib2net make: *** [buildbottest] Error 1 sincerely, -The Buildbot From buildbot at python.org Sat Aug 4 06:36:27 2007 From: buildbot at python.org (buildbot at python.org) Date: Sat, 04 Aug 2007 04:36:27 +0000 Subject: [Python-checkins] buildbot warnings in x86 mvlgcc trunk Message-ID: <20070804043627.F007A1E400B@bag.python.org> The Buildbot has detected a new failure of x86 mvlgcc trunk. Full details are available at: http://www.python.org/dev/buildbot/all/x86%2520mvlgcc%2520trunk/builds/686 Buildbot URL: http://www.python.org/dev/buildbot/all/ Build Reason: Build Source Stamp: [branch trunk] HEAD Blamelist: hyeshik.chang Build had warnings: warnings test Excerpt from the test logfile: Traceback (most recent call last): File "/home2/buildbot/slave/trunk.loewis-linux/build/Lib/threading.py", line 466, in __bootstrap self.run() File "/home2/buildbot/slave/trunk.loewis-linux/build/Lib/threading.py", line 446, in run self.__target(*self.__args, **self.__kwargs) File "/home2/buildbot/slave/trunk.loewis-linux/build/Lib/bsddb/test/test_thread.py", line 245, in writerThread self.assertEqual(data, self.makeData(key)) File "/home2/buildbot/slave/trunk.loewis-linux/build/Lib/unittest.py", line 343, in failUnlessEqual (msg or '%r != %r' % (first, second)) AssertionError: None != '2075-2075-2075-2075-2075' Traceback (most recent call last): File "/home2/buildbot/slave/trunk.loewis-linux/build/Lib/threading.py", line 466, in __bootstrap self.run() File "/home2/buildbot/slave/trunk.loewis-linux/build/Lib/threading.py", line 446, in run self.__target(*self.__args, **self.__kwargs) File "/home2/buildbot/slave/trunk.loewis-linux/build/Lib/bsddb/test/test_thread.py", line 260, in writerThread self.assertEqual(data, self.makeData(key)) File "/home2/buildbot/slave/trunk.loewis-linux/build/Lib/unittest.py", line 343, in failUnlessEqual (msg or '%r != %r' % (first, second)) AssertionError: None != '1001-1001-1001-1001-1001' Traceback (most recent call last): File "/home2/buildbot/slave/trunk.loewis-linux/build/Lib/threading.py", line 466, in __bootstrap self.run() File "/home2/buildbot/slave/trunk.loewis-linux/build/Lib/threading.py", line 446, in run self.__target(*self.__args, **self.__kwargs) File "/home2/buildbot/slave/trunk.loewis-linux/build/Lib/bsddb/test/test_thread.py", line 260, in writerThread self.assertEqual(data, self.makeData(key)) File "/home2/buildbot/slave/trunk.loewis-linux/build/Lib/unittest.py", line 343, in failUnlessEqual (msg or '%r != %r' % (first, second)) AssertionError: None != '0002-0002-0002-0002-0002' 3 tests failed: test_timeout test_urllib2net test_urllibnet make: *** [buildbottest] Error 1 sincerely, -The Buildbot From buildbot at python.org Sat Aug 4 07:10:52 2007 From: buildbot at python.org (buildbot at python.org) Date: Sat, 04 Aug 2007 05:10:52 +0000 Subject: [Python-checkins] buildbot warnings in S-390 Debian trunk Message-ID: <20070804051053.9D36F1E401C@bag.python.org> The Buildbot has detected a new failure of S-390 Debian trunk. Full details are available at: http://www.python.org/dev/buildbot/all/S-390%2520Debian%2520trunk/builds/1078 Buildbot URL: http://www.python.org/dev/buildbot/all/ Build Reason: Build Source Stamp: [branch trunk] HEAD Blamelist: hyeshik.chang Build had warnings: warnings test Excerpt from the test logfile: 1 test failed: test_urllib2net make: *** [buildbottest] Error 1 sincerely, -The Buildbot From buildbot at python.org Sat Aug 4 07:29:51 2007 From: buildbot at python.org (buildbot at python.org) Date: Sat, 04 Aug 2007 05:29:51 +0000 Subject: [Python-checkins] buildbot warnings in x86 XP 2.5 Message-ID: <20070804052951.9FBE81E4013@bag.python.org> The Buildbot has detected a new failure of x86 XP 2.5. Full details are available at: http://www.python.org/dev/buildbot/all/x86%2520XP%25202.5/builds/266 Buildbot URL: http://www.python.org/dev/buildbot/all/ Build Reason: Build Source Stamp: [branch branches/release25-maint] HEAD Blamelist: hyeshik.chang,matthias.klose Build had warnings: warnings failed slave lost sincerely, -The Buildbot From python-checkins at python.org Sat Aug 4 09:11:49 2007 From: python-checkins at python.org (mark.summerfield) Date: Sat, 4 Aug 2007 09:11:49 +0200 (CEST) Subject: [Python-checkins] r56729 - doctools/trunk/Doc-26/library/tk.rst Message-ID: <20070804071149.8914F1E400B@bag.python.org> Author: mark.summerfield Date: Sat Aug 4 09:11:49 2007 New Revision: 56729 Modified: doctools/trunk/Doc-26/library/tk.rst Log: Changed third para of description to give greater emphasis to other GUI toolkits. Modified: doctools/trunk/Doc-26/library/tk.rst ============================================================================== --- doctools/trunk/Doc-26/library/tk.rst (original) +++ doctools/trunk/Doc-26/library/tk.rst Sat Aug 4 09:11:49 2007 @@ -21,8 +21,11 @@ classes. In addition, the internal module :mod:`_tkinter` provides a threadsafe mechanism which allows Python and Tcl to interact. -Tk is not the only GUI for Python; see section :ref:`other-gui-packages` for -more information on other GUI toolkits for Python. +:mod:`Tkinter`'s chief virtues are that it is fast, and that it usually comes +bundled with Python. Although it has been used to create some very good +applications, including IDLE, it has weak documentation and an outdated look and +feel. For more modern, better documented, and much more extensive GUI +libraries, see the :ref:`other-gui-packages` section. .. toctree:: From python-checkins at python.org Sat Aug 4 09:22:22 2007 From: python-checkins at python.org (georg.brandl) Date: Sat, 4 Aug 2007 09:22:22 +0200 (CEST) Subject: [Python-checkins] r56730 - in doctools/trunk: Doc-26/documenting/rest.rst Doc-26/documenting/style.rst Doc-3k/documenting/rest.rst Doc-3k/documenting/style.rst Doc-3k/library/os.rst Doc-3k/library/tk.rst Doc-3k/library/zipfile.rst Message-ID: <20070804072222.E5E2E1E400B@bag.python.org> Author: georg.brandl Date: Sat Aug 4 09:22:22 2007 New Revision: 56730 Modified: doctools/trunk/Doc-26/documenting/rest.rst doctools/trunk/Doc-26/documenting/style.rst doctools/trunk/Doc-3k/documenting/rest.rst doctools/trunk/Doc-3k/documenting/style.rst doctools/trunk/Doc-3k/library/os.rst doctools/trunk/Doc-3k/library/tk.rst doctools/trunk/Doc-3k/library/zipfile.rst Log: Merge 56702-56729 and write a bit on reST source style guide. Modified: doctools/trunk/Doc-26/documenting/rest.rst ============================================================================== --- doctools/trunk/Doc-26/documenting/rest.rst (original) +++ doctools/trunk/Doc-26/documenting/rest.rst Sat Aug 4 09:22:22 2007 @@ -22,8 +22,6 @@ is significant in reST, so all lines of the same paragraph must be left-aligned to the same level of indentation. -The Python docs use an indentation of 3 spaces. - Inline markup ------------- @@ -250,4 +248,4 @@ separated from the surrounding text by non-word characters, you have to use an escaped space to get around that. -.. XXX more? \ No newline at end of file +.. XXX more? Modified: doctools/trunk/Doc-26/documenting/style.rst ============================================================================== --- doctools/trunk/Doc-26/documenting/style.rst (original) +++ doctools/trunk/Doc-26/documenting/style.rst Sat Aug 4 09:22:22 2007 @@ -7,10 +7,15 @@ wherever possible. This particular style guide was selected mostly because it seems reasonable and is easy to get online. -.. _Apple Publications Style Guide: http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/AppleStyleGuide2003.pdf - Topics which are not covered in the Apple's style guide will be discussed in -this document if necessary. +this document. + +All reST files use an indentation of 3 spaces. The maximum line length is 80 +characters for normal text, but tables, deeply indented code samples and long +links may extend beyond that. + +Make generous use of blank lines where applicable; they help grouping things +together. Footnotes are generally discouraged, though they may be used when they are the best way to present specific information. When a footnote reference is added at @@ -20,8 +25,8 @@ This sentence has a footnote reference. [#]_ This is the next sentence. Footnotes should be gathered at the end of a file, or if the file is very long, -at the end of a section. The docutils will automatically create backlinks to the -footnote reference. +at the end of a section. The docutils will automatically create backlinks to +the footnote reference. Footnotes may appear in the middle of sentences where appropriate. @@ -54,4 +59,8 @@ Unix The name of the operating system developed at AT&T Bell Labs in the early - 1970s. \ No newline at end of file + 1970s. + + +.. _Apple Publications Style Guide: http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/AppleStyleGuide2003.pdf + Modified: doctools/trunk/Doc-3k/documenting/rest.rst ============================================================================== --- doctools/trunk/Doc-3k/documenting/rest.rst (original) +++ doctools/trunk/Doc-3k/documenting/rest.rst Sat Aug 4 09:22:22 2007 @@ -22,8 +22,6 @@ is significant in reST, so all lines of the same paragraph must be left-aligned to the same level of indentation. -The Python docs use an indentation of 3 spaces. - Inline markup ------------- @@ -250,4 +248,4 @@ separated from the surrounding text by non-word characters, you have to use an escaped space to get around that. -.. XXX more? \ No newline at end of file +.. XXX more? Modified: doctools/trunk/Doc-3k/documenting/style.rst ============================================================================== --- doctools/trunk/Doc-3k/documenting/style.rst (original) +++ doctools/trunk/Doc-3k/documenting/style.rst Sat Aug 4 09:22:22 2007 @@ -7,10 +7,15 @@ wherever possible. This particular style guide was selected mostly because it seems reasonable and is easy to get online. -.. _Apple Publications Style Guide: http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/AppleStyleGuide2003.pdf - Topics which are not covered in the Apple's style guide will be discussed in -this document if necessary. +this document. + +All reST files use an indentation of 3 spaces. The maximum line length is 80 +characters for normal text, but tables, deeply indented code samples and long +links may extend beyond that. + +Make generous use of blank lines where applicable; they help grouping things +together. Footnotes are generally discouraged, though they may be used when they are the best way to present specific information. When a footnote reference is added at @@ -20,8 +25,8 @@ This sentence has a footnote reference. [#]_ This is the next sentence. Footnotes should be gathered at the end of a file, or if the file is very long, -at the end of a section. The docutils will automatically create backlinks to the -footnote reference. +at the end of a section. The docutils will automatically create backlinks to +the footnote reference. Footnotes may appear in the middle of sentences where appropriate. @@ -54,4 +59,8 @@ Unix The name of the operating system developed at AT&T Bell Labs in the early - 1970s. \ No newline at end of file + 1970s. + + +.. _Apple Publications Style Guide: http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/AppleStyleGuide2003.pdf + Modified: doctools/trunk/Doc-3k/library/os.rst ============================================================================== --- doctools/trunk/Doc-3k/library/os.rst (original) +++ doctools/trunk/Doc-3k/library/os.rst Sat Aug 4 09:22:22 2007 @@ -8,7 +8,8 @@ This module provides a more portable way of using operating system dependent functionality than importing a operating system dependent built-in module like -:mod:`posix` or :mod:`nt`. +:mod:`posix` or :mod:`nt`. (If you just want to read or write a file see +:func:`open`.) This module searches for an operating system dependent built-in module like :mod:`mac` or :mod:`posix` and exports the same functions and data as found @@ -348,7 +349,7 @@ File Object Creation -------------------- -These functions create new file objects. +These functions create new file objects. (See also :func:`open`.) .. function:: fdopen(fd[, mode[, bufsize]]) @@ -775,51 +776,52 @@ following values (as defined in the :mod:`stat` module) or bitwise or-ed combinations of them: -* ``S_ISUID`` +* ``stat.S_ISUID`` -* ``S_ISGID`` +* ``stat.S_ISGID`` -* ``S_ENFMT`` +* ``stat.S_ENFMT`` -* ``S_ISVTX`` +* ``stat.S_ISVTX`` -* ``S_IREAD`` +* ``stat.S_IREAD`` -* ``S_IWRITE`` +* ``stat.S_IWRITE`` -* ``S_IEXEC`` +* ``stat.S_IEXEC`` -* ``S_IRWXU`` +* ``stat.S_IRWXU`` -* ``S_IRUSR`` +* ``stat.S_IRUSR`` -* ``S_IWUSR`` +* ``stat.S_IWUSR`` -* ``S_IXUSR`` +* ``stat.S_IXUSR`` -* ``S_IRWXG`` +* ``stat.S_IRWXG`` -* ``S_IRGRP`` +* ``stat.S_IRGRP`` -* ``S_IWGRP`` +* ``stat.S_IWGRP`` -* ``S_IXGRP`` +* ``stat.S_IXGRP`` -* ``S_IRWXO`` +* ``stat.S_IRWXO`` -* ``S_IROTH`` +* ``stat.S_IROTH`` -* ``S_IWOTH`` +* ``stat.S_IWOTH`` -* ``S_IXOTH`` +* ``stat.S_IXOTH`` Availability: Macintosh, Unix, Windows. .. note:: Although Windows supports :func:`chmod`, you can only set the file's read-only - flag with it (via the ``S_IWRITE`` and ``S_IREAD`` constants or a corresponding - integer value). All other bits are ignored. + flag with it (via the ``stat.S_IWRITE`` and ``stat.S_IREAD`` + constants or a corresponding integer value). All other bits are + ignored. .. function:: chown(path, uid, gid) @@ -884,9 +886,11 @@ Create a filesystem node (file, device special file or named pipe) named *filename*. *mode* specifies both the permissions to use and the type of node to - be created, being combined (bitwise OR) with one of S_IFREG, S_IFCHR, S_IFBLK, - and S_IFIFO (those constants are available in :mod:`stat`). For S_IFCHR and - S_IFBLK, *device* defines the newly created device special file (probably using + be created, being combined (bitwise OR) with one of ``stat.S_IFREG``, + ``stat.S_IFCHR``, ``stat.S_IFBLK``, + and ``stat.S_IFIFO`` (those constants are available in :mod:`stat`). + For ``stat.S_IFCHR`` and + ``stat.S_IFBLK``, *device* defines the newly created device special file (probably using :func:`os.makedev`), otherwise it is ignored. .. versionadded:: 2.3 Modified: doctools/trunk/Doc-3k/library/tk.rst ============================================================================== --- doctools/trunk/Doc-3k/library/tk.rst (original) +++ doctools/trunk/Doc-3k/library/tk.rst Sat Aug 4 09:22:22 2007 @@ -21,8 +21,11 @@ classes. In addition, the internal module :mod:`_tkinter` provides a threadsafe mechanism which allows Python and Tcl to interact. -Tk is not the only GUI for Python; see section :ref:`other-gui-packages` for -more information on other GUI toolkits for Python. +:mod:`Tkinter`'s chief virtues are that it is fast, and that it usually comes +bundled with Python. Although it has been used to create some very good +applications, including IDLE, it has weak documentation and an outdated look and +feel. For more modern, better documented, and much more extensive GUI +libraries, see the :ref:`other-gui-packages` section. .. toctree:: Modified: doctools/trunk/Doc-3k/library/zipfile.rst ============================================================================== --- doctools/trunk/Doc-3k/library/zipfile.rst (original) +++ doctools/trunk/Doc-3k/library/zipfile.rst Sat Aug 4 09:22:22 2007 @@ -85,7 +85,7 @@ Documentation on the ZIP file format by Phil Katz, the creator of the format and algorithms used. - `Info-ZIP Home Page `_ + `Info-ZIP Home Page `_ Information about the Info-ZIP project's ZIP archive programs and development libraries. From python-checkins at python.org Sat Aug 4 10:01:07 2007 From: python-checkins at python.org (mark.summerfield) Date: Sat, 4 Aug 2007 10:01:07 +0200 (CEST) Subject: [Python-checkins] r56731 - doctools/trunk/Doc-26/library/othergui.rst Message-ID: <20070804080107.B11FD1E400B@bag.python.org> Author: mark.summerfield Date: Sat Aug 4 10:01:07 2007 New Revision: 56731 Modified: doctools/trunk/Doc-26/library/othergui.rst Log: Deleted comment: XXX Reference URLs that compare the different UI packages They are too changeable, so instead I've added a reference to the Python Wiki page which has such links. Dropped coverage of PyKDE because it is platform-specific. I think it is best to only list cross-platform GUI libraries here and leave people to go to the Wiki for platform-specific GUI libraries. Dropped the listing for FXPy since its website hasn't been updated since 2002 and its most "up-to-date" installer for Windows is for Python 2.2! Slightly slimmed down wxWidgets coverage for balance. So now only the "big 3" cross-platform toolkits, PyGTK, PyQt, and wxPython, are listed, and they now appear in alphabetical order. Modified: doctools/trunk/Doc-26/library/othergui.rst ============================================================================== --- doctools/trunk/Doc-26/library/othergui.rst (original) +++ doctools/trunk/Doc-26/library/othergui.rst Sat Aug 4 10:01:07 2007 @@ -31,63 +31,54 @@ .. % -Other GUI packages are also available for Python: +The major cross-platform (Windows, Mac OS X, Unix-like) GUI toolkits that are +also available for Python: .. seealso:: + `PyGTK `_ + is a set of bindings for the `GTK `_ widget set. It + provides an object oriented interface that is slightly higher level than the C + one. It comes with many more widgets than Tkinter provides, and + has good Python-specific reference documentation. There are also `bindings + `_ to `GNOME `_. + One well known PyGTK application is + `PythonCAD `_. An + online `tutorial `_ is + available. + + `PyQt `_ + PyQt is a :program:`sip`\ -wrapped binding to the Qt toolkit. Qt is an + extensive C++ GUI application development framework that is + available for Unix, Windows and Mac OS X. :program:`sip` is a tool + for generating bindings for C++ libraries as Python classes, and + is specifically designed for Python. The *PyQt3* bindings have a + book, `GUI Programming with Python: QT Edition + `_ by Boudewijn + Rempt. The *PyQt4* bindings also have a book, `Rapid GUI Programming + with Python and Qt `_, by Mark + Summerfield. + `wxPython `_ wxPython is a cross-platform GUI toolkit for Python that is built around the - popular `wxWidgets `_ C++ toolkit. ?It provides a + popular `wxWidgets `_ (formerly + wxWindows) C++ toolkit. ?It provides a native look and feel for applications on Windows, Mac OS X, and Unix systems by using each platform's native widgets where ever possible, (GTK+ on Unix-like systems). ?In addition to an extensive set of widgets, wxPython provides classes for online documentation and context sensitive help, printing, HTML viewing, low-level device context drawing, drag and drop, system clipboard access, an XML-based resource format and more, including an ever growing library of user- - contributed modules. ?Both the wxWidgets and wxPython projects are under active - development and continuous improvement, and have active and helpful user and - developer communities. - - `wxPython in Action `_ - The wxPython book, by Noel Rappin and Robin Dunn. - - PyQt - PyQt is a :program:`sip`\ -wrapped binding to the Qt toolkit. Qt is an - extensive C++ GUI toolkit that is available for Unix, Windows and Mac OS X. - :program:`sip` is a tool for generating bindings for C++ libraries as Python - classes, and is specifically designed for Python. An online manual is available - at http://www.opendocspublishing.com/pyqt/ (errata are located at - http://www.valdyas.org/python/book.html). - - `PyKDE `_ - PyKDE is a :program:`sip`\ -wrapped interface to the KDE desktop libraries. KDE - is a desktop environment for Unix computers; the graphical components are based - on Qt. - - `FXPy `_ - is a Python extension module which provides an interface to the `FOX - `_ GUI. FOX is a C++ based Toolkit for - developing Graphical User Interfaces easily and effectively. It offers a wide, - and growing, collection of Controls, and provides state of the art facilities - such as drag and drop, selection, as well as OpenGL widgets for 3D graphical - manipulation. FOX also implements icons, images, and user-convenience features - such as status line help, and tooltips. - - Even though FOX offers a large collection of controls already, FOX leverages C++ - to allow programmers to easily build additional Controls and GUI elements, - simply by taking existing controls, and creating a derived class which simply - adds or redefines the desired behavior. - - `PyGTK `_ - is a set of bindings for the `GTK `_ widget set. It - provides an object oriented interface that is slightly higher level than the C - one. It automatically does all the type casting and reference counting that you - would have to do normally with the C API. There are also `bindings - `_ to `GNOME `_, and - a `tutorial - `_ is - available. - -.. % XXX Reference URLs that compare the different UI packages + contributed modules. ?wxPython has a book, + `wxPython in Action `_, + by Noel Rappin and Robin Dunn. + +PyGTK, PyQt, and wxPython, all have a modern look and feel and far more +widgets and better documentation than Tkinter. In addition, +there are many other GUI toolkits for Python, both cross-platform, and +platform-specific. See the `GUI Programming +`_ page in the Python Wiki for a +much more complete list, and also for links to documents where the +different GUI toolkits are compared. From python-checkins at python.org Sat Aug 4 16:33:17 2007 From: python-checkins at python.org (georg.brandl) Date: Sat, 4 Aug 2007 16:33:17 +0200 (CEST) Subject: [Python-checkins] r56732 - doctools/trunk/sphinx/directives.py Message-ID: <20070804143317.0B3F81E4017@bag.python.org> Author: georg.brandl Date: Sat Aug 4 16:33:16 2007 New Revision: 56732 Modified: doctools/trunk/sphinx/directives.py Log: Add the module name to module globals' descriptions. Modified: doctools/trunk/sphinx/directives.py ============================================================================== --- doctools/trunk/sphinx/directives.py (original) +++ doctools/trunk/sphinx/directives.py Sat Aug 4 16:33:16 2007 @@ -113,9 +113,9 @@ py_paramlist_re = re.compile(r'([\[\],])') # split at '[', ']' and ',' -def parse_py_signature(signode, sig, desctype, currclass): +def parse_py_signature(signode, sig, desctype, currmodule, currclass): """ - Transform a python signature into RST nodes. Returns (signode, fullname). + Transform a python signature into RST nodes. Return the fully qualified name of the thing. If inside a class, the current class name is handled intelligently: @@ -139,6 +139,12 @@ if classname: signode += addnodes.desc_classname(classname, classname) + # only add the module name for module globals + # exceptions are a special case, since they are documented in the + # 'exceptions' module. + elif currmodule and currmodule != 'exceptions': + signode += addnodes.desc_classname(currmodule+'.', currmodule+'.') + signode += addnodes.desc_name(name, name) if not arglist: if desctype in ('function', 'method'): @@ -282,7 +288,8 @@ try: if desctype in ('function', 'data', 'class', 'exception', 'method', 'attribute'): - name = parse_py_signature(signode, sig, desctype, env.currclass) + name = parse_py_signature(signode, sig, desctype, + env.currmodule, env.currclass) elif desctype in ('cfunction', 'cmember', 'cmacro', 'ctype', 'cvar'): name = parse_c_signature(signode, sig, desctype) elif desctype == 'opcode': From python-checkins at python.org Sat Aug 4 16:42:00 2007 From: python-checkins at python.org (georg.brandl) Date: Sat, 4 Aug 2007 16:42:00 +0200 (CEST) Subject: [Python-checkins] r56733 - doctools/trunk/sphinx/style/default.css Message-ID: <20070804144200.41D0D1E400D@bag.python.org> Author: georg.brandl Date: Sat Aug 4 16:41:59 2007 New Revision: 56733 Modified: doctools/trunk/sphinx/style/default.css Log: Make admonitions take less space. Modified: doctools/trunk/sphinx/style/default.css ============================================================================== --- doctools/trunk/sphinx/style/default.css (original) +++ doctools/trunk/sphinx/style/default.css Sat Aug 4 16:41:59 2007 @@ -582,7 +582,7 @@ div.admonition { margin-top: 10px; margin-bottom: 10px; - padding: 10px 10px 0px 10px; + padding: 7px; } div.admonition dt { @@ -593,6 +593,10 @@ margin-bottom: 10px; } +div.admonition p { + display: inline; +} + div.seealso { background-color: #ffc; border: 1px solid #ff6; @@ -609,9 +613,10 @@ } p.admonition-title { - margin: 0px 0px 5px 0px; + margin: 0px 10px 5px 0px; font-weight: bold; - font-size: 1.1em; + display: inline; + font-size: 1em; } table.docutils { From python-checkins at python.org Sat Aug 4 16:42:35 2007 From: python-checkins at python.org (georg.brandl) Date: Sat, 4 Aug 2007 16:42:35 +0200 (CEST) Subject: [Python-checkins] r56734 - doctools/trunk/Doc-3k/library/othergui.rst Message-ID: <20070804144235.751FA1E400D@bag.python.org> Author: georg.brandl Date: Sat Aug 4 16:42:35 2007 New Revision: 56734 Modified: doctools/trunk/Doc-3k/library/othergui.rst Log: Merge rev 56731 to 3k tree. Modified: doctools/trunk/Doc-3k/library/othergui.rst ============================================================================== --- doctools/trunk/Doc-3k/library/othergui.rst (original) +++ doctools/trunk/Doc-3k/library/othergui.rst Sat Aug 4 16:42:35 2007 @@ -31,63 +31,54 @@ .. % -Other GUI packages are also available for Python: +The major cross-platform (Windows, Mac OS X, Unix-like) GUI toolkits that are +also available for Python: .. seealso:: + `PyGTK `_ + is a set of bindings for the `GTK `_ widget set. It + provides an object oriented interface that is slightly higher level than the C + one. It comes with many more widgets than Tkinter provides, and + has good Python-specific reference documentation. There are also `bindings + `_ to `GNOME `_. + One well known PyGTK application is + `PythonCAD `_. An + online `tutorial `_ is + available. + + `PyQt `_ + PyQt is a :program:`sip`\ -wrapped binding to the Qt toolkit. Qt is an + extensive C++ GUI application development framework that is + available for Unix, Windows and Mac OS X. :program:`sip` is a tool + for generating bindings for C++ libraries as Python classes, and + is specifically designed for Python. The *PyQt3* bindings have a + book, `GUI Programming with Python: QT Edition + `_ by Boudewijn + Rempt. The *PyQt4* bindings also have a book, `Rapid GUI Programming + with Python and Qt `_, by Mark + Summerfield. + `wxPython `_ wxPython is a cross-platform GUI toolkit for Python that is built around the - popular `wxWidgets `_ C++ toolkit. ?It provides a + popular `wxWidgets `_ (formerly + wxWindows) C++ toolkit. ?It provides a native look and feel for applications on Windows, Mac OS X, and Unix systems by using each platform's native widgets where ever possible, (GTK+ on Unix-like systems). ?In addition to an extensive set of widgets, wxPython provides classes for online documentation and context sensitive help, printing, HTML viewing, low-level device context drawing, drag and drop, system clipboard access, an XML-based resource format and more, including an ever growing library of user- - contributed modules. ?Both the wxWidgets and wxPython projects are under active - development and continuous improvement, and have active and helpful user and - developer communities. - - `wxPython in Action `_ - The wxPython book, by Noel Rappin and Robin Dunn. - - PyQt - PyQt is a :program:`sip`\ -wrapped binding to the Qt toolkit. Qt is an - extensive C++ GUI toolkit that is available for Unix, Windows and Mac OS X. - :program:`sip` is a tool for generating bindings for C++ libraries as Python - classes, and is specifically designed for Python. An online manual is available - at http://www.opendocspublishing.com/pyqt/ (errata are located at - http://www.valdyas.org/python/book.html). - - `PyKDE `_ - PyKDE is a :program:`sip`\ -wrapped interface to the KDE desktop libraries. KDE - is a desktop environment for Unix computers; the graphical components are based - on Qt. - - `FXPy `_ - is a Python extension module which provides an interface to the `FOX - `_ GUI. FOX is a C++ based Toolkit for - developing Graphical User Interfaces easily and effectively. It offers a wide, - and growing, collection of Controls, and provides state of the art facilities - such as drag and drop, selection, as well as OpenGL widgets for 3D graphical - manipulation. FOX also implements icons, images, and user-convenience features - such as status line help, and tooltips. - - Even though FOX offers a large collection of controls already, FOX leverages C++ - to allow programmers to easily build additional Controls and GUI elements, - simply by taking existing controls, and creating a derived class which simply - adds or redefines the desired behavior. - - `PyGTK `_ - is a set of bindings for the `GTK `_ widget set. It - provides an object oriented interface that is slightly higher level than the C - one. It automatically does all the type casting and reference counting that you - would have to do normally with the C API. There are also `bindings - `_ to `GNOME `_, and - a `tutorial - `_ is - available. - -.. % XXX Reference URLs that compare the different UI packages + contributed modules. ?wxPython has a book, + `wxPython in Action `_, + by Noel Rappin and Robin Dunn. + +PyGTK, PyQt, and wxPython, all have a modern look and feel and far more +widgets and better documentation than Tkinter. In addition, +there are many other GUI toolkits for Python, both cross-platform, and +platform-specific. See the `GUI Programming +`_ page in the Python Wiki for a +much more complete list, and also for links to documents where the +different GUI toolkits are compared. From python-checkins at python.org Sat Aug 4 17:48:24 2007 From: python-checkins at python.org (facundo.batista) Date: Sat, 4 Aug 2007 17:48:24 +0200 (CEST) Subject: [Python-checkins] r56735 - python/branches/decimal-branch/Lib/decimal.py Message-ID: <20070804154824.893B11E401D@bag.python.org> Author: facundo.batista Date: Sat Aug 4 17:48:24 2007 New Revision: 56735 Modified: python/branches/decimal-branch/Lib/decimal.py Log: Coded the compare_total() function. All tests pass ok. Modified: python/branches/decimal-branch/Lib/decimal.py ============================================================================== --- python/branches/decimal-branch/Lib/decimal.py (original) +++ python/branches/decimal-branch/Lib/decimal.py Sat Aug 4 17:48:24 2007 @@ -2322,6 +2322,66 @@ value. Note that a total ordering is defined for all possible abstract representations. """ + # if one is negative and the other is positive, it's easy + if self._sign and not other._sign: + return Decimal(-1) + if not self._sign and other._sign: + return Decimal(1) + sign = self._sign + + # let's handle both NaN types + self_nan = self._isnan() + other_nan = other._isnan() + if self_nan or other_nan: + if self_nan == other_nan: + if self._int < other._int: + if sign: + return Decimal(1) + else: + return Decimal(-1) + if self._int > other._int: + if sign: + return Decimal(-1) + else: + return Decimal(1) + return Decimal(0) + + if sign: + if self_nan == 1: + return Decimal(-1) + if other_nan == 1: + return Decimal(1) + if self_nan == 2: + return Decimal(-1) + if other_nan == 2: + return Decimal(1) + else: + if self_nan == 1: + return Decimal(1) + if other_nan == 1: + return Decimal(-1) + if self_nan == 2: + return Decimal(1) + if other_nan == 2: + return Decimal(-1) + + if self < other: + return Decimal(-1) + if self > other: + return Decimal(1) + + if self._exp < other._exp: + if sign: + return Decimal(1) + else: + return Decimal(-1) + if self._exp > other._exp: + if sign: + return Decimal(-1) + else: + return Decimal(1) + return Decimal(0) + def compare_total_mag (self, other, context=None): """Compares self to other using abstract repr., ignoring sign. From python-checkins at python.org Sat Aug 4 17:55:16 2007 From: python-checkins at python.org (georg.brandl) Date: Sat, 4 Aug 2007 17:55:16 +0200 (CEST) Subject: [Python-checkins] r56736 - in doctools/trunk/sphinx: style/default.css web/application.py Message-ID: <20070804155516.DF32E1E401E@bag.python.org> Author: georg.brandl Date: Sat Aug 4 17:55:16 2007 New Revision: 56736 Modified: doctools/trunk/sphinx/style/default.css doctools/trunk/sphinx/web/application.py Log: Further style nit and fix a missing import error. Modified: doctools/trunk/sphinx/style/default.css ============================================================================== --- doctools/trunk/sphinx/style/default.css (original) +++ doctools/trunk/sphinx/style/default.css Sat Aug 4 17:55:16 2007 @@ -589,8 +589,8 @@ font-weight: bold; } -div.admonition dd { - margin-bottom: 10px; +div.admonition dl { + margin-bottom: 0; } div.admonition p { @@ -616,7 +616,6 @@ margin: 0px 10px 5px 0px; font-weight: bold; display: inline; - font-size: 1em; } table.docutils { Modified: doctools/trunk/sphinx/web/application.py ============================================================================== --- doctools/trunk/sphinx/web/application.py (original) +++ doctools/trunk/sphinx/web/application.py Sat Aug 4 17:55:16 2007 @@ -768,7 +768,7 @@ pw2 = getpass.getpass('Enter password again: ') if pw1 != pw2: print 'Error: Passwords don\'t match.' - sys.exit(1) + raise SystemExit(1) app.userdb.set_password('admin', pw1) app.userdb.privileges['admin'].add('master') app.userdb.save() From python-checkins at python.org Sat Aug 4 19:16:56 2007 From: python-checkins at python.org (georg.brandl) Date: Sat, 4 Aug 2007 19:16:56 +0200 (CEST) Subject: [Python-checkins] r56738 - in doctools/trunk: Doc-26/conf.py Doc-3k/conf.py sphinx/builder.py sphinx/templates/index.html sphinx/templates/sidebar.html Message-ID: <20070804171656.E92BE1E400D@bag.python.org> Author: georg.brandl Date: Sat Aug 4 19:16:56 2007 New Revision: 56738 Modified: doctools/trunk/Doc-26/conf.py doctools/trunk/Doc-3k/conf.py doctools/trunk/sphinx/builder.py doctools/trunk/sphinx/templates/index.html doctools/trunk/sphinx/templates/sidebar.html Log: Replace some XXXs on the index page. Port the download page, still needs to be populated. Modified: doctools/trunk/Doc-26/conf.py ============================================================================== --- doctools/trunk/Doc-26/conf.py (original) +++ doctools/trunk/Doc-26/conf.py Sat Aug 4 19:16:56 2007 @@ -46,3 +46,6 @@ # If true, '()' will be appended to :func: etc. cross-reference text. add_function_parentheses = True + +# The base URL for download links. +download_base_url = 'http://docs.python.org/ftp/python/doc/' Modified: doctools/trunk/Doc-3k/conf.py ============================================================================== --- doctools/trunk/Doc-3k/conf.py (original) +++ doctools/trunk/Doc-3k/conf.py Sat Aug 4 19:16:56 2007 @@ -47,3 +47,6 @@ # If true, '()' will be appended to :func: etc. cross-reference text. add_function_parentheses = True + +# The base URL for download links. +download_base_url = 'http://docs.python.org/ftp/python/doc/' Modified: doctools/trunk/sphinx/builder.py ============================================================================== --- doctools/trunk/sphinx/builder.py (original) +++ doctools/trunk/sphinx/builder.py Sat Aug 4 19:16:56 2007 @@ -441,6 +441,14 @@ ) self.handle_file('modindex.rst', modindexcontext, 'modindex') + # the download page + downloadcontext = dict( + pathto = relpath_to(self, self.get_target_uri('download.rst')), + current_page_name = 'download', + download_base_url = self.config['download_base_url'], + ) + self.handle_file('download.rst', downloadcontext, 'download') + # the index page indexcontext = dict( pathto = relpath_to(self, self.get_target_uri('index.rst')), Modified: doctools/trunk/sphinx/templates/index.html ============================================================================== --- doctools/trunk/sphinx/templates/index.html (original) +++ doctools/trunk/sphinx/templates/index.html Sat Aug 4 19:16:56 2007 @@ -1,6 +1,5 @@ {% extends "layout.html" %} {% set title = 'Overview' %} -{% set current_page_name = 'index' %} {% set page_links = [ (pathto('@rss/recent'), 'application/rss+xml', 'Recent Comments') ] %} Modified: doctools/trunk/sphinx/templates/sidebar.html ============================================================================== --- doctools/trunk/sphinx/templates/sidebar.html (original) +++ doctools/trunk/sphinx/templates/sidebar.html Sat Aug 4 19:16:56 2007 @@ -28,13 +28,24 @@ {% endif %} {% if current_page_name == "index" %}

      Download

      -

      - XXX: Add download links here. -

      -

      Old docs

      -

      - XXX: Add links to old docs/essays/etc. here. -

      +

      Download these documents

      +

      Other resources

      + {% endif %} {% if current_page_name != "search" %}

      {{ builder == 'web' and 'Keyword' or 'Quick' }} search

      From python-checkins at python.org Sat Aug 4 20:17:52 2007 From: python-checkins at python.org (georg.brandl) Date: Sat, 4 Aug 2007 20:17:52 +0200 (CEST) Subject: [Python-checkins] r56741 - in doctools/trunk: Doc-26/library/functions.rst Doc-3k/library/functions.rst sphinx/style/default.css sphinx/style/traditional.css Message-ID: <20070804181752.037541E401B@bag.python.org> Author: georg.brandl Date: Sat Aug 4 20:17:51 2007 New Revision: 56741 Modified: doctools/trunk/Doc-26/library/functions.rst doctools/trunk/Doc-3k/library/functions.rst doctools/trunk/sphinx/style/default.css doctools/trunk/sphinx/style/traditional.css Log: Update traditional stylesheet, fix a markup glitch. Modified: doctools/trunk/Doc-26/library/functions.rst ============================================================================== --- doctools/trunk/Doc-26/library/functions.rst (original) +++ doctools/trunk/Doc-26/library/functions.rst Sat Aug 4 20:17:51 2007 @@ -298,13 +298,13 @@ objects, as it attempts to produce the most relevant, rather than complete, information: -* If the object is a module object, the list contains the names of the module's + * If the object is a module object, the list contains the names of the module's attributes. -* If the object is a type or class object, the list contains the names of its + * If the object is a type or class object, the list contains the names of its attributes, and recursively of the attributes of its bases. -* Otherwise, the list contains the object's attributes' names, the names of its + * Otherwise, the list contains the object's attributes' names, the names of its class's attributes, and recursively of the attributes of its class's base classes. Modified: doctools/trunk/Doc-3k/library/functions.rst ============================================================================== --- doctools/trunk/Doc-3k/library/functions.rst (original) +++ doctools/trunk/Doc-3k/library/functions.rst Sat Aug 4 20:17:51 2007 @@ -297,13 +297,13 @@ objects, as it attempts to produce the most relevant, rather than complete, information: -* If the object is a module object, the list contains the names of the module's + * If the object is a module object, the list contains the names of the module's attributes. -* If the object is a type or class object, the list contains the names of its + * If the object is a type or class object, the list contains the names of its attributes, and recursively of the attributes of its bases. -* Otherwise, the list contains the object's attributes' names, the names of its + * Otherwise, the list contains the object's attributes' names, the names of its class's attributes, and recursively of the attributes of its class's base classes. Modified: doctools/trunk/sphinx/style/default.css ============================================================================== --- doctools/trunk/sphinx/style/default.css (original) +++ doctools/trunk/sphinx/style/default.css Sat Aug 4 20:17:51 2007 @@ -268,6 +268,7 @@ div#comments { border: 1px solid #2eabb0; + margin-top: 20px; } div#comments div.nocomments { @@ -577,6 +578,21 @@ font-weight: bold; } +/* "Topics" */ + +div.topic { + background-color: #eee; + border: 1px solid #ccc; + padding: 0 7px 0 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + /* Admonitions */ div.admonition { @@ -618,12 +634,16 @@ display: inline; } +p.admonition-title:after { + content: ":"; +} + table.docutils { border: 0; } table.docutils td, table.docutils th { - margin: 2px; + padding: 0 8px 2px 0; border-top: 0; border-left: 0; border-right: 0; Modified: doctools/trunk/sphinx/style/traditional.css ============================================================================== --- doctools/trunk/sphinx/style/traditional.css (original) +++ doctools/trunk/sphinx/style/traditional.css Sat Aug 4 20:17:51 2007 @@ -483,12 +483,27 @@ font-weight: bold; } +/* "Topics" */ + +div.topic { + background-color: #eee; + border: 1px solid #ccc; + padding: 0 7px 0 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + /* Admonitions */ div.admonition { margin-top: 10px; margin-bottom: 10px; - padding: 10px 10px 0px 10px; + padding: 7px; } div.admonition dt { @@ -499,6 +514,14 @@ margin-bottom: 10px; } +div.admonition dl { + margin-bottom: 0; +} + +div.admonition p { + display: inline; +} + div.seealso { background-color: #ffc; border: 1px solid #ff6; @@ -515,9 +538,13 @@ } p.admonition-title { - margin: 0px 0px 5px 0px; + margin: 0px 10px 5px 0px; font-weight: bold; - font-size: 1.1em; + display: inline; +} + +p.admonition-title:after { + content: ":"; } table.docutils { @@ -525,7 +552,7 @@ } table.docutils td, table.docutils th { - margin: 2px; + padding: 0 8px 2px 0; border-top: 0; border-left: 0; border-right: 0; From python-checkins at python.org Sun Aug 5 00:45:58 2007 From: python-checkins at python.org (georg.brandl) Date: Sun, 5 Aug 2007 00:45:58 +0200 (CEST) Subject: [Python-checkins] r56744 - in doctools/trunk: Doc-26/c-api/abstract.rst Doc-26/c-api/concrete.rst Doc-26/c-api/init.rst Doc-26/c-api/intro.rst Doc-26/c-api/newtypes.rst Doc-26/c-api/utilities.rst Doc-26/distutils/apiref.rst Doc-26/extending/building.rst Doc-26/extending/extending.rst Doc-26/extending/newtypes.rst Doc-26/howto/advocacy.rst Doc-26/howto/curses.rst Doc-26/howto/doanddont.rst Doc-26/howto/functional.rst Doc-26/howto/regex.rst Doc-26/howto/sockets.rst Doc-26/howto/urllib2.rst Doc-26/install/index.rst Doc-26/library/_winreg.rst Doc-26/library/asyncore.rst Doc-26/library/binascii.rst Doc-26/library/bz2.rst Doc-26/library/cgi.rst Doc-26/library/chunk.rst Doc-26/library/cmath.rst Doc-26/library/code.rst Doc-26/library/codecs.rst Doc-26/library/codeop.rst Doc-26/library/cookie.rst Doc-26/library/cookielib.rst Doc-26/library/csv.rst Doc-26/library/ctypes.rst Doc-26/library/curses.rst Doc-26/library/datetime.rst Doc-26/library/decimal.rst Doc-26/library/difflib.rst Doc-26/library/dis.rst Doc-26/library/dl.rst Doc-26/library/doctest.rst Doc-26/library/email.charset.rst Doc-26/library/email.generator.rst Doc-26/library/email.message.rst Doc-26/library/email.parser.rst Doc-26/library/errno.rst Doc-26/library/fcntl.rst Doc-26/library/formatter.rst Doc-26/library/fpectl.rst Doc-26/library/functions.rst Doc-26/library/gdbm.rst Doc-26/library/getopt.rst Doc-26/library/gettext.rst Doc-26/library/httplib.rst Doc-26/library/imageop.rst Doc-26/library/imaplib.rst Doc-26/library/imp.rst Doc-26/library/inspect.rst Doc-26/library/itertools.rst Doc-26/library/logging.rst Doc-26/library/mailbox.rst Doc-26/library/math.rst Doc-26/library/mimetypes.rst Doc-26/library/mimify.rst Doc-26/library/mmap.rst Doc-26/library/msilib.rst Doc-26/library/multifile.rst Doc-26/library/netrc.rst Doc-26/library/new.rst Doc-26/library/nntplib.rst Doc-26/library/optparse.rst Doc-26/library/os.rst Doc-26/library/ossaudiodev.rst Doc-26/library/othergui.rst Doc-26/library/parser.rst Doc-26/library/pickle.rst Doc-26/library/profile.rst Doc-26/library/pyexpat.rst Doc-26/library/random.rst Doc-26/library/re.rst Doc-26/library/repr.rst Doc-26/library/rfc822.rst Doc-26/library/select.rst Doc-26/library/sgmllib.rst Doc-26/library/shelve.rst Doc-26/library/shlex.rst Doc-26/library/simplehttpserver.rst Doc-26/library/simplexmlrpcserver.rst Doc-26/library/site.rst Doc-26/library/socket.rst Doc-26/library/socketserver.rst Doc-26/library/sqlite3.rst Doc-26/library/stdtypes.rst Doc-26/library/string.rst Doc-26/library/stringprep.rst Doc-26/library/struct.rst Doc-26/library/sys.rst Doc-26/library/tempfile.rst Doc-26/library/termios.rst Doc-26/library/textwrap.rst Doc-26/library/threading.rst Doc-26/library/timeit.rst Doc-26/library/tix.rst Doc-26/library/tkinter.rst Doc-26/library/turtle.rst Doc-26/library/urllib.rst Doc-26/library/urllib2.rst Doc-26/library/user.rst Doc-26/library/winsound.rst Doc-26/library/wsgiref.rst Doc-26/library/xml.dom.rst Doc-26/library/xml.etree.elementtree.rst Doc-26/library/xml.sax.handler.rst Doc-26/library/xml.sax.reader.rst Doc-26/library/xml.sax.utils.rst Doc-26/license.rst Doc-26/maclib/using.rst Doc-26/reference/datamodel.rst Doc-26/reference/executionmodel.rst Doc-26/reference/expressions.rst Doc-26/reference/lexical_analysis.rst Doc-26/reference/simple_stmts.rst Doc-26/tutorial/appetite.rst Doc-26/tutorial/datastructures.rst Doc-26/tutorial/errors.rst Doc-26/tutorial/glossary.rst Doc-26/tutorial/introduction.rst Doc-26/tutorial/modules.rst Doc-26/tutorial/whatnow.rst Doc-26/whatsnew/2.0.rst Doc-26/whatsnew/2.1.rst Doc-26/whatsnew/2.3.rst Doc-26/whatsnew/2.5.rst Doc-3k/c-api/abstract.rst Doc-3k/c-api/concrete.rst Doc-3k/c-api/init.rst Doc-3k/c-api/intro.rst Doc-3k/c-api/newtypes.rst Doc-3k/c-api/utilities.rst Doc-3k/distutils/apiref.rst Doc-3k/extending/building.rst Doc-3k/extending/extending.rst Doc-3k/extending/newtypes.rst Doc-3k/howto/advocacy.rst Doc-3k/howto/curses.rst Doc-3k/howto/doanddont.rst Doc-3k/howto/functional.rst Doc-3k/howto/regex.rst Doc-3k/howto/sockets.rst Doc-3k/howto/urllib2.rst Doc-3k/install/index.rst Doc-3k/library/_winreg.rst Doc-3k/library/asyncore.rst Doc-3k/library/binascii.rst Doc-3k/library/bz2.rst Doc-3k/library/cgi.rst Doc-3k/library/chunk.rst Doc-3k/library/cmath.rst Doc-3k/library/code.rst Doc-3k/library/codecs.rst Doc-3k/library/codeop.rst Doc-3k/library/cookie.rst Doc-3k/library/cookielib.rst Doc-3k/library/csv.rst Doc-3k/library/ctypes.rst Doc-3k/library/curses.rst Doc-3k/library/datetime.rst Doc-3k/library/decimal.rst Doc-3k/library/difflib.rst Doc-3k/library/dis.rst Doc-3k/library/dl.rst Doc-3k/library/doctest.rst Doc-3k/library/email.charset.rst Doc-3k/library/email.generator.rst Doc-3k/library/email.message.rst Doc-3k/library/email.parser.rst Doc-3k/library/errno.rst Doc-3k/library/fcntl.rst Doc-3k/library/formatter.rst Doc-3k/library/fpectl.rst Doc-3k/library/functions.rst Doc-3k/library/gdbm.rst Doc-3k/library/getopt.rst Doc-3k/library/gettext.rst Doc-3k/library/httplib.rst Doc-3k/library/imaplib.rst Doc-3k/library/imp.rst Doc-3k/library/inspect.rst Doc-3k/library/itertools.rst Doc-3k/library/logging.rst Doc-3k/library/mailbox.rst Doc-3k/library/math.rst Doc-3k/library/mimetypes.rst Doc-3k/library/mmap.rst Doc-3k/library/msilib.rst Doc-3k/library/multifile.rst Doc-3k/library/netrc.rst Doc-3k/library/new.rst Doc-3k/library/nntplib.rst Doc-3k/library/optparse.rst Doc-3k/library/os.rst Doc-3k/library/ossaudiodev.rst Doc-3k/library/othergui.rst Doc-3k/library/parser.rst Doc-3k/library/pickle.rst Doc-3k/library/profile.rst Doc-3k/library/pyexpat.rst Doc-3k/library/random.rst Doc-3k/library/re.rst Doc-3k/library/repr.rst Doc-3k/library/rfc822.rst Doc-3k/library/select.rst Doc-3k/library/sgmllib.rst Doc-3k/library/shelve.rst Doc-3k/library/shlex.rst Doc-3k/library/simplehttpserver.rst Doc-3k/library/simplexmlrpcserver.rst Doc-3k/library/site.rst Doc-3k/library/socket.rst Doc-3k/library/socketserver.rst Doc-3k/library/sqlite3.rst Doc-3k/library/stdtypes.rst Doc-3k/library/string.rst Doc-3k/library/stringprep.rst Doc-3k/library/struct.rst Doc-3k/library/sys.rst Doc-3k/library/tempfile.rst Doc-3k/library/termios.rst Doc-3k/library/textwrap.rst Doc-3k/library/threading.rst Doc-3k/library/timeit.rst Doc-3k/library/tix.rst Doc-3k/library/tkinter.rst Doc-3k/library/turtle.rst Doc-3k/library/urllib.rst Doc-3k/library/urllib2.rst Doc-3k/library/user.rst Doc-3k/library/winsound.rst Doc-3k/library/wsgiref.rst Doc-3k/library/xml.dom.rst Doc-3k/library/xml.etree.elementtree.rst Doc-3k/library/xml.sax.handler.rst Doc-3k/library/xml.sax.reader.rst Doc-3k/library/xml.sax.utils.rst Doc-3k/license.rst Doc-3k/maclib/using.rst Doc-3k/reference/datamodel.rst Doc-3k/reference/executionmodel.rst Doc-3k/reference/expressions.rst Doc-3k/reference/lexical_analysis.rst Doc-3k/reference/simple_stmts.rst Doc-3k/tutorial/appetite.rst Doc-3k/tutorial/datastructures.rst Doc-3k/tutorial/errors.rst Doc-3k/tutorial/glossary.rst Doc-3k/tutorial/introduction.rst Doc-3k/tutorial/modules.rst Doc-3k/tutorial/whatnow.rst Doc-3k/whatsnew/2.0.rst Doc-3k/whatsnew/2.1.rst Doc-3k/whatsnew/2.3.rst Doc-3k/whatsnew/2.5.rst sphinx/directives.py Message-ID: <20070804224558.DD2E41E4245@bag.python.org> Author: georg.brandl Date: Sun Aug 5 00:45:13 2007 New Revision: 56744 Modified: doctools/trunk/Doc-26/c-api/abstract.rst doctools/trunk/Doc-26/c-api/concrete.rst doctools/trunk/Doc-26/c-api/init.rst doctools/trunk/Doc-26/c-api/intro.rst doctools/trunk/Doc-26/c-api/newtypes.rst doctools/trunk/Doc-26/c-api/utilities.rst doctools/trunk/Doc-26/distutils/apiref.rst doctools/trunk/Doc-26/extending/building.rst doctools/trunk/Doc-26/extending/extending.rst doctools/trunk/Doc-26/extending/newtypes.rst doctools/trunk/Doc-26/howto/advocacy.rst doctools/trunk/Doc-26/howto/curses.rst doctools/trunk/Doc-26/howto/doanddont.rst doctools/trunk/Doc-26/howto/functional.rst doctools/trunk/Doc-26/howto/regex.rst doctools/trunk/Doc-26/howto/sockets.rst doctools/trunk/Doc-26/howto/urllib2.rst doctools/trunk/Doc-26/install/index.rst doctools/trunk/Doc-26/library/_winreg.rst doctools/trunk/Doc-26/library/asyncore.rst doctools/trunk/Doc-26/library/binascii.rst doctools/trunk/Doc-26/library/bz2.rst doctools/trunk/Doc-26/library/cgi.rst doctools/trunk/Doc-26/library/chunk.rst doctools/trunk/Doc-26/library/cmath.rst doctools/trunk/Doc-26/library/code.rst doctools/trunk/Doc-26/library/codecs.rst doctools/trunk/Doc-26/library/codeop.rst doctools/trunk/Doc-26/library/cookie.rst doctools/trunk/Doc-26/library/cookielib.rst doctools/trunk/Doc-26/library/csv.rst doctools/trunk/Doc-26/library/ctypes.rst doctools/trunk/Doc-26/library/curses.rst doctools/trunk/Doc-26/library/datetime.rst doctools/trunk/Doc-26/library/decimal.rst doctools/trunk/Doc-26/library/difflib.rst doctools/trunk/Doc-26/library/dis.rst doctools/trunk/Doc-26/library/dl.rst doctools/trunk/Doc-26/library/doctest.rst doctools/trunk/Doc-26/library/email.charset.rst doctools/trunk/Doc-26/library/email.generator.rst doctools/trunk/Doc-26/library/email.message.rst doctools/trunk/Doc-26/library/email.parser.rst doctools/trunk/Doc-26/library/errno.rst doctools/trunk/Doc-26/library/fcntl.rst doctools/trunk/Doc-26/library/formatter.rst doctools/trunk/Doc-26/library/fpectl.rst doctools/trunk/Doc-26/library/functions.rst doctools/trunk/Doc-26/library/gdbm.rst doctools/trunk/Doc-26/library/getopt.rst doctools/trunk/Doc-26/library/gettext.rst doctools/trunk/Doc-26/library/httplib.rst doctools/trunk/Doc-26/library/imageop.rst doctools/trunk/Doc-26/library/imaplib.rst doctools/trunk/Doc-26/library/imp.rst doctools/trunk/Doc-26/library/inspect.rst doctools/trunk/Doc-26/library/itertools.rst doctools/trunk/Doc-26/library/logging.rst doctools/trunk/Doc-26/library/mailbox.rst doctools/trunk/Doc-26/library/math.rst doctools/trunk/Doc-26/library/mimetypes.rst doctools/trunk/Doc-26/library/mimify.rst doctools/trunk/Doc-26/library/mmap.rst doctools/trunk/Doc-26/library/msilib.rst doctools/trunk/Doc-26/library/multifile.rst doctools/trunk/Doc-26/library/netrc.rst doctools/trunk/Doc-26/library/new.rst doctools/trunk/Doc-26/library/nntplib.rst doctools/trunk/Doc-26/library/optparse.rst doctools/trunk/Doc-26/library/os.rst doctools/trunk/Doc-26/library/ossaudiodev.rst doctools/trunk/Doc-26/library/othergui.rst doctools/trunk/Doc-26/library/parser.rst doctools/trunk/Doc-26/library/pickle.rst doctools/trunk/Doc-26/library/profile.rst doctools/trunk/Doc-26/library/pyexpat.rst doctools/trunk/Doc-26/library/random.rst doctools/trunk/Doc-26/library/re.rst doctools/trunk/Doc-26/library/repr.rst doctools/trunk/Doc-26/library/rfc822.rst doctools/trunk/Doc-26/library/select.rst doctools/trunk/Doc-26/library/sgmllib.rst doctools/trunk/Doc-26/library/shelve.rst doctools/trunk/Doc-26/library/shlex.rst doctools/trunk/Doc-26/library/simplehttpserver.rst doctools/trunk/Doc-26/library/simplexmlrpcserver.rst doctools/trunk/Doc-26/library/site.rst doctools/trunk/Doc-26/library/socket.rst doctools/trunk/Doc-26/library/socketserver.rst doctools/trunk/Doc-26/library/sqlite3.rst doctools/trunk/Doc-26/library/stdtypes.rst doctools/trunk/Doc-26/library/string.rst doctools/trunk/Doc-26/library/stringprep.rst doctools/trunk/Doc-26/library/struct.rst doctools/trunk/Doc-26/library/sys.rst doctools/trunk/Doc-26/library/tempfile.rst doctools/trunk/Doc-26/library/termios.rst doctools/trunk/Doc-26/library/textwrap.rst doctools/trunk/Doc-26/library/threading.rst doctools/trunk/Doc-26/library/timeit.rst doctools/trunk/Doc-26/library/tix.rst doctools/trunk/Doc-26/library/tkinter.rst doctools/trunk/Doc-26/library/turtle.rst doctools/trunk/Doc-26/library/urllib.rst doctools/trunk/Doc-26/library/urllib2.rst doctools/trunk/Doc-26/library/user.rst doctools/trunk/Doc-26/library/winsound.rst doctools/trunk/Doc-26/library/wsgiref.rst doctools/trunk/Doc-26/library/xml.dom.rst doctools/trunk/Doc-26/library/xml.etree.elementtree.rst doctools/trunk/Doc-26/library/xml.sax.handler.rst doctools/trunk/Doc-26/library/xml.sax.reader.rst doctools/trunk/Doc-26/library/xml.sax.utils.rst doctools/trunk/Doc-26/license.rst doctools/trunk/Doc-26/maclib/using.rst doctools/trunk/Doc-26/reference/datamodel.rst doctools/trunk/Doc-26/reference/executionmodel.rst doctools/trunk/Doc-26/reference/expressions.rst doctools/trunk/Doc-26/reference/lexical_analysis.rst doctools/trunk/Doc-26/reference/simple_stmts.rst doctools/trunk/Doc-26/tutorial/appetite.rst doctools/trunk/Doc-26/tutorial/datastructures.rst doctools/trunk/Doc-26/tutorial/errors.rst doctools/trunk/Doc-26/tutorial/glossary.rst doctools/trunk/Doc-26/tutorial/introduction.rst doctools/trunk/Doc-26/tutorial/modules.rst doctools/trunk/Doc-26/tutorial/whatnow.rst doctools/trunk/Doc-26/whatsnew/2.0.rst doctools/trunk/Doc-26/whatsnew/2.1.rst doctools/trunk/Doc-26/whatsnew/2.3.rst doctools/trunk/Doc-26/whatsnew/2.5.rst doctools/trunk/Doc-3k/c-api/abstract.rst doctools/trunk/Doc-3k/c-api/concrete.rst doctools/trunk/Doc-3k/c-api/init.rst doctools/trunk/Doc-3k/c-api/intro.rst doctools/trunk/Doc-3k/c-api/newtypes.rst doctools/trunk/Doc-3k/c-api/utilities.rst doctools/trunk/Doc-3k/distutils/apiref.rst doctools/trunk/Doc-3k/extending/building.rst doctools/trunk/Doc-3k/extending/extending.rst doctools/trunk/Doc-3k/extending/newtypes.rst doctools/trunk/Doc-3k/howto/advocacy.rst doctools/trunk/Doc-3k/howto/curses.rst doctools/trunk/Doc-3k/howto/doanddont.rst doctools/trunk/Doc-3k/howto/functional.rst doctools/trunk/Doc-3k/howto/regex.rst doctools/trunk/Doc-3k/howto/sockets.rst doctools/trunk/Doc-3k/howto/urllib2.rst doctools/trunk/Doc-3k/install/index.rst doctools/trunk/Doc-3k/library/_winreg.rst doctools/trunk/Doc-3k/library/asyncore.rst doctools/trunk/Doc-3k/library/binascii.rst doctools/trunk/Doc-3k/library/bz2.rst doctools/trunk/Doc-3k/library/cgi.rst doctools/trunk/Doc-3k/library/chunk.rst doctools/trunk/Doc-3k/library/cmath.rst doctools/trunk/Doc-3k/library/code.rst doctools/trunk/Doc-3k/library/codecs.rst doctools/trunk/Doc-3k/library/codeop.rst doctools/trunk/Doc-3k/library/cookie.rst doctools/trunk/Doc-3k/library/cookielib.rst doctools/trunk/Doc-3k/library/csv.rst doctools/trunk/Doc-3k/library/ctypes.rst doctools/trunk/Doc-3k/library/curses.rst doctools/trunk/Doc-3k/library/datetime.rst doctools/trunk/Doc-3k/library/decimal.rst doctools/trunk/Doc-3k/library/difflib.rst doctools/trunk/Doc-3k/library/dis.rst doctools/trunk/Doc-3k/library/dl.rst doctools/trunk/Doc-3k/library/doctest.rst doctools/trunk/Doc-3k/library/email.charset.rst doctools/trunk/Doc-3k/library/email.generator.rst doctools/trunk/Doc-3k/library/email.message.rst doctools/trunk/Doc-3k/library/email.parser.rst doctools/trunk/Doc-3k/library/errno.rst doctools/trunk/Doc-3k/library/fcntl.rst doctools/trunk/Doc-3k/library/formatter.rst doctools/trunk/Doc-3k/library/fpectl.rst doctools/trunk/Doc-3k/library/functions.rst doctools/trunk/Doc-3k/library/gdbm.rst doctools/trunk/Doc-3k/library/getopt.rst doctools/trunk/Doc-3k/library/gettext.rst doctools/trunk/Doc-3k/library/httplib.rst doctools/trunk/Doc-3k/library/imaplib.rst doctools/trunk/Doc-3k/library/imp.rst doctools/trunk/Doc-3k/library/inspect.rst doctools/trunk/Doc-3k/library/itertools.rst doctools/trunk/Doc-3k/library/logging.rst doctools/trunk/Doc-3k/library/mailbox.rst doctools/trunk/Doc-3k/library/math.rst doctools/trunk/Doc-3k/library/mimetypes.rst doctools/trunk/Doc-3k/library/mmap.rst doctools/trunk/Doc-3k/library/msilib.rst doctools/trunk/Doc-3k/library/multifile.rst doctools/trunk/Doc-3k/library/netrc.rst doctools/trunk/Doc-3k/library/new.rst doctools/trunk/Doc-3k/library/nntplib.rst doctools/trunk/Doc-3k/library/optparse.rst doctools/trunk/Doc-3k/library/os.rst doctools/trunk/Doc-3k/library/ossaudiodev.rst doctools/trunk/Doc-3k/library/othergui.rst doctools/trunk/Doc-3k/library/parser.rst doctools/trunk/Doc-3k/library/pickle.rst doctools/trunk/Doc-3k/library/profile.rst doctools/trunk/Doc-3k/library/pyexpat.rst doctools/trunk/Doc-3k/library/random.rst doctools/trunk/Doc-3k/library/re.rst doctools/trunk/Doc-3k/library/repr.rst doctools/trunk/Doc-3k/library/rfc822.rst doctools/trunk/Doc-3k/library/select.rst doctools/trunk/Doc-3k/library/sgmllib.rst doctools/trunk/Doc-3k/library/shelve.rst doctools/trunk/Doc-3k/library/shlex.rst doctools/trunk/Doc-3k/library/simplehttpserver.rst doctools/trunk/Doc-3k/library/simplexmlrpcserver.rst doctools/trunk/Doc-3k/library/site.rst doctools/trunk/Doc-3k/library/socket.rst doctools/trunk/Doc-3k/library/socketserver.rst doctools/trunk/Doc-3k/library/sqlite3.rst doctools/trunk/Doc-3k/library/stdtypes.rst doctools/trunk/Doc-3k/library/string.rst doctools/trunk/Doc-3k/library/stringprep.rst doctools/trunk/Doc-3k/library/struct.rst doctools/trunk/Doc-3k/library/sys.rst doctools/trunk/Doc-3k/library/tempfile.rst doctools/trunk/Doc-3k/library/termios.rst doctools/trunk/Doc-3k/library/textwrap.rst doctools/trunk/Doc-3k/library/threading.rst doctools/trunk/Doc-3k/library/timeit.rst doctools/trunk/Doc-3k/library/tix.rst doctools/trunk/Doc-3k/library/tkinter.rst doctools/trunk/Doc-3k/library/turtle.rst doctools/trunk/Doc-3k/library/urllib.rst doctools/trunk/Doc-3k/library/urllib2.rst doctools/trunk/Doc-3k/library/user.rst doctools/trunk/Doc-3k/library/winsound.rst doctools/trunk/Doc-3k/library/wsgiref.rst doctools/trunk/Doc-3k/library/xml.dom.rst doctools/trunk/Doc-3k/library/xml.etree.elementtree.rst doctools/trunk/Doc-3k/library/xml.sax.handler.rst doctools/trunk/Doc-3k/library/xml.sax.reader.rst doctools/trunk/Doc-3k/library/xml.sax.utils.rst doctools/trunk/Doc-3k/license.rst doctools/trunk/Doc-3k/maclib/using.rst doctools/trunk/Doc-3k/reference/datamodel.rst doctools/trunk/Doc-3k/reference/executionmodel.rst doctools/trunk/Doc-3k/reference/expressions.rst doctools/trunk/Doc-3k/reference/lexical_analysis.rst doctools/trunk/Doc-3k/reference/simple_stmts.rst doctools/trunk/Doc-3k/tutorial/appetite.rst doctools/trunk/Doc-3k/tutorial/datastructures.rst doctools/trunk/Doc-3k/tutorial/errors.rst doctools/trunk/Doc-3k/tutorial/glossary.rst doctools/trunk/Doc-3k/tutorial/introduction.rst doctools/trunk/Doc-3k/tutorial/modules.rst doctools/trunk/Doc-3k/tutorial/whatnow.rst doctools/trunk/Doc-3k/whatsnew/2.0.rst doctools/trunk/Doc-3k/whatsnew/2.1.rst doctools/trunk/Doc-3k/whatsnew/2.3.rst doctools/trunk/Doc-3k/whatsnew/2.5.rst doctools/trunk/sphinx/directives.py Log: Fix a whole load of markup glitches introduced mostly by the converter. Many thanks to Tim Hatch for finding them, and thanks to Emacs for making it easy to fix them :) Modified: doctools/trunk/Doc-26/c-api/abstract.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/abstract.rst (original) +++ doctools/trunk/Doc-26/c-api/abstract.rst Sun Aug 5 00:45:13 2007 @@ -182,9 +182,9 @@ either is not a class object, a more general mechanism is used to determine the class relationship of the two objects. When testing if *B* is a subclass of *A*, if *A* is *B*, :cfunc:`PyObject_IsSubclass` returns true. If *A* and *B* -are different objects, *B*'s :attr:`__bases__` attribute is searched in a depth- -first fashion for *A* --- the presence of the :attr:`__bases__` attribute is -considered sufficient for this determination. +are different objects, *B*'s :attr:`__bases__` attribute is searched in a +depth-first fashion for *A* --- the presence of the :attr:`__bases__` attribute +is considered sufficient for this determination. .. cfunction:: int PyObject_IsSubclass(PyObject *derived, PyObject *cls) Modified: doctools/trunk/Doc-26/c-api/concrete.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/concrete.rst (original) +++ doctools/trunk/Doc-26/c-api/concrete.rst Sun Aug 5 00:45:13 2007 @@ -1662,11 +1662,9 @@ Rich compare two unicode strings and return one of the following: -* ``NULL`` in case an exception was raised - -* :const:`Py_True` or :const:`Py_False` for successful comparisons - -* :const:`Py_NotImplemented` in case the type combination is unknown + * ``NULL`` in case an exception was raised + * :const:`Py_True` or :const:`Py_False` for successful comparisons + * :const:`Py_NotImplemented` in case the type combination is unknown Note that :const:`Py_EQ` and :const:`Py_NE` comparisons can cause a :exc:`UnicodeWarning` in case the conversion of the arguments to Unicode fails @@ -2411,7 +2409,7 @@ .. index:: single: EOFError (built-in exception) - Equivalent to ``p.readline([*n*])``, this function reads one line from the + Equivalent to ``p.readline([n])``, this function reads one line from the object *p*. *p* may be a file object or any object with a :meth:`readline` method. If *n* is ``0``, exactly one line is read, regardless of the length of the line. If *n* is greater than ``0``, no more than *n* bytes will be read @@ -2773,8 +2771,9 @@ .. cvar:: PyTypeObject PySeqIter_Type - Type object for iterator objects returned by :cfunc:`PySeqIter_New` and the one- - argument form of the :func:`iter` built-in function for built-in sequence types. + Type object for iterator objects returned by :cfunc:`PySeqIter_New` and the + one-argument form of the :func:`iter` built-in function for built-in sequence + types. .. versionadded:: 2.2 @@ -2965,14 +2964,14 @@ .. cfunction:: PyObject* PyWeakref_NewRef(PyObject *ob, PyObject *callback) - Return a weak reference object for the object *ob*. This will always return a - new reference, but is not guaranteed to create a new object; an existing + Return a weak reference object for the object *ob*. This will always return + a new reference, but is not guaranteed to create a new object; an existing reference object may be returned. The second parameter, *callback*, can be a callable object that receives notification when *ob* is garbage collected; it should accept a single parameter, which will be the weak reference object - itself. *callback* may also be ``None`` or *NULL*. If *ob* is not a weakly- - referencable object, or if *callback* is not callable, ``None``, or *NULL*, this - will return *NULL* and raise :exc:`TypeError`. + itself. *callback* may also be ``None`` or *NULL*. If *ob* is not a + weakly-referencable object, or if *callback* is not callable, ``None``, or + *NULL*, this will return *NULL* and raise :exc:`TypeError`. .. versionadded:: 2.2 @@ -2981,12 +2980,12 @@ Return a weak reference proxy object for the object *ob*. This will always return a new reference, but is not guaranteed to create a new object; an - existing proxy object may be returned. The second parameter, *callback*, can be - a callable object that receives notification when *ob* is garbage collected; it - should accept a single parameter, which will be the weak reference object - itself. *callback* may also be ``None`` or *NULL*. If *ob* is not a weakly- - referencable object, or if *callback* is not callable, ``None``, or *NULL*, this - will return *NULL* and raise :exc:`TypeError`. + existing proxy object may be returned. The second parameter, *callback*, can + be a callable object that receives notification when *ob* is garbage + collected; it should accept a single parameter, which will be the weak + reference object itself. *callback* may also be ``None`` or *NULL*. If *ob* + is not a weakly-referencable object, or if *callback* is not callable, + ``None``, or *NULL*, this will return *NULL* and raise :exc:`TypeError`. .. versionadded:: 2.2 Modified: doctools/trunk/Doc-26/c-api/init.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/init.rst (original) +++ doctools/trunk/Doc-26/c-api/init.rst Sun Aug 5 00:45:13 2007 @@ -102,15 +102,16 @@ ``sys.stdout`` and ``sys.stderr`` (however these refer to the same underlying :ctype:`FILE` structures in the C library). - The return value points to the first thread state created in the new sub- - interpreter. This thread state is made in the current thread state. Note that - no actual thread is created; see the discussion of thread states below. If - creation of the new interpreter is unsuccessful, *NULL* is returned; no - exception is set since the exception state is stored in the current thread state - and there may not be a current thread state. (Like all other Python/C API - functions, the global interpreter lock must be held before calling this function - and is still held when it returns; however, unlike most other Python/C API - functions, there needn't be a current thread state on entry.) + The return value points to the first thread state created in the new + sub-interpreter. This thread state is made in the current thread state. + Note that no actual thread is created; see the discussion of thread states + below. If creation of the new interpreter is unsuccessful, *NULL* is + returned; no exception is set since the exception state is stored in the + current thread state and there may not be a current thread state. (Like all + other Python/C API functions, the global interpreter lock must be held before + calling this function and is still held when it returns; however, unlike most + other Python/C API functions, there needn't be a current thread state on + entry.) .. index:: single: Py_Finalize() @@ -169,15 +170,15 @@ single: main() single: Py_GetPath() - This function should be called before :cfunc:`Py_Initialize` is called for the - first time, if it is called at all. It tells the interpreter the value of the - ``argv[0]`` argument to the :cfunc:`main` function of the program. This is used - by :cfunc:`Py_GetPath` and some other functions below to find the Python run- - time libraries relative to the interpreter executable. The default value is - ``'python'``. The argument should point to a zero-terminated character string - in static storage whose contents will not change for the duration of the - program's execution. No code in the Python interpreter will change the contents - of this storage. + This function should be called before :cfunc:`Py_Initialize` is called for + the first time, if it is called at all. It tells the interpreter the value + of the ``argv[0]`` argument to the :cfunc:`main` function of the program. + This is used by :cfunc:`Py_GetPath` and some other functions below to find + the Python run-time libraries relative to the interpreter executable. The + default value is ``'python'``. The argument should point to a + zero-terminated character string in static storage whose contents will not + change for the duration of the program's execution. No code in the Python + interpreter will change the contents of this storage. .. cfunction:: char* Py_GetProgramName() @@ -376,12 +377,12 @@ single: interpreter lock single: lock, interpreter -The Python interpreter is not fully thread safe. In order to support multi- -threaded Python programs, there's a global lock that must be held by the current -thread before it can safely access Python objects. Without the lock, even the -simplest operations could cause problems in a multi-threaded program: for -example, when two threads simultaneously increment the reference count of the -same object, the reference count could end up being incremented only once +The Python interpreter is not fully thread safe. In order to support +multi-threaded Python programs, there's a global lock that must be held by the +current thread before it can safely access Python objects. Without the lock, +even the simplest operations could cause problems in a multi-threaded program: +for example, when two threads simultaneously increment the reference count of +the same object, the reference count could end up being incremented only once instead of twice. .. index:: single: setcheckinterval() (in module sys) Modified: doctools/trunk/Doc-26/c-api/intro.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/intro.rst (original) +++ doctools/trunk/Doc-26/c-api/intro.rst Sun Aug 5 00:45:13 2007 @@ -70,7 +70,7 @@ To include the headers, place both directories (if different) on your compiler's search path for includes. Do *not* place the parent directories on the search -path and then use ``#include ``; this will break on +path and then use ``#include ``; this will break on multi-platform builds since the platform independent headers under :envvar:`prefix` include the platform specific headers from :envvar:`exec_prefix`. @@ -402,16 +402,16 @@ .. index:: single: exc_info() (in module sys) -Note that starting with Python 1.5, the preferred, thread-safe way to access -the exception state from Python code is to call the function -:func:`sys.exc_info`, which returns the per-thread exception state for Python -code. Also, the semantics of both ways to access the exception state have -changed so that a function which catches an exception will save and restore its -thread's exception state so as to preserve the exception state of its caller. -This prevents common bugs in exception handling code caused by an innocent- -looking function overwriting the exception being handled; it also reduces the -often unwanted lifetime extension for objects that are referenced by the stack -frames in the traceback. +Note that starting with Python 1.5, the preferred, thread-safe way to access the +exception state from Python code is to call the function :func:`sys.exc_info`, +which returns the per-thread exception state for Python code. Also, the +semantics of both ways to access the exception state have changed so that a +function which catches an exception will save and restore its thread's exception +state so as to preserve the exception state of its caller. This prevents common +bugs in exception handling code caused by an innocent-looking function +overwriting the exception being handled; it also reduces the often unwanted +lifetime extension for objects that are referenced by the stack frames in the +traceback. As a general principle, a function that calls another function to perform some task should check whether the called function raised an exception, and if so, @@ -536,13 +536,13 @@ based upon its best guess for the location of the standard Python interpreter executable, assuming that the Python library is found in a fixed location relative to the Python interpreter executable. In particular, it looks for a -directory named :file:`lib/python|version|` relative to the parent directory +directory named :file:`lib/python{X.Y}` relative to the parent directory where the executable named :file:`python` is found on the shell command search path (the environment variable :envvar:`PATH`). For instance, if the Python executable is found in :file:`/usr/local/bin/python`, it will assume that the libraries are in -:file:`/usr/local/lib/python|version|`. (In fact, this particular path is also +:file:`/usr/local/lib/python{X.Y}`. (In fact, this particular path is also the "fallback" location, used when no executable file named :file:`python` is found along :envvar:`PATH`.) The user can override this behavior by setting the environment variable :envvar:`PYTHONHOME`, or insert additional directories in @@ -594,9 +594,9 @@ Compiling the interpreter with the :cmacro:`Py_DEBUG` macro defined produces what is generally meant by "a debug build" of Python. :cmacro:`Py_DEBUG` is enabled in the Unix build by adding :option:`--with-pydebug` to the -:file:`configure` command. It is also implied by the presence of the not- -Python-specific :cmacro:`_DEBUG` macro. When :cmacro:`Py_DEBUG` is enabled in -the Unix build, compiler optimization is disabled. +:file:`configure` command. It is also implied by the presence of the +not-Python-specific :cmacro:`_DEBUG` macro. When :cmacro:`Py_DEBUG` is enabled +in the Unix build, compiler optimization is disabled. In addition to the reference count debugging described below, the following extra checks are performed: Modified: doctools/trunk/Doc-26/c-api/newtypes.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/newtypes.rst (original) +++ doctools/trunk/Doc-26/c-api/newtypes.rst Sun Aug 5 00:45:13 2007 @@ -480,10 +480,10 @@ The basic size does not include the GC header size (this is new in Python 2.2; in 2.1 and 2.0, the GC header size was included in :attr:`tp_basicsize`). - These fields are inherited separately by subtypes. If the base type has a non- - zero :attr:`tp_itemsize`, it is generally not safe to set :attr:`tp_itemsize` to - a different non-zero value in a subtype (though this depends on the - implementation of the base type). + These fields are inherited separately by subtypes. If the base type has a + non-zero :attr:`tp_itemsize`, it is generally not safe to set + :attr:`tp_itemsize` to a different non-zero value in a subtype (though this + depends on the implementation of the base type). A note about alignment: if the variable items require a particular alignment, this should be taken care of by the value of :attr:`tp_basicsize`. Example: Modified: doctools/trunk/Doc-26/c-api/utilities.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/utilities.rst (original) +++ doctools/trunk/Doc-26/c-api/utilities.rst Sun Aug 5 00:45:13 2007 @@ -484,13 +484,13 @@ Unicode into a character buffer. It only works for encoded data without embedded NUL bytes. - This format requires two arguments. The first is only used as input, and must - be a :ctype:`const char\*` which points to the name of an encoding as a NUL- - terminated string, or *NULL*, in which case the default encoding is used. An - exception is raised if the named encoding is not known to Python. The second - argument must be a :ctype:`char\*\*`; the value of the pointer it references - will be set to a buffer with the contents of the argument text. The text will - be encoded in the encoding specified by the first argument. + This format requires two arguments. The first is only used as input, and + must be a :ctype:`const char\*` which points to the name of an encoding as a + NUL-terminated string, or *NULL*, in which case the default encoding is used. + An exception is raised if the named encoding is not known to Python. The + second argument must be a :ctype:`char\*\*`; the value of the pointer it + references will be set to a buffer with the contents of the argument text. + The text will be encoded in the encoding specified by the first argument. :cfunc:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy the encoded data into this buffer and adjust *\*buffer* to reference the newly @@ -508,14 +508,14 @@ input data which contains NUL characters. It requires three arguments. The first is only used as input, and must be a - :ctype:`const char\*` which points to the name of an encoding as a NUL- - terminated string, or *NULL*, in which case the default encoding is used. An - exception is raised if the named encoding is not known to Python. The second - argument must be a :ctype:`char\*\*`; the value of the pointer it references - will be set to a buffer with the contents of the argument text. The text will - be encoded in the encoding specified by the first argument. The third argument - must be a pointer to an integer; the referenced integer will be set to the - number of bytes in the output buffer. + :ctype:`const char\*` which points to the name of an encoding as a + NUL-terminated string, or *NULL*, in which case the default encoding is used. + An exception is raised if the named encoding is not known to Python. The + second argument must be a :ctype:`char\*\*`; the value of the pointer it + references will be set to a buffer with the contents of the argument text. + The text will be encoded in the encoding specified by the first argument. + The third argument must be a pointer to an integer; the referenced integer + will be set to the number of bytes in the output buffer. There are two modes of operation: @@ -966,14 +966,14 @@ The return value (*rv*) for these functions should be interpreted as follows: * When ``0 <= rv < size``, the output conversion was successful and *rv* - characters were written to *str* (excluding the trailing ``'\\0'`` byte at + characters were written to *str* (excluding the trailing ``'\0'`` byte at *str*[*rv*]). * When ``rv >= size``, the output conversion was truncated and a buffer with - ``rv + 1`` bytes would have been needed to succeed. *str*[*size*-1] is ``'\\0'`` + ``rv + 1`` bytes would have been needed to succeed. *str*[*size*-1] is ``'\0'`` in this case. -* When ``rv < 0``, "something bad happened." *str*[*size*-1] is ``'\\0'`` in +* When ``rv < 0``, "something bad happened." *str*[*size*-1] is ``'\0'`` in this case too, but the rest of *str* is undefined. The exact cause of the error depends on the underlying platform. Modified: doctools/trunk/Doc-26/distutils/apiref.rst ============================================================================== --- doctools/trunk/Doc-26/distutils/apiref.rst (original) +++ doctools/trunk/Doc-26/distutils/apiref.rst Sun Aug 5 00:45:13 2007 @@ -100,7 +100,7 @@ +--------------------+--------------------------------+-------------------------------------------------------------+ -.. function:: run_setup(script_name[, script_args=``None``, stop_after=``'run'``]) +.. function:: run_setup(script_name[, script_args=None, stop_after='run']) Run a setup script in a somewhat controlled environment, and return the :class:`distutils.dist.Distribution` instance that drives things. This is @@ -341,7 +341,7 @@ to :command:`build`, :command:`build_ext`, :command:`build_clib`). -.. class:: CCompiler([verbose=``0``, dry_run=``0``, force=``0``]) +.. class:: CCompiler([verbose=0, dry_run=0, force=0]) The abstract base class :class:`CCompiler` defines the interface that must be implemented by real compiler classes. The class also has some utility methods @@ -431,7 +431,7 @@ runtime linker may search by default. - .. method:: CCompiler.define_macro(name[, value=``None``]) + .. method:: CCompiler.define_macro(name[, value=None]) Define a preprocessor macro for all compilations driven by this compiler object. The optional parameter *value* should be a string; if it is not supplied, then @@ -442,11 +442,11 @@ .. method:: CCompiler.undefine_macro(name) Undefine a preprocessor macro for all compilations driven by this compiler - object. If the same macro is defined by :meth:`define_macro` and undefined by - :meth:`undefine_macro` the last call takes precedence (including multiple - redefinitions or undefinitions). If the macro is redefined/undefined on a per- - compilation basis (ie. in the call to :meth:`compile`), then that takes - precedence. + object. If the same macro is defined by :meth:`define_macro` and + undefined by :meth:`undefine_macro` the last call takes precedence + (including multiple redefinitions or undefinitions). If the macro is + redefined/undefined on a per-compilation basis (ie. in the call to + :meth:`compile`), then that takes precedence. .. method:: CCompiler.add_link_object(object) @@ -473,7 +473,7 @@ list) to do the job. - .. method:: CCompiler.find_library_file(dirs, lib[, debug=``0``]) + .. method:: CCompiler.find_library_file(dirs, lib[, debug=0]) Search the specified list of directories for a static or shared library file *lib* and return the full path to that file. If *debug* is true, look for a @@ -481,7 +481,7 @@ ``None`` if *lib* wasn't found in any of the specified directories. - .. method:: CCompiler.has_function(funcname [, includes=``None``, include_dirs=``None``, libraries=``None``, library_dirs=``None``]) + .. method:: CCompiler.has_function(funcname [, includes=None, include_dirs=None, libraries=None, library_dirs=None]) Return a boolean indicating whether *funcname* is supported on the current platform. The optional arguments can be used to augment the compilation @@ -536,7 +536,7 @@ The following methods invoke stages in the build process. - .. method:: CCompiler.compile(sources[, output_dir=``None``, macros=``None``, include_dirs=``None``, debug=``0``, extra_preargs=``None``, extra_postargs=``None``, depends=``None``]) + .. method:: CCompiler.compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None]) Compile one or more source files. Generates object files (e.g. transforms a :file:`.c` file to a :file:`.o` file.) @@ -580,7 +580,7 @@ Raises :exc:`CompileError` on failure. - .. method:: CCompiler.create_static_lib(objects, output_libname[, output_dir=``None``, debug=``0``, target_lang=``None``]) + .. method:: CCompiler.create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None]) Link a bunch of stuff together to create a static library file. The "bunch of stuff" consists of the list of object files supplied as *objects*, the extra @@ -602,7 +602,7 @@ Raises :exc:`LibError` on failure. - .. method:: CCompiler.link(target_desc, objects, output_filename[, output_dir=``None``, libraries=``None``, library_dirs=``None``, runtime_library_dirs=``None``, export_symbols=``None``, debug=``0``, extra_preargs=``None``, extra_postargs=``None``, build_temp=``None``, target_lang=``None``]) + .. method:: CCompiler.link(target_desc, objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None]) Link a bunch of stuff together to create an executable or shared library file. @@ -644,28 +644,28 @@ Raises :exc:`LinkError` on failure. - .. method:: CCompiler.link_executable(objects, output_progname[, output_dir=``None``, libraries=``None``, library_dirs=``None``, runtime_library_dirs=``None``, debug=``0``, extra_preargs=``None``, extra_postargs=``None``, target_lang=``None``]) + .. method:: CCompiler.link_executable(objects, output_progname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, target_lang=None]) Link an executable. *output_progname* is the name of the file executable, while *objects* are a list of object filenames to link in. Other arguments are as for the :meth:`link` method. - .. method:: CCompiler.link_shared_lib(objects, output_libname[, output_dir=``None``, libraries=``None``, library_dirs=``None``, runtime_library_dirs=``None``, export_symbols=``None``, debug=``0``, extra_preargs=``None``, extra_postargs=``None``, build_temp=``None``, target_lang=``None``]) + .. method:: CCompiler.link_shared_lib(objects, output_libname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None]) Link a shared library. *output_libname* is the name of the output library, while *objects* is a list of object filenames to link in. Other arguments are as for the :meth:`link` method. - .. method:: CCompiler.link_shared_object(objects, output_filename[, output_dir=``None``, libraries=``None``, library_dirs=``None``, runtime_library_dirs=``None``, export_symbols=``None``, debug=``0``, extra_preargs=``None``, extra_postargs=``None``, build_temp=``None``, target_lang=``None``]) + .. method:: CCompiler.link_shared_object(objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None]) Link a shared object. *output_filename* is the name of the shared object that will be created, while *objects* is a list of object filenames to link in. Other arguments are as for the :meth:`link` method. - .. method:: CCompiler.preprocess(source[, output_file=``None``, macros=``None``, include_dirs=``None``, extra_preargs=``None``, extra_postargs=``None``]) + .. method:: CCompiler.preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None]) Preprocess a single C/C++ source file, named in *source*. Output will be written to file named *output_file*, or *stdout* if *output_file* not supplied. @@ -680,14 +680,14 @@ use by the various concrete subclasses. - .. method:: CCompiler.executable_filename(basename[, strip_dir=``0``, output_dir=``''``]) + .. method:: CCompiler.executable_filename(basename[, strip_dir=0, output_dir='']) Returns the filename of the executable for the given *basename*. Typically for non-Windows platforms this is the same as the basename, while Windows will get a :file:`.exe` added. - .. method:: CCompiler.library_filename(libname[, lib_type=``'static'``, strip_dir=``0``, output_dir=``''``]) + .. method:: CCompiler.library_filename(libname[, lib_type='static', strip_dir=0, output_dir='']) Returns the filename for the given library name on the current platform. On Unix a library with *lib_type* of ``'static'`` will typically be of the form @@ -695,18 +695,18 @@ :file:`liblibname.so`. - .. method:: CCompiler.object_filenames(source_filenames[, strip_dir=``0``, output_dir=``''``]) + .. method:: CCompiler.object_filenames(source_filenames[, strip_dir=0, output_dir='']) Returns the name of the object files for the given source files. *source_filenames* should be a list of filenames. - .. method:: CCompiler.shared_object_filename(basename[, strip_dir=``0``, output_dir=``''``]) + .. method:: CCompiler.shared_object_filename(basename[, strip_dir=0, output_dir='']) Returns the name of a shared object file for the given file name *basename*. - .. method:: CCompiler.execute(func, args[, msg=``None``, level=``1``]) + .. method:: CCompiler.execute(func, args[, msg=None, level=1]) Invokes :func:`distutils.util.execute` This method invokes a Python function *func* with the given arguments *args*, after logging and taking into account @@ -719,7 +719,7 @@ the given command. XXX see also. - .. method:: CCompiler.mkpath(name[, mode=``511``]) + .. method:: CCompiler.mkpath(name[, mode=511]) Invokes :func:`distutils.dir_util.mkpath`. This creates a directory and any missing ancestor directories. XXX see also. @@ -731,7 +731,7 @@ also. - .. method:: CCompiler.announce(msg[, level=``1``]) + .. method:: CCompiler.announce(msg[, level=1]) Write a message using :func:`distutils.log.debug`. XXX see also. @@ -867,7 +867,7 @@ tarballs or zipfiles. -.. function:: make_archive(base_name, format[, root_dir=``None``, base_dir=``None``, verbose=``0``, dry_run=``0``]) +.. function:: make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0]) Create an archive file (eg. ``zip`` or ``tar``). *base_name* is the name of the file to create, minus any format-specific extension; *format* is the @@ -883,7 +883,7 @@ This should be changed to support bz2 files -.. function:: make_tarball(base_name, base_dir[, compress=``'gzip'``, verbose=``0``, dry_run=``0``]) +.. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0]) 'Create an (optional compressed) archive as a tar file from all files in and under *base_dir*. *compress* must be ``'gzip'`` (the default), ``'compress'``, @@ -898,7 +898,7 @@ This should be replaced with calls to the :mod:`tarfile` module. -.. function:: make_zipfile(base_name, base_dir[, verbose=``0``, dry_run=``0``]) +.. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0]) Create a zip file from all files in and under *base_dir*. The output zip file will be named *base_dir* + :file:`.zip`. Uses either the :mod:`zipfile` Python @@ -936,7 +936,7 @@ .. % % equivalent to a listcomp... -.. function:: newer_group(sources, target[, missing=``'error'``]) +.. function:: newer_group(sources, target[, missing='error']) Return true if *target* is out-of-date with respect to any file listed in *sources* In other words, if *target* exists and is newer than every file in @@ -961,7 +961,7 @@ directories. -.. function:: mkpath(name[, mode=``0777``, verbose=``0``, dry_run=``0``]) +.. function:: mkpath(name[, mode=0777, verbose=0, dry_run=0]) Create a directory and any missing ancestor directories. If the directory already exists (or if *name* is the empty string, which means the current @@ -972,7 +972,7 @@ directories actually created. -.. function:: create_tree(base_dir, files[, mode=``0777``, verbose=``0``, dry_run=``0``]) +.. function:: create_tree(base_dir, files[, mode=0777, verbose=0, dry_run=0]) Create all the empty directories under *base_dir* needed to put *files* there. *base_dir* is just the a name of a directory which doesn't necessarily exist @@ -982,7 +982,7 @@ :func:`mkpath`. -.. function:: copy_tree(src, dst[preserve_mode=``1``, preserve_times=``1``, preserve_symlinks=``0``, update=``0``, verbose=``0``, dry_run=``0``]) +.. function:: copy_tree(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0]) Copy an entire directory tree *src* to a new location *dst*. Both *src* and *dst* must be directory names. If *src* is not a directory, raise @@ -1002,7 +1002,7 @@ as for :func:`copy_file`. -.. function:: remove_tree(directory[verbose=``0``, dry_run=``0``]) +.. function:: remove_tree(directory[, verbose=0, dry_run=0]) Recursively remove *directory* and all files and directories underneath it. Any errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is @@ -1021,16 +1021,16 @@ This module contains some utility functions for operating on individual files. -.. function:: copy_file(src, dst[preserve_mode=``1``, preserve_times=``1``, update=``0``, link=``None``, verbose=``0``, dry_run=``0``]) +.. function:: copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0]) Copy file *src* to *dst*. If *dst* is a directory, then *src* is copied there with the same name; otherwise, it must be a filename. (If the file exists, it will be ruthlessly clobbered.) If *preserve_mode* is true (the default), the - file's mode (type and permission bits, or whatever is analogous on the current - platform) is copied. If *preserve_times* is true (the default), the last- - modified and last-access times are copied as well. If *update* is true, *src* - will only be copied if *dst* does not exist, or if *dst* does exist but is older - than *src*. + file's mode (type and permission bits, or whatever is analogous on the + current platform) is copied. If *preserve_times* is true (the default), the + last-modified and last-access times are copied as well. If *update* is true, + *src* will only be copied if *dst* does not exist, or if *dst* does exist but + is older than *src*. *link* allows you to make hard links (using :func:`os.link`) or symbolic links (using :func:`os.symlink`) instead of copying: set it to ``'hard'`` or @@ -1051,7 +1051,7 @@ .. % (not update) and (src newer than dst)). -.. function:: move_file(src, dst[verbose, dry_run]) +.. function:: move_file(src, dst[, verbose, dry_run]) Move file *src* to *dst*. If *dst* is a directory, the file will be moved into it with the same name; otherwise, *src* is just renamed to *dst*. Returns the @@ -1092,15 +1092,11 @@ Examples of returned values: -* ``linux-i586`` - -* ``linux-alpha`` - -* ``solaris-2.6-sun4u`` - -* ``irix-5.3`` - -* ``irix64-6.2`` + * ``linux-i586`` + * ``linux-alpha`` + * ``solaris-2.6-sun4u`` + * ``irix-5.3`` + * ``irix64-6.2`` For non-POSIX platforms, currently just returns ``sys.platform``. @@ -1130,9 +1126,8 @@ users can use in config files, command-line options, etc. Currently this includes: -* :envvar:`HOME` - user's home directory (Unix only) - -* :envvar:`PLAT` - description of the current platform, including hardware and + * :envvar:`HOME` - user's home directory (Unix only) + * :envvar:`PLAT` - description of the current platform, including hardware and OS (see :func:`get_platform`) @@ -1150,7 +1145,7 @@ underscore. No { } or ( ) style quoting is available. -.. function:: grok_environment_error(exc[, prefix=``'error: '``]) +.. function:: grok_environment_error(exc[, prefix='error: ']) Generate a useful error message from an :exc:`EnvironmentError` (:exc:`IOError` or :exc:`OSError`) exception object. Handles Python 1.5.1 and later styles, @@ -1173,7 +1168,7 @@ .. % Should probably be moved into the standard library. -.. function:: execute(func, args[, msg=``None``, verbose=``0``, dry_run=``0``]) +.. function:: execute(func, args[, msg=None, verbose=0, dry_run=0]) Perform some action that affects the outside world (for instance, writing to the filesystem). Such actions are special because they are disabled by the @@ -1191,18 +1186,16 @@ :exc:`ValueError` if *val* is anything else. -.. function:: byte_compile(py_files[, optimize=``0``, force=``0``, prefix=``None``, base_dir=``None``, verbose=``1``, dry_run=``0``, direct=``None``]) +.. function:: byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None]) Byte-compile a collection of Python source files to either :file:`.pyc` or :file:`.pyo` files in the same directory. *py_files* is a list of files to compile; any files that don't end in :file:`.py` are silently skipped. *optimize* must be one of the following: -* ``0`` - don't optimize (generate :file:`.pyc`) - -* ``1`` - normal optimization (like ``python -O``) - -* ``2`` - extra optimization (like ``python -OO``) + * ``0`` - don't optimize (generate :file:`.pyc`) + * ``1`` - normal optimization (like ``python -O``) + * ``2`` - extra optimization (like ``python -OO``) If *force* is true, all files are recompiled regardless of timestamps. @@ -1333,7 +1326,7 @@ later). -.. class:: FancyGetopt([option_table=``None``]) +.. class:: FancyGetopt([option_table=None]) The option_table is a list of 3-tuples: ``(long_option, short_option, help_string)`` @@ -1346,7 +1339,7 @@ The :class:`FancyGetopt` class provides the following methods: -.. method:: FancyGetopt.getopt([args=``None``, object=``None``]) +.. method:: FancyGetopt.getopt([args=None, object=None]) Parse command-line options in args. Store as attributes on *object*. @@ -1367,7 +1360,7 @@ yet. -.. method:: FancyGetopt.generate_help([header=``None``]) +.. method:: FancyGetopt.generate_help([header=None]) Generate help text (a list of strings, one per suggested line of output) from the option table for this :class:`FancyGetopt` object. @@ -1540,7 +1533,7 @@ lines, and joining lines with backslashes. -.. class:: TextFile([filename=``None``, file=``None``, **options]) +.. class:: TextFile([filename=None, file=None, **options]) This class provides a file-like object that takes care of all the things you commonly want to do when processing a text file that has some line-by-line @@ -1628,7 +1621,7 @@ filename and the current line number). - .. method:: TextFile.warn(msg[,line=``None``]) + .. method:: TextFile.warn(msg[,line=None]) Print (to stderr) a warning message tied to the current logical line in the current file. If the current logical line in the file spans multiple physical @@ -1952,12 +1945,12 @@ .. method:: Command.finalize_options() - Set final values for all the options that this command supports. This is always - called as late as possible, ie. after any option assignments from the command- - line or from other commands have been done. Thus, this is the place to to code - option dependencies: if *foo* depends on *bar*, then it is safe to set *foo* - from *bar* as long as *foo* still has the same value it was assigned in - :meth:`initialize_options`. + Set final values for all the options that this command supports. This is + always called as late as possible, ie. after any option assignments from the + command-line or from other commands have been done. Thus, this is the place + to to code option dependencies: if *foo* depends on *bar*, then it is safe to + set *foo* from *bar* as long as *foo* still has the same value it was + assigned in :meth:`initialize_options`. .. method:: Command.run() Modified: doctools/trunk/Doc-26/extending/building.rst ============================================================================== --- doctools/trunk/Doc-26/extending/building.rst (original) +++ doctools/trunk/Doc-26/extending/building.rst Sun Aug 5 00:45:13 2007 @@ -47,14 +47,13 @@ :file:`demo.so` or :file:`demo.pyd`. In the :file:`setup.py`, all execution is performed by calling the ``setup`` -function. This takes a variable number of keyword arguments, of which the -example above uses only a subset. Specifically, the example specifies meta- -information to build packages, and it specifies the contents of the package. -Normally, a package will contain of addition modules, like Python source -modules, documentation, subpackages, etc. Please refer to the distutils -documentation in :ref:`distutils-index` -to learn more about the features of distutils; this section explains building -extension modules only. +function. This takes a variable number of keyword arguments, of which the +example above uses only a subset. Specifically, the example specifies +meta-information to build packages, and it specifies the contents of the +package. Normally, a package will contain of addition modules, like Python +source modules, documentation, subpackages, etc. Please refer to the distutils +documentation in :ref:`distutils-index` to learn more about the features of +distutils; this section explains building extension modules only. It is common to pre-compute arguments to :func:`setup`, to better structure the driver script. In the example above, the\ ``ext_modules`` argument to Modified: doctools/trunk/Doc-26/extending/extending.rst ============================================================================== --- doctools/trunk/Doc-26/extending/extending.rst (original) +++ doctools/trunk/Doc-26/extending/extending.rst Sun Aug 5 00:45:13 2007 @@ -165,9 +165,9 @@ Every failing :cfunc:`malloc` call must be turned into an exception --- the direct caller of :cfunc:`malloc` (or :cfunc:`realloc`) must call -:cfunc:`PyErr_NoMemory` and return a failure indicator itself. All the object- -creating functions (for example, :cfunc:`PyInt_FromLong`) already do this, so -this note is only relevant to those who call :cfunc:`malloc` directly. +:cfunc:`PyErr_NoMemory` and return a failure indicator itself. All the +object-creating functions (for example, :cfunc:`PyInt_FromLong`) already do +this, so this note is only relevant to those who call :cfunc:`malloc` directly. Also note that, with the important exception of :cfunc:`PyArg_ParseTuple` and friends, functions that return an integer status usually return a positive value @@ -332,9 +332,9 @@ When embedding Python, the :cfunc:`initspam` function is not called automatically unless there's an entry in the :cdata:`_PyImport_Inittab` table. -The easiest way to handle this is to statically initialize your statically- -linked modules by directly calling :cfunc:`initspam` after the call to -:cfunc:`Py_Initialize`:: +The easiest way to handle this is to statically initialize your +statically-linked modules by directly calling :cfunc:`initspam` after the call +to :cfunc:`Py_Initialize`:: int main(int argc, char *argv[]) @@ -488,10 +488,10 @@ Py_DECREF(arglist); :cfunc:`PyEval_CallObject` returns a Python object pointer: this is the return -value of the Python function. :cfunc:`PyEval_CallObject` is "reference-count- -neutral" with respect to its arguments. In the example a new tuple was created -to serve as the argument list, which is :cfunc:`Py_DECREF`\ -ed immediately -after the call. +value of the Python function. :cfunc:`PyEval_CallObject` is +"reference-count-neutral" with respect to its arguments. In the example a new +tuple was created to serve as the argument list, which is :cfunc:`Py_DECREF`\ +-ed immediately after the call. The return value of :cfunc:`PyEval_CallObject` is "new": either it is a brand new object, or it is an existing object whose reference count has been Modified: doctools/trunk/Doc-26/extending/newtypes.rst ============================================================================== --- doctools/trunk/Doc-26/extending/newtypes.rst (original) +++ doctools/trunk/Doc-26/extending/newtypes.rst Sun Aug 5 00:45:13 2007 @@ -700,10 +700,10 @@ >>> l = [n] >>> n.first = l -This is pretty silly, but it gives us an excuse to add support for the cyclic- -garbage collector to the :class:`Noddy` example. To support cyclic garbage -collection, types need to fill two slots and set a class flag that enables these -slots: +This is pretty silly, but it gives us an excuse to add support for the +cyclic-garbage collector to the :class:`Noddy` example. To support cyclic +garbage collection, types need to fill two slots and set a class flag that +enables these slots: .. literalinclude:: ../includes/noddy4.c Modified: doctools/trunk/Doc-26/howto/advocacy.rst ============================================================================== --- doctools/trunk/Doc-26/howto/advocacy.rst (original) +++ doctools/trunk/Doc-26/howto/advocacy.rst Sun Aug 5 00:45:13 2007 @@ -232,9 +232,9 @@ being considered another one of Python's advantages. Most questions posted to the comp.lang.python newsgroup are quickly answered by someone. -Should you need to dig into the source code, you'll find it's clear and well- -organized, so it's not very difficult to write extensions and track down bugs -yourself. If you'd prefer to pay for support, there are companies and +Should you need to dig into the source code, you'll find it's clear and +well-organized, so it's not very difficult to write extensions and track down +bugs yourself. If you'd prefer to pay for support, there are companies and individuals who offer commercial support for Python. **Who uses Python for serious work?** Modified: doctools/trunk/Doc-26/howto/curses.rst ============================================================================== --- doctools/trunk/Doc-26/howto/curses.rst (original) +++ doctools/trunk/Doc-26/howto/curses.rst Sun Aug 5 00:45:13 2007 @@ -15,36 +15,37 @@ What is curses? =============== -The curses library supplies a terminal-independent screen-painting and keyboard- -handling facility for text-based terminals; such terminals include VT100s, the -Linux console, and the simulated terminal provided by X11 programs such as xterm -and rxvt. Display terminals support various control codes to perform common -operations such as moving the cursor, scrolling the screen, and erasing areas. -Different terminals use widely differing codes, and often have their own minor -quirks. - -In a world of X displays, one might ask "why bother"? It's true that character- -cell display terminals are an obsolete technology, but there are niches in which -being able to do fancy things with them are still valuable. One is on small- -footprint or embedded Unixes that don't carry an X server. Another is for -tools like OS installers and kernel configurators that may have to run before X -is available. +The curses library supplies a terminal-independent screen-painting and +keyboard-handling facility for text-based terminals; such terminals include +VT100s, the Linux console, and the simulated terminal provided by X11 programs +such as xterm and rxvt. Display terminals support various control codes to +perform common operations such as moving the cursor, scrolling the screen, and +erasing areas. Different terminals use widely differing codes, and often have +their own minor quirks. + +In a world of X displays, one might ask "why bother"? It's true that +character-cell display terminals are an obsolete technology, but there are +niches in which being able to do fancy things with them are still valuable. One +is on small-footprint or embedded Unixes that don't carry an X server. Another +is for tools like OS installers and kernel configurators that may have to run +before X is available. The curses library hides all the details of different terminals, and provides -the programmer with an abstraction of a display, containing multiple non- -overlapping windows. The contents of a window can be changed in various ways-- -adding text, erasing it, changing its appearance--and the curses library will -automagically figure out what control codes need to be sent to the terminal to -produce the right output. +the programmer with an abstraction of a display, containing multiple +non-overlapping windows. The contents of a window can be changed in various +ways-- adding text, erasing it, changing its appearance--and the curses library +will automagically figure out what control codes need to be sent to the terminal +to produce the right output. The curses library was originally written for BSD Unix; the later System V versions of Unix from AT&T added many enhancements and new functions. BSD curses -is no longer maintained, having been replaced by ncurses, which is an open- -source implementation of the AT&T interface. If you're using an open-source -Unix such as Linux or FreeBSD, your system almost certainly uses ncurses. Since -most current commercial Unix versions are based on System V code, all the -functions described here will probably be available. The older versions of -curses carried by some proprietary Unixes may not support everything, though. +is no longer maintained, having been replaced by ncurses, which is an +open-source implementation of the AT&T interface. If you're using an +open-source Unix such as Linux or FreeBSD, your system almost certainly uses +ncurses. Since most current commercial Unix versions are based on System V +code, all the functions described here will probably be available. The older +versions of curses carried by some proprietary Unixes may not support +everything, though. No one has made a Windows port of the curses module. On a Windows platform, try the Console module written by Fredrik Lundh. The Console module provides Modified: doctools/trunk/Doc-26/howto/doanddont.rst ============================================================================== --- doctools/trunk/Doc-26/howto/doanddont.rst (original) +++ doctools/trunk/Doc-26/howto/doanddont.rst Sun Aug 5 00:45:13 2007 @@ -272,8 +272,8 @@ print reduce(operator.add, nums)/len(nums) This cute little script prints the average of all numbers given on the command -line. The :func:`reduce` adds up all the numbers, and the rest is just some pre- -and postprocessing. +line. The :func:`reduce` adds up all the numbers, and the rest is just some +pre- and postprocessing. On the same note, note that :func:`float`, :func:`int` and :func:`long` all accept arguments of type string, and so are suited to parsing --- assuming you Modified: doctools/trunk/Doc-26/howto/functional.rst ============================================================================== --- doctools/trunk/Doc-26/howto/functional.rst (original) +++ doctools/trunk/Doc-26/howto/functional.rst Sun Aug 5 00:45:13 2007 @@ -1035,7 +1035,7 @@ Grouping elements -''''''''''''''''' +----------------- The last function I'll discuss, ``itertools.groupby(iter, key_func=None)``, is the most complicated. ``key_func(elem)`` is a function that can compute a key Modified: doctools/trunk/Doc-26/howto/regex.rst ============================================================================== --- doctools/trunk/Doc-26/howto/regex.rst (original) +++ doctools/trunk/Doc-26/howto/regex.rst Sun Aug 5 00:45:13 2007 @@ -367,9 +367,9 @@ :file:`Tools/scripts/redemo.py`, a demonstration program included with the Python distribution. It allows you to enter REs and strings, and displays whether the RE matches or fails. :file:`redemo.py` can be quite useful when -trying to debug a complicated RE. Phil Schwartz's `Kodos `_ is also an interactive tool for developing and testing -RE patterns. +trying to debug a complicated RE. Phil Schwartz's `Kodos +`_ is also an interactive tool for +developing and testing RE patterns. This HOWTO uses the standard Python interpreter for its examples. First, run the Python interpreter, import the :mod:`re` module, and compile a RE:: @@ -708,10 +708,10 @@ Matches only at the end of the string. ``\b`` - Word boundary. This is a zero-width assertion that matches only at the + Word boundary. This is a zero-width assertion that matches only at the beginning or end of a word. A word is defined as a sequence of alphanumeric - characters, so the end of a word is indicated by whitespace or a non- - alphanumeric character. + characters, so the end of a word is indicated by whitespace or a + non-alphanumeric character. The following example matches ``class`` only when it's a complete word; it won't match when it's contained inside another word. :: @@ -1057,7 +1057,7 @@ :func:`re.split` function, too. -.. method:: .split(string [, maxsplit\ ``= 0``]) +.. method:: .split(string [, maxsplit=0]) :noindex: Split *string* by the matches of the regular expression. If capturing @@ -1108,7 +1108,7 @@ which can be either a string or a function, and the string to be processed. -.. method:: .sub(replacement, string[, count\ ``= 0``]) +.. method:: .sub(replacement, string[, count=0]) :noindex: Returns the string obtained by replacing the leftmost non-overlapping @@ -1307,11 +1307,11 @@ >>> print re.match('<.*?>', s).group() -(Note that parsing HTML or XML with regular expressions is painful. Quick-and- -dirty patterns will handle common cases, but HTML and XML have special cases -that will break the obvious regular expression; by the time you've written a -regular expression that handles all of the possible cases, the patterns will be -*very* complicated. Use an HTML or XML parser module for such tasks.) +(Note that parsing HTML or XML with regular expressions is painful. +Quick-and-dirty patterns will handle common cases, but HTML and XML have special +cases that will break the obvious regular expression; by the time you've written +a regular expression that handles all of the possible cases, the patterns will +be *very* complicated. Use an HTML or XML parser module for such tasks.) Not Using re.VERBOSE @@ -1366,9 +1366,9 @@ Friedl's Mastering Regular Expressions, published by O'Reilly. Unfortunately, it exclusively concentrates on Perl and Java's flavours of regular expressions, and doesn't contain any Python material at all, so it won't be useful as a -reference for programming in Python. (The first edition covered Python's now- -removed :mod:`regex` module, which won't help you much.) Consider checking it -out from your library. +reference for programming in Python. (The first edition covered Python's +now-removed :mod:`regex` module, which won't help you much.) Consider checking +it out from your library. .. rubric:: Footnotes Modified: doctools/trunk/Doc-26/howto/sockets.rst ============================================================================== --- doctools/trunk/Doc-26/howto/sockets.rst (original) +++ doctools/trunk/Doc-26/howto/sockets.rst Sun Aug 5 00:45:13 2007 @@ -29,8 +29,8 @@ better behavior and performance from a STREAM socket than anything else. I will try to clear up the mystery of what a socket is, as well as some hints on how to work with blocking and non-blocking sockets. But I'll start by talking about -blocking sockets. You'll need to know how they work before dealing with non- -blocking sockets. +blocking sockets. You'll need to know how they work before dealing with +non-blocking sockets. Part of the trouble with understanding these things is that "socket" can mean a number of subtly different things, depending on context. So first, let's make a @@ -361,12 +361,12 @@ empty) of the corresponding list you passed in. And if you put a socket in more than one input list, it will only be (at most) in one output list. -If a socket is in the output readable list, you can be as-close-to-certain-as- -we-ever-get-in-this-business that a ``recv`` on that socket will return -*something*. Same idea for the writable list. You'll be able to send -*something*. Maybe not all you want to, but *something* is better than nothing. -(Actually, any reasonably healthy socket will return as writable - it just means -outbound network buffer space is available.) +If a socket is in the output readable list, you can be +as-close-to-certain-as-we-ever-get-in-this-business that a ``recv`` on that +socket will return *something*. Same idea for the writable list. You'll be able +to send *something*. Maybe not all you want to, but *something* is better than +nothing. (Actually, any reasonably healthy socket will return as writable - it +just means outbound network buffer space is available.) If you have a "server" socket, put it in the potential_readers list. If it comes out in the readable list, your ``accept`` will (almost certainly) work. If you Modified: doctools/trunk/Doc-26/howto/urllib2.rst ============================================================================== --- doctools/trunk/Doc-26/howto/urllib2.rst (original) +++ doctools/trunk/Doc-26/howto/urllib2.rst Sun Aug 5 00:45:13 2007 @@ -432,7 +432,7 @@ ==================== To illustrate creating and installing a handler we will use the -``HTTPBasicAuthHandler``. For a more detailed discussion of this subject - +``HTTPBasicAuthHandler``. For a more detailed discussion of this subject -- including an explanation of how Basic Authentication works - see the `Basic Authentication Tutorial `_. Modified: doctools/trunk/Doc-26/install/index.rst ============================================================================== --- doctools/trunk/Doc-26/install/index.rst (original) +++ doctools/trunk/Doc-26/install/index.rst Sun Aug 5 00:45:13 2007 @@ -263,7 +263,7 @@ can find out what your Python installation uses for :file:`{prefix}` and :file:`{exec-prefix}` by running Python in interactive mode and typing a few simple commands. Under Unix, just type ``python`` at the shell prompt. Under -Windows, choose :menuselection:`Start --> Programs --> Python |version|--> +Windows, choose :menuselection:`Start --> Programs --> Python X.Y --> Python (command line)`. Once the interpreter is started, you type Python code at the prompt. For example, on my Linux system, I type the three Python statements shown below, and get the output as shown, to find out my @@ -506,8 +506,8 @@ If you want to define an entire installation scheme, you just have to supply all of the installation directory options. The recommended way to do this is to -supply relative paths; for example, if you want to maintain all Python module- -related files under :file:`python` in your home directory, and you want a +supply relative paths; for example, if you want to maintain all Python +module-related files under :file:`python` in your home directory, and you want a separate directory for each platform that you use your home directory from, you might define the following installation scheme:: @@ -645,8 +645,8 @@ There are two environment variables that can modify ``sys.path``. :envvar:`PYTHONHOME` sets an alternate value for the prefix of the Python installation. For example, if :envvar:`PYTHONHOME` is set to ``/www/python``, -the search path will be set to ``['', '/www/python/lib/python|version|/', -'/www/python/lib/python|version|/plat-linux2', ...]``. +the search path will be set to ``['', '/www/python/lib/pythonX.Y/', +'/www/python/lib/pythonX.Y/plat-linux2', ...]``. The :envvar:`PYTHONPATH` variable can be set to a list of paths that will be added to the beginning of ``sys.path``. For example, if :envvar:`PYTHONPATH` is @@ -812,8 +812,8 @@ Compiling a Python extension written in C or C++ will sometimes require specifying custom flags for the compiler and linker in order to use a particular library or produce a special kind of object code. This is especially true if the -extension hasn't been tested on your platform, or if you're trying to cross- -compile Python. +extension hasn't been tested on your platform, or if you're trying to +cross-compile Python. In the most general case, the extension author might have foreseen that compiling the extensions would be complicated, and provided a :file:`Setup` file Modified: doctools/trunk/Doc-26/library/_winreg.rst ============================================================================== --- doctools/trunk/Doc-26/library/_winreg.rst (original) +++ doctools/trunk/Doc-26/library/_winreg.rst Sun Aug 5 00:45:13 2007 @@ -178,7 +178,7 @@ :const:`HKEY_LOCAL_MACHINE` tree. This may or may not be true. -.. function:: OpenKey(key, sub_key[, res\ ``= 0``][, sam\ ``= KEY_READ``]) +.. function:: OpenKey(key, sub_key[, res=0][, sam=KEY_READ]) Opens the specified key, returning a :dfn:`handle object` Modified: doctools/trunk/Doc-26/library/asyncore.rst ============================================================================== --- doctools/trunk/Doc-26/library/asyncore.rst (original) +++ doctools/trunk/Doc-26/library/asyncore.rst Sun Aug 5 00:45:13 2007 @@ -23,15 +23,15 @@ are probably what you really need. Network servers are rarely processor bound, however. -If your operating system supports the :cfunc:`select` system call in its I/O -library (and nearly all do), then you can use it to juggle multiple -communication channels at once; doing other work while your I/O is taking place -in the "background." Although this strategy can seem strange and complex, -especially at first, it is in many ways easier to understand and control than -multi-threaded programming. The :mod:`asyncore` module solves many of the -difficult problems for you, making the task of building sophisticated high- -performance network servers and clients a snap. For "conversational" -applications and protocols the companion :mod:`asynchat` module is invaluable. +If your operating system supports the :cfunc:`select` system call in its I/O +library (and nearly all do), then you can use it to juggle multiple +communication channels at once; doing other work while your I/O is taking place +in the "background." Although this strategy can seem strange and complex, +especially at first, it is in many ways easier to understand and control than +multi-threaded programming. The :mod:`asyncore` module solves many of the +difficult problems for you, making the task of building sophisticated +high-performance network servers and clients a snap. For "conversational" +applications and protocols the companion :mod:`asynchat` module is invaluable. The basic idea behind both modules is to create one or more network *channels*, instances of class :class:`asyncore.dispatcher` and Modified: doctools/trunk/Doc-26/library/binascii.rst ============================================================================== --- doctools/trunk/Doc-26/library/binascii.rst (original) +++ doctools/trunk/Doc-26/library/binascii.rst Sun Aug 5 00:45:13 2007 @@ -16,8 +16,8 @@ binary and various ASCII-encoded binary representations. Normally, you will not use these functions directly but use wrapper modules like :mod:`uu`, :mod:`base64`, or :mod:`binhex` instead. The :mod:`binascii` module contains -low-level functions written in C for greater speed that are used by the higher- -level modules. +low-level functions written in C for greater speed that are used by the +higher-level modules. The :mod:`binascii` module defines the following functions: Modified: doctools/trunk/Doc-26/library/bz2.rst ============================================================================== --- doctools/trunk/Doc-26/library/bz2.rst (original) +++ doctools/trunk/Doc-26/library/bz2.rst Sun Aug 5 00:45:13 2007 @@ -74,8 +74,8 @@ .. method:: BZ2File.readline([size]) - Return the next line from the file, as a string, retaining newline. A non- - negative *size* argument limits the maximum number of bytes to return (an + Return the next line from the file, as a string, retaining newline. A + non-negative *size* argument limits the maximum number of bytes to return (an incomplete line may be returned then). Return an empty string at EOF. Modified: doctools/trunk/Doc-26/library/cgi.rst ============================================================================== --- doctools/trunk/Doc-26/library/cgi.rst (original) +++ doctools/trunk/Doc-26/library/cgi.rst Sun Aug 5 00:45:13 2007 @@ -552,7 +552,7 @@ .. rubric:: Footnotes .. [#] Note that some recent versions of the HTML specification do state what order the - field values should be supplied in, but knowing whether a request was received - from a conforming browser, or even from a browser at all, is tedious and error- - prone. + field values should be supplied in, but knowing whether a request was + received from a conforming browser, or even from a browser at all, is tedious + and error-prone. Modified: doctools/trunk/Doc-26/library/chunk.rst ============================================================================== --- doctools/trunk/Doc-26/library/chunk.rst (original) +++ doctools/trunk/Doc-26/library/chunk.rst Sun Aug 5 00:45:13 2007 @@ -53,18 +53,18 @@ .. class:: Chunk(file[, align, bigendian, inclheader]) - 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 only - method that is needed is :meth:`read`. If the methods :meth:`seek` and - :meth:`tell` are present and don't raise an exception, they are also used. If - these methods are present and raise an exception, they are expected to not have - altered the object. If the optional argument *align* is true, chunks are - assumed to be aligned on 2-byte boundaries. If *align* is false, no alignment - is assumed. The default value is true. If the optional argument *bigendian* is - false, the chunk size is assumed to be in little-endian order. This is needed - for WAVE audio files. The default value is true. If the optional argument - *inclheader* is true, the size given in the chunk header includes the size of - the header. The default value is 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 + only method that is needed is :meth:`read`. If the methods :meth:`seek` and + :meth:`tell` are present and don't raise an exception, they are also used. + If these methods are present and raise an exception, they are expected to not + have altered the object. If the optional argument *align* is true, chunks + are assumed to be aligned on 2-byte boundaries. If *align* is false, no + alignment is assumed. The default value is true. If the optional argument + *bigendian* is false, the chunk size is assumed to be in little-endian order. + This is needed for WAVE audio files. The default value is true. If the + optional argument *inclheader* is true, the size given in the chunk header + includes the size of the header. The default value is false. A :class:`Chunk` object supports the following methods: Modified: doctools/trunk/Doc-26/library/cmath.rst ============================================================================== --- doctools/trunk/Doc-26/library/cmath.rst (original) +++ doctools/trunk/Doc-26/library/cmath.rst Sun Aug 5 00:45:13 2007 @@ -7,12 +7,12 @@ This module is always available. It provides access to mathematical functions -for complex numbers. The functions in this module accept integers, floating- -point numbers or complex numbers as arguments. They will also accept any Python -object that has either a :meth:`__complex__` or a :meth:`__float__` method: -these methods are used to convert the object to a complex or floating-point -number, respectively, and the function is then applied to the result of the -conversion. +for complex numbers. The functions in this module accept integers, +floating-point numbers or complex numbers as arguments. They will also accept +any Python object that has either a :meth:`__complex__` or a :meth:`__float__` +method: these methods are used to convert the object to a complex or +floating-point number, respectively, and the function is then applied to the +result of the conversion. The functions are: Modified: doctools/trunk/Doc-26/library/code.rst ============================================================================== --- doctools/trunk/Doc-26/library/code.rst (original) +++ doctools/trunk/Doc-26/library/code.rst Sun Aug 5 00:45:13 2007 @@ -73,15 +73,15 @@ :func:`compile_command`; the default for *filename* is ``''``, and for *symbol* is ``'single'``. One several things can happen: -* The input is incorrect; :func:`compile_command` raised an exception + * The input is incorrect; :func:`compile_command` raised an exception (:exc:`SyntaxError` or :exc:`OverflowError`). A syntax traceback will be printed by calling the :meth:`showsyntaxerror` method. :meth:`runsource` returns ``False``. -* The input is incomplete, and more input is required; :func:`compile_command` + * The input is incomplete, and more input is required; :func:`compile_command` returned ``None``. :meth:`runsource` returns ``True``. -* The input is complete; :func:`compile_command` returned a code object. The + * The input is complete; :func:`compile_command` returned a code object. The code is executed by calling the :meth:`runcode` (which also handles run-time exceptions, except for :exc:`SystemExit`). :meth:`runsource` returns ``False``. Modified: doctools/trunk/Doc-26/library/codecs.rst ============================================================================== --- doctools/trunk/Doc-26/library/codecs.rst (original) +++ doctools/trunk/Doc-26/library/codecs.rst Sun Aug 5 00:45:13 2007 @@ -30,19 +30,19 @@ argument, the encoding name in all lower case letters, and return a :class:`CodecInfo` object having the following attributes: -* ``name`` The name of the encoding; + * ``name`` The name of the encoding; -* ``encoder`` The stateless encoding function; + * ``encoder`` The stateless encoding function; -* ``decoder`` The stateless decoding function; + * ``decoder`` The stateless decoding function; -* ``incrementalencoder`` An incremental encoder class or factory function; + * ``incrementalencoder`` An incremental encoder class or factory function; -* ``incrementaldecoder`` An incremental decoder class or factory function; + * ``incrementaldecoder`` An incremental decoder class or factory function; -* ``streamwriter`` A stream writer class or factory function; + * ``streamwriter`` A stream writer class or factory function; -* ``streamreader`` A stream reader class or factory function. + * ``streamreader`` A stream reader class or factory function. The various functions or classes take the following arguments: @@ -408,15 +408,15 @@ The :class:`IncrementalEncoder` may implement different error handling schemes by providing the *errors* keyword argument. These parameters are predefined: -* ``'strict'`` Raise :exc:`ValueError` (or a subclass); this is the default. + * ``'strict'`` Raise :exc:`ValueError` (or a subclass); this is the default. -* ``'ignore'`` Ignore the character and continue with the next. + * ``'ignore'`` Ignore the character and continue with the next. -* ``'replace'`` Replace with a suitable replacement character + * ``'replace'`` Replace with a suitable replacement character -* ``'xmlcharrefreplace'`` Replace with the appropriate XML character reference + * ``'xmlcharrefreplace'`` Replace with the appropriate XML character reference -* ``'backslashreplace'`` Replace with backslashed escape sequences. + * ``'backslashreplace'`` Replace with backslashed escape sequences. The *errors* argument will be assigned to an attribute of the same name. Assigning to this attribute makes it possible to switch between different error @@ -460,11 +460,11 @@ The :class:`IncrementalDecoder` may implement different error handling schemes by providing the *errors* keyword argument. These parameters are predefined: -* ``'strict'`` Raise :exc:`ValueError` (or a subclass); this is the default. + * ``'strict'`` Raise :exc:`ValueError` (or a subclass); this is the default. -* ``'ignore'`` Ignore the character and continue with the next. + * ``'ignore'`` Ignore the character and continue with the next. -* ``'replace'`` Replace with a suitable replacement character. + * ``'replace'`` Replace with a suitable replacement character. The *errors* argument will be assigned to an attribute of the same name. Assigning to this attribute makes it possible to switch between different error @@ -518,15 +518,15 @@ The :class:`StreamWriter` may implement different error handling schemes by providing the *errors* keyword argument. These parameters are predefined: -* ``'strict'`` Raise :exc:`ValueError` (or a subclass); this is the default. + * ``'strict'`` Raise :exc:`ValueError` (or a subclass); this is the default. -* ``'ignore'`` Ignore the character and continue with the next. + * ``'ignore'`` Ignore the character and continue with the next. -* ``'replace'`` Replace with a suitable replacement character + * ``'replace'`` Replace with a suitable replacement character -* ``'xmlcharrefreplace'`` Replace with the appropriate XML character reference + * ``'xmlcharrefreplace'`` Replace with the appropriate XML character reference -* ``'backslashreplace'`` Replace with backslashed escape sequences. + * ``'backslashreplace'`` Replace with backslashed escape sequences. The *errors* argument will be assigned to an attribute of the same name. Assigning to this attribute makes it possible to switch between different error @@ -582,11 +582,11 @@ The :class:`StreamReader` may implement different error handling schemes by providing the *errors* keyword argument. These parameters are defined: -* ``'strict'`` Raise :exc:`ValueError` (or a subclass); this is the default. + * ``'strict'`` Raise :exc:`ValueError` (or a subclass); this is the default. -* ``'ignore'`` Ignore the character and continue with the next. + * ``'ignore'`` Ignore the character and continue with the next. -* ``'replace'`` Replace with a suitable replacement character. + * ``'replace'`` Replace with a suitable replacement character. The *errors* argument will be assigned to an attribute of the same name. Assigning to this attribute makes it possible to switch between different error Modified: doctools/trunk/Doc-26/library/codeop.rst ============================================================================== --- doctools/trunk/Doc-26/library/codeop.rst (original) +++ doctools/trunk/Doc-26/library/codeop.rst Sun Aug 5 00:45:13 2007 @@ -10,10 +10,11 @@ .. % LaTeXed from excellent doc-string. -The :mod:`codeop` module provides utilities upon which the Python read-eval- -print loop can be emulated, as is done in the :mod:`code` module. As a result, -you probably don't want to use the module directly; if you want to include such -a loop in your program you probably want to use the :mod:`code` module instead. +The :mod:`codeop` module provides utilities upon which the Python +read-eval-print loop can be emulated, as is done in the :mod:`code` module. As +a result, you probably don't want to use the module directly; if you want to +include such a loop in your program you probably want to use the :mod:`code` +module instead. There are two parts to this job: Modified: doctools/trunk/Doc-26/library/cookie.rst ============================================================================== --- doctools/trunk/Doc-26/library/cookie.rst (original) +++ doctools/trunk/Doc-26/library/cookie.rst Sun Aug 5 00:45:13 2007 @@ -145,19 +145,13 @@ Morsels are dictionary-like objects, whose set of keys is constant --- the valid :rfc:`2109` attributes, which are -* ``expires`` - -* ``path`` - -* ``comment`` - -* ``domain`` - -* ``max-age`` - -* ``secure`` - -* ``version`` + * ``expires`` + * ``path`` + * ``comment`` + * ``domain`` + * ``max-age`` + * ``secure`` + * ``version`` The keys are case-insensitive. Modified: doctools/trunk/Doc-26/library/cookielib.rst ============================================================================== --- doctools/trunk/Doc-26/library/cookielib.rst (original) +++ doctools/trunk/Doc-26/library/cookielib.rst Sun Aug 5 00:45:13 2007 @@ -94,10 +94,10 @@ received in a :mailheader:`Set-Cookie` header with a version cookie-attribute of 1) are treated according to the RFC 2965 rules. However, if RFC 2965 handling is turned off or :attr:`rfc2109_as_netscape` is True, RFC 2109 cookies are - 'downgraded' by the :class:`CookieJar` instance to Netscape cookies, by setting - the :attr:`version` attribute of the :class:`Cookie` instance to 0. - :class:`DefaultCookiePolicy` also provides some parameters to allow some fine- - tuning of policy. + 'downgraded' by the :class:`CookieJar` instance to Netscape cookies, by + setting the :attr:`version` attribute of the :class:`Cookie` instance to 0. + :class:`DefaultCookiePolicy` also provides some parameters to allow some + fine-tuning of policy. .. class:: Cookie() @@ -320,8 +320,8 @@ .. note:: - This loses information about RFC 2965 cookies, and also about newer or non- - standard cookie-attributes such as ``port``. + This loses information about RFC 2965 cookies, and also about newer or + non-standard cookie-attributes such as ``port``. .. warning:: @@ -608,9 +608,10 @@ :class:`Cookie` instances have Python attributes roughly corresponding to the standard cookie-attributes specified in the various cookie standards. The correspondence is not one-to-one, because there are complicated rules for -assigning default values, because the ``max-age`` and ``expires`` cookie- -attributes contain equivalent information, and because RFC 2109 cookies may be -'downgraded' by :mod:`cookielib` from version 1 to version 0 (Netscape) cookies. +assigning default values, because the ``max-age`` and ``expires`` +cookie-attributes contain equivalent information, and because RFC 2109 cookies +may be 'downgraded' by :mod:`cookielib` from version 1 to version 0 (Netscape) +cookies. Assignment to these attributes should not be necessary other than in rare circumstances in a :class:`CookiePolicy` method. The class does not enforce @@ -676,11 +677,11 @@ .. attribute:: Cookie.rfc2109 - True if this cookie was received as an RFC 2109 cookie (ie. the cookie arrived - in a :mailheader:`Set-Cookie` header, and the value of the Version cookie- - attribute in that header was 1). This attribute is provided because - :mod:`cookielib` may 'downgrade' RFC 2109 cookies to Netscape cookies, in which - case :attr:`version` is 0. + True if this cookie was received as an RFC 2109 cookie (ie. the cookie + arrived in a :mailheader:`Set-Cookie` header, and the value of the Version + cookie-attribute in that header was 1). This attribute is provided because + :mod:`cookielib` may 'downgrade' RFC 2109 cookies to Netscape cookies, in + which case :attr:`version` is 0. .. versionadded:: 2.5 Modified: doctools/trunk/Doc-26/library/csv.rst ============================================================================== --- doctools/trunk/Doc-26/library/csv.rst (original) +++ doctools/trunk/Doc-26/library/csv.rst Sun Aug 5 00:45:13 2007 @@ -59,7 +59,7 @@ The :mod:`csv` module defines the following functions: -.. function:: reader(csvfile[, dialect=``'excel'``][, fmtparam]) +.. function:: reader(csvfile[, dialect='excel'][, fmtparam]) Return a reader object which will iterate over lines in the given *csvfile*. *csvfile* can be any object which supports the iterator protocol and returns a @@ -87,7 +87,7 @@ be split into lines in a manner which preserves the newline characters. -.. function:: writer(csvfile[, dialect=``'excel'``][, fmtparam]) +.. function:: writer(csvfile[, dialect='excel'][, fmtparam]) Return a writer object responsible for converting the user's data into delimited strings on the given file-like object. *csvfile* can be any object with a @@ -143,7 +143,7 @@ The :mod:`csv` module defines the following classes: -.. class:: DictReader(csvfile[, fieldnames=:const:`None`,[, restkey=:const:`None`[, restval=:const:`None`[, dialect=``'excel'``[, *args, **kwds]]]]]) +.. class:: DictReader(csvfile[, fieldnames=:const:None,[, restkey=:const:None[, restval=None[, dialect='excel'[, *args, **kwds]]]]]) Create an object which operates like a regular reader but maps the information read into a dict whose keys are given by the optional *fieldnames* parameter. @@ -157,7 +157,7 @@ arguments are passed to the underlying :class:`reader` instance. -.. class:: DictWriter(csvfile, fieldnames[, restval=""[, extrasaction=``'raise'``[, dialect=``'excel'``[, *args, **kwds]]]]) +.. class:: DictWriter(csvfile, fieldnames[, restval=''[, extrasaction='raise'[, dialect='excel'[, *args, **kwds]]]]) Create an object which operates like a regular writer but maps dictionaries onto output rows. The *fieldnames* parameter identifies the order in which values in @@ -202,7 +202,7 @@ The :class:`Sniffer` class provides two methods: -.. method:: Sniffer.sniff(sample[,delimiters=None]) +.. method:: Sniffer.sniff(sample[, delimiters=None]) Analyze the given *sample* and return a :class:`Dialect` subclass reflecting the parameters found. If the optional *delimiters* parameter is given, it is Modified: doctools/trunk/Doc-26/library/ctypes.rst ============================================================================== --- doctools/trunk/Doc-26/library/ctypes.rst (original) +++ doctools/trunk/Doc-26/library/ctypes.rst Sun Aug 5 00:45:13 2007 @@ -1910,9 +1910,9 @@ .. function:: string_at(address[, size]) - This function returns the string starting at memory address address. If size is - specified, it is used as size, otherwise the string is assumed to be zero- - terminated. + This function returns the string starting at memory address address. If size + is specified, it is used as size, otherwise the string is assumed to be + zero-terminated. .. function:: WinError(code=None, descr=None) @@ -1928,8 +1928,8 @@ This function returns the wide character string starting at memory address ``address`` as unicode string. If ``size`` is specified, it is used as the - number of characters of the string, otherwise the string is assumed to be zero- - terminated. + number of characters of the string, otherwise the string is assumed to be + zero-terminated. .. _ctypes-data-types: @@ -2198,9 +2198,9 @@ .. class:: c_wchar_p - Represents the C ``wchar_t *`` datatype, which must be a pointer to a zero- - terminated wide character string. The constructor accepts an integer address, or - a string. + Represents the C ``wchar_t *`` datatype, which must be a pointer to a + zero-terminated wide character string. The constructor accepts an integer + address, or a string. .. class:: c_bool Modified: doctools/trunk/Doc-26/library/curses.rst ============================================================================== --- doctools/trunk/Doc-26/library/curses.rst (original) +++ doctools/trunk/Doc-26/library/curses.rst Sun Aug 5 00:45:13 2007 @@ -11,8 +11,8 @@ .. versionchanged:: 1.6 Added support for the ``ncurses`` library and converted to a package. -The :mod:`curses` module provides an interface to the curses library, the de- -facto standard for portable advanced terminal handling. +The :mod:`curses` module provides an interface to the curses library, the +de-facto standard for portable advanced terminal handling. While curses is most widely used in the Unix environment, versions are available for DOS, OS/2, and possibly other systems as well. This extension module is @@ -641,10 +641,10 @@ attributes *attr*. The change is then applied to every character position in that window: -* The attribute of every character in the window is changed to the new + * The attribute of every character in the window is changed to the new background attribute. -* Wherever the former background character appears, it is changed to the new + * Wherever the former background character appears, it is changed to the new background character. @@ -1023,7 +1023,7 @@ *sminrow*, or *smincol* are treated as if they were zero. -.. method:: window.scroll([lines\ ``= 1``]) +.. method:: window.scroll([lines=1]) Scroll the screen or scrolling region upward by *lines* lines. @@ -1526,8 +1526,8 @@ The :mod:`curses.textpad` module provides a :class:`Textbox` class that handles elementary text editing in a curses window, supporting a set of keybindings resembling those of Emacs (thus, also of Netscape Navigator, BBedit 6.x, -FrameMaker, and many other programs). The module also provides a rectangle- -drawing function useful for framing text boxes or for other purposes. +FrameMaker, and many other programs). The module also provides a +rectangle-drawing function useful for framing text boxes or for other purposes. The module :mod:`curses.textpad` defines the following function: Modified: doctools/trunk/Doc-26/library/datetime.rst ============================================================================== --- doctools/trunk/Doc-26/library/datetime.rst (original) +++ doctools/trunk/Doc-26/library/datetime.rst Sun Aug 5 00:45:13 2007 @@ -139,22 +139,17 @@ Only *days*, *seconds* and *microseconds* are stored internally. Arguments are converted to those units: -* A millisecond is converted to 1000 microseconds. - -* A minute is converted to 60 seconds. - -* An hour is converted to 3600 seconds. - -* A week is converted to 7 days. + * A millisecond is converted to 1000 microseconds. + * A minute is converted to 60 seconds. + * An hour is converted to 3600 seconds. + * A week is converted to 7 days. and days, seconds and microseconds are then normalized so that the representation is unique, with -* ``0 <= microseconds < 1000000`` - -* ``0 <= seconds < 3600*24`` (the number of seconds in one day) - -* ``-999999999 <= days <= 999999999`` + * ``0 <= microseconds < 1000000`` + * ``0 <= seconds < 3600*24`` (the number of seconds in one day) + * ``-999999999 <= days <= 999999999`` If any argument is a float and there are fractional microseconds, the fractional microseconds left over from all arguments are combined and their sum is rounded @@ -291,11 +286,9 @@ All arguments are required. Arguments may be ints or longs, in the following ranges: -* ``MINYEAR <= year <= MAXYEAR`` - -* ``1 <= month <= 12`` - -* ``1 <= day <= number of days in the given month and year`` + * ``MINYEAR <= year <= MAXYEAR`` + * ``1 <= month <= 12`` + * ``1 <= day <= number of days in the given month and year`` If an argument outside those ranges is given, :exc:`ValueError` is raised. @@ -514,19 +507,13 @@ instance of a :class:`tzinfo` subclass. The remaining arguments may be ints or longs, in the following ranges: -* ``MINYEAR <= year <= MAXYEAR`` - -* ``1 <= month <= 12`` - -* ``1 <= day <= number of days in the given month and year`` - -* ``0 <= hour < 24`` - -* ``0 <= minute < 60`` - -* ``0 <= second < 60`` - -* ``0 <= microsecond < 1000000`` + * ``MINYEAR <= year <= MAXYEAR`` + * ``1 <= month <= 12`` + * ``1 <= day <= number of days in the given month and year`` + * ``0 <= hour < 24`` + * ``0 <= minute < 60`` + * ``0 <= second < 60`` + * ``0 <= microsecond < 1000000`` If an argument outside those ranges is given, :exc:`ValueError` is raised. @@ -894,13 +881,14 @@ .. method:: datetime.isoformat([sep]) - Return a string representing the date and time in ISO 8601 format, YYYY-MM- - DDTHH:MM:SS.mmmmmm or, if :attr:`microsecond` is 0, YYYY-MM-DDTHH:MM:SS - - If :meth:`utcoffset` does not return ``None``, a 6-character string is appended, - giving the UTC offset in (signed) hours and minutes: YYYY-MM- - DDTHH:MM:SS.mmmmmm+HH:MM or, if :attr:`microsecond` is 0 YYYY-MM- - DDTHH:MM:SS+HH:MM + Return a string representing the date and time in ISO 8601 format, + YYYY-MM-DDTHH:MM:SS.mmmmmm or, if :attr:`microsecond` is 0, + YYYY-MM-DDTHH:MM:SS + + If :meth:`utcoffset` does not return ``None``, a 6-character string is + appended, giving the UTC offset in (signed) hours and minutes: + YYYY-MM-DDTHH:MM:SS.mmmmmm+HH:MM or, if :attr:`microsecond` is 0 + YYYY-MM-DDTHH:MM:SS+HH:MM The optional argument *sep* (default ``'T'``) is a one-character separator, placed between the date and time portions of the result. For example, :: @@ -949,13 +937,10 @@ :class:`tzinfo` subclass. The remaining arguments may be ints or longs, in the following ranges: -* ``0 <= hour < 24`` - -* ``0 <= minute < 60`` - -* ``0 <= second < 60`` - -* ``0 <= microsecond < 1000000``. + * ``0 <= hour < 24`` + * ``0 <= minute < 60`` + * ``0 <= second < 60`` + * ``0 <= microsecond < 1000000``. If an argument outside those ranges is given, :exc:`ValueError` is raised. All default to ``0`` except *tzinfo*, which defaults to :const:`None`. Modified: doctools/trunk/Doc-26/library/decimal.rst ============================================================================== --- doctools/trunk/Doc-26/library/decimal.rst (original) +++ doctools/trunk/Doc-26/library/decimal.rst Sun Aug 5 00:45:13 2007 @@ -509,19 +509,13 @@ The *rounding* option is one of: -* :const:`ROUND_CEILING` (towards :const:`Infinity`), - -* :const:`ROUND_DOWN` (towards zero), - -* :const:`ROUND_FLOOR` (towards :const:`-Infinity`), - -* :const:`ROUND_HALF_DOWN` (to nearest with ties going towards zero), - -* :const:`ROUND_HALF_EVEN` (to nearest with ties going to nearest even integer), - -* :const:`ROUND_HALF_UP` (to nearest with ties going away from zero), or - -* :const:`ROUND_UP` (away from zero). + * :const:`ROUND_CEILING` (towards :const:`Infinity`), + * :const:`ROUND_DOWN` (towards zero), + * :const:`ROUND_FLOOR` (towards :const:`-Infinity`), + * :const:`ROUND_HALF_DOWN` (to nearest with ties going towards zero), + * :const:`ROUND_HALF_EVEN` (to nearest with ties going to nearest even integer), + * :const:`ROUND_HALF_UP` (to nearest with ties going away from zero), or + * :const:`ROUND_UP` (away from zero). The *traps* and *flags* fields list any signals to be set. Generally, new contexts should only set traps and leave the flags clear. @@ -1260,10 +1254,10 @@ Q. Within a complex calculation, how can I make sure that I haven't gotten a spurious result because of insufficient precision or rounding anomalies. -A. The decimal module makes it easy to test results. A best practice is to re- -run calculations using greater precision and with various rounding modes. Widely -differing results indicate insufficient precision, rounding mode issues, ill- -conditioned inputs, or a numerically unstable algorithm. +A. The decimal module makes it easy to test results. A best practice is to +re-run calculations using greater precision and with various rounding modes. +Widely differing results indicate insufficient precision, rounding mode issues, +ill-conditioned inputs, or a numerically unstable algorithm. Q. I noticed that context precision is applied to the results of operations but not to the inputs. Is there anything to watch out for when mixing values of Modified: doctools/trunk/Doc-26/library/difflib.rst ============================================================================== --- doctools/trunk/Doc-26/library/difflib.rst (original) +++ doctools/trunk/Doc-26/library/difflib.rst Sun Aug 5 00:45:13 2007 @@ -34,10 +34,10 @@ .. class:: Differ - This is a class for comparing sequences of lines of text, and producing human- - readable differences or deltas. Differ uses :class:`SequenceMatcher` both to - compare sequences of lines, and to compare sequences of characters within - similar (near-matching) lines. + This is a class for comparing sequences of lines of text, and producing + human-readable differences or deltas. Differ uses :class:`SequenceMatcher` + both to compare sequences of lines, and to compare sequences of characters + within similar (near-matching) lines. Each line of a :class:`Differ` delta begins with a two-letter code: Modified: doctools/trunk/Doc-26/library/dis.rst ============================================================================== --- doctools/trunk/Doc-26/library/dis.rst (original) +++ doctools/trunk/Doc-26/library/dis.rst Sun Aug 5 00:45:13 2007 @@ -50,19 +50,13 @@ Disassembles a code object, indicating the last instruction if *lasti* was provided. The output is divided in the following columns: -#. the line number, for the first instruction of each line - -#. the current instruction, indicated as ``-->``, - -#. a labelled instruction, indicated with ``>>``, - -#. the address of the instruction, - -#. the operation code name, - -#. operation parameters, and - -#. interpretation of the parameters in parentheses. + #. the line number, for the first instruction of each line + #. the current instruction, indicated as ``-->``, + #. a labelled instruction, indicated with ``>>``, + #. the address of the instruction, + #. the operation code name, + #. operation parameters, and + #. interpretation of the parameters in parentheses. The parameter interpretation recognizes local and global variable names, constant values, branch targets, and compare operators. @@ -541,8 +535,8 @@ .. opcode:: UNPACK_SEQUENCE (count) - Unpacks TOS into *count* individual values, which are put onto the stack right- - to-left. + Unpacks TOS into *count* individual values, which are put onto the stack + right-to-left. .. % \begin{opcodedesc}{UNPACK_LIST}{count} .. % This opcode is obsolete. Modified: doctools/trunk/Doc-26/library/dl.rst ============================================================================== --- doctools/trunk/Doc-26/library/dl.rst (original) +++ doctools/trunk/Doc-26/library/dl.rst Sun Aug 5 00:45:13 2007 @@ -28,7 +28,7 @@ The :mod:`dl` module defines the following function: -.. function:: open(name[, mode\ ``= RTLD_LAZY``]) +.. function:: open(name[, mode=RTLD_LAZY]) Open a shared object file, and return a handle. Mode signifies late binding (:const:`RTLD_LAZY`) or immediate binding (:const:`RTLD_NOW`). Default is Modified: doctools/trunk/Doc-26/library/doctest.rst ============================================================================== --- doctools/trunk/Doc-26/library/doctest.rst (original) +++ doctools/trunk/Doc-26/library/doctest.rst Sun Aug 5 00:45:13 2007 @@ -435,10 +435,10 @@ are ignored by doctest. The traceback stack is typically omitted, or copied verbatim from an interactive session. -The traceback stack is followed by the most interesting part: the line(s) +The traceback stack is followed by the most interesting part: the line(s) containing the exception type and detail. This is usually the last line of a -traceback, but can extend across multiple lines if the exception has a multi- -line detail:: +traceback, but can extend across multiple lines if the exception has a +multi-line detail:: >>> raise ValueError('multi\n line\ndetail') Traceback (most recent call last): @@ -823,14 +823,14 @@ Optional argument *module_relative* specifies how the filename should be interpreted: -* If *module_relative* is ``True`` (the default), then *filename* specifies an + * If *module_relative* is ``True`` (the default), then *filename* specifies an OS-independent module-relative path. By default, this path is relative to the calling module's directory; but if the *package* argument is specified, then it is relative to that package. To ensure OS-independence, *filename* should use ``/`` characters to separate path segments, and may not be an absolute path (i.e., it may not begin with ``/``). -* If *module_relative* is ``False``, then *filename* specifies an OS-specific + * If *module_relative* is ``False``, then *filename* specifies an OS-specific path. The path may be absolute or relative; relative paths are resolved with respect to the current working directory. @@ -1000,14 +1000,14 @@ Optional argument *module_relative* specifies how the filenames in *paths* should be interpreted: -* If *module_relative* is ``True`` (the default), then each filename specifies + * If *module_relative* is ``True`` (the default), then each filename specifies an OS-independent module-relative path. By default, this path is relative to the calling module's directory; but if the *package* argument is specified, then it is relative to that package. To ensure OS-independence, each filename should use ``/`` characters to separate path segments, and may not be an absolute path (i.e., it may not begin with ``/``). -* If *module_relative* is ``False``, then each filename specifies an OS-specific + * If *module_relative* is ``False``, then each filename specifies an OS-specific path. The path may be absolute or relative; relative paths are resolved with respect to the current working directory. @@ -1074,8 +1074,8 @@ Optional argument *extraglobs* specifies an extra set of global variables, which is merged into *globs*. By default, no extra globals are used. - Optional argument *test_finder* is the :class:`DocTestFinder` object (or a drop- - in replacement) that is used to extract doctests from the module. + Optional argument *test_finder* is the :class:`DocTestFinder` object (or a + drop-in replacement) that is used to extract doctests from the module. Optional arguments *setUp*, *tearDown*, and *optionflags* are the same as for function :func:`DocFileSuite` above. @@ -1346,15 +1346,15 @@ If the module is not specified or is None, then the test finder will attempt to automatically determine the correct module. The object's module is used: -* As a default namespace, if *globs* is not specified. + * As a default namespace, if *globs* is not specified. -* To prevent the DocTestFinder from extracting DocTests from objects that are + * To prevent the DocTestFinder from extracting DocTests from objects that are imported from other modules. (Contained objects with modules other than *module* are ignored.) -* To find the name of the file containing the object. + * To find the name of the file containing the object. -* To help find the line number of the object within its file. + * To help find the line number of the object within its file. If *module* is ``False``, no attempt to find the module will be made. This is obscure, of use mostly in testing doctest itself: if *module* is ``False``, or Modified: doctools/trunk/Doc-26/library/email.charset.rst ============================================================================== --- doctools/trunk/Doc-26/library/email.charset.rst (original) +++ doctools/trunk/Doc-26/library/email.charset.rst Sun Aug 5 00:45:13 2007 @@ -149,8 +149,8 @@ .. method:: Charset.encoded_header_len() - Return the length of the encoded header string, properly calculating for quoted- - printable or base64 encoding. + Return the length of the encoded header string, properly calculating for + quoted-printable or base64 encoding. .. method:: Charset.header_encode(s[, convert]) @@ -210,11 +210,11 @@ *charset* is the input character set, and must be the canonical name of a character set. - Optional *header_enc* and *body_enc* is either ``Charset.QP`` for quoted- - printable, ``Charset.BASE64`` for base64 encoding, ``Charset.SHORTEST`` for the - shortest of quoted-printable or base64 encoding, or ``None`` for no encoding. - ``SHORTEST`` is only valid for *header_enc*. The default is ``None`` for no - encoding. + Optional *header_enc* and *body_enc* is either ``Charset.QP`` for + quoted-printable, ``Charset.BASE64`` for base64 encoding, + ``Charset.SHORTEST`` for the shortest of quoted-printable or base64 encoding, + or ``None`` for no encoding. ``SHORTEST`` is only valid for + *header_enc*. The default is ``None`` for no encoding. Optional *output_charset* is the character set that the output should be in. Conversions will proceed from input charset, to Unicode, to the output charset Modified: doctools/trunk/Doc-26/library/email.generator.rst ============================================================================== --- doctools/trunk/Doc-26/library/email.generator.rst (original) +++ doctools/trunk/Doc-26/library/email.generator.rst Sun Aug 5 00:45:13 2007 @@ -100,17 +100,17 @@ string that is used instead of the message payload. *fmt* is expanded with the following keywords, ``%(keyword)s`` format: -* ``type`` -- Full MIME type of the non-\ :mimetype:`text` part + * ``type`` -- Full MIME type of the non-\ :mimetype:`text` part -* ``maintype`` -- Main MIME type of the non-\ :mimetype:`text` part + * ``maintype`` -- Main MIME type of the non-\ :mimetype:`text` part -* ``subtype`` -- Sub-MIME type of the non-\ :mimetype:`text` part + * ``subtype`` -- Sub-MIME type of the non-\ :mimetype:`text` part -* ``filename`` -- Filename of the non-\ :mimetype:`text` part + * ``filename`` -- Filename of the non-\ :mimetype:`text` part -* ``description`` -- Description associated with the non-\ :mimetype:`text` part + * ``description`` -- Description associated with the non-\ :mimetype:`text` part -* ``encoding`` -- Content transfer encoding of the non-\ :mimetype:`text` part + * ``encoding`` -- Content transfer encoding of the non-\ :mimetype:`text` part The default value for *fmt* is ``None``, meaning :: Modified: doctools/trunk/Doc-26/library/email.message.rst ============================================================================== --- doctools/trunk/Doc-26/library/email.message.rst (original) +++ doctools/trunk/Doc-26/library/email.message.rst Sun Aug 5 00:45:13 2007 @@ -15,10 +15,10 @@ value are separated by a colon. The colon is not part of either the field name or the field value. -Headers are stored and returned in case-preserving form but are matched case- -insensitively. There may also be a single envelope header, also known as the -*Unix-From* header or the ``From_`` header. The payload is either a string in -the case of simple message objects or a list of :class:`Message` objects for +Headers are stored and returned in case-preserving form but are matched +case-insensitively. There may also be a single envelope header, also known as +the *Unix-From* header or the ``From_`` header. The payload is either a string +in the case of simple message objects or a list of :class:`Message` objects for MIME container documents (e.g. :mimetype:`multipart/\*` and :mimetype:`message/rfc822`). Modified: doctools/trunk/Doc-26/library/email.parser.rst ============================================================================== --- doctools/trunk/Doc-26/library/email.parser.rst (original) +++ doctools/trunk/Doc-26/library/email.parser.rst Sun Aug 5 00:45:13 2007 @@ -51,11 +51,11 @@ The :class:`FeedParser`'s API is simple; you create an instance, feed it a bunch of text until there's no more to feed it, then close the parser to retrieve the root message object. The :class:`FeedParser` is extremely accurate when parsing -standards-compliant messages, and it does a very good job of parsing non- -compliant messages, providing information about how a message was deemed broken. -It will populate a message object's *defects* attribute with a list of any -problems it found in a message. See the :mod:`email.errors` module for the list -of defects that it can find. +standards-compliant messages, and it does a very good job of parsing +non-compliant messages, providing information about how a message was deemed +broken. It will populate a message object's *defects* attribute with a list of +any problems it found in a message. See the :mod:`email.errors` module for the +list of defects that it can find. Here is the API for the :class:`FeedParser`: @@ -108,10 +108,10 @@ The optional *strict* flag is ignored. .. deprecated:: 2.4 - Because the :class:`Parser` class is a backward compatible API wrapper around - the new-in-Python 2.4 :class:`FeedParser`, *all* parsing is effectively non- - strict. You should simply stop passing a *strict* flag to the :class:`Parser` - constructor. + Because the :class:`Parser` class is a backward compatible API wrapper + around the new-in-Python 2.4 :class:`FeedParser`, *all* parsing is + effectively non-strict. You should simply stop passing a *strict* flag to + the :class:`Parser` constructor. .. versionchanged:: 2.2.2 The *strict* flag was added. @@ -129,10 +129,10 @@ the :meth:`read` methods on file-like objects. The text contained in *fp* must be formatted as a block of :rfc:`2822` style - headers and header continuation lines, optionally preceded by a envelope header. - The header block is terminated either by the end of the data or by a blank line. - Following the header block is the body of the message (which may contain MIME- - encoded subparts). + headers and header continuation lines, optionally preceded by a envelope + header. The header block is terminated either by the end of the data or by a + blank line. Following the header block is the body of the message (which may + contain MIME-encoded subparts). Optional *headersonly* is as with the :meth:`parse` method. Modified: doctools/trunk/Doc-26/library/errno.rst ============================================================================== --- doctools/trunk/Doc-26/library/errno.rst (original) +++ doctools/trunk/Doc-26/library/errno.rst Sun Aug 5 00:45:13 2007 @@ -8,8 +8,8 @@ This module makes available standard ``errno`` system symbols. The value of each symbol is the corresponding integer value. The names and descriptions are -borrowed from :file:`linux/include/errno.h`, which should be pretty all- -inclusive. +borrowed from :file:`linux/include/errno.h`, which should be pretty +all-inclusive. .. data:: errorcode Modified: doctools/trunk/Doc-26/library/fcntl.rst ============================================================================== --- doctools/trunk/Doc-26/library/fcntl.rst (original) +++ doctools/trunk/Doc-26/library/fcntl.rst Sun Aug 5 00:45:13 2007 @@ -104,29 +104,26 @@ the file descriptor of the file to lock or unlock, and *operation* is one of the following values: -* :const:`LOCK_UN` -- unlock - -* :const:`LOCK_SH` -- acquire a shared lock - -* :const:`LOCK_EX` -- acquire an exclusive lock - - When *operation* is :const:`LOCK_SH` or :const:`LOCK_EX`, it can also be bit- - wise OR'd with :const:`LOCK_NB` to avoid blocking on lock acquisition. If - :const:`LOCK_NB` is used and the lock cannot be acquired, an :exc:`IOError` will - be raised and the exception will have an *errno* attribute set to - :const:`EACCES` or :const:`EAGAIN` (depending on the operating system; for - portability, check for both values). On at least some systems, :const:`LOCK_EX` - can only be used if the file descriptor refers to a file opened for writing. + * :const:`LOCK_UN` -- unlock + * :const:`LOCK_SH` -- acquire a shared lock + * :const:`LOCK_EX` -- acquire an exclusive lock + + When *operation* is :const:`LOCK_SH` or :const:`LOCK_EX`, it can also be + bit-wise OR'd with :const:`LOCK_NB` to avoid blocking on lock acquisition. + If :const:`LOCK_NB` is used and the lock cannot be acquired, an + :exc:`IOError` will be raised and the exception will have an *errno* + attribute set to :const:`EACCES` or :const:`EAGAIN` (depending on the + operating system; for portability, check for both values). On at least some + systems, :const:`LOCK_EX` can only be used if the file descriptor refers to a + file opened for writing. *length* is the number of bytes to lock, *start* is the byte offset at which the lock starts, relative to *whence*, and *whence* is as with :func:`fileobj.seek`, specifically: -* :const:`0` -- relative to the start of the file (:const:`SEEK_SET`) - -* :const:`1` -- relative to the current buffer position (:const:`SEEK_CUR`) - -* :const:`2` -- relative to the end of the file (:const:`SEEK_END`) + * :const:`0` -- relative to the start of the file (:const:`SEEK_SET`) + * :const:`1` -- relative to the current buffer position (:const:`SEEK_CUR`) + * :const:`2` -- relative to the end of the file (:const:`SEEK_END`) The default for *start* is 0, which means to start at the beginning of the file. The default for *length* is 0 which means to lock to the end of the file. The @@ -151,7 +148,8 @@ .. seealso:: Module :mod:`os` - If the locking flags :const:`O_SHLOCK` and :const:`O_EXLOCK` are present in the - :mod:`os` module, the :func:`os.open` function provides a more platform- - independent alternative to the :func:`lockf` and :func:`flock` functions. + If the locking flags :const:`O_SHLOCK` and :const:`O_EXLOCK` are present + in the :mod:`os` module, the :func:`os.open` function provides a more + platform-independent alternative to the :func:`lockf` and :func:`flock` + functions. Modified: doctools/trunk/Doc-26/library/formatter.rst ============================================================================== --- doctools/trunk/Doc-26/library/formatter.rst (original) +++ doctools/trunk/Doc-26/library/formatter.rst Sun Aug 5 00:45:13 2007 @@ -169,7 +169,7 @@ :const:`AS_IS` values, is passed to the writer's :meth:`new_styles` method. -.. method:: formatter.pop_style([n\ ``= 1``]) +.. method:: formatter.pop_style([n=1]) Pop the last *n* style specifications passed to :meth:`push_style`. A tuple representing the revised stack, including :const:`AS_IS` values, is passed to @@ -181,12 +181,12 @@ Set the spacing style for the writer. -.. method:: formatter.assert_line_data([flag\ ``= 1``]) +.. method:: formatter.assert_line_data([flag=1]) - Inform the formatter that data has been added to the current paragraph out-of- - band. This should be used when the writer has been manipulated directly. The - optional *flag* argument can be set to false if the writer manipulations - produced a hard line break at the end of the output. + Inform the formatter that data has been added to the current paragraph + out-of-band. This should be used when the writer has been manipulated + directly. The optional *flag* argument can be set to false if the writer + manipulations produced a hard line break at the end of the output. .. _formatter-impls: @@ -341,7 +341,7 @@ output. -.. class:: DumbWriter([file[, maxcol\ ``= 72``]]) +.. class:: DumbWriter([file[, maxcol=72]]) Simple writer class which writes output on the file object passed in as *file* or, if *file* is omitted, on standard output. The output is simply word-wrapped Modified: doctools/trunk/Doc-26/library/fpectl.rst ============================================================================== --- doctools/trunk/Doc-26/library/fpectl.rst (original) +++ doctools/trunk/Doc-26/library/fpectl.rst Sun Aug 5 00:45:13 2007 @@ -17,10 +17,10 @@ .. index:: single: IEEE-754 -Most computers carry out floating point operations in conformance with the so- -called IEEE-754 standard. On any real computer, some floating point operations -produce results that cannot be expressed as a normal floating point value. For -example, try :: +Most computers carry out floating point operations in conformance with the +so-called IEEE-754 standard. On any real computer, some floating point +operations produce results that cannot be expressed as a normal floating point +value. For example, try :: >>> import math >>> math.exp(1000) Modified: doctools/trunk/Doc-26/library/functions.rst ============================================================================== --- doctools/trunk/Doc-26/library/functions.rst (original) +++ doctools/trunk/Doc-26/library/functions.rst Sun Aug 5 00:45:13 2007 @@ -39,16 +39,17 @@ its *locals* argument at all, and uses its *globals* only to determine the package context of the :keyword:`import` statement.) - When the *name* variable is of the form ``package.module``, normally, the top- - level package (the name up till the first dot) is returned, *not* the module - named by *name*. However, when a non-empty *fromlist* argument is given, the - module named by *name* is returned. This is done for compatibility with the - bytecode generated for the different kinds of import statement; when using - ``import spam.ham.eggs``, the top-level package :mod:`spam` must be placed in - the importing namespace, but when using ``from spam.ham import eggs``, the - ``spam.ham`` subpackage must be used to find the ``eggs`` variable. As a - workaround for this behavior, use :func:`getattr` to extract the desired - components. For example, you could define the following helper:: + When the *name* variable is of the form ``package.module``, normally, the + top-level package (the name up till the first dot) is returned, *not* the + module named by *name*. However, when a non-empty *fromlist* argument is + given, the module named by *name* is returned. This is done for + compatibility with the bytecode generated for the different kinds of import + statement; when using ``import spam.ham.eggs``, the top-level package + :mod:`spam` must be placed in the importing namespace, but when using ``from + spam.ham import eggs``, the ``spam.ham`` subpackage must be used to find the + ``eggs`` variable. As a workaround for this behavior, use :func:`getattr` to + extract the desired components. For example, you could define the following + helper:: def my_import(name): mod = __import__(name) @@ -259,19 +260,19 @@ keyword is retained in the dictionary. For example, these all return a dictionary equal to ``{"one": 2, "two": 3}``: -* ``dict({'one': 2, 'two': 3})`` + * ``dict({'one': 2, 'two': 3})`` -* ``dict({'one': 2, 'two': 3}.items())`` + * ``dict({'one': 2, 'two': 3}.items())`` -* ``dict({'one': 2, 'two': 3}.iteritems())`` + * ``dict({'one': 2, 'two': 3}.iteritems())`` -* ``dict(zip(('one', 'two'), (2, 3)))`` + * ``dict(zip(('one', 'two'), (2, 3)))`` -* ``dict([['two', 3], ['one', 2]])`` + * ``dict([['two', 3], ['one', 2]])`` -* ``dict(one=2, two=3)`` + * ``dict(one=2, two=3)`` -* ``dict([(['one', 'two'][i-2], i) for i in (2, 3)])`` + * ``dict([(['one', 'two'][i-2], i) for i in (2, 3)])`` .. versionadded:: 2.2 @@ -924,18 +925,18 @@ When ``reload(module)`` is executed: -* Python modules' code is recompiled and the module-level code reexecuted, + * Python modules' code is recompiled and the module-level code reexecuted, defining a new set of objects which are bound to names in the module's dictionary. The ``init`` function of extension modules is not called a second time. -* As with all other objects in Python the old objects are only reclaimed after + * As with all other objects in Python the old objects are only reclaimed after their reference counts drop to zero. -* The names in the module namespace are updated to point to any new or changed + * The names in the module namespace are updated to point to any new or changed objects. -* Other references to the old objects (such as names external to the module) are + * Other references to the old objects (such as names external to the module) are not rebound to refer to the new objects and must be updated in each namespace where they occur if that is desired. Modified: doctools/trunk/Doc-26/library/gdbm.rst ============================================================================== --- doctools/trunk/Doc-26/library/gdbm.rst (original) +++ doctools/trunk/Doc-26/library/gdbm.rst Sun Aug 5 00:45:13 2007 @@ -40,13 +40,13 @@ The following additional characters may be appended to the flag to control how the database is opened: -* ``'f'`` --- Open the database in fast mode. Writes to the database will not + * ``'f'`` --- Open the database in fast mode. Writes to the database will not be synchronized. -* ``'s'`` --- Synchronized mode. This will cause changes to the database will be + * ``'s'`` --- Synchronized mode. This will cause changes to the database will be immediately written to the file. -* ``'u'`` --- Do not lock database. + * ``'u'`` --- Do not lock database. Not all flags are valid for all versions of ``gdbm``. The module constant ``open_flags`` is a string of supported flag characters. The exception Modified: doctools/trunk/Doc-26/library/getopt.rst ============================================================================== --- doctools/trunk/Doc-26/library/getopt.rst (original) +++ doctools/trunk/Doc-26/library/getopt.rst Sun Aug 5 00:45:13 2007 @@ -43,13 +43,13 @@ The return value consists of two elements: the first is a list of ``(option, value)`` pairs; the second is the list of program arguments left after the - option list was stripped (this is a trailing slice of *args*). Each option-and- - value pair returned has the option as its first element, prefixed with a hyphen - for short options (e.g., ``'-x'``) or two hyphens for long options (e.g., - ``'-``\ ``-long-option'``), and the option argument as its second element, or an - empty string if the option has no argument. The options occur in the list in - the same order in which they were found, thus allowing multiple occurrences. - Long and short options may be mixed. + option list was stripped (this is a trailing slice of *args*). Each + option-and-value pair returned has the option as its first element, prefixed + with a hyphen for short options (e.g., ``'-x'``) or two hyphens for long + options (e.g., ``'-``\ ``-long-option'``), and the option argument as its + second element, or an empty string if the option has no argument. The + options occur in the list in the same order in which they were found, thus + allowing multiple occurrences. Long and short options may be mixed. .. function:: gnu_getopt(args, options[, long_options]) @@ -60,8 +60,8 @@ non-option argument is encountered. If the first character of the option string is '+', or if the environment - variable POSIXLY_CORRECT is set, then option processing stops as soon as a non- - option argument is encountered. + variable POSIXLY_CORRECT is set, then option processing stops as soon as a + non-option argument is encountered. .. versionadded:: 2.3 Modified: doctools/trunk/Doc-26/library/gettext.rst ============================================================================== --- doctools/trunk/Doc-26/library/gettext.rst (original) +++ doctools/trunk/Doc-26/library/gettext.rst Sun Aug 5 00:45:13 2007 @@ -385,10 +385,10 @@ ids and message strings read from the catalog are converted to Unicode using this encoding. The :meth:`ugettext` method always returns a Unicode, while the :meth:`gettext` returns an encoded 8-bit string. For the message id arguments -of both methods, either Unicode strings or 8-bit strings containing only US- -ASCII characters are acceptable. Note that the Unicode version of the methods -(i.e. :meth:`ugettext` and :meth:`ungettext`) are the recommended interface to -use for internationalized Python programs. +of both methods, either Unicode strings or 8-bit strings containing only +US-ASCII characters are acceptable. Note that the Unicode version of the +methods (i.e. :meth:`ugettext` and :meth:`ungettext`) are the recommended +interface to use for internationalized Python programs. The entire set of key/value pairs are placed into a dictionary and set as the "protected" :attr:`_info` instance variable. Modified: doctools/trunk/Doc-26/library/httplib.rst ============================================================================== --- doctools/trunk/Doc-26/library/httplib.rst (original) +++ doctools/trunk/Doc-26/library/httplib.rst Sun Aug 5 00:45:13 2007 @@ -100,8 +100,8 @@ .. exception:: InvalidURL - A subclass of :exc:`HTTPException`, raised if a port is given and is either non- - numeric or empty. + A subclass of :exc:`HTTPException`, raised if a port is given and is either + non-numeric or empty. .. versionadded:: 2.3 @@ -396,11 +396,11 @@ This will send a request to the server using the HTTP request method *method* and the selector *url*. If the *body* argument is present, it should be a - string of data to send after the headers are finished. Alternatively, it may be - an open file object, in which case the contents of the file is sent; this file - object should support ``fileno()`` and ``read()`` methods. The header Content- - Length is automatically set to the correct value. The *headers* argument should - be a mapping of extra HTTP headers to send with the request. + string of data to send after the headers are finished. Alternatively, it may + be an open file object, in which case the contents of the file is sent; this + file object should support ``fileno()`` and ``read()`` methods. The header + Content-Length is automatically set to the correct value. The *headers* + argument should be a mapping of extra HTTP headers to send with the request. .. versionchanged:: 2.6 *body* can be a file object. Modified: doctools/trunk/Doc-26/library/imageop.rst ============================================================================== --- doctools/trunk/Doc-26/library/imageop.rst (original) +++ doctools/trunk/Doc-26/library/imageop.rst Sun Aug 5 00:45:13 2007 @@ -53,8 +53,8 @@ .. function:: dither2mono(image, width, height) - Convert an 8-bit greyscale image to a 1-bit monochrome image using a (simple- - minded) dithering algorithm. + Convert an 8-bit greyscale image to a 1-bit monochrome image using a + (simple-minded) dithering algorithm. .. function:: mono2grey(image, width, height, p0, p1) @@ -93,11 +93,12 @@ .. data:: backward_compatible - If set to 0, the functions in this module use a non-backward compatible way of - representing multi-byte pixels on little-endian systems. The SGI for which this - module was originally written is a big-endian system, so setting this variable - will have no effect. However, the code wasn't originally intended to run on - anything else, so it made assumptions about byte order which are not universal. - Setting this variable to 0 will cause the byte order to be reversed on little- - endian systems, so that it then is the same as on big-endian systems. + If set to 0, the functions in this module use a non-backward compatible way + of representing multi-byte pixels on little-endian systems. The SGI for + which this module was originally written is a big-endian system, so setting + this variable will have no effect. However, the code wasn't originally + intended to run on anything else, so it made assumptions about byte order + which are not universal. Setting this variable to 0 will cause the byte + order to be reversed on little-endian systems, so that it then is the same as + on big-endian systems. Modified: doctools/trunk/Doc-26/library/imaplib.rst ============================================================================== --- doctools/trunk/Doc-26/library/imaplib.rst (original) +++ doctools/trunk/Doc-26/library/imaplib.rst Sun Aug 5 00:45:13 2007 @@ -232,8 +232,8 @@ .. method:: IMAP4.getannotation(mailbox, entry, attribute) - Retrieve the specified ``ANNOTATION``\ s for *mailbox*. The method is non- - standard, but is supported by the ``Cyrus`` server. + Retrieve the specified ``ANNOTATION``\ s for *mailbox*. The method is + non-standard, but is supported by the ``Cyrus`` server. .. versionadded:: 2.5 Modified: doctools/trunk/Doc-26/library/imp.rst ============================================================================== --- doctools/trunk/Doc-26/library/imp.rst (original) +++ doctools/trunk/Doc-26/library/imp.rst Sun Aug 5 00:45:13 2007 @@ -179,12 +179,12 @@ .. function:: init_frozen(name) - Initialize the frozen module called *name* and return its module object. If the - module was already initialized, it will be initialized *again*. If there is no - frozen module called *name*, ``None`` is returned. (Frozen modules are modules - written in Python whose compiled byte-code object is incorporated into a custom- - built Python interpreter by Python's :program:`freeze` utility. See - :file:`Tools/freeze/` for now.) + Initialize the frozen module called *name* and return its module object. If + the module was already initialized, it will be initialized *again*. If there + is no frozen module called *name*, ``None`` is returned. (Frozen modules are + modules written in Python whose compiled byte-code object is incorporated + into a custom-built Python interpreter by Python's :program:`freeze` + utility. See :file:`Tools/freeze/` for now.) .. function:: is_builtin(name) @@ -242,10 +242,10 @@ .. class:: NullImporter(path_string) - The :class:`NullImporter` type is a :pep:`302` import hook that handles non- - directory path strings by failing to find any modules. Calling this type with - an existing directory or empty string raises :exc:`ImportError`. Otherwise, a - :class:`NullImporter` instance is returned. + The :class:`NullImporter` type is a :pep:`302` import hook that handles + non-directory path strings by failing to find any modules. Calling this type + with an existing directory or empty string raises :exc:`ImportError`. + Otherwise, a :class:`NullImporter` instance is returned. Python adds instances of this type to ``sys.path_importer_cache`` for any path entries that are not directories and are not handled by any other path hooks on Modified: doctools/trunk/Doc-26/library/inspect.rst ============================================================================== --- doctools/trunk/Doc-26/library/inspect.rst (original) +++ doctools/trunk/Doc-26/library/inspect.rst Sun Aug 5 00:45:13 2007 @@ -202,12 +202,12 @@ identified by *path* if it is a module, or ``None`` if it would not be identified as a module. The return tuple is ``(name, suffix, mode, mtype)``, where *name* is the name of the module without the name of any enclosing - package, *suffix* is the trailing part of the file name (which may not be a dot- - delimited extension), *mode* is the :func:`open` mode that would be used - (``'r'`` or ``'rb'``), and *mtype* is an integer giving the type of the module. - *mtype* will have a value which can be compared to the constants defined in the - :mod:`imp` module; see the documentation for that module for more information on - module types. + package, *suffix* is the trailing part of the file name (which may not be a + dot-delimited extension), *mode* is the :func:`open` mode that would be used + (``'r'`` or ``'rb'``), and *mtype* is an integer giving the type of the + module. *mtype* will have a value which can be compared to the constants + defined in the :mod:`imp` module; see the documentation for that module for + more information on module types. .. function:: getmodulename(path) Modified: doctools/trunk/Doc-26/library/itertools.rst ============================================================================== --- doctools/trunk/Doc-26/library/itertools.rst (original) +++ doctools/trunk/Doc-26/library/itertools.rst Sun Aug 5 00:45:13 2007 @@ -279,16 +279,16 @@ last tuple can be pre-padded with fill values using ``izip(*[chain(s, [None]*(n-1))]*n)``. - Note, when :func:`izip` is used with unequal length inputs, subsequent iteration - over the longer iterables cannot reliably be continued after :func:`izip` - terminates. Potentially, up to one entry will be missing from each of the left- - over iterables. This occurs because a value is fetched from each iterator in- - turn, but the process ends when one of the iterators terminates. This leaves - the last fetched values in limbo (they cannot be returned in a final, incomplete - tuple and they are cannot be pushed back into the iterator for retrieval with - ``it.next()``). In general, :func:`izip` should only be used with unequal - length inputs when you don't care about trailing, unmatched values from the - longer iterables. + Note, when :func:`izip` is used with unequal length inputs, subsequent + iteration over the longer iterables cannot reliably be continued after + :func:`izip` terminates. Potentially, up to one entry will be missing from + each of the left-over iterables. This occurs because a value is fetched from + each iterator in turn, but the process ends when one of the iterators + terminates. This leaves the last fetched values in limbo (they cannot be + returned in a final, incomplete tuple and they are cannot be pushed back into + the iterator for retrieval with ``it.next()``). In general, :func:`izip` + should only be used with unequal length inputs when you don't care about + trailing, unmatched values from the longer iterables. .. function:: izip_longest(*iterables[, fillvalue]) Modified: doctools/trunk/Doc-26/library/logging.rst ============================================================================== --- doctools/trunk/Doc-26/library/logging.rst (original) +++ doctools/trunk/Doc-26/library/logging.rst Sun Aug 5 00:45:13 2007 @@ -984,9 +984,9 @@ ^^^^^^^^^^^^^ The :class:`StreamHandler` class, located in the core :mod:`logging` package, -sends logging output to streams such as *sys.stdout*, *sys.stderr* or any file- -like object (or, more precisely, any object which supports :meth:`write` and -:meth:`flush` methods). +sends logging output to streams such as *sys.stdout*, *sys.stderr* or any +file-like object (or, more precisely, any object which supports :meth:`write` +and :meth:`flush` methods). .. class:: StreamHandler([strm]) @@ -1635,8 +1635,8 @@ .. method:: LogRecord.getMessage() - Returns the message for this :class:`LogRecord` instance after merging any user- - supplied arguments with the message. + Returns the message for this :class:`LogRecord` instance after merging any + user-supplied arguments with the message. Thread Safety Modified: doctools/trunk/Doc-26/library/mailbox.rst ============================================================================== --- doctools/trunk/Doc-26/library/mailbox.rst (original) +++ doctools/trunk/Doc-26/library/mailbox.rst Sun Aug 5 00:45:13 2007 @@ -617,12 +617,13 @@ the last message, a line containing a Control-Underscore (``'\\037'``) character. -Messages in a Babyl mailbox have two sets of headers, original headers and so- -called visible headers. Visible headers are typically a subset of the original -headers that have been reformatted or abridged to be more attractive. Each -message in a Babyl mailbox also has an accompanying list of :dfn:`labels`, or -short strings that record extra information about the message, and a list of all -user-defined labels found in the mailbox is kept in the Babyl options section. +Messages in a Babyl mailbox have two sets of headers, original headers and +so-called visible headers. Visible headers are typically a subset of the +original headers that have been reformatted or abridged to be more +attractive. Each message in a Babyl mailbox also has an accompanying list of +:dfn:`labels`, or short strings that record extra information about the message, +and a list of all user-defined labels found in the mailbox is kept in the Babyl +options section. :class:`Babyl` instances have all of the methods of :class:`Mailbox` in addition to the following: @@ -772,8 +773,8 @@ "info" section added to its file name to store information about its state. (Some mail readers may also add an "info" section to messages in :file:`new`.) The "info" section may take one of two forms: it may contain "2," followed by a -list of standardized flags (e.g., "2,FR") or it may contain "1," followed by so- -called experimental information. Standard flags for Maildir messages are as +list of standardized flags (e.g., "2,FR") or it may contain "1," followed by +so-called experimental information. Standard flags for Maildir messages are as follows: +------+---------+--------------------------------+ @@ -1540,9 +1541,9 @@ :class:`UnixMailbox` except that individual messages are separated by only ``From`` lines. - For more information, see `Configuring Netscape Mail on Unix: Why the Content- - Length Format is Bad `_. + For more information, see `Configuring Netscape Mail on Unix: Why the + Content-Length Format is Bad + `_. .. class:: PortableUnixMailbox(fp[, factory]) Modified: doctools/trunk/Doc-26/library/math.rst ============================================================================== --- doctools/trunk/Doc-26/library/math.rst (original) +++ doctools/trunk/Doc-26/library/math.rst Sun Aug 5 00:45:13 2007 @@ -209,15 +209,15 @@ .. note:: The :mod:`math` module consists mostly of thin wrappers around the platform C - math library functions. Behavior in exceptional cases is loosely specified by - the C standards, and Python inherits much of its math-function error-reporting - behavior from the platform C implementation. As a result, the specific - exceptions raised in error cases (and even whether some arguments are considered - to be exceptional at all) are not defined in any useful cross-platform or cross- - release way. For example, whether ``math.log(0)`` returns ``-Inf`` or raises - :exc:`ValueError` or :exc:`OverflowError` isn't defined, and in cases where - ``math.log(0)`` raises :exc:`OverflowError`, ``math.log(0L)`` may raise - :exc:`ValueError` instead. + math library functions. Behavior in exceptional cases is loosely specified + by the C standards, and Python inherits much of its math-function + error-reporting behavior from the platform C implementation. As a result, + the specific exceptions raised in error cases (and even whether some + arguments are considered to be exceptional at all) are not defined in any + useful cross-platform or cross-release way. For example, whether + ``math.log(0)`` returns ``-Inf`` or raises :exc:`ValueError` or + :exc:`OverflowError` isn't defined, and in cases where ``math.log(0)`` raises + :exc:`OverflowError`, ``math.log(0L)`` may raise :exc:`ValueError` instead. .. seealso:: Modified: doctools/trunk/Doc-26/library/mimetypes.rst ============================================================================== --- doctools/trunk/Doc-26/library/mimetypes.rst (original) +++ doctools/trunk/Doc-26/library/mimetypes.rst Sun Aug 5 00:45:13 2007 @@ -39,11 +39,12 @@ Encoding suffixes are case sensitive; type suffixes are first tried case sensitively, then case insensitively. - Optional *strict* is a flag specifying whether the list of known MIME types is - limited to only the official types `registered with IANA `_ are recognized. When *strict* is true - (the default), only the IANA types are supported; when *strict* is false, some - additional non-standard but commonly used MIME types are also recognized. + Optional *strict* is a flag specifying whether the list of known MIME types + is limited to only the official types `registered with IANA + `_ are recognized. + When *strict* is true (the default), only the IANA types are supported; when + *strict* is false, some additional non-standard but commonly used MIME types + are also recognized. .. function:: guess_all_extensions(type[, strict]) Modified: doctools/trunk/Doc-26/library/mimify.rst ============================================================================== --- doctools/trunk/Doc-26/library/mimify.rst (original) +++ doctools/trunk/Doc-26/library/mimify.rst Sun Aug 5 00:45:13 2007 @@ -11,8 +11,8 @@ module. This module is present only to maintain backward compatibility. The :mod:`mimify` module defines two functions to convert mail messages to and -from MIME format. The mail message can be either a simple message or a so- -called multipart message. Each part is treated separately. Mimifying (a part +from MIME format. The mail message can be either a simple message or a +so-called multipart message. Each part is treated separately. Mimifying (a part of) a message entails encoding the message as quoted-printable if it contains any characters that cannot be represented using 7-bit ASCII. Unmimifying (a part of) a message entails undoing the quoted-printable encoding. Mimify and @@ -61,9 +61,9 @@ .. data:: MAXLEN - By default, a part will be encoded as quoted-printable when it contains any non- - ASCII characters (characters with the 8th bit set), or if there are any lines - longer than :const:`MAXLEN` characters (default value 200). + By default, a part will be encoded as quoted-printable when it contains any + non-ASCII characters (characters with the 8th bit set), or if there are any + lines longer than :const:`MAXLEN` characters (default value 200). .. data:: CHARSET Modified: doctools/trunk/Doc-26/library/mmap.rst ============================================================================== --- doctools/trunk/Doc-26/library/mmap.rst (original) +++ doctools/trunk/Doc-26/library/mmap.rst Sun Aug 5 00:45:13 2007 @@ -147,8 +147,8 @@ .. method:: mmap.size() - Return the length of the file, which can be larger than the size of the memory- - mapped area. + Return the length of the file, which can be larger than the size of the + memory-mapped area. .. method:: mmap.tell() Modified: doctools/trunk/Doc-26/library/msilib.rst ============================================================================== --- doctools/trunk/Doc-26/library/msilib.rst (original) +++ doctools/trunk/Doc-26/library/msilib.rst Sun Aug 5 00:45:13 2007 @@ -424,7 +424,7 @@ belongs to, and *name* is the control's name. -.. method:: Control.event(event, argument[, condition = ``1''[, ordering]]) +.. method:: Control.event(event, argument[, condition=1[, ordering]]) Make an entry into the ``ControlEvent`` table for this control. Modified: doctools/trunk/Doc-26/library/multifile.rst ============================================================================== --- doctools/trunk/Doc-26/library/multifile.rst (original) +++ doctools/trunk/Doc-26/library/multifile.rst Sun Aug 5 00:45:13 2007 @@ -33,8 +33,8 @@ It will be useful to know that in :class:`MultiFile`'s view of the world, text is composed of three kinds of lines: data, section-dividers, and end-markers. MultiFile is designed to support parsing of messages that may have multiple -nested message parts, each with its own pattern for section-divider and end- -marker lines. +nested message parts, each with its own pattern for section-divider and +end-marker lines. .. seealso:: @@ -110,9 +110,9 @@ return the empty string to indicate end-of-file, until a call to :meth:`pop` removes the boundary a or :meth:`next` call reenables it. - It is possible to push more than one boundary. Encountering the most-recently- - pushed boundary will return EOF; encountering any other boundary will raise an - error. + It is possible to push more than one boundary. Encountering the + most-recently-pushed boundary will return EOF; encountering any other + boundary will raise an error. .. method:: MultiFile.pop() @@ -122,19 +122,19 @@ .. method:: MultiFile.section_divider(str) - Turn a boundary into a section-divider line. By default, this method prepends - ``'-``\ ``-'`` (which MIME section boundaries have) but it is declared so it can - be overridden in derived classes. This method need not append LF or CR-LF, as - comparison with the result ignores trailing whitespace. + Turn a boundary into a section-divider line. By default, this method + prepends ``'--'`` (which MIME section boundaries have) but it is declared so + it can be overridden in derived classes. This method need not append LF or + CR-LF, as comparison with the result ignores trailing whitespace. .. method:: MultiFile.end_marker(str) Turn a boundary string into an end-marker line. By default, this method - prepends ``'-``\ ``-'`` and appends ``'-``\ ``-'`` (like a MIME-multipart end- - of-message marker) but it is declared so it can be overridden in derived - classes. This method need not append LF or CR-LF, as comparison with the result - ignores trailing whitespace. + prepends ``'--'`` and appends ``'--'`` (like a MIME-multipart end-of-message + marker) but it is declared so it can be overridden in derived classes. This + method need not append LF or CR-LF, as comparison with the result ignores + trailing whitespace. Finally, :class:`MultiFile` instances have two public instance variables: Modified: doctools/trunk/Doc-26/library/netrc.rst ============================================================================== --- doctools/trunk/Doc-26/library/netrc.rst (original) +++ doctools/trunk/Doc-26/library/netrc.rst Sun Aug 5 00:45:13 2007 @@ -70,9 +70,9 @@ .. note:: - Passwords are limited to a subset of the ASCII character set. Versions of this - module prior to 2.3 were extremely limited. Starting with 2.3, all ASCII - punctuation is allowed in passwords. However, note that whitespace and non- - printable characters are not allowed in passwords. This is a limitation of the - way the .netrc file is parsed and may be removed in the future. + Passwords are limited to a subset of the ASCII character set. Versions of + this module prior to 2.3 were extremely limited. Starting with 2.3, all + ASCII punctuation is allowed in passwords. However, note that whitespace and + non-printable characters are not allowed in passwords. This is a limitation + of the way the .netrc file is parsed and may be removed in the future. Modified: doctools/trunk/Doc-26/library/new.rst ============================================================================== --- doctools/trunk/Doc-26/library/new.rst (original) +++ doctools/trunk/Doc-26/library/new.rst Sun Aug 5 00:45:13 2007 @@ -11,8 +11,8 @@ functions. This is for use primarily in marshal-type functions, when a new object needs to be created "magically" and not by using the regular creation functions. This module provides a low-level interface to the interpreter, so -care must be exercised when using this module. It is possible to supply non- -sensical arguments which crash the interpreter when the object is used. +care must be exercised when using this module. It is possible to supply +non-sensical arguments which crash the interpreter when the object is used. The :mod:`new` module defines the following functions: Modified: doctools/trunk/Doc-26/library/nntplib.rst ============================================================================== --- doctools/trunk/Doc-26/library/nntplib.rst (original) +++ doctools/trunk/Doc-26/library/nntplib.rst Sun Aug 5 00:45:13 2007 @@ -53,18 +53,18 @@ .. class:: NNTP(host[, port [, user[, password [, readermode] [, usenetrc]]]]) - Return a new instance of the :class:`NNTP` class, representing a connection to - the NNTP server running on host *host*, listening at port *port*. The default - *port* is 119. If the optional *user* and *password* are provided, or if - suitable credentials are present in :file:`/.netrc` and the optional flag - *usenetrc* is true (the default), the ``AUTHINFO USER`` and ``AUTHINFO PASS`` - commands are used to identify and authenticate the user to the server. If the - optional flag *readermode* is true, then a ``mode reader`` command is sent - before authentication is performed. Reader mode is sometimes necessary if you - are connecting to an NNTP server on the local machine and intend to call reader- - specific commands, such as ``group``. If you get unexpected - :exc:`NNTPPermanentError`\ s, you might need to set *readermode*. *readermode* - defaults to ``None``. *usenetrc* defaults to ``True``. + Return a new instance of the :class:`NNTP` class, representing a connection + to the NNTP server running on host *host*, listening at port *port*. The + default *port* is 119. If the optional *user* and *password* are provided, + or if suitable credentials are present in :file:`/.netrc` and the optional + flag *usenetrc* is true (the default), the ``AUTHINFO USER`` and ``AUTHINFO + PASS`` commands are used to identify and authenticate the user to the server. + If the optional flag *readermode* is true, then a ``mode reader`` command is + sent before authentication is performed. Reader mode is sometimes necessary + if you are connecting to an NNTP server on the local machine and intend to + call reader-specific commands, such as ``group``. If you get unexpected + :exc:`NNTPPermanentError`\ s, you might need to set *readermode*. + *readermode* defaults to ``None``. *usenetrc* defaults to ``True``. .. versionchanged:: 2.4 *usenetrc* argument added. Modified: doctools/trunk/Doc-26/library/optparse.rst ============================================================================== --- doctools/trunk/Doc-26/library/optparse.rst (original) +++ doctools/trunk/Doc-26/library/optparse.rst Sun Aug 5 00:45:13 2007 @@ -117,18 +117,18 @@ Some other option syntaxes that the world has seen include: -* a hyphen followed by a few letters, e.g. ``"-pf"`` (this is *not* the same - as multiple options merged into a single argument) + * a hyphen followed by a few letters, e.g. ``"-pf"`` (this is *not* the same + as multiple options merged into a single argument) -* a hyphen followed by a whole word, e.g. ``"-file"`` (this is technically - equivalent to the previous syntax, but they aren't usually seen in the same - program) + * a hyphen followed by a whole word, e.g. ``"-file"`` (this is technically + equivalent to the previous syntax, but they aren't usually seen in the same + program) -* a plus sign followed by a single letter, or a few letters, or a word, e.g. - ``"+f"``, ``"+rgb"`` + * a plus sign followed by a single letter, or a few letters, or a word, e.g. + ``"+f"``, ``"+rgb"`` -* a slash followed by a letter, or a few letters, or a word, e.g. ``"/f"``, - ``"/file"`` + * a slash followed by a letter, or a few letters, or a word, e.g. ``"/f"``, + ``"/file"`` These option syntaxes are not supported by :mod:`optparse`, and they never will be. This is deliberate: the first three are non-standard on any environment, @@ -470,8 +470,8 @@ :mod:`optparse`'s ability to generate help and usage text automatically is useful for creating user-friendly command-line interfaces. All you have to do is supply a :attr:`help` value for each option, and optionally a short usage -message for your whole program. Here's an OptionParser populated with user- -friendly (documented) options:: +message for your whole program. Here's an OptionParser populated with +user-friendly (documented) options:: usage = "usage: %prog [options] arg1 arg2" parser = OptionParser(usage=usage) @@ -488,9 +488,9 @@ help="interaction mode: novice, intermediate, " "or expert [default: %default]") -If :mod:`optparse` encounters either ``"-h"`` or ``"--help"`` on the command- -line, or if you just call :meth:`parser.print_help`, it prints the following to -standard output:: +If :mod:`optparse` encounters either ``"-h"`` or ``"--help"`` on the +command-line, or if you just call :meth:`parser.print_help`, it prints the +following to standard output:: usage: [options] arg1 arg2 @@ -521,12 +521,12 @@ default: ``"usage: %prog [options]"``, which is fine if your script doesn't take any positional arguments. -* every option defines a help string, and doesn't worry about line- - wrapping---\ :mod:`optparse` takes care of wrapping lines and making the help - output look good. +* every option defines a help string, and doesn't worry about line-wrapping--- + :mod:`optparse` takes care of wrapping lines and making the help output look + good. -* options that take a value indicate this fact in their automatically- - generated help message, e.g. for the "mode" option:: +* options that take a value indicate this fact in their automatically-generated + help message, e.g. for the "mode" option:: -m MODE, --mode=MODE @@ -1663,14 +1663,14 @@ where ``option`` is an :class:`Option` instance, ``opt`` is an option string (e.g., ``"-f"``), and ``value`` is the string from the command line that must be checked and converted to your desired type. ``check_mytype()`` should return an -object of the hypothetical type ``mytype``. The value returned by a type- -checking function will wind up in the OptionValues instance returned by +object of the hypothetical type ``mytype``. The value returned by a +type-checking function will wind up in the OptionValues instance returned by :meth:`OptionParser.parse_args`, or be passed to a callback as the ``value`` parameter. Your type-checking function should raise OptionValueError if it encounters any -problems. OptionValueError takes a single string argument, which is passed as- -is to OptionParser's :meth:`error` method, which in turn prepends the program +problems. OptionValueError takes a single string argument, which is passed +as-is to OptionParser's :meth:`error` method, which in turn prepends the program name and the string ``"error:"`` and prints everything to stderr before terminating the process. Modified: doctools/trunk/Doc-26/library/os.rst ============================================================================== --- doctools/trunk/Doc-26/library/os.rst (original) +++ doctools/trunk/Doc-26/library/os.rst Sun Aug 5 00:45:13 2007 @@ -644,9 +644,9 @@ .. function:: ttyname(fd) - Return a string which specifies the terminal device associated with file- - descriptor *fd*. If *fd* is not associated with a terminal device, an exception - is raised. Availability:Macintosh, Unix. + Return a string which specifies the terminal device associated with + file-descriptor *fd*. If *fd* is not associated with a terminal device, an + exception is raised. Availability:Macintosh, Unix. .. function:: write(fd, str) @@ -676,8 +676,8 @@ O_EXCL O_TRUNC - Options for the *flag* argument to the :func:`open` function. These can be bit- - wise OR'd together. Availability: Macintosh, Unix, Windows. + Options for the *flag* argument to the :func:`open` function. These can be + bit-wise OR'd together. Availability: Macintosh, Unix, Windows. .. data:: O_DSYNC @@ -695,8 +695,8 @@ .. data:: O_BINARY - Option for the *flag* argument to the :func:`open` function. This can be bit- - wise OR'd together with those listed above. Availability: Windows. + Option for the *flag* argument to the :func:`open` function. This can be + bit-wise OR'd together with those listed above. Availability: Windows. .. % XXX need to check on the availability of this one. @@ -708,8 +708,8 @@ O_SEQUENTIAL O_TEXT - Options for the *flag* argument to the :func:`open` function. These can be bit- - wise OR'd together. Availability: Windows. + Options for the *flag* argument to the :func:`open` function. These can be + bit-wise OR'd together. Availability: Windows. .. data:: SEEK_SET @@ -813,25 +813,16 @@ Set the flags of *path* to the numeric *flags*. *flags* may take a combination (bitwise OR) of the following values (as defined in the :mod:`stat` module): -* ``UF_NODUMP`` - -* ``UF_IMMUTABLE`` - -* ``UF_APPEND`` - -* ``UF_OPAQUE`` - -* ``UF_NOUNLINK`` - -* ``SF_ARCHIVED`` - -* ``SF_IMMUTABLE`` - -* ``SF_APPEND`` - -* ``SF_NOUNLINK`` - -* ``SF_SNAPSHOT`` + * ``UF_NODUMP`` + * ``UF_IMMUTABLE`` + * ``UF_APPEND`` + * ``UF_OPAQUE`` + * ``UF_NOUNLINK`` + * ``SF_ARCHIVED`` + * ``SF_IMMUTABLE`` + * ``SF_APPEND`` + * ``SF_NOUNLINK`` + * ``SF_SNAPSHOT`` Availability: Macintosh, Unix. @@ -852,43 +843,26 @@ following values (as defined in the :mod:`stat` module) or bitwise or-ed combinations of them: -* ``stat.S_ISUID`` - -* ``stat.S_ISGID`` - -* ``stat.S_ENFMT`` - -* ``stat.S_ISVTX`` - -* ``stat.S_IREAD`` - -* ``stat.S_IWRITE`` - -* ``stat.S_IEXEC`` - -* ``stat.S_IRWXU`` - -* ``stat.S_IRUSR`` - -* ``stat.S_IWUSR`` - -* ``stat.S_IXUSR`` - -* ``stat.S_IRWXG`` - -* ``stat.S_IRGRP`` - -* ``stat.S_IWGRP`` - -* ``stat.S_IXGRP`` - -* ``stat.S_IRWXO`` - -* ``stat.S_IROTH`` - -* ``stat.S_IWOTH`` -* ``stat.S_IXOTH`` + * ``stat.S_ISUID`` + * ``stat.S_ISGID`` + * ``stat.S_ENFMT`` + * ``stat.S_ISVTX`` + * ``stat.S_IREAD`` + * ``stat.S_IWRITE`` + * ``stat.S_IEXEC`` + * ``stat.S_IRWXU`` + * ``stat.S_IRUSR`` + * ``stat.S_IWUSR`` + * ``stat.S_IXUSR`` + * ``stat.S_IRWXG`` + * ``stat.S_IRGRP`` + * ``stat.S_IWGRP`` + * ``stat.S_IXGRP`` + * ``stat.S_IRWXO`` + * ``stat.S_IROTH`` + * ``stat.S_IWOTH`` + * ``stat.S_IXOTH`` Availability: Macintosh, Unix, Windows. @@ -1317,7 +1291,7 @@ Availability: Macintosh, Unix, Windows. -.. function:: walk(top[, topdown\ ``=True`` [, onerror\ ``=None``[, followlinks\ ``=False``]]]) +.. function:: walk(top[, topdown=True [, onerror=None[, followlinks=False]]]) .. index:: single: directory; walking Modified: doctools/trunk/Doc-26/library/ossaudiodev.rst ============================================================================== --- doctools/trunk/Doc-26/library/ossaudiodev.rst (original) +++ doctools/trunk/Doc-26/library/ossaudiodev.rst Sun Aug 5 00:45:13 2007 @@ -78,11 +78,12 @@ module first looks in the environment variable :envvar:`AUDIODEV` for a device to use. If not found, it falls back to :file:`/dev/dsp`. - *mode* is one of ``'r'`` for read-only (record) access, ``'w'`` for write-only - (playback) access and ``'rw'`` for both. Since many sound cards only allow one - process to have the recorder or player open at a time, it is a good idea to open - the device only for the activity needed. Further, some sound cards are half- - duplex: they can be opened for reading or writing, but not both at once. + *mode* is one of ``'r'`` for read-only (record) access, ``'w'`` for + write-only (playback) access and ``'rw'`` for both. Since many sound cards + only allow one process to have the recorder or player open at a time, it is a + good idea to open the device only for the activity needed. Further, some + sound cards are half-duplex: they can be opened for reading or writing, but + not both at once. Note the unusual calling syntax: the *first* argument is optional, and the second is required. This is a historical artifact for compatibility with the Modified: doctools/trunk/Doc-26/library/othergui.rst ============================================================================== --- doctools/trunk/Doc-26/library/othergui.rst (original) +++ doctools/trunk/Doc-26/library/othergui.rst Sun Aug 5 00:45:13 2007 @@ -61,18 +61,18 @@ Summerfield. `wxPython `_ - wxPython is a cross-platform GUI toolkit for Python that is built around the - popular `wxWidgets `_ (formerly - wxWindows) C++ toolkit. ?It provides a - native look and feel for applications on Windows, Mac OS X, and Unix systems by - using each platform's native widgets where ever possible, (GTK+ on Unix-like - systems). ?In addition to an extensive set of widgets, wxPython provides classes - for online documentation and context sensitive help, printing, HTML viewing, - low-level device context drawing, drag and drop, system clipboard access, an - XML-based resource format and more, including an ever growing library of user- - contributed modules. ?wxPython has a book, - `wxPython in Action `_, - by Noel Rappin and Robin Dunn. + wxPython is a cross-platform GUI toolkit for Python that is built around + the popular `wxWidgets `_ (formerly wxWindows) + C++ toolkit. ?It provides a native look and feel for applications on + Windows, Mac OS X, and Unix systems by using each platform's native + widgets where ever possible, (GTK+ on Unix-like systems). ?In addition to + an extensive set of widgets, wxPython provides classes for online + documentation and context sensitive help, printing, HTML viewing, + low-level device context drawing, drag and drop, system clipboard access, + an XML-based resource format and more, including an ever growing library + of user-contributed modules. ?wxPython has a book, `wxPython in Action + `_, by Noel Rappin and + Robin Dunn. PyGTK, PyQt, and wxPython, all have a modern look and feel and far more widgets and better documentation than Tkinter. In addition, Modified: doctools/trunk/Doc-26/library/parser.rst ============================================================================== --- doctools/trunk/Doc-26/library/parser.rst (original) +++ doctools/trunk/Doc-26/library/parser.rst Sun Aug 5 00:45:13 2007 @@ -189,7 +189,7 @@ information is omitted if the flag is false or omitted. -.. function:: compileast(ast[, filename\ ``= ''``]) +.. function:: compileast(ast[, filename='']) .. index:: builtin: eval Modified: doctools/trunk/Doc-26/library/pickle.rst ============================================================================== --- doctools/trunk/Doc-26/library/pickle.rst (original) +++ doctools/trunk/Doc-26/library/pickle.rst Sun Aug 5 00:45:13 2007 @@ -91,8 +91,8 @@ with the same internal structure. Perhaps the most obvious thing to do with these byte streams is to write them onto a file, but it is also conceivable to send them across a network or store them in a database. The module -:mod:`shelve` provides a simple interface to pickle and unpickle objects on DBM- -style database files. +:mod:`shelve` provides a simple interface to pickle and unpickle objects on +DBM-style database files. Data stream format @@ -689,9 +689,9 @@ output.close() -The following example reads the resulting pickled data. When reading a pickle- -containing file, you should open the file in binary mode because you can't be -sure if the ASCII or binary format was used. :: +The following example reads the resulting pickled data. When reading a +pickle-containing file, you should open the file in binary mode because you +can't be sure if the ASCII or binary format was used. :: import pprint, pickle Modified: doctools/trunk/Doc-26/library/profile.rst ============================================================================== --- doctools/trunk/Doc-26/library/profile.rst (original) +++ doctools/trunk/Doc-26/library/profile.rst Sun Aug 5 00:45:13 2007 @@ -295,13 +295,13 @@ .. function:: run(command[, filename]) - This function takes a single argument that can be passed to the :keyword:`exec` - statement, and an optional file name. In all cases this routine attempts to - :keyword:`exec` its first argument, and gather profiling statistics from the - execution. If no file name is present, then this function automatically prints a - simple profiling report, sorted by the standard name string (file/line/function- - name) that is presented in each line. The following is a typical output from - such a call:: + This function takes a single argument that can be passed to the + :keyword:`exec` statement, and an optional file name. In all cases this + routine attempts to :keyword:`exec` its first argument, and gather profiling + statistics from the execution. If no file name is present, then this function + automatically prints a simple profiling report, sorted by the standard name + string (file/line/function-name) that is presented in each line. The + following is a typical output from such a call:: 2706 function calls (2004 primitive calls) in 4.504 CPU seconds @@ -527,12 +527,12 @@ argument is also identical. Each caller is reported on its own line. The format differs slightly depending on the profiler that produced the stats: -* With :mod:`profile`, a number is shown in parentheses after each caller to - show how many times this specific call was made. For convenience, a second non- - parenthesized number repeats the cumulative time spent in the function at the - right. + * With :mod:`profile`, a number is shown in parentheses after each caller to + show how many times this specific call was made. For convenience, a second + non-parenthesized number repeats the cumulative time spent in the function + at the right. -* With :mod:`cProfile`, each caller is preceeded by three numbers: the number of + * With :mod:`cProfile`, each caller is preceeded by three numbers: the number of times this specific call was made, and the total and cumulative times spent in the current function while it was invoked by this specific caller. Modified: doctools/trunk/Doc-26/library/pyexpat.rst ============================================================================== --- doctools/trunk/Doc-26/library/pyexpat.rst (original) +++ doctools/trunk/Doc-26/library/pyexpat.rst Sun Aug 5 00:45:13 2007 @@ -20,8 +20,8 @@ .. index:: single: Expat -The :mod:`xml.parsers.expat` module is a Python interface to the Expat non- -validating XML parser. The module provides a single extension type, +The :mod:`xml.parsers.expat` module is a Python interface to the Expat +non-validating XML parser. The module provides a single extension type, :class:`xmlparser`, that represents the current state of an XML parser. After an :class:`xmlparser` object has been created, various attributes of the object can be set to handler functions. When an XML document is then fed to the Modified: doctools/trunk/Doc-26/library/random.rst ============================================================================== --- doctools/trunk/Doc-26/library/random.rst (original) +++ doctools/trunk/Doc-26/library/random.rst Sun Aug 5 00:45:13 2007 @@ -10,8 +10,8 @@ distributions. For integers, uniform selection from a range. For sequences, uniform selection -of a random element, a function to generate a random permutation of a list in- -place, and a function for random sampling without replacement. +of a random element, a function to generate a random permutation of a list +in-place, and a function for random sampling without replacement. On the real line, there are functions to compute uniform, normal (Gaussian), lognormal, negative exponential, gamma, and beta distributions. For generating Modified: doctools/trunk/Doc-26/library/re.rst ============================================================================== --- doctools/trunk/Doc-26/library/re.rst (original) +++ doctools/trunk/Doc-26/library/re.rst Sun Aug 5 00:45:13 2007 @@ -134,10 +134,10 @@ ``{m,n}?`` Causes the resulting RE to match from *m* to *n* repetitions of the preceding - RE, attempting to match as *few* repetitions as possible. This is the non- - greedy version of the previous qualifier. For example, on the 6-character - string ``'aaaaaa'``, ``a{3,5}`` will match 5 ``'a'`` characters, while - ``a{3,5}?`` will only match 3 characters. + RE, attempting to match as *few* repetitions as possible. This is the + non-greedy version of the previous qualifier. For example, on the + 6-character string ``'aaaaaa'``, ``a{3,5}`` will match 5 ``'a'`` characters, + while ``a{3,5}?`` will only match 3 characters. ``'\'`` Either escapes special characters (permitting you to match characters like @@ -519,7 +519,7 @@ If you want to locate a match anywhere in *string*, use :meth:`search` instead. -.. function:: split(pattern, string[, maxsplit\ ``= 0``]) +.. function:: split(pattern, string[, maxsplit=0]) Split *string* by the occurrences of *pattern*. If capturing parentheses are used in *pattern*, then the text of all groups in the pattern are also returned @@ -673,7 +673,7 @@ :meth:`match` method. -.. method:: RegexObject.split(string[, maxsplit\ ``= 0``]) +.. method:: RegexObject.split(string[, maxsplit=0]) Identical to the :func:`split` function, using the compiled pattern. @@ -688,12 +688,12 @@ Identical to the :func:`finditer` function, using the compiled pattern. -.. method:: RegexObject.sub(repl, string[, count\ ``= 0``]) +.. method:: RegexObject.sub(repl, string[, count=0]) Identical to the :func:`sub` function, using the compiled pattern. -.. method:: RegexObject.subn(repl, string[, count\ ``= 0``]) +.. method:: RegexObject.subn(repl, string[, count=0]) Identical to the :func:`subn` function, using the compiled pattern. Modified: doctools/trunk/Doc-26/library/repr.rst ============================================================================== --- doctools/trunk/Doc-26/library/repr.rst (original) +++ doctools/trunk/Doc-26/library/repr.rst Sun Aug 5 00:45:13 2007 @@ -65,8 +65,6 @@ .. versionadded:: 2.4 :attr:`maxset`, :attr:`maxfrozenset`, and :attr:`set`. - . - .. attribute:: Repr.maxlong Modified: doctools/trunk/Doc-26/library/rfc822.rst ============================================================================== --- doctools/trunk/Doc-26/library/rfc822.rst (original) +++ doctools/trunk/Doc-26/library/rfc822.rst Sun Aug 5 00:45:13 2007 @@ -256,9 +256,9 @@ :class:`Message` instances also support a limited mapping interface. In particular: ``m[name]`` is like ``m.getheader(name)`` but raises :exc:`KeyError` -if there is no matching header; and ``len(m)``, ``m.get(name[, *default*])``, +if there is no matching header; and ``len(m)``, ``m.get(name[, default])``, ``m.has_key(name)``, ``m.keys()``, ``m.values()`` ``m.items()``, and -``m.setdefault(name[, *default*])`` act as expected, with the one difference +``m.setdefault(name[, default])`` act as expected, with the one difference that :meth:`setdefault` uses an empty string as the default value. :class:`Message` instances also support the mapping writable interface ``m[name] = value`` and ``del m[name]``. :class:`Message` objects do not support the Modified: doctools/trunk/Doc-26/library/select.rst ============================================================================== --- doctools/trunk/Doc-26/library/select.rst (original) +++ doctools/trunk/Doc-26/library/select.rst Sun Aug 5 00:45:13 2007 @@ -33,16 +33,16 @@ .. function:: select(iwtd, owtd, ewtd[, timeout]) This is a straightforward interface to the Unix :cfunc:`select` system call. - The first three arguments are sequences of 'waitable objects': either integers - representing file descriptors or objects with a parameterless method named - :meth:`fileno` returning such an integer. The three sequences of waitable - objects are for input, output and 'exceptional conditions', respectively. Empty - sequences are allowed, but acceptance of three empty sequences is platform- - dependent. (It is known to work on Unix but not on Windows.) The optional - *timeout* argument specifies a time-out as a floating point number in seconds. - When the *timeout* argument is omitted the function blocks until at least one - file descriptor is ready. A time-out value of zero specifies a poll and never - blocks. + The first three arguments are sequences of 'waitable objects': either + integers representing file descriptors or objects with a parameterless method + named :meth:`fileno` returning such an integer. The three sequences of + waitable objects are for input, output and 'exceptional conditions', + respectively. Empty sequences are allowed, but acceptance of three empty + sequences is platform-dependent. (It is known to work on Unix but not on + Windows.) The optional *timeout* argument specifies a time-out as a floating + point number in seconds. When the *timeout* argument is omitted the function + blocks until at least one file descriptor is ready. A time-out value of zero + specifies a poll and never blocks. The return value is a triple of lists of objects that are ready: subsets of the first three arguments. When the time-out is reached without a file descriptor Modified: doctools/trunk/Doc-26/library/sgmllib.rst ============================================================================== --- doctools/trunk/Doc-26/library/sgmllib.rst (original) +++ doctools/trunk/Doc-26/library/sgmllib.rst Sun Aug 5 00:45:13 2007 @@ -21,14 +21,14 @@ The :class:`SGMLParser` class is instantiated without arguments. The parser is hardcoded to recognize the following constructs: -* Opening and closing tags of the form ```` and + * Opening and closing tags of the form ```` and ````, respectively. -* Numeric character references of the form ``&#name;``. + * Numeric character references of the form ``&#name;``. -* Entity references of the form ``&name;``. + * Entity references of the form ``&name;``. -* SGML comments of the form ````. Note that spaces, tabs, and + * SGML comments of the form ````. Note that spaces, tabs, and newlines are allowed between the trailing ``>`` and the immediately preceding ``--``. Modified: doctools/trunk/Doc-26/library/shelve.rst ============================================================================== --- doctools/trunk/Doc-26/library/shelve.rst (original) +++ doctools/trunk/Doc-26/library/shelve.rst Sun Aug 5 00:45:13 2007 @@ -15,7 +15,7 @@ lots of shared sub-objects. The keys are ordinary strings. -.. function:: open(filename[,flag='c'[,protocol=``None``[,writeback=``False``]]]) +.. function:: open(filename[, flag='c'[, protocol=None[, writeback=False]]]) Open a persistent dictionary. The filename specified is the base filename for the underlying database. As a side-effect, an extension may be added to the Modified: doctools/trunk/Doc-26/library/shlex.rst ============================================================================== --- doctools/trunk/Doc-26/library/shlex.rst (original) +++ doctools/trunk/Doc-26/library/shlex.rst Sun Aug 5 00:45:13 2007 @@ -29,8 +29,8 @@ Split the string *s* using shell-like syntax. If *comments* is :const:`False` (the default), the parsing of comments in the given string will be disabled (setting the :attr:`commenters` member of the :class:`shlex` instance to the - empty string). This function operates in POSIX mode by default, but uses non- - POSIX mode if the *posix* argument is false. + empty string). This function operates in POSIX mode by default, but uses + non-POSIX mode if the *posix* argument is false. .. versionadded:: 2.3 @@ -292,7 +292,7 @@ next character that follows; * Enclosing characters in quotes which are not part of :attr:`escapedquotes` - (e.g. ``'''``) preserve the literal value of all characters within the quotes; + (e.g. ``"'"``) preserve the literal value of all characters within the quotes; * Enclosing characters in quotes which are part of :attr:`escapedquotes` (e.g. ``'"'``) preserves the literal value of all characters within the quotes, with Modified: doctools/trunk/Doc-26/library/simplehttpserver.rst ============================================================================== --- doctools/trunk/Doc-26/library/simplehttpserver.rst (original) +++ doctools/trunk/Doc-26/library/simplehttpserver.rst Sun Aug 5 00:45:13 2007 @@ -7,9 +7,9 @@ .. sectionauthor:: Moshe Zadka -The :mod:`SimpleHTTPServer` module defines a request-handler class, interface- -compatible with :class:`BaseHTTPServer.BaseHTTPRequestHandler`, that serves -files only from a base directory. +The :mod:`SimpleHTTPServer` module defines a request-handler class, +interface-compatible with :class:`BaseHTTPServer.BaseHTTPRequestHandler`, that +serves files only from a base directory. The :mod:`SimpleHTTPServer` module defines the following class: Modified: doctools/trunk/Doc-26/library/simplexmlrpcserver.rst ============================================================================== --- doctools/trunk/Doc-26/library/simplexmlrpcserver.rst (original) +++ doctools/trunk/Doc-26/library/simplexmlrpcserver.rst Sun Aug 5 00:45:13 2007 @@ -10,8 +10,8 @@ .. versionadded:: 2.2 -The :mod:`SimpleXMLRPCServer` module provides a basic server framework for XML- -RPC servers written in Python. Servers can either be free standing, using +The :mod:`SimpleXMLRPCServer` module provides a basic server framework for +XML-RPC servers written in Python. Servers can either be free standing, using :class:`SimpleXMLRPCServer`, or embedded in a CGI environment, using :class:`CGIXMLRPCRequestHandler`. Modified: doctools/trunk/Doc-26/library/site.rst ============================================================================== --- doctools/trunk/Doc-26/library/site.rst (original) +++ doctools/trunk/Doc-26/library/site.rst Sun Aug 5 00:45:13 2007 @@ -42,10 +42,10 @@ triple: path; configuration; file For example, suppose ``sys.prefix`` and ``sys.exec_prefix`` are set to -:file:`/usr/local`. The Python |release| library is then installed in -:file:`/usr/local/lib/python|version|` (where only the first three characters of +:file:`/usr/local`. The Python X.Y library is then installed in +:file:`/usr/local/lib/python{X.Y}` (where only the first three characters of ``sys.version`` are used to form the installation path name). Suppose this has -a subdirectory :file:`/usr/local/lib/python|version|/site-packages` with three +a subdirectory :file:`/usr/local/lib/python{X.Y}/site-packages` with three subsubdirectories, :file:`foo`, :file:`bar` and :file:`spam`, and two path configuration files, :file:`foo.pth` and :file:`bar.pth`. Assume :file:`foo.pth` contains the following:: Modified: doctools/trunk/Doc-26/library/socket.rst ============================================================================== --- doctools/trunk/Doc-26/library/socket.rst (original) +++ doctools/trunk/Doc-26/library/socket.rst Sun Aug 5 00:45:13 2007 @@ -686,11 +686,11 @@ Some notes on socket blocking and timeouts: A socket object can be in one of three modes: blocking, non-blocking, or timeout. Sockets are always created in -blocking mode. In blocking mode, operations block until complete. In non- -blocking mode, operations fail (with an error that is unfortunately system- -dependent) if they cannot be completed immediately. In timeout mode, operations -fail if they cannot be completed within the timeout specified for the socket. -The :meth:`setblocking` method is simply a shorthand for certain +blocking mode. In blocking mode, operations block until complete. In +non-blocking mode, operations fail (with an error that is unfortunately +system-dependent) if they cannot be completed immediately. In timeout mode, +operations fail if they cannot be completed within the timeout specified for the +socket. The :meth:`setblocking` method is simply a shorthand for certain :meth:`settimeout` calls. Timeout mode internally sets the socket in non-blocking mode. The blocking and Modified: doctools/trunk/Doc-26/library/socketserver.rst ============================================================================== --- doctools/trunk/Doc-26/library/socketserver.rst (original) +++ doctools/trunk/Doc-26/library/socketserver.rst Sun Aug 5 00:45:13 2007 @@ -13,8 +13,9 @@ server. :class:`UDPServer` uses datagrams, which are discrete packets of information that may arrive out of order or be lost while in transit. The more infrequently used :class:`UnixStreamServer` and :class:`UnixDatagramServer` -classes are similar, but use Unix domain sockets; they're not available on non- -Unix platforms. For more details on network programming, consult a book such as +classes are similar, but use Unix domain sockets; they're not available on +non-Unix platforms. For more details on network programming, consult a book +such as W. Richard Steven's UNIX Network Programming or Ralph Davis's Win32 Network Programming. Modified: doctools/trunk/Doc-26/library/sqlite3.rst ============================================================================== --- doctools/trunk/Doc-26/library/sqlite3.rst (original) +++ doctools/trunk/Doc-26/library/sqlite3.rst Sun Aug 5 00:45:13 2007 @@ -324,9 +324,9 @@ The first argument to the callback signifies what kind of operation is to be authorized. The second and third argument will be arguments or :const:`None` depending on the first argument. The 4th argument is the name of the database - ("main", "temp", etc.) if applicable. The 5th argument is the name of the inner- - most trigger or view that is responsible for the access attempt or :const:`None` - if this access attempt is directly from input SQL code. + ("main", "temp", etc.) if applicable. The 5th argument is the name of the + inner-most trigger or view that is responsible for the access attempt or + :const:`None` if this access attempt is directly from input SQL code. Please consult the SQLite documentation about the possible values for the first argument and the meaning of the second and third argument depending on the first @@ -344,12 +344,12 @@ .. literalinclude:: ../includes/sqlite3/row_factory.py - If returning a tuple doesn't suffice and you want name-based access to columns, - you should consider setting :attr:`row_factory` to the highly-optimized - :class:`sqlite3.Row` type. :class:`Row` provides both index-based and case- - insensitive name-based access to columns with almost no memory overhead. It will - probably be better than your own custom dictionary-based approach or even a - db_row based solution. + If returning a tuple doesn't suffice and you want name-based access to + columns, you should consider setting :attr:`row_factory` to the + highly-optimized :class:`sqlite3.Row` type. :class:`Row` provides both + index-based and case-insensitive name-based access to columns with almost no + memory overhead. It will probably be better than your own custom + dictionary-based approach or even a db_row based solution. .. % XXX what's a db_row-based solution? Modified: doctools/trunk/Doc-26/library/stdtypes.rst ============================================================================== --- doctools/trunk/Doc-26/library/stdtypes.rst (original) +++ doctools/trunk/Doc-26/library/stdtypes.rst Sun Aug 5 00:45:13 2007 @@ -439,12 +439,13 @@ .. method:: container.__iter__() Return an iterator object. The object is required to support the iterator - protocol described below. If a container supports different types of iteration, - additional methods can be provided to specifically request iterators for those - iteration types. (An example of an object supporting multiple forms of - iteration would be a tree structure which supports both breadth-first and depth- - first traversal.) This method corresponds to the :attr:`tp_iter` slot of the - type structure for Python objects in the Python/C API. + protocol described below. If a container supports different types of + iteration, additional methods can be provided to specifically request + iterators for those iteration types. (An example of an object supporting + multiple forms of iteration would be a tree structure which supports both + breadth-first and depth-first traversal.) This method corresponds to the + :attr:`tp_iter` slot of the type structure for Python objects in the Python/C + API. The iterator objects themselves are required to support the following two methods, which together form the :dfn:`iterator protocol`: @@ -1184,9 +1185,9 @@ Notes: (1) - The alternate form causes a leading zero (``'0'``) to be inserted between left- - hand padding and the formatting of the number if the leading character of the - result is not already a zero. + The alternate form causes a leading zero (``'0'``) to be inserted between + left-hand padding and the formatting of the number if the leading character + of the result is not already a zero. (2) The alternate form causes a leading ``'0x'`` or ``'0X'`` (depending on whether @@ -1294,13 +1295,13 @@ | ``s.count(x)`` | return number of *i*'s for | | | | which ``s[i] == x`` | | +------------------------------+--------------------------------+---------------------+ -| ``s.index(x[, *i*[, *j*]])`` | return smallest *k* such that | \(4) | +| ``s.index(x[, i[, j]])`` | return smallest *k* such that | \(4) | | | ``s[k] == x`` and ``i <= k < | | | | j`` | | +------------------------------+--------------------------------+---------------------+ | ``s.insert(i, x)`` | same as ``s[i:i] = [x]`` | \(5) | +------------------------------+--------------------------------+---------------------+ -| ``s.pop([*i*])`` | same as ``x = s[i]; del s[i]; | \(6) | +| ``s.pop([i])`` | same as ``x = s[i]; del s[i]; | \(6) | | | return x`` | | +------------------------------+--------------------------------+---------------------+ | ``s.remove(x)`` | same as ``del s[s.index(x)]`` | \(4) | @@ -1308,8 +1309,8 @@ | ``s.reverse()`` | reverses the items of *s* in | \(7) | | | place | | +------------------------------+--------------------------------+---------------------+ -| ``s.sort([*cmp*[, *key*[, | sort the items of *s* in place | (7), (8), (9), (10) | -| *reverse*]]])`` | | | +| ``s.sort([cmp[, key[, | sort the items of *s* in place | (7), (8), (9), (10) | +| reverse]]])`` | | | +------------------------------+--------------------------------+---------------------+ .. index:: @@ -1630,23 +1631,23 @@ +--------------------------------+---------------------------------+-----------+ | ``a.keys()`` | a copy of *a*'s list of keys | \(3) | +--------------------------------+---------------------------------+-----------+ -| ``a.update([*b*])`` | updates *a* with key/value | \(9) | +| ``a.update([b])`` | updates *a* with key/value | \(9) | | | pairs from *b*, overwriting | | | | existing keys, returns ``None`` | | +--------------------------------+---------------------------------+-----------+ -| ``a.fromkeys(seq[, *value*])`` | Creates a new dictionary with | \(7) | +| ``a.fromkeys(seq[, value])`` | Creates a new dictionary with | \(7) | | | keys from *seq* and values set | | | | to *value* | | +--------------------------------+---------------------------------+-----------+ | ``a.values()`` | a copy of *a*'s list of values | \(3) | +--------------------------------+---------------------------------+-----------+ -| ``a.get(k[, *x*])`` | ``a[k]`` if ``k in a``, else | \(4) | +| ``a.get(k[, x])`` | ``a[k]`` if ``k in a``, else | \(4) | | | *x* | | +--------------------------------+---------------------------------+-----------+ -| ``a.setdefault(k[, *x*])`` | ``a[k]`` if ``k in a``, else | \(5) | +| ``a.setdefault(k[, x])`` | ``a[k]`` if ``k in a``, else | \(5) | | | *x* (also setting it) | | +--------------------------------+---------------------------------+-----------+ -| ``a.pop(k[, *x*])`` | ``a[k]`` if ``k in a``, else | \(8) | +| ``a.pop(k[, x])`` | ``a[k]`` if ``k in a``, else | \(8) | | | *x* (and remove k) | | +--------------------------------+---------------------------------+-----------+ | ``a.popitem()`` | remove and return an arbitrary | \(6) | @@ -1721,13 +1722,13 @@ (10) If a subclass of dict defines a method :meth:`__missing__`, if the key *k* is - not present, the *a*[*k*] operation calls that method with the key *k* as - argument. The *a*[*k*] operation then returns or raises whatever is returned or - raised by the :func:`__missing__`\ (*k*) call if the key is not present. No - other operations or methods invoke :meth:`__missing__`\ (). If - :meth:`__missing__` is not defined, :exc:`KeyError` is raised. - :meth:`__missing__` must be a method; it cannot be an instance variable. For an - example, see :mod:`collections`.\ :class:`defaultdict`. + not present, the ``a[k]`` operation calls that method with the key *k* as + argument. The ``a[k]`` operation then returns or raises whatever is returned + or raised by the ``__missing__(k)`` call if the key is not present. No other + operations or methods invoke :meth:`__missing__`. If :meth:`__missing__` is + not defined, :exc:`KeyError` is raised. :meth:`__missing__` must be a + method; it cannot be an instance variable. For an example, see + :class:`collections.defaultdict`. .. versionadded:: 2.5 @@ -1793,8 +1794,8 @@ .. method:: file.flush() - Flush the internal buffer, like ``stdio``'s :cfunc:`fflush`. This may be a no- - op on some file-like objects. + Flush the internal buffer, like ``stdio``'s :cfunc:`fflush`. This may be a + no-op on some file-like objects. .. method:: file.fileno() @@ -1873,11 +1874,11 @@ .. method:: file.readlines([sizehint]) Read until EOF using :meth:`readline` and return a list containing the lines - thus read. If the optional *sizehint* argument is present, instead of reading - up to EOF, whole lines totalling approximately *sizehint* bytes (possibly after - rounding up to an internal buffer size) are read. Objects implementing a file- - like interface may choose to ignore *sizehint* if it cannot be implemented, or - cannot be implemented efficiently. + thus read. If the optional *sizehint* argument is present, instead of + reading up to EOF, whole lines totalling approximately *sizehint* bytes + (possibly after rounding up to an internal buffer size) are read. Objects + implementing a file-like interface may choose to ignore *sizehint* if it + cannot be implemented, or cannot be implemented efficiently. .. method:: file.xreadlines() @@ -1906,9 +1907,8 @@ Note that not all file objects are seekable. - .. versionchanged:: Passing float values as offset has been deprecated - - [2.6] + .. versionchanged:: 2.6 + Passing float values as offset has been deprecated .. method:: file.tell() @@ -1986,9 +1986,9 @@ .. attribute:: file.name If the file object was created using :func:`open`, the name of the file. - Otherwise, some string that indicates the source of the file object, of the form - ``<...>``. This is a read-only attribute and may not be present on all file- - like objects. + Otherwise, some string that indicates the source of the file object, of the + form ``<...>``. This is a read-only attribute and may not be present on all + file-like objects. .. attribute:: file.newlines @@ -2041,7 +2041,7 @@ to be provided for a context manager object to define a runtime context: -.. method:: context manager.__enter__() +.. method:: contextmanager.__enter__() Enter the runtime context and return either this object or another object related to the runtime context. The value returned by this method is bound to @@ -2060,7 +2060,7 @@ :keyword:`with` statement. -.. method:: context manager.__exit__(exc_type, exc_val, exc_tb) +.. method:: contextmanager.__exit__(exc_type, exc_val, exc_tb) Exit the runtime context and return a Boolean flag indicating if any expection that occurred should be suppressed. If an exception occurred while executing the @@ -2129,7 +2129,7 @@ Modules built into the interpreter are written like this: ````. If loaded from a file, they are written as ````. +'/usr/local/lib/pythonX.Y/os.pyc'>``. .. _typesobjects: @@ -2150,9 +2150,9 @@ Function objects are created by function definitions. The only operation on a function object is to call it: ``func(argument-list)``. -There are really two flavors of function objects: built-in functions and user- -defined functions. Both support the same operation (to call the function), but -the implementation is different, hence the different object types. +There are really two flavors of function objects: built-in functions and +user-defined functions. Both support the same operation (to call the function), +but the implementation is different, hence the different object types. See :ref:`function` for more information. Modified: doctools/trunk/Doc-26/library/string.rst ============================================================================== --- doctools/trunk/Doc-26/library/string.rst (original) +++ doctools/trunk/Doc-26/library/string.rst Sun Aug 5 00:45:13 2007 @@ -109,13 +109,13 @@ * ``$$`` is an escape; it is replaced with a single ``$``. * ``$identifier`` names a substitution placeholder matching a mapping key of - "identifier". By default, "identifier" must spell a Python identifier. The - first non-identifier character after the ``$`` character terminates this - placeholder specification. + ``"identifier"``. By default, ``"identifier"`` must spell a Python + identifier. The first non-identifier character after the ``$`` character + terminates this placeholder specification. * ``${identifier}`` is equivalent to ``$identifier``. It is required when valid identifier characters follow the placeholder but are not part of the - placeholder, such as "${noun}ification". + placeholder, such as ``"${noun}ification"``. Any other appearance of ``$`` in the string will result in a :exc:`ValueError` being raised. @@ -190,9 +190,10 @@ expression, as the implementation will call :meth:`re.escape` on this string as needed. -* *idpattern* -- This is the regular expression describing the pattern for non- - braced placeholders (the braces will be added automatically as appropriate). - The default value is the regular expression ``[_a-z][_a-z0-9]*``. +* *idpattern* -- This is the regular expression describing the pattern for + non-braced placeholders (the braces will be added automatically as + appropriate). The default value is the regular expression + ``[_a-z][_a-z0-9]*``. Alternatively, you can provide the entire regular expression pattern by overriding the class attribute *pattern*. If you do this, the value must be a Modified: doctools/trunk/Doc-26/library/stringprep.rst ============================================================================== --- doctools/trunk/Doc-26/library/stringprep.rst (original) +++ doctools/trunk/Doc-26/library/stringprep.rst Sun Aug 5 00:45:13 2007 @@ -50,14 +50,14 @@ .. function:: map_table_b2(code) - Return the mapped value for *code* according to tableB.2 (Mapping for case- - folding used with NFKC). + Return the mapped value for *code* according to tableB.2 (Mapping for + case-folding used with NFKC). .. function:: map_table_b3(code) - Return the mapped value for *code* according to tableB.3 (Mapping for case- - folding used with no normalization). + Return the mapped value for *code* according to tableB.3 (Mapping for + case-folding used with no normalization). .. function:: in_table_c11(code) Modified: doctools/trunk/Doc-26/library/struct.rst ============================================================================== --- doctools/trunk/Doc-26/library/struct.rst (original) +++ doctools/trunk/Doc-26/library/struct.rst Sun Aug 5 00:45:13 2007 @@ -48,7 +48,7 @@ (``len(string)`` must equal ``calcsize(fmt)``). -.. function:: unpack_from(fmt, buffer[,offset ``= 0``]) +.. function:: unpack_from(fmt, buffer[,offset=0]) Unpack the *buffer* according to tthe given format. The result is a tuple even if it contains exactly one item. The *buffer* must contain at least the amount @@ -280,7 +280,7 @@ (``len(string)`` must equal :attr:`self.size`). -.. method:: Struct.unpack_from(buffer[,offset ``= 0``]) +.. method:: Struct.unpack_from(buffer[, offset=0]) Identical to the :func:`unpack_from` function, using the compiled format. (``len(buffer[offset:])`` must be at least :attr:`self.size`). Modified: doctools/trunk/Doc-26/library/sys.rst ============================================================================== --- doctools/trunk/Doc-26/library/sys.rst (original) +++ doctools/trunk/Doc-26/library/sys.rst Sun Aug 5 00:45:13 2007 @@ -23,8 +23,8 @@ .. data:: byteorder An indicator of the native byte order. This will have the value ``'big'`` on - big-endian (most-significant byte first) platforms, and ``'little'`` on little- - endian (least-significant byte first) platforms. + big-endian (most-significant byte first) platforms, and ``'little'`` on + little-endian (least-significant byte first) platforms. .. versionadded:: 2.0 @@ -267,14 +267,14 @@ file names, or ``None`` if the system default encoding is used. The result value depends on the operating system: -* On Windows 9x, the encoding is "mbcs". + * On Windows 9x, the encoding is "mbcs". -* On Mac OS X, the encoding is "utf-8". + * On Mac OS X, the encoding is "utf-8". -* On Unix, the encoding is the user's preference according to the result of + * On Unix, the encoding is the user's preference according to the result of nl_langinfo(CODESET), or :const:`None` if the ``nl_langinfo(CODESET)`` failed. -* On Windows NT+, file names are Unicode natively, so no conversion is + * On Windows NT+, file names are Unicode natively, so no conversion is performed. :func:`getfilesystemencoding` still returns ``'mbcs'``, as this is the encoding that applications should use when they explicitly want to convert Unicode strings to byte strings that are equivalent when used as file names. @@ -369,8 +369,9 @@ more information.) The meaning of the variables is the same as that of the return values from - :func:`exc_info` above. (Since there is only one interactive thread, thread- - safety is not a concern for these variables, unlike for ``exc_type`` etc.) + :func:`exc_info` above. (Since there is only one interactive thread, + thread-safety is not a concern for these variables, unlike for ``exc_type`` + etc.) .. data:: maxint Modified: doctools/trunk/Doc-26/library/tempfile.rst ============================================================================== --- doctools/trunk/Doc-26/library/tempfile.rst (original) +++ doctools/trunk/Doc-26/library/tempfile.rst Sun Aug 5 00:45:13 2007 @@ -32,7 +32,7 @@ The module defines the following user-callable functions: -.. function:: TemporaryFile([mode=``'w+b'``[, bufsize=``-1``[, suffix[, prefix[, dir]]]]]) +.. function:: TemporaryFile([mode='w+b'[, bufsize=-1[, suffix[, prefix[, dir]]]]]) Return a file (or file-like) object that can be used as a temporary storage area. The file is created using :func:`mkstemp`. It will be destroyed as soon @@ -50,7 +50,7 @@ The *dir*, *prefix* and *suffix* parameters are passed to :func:`mkstemp`. -.. function:: NamedTemporaryFile([mode=``'w+b'``[, bufsize=``-1``[, suffix[, prefix[, dir[, delete]]]]]]) +.. function:: NamedTemporaryFile([mode='w+b'[, bufsize=-1[, suffix[, prefix[, dir[, delete]]]]]]) This function operates exactly as :func:`TemporaryFile` does, except that the file is guaranteed to have a visible name in the file system (on Unix, the @@ -66,7 +66,7 @@ The *delete* parameter. -.. function:: SpooledTemporaryFile([max_size=``0``, [mode=``'w+b'``[, bufsize=``-1``[, suffix[, prefix[, dir]]]]]]) +.. function:: SpooledTemporaryFile([max_size=0, [mode='w+b'[, bufsize=-1[, suffix[, prefix[, dir]]]]]]) This function operates exactly as :func:`TemporaryFile` does, except that data is spooled in memory until the file size exceeds *max_size*, or until the file's @@ -98,13 +98,13 @@ If *prefix* is specified, the file name will begin with that prefix; otherwise, a default prefix is used. - If *dir* is specified, the file will be created in that directory; otherwise, a - default directory is used. The default directory is chosen from a platform- - dependent list, but the user of the application can control the directory - location by setting the *TMPDIR*, *TEMP* or *TMP* environment variables. There - is thus no guarantee that the generated filename will have any nice properties, - such as not requiring quoting when passed to external commands via - ``os.popen()``. + If *dir* is specified, the file will be created in that directory; otherwise, + a default directory is used. The default directory is chosen from a + platform-dependent list, but the user of the application can control the + directory location by setting the *TMPDIR*, *TEMP* or *TMP* environment + variables. There is thus no guarantee that the generated filename will have + any nice properties, such as not requiring quoting when passed to external + commands via ``os.popen()``. If *text* is specified, it indicates whether to open the file in binary mode (the default) or text mode. On some platforms, this makes no difference. @@ -162,24 +162,24 @@ Python searches a standard list of directories and sets *tempdir* to the first one which the calling user can create files in. The list is: -#. The directory named by the :envvar:`TMPDIR` environment variable. + #. The directory named by the :envvar:`TMPDIR` environment variable. -#. The directory named by the :envvar:`TEMP` environment variable. + #. The directory named by the :envvar:`TEMP` environment variable. -#. The directory named by the :envvar:`TMP` environment variable. + #. The directory named by the :envvar:`TMP` environment variable. -#. A platform-specific location: + #. A platform-specific location: -* On RiscOS, the directory named by the :envvar:`Wimp$ScrapDir` environment + * On RiscOS, the directory named by the :envvar:`Wimp$ScrapDir` environment variable. -* On Windows, the directories :file:`C:$\\TEMP`, :file:`C:$\\TMP`, + * On Windows, the directories :file:`C:$\\TEMP`, :file:`C:$\\TMP`, :file:`\\TEMP`, and :file:`\\TMP`, in that order. -* On all other platforms, the directories :file:`/tmp`, :file:`/var/tmp`, and + * On all other platforms, the directories :file:`/tmp`, :file:`/var/tmp`, and :file:`/usr/tmp`, in that order. -#. As a last resort, the current working directory. + #. As a last resort, the current working directory. .. function:: gettempdir() Modified: doctools/trunk/Doc-26/library/termios.rst ============================================================================== --- doctools/trunk/Doc-26/library/termios.rst (original) +++ doctools/trunk/Doc-26/library/termios.rst Sun Aug 5 00:45:13 2007 @@ -31,12 +31,12 @@ .. function:: tcgetattr(fd) Return a list containing the tty attributes for file descriptor *fd*, as - follows: ``[``*iflag*, *oflag*, *cflag*, *lflag*, *ispeed*, *ospeed*, *cc*``]`` - where *cc* is a list of the tty special characters (each a string of length 1, - except the items with indices :const:`VMIN` and :const:`VTIME`, which are - integers when these fields are defined). The interpretation of the flags and - the speeds as well as the indexing in the *cc* array must be done using the - symbolic constants defined in the :mod:`termios` module. + follows: ``[iflag, oflag, cflag, lflag, ispeed, ospeed, cc]`` where *cc* is a + list of the tty special characters (each a string of length 1, except the + items with indices :const:`VMIN` and :const:`VTIME`, which are integers when + these fields are defined). The interpretation of the flags and the speeds as + well as the indexing in the *cc* array must be done using the symbolic + constants defined in the :mod:`termios` module. .. function:: tcsetattr(fd, when, attributes) Modified: doctools/trunk/Doc-26/library/textwrap.rst ============================================================================== --- doctools/trunk/Doc-26/library/textwrap.rst (original) +++ doctools/trunk/Doc-26/library/textwrap.rst Sun Aug 5 00:45:13 2007 @@ -147,7 +147,7 @@ This is generally desired for text in a monospaced font. However, the sentence detection algorithm is imperfect: it assumes that a sentence ending consists of a lowercase letter followed by one of ``'.'``, ``'!'``, or ``'?'``, possibly - followed by one of ``'"'`` or ``'''``, followed by a space. One problem with + followed by one of ``'"'`` or ``"'"``, followed by a space. One problem with this is algorithm is that it is unable to detect the difference between "Dr." in :: @@ -160,9 +160,9 @@ :attr:`fix_sentence_endings` is false by default. Since the sentence detection algorithm relies on ``string.lowercase`` for the - definition of "lowercase letter," and a convention of using two spaces after a - period to separate sentences on the same line, it is specific to English- - language texts. + definition of "lowercase letter," and a convention of using two spaces after + a period to separate sentences on the same line, it is specific to + English-language texts. .. attribute:: TextWrapper.break_long_words @@ -173,8 +173,8 @@ (Long words will be put on a line by themselves, in order to minimize the amount by which :attr:`width` is exceeded.) -:class:`TextWrapper` also provides two public methods, analogous to the module- -level convenience functions: +:class:`TextWrapper` also provides two public methods, analogous to the +module-level convenience functions: .. method:: TextWrapper.wrap(text) Modified: doctools/trunk/Doc-26/library/threading.rst ============================================================================== --- doctools/trunk/Doc-26/library/threading.rst (original) +++ doctools/trunk/Doc-26/library/threading.rst Sun Aug 5 00:45:13 2007 @@ -197,7 +197,7 @@ All methods are executed atomically. -.. method:: Lock.acquire([blocking\ ``= 1``]) +.. method:: Lock.acquire([blocking=1]) Acquire a lock, blocking or non-blocking. @@ -244,7 +244,7 @@ :meth:`acquire` to proceed. -.. method:: RLock.acquire([blocking\ ``= 1``]) +.. method:: RLock.acquire([blocking=1]) Acquire a lock, blocking or non-blocking. Modified: doctools/trunk/Doc-26/library/timeit.rst ============================================================================== --- doctools/trunk/Doc-26/library/timeit.rst (original) +++ doctools/trunk/Doc-26/library/timeit.rst Sun Aug 5 00:45:13 2007 @@ -20,7 +20,7 @@ The module defines the following public class: -.. class:: Timer([stmt=``'pass'`` [, setup=``'pass'`` [, timer=]]]) +.. class:: Timer([stmt='pass' [, setup='pass' [, timer=]]]) Class for timing execution speed of small code snippets. @@ -40,7 +40,7 @@ larger in this case because of the extra function calls. -.. method:: Timer.print_exc([file=:const:`None`]) +.. method:: Timer.print_exc([file=None]) Helper to print a traceback from the timed code. @@ -57,7 +57,7 @@ traceback is sent; it defaults to ``sys.stderr``. -.. method:: Timer.repeat([repeat\ ``=3`` [, number\ ``=1000000``]]) +.. method:: Timer.repeat([repeat=3 [, number=1000000]]) Call :meth:`timeit` a few times. @@ -78,7 +78,7 @@ and apply common sense rather than statistics. -.. method:: Timer.timeit([number\ ``=1000000``]) +.. method:: Timer.timeit([number=1000000]) Time *number* executions of the main statement. This executes the setup statement once, and then returns the time it takes to execute the main statement @@ -99,7 +99,7 @@ Starting with version 2.6, the module also defines two convenience functions: -.. function:: repeat(stmt[, setup[, timer[, repeat\ ``=3`` [, number\ ``=1000000``]]]]) +.. function:: repeat(stmt[, setup[, timer[, repeat=3 [, number=1000000]]]]) Create a :class:`Timer` instance with the given statement, setup code and timer function and run its :meth:`repeat` method with the given repeat count and @@ -108,7 +108,7 @@ .. versionadded:: 2.6 -.. function:: timeit(stmt[, setup[, timer[, number\ ``=1000000``]]]) +.. function:: timeit(stmt[, setup[, timer[, number=1000000]]]) Create a :class:`Timer` instance with the given statement, setup code and timer function and run its :meth:`timeit` method with *number* executions. Modified: doctools/trunk/Doc-26/library/tix.rst ============================================================================== --- doctools/trunk/Doc-26/library/tix.rst (original) +++ doctools/trunk/Doc-26/library/tix.rst Sun Aug 5 00:45:13 2007 @@ -263,10 +263,10 @@ .. class:: DirSelectBox() - The :class:`DirSelectBox` is similar to the standard Motif(TM) directory- - selection box. It is generally used for the user to choose a directory. - DirSelectBox stores the directories mostly recently selected into a ComboBox - widget so that they can be quickly selected again. + The :class:`DirSelectBox` is similar to the standard Motif(TM) + directory-selection box. It is generally used for the user to choose a + directory. DirSelectBox stores the directories mostly recently selected into + a ComboBox widget so that they can be quickly selected again. .. class:: ExFileSelectBox() Modified: doctools/trunk/Doc-26/library/tkinter.rst ============================================================================== --- doctools/trunk/Doc-26/library/tkinter.rst (original) +++ doctools/trunk/Doc-26/library/tkinter.rst Sun Aug 5 00:45:13 2007 @@ -798,21 +798,21 @@ Some options and methods for menus manipulate specific menu entries. Anytime a menu index is needed for an option or a parameter, you may pass in: -* an integer which refers to the numeric position of the entry in the widget, + * an integer which refers to the numeric position of the entry in the widget, counted from the top, starting with 0; -* the string ``'active'``, which refers to the menu position that is currently + * the string ``'active'``, which refers to the menu position that is currently under the cursor; -* the string ``"last"`` which refers to the last menu item; + * the string ``"last"`` which refers to the last menu item; -* An integer preceded by ``@``, as in ``@6``, where the integer is interpreted + * An integer preceded by ``@``, as in ``@6``, where the integer is interpreted as a y pixel coordinate in the menu's coordinate system; -* the string ``"none"``, which indicates no menu entry at all, most often used + * the string ``"none"``, which indicates no menu entry at all, most often used with menu.activate() to deactivate all entries, and finally, -* a text string that is pattern matched against the label of the menu entry, as + * a text string that is pattern matched against the label of the menu entry, as scanned from the top of the menu to the bottom. Note that this index type is considered after all the others, which means that matches for menu items labelled ``last``, ``active``, or ``none`` may be interpreted as the above Modified: doctools/trunk/Doc-26/library/turtle.rst ============================================================================== --- doctools/trunk/Doc-26/library/turtle.rst (original) +++ doctools/trunk/Doc-26/library/turtle.rst Sun Aug 5 00:45:13 2007 @@ -11,9 +11,9 @@ .. sectionauthor:: Moshe Zadka -The :mod:`turtle` module provides turtle graphics primitives, in both an object- -oriented and procedure-oriented ways. Because it uses :mod:`Tkinter` for the -underlying graphics, it needs a version of python installed with Tk support. +The :mod:`turtle` module provides turtle graphics primitives, in both an +object-oriented and procedure-oriented ways. Because it uses :mod:`Tkinter` for +the underlying graphics, it needs a version of python installed with Tk support. The procedural interface uses a pen and a canvas which are automagically created when any of the functions are called. @@ -35,16 +35,16 @@ Sets the size and position of the main window. Keywords are: -* ``width``: either a size in pixels or a fraction of the screen. The default is + * ``width``: either a size in pixels or a fraction of the screen. The default is 50% of the screen. -* ``height``: either a size in pixels or a fraction of the screen. The default + * ``height``: either a size in pixels or a fraction of the screen. The default is 50% of the screen. -* ``startx``: starting position in pixels from the left edge of the screen. + * ``startx``: starting position in pixels from the left edge of the screen. ``None`` is the default value and centers the window horizontally on screen. -* ``starty``: starting position in pixels from the top edge of the screen. + * ``starty``: starting position in pixels from the top edge of the screen. ``None`` is the default value and centers the window vertically on screen. Examples:: Modified: doctools/trunk/Doc-26/library/urllib.rst ============================================================================== --- doctools/trunk/Doc-26/library/urllib.rst (original) +++ doctools/trunk/Doc-26/library/urllib.rst Sun Aug 5 00:45:13 2007 @@ -12,10 +12,10 @@ single: URL This module provides a high-level interface for fetching data across the World -Wide Web. In particular, the :func:`urlopen` function is similar to the built- -in function :func:`open`, but accepts Universal Resource Locators (URLs) instead -of filenames. Some restrictions apply --- it can only open URLs for reading, -and no seek operations are available. +Wide Web. In particular, the :func:`urlopen` function is similar to the +built-in function :func:`open`, but accepts Universal Resource Locators (URLs) +instead of filenames. Some restrictions apply --- it can only open URLs for +reading, and no seek operations are available. It defines the following public functions: @@ -42,16 +42,16 @@ .. index:: module: mimetools The :meth:`info` method returns an instance of the class - :class:`mimetools.Message` containing meta-information associated with the URL. - When the method is HTTP, these headers are those returned by the server at the - head of the retrieved HTML page (including Content-Length and Content-Type). - When the method is FTP, a Content-Length header will be present if (as is now - usual) the server passed back a file length in response to the FTP retrieval - request. A Content-Type header will be present if the MIME type can be guessed. - When the method is local-file, returned headers will include a Date representing - the file's last-modified time, a Content-Length giving file size, and a Content- - Type containing a guess at the file's type. See also the description of the - :mod:`mimetools` module. + :class:`mimetools.Message` containing meta-information associated with the + URL. When the method is HTTP, these headers are those returned by the server + at the head of the retrieved HTML page (including Content-Length and + Content-Type). When the method is FTP, a Content-Length header will be + present if (as is now usual) the server passed back a file length in response + to the FTP retrieval request. A Content-Type header will be present if the + MIME type can be guessed. When the method is local-file, returned headers + will include a Date representing the file's last-modified time, a + Content-Length giving file size, and a Content-Type containing a guess at the + file's type. See also the description of the :mod:`mimetools` module. The :meth:`geturl` method returns the real URL of the page. In some cases, the HTTP server redirects a client to another URL. The :func:`urlopen` function Modified: doctools/trunk/Doc-26/library/urllib2.rst ============================================================================== --- doctools/trunk/Doc-26/library/urllib2.rst (original) +++ doctools/trunk/Doc-26/library/urllib2.rst Sun Aug 5 00:45:13 2007 @@ -33,9 +33,9 @@ This function returns a file-like object with two additional methods: -* :meth:`geturl` --- return the URL of the resource retrieved + * :meth:`geturl` --- return the URL of the resource retrieved -* :meth:`info` --- return the meta-information of the page, as a dictionary-like + * :meth:`info` --- return the meta-information of the page, as a dictionary-like object Raises :exc:`URLError` on errors. @@ -87,9 +87,10 @@ .. exception:: HTTPError - A subclass of :exc:`URLError`, it can also function as a non-exceptional file- - like return value (the same thing that :func:`urlopen` returns). This is useful - when handling exotic HTTP errors, such as requests for authentication. + A subclass of :exc:`URLError`, it can also function as a non-exceptional + file-like return value (the same thing that :func:`urlopen` returns). This + is useful when handling exotic HTTP errors, such as requests for + authentication. The following classes are provided: @@ -365,20 +366,20 @@ are searched, and added to the possible chains (note that HTTP errors are a special case). -* :meth:`protocol_open` --- signal that the handler knows how to open *protocol* + * :meth:`protocol_open` --- signal that the handler knows how to open *protocol* URLs. -* :meth:`http_error_type` --- signal that the handler knows how to handle HTTP + * :meth:`http_error_type` --- signal that the handler knows how to handle HTTP errors with HTTP error code *type*. -* :meth:`protocol_error` --- signal that the handler knows how to handle errors + * :meth:`protocol_error` --- signal that the handler knows how to handle errors from (non-\ ``http``) *protocol*. -* :meth:`protocol_request` --- signal that the handler knows how to pre-process + * :meth:`protocol_request` --- signal that the handler knows how to pre-process *protocol* requests. -* :meth:`protocol_response` --- signal that the handler knows how to post- - process *protocol* responses. + * :meth:`protocol_response` --- signal that the handler knows how to + post-process *protocol* responses. .. method:: OpenerDirector.open(url[, data][, timeout]) Modified: doctools/trunk/Doc-26/library/user.rst ============================================================================== --- doctools/trunk/Doc-26/library/user.rst (original) +++ doctools/trunk/Doc-26/library/user.rst Sun Aug 5 00:45:13 2007 @@ -51,8 +51,8 @@ (The three-argument form of :func:`getattr` is used in case the user has not defined ``spam_verbose`` in their :file:`.pythonrc.py` file.) -Programs with extensive customization needs are better off reading a program- -specific customization file. +Programs with extensive customization needs are better off reading a +program-specific customization file. Programs with security or privacy concerns should *not* import this module; a user can easily break into a program by placing arbitrary code in the Modified: doctools/trunk/Doc-26/library/winsound.rst ============================================================================== --- doctools/trunk/Doc-26/library/winsound.rst (original) +++ doctools/trunk/Doc-26/library/winsound.rst Sun Aug 5 00:45:13 2007 @@ -41,7 +41,7 @@ :exc:`RuntimeError` is raised. -.. function:: MessageBeep([type=``MB_OK``]) +.. function:: MessageBeep([type=MB_OK]) Call the underlying :cfunc:`MessageBeep` function from the Platform API. This plays a sound as specified in the registry. The *type* argument specifies which Modified: doctools/trunk/Doc-26/library/wsgiref.rst ============================================================================== --- doctools/trunk/Doc-26/library/wsgiref.rst (original) +++ doctools/trunk/Doc-26/library/wsgiref.rst Sun Aug 5 00:45:13 2007 @@ -234,7 +234,7 @@ :mod:`wsgiref.util`.) -.. function:: make_server(host, port, app [, server_class=WSGIServer [, handler_class=:class:`WSGIRequestHandler`]]) +.. function:: make_server(host, port, app [, server_class=WSGIServer [, handler_class=WSGIRequestHandler]]) Create a new WSGI server listening on *host* and *port*, accepting connections for *app*. The return value is an instance of the supplied *server_class*, and Modified: doctools/trunk/Doc-26/library/xml.dom.rst ============================================================================== --- doctools/trunk/Doc-26/library/xml.dom.rst (original) +++ doctools/trunk/Doc-26/library/xml.dom.rst Sun Aug 5 00:45:13 2007 @@ -136,8 +136,8 @@ .. data:: XMLNS_NAMESPACE The namespace URI for namespace declarations, as defined by `Document Object - Model (DOM) Level 2 Core Specification `_ (section 1.1.8). + Model (DOM) Level 2 Core Specification + `_ (section 1.1.8). .. versionadded:: 2.2 @@ -281,12 +281,12 @@ .. attribute:: Node.previousSibling - The node that immediately precedes this one with the same parent. For instance - the element with an end-tag that comes just before the *self* element's start- - tag. Of course, XML documents are made up of more than just elements so the - previous sibling could be text, a comment, or something else. If this node is - the first child of the parent, this attribute will be ``None``. This is a read- - only attribute. + The node that immediately precedes this one with the same parent. For + instance the element with an end-tag that comes just before the *self* + element's start-tag. Of course, XML documents are made up of more than just + elements so the previous sibling could be text, a comment, or something else. + If this node is the first child of the parent, this attribute will be + ``None``. This is a read-only attribute. .. attribute:: Node.nextSibling Modified: doctools/trunk/Doc-26/library/xml.etree.elementtree.rst ============================================================================== --- doctools/trunk/Doc-26/library/xml.etree.elementtree.rst (original) +++ doctools/trunk/Doc-26/library/xml.etree.elementtree.rst Sun Aug 5 00:45:13 2007 @@ -354,8 +354,8 @@ .. method:: ElementTree.write(file[, encoding]) Writes the element tree to a file, as XML. *file* is a file name, or a file - object opened for writing. *encoding* is the output encoding (default is US- - ASCII). + object opened for writing. *encoding* is the output encoding (default is + US-ASCII). .. _elementtree-qname-objects: Modified: doctools/trunk/Doc-26/library/xml.sax.handler.rst ============================================================================== --- doctools/trunk/Doc-26/library/xml.sax.handler.rst (original) +++ doctools/trunk/Doc-26/library/xml.sax.handler.rst Sun Aug 5 00:45:13 2007 @@ -60,11 +60,11 @@ .. data:: feature_namespace_prefixes - Value: ``"http://xml.org/sax/features/namespace-prefixes"`` --- true: Report - the original prefixed names and attributes used for Namespace declarations. --- - false: Do not report attributes used for Namespace declarations, and optionally - do not report original prefixed names (default). --- access: (parsing) read- - only; (not parsing) read/write + Value: ``"http://xml.org/sax/features/namespace-prefixes"`` --- true: Report + the original prefixed names and attributes used for Namespace + declarations. --- false: Do not report attributes used for Namespace + declarations, and optionally do not report original prefixed names + (default). --- access: (parsing) read-only; (not parsing) read/write .. data:: feature_string_interning @@ -78,10 +78,10 @@ .. data:: feature_validation - Value: ``"http://xml.org/sax/features/validation"`` --- true: Report all - validation errors (implies external-general-entities and external-parameter- - entities). --- false: Do not report validation errors. --- access: (parsing) - read-only; (not parsing) read/write + Value: ``"http://xml.org/sax/features/validation"`` --- true: Report all + validation errors (implies external-general-entities and + external-parameter-entities). --- false: Do not report validation errors. --- + access: (parsing) read-only; (not parsing) read/write .. data:: feature_external_ges Modified: doctools/trunk/Doc-26/library/xml.sax.reader.rst ============================================================================== --- doctools/trunk/Doc-26/library/xml.sax.reader.rst (original) +++ doctools/trunk/Doc-26/library/xml.sax.reader.rst Sun Aug 5 00:45:13 2007 @@ -288,8 +288,8 @@ .. method:: InputSource.setByteStream(bytefile) - Set the byte stream (a Python file-like object which does not perform byte-to- - character conversion) for this input source. + Set the byte stream (a Python file-like object which does not perform + byte-to-character conversion) for this input source. The SAX parser will ignore this if there is also a character stream specified, but it will use a byte stream in preference to opening a URI connection itself. Modified: doctools/trunk/Doc-26/library/xml.sax.utils.rst ============================================================================== --- doctools/trunk/Doc-26/library/xml.sax.utils.rst (original) +++ doctools/trunk/Doc-26/library/xml.sax.utils.rst Sun Aug 5 00:45:13 2007 @@ -37,13 +37,14 @@ .. function:: quoteattr(data[, entities]) - Similar to :func:`escape`, but also prepares *data* to be used as an attribute - value. The return value is a quoted version of *data* with any additional - required replacements. :func:`quoteattr` will select a quote character based on - the content of *data*, attempting to avoid encoding any quote characters in the - string. If both single- and double-quote characters are already in *data*, the - double-quote characters will be encoded and *data* will be wrapped in double- - quotes. The resulting string can be used directly as an attribute value:: + Similar to :func:`escape`, but also prepares *data* to be used as an + attribute value. The return value is a quoted version of *data* with any + additional required replacements. :func:`quoteattr` will select a quote + character based on the content of *data*, attempting to avoid encoding any + quote characters in the string. If both single- and double-quote characters + are already in *data*, the double-quote characters will be encoded and *data* + will be wrapped in double-quotes. The resulting string can be used directly + as an attribute value:: >>> print "" % quoteattr("ab ' cd \" ef") Modified: doctools/trunk/Doc-26/license.rst ============================================================================== --- doctools/trunk/Doc-26/license.rst (original) +++ doctools/trunk/Doc-26/license.rst Sun Aug 5 00:45:13 2007 @@ -105,7 +105,7 @@ ============================================================ -.. centered:: **PSF LICENSE AGREEMENT FOR PYTHON |release|** +.. centered:: **PSF LICENSE AGREEMENT FOR PYTHON** |release| #. This LICENSE AGREEMENT is between the Python Software Foundation ("PSF"), and the Individual or Organization ("Licensee") accessing and otherwise using Python Modified: doctools/trunk/Doc-26/maclib/using.rst ============================================================================== --- doctools/trunk/Doc-26/maclib/using.rst (original) +++ doctools/trunk/Doc-26/maclib/using.rst Sun Aug 5 00:45:13 2007 @@ -43,8 +43,8 @@ The Apple-provided build of Python is installed in :file:`/System/Library/Frameworks/Python.framework` and :file:`/usr/bin/python`, -respectively. You should never modify or delete these, as they are Apple- -controlled and are used by Apple- or third-party software. +respectively. You should never modify or delete these, as they are +Apple-controlled and are used by Apple- or third-party software. IDLE includes a help menu that allows you to access Python documentation. If you are completely new to Python you should start reading the tutorial introduction Modified: doctools/trunk/Doc-26/reference/datamodel.rst ============================================================================== --- doctools/trunk/Doc-26/reference/datamodel.rst (original) +++ doctools/trunk/Doc-26/reference/datamodel.rst Sun Aug 5 00:45:13 2007 @@ -251,10 +251,10 @@ single: item selection single: subscription - These represent finite ordered sets indexed by non-negative numbers. The built- - in function :func:`len` returns the number of items of a sequence. When the - length of a sequence is *n*, the index set contains the numbers 0, 1, ..., - *n*-1. Item *i* of sequence *a* is selected by ``a[i]``. + These represent finite ordered sets indexed by non-negative numbers. The + built-in function :func:`len` returns the number of items of a sequence. When + the length of a sequence is *n*, the index set contains the numbers 0, 1, + ..., *n*-1. Item *i* of sequence *a* is selected by ``a[i]``. .. index:: single: slicing @@ -592,13 +592,13 @@ single: im_self (method attribute) When a user-defined method object is created by retrieving a user-defined - function object from a class, its :attr:`im_self` attribute is ``None`` and the - method object is said to be unbound. When one is created by retrieving a user- - defined function object from a class via one of its instances, its - :attr:`im_self` attribute is the instance, and the method object is said to be - bound. In either case, the new method's :attr:`im_class` attribute is the class - from which the retrieval takes place, and its :attr:`im_func` attribute is the - original function object. + function object from a class, its :attr:`im_self` attribute is ``None`` + and the method object is said to be unbound. When one is created by + retrieving a user-defined function object from a class via one of its + instances, its :attr:`im_self` attribute is the instance, and the method + object is said to be bound. In either case, the new method's + :attr:`im_class` attribute is the class from which the retrieval takes + place, and its :attr:`im_func` attribute is the original function object. .. index:: single: im_func (method attribute) @@ -664,14 +664,14 @@ object: function pair: C; language - A built-in function object is a wrapper around a C function. Examples of built- - in functions are :func:`len` and :func:`math.sin` (:mod:`math` is a standard - built-in module). The number and type of the arguments are determined by the C - function. Special read-only attributes: :attr:`__doc__` is the function's - documentation string, or ``None`` if unavailable; :attr:`__name__` is the - function's name; :attr:`__self__` is set to ``None`` (but see the next item); - :attr:`__module__` is the name of the module the function was defined in or - ``None`` if unavailable. + A built-in function object is a wrapper around a C function. Examples of + built-in functions are :func:`len` and :func:`math.sin` (:mod:`math` is a + standard built-in module). The number and type of the arguments are + determined by the C function. Special read-only attributes: + :attr:`__doc__` is the function's documentation string, or ``None`` if + unavailable; :attr:`__name__` is the function's name; :attr:`__self__` is + set to ``None`` (but see the next item); :attr:`__module__` is the name of + the module the function was defined in or ``None`` if unavailable. Built-in methods .. index:: @@ -750,12 +750,12 @@ of the shared library file. Classes - Class objects are created by class definitions (see section :ref:`class`). - A class has a namespace implemented by a dictionary object. Class - attribute references are translated to lookups in this dictionary, e.g., ``C.x`` - is translated to ``C.__dict__["x"]``. When the attribute name is not found - there, the attribute search continues in the base classes. The search is depth- - first, left-to-right in the order of occurrence in the base class list. + Class objects are created by class definitions (see section :ref:`class`). A + class has a namespace implemented by a dictionary object. Class attribute + references are translated to lookups in this dictionary, e.g., ``C.x`` is + translated to ``C.__dict__["x"]``. When the attribute name is not found + there, the attribute search continues in the base classes. The search is + depth-first, left-to-right in the order of occurrence in the base class list. .. index:: object: class @@ -766,17 +766,17 @@ object: dictionary pair: class; attribute - When a class attribute reference (for class :class:`C`, say) would yield a user- - defined function object or an unbound user-defined method object whose + When a class attribute reference (for class :class:`C`, say) would yield a + user-defined function object or an unbound user-defined method object whose associated class is either :class:`C` or one of its base classes, it is transformed into an unbound user-defined method object whose :attr:`im_class` attribute is :class:`C`. When it would yield a class method object, it is - transformed into a bound user-defined method object whose :attr:`im_class` and - :attr:`im_self` attributes are both :class:`C`. When it would yield a static - method object, it is transformed into the object wrapped by the static method - object. See section :ref:`descriptors` for another way in which attributes - retrieved from a class may differ from those actually contained in its - :attr:`__dict__`. + transformed into a bound user-defined method object whose :attr:`im_class` + and :attr:`im_self` attributes are both :class:`C`. When it would yield a + static method object, it is transformed into the object wrapped by the static + method object. See section :ref:`descriptors` for another way in which + attributes retrieved from a class may differ from those actually contained in + its :attr:`__dict__`. .. index:: triple: class; attribute; assignment @@ -2039,14 +2039,14 @@ These methods are called to implement the augmented arithmetic operations (``+=``, ``-=``, ``*=``, ``/=``, ``//=``, ``%=``, ``**=``, ``<<=``, ``>>=``, - ``&=``, ``^=``, ``|=``). These methods should attempt to do the operation in- - place (modifying *self*) and return the result (which could be, but does not - have to be, *self*). If a specific method is not defined, the augmented + ``&=``, ``^=``, ``|=``). These methods should attempt to do the operation + in-place (modifying *self*) and return the result (which could be, but does + not have to be, *self*). If a specific method is not defined, the augmented operation falls back to the normal methods. For instance, to evaluate the expression *x*``+=``*y*, where *x* is an instance of a class that has an - :meth:`__iadd__` method, ``x.__iadd__(y)`` is called. If *x* is an instance of - a class that does not define a :meth:`__iadd__` method, ``x.__add__(y)`` and - ``y.__radd__(x)`` are considered, as with the evaluation of *x*``+``*y*. + :meth:`__iadd__` method, ``x.__iadd__(y)`` is called. If *x* is an instance + of a class that does not define a :meth:`__iadd__` method, ``x.__add__(y)`` + and ``y.__radd__(x)`` are considered, as with the evaluation of *x*``+``*y*. .. method:: numeric object.__neg__(self) Modified: doctools/trunk/Doc-26/reference/executionmodel.rst ============================================================================== --- doctools/trunk/Doc-26/reference/executionmodel.rst (original) +++ doctools/trunk/Doc-26/reference/executionmodel.rst Sun Aug 5 00:45:13 2007 @@ -206,8 +206,8 @@ Python uses the "termination" model of error handling: an exception handler can find out what happened and continue execution at an outer level, but it cannot -repair the cause of the error and retry the failing operation (except by re- -entering the offending piece of code from the top). +repair the cause of the error and retry the failing operation (except by +re-entering the offending piece of code from the top). .. index:: single: SystemExit (built-in exception) Modified: doctools/trunk/Doc-26/reference/expressions.rst ============================================================================== --- doctools/trunk/Doc-26/reference/expressions.rst (original) +++ doctools/trunk/Doc-26/reference/expressions.rst Sun Aug 5 00:45:13 2007 @@ -196,9 +196,9 @@ pair: empty; list A list display yields a new list object. Its contents are specified by -providing either a list of expressions or a list comprehension. When a comma- -separated list of expressions is supplied, its elements are evaluated from left -to right and placed into the list object in that order. When a list +providing either a list of expressions or a list comprehension. When a +comma-separated list of expressions is supplied, its elements are evaluated from +left to right and placed into the list object in that order. When a list comprehension is supplied, it consists of a single expression followed by at least one :keyword:`for` clause and zero or more :keyword:`for` or :keyword:`if` clauses. In this case, the elements of the new list are those that would be Modified: doctools/trunk/Doc-26/reference/lexical_analysis.rst ============================================================================== --- doctools/trunk/Doc-26/reference/lexical_analysis.rst (original) +++ doctools/trunk/Doc-26/reference/lexical_analysis.rst Sun Aug 5 00:45:13 2007 @@ -457,14 +457,14 @@ In plain English: String literals can be enclosed in matching single quotes (``'``) or double quotes (``"``). They can also be enclosed in matching groups -of three single or double quotes (these are generally referred to as *triple- -quoted strings*). The backslash (``\``) character is used to escape characters -that otherwise have a special meaning, such as newline, backslash itself, or the -quote character. String literals may optionally be prefixed with a letter -``'r'`` or ``'R'``; such strings are called :dfn:`raw strings` and use different -rules for interpreting backslash escape sequences. A prefix of ``'u'`` or -``'U'`` makes the string a Unicode string. Unicode strings use the Unicode -character set as defined by the Unicode Consortium and ISO 10646. Some +of three single or double quotes (these are generally referred to as +*triple-quoted strings*). The backslash (``\``) character is used to escape +characters that otherwise have a special meaning, such as newline, backslash +itself, or the quote character. String literals may optionally be prefixed with +a letter ``'r'`` or ``'R'``; such strings are called :dfn:`raw strings` and use +different rules for interpreting backslash escape sequences. A prefix of +``'u'`` or ``'U'`` makes the string a Unicode string. Unicode strings use the +Unicode character set as defined by the Unicode Consortium and ISO 10646. Some additional escape sequences, described below, are available in Unicode strings. The two prefix characters may be combined; in this case, ``'u'`` must appear before ``'r'``. Modified: doctools/trunk/Doc-26/reference/simple_stmts.rst ============================================================================== --- doctools/trunk/Doc-26/reference/simple_stmts.rst (original) +++ doctools/trunk/Doc-26/reference/simple_stmts.rst Sun Aug 5 00:45:13 2007 @@ -790,11 +790,8 @@ can appear before a future statement are: * the module docstring (if any), - * comments, - * blank lines, and - * other future statements. The features recognized by Python 2.5 are ``absolute_import``, ``division``, Modified: doctools/trunk/Doc-26/tutorial/appetite.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/appetite.rst (original) +++ doctools/trunk/Doc-26/tutorial/appetite.rst Sun Aug 5 00:45:13 2007 @@ -5,10 +5,10 @@ ********************** If you do much work on computers, eventually you find that there's some task -you'd like to automate. For example, you may wish to perform a search-and- -replace over a large number of text files, or rename and rearrange a bunch of -photo files in a complicated way. Perhaps you'd like to write a small custom -database, or a specialized GUI application, or a simple game. +you'd like to automate. For example, you may wish to perform a +search-and-replace over a large number of text files, or rename and rearrange a +bunch of photo files in a complicated way. Perhaps you'd like to write a small +custom database, or a specialized GUI application, or a simple game. If you're a professional software developer, you may have to work with several C/C++/Java libraries but find the usual write/compile/test/re-compile cycle is Modified: doctools/trunk/Doc-26/tutorial/datastructures.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/datastructures.rst (original) +++ doctools/trunk/Doc-26/tutorial/datastructures.rst Sun Aug 5 00:45:13 2007 @@ -451,8 +451,8 @@ >>> 'guido' in tel True -The :func:`dict` constructor builds dictionaries directly from lists of key- -value pairs stored as tuples. When the pairs form a pattern, list +The :func:`dict` constructor builds dictionaries directly from lists of +key-value pairs stored as tuples. When the pairs form a pattern, list comprehensions can compactly specify the key-value list. :: >>> dict([('sape', 4139), ('guido', 4127), ('jack', 4098)]) Modified: doctools/trunk/Doc-26/tutorial/errors.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/errors.rst (original) +++ doctools/trunk/Doc-26/tutorial/errors.rst Sun Aug 5 00:45:13 2007 @@ -227,8 +227,8 @@ fine, but there seems to be a growing stylistic preference for the latter. If you need to determine whether an exception was raised but don't intend to -handle it, a simpler form of the :keyword:`raise` statement allows you to re- -raise the exception:: +handle it, a simpler form of the :keyword:`raise` statement allows you to +re-raise the exception:: >>> try: ... raise NameError, 'HiThere' Modified: doctools/trunk/Doc-26/tutorial/glossary.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/glossary.rst (original) +++ doctools/trunk/Doc-26/tutorial/glossary.rst Sun Aug 5 00:45:13 2007 @@ -155,13 +155,14 @@ .. index:: single: global interpreter lock global interpreter lock - The lock used by Python threads to assure that only one thread can be run at a - time. This simplifies Python by assuring that no two processes can access the - same memory at the same time. Locking the entire interpreter makes it easier - for the interpreter to be multi-threaded, at the expense of some parallelism on - multi-processor machines. Efforts have been made in the past to create a "free- - threaded" interpreter (one which locks shared data at a much finer granularity), - but performance suffered in the common single-processor case. + The lock used by Python threads to assure that only one thread can be run at + a time. This simplifies Python by assuring that no two processes can access + the same memory at the same time. Locking the entire interpreter makes it + easier for the interpreter to be multi-threaded, at the expense of some + parallelism on multi-processor machines. Efforts have been made in the past + to create a "free-threaded" interpreter (one which locks shared data at a + much finer granularity), but performance suffered in the common + single-processor case. .. index:: single: IDLE Modified: doctools/trunk/Doc-26/tutorial/introduction.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/introduction.rst (original) +++ doctools/trunk/Doc-26/tutorial/introduction.rst Sun Aug 5 00:45:13 2007 @@ -429,9 +429,10 @@ characters of Latin-1. For experts, there is also a raw mode just like the one for normal strings. You -have to prefix the opening quote with 'ur' to have Python use the *Raw-Unicode- -Escape* encoding. It will only apply the above ``\uXXXX`` conversion if there is -an uneven number of backslashes in front of the small 'u'. :: +have to prefix the opening quote with 'ur' to have Python use the +*Raw-Unicode-Escape* encoding. It will only apply the above ``\uXXXX`` +conversion if there is an uneven number of backslashes in front of the small +'u'. :: >>> ur'Hello\u0020World !' u'Hello World !' Modified: doctools/trunk/Doc-26/tutorial/modules.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/modules.rst (original) +++ doctools/trunk/Doc-26/tutorial/modules.rst Sun Aug 5 00:45:13 2007 @@ -168,9 +168,9 @@ As an important speed-up of the start-up time for short programs that use a lot of standard modules, if a file called :file:`spam.pyc` exists in the directory -where :file:`spam.py` is found, this is assumed to contain an already-"byte- -compiled" version of the module :mod:`spam`. The modification time of the -version of :file:`spam.py` used to create :file:`spam.pyc` is recorded in +where :file:`spam.py` is found, this is assumed to contain an +already-"byte-compiled" version of the module :mod:`spam`. The modification time +of the version of :file:`spam.py` used to create :file:`spam.pyc` is recorded in :file:`spam.pyc`, and the :file:`.pyc` file is ignored if these don't match. Normally, you don't need to do anything to create the :file:`spam.pyc` file. Modified: doctools/trunk/Doc-26/tutorial/whatnow.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/whatnow.rst (original) +++ doctools/trunk/Doc-26/tutorial/whatnow.rst Sun Aug 5 00:45:13 2007 @@ -49,12 +49,12 @@ Cookbook (O'Reilly & Associates, ISBN 0-596-00797-3.) For Python-related questions and problem reports, you can post to the newsgroup -:newsgroup:`comp.lang.python`, or send them to the mailing list at python- -list at python.org. The newsgroup and mailing list are gatewayed, so messages -posted to one will automatically be forwarded to the other. There are around -120 postings a day (with peaks up to several hundred), asking (and answering) -questions, suggesting new features, and announcing new modules. Before posting, -be sure to check the list of `Frequently Asked Questions +:newsgroup:`comp.lang.python`, or send them to the mailing list at +python-list at python.org. The newsgroup and mailing list are gatewayed, so +messages posted to one will automatically be forwarded to the other. There are +around 120 postings a day (with peaks up to several hundred), asking (and +answering) questions, suggesting new features, and announcing new modules. +Before posting, be sure to check the list of `Frequently Asked Questions `_ (also called the FAQ), or look for it in the :file:`Misc/` directory of the Python source distribution. Mailing list archives are available at http://mail.python.org/pipermail/. The FAQ answers Modified: doctools/trunk/Doc-26/whatsnew/2.0.rst ============================================================================== --- doctools/trunk/Doc-26/whatsnew/2.0.rst (original) +++ doctools/trunk/Doc-26/whatsnew/2.0.rst Sun Aug 5 00:45:13 2007 @@ -181,7 +181,7 @@ * ``ord(u)``, where *u* is a 1-character regular or Unicode string, returns the number of the character as an integer. -* ``unicode(string [, *encoding*] [, *errors*] )`` creates a Unicode string +* ``unicode(string [, encoding] [, errors] )`` creates a Unicode string from an 8-bit string. ``encoding`` is a string naming the encoding to use. The ``errors`` parameter specifies the treatment of characters that are invalid for the current encoding; passing ``'strict'`` as the value causes an exception to Modified: doctools/trunk/Doc-26/whatsnew/2.1.rst ============================================================================== --- doctools/trunk/Doc-26/whatsnew/2.1.rst (original) +++ doctools/trunk/Doc-26/whatsnew/2.1.rst Sun Aug 5 00:45:13 2007 @@ -755,12 +755,12 @@ Wolfson, but after some python-dev discussion, a weaker final version was checked in. -* Applying :func:`repr` to strings previously used octal escapes for non- - printable characters; for example, a newline was ``'\012'``. This was a +* Applying :func:`repr` to strings previously used octal escapes for + non-printable characters; for example, a newline was ``'\012'``. This was a vestigial trace of Python's C ancestry, but today octal is of very little practical use. Ka-Ping Yee suggested using hex escapes instead of octal ones, - and using the ``\n``, ``\t``, ``\r`` escapes for the appropriate characters, and - implemented this new formatting. + and using the ``\n``, ``\t``, ``\r`` escapes for the appropriate characters, + and implemented this new formatting. * Syntax errors detected at compile-time can now raise exceptions containing the filename and line number of the error, a pleasant side effect of the compiler Modified: doctools/trunk/Doc-26/whatsnew/2.3.rst ============================================================================== --- doctools/trunk/Doc-26/whatsnew/2.3.rst (original) +++ doctools/trunk/Doc-26/whatsnew/2.3.rst Sun Aug 5 00:45:13 2007 @@ -1660,12 +1660,13 @@ >{}>{}> u"www.Alliancefran?aise.nu".encode("idna") 'www.xn--alliancefranaise-npb.nu' - The :mod:`socket` module has also been extended to transparently convert Unicode - hostnames to the ACE version before passing them to the C library. Modules that - deal with hostnames such as :mod:`httplib` and :mod:`ftplib`) also support - Unicode host names; :mod:`httplib` also sends HTTP ``Host`` headers using the - ACE version of the domain name. :mod:`urllib` supports Unicode URLs with non- - ASCII host names as long as the ``path`` part of the URL is ASCII only. + The :mod:`socket` module has also been extended to transparently convert + Unicode hostnames to the ACE version before passing them to the C library. + Modules that deal with hostnames such as :mod:`httplib` and :mod:`ftplib`) + also support Unicode host names; :mod:`httplib` also sends HTTP ``Host`` + headers using the ACE version of the domain name. :mod:`urllib` supports + Unicode URLs with non-ASCII host names as long as the ``path`` part of the URL + is ASCII only. To implement this change, the :mod:`stringprep` module, the ``mkstringprep`` tool and the ``punycode`` encoding have been added. Modified: doctools/trunk/Doc-26/whatsnew/2.5.rst ============================================================================== --- doctools/trunk/Doc-26/whatsnew/2.5.rst (original) +++ doctools/trunk/Doc-26/whatsnew/2.5.rst Sun Aug 5 00:45:13 2007 @@ -1048,12 +1048,12 @@ returned by the iterator evaluate as true. (Suggested by Guido van Rossum, and implemented by Raymond Hettinger.) -* The result of a class's :meth:`__hash__` method can now be either a long +* The result of a class's :meth:`__hash__` method can now be either a long integer or a regular integer. If a long integer is returned, the hash of that - value is taken. In earlier versions the hash value was required to be a regular - integer, but in 2.5 the :func:`id` built-in was changed to always return non- - negative numbers, and users often seem to use ``id(self)`` in :meth:`__hash__` - methods (though this is discouraged). + value is taken. In earlier versions the hash value was required to be a + regular integer, but in 2.5 the :func:`id` built-in was changed to always + return non-negative numbers, and users often seem to use ``id(self)`` in + :meth:`__hash__` methods (though this is discouraged). .. % Bug #1536021 Modified: doctools/trunk/Doc-3k/c-api/abstract.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/abstract.rst (original) +++ doctools/trunk/Doc-3k/c-api/abstract.rst Sun Aug 5 00:45:13 2007 @@ -182,9 +182,9 @@ either is not a class object, a more general mechanism is used to determine the class relationship of the two objects. When testing if *B* is a subclass of *A*, if *A* is *B*, :cfunc:`PyObject_IsSubclass` returns true. If *A* and *B* -are different objects, *B*'s :attr:`__bases__` attribute is searched in a depth- -first fashion for *A* --- the presence of the :attr:`__bases__` attribute is -considered sufficient for this determination. +are different objects, *B*'s :attr:`__bases__` attribute is searched in a +depth-first fashion for *A* --- the presence of the :attr:`__bases__` attribute +is considered sufficient for this determination. .. cfunction:: int PyObject_IsSubclass(PyObject *derived, PyObject *cls) Modified: doctools/trunk/Doc-3k/c-api/concrete.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/concrete.rst (original) +++ doctools/trunk/Doc-3k/c-api/concrete.rst Sun Aug 5 00:45:13 2007 @@ -1758,11 +1758,9 @@ Rich compare two unicode strings and return one of the following: -* ``NULL`` in case an exception was raised - -* :const:`Py_True` or :const:`Py_False` for successful comparisons - -* :const:`Py_NotImplemented` in case the type combination is unknown + * ``NULL`` in case an exception was raised + * :const:`Py_True` or :const:`Py_False` for successful comparisons + * :const:`Py_NotImplemented` in case the type combination is unknown Note that :const:`Py_EQ` and :const:`Py_NE` comparisons can cause a :exc:`UnicodeWarning` in case the conversion of the arguments to Unicode fails @@ -2528,7 +2526,7 @@ .. index:: single: EOFError (built-in exception) - Equivalent to ``p.readline([*n*])``, this function reads one line from the + Equivalent to ``p.readline([n])``, this function reads one line from the object *p*. *p* may be a file object or any object with a :meth:`readline` method. If *n* is ``0``, exactly one line is read, regardless of the length of the line. If *n* is greater than ``0``, no more than *n* bytes will be read @@ -2890,8 +2888,9 @@ .. cvar:: PyTypeObject PySeqIter_Type - Type object for iterator objects returned by :cfunc:`PySeqIter_New` and the one- - argument form of the :func:`iter` built-in function for built-in sequence types. + Type object for iterator objects returned by :cfunc:`PySeqIter_New` and the + one-argument form of the :func:`iter` built-in function for built-in sequence + types. .. versionadded:: 2.2 @@ -3082,14 +3081,14 @@ .. cfunction:: PyObject* PyWeakref_NewRef(PyObject *ob, PyObject *callback) - Return a weak reference object for the object *ob*. This will always return a - new reference, but is not guaranteed to create a new object; an existing + Return a weak reference object for the object *ob*. This will always return + a new reference, but is not guaranteed to create a new object; an existing reference object may be returned. The second parameter, *callback*, can be a callable object that receives notification when *ob* is garbage collected; it should accept a single parameter, which will be the weak reference object - itself. *callback* may also be ``None`` or *NULL*. If *ob* is not a weakly- - referencable object, or if *callback* is not callable, ``None``, or *NULL*, this - will return *NULL* and raise :exc:`TypeError`. + itself. *callback* may also be ``None`` or *NULL*. If *ob* is not a + weakly-referencable object, or if *callback* is not callable, ``None``, or + *NULL*, this will return *NULL* and raise :exc:`TypeError`. .. versionadded:: 2.2 @@ -3098,12 +3097,12 @@ Return a weak reference proxy object for the object *ob*. This will always return a new reference, but is not guaranteed to create a new object; an - existing proxy object may be returned. The second parameter, *callback*, can be - a callable object that receives notification when *ob* is garbage collected; it - should accept a single parameter, which will be the weak reference object - itself. *callback* may also be ``None`` or *NULL*. If *ob* is not a weakly- - referencable object, or if *callback* is not callable, ``None``, or *NULL*, this - will return *NULL* and raise :exc:`TypeError`. + existing proxy object may be returned. The second parameter, *callback*, can + be a callable object that receives notification when *ob* is garbage + collected; it should accept a single parameter, which will be the weak + reference object itself. *callback* may also be ``None`` or *NULL*. If *ob* + is not a weakly-referencable object, or if *callback* is not callable, + ``None``, or *NULL*, this will return *NULL* and raise :exc:`TypeError`. .. versionadded:: 2.2 Modified: doctools/trunk/Doc-3k/c-api/init.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/init.rst (original) +++ doctools/trunk/Doc-3k/c-api/init.rst Sun Aug 5 00:45:13 2007 @@ -102,15 +102,16 @@ ``sys.stdout`` and ``sys.stderr`` (however these refer to the same underlying :ctype:`FILE` structures in the C library). - The return value points to the first thread state created in the new sub- - interpreter. This thread state is made in the current thread state. Note that - no actual thread is created; see the discussion of thread states below. If - creation of the new interpreter is unsuccessful, *NULL* is returned; no - exception is set since the exception state is stored in the current thread state - and there may not be a current thread state. (Like all other Python/C API - functions, the global interpreter lock must be held before calling this function - and is still held when it returns; however, unlike most other Python/C API - functions, there needn't be a current thread state on entry.) + The return value points to the first thread state created in the new + sub-interpreter. This thread state is made in the current thread state. + Note that no actual thread is created; see the discussion of thread states + below. If creation of the new interpreter is unsuccessful, *NULL* is + returned; no exception is set since the exception state is stored in the + current thread state and there may not be a current thread state. (Like all + other Python/C API functions, the global interpreter lock must be held before + calling this function and is still held when it returns; however, unlike most + other Python/C API functions, there needn't be a current thread state on + entry.) .. index:: single: Py_Finalize() @@ -169,15 +170,15 @@ single: main() single: Py_GetPath() - This function should be called before :cfunc:`Py_Initialize` is called for the - first time, if it is called at all. It tells the interpreter the value of the - ``argv[0]`` argument to the :cfunc:`main` function of the program. This is used - by :cfunc:`Py_GetPath` and some other functions below to find the Python run- - time libraries relative to the interpreter executable. The default value is - ``'python'``. The argument should point to a zero-terminated character string - in static storage whose contents will not change for the duration of the - program's execution. No code in the Python interpreter will change the contents - of this storage. + This function should be called before :cfunc:`Py_Initialize` is called for + the first time, if it is called at all. It tells the interpreter the value + of the ``argv[0]`` argument to the :cfunc:`main` function of the program. + This is used by :cfunc:`Py_GetPath` and some other functions below to find + the Python run-time libraries relative to the interpreter executable. The + default value is ``'python'``. The argument should point to a + zero-terminated character string in static storage whose contents will not + change for the duration of the program's execution. No code in the Python + interpreter will change the contents of this storage. .. cfunction:: char* Py_GetProgramName() @@ -376,12 +377,12 @@ single: interpreter lock single: lock, interpreter -The Python interpreter is not fully thread safe. In order to support multi- -threaded Python programs, there's a global lock that must be held by the current -thread before it can safely access Python objects. Without the lock, even the -simplest operations could cause problems in a multi-threaded program: for -example, when two threads simultaneously increment the reference count of the -same object, the reference count could end up being incremented only once +The Python interpreter is not fully thread safe. In order to support +multi-threaded Python programs, there's a global lock that must be held by the +current thread before it can safely access Python objects. Without the lock, +even the simplest operations could cause problems in a multi-threaded program: +for example, when two threads simultaneously increment the reference count of +the same object, the reference count could end up being incremented only once instead of twice. .. index:: single: setcheckinterval() (in module sys) Modified: doctools/trunk/Doc-3k/c-api/intro.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/intro.rst (original) +++ doctools/trunk/Doc-3k/c-api/intro.rst Sun Aug 5 00:45:13 2007 @@ -70,7 +70,7 @@ To include the headers, place both directories (if different) on your compiler's search path for includes. Do *not* place the parent directories on the search -path and then use ``#include ``; this will break on +path and then use ``#include ``; this will break on multi-platform builds since the platform independent headers under :envvar:`prefix` include the platform specific headers from :envvar:`exec_prefix`. @@ -397,16 +397,16 @@ .. index:: single: exc_info() (in module sys) -Note that starting with Python 1.5, the preferred, thread-safe way to access -the exception state from Python code is to call the function -:func:`sys.exc_info`, which returns the per-thread exception state for Python -code. Also, the semantics of both ways to access the exception state have -changed so that a function which catches an exception will save and restore its -thread's exception state so as to preserve the exception state of its caller. -This prevents common bugs in exception handling code caused by an innocent- -looking function overwriting the exception being handled; it also reduces the -often unwanted lifetime extension for objects that are referenced by the stack -frames in the traceback. +Note that starting with Python 1.5, the preferred, thread-safe way to access the +exception state from Python code is to call the function :func:`sys.exc_info`, +which returns the per-thread exception state for Python code. Also, the +semantics of both ways to access the exception state have changed so that a +function which catches an exception will save and restore its thread's exception +state so as to preserve the exception state of its caller. This prevents common +bugs in exception handling code caused by an innocent-looking function +overwriting the exception being handled; it also reduces the often unwanted +lifetime extension for objects that are referenced by the stack frames in the +traceback. As a general principle, a function that calls another function to perform some task should check whether the called function raised an exception, and if so, @@ -531,13 +531,13 @@ based upon its best guess for the location of the standard Python interpreter executable, assuming that the Python library is found in a fixed location relative to the Python interpreter executable. In particular, it looks for a -directory named :file:`lib/python|version|` relative to the parent directory +directory named :file:`lib/python{X.Y}` relative to the parent directory where the executable named :file:`python` is found on the shell command search path (the environment variable :envvar:`PATH`). For instance, if the Python executable is found in :file:`/usr/local/bin/python`, it will assume that the libraries are in -:file:`/usr/local/lib/python|version|`. (In fact, this particular path is also +:file:`/usr/local/lib/python{X.Y}`. (In fact, this particular path is also the "fallback" location, used when no executable file named :file:`python` is found along :envvar:`PATH`.) The user can override this behavior by setting the environment variable :envvar:`PYTHONHOME`, or insert additional directories in @@ -589,9 +589,9 @@ Compiling the interpreter with the :cmacro:`Py_DEBUG` macro defined produces what is generally meant by "a debug build" of Python. :cmacro:`Py_DEBUG` is enabled in the Unix build by adding :option:`--with-pydebug` to the -:file:`configure` command. It is also implied by the presence of the not- -Python-specific :cmacro:`_DEBUG` macro. When :cmacro:`Py_DEBUG` is enabled in -the Unix build, compiler optimization is disabled. +:file:`configure` command. It is also implied by the presence of the +not-Python-specific :cmacro:`_DEBUG` macro. When :cmacro:`Py_DEBUG` is enabled +in the Unix build, compiler optimization is disabled. In addition to the reference count debugging described below, the following extra checks are performed: Modified: doctools/trunk/Doc-3k/c-api/newtypes.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/newtypes.rst (original) +++ doctools/trunk/Doc-3k/c-api/newtypes.rst Sun Aug 5 00:45:13 2007 @@ -480,10 +480,10 @@ The basic size does not include the GC header size (this is new in Python 2.2; in 2.1 and 2.0, the GC header size was included in :attr:`tp_basicsize`). - These fields are inherited separately by subtypes. If the base type has a non- - zero :attr:`tp_itemsize`, it is generally not safe to set :attr:`tp_itemsize` to - a different non-zero value in a subtype (though this depends on the - implementation of the base type). + These fields are inherited separately by subtypes. If the base type has a + non-zero :attr:`tp_itemsize`, it is generally not safe to set + :attr:`tp_itemsize` to a different non-zero value in a subtype (though this + depends on the implementation of the base type). A note about alignment: if the variable items require a particular alignment, this should be taken care of by the value of :attr:`tp_basicsize`. Example: Modified: doctools/trunk/Doc-3k/c-api/utilities.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/utilities.rst (original) +++ doctools/trunk/Doc-3k/c-api/utilities.rst Sun Aug 5 00:45:13 2007 @@ -489,13 +489,13 @@ Unicode into a character buffer. It only works for encoded data without embedded NUL bytes. - This format requires two arguments. The first is only used as input, and must - be a :ctype:`const char\*` which points to the name of an encoding as a NUL- - terminated string, or *NULL*, in which case the default encoding is used. An - exception is raised if the named encoding is not known to Python. The second - argument must be a :ctype:`char\*\*`; the value of the pointer it references - will be set to a buffer with the contents of the argument text. The text will - be encoded in the encoding specified by the first argument. + This format requires two arguments. The first is only used as input, and + must be a :ctype:`const char\*` which points to the name of an encoding as a + NUL-terminated string, or *NULL*, in which case the default encoding is used. + An exception is raised if the named encoding is not known to Python. The + second argument must be a :ctype:`char\*\*`; the value of the pointer it + references will be set to a buffer with the contents of the argument text. + The text will be encoded in the encoding specified by the first argument. :cfunc:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy the encoded data into this buffer and adjust *\*buffer* to reference the newly @@ -513,14 +513,14 @@ input data which contains NUL characters. It requires three arguments. The first is only used as input, and must be a - :ctype:`const char\*` which points to the name of an encoding as a NUL- - terminated string, or *NULL*, in which case the default encoding is used. An - exception is raised if the named encoding is not known to Python. The second - argument must be a :ctype:`char\*\*`; the value of the pointer it references - will be set to a buffer with the contents of the argument text. The text will - be encoded in the encoding specified by the first argument. The third argument - must be a pointer to an integer; the referenced integer will be set to the - number of bytes in the output buffer. + :ctype:`const char\*` which points to the name of an encoding as a + NUL-terminated string, or *NULL*, in which case the default encoding is used. + An exception is raised if the named encoding is not known to Python. The + second argument must be a :ctype:`char\*\*`; the value of the pointer it + references will be set to a buffer with the contents of the argument text. + The text will be encoded in the encoding specified by the first argument. + The third argument must be a pointer to an integer; the referenced integer + will be set to the number of bytes in the output buffer. There are two modes of operation: @@ -979,14 +979,14 @@ The return value (*rv*) for these functions should be interpreted as follows: * When ``0 <= rv < size``, the output conversion was successful and *rv* - characters were written to *str* (excluding the trailing ``'\\0'`` byte at + characters were written to *str* (excluding the trailing ``'\0'`` byte at *str*[*rv*]). * When ``rv >= size``, the output conversion was truncated and a buffer with - ``rv + 1`` bytes would have been needed to succeed. *str*[*size*-1] is ``'\\0'`` + ``rv + 1`` bytes would have been needed to succeed. *str*[*size*-1] is ``'\0'`` in this case. -* When ``rv < 0``, "something bad happened." *str*[*size*-1] is ``'\\0'`` in +* When ``rv < 0``, "something bad happened." *str*[*size*-1] is ``'\0'`` in this case too, but the rest of *str* is undefined. The exact cause of the error depends on the underlying platform. Modified: doctools/trunk/Doc-3k/distutils/apiref.rst ============================================================================== --- doctools/trunk/Doc-3k/distutils/apiref.rst (original) +++ doctools/trunk/Doc-3k/distutils/apiref.rst Sun Aug 5 00:45:13 2007 @@ -100,7 +100,7 @@ +--------------------+--------------------------------+-------------------------------------------------------------+ -.. function:: run_setup(script_name[, script_args=``None``, stop_after=``'run'``]) +.. function:: run_setup(script_name[, script_args=None, stop_after='run']) Run a setup script in a somewhat controlled environment, and return the :class:`distutils.dist.Distribution` instance that drives things. This is @@ -341,7 +341,7 @@ to :command:`build`, :command:`build_ext`, :command:`build_clib`). -.. class:: CCompiler([verbose=``0``, dry_run=``0``, force=``0``]) +.. class:: CCompiler([verbose=0, dry_run=0, force=0]) The abstract base class :class:`CCompiler` defines the interface that must be implemented by real compiler classes. The class also has some utility methods @@ -431,7 +431,7 @@ runtime linker may search by default. - .. method:: CCompiler.define_macro(name[, value=``None``]) + .. method:: CCompiler.define_macro(name[, value=None]) Define a preprocessor macro for all compilations driven by this compiler object. The optional parameter *value* should be a string; if it is not supplied, then @@ -442,11 +442,11 @@ .. method:: CCompiler.undefine_macro(name) Undefine a preprocessor macro for all compilations driven by this compiler - object. If the same macro is defined by :meth:`define_macro` and undefined by - :meth:`undefine_macro` the last call takes precedence (including multiple - redefinitions or undefinitions). If the macro is redefined/undefined on a per- - compilation basis (ie. in the call to :meth:`compile`), then that takes - precedence. + object. If the same macro is defined by :meth:`define_macro` and + undefined by :meth:`undefine_macro` the last call takes precedence + (including multiple redefinitions or undefinitions). If the macro is + redefined/undefined on a per-compilation basis (ie. in the call to + :meth:`compile`), then that takes precedence. .. method:: CCompiler.add_link_object(object) @@ -473,7 +473,7 @@ list) to do the job. - .. method:: CCompiler.find_library_file(dirs, lib[, debug=``0``]) + .. method:: CCompiler.find_library_file(dirs, lib[, debug=0]) Search the specified list of directories for a static or shared library file *lib* and return the full path to that file. If *debug* is true, look for a @@ -481,7 +481,7 @@ ``None`` if *lib* wasn't found in any of the specified directories. - .. method:: CCompiler.has_function(funcname [, includes=``None``, include_dirs=``None``, libraries=``None``, library_dirs=``None``]) + .. method:: CCompiler.has_function(funcname [, includes=None, include_dirs=None, libraries=None, library_dirs=None]) Return a boolean indicating whether *funcname* is supported on the current platform. The optional arguments can be used to augment the compilation @@ -536,7 +536,7 @@ The following methods invoke stages in the build process. - .. method:: CCompiler.compile(sources[, output_dir=``None``, macros=``None``, include_dirs=``None``, debug=``0``, extra_preargs=``None``, extra_postargs=``None``, depends=``None``]) + .. method:: CCompiler.compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None]) Compile one or more source files. Generates object files (e.g. transforms a :file:`.c` file to a :file:`.o` file.) @@ -580,7 +580,7 @@ Raises :exc:`CompileError` on failure. - .. method:: CCompiler.create_static_lib(objects, output_libname[, output_dir=``None``, debug=``0``, target_lang=``None``]) + .. method:: CCompiler.create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None]) Link a bunch of stuff together to create a static library file. The "bunch of stuff" consists of the list of object files supplied as *objects*, the extra @@ -602,7 +602,7 @@ Raises :exc:`LibError` on failure. - .. method:: CCompiler.link(target_desc, objects, output_filename[, output_dir=``None``, libraries=``None``, library_dirs=``None``, runtime_library_dirs=``None``, export_symbols=``None``, debug=``0``, extra_preargs=``None``, extra_postargs=``None``, build_temp=``None``, target_lang=``None``]) + .. method:: CCompiler.link(target_desc, objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None]) Link a bunch of stuff together to create an executable or shared library file. @@ -644,28 +644,28 @@ Raises :exc:`LinkError` on failure. - .. method:: CCompiler.link_executable(objects, output_progname[, output_dir=``None``, libraries=``None``, library_dirs=``None``, runtime_library_dirs=``None``, debug=``0``, extra_preargs=``None``, extra_postargs=``None``, target_lang=``None``]) + .. method:: CCompiler.link_executable(objects, output_progname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, target_lang=None]) Link an executable. *output_progname* is the name of the file executable, while *objects* are a list of object filenames to link in. Other arguments are as for the :meth:`link` method. - .. method:: CCompiler.link_shared_lib(objects, output_libname[, output_dir=``None``, libraries=``None``, library_dirs=``None``, runtime_library_dirs=``None``, export_symbols=``None``, debug=``0``, extra_preargs=``None``, extra_postargs=``None``, build_temp=``None``, target_lang=``None``]) + .. method:: CCompiler.link_shared_lib(objects, output_libname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None]) Link a shared library. *output_libname* is the name of the output library, while *objects* is a list of object filenames to link in. Other arguments are as for the :meth:`link` method. - .. method:: CCompiler.link_shared_object(objects, output_filename[, output_dir=``None``, libraries=``None``, library_dirs=``None``, runtime_library_dirs=``None``, export_symbols=``None``, debug=``0``, extra_preargs=``None``, extra_postargs=``None``, build_temp=``None``, target_lang=``None``]) + .. method:: CCompiler.link_shared_object(objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None]) Link a shared object. *output_filename* is the name of the shared object that will be created, while *objects* is a list of object filenames to link in. Other arguments are as for the :meth:`link` method. - .. method:: CCompiler.preprocess(source[, output_file=``None``, macros=``None``, include_dirs=``None``, extra_preargs=``None``, extra_postargs=``None``]) + .. method:: CCompiler.preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None]) Preprocess a single C/C++ source file, named in *source*. Output will be written to file named *output_file*, or *stdout* if *output_file* not supplied. @@ -680,14 +680,14 @@ use by the various concrete subclasses. - .. method:: CCompiler.executable_filename(basename[, strip_dir=``0``, output_dir=``''``]) + .. method:: CCompiler.executable_filename(basename[, strip_dir=0, output_dir='']) Returns the filename of the executable for the given *basename*. Typically for non-Windows platforms this is the same as the basename, while Windows will get a :file:`.exe` added. - .. method:: CCompiler.library_filename(libname[, lib_type=``'static'``, strip_dir=``0``, output_dir=``''``]) + .. method:: CCompiler.library_filename(libname[, lib_type='static', strip_dir=0, output_dir='']) Returns the filename for the given library name on the current platform. On Unix a library with *lib_type* of ``'static'`` will typically be of the form @@ -695,18 +695,18 @@ :file:`liblibname.so`. - .. method:: CCompiler.object_filenames(source_filenames[, strip_dir=``0``, output_dir=``''``]) + .. method:: CCompiler.object_filenames(source_filenames[, strip_dir=0, output_dir='']) Returns the name of the object files for the given source files. *source_filenames* should be a list of filenames. - .. method:: CCompiler.shared_object_filename(basename[, strip_dir=``0``, output_dir=``''``]) + .. method:: CCompiler.shared_object_filename(basename[, strip_dir=0, output_dir='']) Returns the name of a shared object file for the given file name *basename*. - .. method:: CCompiler.execute(func, args[, msg=``None``, level=``1``]) + .. method:: CCompiler.execute(func, args[, msg=None, level=1]) Invokes :func:`distutils.util.execute` This method invokes a Python function *func* with the given arguments *args*, after logging and taking into account @@ -719,7 +719,7 @@ the given command. XXX see also. - .. method:: CCompiler.mkpath(name[, mode=``511``]) + .. method:: CCompiler.mkpath(name[, mode=511]) Invokes :func:`distutils.dir_util.mkpath`. This creates a directory and any missing ancestor directories. XXX see also. @@ -731,7 +731,7 @@ also. - .. method:: CCompiler.announce(msg[, level=``1``]) + .. method:: CCompiler.announce(msg[, level=1]) Write a message using :func:`distutils.log.debug`. XXX see also. @@ -867,7 +867,7 @@ tarballs or zipfiles. -.. function:: make_archive(base_name, format[, root_dir=``None``, base_dir=``None``, verbose=``0``, dry_run=``0``]) +.. function:: make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0]) Create an archive file (eg. ``zip`` or ``tar``). *base_name* is the name of the file to create, minus any format-specific extension; *format* is the @@ -883,7 +883,7 @@ This should be changed to support bz2 files -.. function:: make_tarball(base_name, base_dir[, compress=``'gzip'``, verbose=``0``, dry_run=``0``]) +.. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0]) 'Create an (optional compressed) archive as a tar file from all files in and under *base_dir*. *compress* must be ``'gzip'`` (the default), ``'compress'``, @@ -898,7 +898,7 @@ This should be replaced with calls to the :mod:`tarfile` module. -.. function:: make_zipfile(base_name, base_dir[, verbose=``0``, dry_run=``0``]) +.. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0]) Create a zip file from all files in and under *base_dir*. The output zip file will be named *base_dir* + :file:`.zip`. Uses either the :mod:`zipfile` Python @@ -936,7 +936,7 @@ .. % % equivalent to a listcomp... -.. function:: newer_group(sources, target[, missing=``'error'``]) +.. function:: newer_group(sources, target[, missing='error']) Return true if *target* is out-of-date with respect to any file listed in *sources* In other words, if *target* exists and is newer than every file in @@ -961,7 +961,7 @@ directories. -.. function:: mkpath(name[, mode=``0777``, verbose=``0``, dry_run=``0``]) +.. function:: mkpath(name[, mode=0777, verbose=0, dry_run=0]) Create a directory and any missing ancestor directories. If the directory already exists (or if *name* is the empty string, which means the current @@ -972,7 +972,7 @@ directories actually created. -.. function:: create_tree(base_dir, files[, mode=``0777``, verbose=``0``, dry_run=``0``]) +.. function:: create_tree(base_dir, files[, mode=0777, verbose=0, dry_run=0]) Create all the empty directories under *base_dir* needed to put *files* there. *base_dir* is just the a name of a directory which doesn't necessarily exist @@ -982,7 +982,7 @@ :func:`mkpath`. -.. function:: copy_tree(src, dst[preserve_mode=``1``, preserve_times=``1``, preserve_symlinks=``0``, update=``0``, verbose=``0``, dry_run=``0``]) +.. function:: copy_tree(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0]) Copy an entire directory tree *src* to a new location *dst*. Both *src* and *dst* must be directory names. If *src* is not a directory, raise @@ -1002,7 +1002,7 @@ as for :func:`copy_file`. -.. function:: remove_tree(directory[verbose=``0``, dry_run=``0``]) +.. function:: remove_tree(directory[, verbose=0, dry_run=0]) Recursively remove *directory* and all files and directories underneath it. Any errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is @@ -1021,16 +1021,16 @@ This module contains some utility functions for operating on individual files. -.. function:: copy_file(src, dst[preserve_mode=``1``, preserve_times=``1``, update=``0``, link=``None``, verbose=``0``, dry_run=``0``]) +.. function:: copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0]) Copy file *src* to *dst*. If *dst* is a directory, then *src* is copied there with the same name; otherwise, it must be a filename. (If the file exists, it will be ruthlessly clobbered.) If *preserve_mode* is true (the default), the - file's mode (type and permission bits, or whatever is analogous on the current - platform) is copied. If *preserve_times* is true (the default), the last- - modified and last-access times are copied as well. If *update* is true, *src* - will only be copied if *dst* does not exist, or if *dst* does exist but is older - than *src*. + file's mode (type and permission bits, or whatever is analogous on the + current platform) is copied. If *preserve_times* is true (the default), the + last-modified and last-access times are copied as well. If *update* is true, + *src* will only be copied if *dst* does not exist, or if *dst* does exist but + is older than *src*. *link* allows you to make hard links (using :func:`os.link`) or symbolic links (using :func:`os.symlink`) instead of copying: set it to ``'hard'`` or @@ -1051,7 +1051,7 @@ .. % (not update) and (src newer than dst)). -.. function:: move_file(src, dst[verbose, dry_run]) +.. function:: move_file(src, dst[, verbose, dry_run]) Move file *src* to *dst*. If *dst* is a directory, the file will be moved into it with the same name; otherwise, *src* is just renamed to *dst*. Returns the @@ -1092,15 +1092,11 @@ Examples of returned values: -* ``linux-i586`` - -* ``linux-alpha`` - -* ``solaris-2.6-sun4u`` - -* ``irix-5.3`` - -* ``irix64-6.2`` + * ``linux-i586`` + * ``linux-alpha`` + * ``solaris-2.6-sun4u`` + * ``irix-5.3`` + * ``irix64-6.2`` For non-POSIX platforms, currently just returns ``sys.platform``. @@ -1130,9 +1126,8 @@ users can use in config files, command-line options, etc. Currently this includes: -* :envvar:`HOME` - user's home directory (Unix only) - -* :envvar:`PLAT` - description of the current platform, including hardware and + * :envvar:`HOME` - user's home directory (Unix only) + * :envvar:`PLAT` - description of the current platform, including hardware and OS (see :func:`get_platform`) @@ -1150,7 +1145,7 @@ underscore. No { } or ( ) style quoting is available. -.. function:: grok_environment_error(exc[, prefix=``'error: '``]) +.. function:: grok_environment_error(exc[, prefix='error: ']) Generate a useful error message from an :exc:`EnvironmentError` (:exc:`IOError` or :exc:`OSError`) exception object. Handles Python 1.5.1 and later styles, @@ -1173,7 +1168,7 @@ .. % Should probably be moved into the standard library. -.. function:: execute(func, args[, msg=``None``, verbose=``0``, dry_run=``0``]) +.. function:: execute(func, args[, msg=None, verbose=0, dry_run=0]) Perform some action that affects the outside world (for instance, writing to the filesystem). Such actions are special because they are disabled by the @@ -1191,18 +1186,16 @@ :exc:`ValueError` if *val* is anything else. -.. function:: byte_compile(py_files[, optimize=``0``, force=``0``, prefix=``None``, base_dir=``None``, verbose=``1``, dry_run=``0``, direct=``None``]) +.. function:: byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None]) Byte-compile a collection of Python source files to either :file:`.pyc` or :file:`.pyo` files in the same directory. *py_files* is a list of files to compile; any files that don't end in :file:`.py` are silently skipped. *optimize* must be one of the following: -* ``0`` - don't optimize (generate :file:`.pyc`) - -* ``1`` - normal optimization (like ``python -O``) - -* ``2`` - extra optimization (like ``python -OO``) + * ``0`` - don't optimize (generate :file:`.pyc`) + * ``1`` - normal optimization (like ``python -O``) + * ``2`` - extra optimization (like ``python -OO``) If *force* is true, all files are recompiled regardless of timestamps. @@ -1333,7 +1326,7 @@ later). -.. class:: FancyGetopt([option_table=``None``]) +.. class:: FancyGetopt([option_table=None]) The option_table is a list of 3-tuples: ``(long_option, short_option, help_string)`` @@ -1346,7 +1339,7 @@ The :class:`FancyGetopt` class provides the following methods: -.. method:: FancyGetopt.getopt([args=``None``, object=``None``]) +.. method:: FancyGetopt.getopt([args=None, object=None]) Parse command-line options in args. Store as attributes on *object*. @@ -1367,7 +1360,7 @@ yet. -.. method:: FancyGetopt.generate_help([header=``None``]) +.. method:: FancyGetopt.generate_help([header=None]) Generate help text (a list of strings, one per suggested line of output) from the option table for this :class:`FancyGetopt` object. @@ -1540,7 +1533,7 @@ lines, and joining lines with backslashes. -.. class:: TextFile([filename=``None``, file=``None``, **options]) +.. class:: TextFile([filename=None, file=None, **options]) This class provides a file-like object that takes care of all the things you commonly want to do when processing a text file that has some line-by-line @@ -1628,7 +1621,7 @@ filename and the current line number). - .. method:: TextFile.warn(msg[,line=``None``]) + .. method:: TextFile.warn(msg[,line=None]) Print (to stderr) a warning message tied to the current logical line in the current file. If the current logical line in the file spans multiple physical @@ -1952,12 +1945,12 @@ .. method:: Command.finalize_options() - Set final values for all the options that this command supports. This is always - called as late as possible, ie. after any option assignments from the command- - line or from other commands have been done. Thus, this is the place to to code - option dependencies: if *foo* depends on *bar*, then it is safe to set *foo* - from *bar* as long as *foo* still has the same value it was assigned in - :meth:`initialize_options`. + Set final values for all the options that this command supports. This is + always called as late as possible, ie. after any option assignments from the + command-line or from other commands have been done. Thus, this is the place + to to code option dependencies: if *foo* depends on *bar*, then it is safe to + set *foo* from *bar* as long as *foo* still has the same value it was + assigned in :meth:`initialize_options`. .. method:: Command.run() Modified: doctools/trunk/Doc-3k/extending/building.rst ============================================================================== --- doctools/trunk/Doc-3k/extending/building.rst (original) +++ doctools/trunk/Doc-3k/extending/building.rst Sun Aug 5 00:45:13 2007 @@ -47,14 +47,13 @@ :file:`demo.so` or :file:`demo.pyd`. In the :file:`setup.py`, all execution is performed by calling the ``setup`` -function. This takes a variable number of keyword arguments, of which the -example above uses only a subset. Specifically, the example specifies meta- -information to build packages, and it specifies the contents of the package. -Normally, a package will contain of addition modules, like Python source -modules, documentation, subpackages, etc. Please refer to the distutils -documentation in :ref:`distutils-index` -to learn more about the features of distutils; this section explains building -extension modules only. +function. This takes a variable number of keyword arguments, of which the +example above uses only a subset. Specifically, the example specifies +meta-information to build packages, and it specifies the contents of the +package. Normally, a package will contain of addition modules, like Python +source modules, documentation, subpackages, etc. Please refer to the distutils +documentation in :ref:`distutils-index` to learn more about the features of +distutils; this section explains building extension modules only. It is common to pre-compute arguments to :func:`setup`, to better structure the driver script. In the example above, the\ ``ext_modules`` argument to Modified: doctools/trunk/Doc-3k/extending/extending.rst ============================================================================== --- doctools/trunk/Doc-3k/extending/extending.rst (original) +++ doctools/trunk/Doc-3k/extending/extending.rst Sun Aug 5 00:45:13 2007 @@ -164,9 +164,9 @@ Every failing :cfunc:`malloc` call must be turned into an exception --- the direct caller of :cfunc:`malloc` (or :cfunc:`realloc`) must call -:cfunc:`PyErr_NoMemory` and return a failure indicator itself. All the object- -creating functions (for example, :cfunc:`PyInt_FromLong`) already do this, so -this note is only relevant to those who call :cfunc:`malloc` directly. +:cfunc:`PyErr_NoMemory` and return a failure indicator itself. All the +object-creating functions (for example, :cfunc:`PyInt_FromLong`) already do +this, so this note is only relevant to those who call :cfunc:`malloc` directly. Also note that, with the important exception of :cfunc:`PyArg_ParseTuple` and friends, functions that return an integer status usually return a positive value @@ -331,9 +331,9 @@ When embedding Python, the :cfunc:`initspam` function is not called automatically unless there's an entry in the :cdata:`_PyImport_Inittab` table. -The easiest way to handle this is to statically initialize your statically- -linked modules by directly calling :cfunc:`initspam` after the call to -:cfunc:`Py_Initialize`:: +The easiest way to handle this is to statically initialize your +statically-linked modules by directly calling :cfunc:`initspam` after the call +to :cfunc:`Py_Initialize`:: int main(int argc, char *argv[]) @@ -483,10 +483,10 @@ Py_DECREF(arglist); :cfunc:`PyEval_CallObject` returns a Python object pointer: this is the return -value of the Python function. :cfunc:`PyEval_CallObject` is "reference-count- -neutral" with respect to its arguments. In the example a new tuple was created -to serve as the argument list, which is :cfunc:`Py_DECREF`\ -ed immediately -after the call. +value of the Python function. :cfunc:`PyEval_CallObject` is +"reference-count-neutral" with respect to its arguments. In the example a new +tuple was created to serve as the argument list, which is :cfunc:`Py_DECREF`\ +-ed immediately after the call. The return value of :cfunc:`PyEval_CallObject` is "new": either it is a brand new object, or it is an existing object whose reference count has been Modified: doctools/trunk/Doc-3k/extending/newtypes.rst ============================================================================== --- doctools/trunk/Doc-3k/extending/newtypes.rst (original) +++ doctools/trunk/Doc-3k/extending/newtypes.rst Sun Aug 5 00:45:13 2007 @@ -700,10 +700,10 @@ >>> l = [n] >>> n.first = l -This is pretty silly, but it gives us an excuse to add support for the cyclic- -garbage collector to the :class:`Noddy` example. To support cyclic garbage -collection, types need to fill two slots and set a class flag that enables these -slots: +This is pretty silly, but it gives us an excuse to add support for the +cyclic-garbage collector to the :class:`Noddy` example. To support cyclic +garbage collection, types need to fill two slots and set a class flag that +enables these slots: .. literalinclude:: ../includes/noddy4.c Modified: doctools/trunk/Doc-3k/howto/advocacy.rst ============================================================================== --- doctools/trunk/Doc-3k/howto/advocacy.rst (original) +++ doctools/trunk/Doc-3k/howto/advocacy.rst Sun Aug 5 00:45:13 2007 @@ -232,9 +232,9 @@ being considered another one of Python's advantages. Most questions posted to the comp.lang.python newsgroup are quickly answered by someone. -Should you need to dig into the source code, you'll find it's clear and well- -organized, so it's not very difficult to write extensions and track down bugs -yourself. If you'd prefer to pay for support, there are companies and +Should you need to dig into the source code, you'll find it's clear and +well-organized, so it's not very difficult to write extensions and track down +bugs yourself. If you'd prefer to pay for support, there are companies and individuals who offer commercial support for Python. **Who uses Python for serious work?** Modified: doctools/trunk/Doc-3k/howto/curses.rst ============================================================================== --- doctools/trunk/Doc-3k/howto/curses.rst (original) +++ doctools/trunk/Doc-3k/howto/curses.rst Sun Aug 5 00:45:13 2007 @@ -15,36 +15,37 @@ What is curses? =============== -The curses library supplies a terminal-independent screen-painting and keyboard- -handling facility for text-based terminals; such terminals include VT100s, the -Linux console, and the simulated terminal provided by X11 programs such as xterm -and rxvt. Display terminals support various control codes to perform common -operations such as moving the cursor, scrolling the screen, and erasing areas. -Different terminals use widely differing codes, and often have their own minor -quirks. - -In a world of X displays, one might ask "why bother"? It's true that character- -cell display terminals are an obsolete technology, but there are niches in which -being able to do fancy things with them are still valuable. One is on small- -footprint or embedded Unixes that don't carry an X server. Another is for -tools like OS installers and kernel configurators that may have to run before X -is available. +The curses library supplies a terminal-independent screen-painting and +keyboard-handling facility for text-based terminals; such terminals include +VT100s, the Linux console, and the simulated terminal provided by X11 programs +such as xterm and rxvt. Display terminals support various control codes to +perform common operations such as moving the cursor, scrolling the screen, and +erasing areas. Different terminals use widely differing codes, and often have +their own minor quirks. + +In a world of X displays, one might ask "why bother"? It's true that +character-cell display terminals are an obsolete technology, but there are +niches in which being able to do fancy things with them are still valuable. One +is on small-footprint or embedded Unixes that don't carry an X server. Another +is for tools like OS installers and kernel configurators that may have to run +before X is available. The curses library hides all the details of different terminals, and provides -the programmer with an abstraction of a display, containing multiple non- -overlapping windows. The contents of a window can be changed in various ways-- -adding text, erasing it, changing its appearance--and the curses library will -automagically figure out what control codes need to be sent to the terminal to -produce the right output. +the programmer with an abstraction of a display, containing multiple +non-overlapping windows. The contents of a window can be changed in various +ways-- adding text, erasing it, changing its appearance--and the curses library +will automagically figure out what control codes need to be sent to the terminal +to produce the right output. The curses library was originally written for BSD Unix; the later System V versions of Unix from AT&T added many enhancements and new functions. BSD curses -is no longer maintained, having been replaced by ncurses, which is an open- -source implementation of the AT&T interface. If you're using an open-source -Unix such as Linux or FreeBSD, your system almost certainly uses ncurses. Since -most current commercial Unix versions are based on System V code, all the -functions described here will probably be available. The older versions of -curses carried by some proprietary Unixes may not support everything, though. +is no longer maintained, having been replaced by ncurses, which is an +open-source implementation of the AT&T interface. If you're using an +open-source Unix such as Linux or FreeBSD, your system almost certainly uses +ncurses. Since most current commercial Unix versions are based on System V +code, all the functions described here will probably be available. The older +versions of curses carried by some proprietary Unixes may not support +everything, though. No one has made a Windows port of the curses module. On a Windows platform, try the Console module written by Fredrik Lundh. The Console module provides Modified: doctools/trunk/Doc-3k/howto/doanddont.rst ============================================================================== --- doctools/trunk/Doc-3k/howto/doanddont.rst (original) +++ doctools/trunk/Doc-3k/howto/doanddont.rst Sun Aug 5 00:45:13 2007 @@ -272,8 +272,8 @@ print reduce(operator.add, nums)/len(nums) This cute little script prints the average of all numbers given on the command -line. The :func:`reduce` adds up all the numbers, and the rest is just some pre- -and postprocessing. +line. The :func:`reduce` adds up all the numbers, and the rest is just some +pre- and postprocessing. On the same note, note that :func:`float`, :func:`int` and :func:`long` all accept arguments of type string, and so are suited to parsing --- assuming you Modified: doctools/trunk/Doc-3k/howto/functional.rst ============================================================================== --- doctools/trunk/Doc-3k/howto/functional.rst (original) +++ doctools/trunk/Doc-3k/howto/functional.rst Sun Aug 5 00:45:13 2007 @@ -1035,7 +1035,7 @@ Grouping elements -''''''''''''''''' +----------------- The last function I'll discuss, ``itertools.groupby(iter, key_func=None)``, is the most complicated. ``key_func(elem)`` is a function that can compute a key Modified: doctools/trunk/Doc-3k/howto/regex.rst ============================================================================== --- doctools/trunk/Doc-3k/howto/regex.rst (original) +++ doctools/trunk/Doc-3k/howto/regex.rst Sun Aug 5 00:45:13 2007 @@ -367,9 +367,9 @@ :file:`Tools/scripts/redemo.py`, a demonstration program included with the Python distribution. It allows you to enter REs and strings, and displays whether the RE matches or fails. :file:`redemo.py` can be quite useful when -trying to debug a complicated RE. Phil Schwartz's `Kodos `_ is also an interactive tool for developing and testing -RE patterns. +trying to debug a complicated RE. Phil Schwartz's `Kodos +`_ is also an interactive tool for +developing and testing RE patterns. This HOWTO uses the standard Python interpreter for its examples. First, run the Python interpreter, import the :mod:`re` module, and compile a RE:: @@ -708,10 +708,10 @@ Matches only at the end of the string. ``\b`` - Word boundary. This is a zero-width assertion that matches only at the + Word boundary. This is a zero-width assertion that matches only at the beginning or end of a word. A word is defined as a sequence of alphanumeric - characters, so the end of a word is indicated by whitespace or a non- - alphanumeric character. + characters, so the end of a word is indicated by whitespace or a + non-alphanumeric character. The following example matches ``class`` only when it's a complete word; it won't match when it's contained inside another word. :: @@ -1057,7 +1057,7 @@ :func:`re.split` function, too. -.. method:: .split(string [, maxsplit\ ``= 0``]) +.. method:: .split(string [, maxsplit=0]) :noindex: Split *string* by the matches of the regular expression. If capturing @@ -1108,7 +1108,7 @@ which can be either a string or a function, and the string to be processed. -.. method:: .sub(replacement, string[, count\ ``= 0``]) +.. method:: .sub(replacement, string[, count=0]) :noindex: Returns the string obtained by replacing the leftmost non-overlapping @@ -1307,11 +1307,11 @@ >>> print re.match('<.*?>', s).group() -(Note that parsing HTML or XML with regular expressions is painful. Quick-and- -dirty patterns will handle common cases, but HTML and XML have special cases -that will break the obvious regular expression; by the time you've written a -regular expression that handles all of the possible cases, the patterns will be -*very* complicated. Use an HTML or XML parser module for such tasks.) +(Note that parsing HTML or XML with regular expressions is painful. +Quick-and-dirty patterns will handle common cases, but HTML and XML have special +cases that will break the obvious regular expression; by the time you've written +a regular expression that handles all of the possible cases, the patterns will +be *very* complicated. Use an HTML or XML parser module for such tasks.) Not Using re.VERBOSE @@ -1366,9 +1366,9 @@ Friedl's Mastering Regular Expressions, published by O'Reilly. Unfortunately, it exclusively concentrates on Perl and Java's flavours of regular expressions, and doesn't contain any Python material at all, so it won't be useful as a -reference for programming in Python. (The first edition covered Python's now- -removed :mod:`regex` module, which won't help you much.) Consider checking it -out from your library. +reference for programming in Python. (The first edition covered Python's +now-removed :mod:`regex` module, which won't help you much.) Consider checking +it out from your library. .. rubric:: Footnotes Modified: doctools/trunk/Doc-3k/howto/sockets.rst ============================================================================== --- doctools/trunk/Doc-3k/howto/sockets.rst (original) +++ doctools/trunk/Doc-3k/howto/sockets.rst Sun Aug 5 00:45:13 2007 @@ -29,8 +29,8 @@ better behavior and performance from a STREAM socket than anything else. I will try to clear up the mystery of what a socket is, as well as some hints on how to work with blocking and non-blocking sockets. But I'll start by talking about -blocking sockets. You'll need to know how they work before dealing with non- -blocking sockets. +blocking sockets. You'll need to know how they work before dealing with +non-blocking sockets. Part of the trouble with understanding these things is that "socket" can mean a number of subtly different things, depending on context. So first, let's make a @@ -361,12 +361,12 @@ empty) of the corresponding list you passed in. And if you put a socket in more than one input list, it will only be (at most) in one output list. -If a socket is in the output readable list, you can be as-close-to-certain-as- -we-ever-get-in-this-business that a ``recv`` on that socket will return -*something*. Same idea for the writable list. You'll be able to send -*something*. Maybe not all you want to, but *something* is better than nothing. -(Actually, any reasonably healthy socket will return as writable - it just means -outbound network buffer space is available.) +If a socket is in the output readable list, you can be +as-close-to-certain-as-we-ever-get-in-this-business that a ``recv`` on that +socket will return *something*. Same idea for the writable list. You'll be able +to send *something*. Maybe not all you want to, but *something* is better than +nothing. (Actually, any reasonably healthy socket will return as writable - it +just means outbound network buffer space is available.) If you have a "server" socket, put it in the potential_readers list. If it comes out in the readable list, your ``accept`` will (almost certainly) work. If you Modified: doctools/trunk/Doc-3k/howto/urllib2.rst ============================================================================== --- doctools/trunk/Doc-3k/howto/urllib2.rst (original) +++ doctools/trunk/Doc-3k/howto/urllib2.rst Sun Aug 5 00:45:13 2007 @@ -432,7 +432,7 @@ ==================== To illustrate creating and installing a handler we will use the -``HTTPBasicAuthHandler``. For a more detailed discussion of this subject - +``HTTPBasicAuthHandler``. For a more detailed discussion of this subject -- including an explanation of how Basic Authentication works - see the `Basic Authentication Tutorial `_. Modified: doctools/trunk/Doc-3k/install/index.rst ============================================================================== --- doctools/trunk/Doc-3k/install/index.rst (original) +++ doctools/trunk/Doc-3k/install/index.rst Sun Aug 5 00:45:13 2007 @@ -263,7 +263,7 @@ can find out what your Python installation uses for :file:`{prefix}` and :file:`{exec-prefix}` by running Python in interactive mode and typing a few simple commands. Under Unix, just type ``python`` at the shell prompt. Under -Windows, choose :menuselection:`Start --> Programs --> Python |version|--> +Windows, choose :menuselection:`Start --> Programs --> Python X.Y --> Python (command line)`. Once the interpreter is started, you type Python code at the prompt. For example, on my Linux system, I type the three Python statements shown below, and get the output as shown, to find out my @@ -506,8 +506,8 @@ If you want to define an entire installation scheme, you just have to supply all of the installation directory options. The recommended way to do this is to -supply relative paths; for example, if you want to maintain all Python module- -related files under :file:`python` in your home directory, and you want a +supply relative paths; for example, if you want to maintain all Python +module-related files under :file:`python` in your home directory, and you want a separate directory for each platform that you use your home directory from, you might define the following installation scheme:: @@ -645,8 +645,8 @@ There are two environment variables that can modify ``sys.path``. :envvar:`PYTHONHOME` sets an alternate value for the prefix of the Python installation. For example, if :envvar:`PYTHONHOME` is set to ``/www/python``, -the search path will be set to ``['', '/www/python/lib/python|version|/', -'/www/python/lib/python|version|/plat-linux2', ...]``. +the search path will be set to ``['', '/www/python/lib/pythonX.Y/', +'/www/python/lib/pythonX.Y/plat-linux2', ...]``. The :envvar:`PYTHONPATH` variable can be set to a list of paths that will be added to the beginning of ``sys.path``. For example, if :envvar:`PYTHONPATH` is @@ -812,8 +812,8 @@ Compiling a Python extension written in C or C++ will sometimes require specifying custom flags for the compiler and linker in order to use a particular library or produce a special kind of object code. This is especially true if the -extension hasn't been tested on your platform, or if you're trying to cross- -compile Python. +extension hasn't been tested on your platform, or if you're trying to +cross-compile Python. In the most general case, the extension author might have foreseen that compiling the extensions would be complicated, and provided a :file:`Setup` file Modified: doctools/trunk/Doc-3k/library/_winreg.rst ============================================================================== --- doctools/trunk/Doc-3k/library/_winreg.rst (original) +++ doctools/trunk/Doc-3k/library/_winreg.rst Sun Aug 5 00:45:13 2007 @@ -178,7 +178,7 @@ :const:`HKEY_LOCAL_MACHINE` tree. This may or may not be true. -.. function:: OpenKey(key, sub_key[, res\ ``= 0``][, sam\ ``= KEY_READ``]) +.. function:: OpenKey(key, sub_key[, res=0][, sam=KEY_READ]) Opens the specified key, returning a :dfn:`handle object` Modified: doctools/trunk/Doc-3k/library/asyncore.rst ============================================================================== --- doctools/trunk/Doc-3k/library/asyncore.rst (original) +++ doctools/trunk/Doc-3k/library/asyncore.rst Sun Aug 5 00:45:13 2007 @@ -23,15 +23,15 @@ are probably what you really need. Network servers are rarely processor bound, however. -If your operating system supports the :cfunc:`select` system call in its I/O -library (and nearly all do), then you can use it to juggle multiple -communication channels at once; doing other work while your I/O is taking place -in the "background." Although this strategy can seem strange and complex, -especially at first, it is in many ways easier to understand and control than -multi-threaded programming. The :mod:`asyncore` module solves many of the -difficult problems for you, making the task of building sophisticated high- -performance network servers and clients a snap. For "conversational" -applications and protocols the companion :mod:`asynchat` module is invaluable. +If your operating system supports the :cfunc:`select` system call in its I/O +library (and nearly all do), then you can use it to juggle multiple +communication channels at once; doing other work while your I/O is taking place +in the "background." Although this strategy can seem strange and complex, +especially at first, it is in many ways easier to understand and control than +multi-threaded programming. The :mod:`asyncore` module solves many of the +difficult problems for you, making the task of building sophisticated +high-performance network servers and clients a snap. For "conversational" +applications and protocols the companion :mod:`asynchat` module is invaluable. The basic idea behind both modules is to create one or more network *channels*, instances of class :class:`asyncore.dispatcher` and Modified: doctools/trunk/Doc-3k/library/binascii.rst ============================================================================== --- doctools/trunk/Doc-3k/library/binascii.rst (original) +++ doctools/trunk/Doc-3k/library/binascii.rst Sun Aug 5 00:45:13 2007 @@ -16,8 +16,8 @@ binary and various ASCII-encoded binary representations. Normally, you will not use these functions directly but use wrapper modules like :mod:`uu`, :mod:`base64`, or :mod:`binhex` instead. The :mod:`binascii` module contains -low-level functions written in C for greater speed that are used by the higher- -level modules. +low-level functions written in C for greater speed that are used by the +higher-level modules. The :mod:`binascii` module defines the following functions: Modified: doctools/trunk/Doc-3k/library/bz2.rst ============================================================================== --- doctools/trunk/Doc-3k/library/bz2.rst (original) +++ doctools/trunk/Doc-3k/library/bz2.rst Sun Aug 5 00:45:13 2007 @@ -74,8 +74,8 @@ .. method:: BZ2File.readline([size]) - Return the next line from the file, as a string, retaining newline. A non- - negative *size* argument limits the maximum number of bytes to return (an + Return the next line from the file, as a string, retaining newline. A + non-negative *size* argument limits the maximum number of bytes to return (an incomplete line may be returned then). Return an empty string at EOF. Modified: doctools/trunk/Doc-3k/library/cgi.rst ============================================================================== --- doctools/trunk/Doc-3k/library/cgi.rst (original) +++ doctools/trunk/Doc-3k/library/cgi.rst Sun Aug 5 00:45:13 2007 @@ -552,7 +552,7 @@ .. rubric:: Footnotes .. [#] Note that some recent versions of the HTML specification do state what order the - field values should be supplied in, but knowing whether a request was received - from a conforming browser, or even from a browser at all, is tedious and error- - prone. + field values should be supplied in, but knowing whether a request was + received from a conforming browser, or even from a browser at all, is tedious + and error-prone. Modified: doctools/trunk/Doc-3k/library/chunk.rst ============================================================================== --- doctools/trunk/Doc-3k/library/chunk.rst (original) +++ doctools/trunk/Doc-3k/library/chunk.rst Sun Aug 5 00:45:13 2007 @@ -53,18 +53,18 @@ .. class:: Chunk(file[, align, bigendian, inclheader]) - 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 only - method that is needed is :meth:`read`. If the methods :meth:`seek` and - :meth:`tell` are present and don't raise an exception, they are also used. If - these methods are present and raise an exception, they are expected to not have - altered the object. If the optional argument *align* is true, chunks are - assumed to be aligned on 2-byte boundaries. If *align* is false, no alignment - is assumed. The default value is true. If the optional argument *bigendian* is - false, the chunk size is assumed to be in little-endian order. This is needed - for WAVE audio files. The default value is true. If the optional argument - *inclheader* is true, the size given in the chunk header includes the size of - the header. The default value is 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 + only method that is needed is :meth:`read`. If the methods :meth:`seek` and + :meth:`tell` are present and don't raise an exception, they are also used. + If these methods are present and raise an exception, they are expected to not + have altered the object. If the optional argument *align* is true, chunks + are assumed to be aligned on 2-byte boundaries. If *align* is false, no + alignment is assumed. The default value is true. If the optional argument + *bigendian* is false, the chunk size is assumed to be in little-endian order. + This is needed for WAVE audio files. The default value is true. If the + optional argument *inclheader* is true, the size given in the chunk header + includes the size of the header. The default value is false. A :class:`Chunk` object supports the following methods: Modified: doctools/trunk/Doc-3k/library/cmath.rst ============================================================================== --- doctools/trunk/Doc-3k/library/cmath.rst (original) +++ doctools/trunk/Doc-3k/library/cmath.rst Sun Aug 5 00:45:13 2007 @@ -7,12 +7,12 @@ This module is always available. It provides access to mathematical functions -for complex numbers. The functions in this module accept integers, floating- -point numbers or complex numbers as arguments. They will also accept any Python -object that has either a :meth:`__complex__` or a :meth:`__float__` method: -these methods are used to convert the object to a complex or floating-point -number, respectively, and the function is then applied to the result of the -conversion. +for complex numbers. The functions in this module accept integers, +floating-point numbers or complex numbers as arguments. They will also accept +any Python object that has either a :meth:`__complex__` or a :meth:`__float__` +method: these methods are used to convert the object to a complex or +floating-point number, respectively, and the function is then applied to the +result of the conversion. The functions are: Modified: doctools/trunk/Doc-3k/library/code.rst ============================================================================== --- doctools/trunk/Doc-3k/library/code.rst (original) +++ doctools/trunk/Doc-3k/library/code.rst Sun Aug 5 00:45:13 2007 @@ -73,15 +73,15 @@ :func:`compile_command`; the default for *filename* is ``''``, and for *symbol* is ``'single'``. One several things can happen: -* The input is incorrect; :func:`compile_command` raised an exception + * The input is incorrect; :func:`compile_command` raised an exception (:exc:`SyntaxError` or :exc:`OverflowError`). A syntax traceback will be printed by calling the :meth:`showsyntaxerror` method. :meth:`runsource` returns ``False``. -* The input is incomplete, and more input is required; :func:`compile_command` + * The input is incomplete, and more input is required; :func:`compile_command` returned ``None``. :meth:`runsource` returns ``True``. -* The input is complete; :func:`compile_command` returned a code object. The + * The input is complete; :func:`compile_command` returned a code object. The code is executed by calling the :meth:`runcode` (which also handles run-time exceptions, except for :exc:`SystemExit`). :meth:`runsource` returns ``False``. Modified: doctools/trunk/Doc-3k/library/codecs.rst ============================================================================== --- doctools/trunk/Doc-3k/library/codecs.rst (original) +++ doctools/trunk/Doc-3k/library/codecs.rst Sun Aug 5 00:45:13 2007 @@ -30,19 +30,19 @@ argument, the encoding name in all lower case letters, and return a :class:`CodecInfo` object having the following attributes: -* ``name`` The name of the encoding; + * ``name`` The name of the encoding; -* ``encoder`` The stateless encoding function; + * ``encoder`` The stateless encoding function; -* ``decoder`` The stateless decoding function; + * ``decoder`` The stateless decoding function; -* ``incrementalencoder`` An incremental encoder class or factory function; + * ``incrementalencoder`` An incremental encoder class or factory function; -* ``incrementaldecoder`` An incremental decoder class or factory function; + * ``incrementaldecoder`` An incremental decoder class or factory function; -* ``streamwriter`` A stream writer class or factory function; + * ``streamwriter`` A stream writer class or factory function; -* ``streamreader`` A stream reader class or factory function. + * ``streamreader`` A stream reader class or factory function. The various functions or classes take the following arguments: @@ -408,15 +408,15 @@ The :class:`IncrementalEncoder` may implement different error handling schemes by providing the *errors* keyword argument. These parameters are predefined: -* ``'strict'`` Raise :exc:`ValueError` (or a subclass); this is the default. + * ``'strict'`` Raise :exc:`ValueError` (or a subclass); this is the default. -* ``'ignore'`` Ignore the character and continue with the next. + * ``'ignore'`` Ignore the character and continue with the next. -* ``'replace'`` Replace with a suitable replacement character + * ``'replace'`` Replace with a suitable replacement character -* ``'xmlcharrefreplace'`` Replace with the appropriate XML character reference + * ``'xmlcharrefreplace'`` Replace with the appropriate XML character reference -* ``'backslashreplace'`` Replace with backslashed escape sequences. + * ``'backslashreplace'`` Replace with backslashed escape sequences. The *errors* argument will be assigned to an attribute of the same name. Assigning to this attribute makes it possible to switch between different error @@ -479,11 +479,11 @@ The :class:`IncrementalDecoder` may implement different error handling schemes by providing the *errors* keyword argument. These parameters are predefined: -* ``'strict'`` Raise :exc:`ValueError` (or a subclass); this is the default. + * ``'strict'`` Raise :exc:`ValueError` (or a subclass); this is the default. -* ``'ignore'`` Ignore the character and continue with the next. + * ``'ignore'`` Ignore the character and continue with the next. -* ``'replace'`` Replace with a suitable replacement character. + * ``'replace'`` Replace with a suitable replacement character. The *errors* argument will be assigned to an attribute of the same name. Assigning to this attribute makes it possible to switch between different error @@ -562,15 +562,15 @@ The :class:`StreamWriter` may implement different error handling schemes by providing the *errors* keyword argument. These parameters are predefined: -* ``'strict'`` Raise :exc:`ValueError` (or a subclass); this is the default. + * ``'strict'`` Raise :exc:`ValueError` (or a subclass); this is the default. -* ``'ignore'`` Ignore the character and continue with the next. + * ``'ignore'`` Ignore the character and continue with the next. -* ``'replace'`` Replace with a suitable replacement character + * ``'replace'`` Replace with a suitable replacement character -* ``'xmlcharrefreplace'`` Replace with the appropriate XML character reference + * ``'xmlcharrefreplace'`` Replace with the appropriate XML character reference -* ``'backslashreplace'`` Replace with backslashed escape sequences. + * ``'backslashreplace'`` Replace with backslashed escape sequences. The *errors* argument will be assigned to an attribute of the same name. Assigning to this attribute makes it possible to switch between different error @@ -626,11 +626,11 @@ The :class:`StreamReader` may implement different error handling schemes by providing the *errors* keyword argument. These parameters are defined: -* ``'strict'`` Raise :exc:`ValueError` (or a subclass); this is the default. + * ``'strict'`` Raise :exc:`ValueError` (or a subclass); this is the default. -* ``'ignore'`` Ignore the character and continue with the next. + * ``'ignore'`` Ignore the character and continue with the next. -* ``'replace'`` Replace with a suitable replacement character. + * ``'replace'`` Replace with a suitable replacement character. The *errors* argument will be assigned to an attribute of the same name. Assigning to this attribute makes it possible to switch between different error Modified: doctools/trunk/Doc-3k/library/codeop.rst ============================================================================== --- doctools/trunk/Doc-3k/library/codeop.rst (original) +++ doctools/trunk/Doc-3k/library/codeop.rst Sun Aug 5 00:45:13 2007 @@ -10,10 +10,11 @@ .. % LaTeXed from excellent doc-string. -The :mod:`codeop` module provides utilities upon which the Python read-eval- -print loop can be emulated, as is done in the :mod:`code` module. As a result, -you probably don't want to use the module directly; if you want to include such -a loop in your program you probably want to use the :mod:`code` module instead. +The :mod:`codeop` module provides utilities upon which the Python +read-eval-print loop can be emulated, as is done in the :mod:`code` module. As +a result, you probably don't want to use the module directly; if you want to +include such a loop in your program you probably want to use the :mod:`code` +module instead. There are two parts to this job: Modified: doctools/trunk/Doc-3k/library/cookie.rst ============================================================================== --- doctools/trunk/Doc-3k/library/cookie.rst (original) +++ doctools/trunk/Doc-3k/library/cookie.rst Sun Aug 5 00:45:13 2007 @@ -145,19 +145,13 @@ Morsels are dictionary-like objects, whose set of keys is constant --- the valid :rfc:`2109` attributes, which are -* ``expires`` - -* ``path`` - -* ``comment`` - -* ``domain`` - -* ``max-age`` - -* ``secure`` - -* ``version`` + * ``expires`` + * ``path`` + * ``comment`` + * ``domain`` + * ``max-age`` + * ``secure`` + * ``version`` The keys are case-insensitive. Modified: doctools/trunk/Doc-3k/library/cookielib.rst ============================================================================== --- doctools/trunk/Doc-3k/library/cookielib.rst (original) +++ doctools/trunk/Doc-3k/library/cookielib.rst Sun Aug 5 00:45:13 2007 @@ -94,10 +94,10 @@ received in a :mailheader:`Set-Cookie` header with a version cookie-attribute of 1) are treated according to the RFC 2965 rules. However, if RFC 2965 handling is turned off or :attr:`rfc2109_as_netscape` is True, RFC 2109 cookies are - 'downgraded' by the :class:`CookieJar` instance to Netscape cookies, by setting - the :attr:`version` attribute of the :class:`Cookie` instance to 0. - :class:`DefaultCookiePolicy` also provides some parameters to allow some fine- - tuning of policy. + 'downgraded' by the :class:`CookieJar` instance to Netscape cookies, by + setting the :attr:`version` attribute of the :class:`Cookie` instance to 0. + :class:`DefaultCookiePolicy` also provides some parameters to allow some + fine-tuning of policy. .. class:: Cookie() @@ -320,8 +320,8 @@ .. note:: - This loses information about RFC 2965 cookies, and also about newer or non- - standard cookie-attributes such as ``port``. + This loses information about RFC 2965 cookies, and also about newer or + non-standard cookie-attributes such as ``port``. .. warning:: @@ -608,9 +608,10 @@ :class:`Cookie` instances have Python attributes roughly corresponding to the standard cookie-attributes specified in the various cookie standards. The correspondence is not one-to-one, because there are complicated rules for -assigning default values, because the ``max-age`` and ``expires`` cookie- -attributes contain equivalent information, and because RFC 2109 cookies may be -'downgraded' by :mod:`cookielib` from version 1 to version 0 (Netscape) cookies. +assigning default values, because the ``max-age`` and ``expires`` +cookie-attributes contain equivalent information, and because RFC 2109 cookies +may be 'downgraded' by :mod:`cookielib` from version 1 to version 0 (Netscape) +cookies. Assignment to these attributes should not be necessary other than in rare circumstances in a :class:`CookiePolicy` method. The class does not enforce @@ -676,11 +677,11 @@ .. attribute:: Cookie.rfc2109 - True if this cookie was received as an RFC 2109 cookie (ie. the cookie arrived - in a :mailheader:`Set-Cookie` header, and the value of the Version cookie- - attribute in that header was 1). This attribute is provided because - :mod:`cookielib` may 'downgrade' RFC 2109 cookies to Netscape cookies, in which - case :attr:`version` is 0. + True if this cookie was received as an RFC 2109 cookie (ie. the cookie + arrived in a :mailheader:`Set-Cookie` header, and the value of the Version + cookie-attribute in that header was 1). This attribute is provided because + :mod:`cookielib` may 'downgrade' RFC 2109 cookies to Netscape cookies, in + which case :attr:`version` is 0. .. versionadded:: 2.5 Modified: doctools/trunk/Doc-3k/library/csv.rst ============================================================================== --- doctools/trunk/Doc-3k/library/csv.rst (original) +++ doctools/trunk/Doc-3k/library/csv.rst Sun Aug 5 00:45:13 2007 @@ -59,7 +59,7 @@ The :mod:`csv` module defines the following functions: -.. function:: reader(csvfile[, dialect=``'excel'``][, fmtparam]) +.. function:: reader(csvfile[, dialect='excel'][, fmtparam]) Return a reader object which will iterate over lines in the given *csvfile*. *csvfile* can be any object which supports the iterator protocol and returns a @@ -87,7 +87,7 @@ be split into lines in a manner which preserves the newline characters. -.. function:: writer(csvfile[, dialect=``'excel'``][, fmtparam]) +.. function:: writer(csvfile[, dialect='excel'][, fmtparam]) Return a writer object responsible for converting the user's data into delimited strings on the given file-like object. *csvfile* can be any object with a @@ -143,7 +143,7 @@ The :mod:`csv` module defines the following classes: -.. class:: DictReader(csvfile[, fieldnames=:const:`None`,[, restkey=:const:`None`[, restval=:const:`None`[, dialect=``'excel'``[, *args, **kwds]]]]]) +.. class:: DictReader(csvfile[, fieldnames=:const:None,[, restkey=:const:None[, restval=None[, dialect='excel'[, *args, **kwds]]]]]) Create an object which operates like a regular reader but maps the information read into a dict whose keys are given by the optional *fieldnames* parameter. @@ -157,7 +157,7 @@ arguments are passed to the underlying :class:`reader` instance. -.. class:: DictWriter(csvfile, fieldnames[, restval=""[, extrasaction=``'raise'``[, dialect=``'excel'``[, *args, **kwds]]]]) +.. class:: DictWriter(csvfile, fieldnames[, restval=''[, extrasaction='raise'[, dialect='excel'[, *args, **kwds]]]]) Create an object which operates like a regular writer but maps dictionaries onto output rows. The *fieldnames* parameter identifies the order in which values in @@ -202,7 +202,7 @@ The :class:`Sniffer` class provides two methods: -.. method:: Sniffer.sniff(sample[,delimiters=None]) +.. method:: Sniffer.sniff(sample[, delimiters=None]) Analyze the given *sample* and return a :class:`Dialect` subclass reflecting the parameters found. If the optional *delimiters* parameter is given, it is Modified: doctools/trunk/Doc-3k/library/ctypes.rst ============================================================================== --- doctools/trunk/Doc-3k/library/ctypes.rst (original) +++ doctools/trunk/Doc-3k/library/ctypes.rst Sun Aug 5 00:45:13 2007 @@ -1910,9 +1910,9 @@ .. function:: string_at(address[, size]) - This function returns the string starting at memory address address. If size is - specified, it is used as size, otherwise the string is assumed to be zero- - terminated. + This function returns the string starting at memory address address. If size + is specified, it is used as size, otherwise the string is assumed to be + zero-terminated. .. function:: WinError(code=None, descr=None) @@ -1928,8 +1928,8 @@ This function returns the wide character string starting at memory address ``address`` as unicode string. If ``size`` is specified, it is used as the - number of characters of the string, otherwise the string is assumed to be zero- - terminated. + number of characters of the string, otherwise the string is assumed to be + zero-terminated. .. _ctypes-data-types: @@ -2198,9 +2198,9 @@ .. class:: c_wchar_p - Represents the C ``wchar_t *`` datatype, which must be a pointer to a zero- - terminated wide character string. The constructor accepts an integer address, or - a string. + Represents the C ``wchar_t *`` datatype, which must be a pointer to a + zero-terminated wide character string. The constructor accepts an integer + address, or a string. .. class:: c_bool Modified: doctools/trunk/Doc-3k/library/curses.rst ============================================================================== --- doctools/trunk/Doc-3k/library/curses.rst (original) +++ doctools/trunk/Doc-3k/library/curses.rst Sun Aug 5 00:45:13 2007 @@ -11,8 +11,8 @@ .. versionchanged:: 1.6 Added support for the ``ncurses`` library and converted to a package. -The :mod:`curses` module provides an interface to the curses library, the de- -facto standard for portable advanced terminal handling. +The :mod:`curses` module provides an interface to the curses library, the +de-facto standard for portable advanced terminal handling. While curses is most widely used in the Unix environment, versions are available for DOS, OS/2, and possibly other systems as well. This extension module is @@ -641,10 +641,10 @@ attributes *attr*. The change is then applied to every character position in that window: -* The attribute of every character in the window is changed to the new + * The attribute of every character in the window is changed to the new background attribute. -* Wherever the former background character appears, it is changed to the new + * Wherever the former background character appears, it is changed to the new background character. @@ -1023,7 +1023,7 @@ *sminrow*, or *smincol* are treated as if they were zero. -.. method:: window.scroll([lines\ ``= 1``]) +.. method:: window.scroll([lines=1]) Scroll the screen or scrolling region upward by *lines* lines. @@ -1526,8 +1526,8 @@ The :mod:`curses.textpad` module provides a :class:`Textbox` class that handles elementary text editing in a curses window, supporting a set of keybindings resembling those of Emacs (thus, also of Netscape Navigator, BBedit 6.x, -FrameMaker, and many other programs). The module also provides a rectangle- -drawing function useful for framing text boxes or for other purposes. +FrameMaker, and many other programs). The module also provides a +rectangle-drawing function useful for framing text boxes or for other purposes. The module :mod:`curses.textpad` defines the following function: Modified: doctools/trunk/Doc-3k/library/datetime.rst ============================================================================== --- doctools/trunk/Doc-3k/library/datetime.rst (original) +++ doctools/trunk/Doc-3k/library/datetime.rst Sun Aug 5 00:45:13 2007 @@ -139,22 +139,17 @@ Only *days*, *seconds* and *microseconds* are stored internally. Arguments are converted to those units: -* A millisecond is converted to 1000 microseconds. - -* A minute is converted to 60 seconds. - -* An hour is converted to 3600 seconds. - -* A week is converted to 7 days. + * A millisecond is converted to 1000 microseconds. + * A minute is converted to 60 seconds. + * An hour is converted to 3600 seconds. + * A week is converted to 7 days. and days, seconds and microseconds are then normalized so that the representation is unique, with -* ``0 <= microseconds < 1000000`` - -* ``0 <= seconds < 3600*24`` (the number of seconds in one day) - -* ``-999999999 <= days <= 999999999`` + * ``0 <= microseconds < 1000000`` + * ``0 <= seconds < 3600*24`` (the number of seconds in one day) + * ``-999999999 <= days <= 999999999`` If any argument is a float and there are fractional microseconds, the fractional microseconds left over from all arguments are combined and their sum is rounded @@ -291,11 +286,9 @@ All arguments are required. Arguments may be ints or longs, in the following ranges: -* ``MINYEAR <= year <= MAXYEAR`` - -* ``1 <= month <= 12`` - -* ``1 <= day <= number of days in the given month and year`` + * ``MINYEAR <= year <= MAXYEAR`` + * ``1 <= month <= 12`` + * ``1 <= day <= number of days in the given month and year`` If an argument outside those ranges is given, :exc:`ValueError` is raised. @@ -514,19 +507,13 @@ instance of a :class:`tzinfo` subclass. The remaining arguments may be ints or longs, in the following ranges: -* ``MINYEAR <= year <= MAXYEAR`` - -* ``1 <= month <= 12`` - -* ``1 <= day <= number of days in the given month and year`` - -* ``0 <= hour < 24`` - -* ``0 <= minute < 60`` - -* ``0 <= second < 60`` - -* ``0 <= microsecond < 1000000`` + * ``MINYEAR <= year <= MAXYEAR`` + * ``1 <= month <= 12`` + * ``1 <= day <= number of days in the given month and year`` + * ``0 <= hour < 24`` + * ``0 <= minute < 60`` + * ``0 <= second < 60`` + * ``0 <= microsecond < 1000000`` If an argument outside those ranges is given, :exc:`ValueError` is raised. @@ -894,13 +881,14 @@ .. method:: datetime.isoformat([sep]) - Return a string representing the date and time in ISO 8601 format, YYYY-MM- - DDTHH:MM:SS.mmmmmm or, if :attr:`microsecond` is 0, YYYY-MM-DDTHH:MM:SS - - If :meth:`utcoffset` does not return ``None``, a 6-character string is appended, - giving the UTC offset in (signed) hours and minutes: YYYY-MM- - DDTHH:MM:SS.mmmmmm+HH:MM or, if :attr:`microsecond` is 0 YYYY-MM- - DDTHH:MM:SS+HH:MM + Return a string representing the date and time in ISO 8601 format, + YYYY-MM-DDTHH:MM:SS.mmmmmm or, if :attr:`microsecond` is 0, + YYYY-MM-DDTHH:MM:SS + + If :meth:`utcoffset` does not return ``None``, a 6-character string is + appended, giving the UTC offset in (signed) hours and minutes: + YYYY-MM-DDTHH:MM:SS.mmmmmm+HH:MM or, if :attr:`microsecond` is 0 + YYYY-MM-DDTHH:MM:SS+HH:MM The optional argument *sep* (default ``'T'``) is a one-character separator, placed between the date and time portions of the result. For example, :: @@ -949,13 +937,10 @@ :class:`tzinfo` subclass. The remaining arguments may be ints or longs, in the following ranges: -* ``0 <= hour < 24`` - -* ``0 <= minute < 60`` - -* ``0 <= second < 60`` - -* ``0 <= microsecond < 1000000``. + * ``0 <= hour < 24`` + * ``0 <= minute < 60`` + * ``0 <= second < 60`` + * ``0 <= microsecond < 1000000``. If an argument outside those ranges is given, :exc:`ValueError` is raised. All default to ``0`` except *tzinfo*, which defaults to :const:`None`. Modified: doctools/trunk/Doc-3k/library/decimal.rst ============================================================================== --- doctools/trunk/Doc-3k/library/decimal.rst (original) +++ doctools/trunk/Doc-3k/library/decimal.rst Sun Aug 5 00:45:13 2007 @@ -509,19 +509,13 @@ The *rounding* option is one of: -* :const:`ROUND_CEILING` (towards :const:`Infinity`), - -* :const:`ROUND_DOWN` (towards zero), - -* :const:`ROUND_FLOOR` (towards :const:`-Infinity`), - -* :const:`ROUND_HALF_DOWN` (to nearest with ties going towards zero), - -* :const:`ROUND_HALF_EVEN` (to nearest with ties going to nearest even integer), - -* :const:`ROUND_HALF_UP` (to nearest with ties going away from zero), or - -* :const:`ROUND_UP` (away from zero). + * :const:`ROUND_CEILING` (towards :const:`Infinity`), + * :const:`ROUND_DOWN` (towards zero), + * :const:`ROUND_FLOOR` (towards :const:`-Infinity`), + * :const:`ROUND_HALF_DOWN` (to nearest with ties going towards zero), + * :const:`ROUND_HALF_EVEN` (to nearest with ties going to nearest even integer), + * :const:`ROUND_HALF_UP` (to nearest with ties going away from zero), or + * :const:`ROUND_UP` (away from zero). The *traps* and *flags* fields list any signals to be set. Generally, new contexts should only set traps and leave the flags clear. @@ -1260,10 +1254,10 @@ Q. Within a complex calculation, how can I make sure that I haven't gotten a spurious result because of insufficient precision or rounding anomalies. -A. The decimal module makes it easy to test results. A best practice is to re- -run calculations using greater precision and with various rounding modes. Widely -differing results indicate insufficient precision, rounding mode issues, ill- -conditioned inputs, or a numerically unstable algorithm. +A. The decimal module makes it easy to test results. A best practice is to +re-run calculations using greater precision and with various rounding modes. +Widely differing results indicate insufficient precision, rounding mode issues, +ill-conditioned inputs, or a numerically unstable algorithm. Q. I noticed that context precision is applied to the results of operations but not to the inputs. Is there anything to watch out for when mixing values of Modified: doctools/trunk/Doc-3k/library/difflib.rst ============================================================================== --- doctools/trunk/Doc-3k/library/difflib.rst (original) +++ doctools/trunk/Doc-3k/library/difflib.rst Sun Aug 5 00:45:13 2007 @@ -34,10 +34,10 @@ .. class:: Differ - This is a class for comparing sequences of lines of text, and producing human- - readable differences or deltas. Differ uses :class:`SequenceMatcher` both to - compare sequences of lines, and to compare sequences of characters within - similar (near-matching) lines. + This is a class for comparing sequences of lines of text, and producing + human-readable differences or deltas. Differ uses :class:`SequenceMatcher` + both to compare sequences of lines, and to compare sequences of characters + within similar (near-matching) lines. Each line of a :class:`Differ` delta begins with a two-letter code: Modified: doctools/trunk/Doc-3k/library/dis.rst ============================================================================== --- doctools/trunk/Doc-3k/library/dis.rst (original) +++ doctools/trunk/Doc-3k/library/dis.rst Sun Aug 5 00:45:13 2007 @@ -50,19 +50,13 @@ Disassembles a code object, indicating the last instruction if *lasti* was provided. The output is divided in the following columns: -#. the line number, for the first instruction of each line - -#. the current instruction, indicated as ``-->``, - -#. a labelled instruction, indicated with ``>>``, - -#. the address of the instruction, - -#. the operation code name, - -#. operation parameters, and - -#. interpretation of the parameters in parentheses. + #. the line number, for the first instruction of each line + #. the current instruction, indicated as ``-->``, + #. a labelled instruction, indicated with ``>>``, + #. the address of the instruction, + #. the operation code name, + #. operation parameters, and + #. interpretation of the parameters in parentheses. The parameter interpretation recognizes local and global variable names, constant values, branch targets, and compare operators. @@ -499,8 +493,8 @@ .. opcode:: UNPACK_SEQUENCE (count) - Unpacks TOS into *count* individual values, which are put onto the stack right- - to-left. + Unpacks TOS into *count* individual values, which are put onto the stack + right-to-left. .. % \begin{opcodedesc}{UNPACK_LIST}{count} .. % This opcode is obsolete. Modified: doctools/trunk/Doc-3k/library/dl.rst ============================================================================== --- doctools/trunk/Doc-3k/library/dl.rst (original) +++ doctools/trunk/Doc-3k/library/dl.rst Sun Aug 5 00:45:13 2007 @@ -28,7 +28,7 @@ The :mod:`dl` module defines the following function: -.. function:: open(name[, mode\ ``= RTLD_LAZY``]) +.. function:: open(name[, mode=RTLD_LAZY]) Open a shared object file, and return a handle. Mode signifies late binding (:const:`RTLD_LAZY`) or immediate binding (:const:`RTLD_NOW`). Default is Modified: doctools/trunk/Doc-3k/library/doctest.rst ============================================================================== --- doctools/trunk/Doc-3k/library/doctest.rst (original) +++ doctools/trunk/Doc-3k/library/doctest.rst Sun Aug 5 00:45:13 2007 @@ -435,10 +435,10 @@ are ignored by doctest. The traceback stack is typically omitted, or copied verbatim from an interactive session. -The traceback stack is followed by the most interesting part: the line(s) +The traceback stack is followed by the most interesting part: the line(s) containing the exception type and detail. This is usually the last line of a -traceback, but can extend across multiple lines if the exception has a multi- -line detail:: +traceback, but can extend across multiple lines if the exception has a +multi-line detail:: >>> raise ValueError('multi\n line\ndetail') Traceback (most recent call last): @@ -823,14 +823,14 @@ Optional argument *module_relative* specifies how the filename should be interpreted: -* If *module_relative* is ``True`` (the default), then *filename* specifies an + * If *module_relative* is ``True`` (the default), then *filename* specifies an OS-independent module-relative path. By default, this path is relative to the calling module's directory; but if the *package* argument is specified, then it is relative to that package. To ensure OS-independence, *filename* should use ``/`` characters to separate path segments, and may not be an absolute path (i.e., it may not begin with ``/``). -* If *module_relative* is ``False``, then *filename* specifies an OS-specific + * If *module_relative* is ``False``, then *filename* specifies an OS-specific path. The path may be absolute or relative; relative paths are resolved with respect to the current working directory. @@ -1000,14 +1000,14 @@ Optional argument *module_relative* specifies how the filenames in *paths* should be interpreted: -* If *module_relative* is ``True`` (the default), then each filename specifies + * If *module_relative* is ``True`` (the default), then each filename specifies an OS-independent module-relative path. By default, this path is relative to the calling module's directory; but if the *package* argument is specified, then it is relative to that package. To ensure OS-independence, each filename should use ``/`` characters to separate path segments, and may not be an absolute path (i.e., it may not begin with ``/``). -* If *module_relative* is ``False``, then each filename specifies an OS-specific + * If *module_relative* is ``False``, then each filename specifies an OS-specific path. The path may be absolute or relative; relative paths are resolved with respect to the current working directory. @@ -1074,8 +1074,8 @@ Optional argument *extraglobs* specifies an extra set of global variables, which is merged into *globs*. By default, no extra globals are used. - Optional argument *test_finder* is the :class:`DocTestFinder` object (or a drop- - in replacement) that is used to extract doctests from the module. + Optional argument *test_finder* is the :class:`DocTestFinder` object (or a + drop-in replacement) that is used to extract doctests from the module. Optional arguments *setUp*, *tearDown*, and *optionflags* are the same as for function :func:`DocFileSuite` above. @@ -1346,15 +1346,15 @@ If the module is not specified or is None, then the test finder will attempt to automatically determine the correct module. The object's module is used: -* As a default namespace, if *globs* is not specified. + * As a default namespace, if *globs* is not specified. -* To prevent the DocTestFinder from extracting DocTests from objects that are + * To prevent the DocTestFinder from extracting DocTests from objects that are imported from other modules. (Contained objects with modules other than *module* are ignored.) -* To find the name of the file containing the object. + * To find the name of the file containing the object. -* To help find the line number of the object within its file. + * To help find the line number of the object within its file. If *module* is ``False``, no attempt to find the module will be made. This is obscure, of use mostly in testing doctest itself: if *module* is ``False``, or Modified: doctools/trunk/Doc-3k/library/email.charset.rst ============================================================================== --- doctools/trunk/Doc-3k/library/email.charset.rst (original) +++ doctools/trunk/Doc-3k/library/email.charset.rst Sun Aug 5 00:45:13 2007 @@ -149,8 +149,8 @@ .. method:: Charset.encoded_header_len() - Return the length of the encoded header string, properly calculating for quoted- - printable or base64 encoding. + Return the length of the encoded header string, properly calculating for + quoted-printable or base64 encoding. .. method:: Charset.header_encode(s[, convert]) @@ -210,11 +210,11 @@ *charset* is the input character set, and must be the canonical name of a character set. - Optional *header_enc* and *body_enc* is either ``Charset.QP`` for quoted- - printable, ``Charset.BASE64`` for base64 encoding, ``Charset.SHORTEST`` for the - shortest of quoted-printable or base64 encoding, or ``None`` for no encoding. - ``SHORTEST`` is only valid for *header_enc*. The default is ``None`` for no - encoding. + Optional *header_enc* and *body_enc* is either ``Charset.QP`` for + quoted-printable, ``Charset.BASE64`` for base64 encoding, + ``Charset.SHORTEST`` for the shortest of quoted-printable or base64 encoding, + or ``None`` for no encoding. ``SHORTEST`` is only valid for + *header_enc*. The default is ``None`` for no encoding. Optional *output_charset* is the character set that the output should be in. Conversions will proceed from input charset, to Unicode, to the output charset Modified: doctools/trunk/Doc-3k/library/email.generator.rst ============================================================================== --- doctools/trunk/Doc-3k/library/email.generator.rst (original) +++ doctools/trunk/Doc-3k/library/email.generator.rst Sun Aug 5 00:45:13 2007 @@ -100,17 +100,17 @@ string that is used instead of the message payload. *fmt* is expanded with the following keywords, ``%(keyword)s`` format: -* ``type`` -- Full MIME type of the non-\ :mimetype:`text` part + * ``type`` -- Full MIME type of the non-\ :mimetype:`text` part -* ``maintype`` -- Main MIME type of the non-\ :mimetype:`text` part + * ``maintype`` -- Main MIME type of the non-\ :mimetype:`text` part -* ``subtype`` -- Sub-MIME type of the non-\ :mimetype:`text` part + * ``subtype`` -- Sub-MIME type of the non-\ :mimetype:`text` part -* ``filename`` -- Filename of the non-\ :mimetype:`text` part + * ``filename`` -- Filename of the non-\ :mimetype:`text` part -* ``description`` -- Description associated with the non-\ :mimetype:`text` part + * ``description`` -- Description associated with the non-\ :mimetype:`text` part -* ``encoding`` -- Content transfer encoding of the non-\ :mimetype:`text` part + * ``encoding`` -- Content transfer encoding of the non-\ :mimetype:`text` part The default value for *fmt* is ``None``, meaning :: Modified: doctools/trunk/Doc-3k/library/email.message.rst ============================================================================== --- doctools/trunk/Doc-3k/library/email.message.rst (original) +++ doctools/trunk/Doc-3k/library/email.message.rst Sun Aug 5 00:45:13 2007 @@ -15,10 +15,10 @@ value are separated by a colon. The colon is not part of either the field name or the field value. -Headers are stored and returned in case-preserving form but are matched case- -insensitively. There may also be a single envelope header, also known as the -*Unix-From* header or the ``From_`` header. The payload is either a string in -the case of simple message objects or a list of :class:`Message` objects for +Headers are stored and returned in case-preserving form but are matched +case-insensitively. There may also be a single envelope header, also known as +the *Unix-From* header or the ``From_`` header. The payload is either a string +in the case of simple message objects or a list of :class:`Message` objects for MIME container documents (e.g. :mimetype:`multipart/\*` and :mimetype:`message/rfc822`). Modified: doctools/trunk/Doc-3k/library/email.parser.rst ============================================================================== --- doctools/trunk/Doc-3k/library/email.parser.rst (original) +++ doctools/trunk/Doc-3k/library/email.parser.rst Sun Aug 5 00:45:13 2007 @@ -51,11 +51,11 @@ The :class:`FeedParser`'s API is simple; you create an instance, feed it a bunch of text until there's no more to feed it, then close the parser to retrieve the root message object. The :class:`FeedParser` is extremely accurate when parsing -standards-compliant messages, and it does a very good job of parsing non- -compliant messages, providing information about how a message was deemed broken. -It will populate a message object's *defects* attribute with a list of any -problems it found in a message. See the :mod:`email.errors` module for the list -of defects that it can find. +standards-compliant messages, and it does a very good job of parsing +non-compliant messages, providing information about how a message was deemed +broken. It will populate a message object's *defects* attribute with a list of +any problems it found in a message. See the :mod:`email.errors` module for the +list of defects that it can find. Here is the API for the :class:`FeedParser`: @@ -108,10 +108,10 @@ The optional *strict* flag is ignored. .. deprecated:: 2.4 - Because the :class:`Parser` class is a backward compatible API wrapper around - the new-in-Python 2.4 :class:`FeedParser`, *all* parsing is effectively non- - strict. You should simply stop passing a *strict* flag to the :class:`Parser` - constructor. + Because the :class:`Parser` class is a backward compatible API wrapper + around the new-in-Python 2.4 :class:`FeedParser`, *all* parsing is + effectively non-strict. You should simply stop passing a *strict* flag to + the :class:`Parser` constructor. .. versionchanged:: 2.2.2 The *strict* flag was added. @@ -129,10 +129,10 @@ the :meth:`read` methods on file-like objects. The text contained in *fp* must be formatted as a block of :rfc:`2822` style - headers and header continuation lines, optionally preceded by a envelope header. - The header block is terminated either by the end of the data or by a blank line. - Following the header block is the body of the message (which may contain MIME- - encoded subparts). + headers and header continuation lines, optionally preceded by a envelope + header. The header block is terminated either by the end of the data or by a + blank line. Following the header block is the body of the message (which may + contain MIME-encoded subparts). Optional *headersonly* is as with the :meth:`parse` method. Modified: doctools/trunk/Doc-3k/library/errno.rst ============================================================================== --- doctools/trunk/Doc-3k/library/errno.rst (original) +++ doctools/trunk/Doc-3k/library/errno.rst Sun Aug 5 00:45:13 2007 @@ -8,8 +8,8 @@ This module makes available standard ``errno`` system symbols. The value of each symbol is the corresponding integer value. The names and descriptions are -borrowed from :file:`linux/include/errno.h`, which should be pretty all- -inclusive. +borrowed from :file:`linux/include/errno.h`, which should be pretty +all-inclusive. .. data:: errorcode Modified: doctools/trunk/Doc-3k/library/fcntl.rst ============================================================================== --- doctools/trunk/Doc-3k/library/fcntl.rst (original) +++ doctools/trunk/Doc-3k/library/fcntl.rst Sun Aug 5 00:45:13 2007 @@ -104,29 +104,26 @@ the file descriptor of the file to lock or unlock, and *operation* is one of the following values: -* :const:`LOCK_UN` -- unlock - -* :const:`LOCK_SH` -- acquire a shared lock - -* :const:`LOCK_EX` -- acquire an exclusive lock - - When *operation* is :const:`LOCK_SH` or :const:`LOCK_EX`, it can also be bit- - wise OR'd with :const:`LOCK_NB` to avoid blocking on lock acquisition. If - :const:`LOCK_NB` is used and the lock cannot be acquired, an :exc:`IOError` will - be raised and the exception will have an *errno* attribute set to - :const:`EACCES` or :const:`EAGAIN` (depending on the operating system; for - portability, check for both values). On at least some systems, :const:`LOCK_EX` - can only be used if the file descriptor refers to a file opened for writing. + * :const:`LOCK_UN` -- unlock + * :const:`LOCK_SH` -- acquire a shared lock + * :const:`LOCK_EX` -- acquire an exclusive lock + + When *operation* is :const:`LOCK_SH` or :const:`LOCK_EX`, it can also be + bit-wise OR'd with :const:`LOCK_NB` to avoid blocking on lock acquisition. + If :const:`LOCK_NB` is used and the lock cannot be acquired, an + :exc:`IOError` will be raised and the exception will have an *errno* + attribute set to :const:`EACCES` or :const:`EAGAIN` (depending on the + operating system; for portability, check for both values). On at least some + systems, :const:`LOCK_EX` can only be used if the file descriptor refers to a + file opened for writing. *length* is the number of bytes to lock, *start* is the byte offset at which the lock starts, relative to *whence*, and *whence* is as with :func:`fileobj.seek`, specifically: -* :const:`0` -- relative to the start of the file (:const:`SEEK_SET`) - -* :const:`1` -- relative to the current buffer position (:const:`SEEK_CUR`) - -* :const:`2` -- relative to the end of the file (:const:`SEEK_END`) + * :const:`0` -- relative to the start of the file (:const:`SEEK_SET`) + * :const:`1` -- relative to the current buffer position (:const:`SEEK_CUR`) + * :const:`2` -- relative to the end of the file (:const:`SEEK_END`) The default for *start* is 0, which means to start at the beginning of the file. The default for *length* is 0 which means to lock to the end of the file. The @@ -151,7 +148,8 @@ .. seealso:: Module :mod:`os` - If the locking flags :const:`O_SHLOCK` and :const:`O_EXLOCK` are present in the - :mod:`os` module, the :func:`os.open` function provides a more platform- - independent alternative to the :func:`lockf` and :func:`flock` functions. + If the locking flags :const:`O_SHLOCK` and :const:`O_EXLOCK` are present + in the :mod:`os` module, the :func:`os.open` function provides a more + platform-independent alternative to the :func:`lockf` and :func:`flock` + functions. Modified: doctools/trunk/Doc-3k/library/formatter.rst ============================================================================== --- doctools/trunk/Doc-3k/library/formatter.rst (original) +++ doctools/trunk/Doc-3k/library/formatter.rst Sun Aug 5 00:45:13 2007 @@ -169,7 +169,7 @@ :const:`AS_IS` values, is passed to the writer's :meth:`new_styles` method. -.. method:: formatter.pop_style([n\ ``= 1``]) +.. method:: formatter.pop_style([n=1]) Pop the last *n* style specifications passed to :meth:`push_style`. A tuple representing the revised stack, including :const:`AS_IS` values, is passed to @@ -181,12 +181,12 @@ Set the spacing style for the writer. -.. method:: formatter.assert_line_data([flag\ ``= 1``]) +.. method:: formatter.assert_line_data([flag=1]) - Inform the formatter that data has been added to the current paragraph out-of- - band. This should be used when the writer has been manipulated directly. The - optional *flag* argument can be set to false if the writer manipulations - produced a hard line break at the end of the output. + Inform the formatter that data has been added to the current paragraph + out-of-band. This should be used when the writer has been manipulated + directly. The optional *flag* argument can be set to false if the writer + manipulations produced a hard line break at the end of the output. .. _formatter-impls: @@ -341,7 +341,7 @@ output. -.. class:: DumbWriter([file[, maxcol\ ``= 72``]]) +.. class:: DumbWriter([file[, maxcol=72]]) Simple writer class which writes output on the file object passed in as *file* or, if *file* is omitted, on standard output. The output is simply word-wrapped Modified: doctools/trunk/Doc-3k/library/fpectl.rst ============================================================================== --- doctools/trunk/Doc-3k/library/fpectl.rst (original) +++ doctools/trunk/Doc-3k/library/fpectl.rst Sun Aug 5 00:45:13 2007 @@ -17,10 +17,10 @@ .. index:: single: IEEE-754 -Most computers carry out floating point operations in conformance with the so- -called IEEE-754 standard. On any real computer, some floating point operations -produce results that cannot be expressed as a normal floating point value. For -example, try :: +Most computers carry out floating point operations in conformance with the +so-called IEEE-754 standard. On any real computer, some floating point +operations produce results that cannot be expressed as a normal floating point +value. For example, try :: >>> import math >>> math.exp(1000) Modified: doctools/trunk/Doc-3k/library/functions.rst ============================================================================== --- doctools/trunk/Doc-3k/library/functions.rst (original) +++ doctools/trunk/Doc-3k/library/functions.rst Sun Aug 5 00:45:13 2007 @@ -39,16 +39,17 @@ its *locals* argument at all, and uses its *globals* only to determine the package context of the :keyword:`import` statement.) - When the *name* variable is of the form ``package.module``, normally, the top- - level package (the name up till the first dot) is returned, *not* the module - named by *name*. However, when a non-empty *fromlist* argument is given, the - module named by *name* is returned. This is done for compatibility with the - bytecode generated for the different kinds of import statement; when using - ``import spam.ham.eggs``, the top-level package :mod:`spam` must be placed in - the importing namespace, but when using ``from spam.ham import eggs``, the - ``spam.ham`` subpackage must be used to find the ``eggs`` variable. As a - workaround for this behavior, use :func:`getattr` to extract the desired - components. For example, you could define the following helper:: + When the *name* variable is of the form ``package.module``, normally, the + top-level package (the name up till the first dot) is returned, *not* the + module named by *name*. However, when a non-empty *fromlist* argument is + given, the module named by *name* is returned. This is done for + compatibility with the bytecode generated for the different kinds of import + statement; when using ``import spam.ham.eggs``, the top-level package + :mod:`spam` must be placed in the importing namespace, but when using ``from + spam.ham import eggs``, the ``spam.ham`` subpackage must be used to find the + ``eggs`` variable. As a workaround for this behavior, use :func:`getattr` to + extract the desired components. For example, you could define the following + helper:: def my_import(name): mod = __import__(name) @@ -258,19 +259,19 @@ keyword is retained in the dictionary. For example, these all return a dictionary equal to ``{"one": 2, "two": 3}``: -* ``dict({'one': 2, 'two': 3})`` + * ``dict({'one': 2, 'two': 3})`` -* ``dict({'one': 2, 'two': 3}.items())`` + * ``dict({'one': 2, 'two': 3}.items())`` -* ``dict({'one': 2, 'two': 3}.iteritems())`` + * ``dict({'one': 2, 'two': 3}.iteritems())`` -* ``dict(zip(('one', 'two'), (2, 3)))`` + * ``dict(zip(('one', 'two'), (2, 3)))`` -* ``dict([['two', 3], ['one', 2]])`` + * ``dict([['two', 3], ['one', 2]])`` -* ``dict(one=2, two=3)`` + * ``dict(one=2, two=3)`` -* ``dict([(['one', 'two'][i-2], i) for i in (2, 3)])`` + * ``dict([(['one', 'two'][i-2], i) for i in (2, 3)])`` .. versionadded:: 2.2 Modified: doctools/trunk/Doc-3k/library/gdbm.rst ============================================================================== --- doctools/trunk/Doc-3k/library/gdbm.rst (original) +++ doctools/trunk/Doc-3k/library/gdbm.rst Sun Aug 5 00:45:13 2007 @@ -40,13 +40,13 @@ The following additional characters may be appended to the flag to control how the database is opened: -* ``'f'`` --- Open the database in fast mode. Writes to the database will not + * ``'f'`` --- Open the database in fast mode. Writes to the database will not be synchronized. -* ``'s'`` --- Synchronized mode. This will cause changes to the database will be + * ``'s'`` --- Synchronized mode. This will cause changes to the database will be immediately written to the file. -* ``'u'`` --- Do not lock database. + * ``'u'`` --- Do not lock database. Not all flags are valid for all versions of ``gdbm``. The module constant ``open_flags`` is a string of supported flag characters. The exception Modified: doctools/trunk/Doc-3k/library/getopt.rst ============================================================================== --- doctools/trunk/Doc-3k/library/getopt.rst (original) +++ doctools/trunk/Doc-3k/library/getopt.rst Sun Aug 5 00:45:13 2007 @@ -43,13 +43,13 @@ The return value consists of two elements: the first is a list of ``(option, value)`` pairs; the second is the list of program arguments left after the - option list was stripped (this is a trailing slice of *args*). Each option-and- - value pair returned has the option as its first element, prefixed with a hyphen - for short options (e.g., ``'-x'``) or two hyphens for long options (e.g., - ``'-``\ ``-long-option'``), and the option argument as its second element, or an - empty string if the option has no argument. The options occur in the list in - the same order in which they were found, thus allowing multiple occurrences. - Long and short options may be mixed. + option list was stripped (this is a trailing slice of *args*). Each + option-and-value pair returned has the option as its first element, prefixed + with a hyphen for short options (e.g., ``'-x'``) or two hyphens for long + options (e.g., ``'-``\ ``-long-option'``), and the option argument as its + second element, or an empty string if the option has no argument. The + options occur in the list in the same order in which they were found, thus + allowing multiple occurrences. Long and short options may be mixed. .. function:: gnu_getopt(args, options[, long_options]) @@ -60,8 +60,8 @@ non-option argument is encountered. If the first character of the option string is '+', or if the environment - variable POSIXLY_CORRECT is set, then option processing stops as soon as a non- - option argument is encountered. + variable POSIXLY_CORRECT is set, then option processing stops as soon as a + non-option argument is encountered. .. versionadded:: 2.3 Modified: doctools/trunk/Doc-3k/library/gettext.rst ============================================================================== --- doctools/trunk/Doc-3k/library/gettext.rst (original) +++ doctools/trunk/Doc-3k/library/gettext.rst Sun Aug 5 00:45:13 2007 @@ -385,10 +385,10 @@ ids and message strings read from the catalog are converted to Unicode using this encoding. The :meth:`ugettext` method always returns a Unicode, while the :meth:`gettext` returns an encoded 8-bit string. For the message id arguments -of both methods, either Unicode strings or 8-bit strings containing only US- -ASCII characters are acceptable. Note that the Unicode version of the methods -(i.e. :meth:`ugettext` and :meth:`ungettext`) are the recommended interface to -use for internationalized Python programs. +of both methods, either Unicode strings or 8-bit strings containing only +US-ASCII characters are acceptable. Note that the Unicode version of the +methods (i.e. :meth:`ugettext` and :meth:`ungettext`) are the recommended +interface to use for internationalized Python programs. The entire set of key/value pairs are placed into a dictionary and set as the "protected" :attr:`_info` instance variable. Modified: doctools/trunk/Doc-3k/library/httplib.rst ============================================================================== --- doctools/trunk/Doc-3k/library/httplib.rst (original) +++ doctools/trunk/Doc-3k/library/httplib.rst Sun Aug 5 00:45:13 2007 @@ -100,8 +100,8 @@ .. exception:: InvalidURL - A subclass of :exc:`HTTPException`, raised if a port is given and is either non- - numeric or empty. + A subclass of :exc:`HTTPException`, raised if a port is given and is either + non-numeric or empty. .. versionadded:: 2.3 @@ -396,11 +396,11 @@ This will send a request to the server using the HTTP request method *method* and the selector *url*. If the *body* argument is present, it should be a - string of data to send after the headers are finished. Alternatively, it may be - an open file object, in which case the contents of the file is sent; this file - object should support ``fileno()`` and ``read()`` methods. The header Content- - Length is automatically set to the correct value. The *headers* argument should - be a mapping of extra HTTP headers to send with the request. + string of data to send after the headers are finished. Alternatively, it may + be an open file object, in which case the contents of the file is sent; this + file object should support ``fileno()`` and ``read()`` methods. The header + Content-Length is automatically set to the correct value. The *headers* + argument should be a mapping of extra HTTP headers to send with the request. .. versionchanged:: 2.6 *body* can be a file object. Modified: doctools/trunk/Doc-3k/library/imaplib.rst ============================================================================== --- doctools/trunk/Doc-3k/library/imaplib.rst (original) +++ doctools/trunk/Doc-3k/library/imaplib.rst Sun Aug 5 00:45:13 2007 @@ -232,8 +232,8 @@ .. method:: IMAP4.getannotation(mailbox, entry, attribute) - Retrieve the specified ``ANNOTATION``\ s for *mailbox*. The method is non- - standard, but is supported by the ``Cyrus`` server. + Retrieve the specified ``ANNOTATION``\ s for *mailbox*. The method is + non-standard, but is supported by the ``Cyrus`` server. .. versionadded:: 2.5 Modified: doctools/trunk/Doc-3k/library/imp.rst ============================================================================== --- doctools/trunk/Doc-3k/library/imp.rst (original) +++ doctools/trunk/Doc-3k/library/imp.rst Sun Aug 5 00:45:13 2007 @@ -177,12 +177,12 @@ .. function:: init_frozen(name) - Initialize the frozen module called *name* and return its module object. If the - module was already initialized, it will be initialized *again*. If there is no - frozen module called *name*, ``None`` is returned. (Frozen modules are modules - written in Python whose compiled byte-code object is incorporated into a custom- - built Python interpreter by Python's :program:`freeze` utility. See - :file:`Tools/freeze/` for now.) + Initialize the frozen module called *name* and return its module object. If + the module was already initialized, it will be initialized *again*. If there + is no frozen module called *name*, ``None`` is returned. (Frozen modules are + modules written in Python whose compiled byte-code object is incorporated + into a custom-built Python interpreter by Python's :program:`freeze` + utility. See :file:`Tools/freeze/` for now.) .. function:: is_builtin(name) @@ -240,10 +240,10 @@ .. class:: NullImporter(path_string) - The :class:`NullImporter` type is a :pep:`302` import hook that handles non- - directory path strings by failing to find any modules. Calling this type with - an existing directory or empty string raises :exc:`ImportError`. Otherwise, a - :class:`NullImporter` instance is returned. + The :class:`NullImporter` type is a :pep:`302` import hook that handles + non-directory path strings by failing to find any modules. Calling this type + with an existing directory or empty string raises :exc:`ImportError`. + Otherwise, a :class:`NullImporter` instance is returned. Python adds instances of this type to ``sys.path_importer_cache`` for any path entries that are not directories and are not handled by any other path hooks on Modified: doctools/trunk/Doc-3k/library/inspect.rst ============================================================================== --- doctools/trunk/Doc-3k/library/inspect.rst (original) +++ doctools/trunk/Doc-3k/library/inspect.rst Sun Aug 5 00:45:13 2007 @@ -198,12 +198,12 @@ identified by *path* if it is a module, or ``None`` if it would not be identified as a module. The return tuple is ``(name, suffix, mode, mtype)``, where *name* is the name of the module without the name of any enclosing - package, *suffix* is the trailing part of the file name (which may not be a dot- - delimited extension), *mode* is the :func:`open` mode that would be used - (``'r'`` or ``'rb'``), and *mtype* is an integer giving the type of the module. - *mtype* will have a value which can be compared to the constants defined in the - :mod:`imp` module; see the documentation for that module for more information on - module types. + package, *suffix* is the trailing part of the file name (which may not be a + dot-delimited extension), *mode* is the :func:`open` mode that would be used + (``'r'`` or ``'rb'``), and *mtype* is an integer giving the type of the + module. *mtype* will have a value which can be compared to the constants + defined in the :mod:`imp` module; see the documentation for that module for + more information on module types. .. function:: getmodulename(path) Modified: doctools/trunk/Doc-3k/library/itertools.rst ============================================================================== --- doctools/trunk/Doc-3k/library/itertools.rst (original) +++ doctools/trunk/Doc-3k/library/itertools.rst Sun Aug 5 00:45:13 2007 @@ -279,16 +279,16 @@ last tuple can be pre-padded with fill values using ``izip(*[chain(s, [None]*(n-1))]*n)``. - Note, when :func:`izip` is used with unequal length inputs, subsequent iteration - over the longer iterables cannot reliably be continued after :func:`izip` - terminates. Potentially, up to one entry will be missing from each of the left- - over iterables. This occurs because a value is fetched from each iterator in- - turn, but the process ends when one of the iterators terminates. This leaves - the last fetched values in limbo (they cannot be returned in a final, incomplete - tuple and they are cannot be pushed back into the iterator for retrieval with - ``next(it)``). In general, :func:`izip` should only be used with unequal length - inputs when you don't care about trailing, unmatched values from the longer - iterables. + Note, when :func:`izip` is used with unequal length inputs, subsequent + iteration over the longer iterables cannot reliably be continued after + :func:`izip` terminates. Potentially, up to one entry will be missing from + each of the left-over iterables. This occurs because a value is fetched from + each iterator in- turn, but the process ends when one of the iterators + terminates. This leaves the last fetched values in limbo (they cannot be + returned in a final, incomplete tuple and they are cannot be pushed back into + the iterator for retrieval with ``next(it)``). In general, :func:`izip` + should only be used with unequal length inputs when you don't care about + trailing, unmatched values from the longer iterables. .. function:: izip_longest(*iterables[, fillvalue]) Modified: doctools/trunk/Doc-3k/library/logging.rst ============================================================================== --- doctools/trunk/Doc-3k/library/logging.rst (original) +++ doctools/trunk/Doc-3k/library/logging.rst Sun Aug 5 00:45:13 2007 @@ -984,9 +984,9 @@ ^^^^^^^^^^^^^ The :class:`StreamHandler` class, located in the core :mod:`logging` package, -sends logging output to streams such as *sys.stdout*, *sys.stderr* or any file- -like object (or, more precisely, any object which supports :meth:`write` and -:meth:`flush` methods). +sends logging output to streams such as *sys.stdout*, *sys.stderr* or any +file-like object (or, more precisely, any object which supports :meth:`write` +and :meth:`flush` methods). .. class:: StreamHandler([strm]) @@ -1635,8 +1635,8 @@ .. method:: LogRecord.getMessage() - Returns the message for this :class:`LogRecord` instance after merging any user- - supplied arguments with the message. + Returns the message for this :class:`LogRecord` instance after merging any + user-supplied arguments with the message. Thread Safety Modified: doctools/trunk/Doc-3k/library/mailbox.rst ============================================================================== --- doctools/trunk/Doc-3k/library/mailbox.rst (original) +++ doctools/trunk/Doc-3k/library/mailbox.rst Sun Aug 5 00:45:13 2007 @@ -617,12 +617,13 @@ the last message, a line containing a Control-Underscore (``'\\037'``) character. -Messages in a Babyl mailbox have two sets of headers, original headers and so- -called visible headers. Visible headers are typically a subset of the original -headers that have been reformatted or abridged to be more attractive. Each -message in a Babyl mailbox also has an accompanying list of :dfn:`labels`, or -short strings that record extra information about the message, and a list of all -user-defined labels found in the mailbox is kept in the Babyl options section. +Messages in a Babyl mailbox have two sets of headers, original headers and +so-called visible headers. Visible headers are typically a subset of the +original headers that have been reformatted or abridged to be more +attractive. Each message in a Babyl mailbox also has an accompanying list of +:dfn:`labels`, or short strings that record extra information about the message, +and a list of all user-defined labels found in the mailbox is kept in the Babyl +options section. :class:`Babyl` instances have all of the methods of :class:`Mailbox` in addition to the following: @@ -772,8 +773,8 @@ "info" section added to its file name to store information about its state. (Some mail readers may also add an "info" section to messages in :file:`new`.) The "info" section may take one of two forms: it may contain "2," followed by a -list of standardized flags (e.g., "2,FR") or it may contain "1," followed by so- -called experimental information. Standard flags for Maildir messages are as +list of standardized flags (e.g., "2,FR") or it may contain "1," followed by +so-called experimental information. Standard flags for Maildir messages are as follows: +------+---------+--------------------------------+ @@ -1540,9 +1541,9 @@ :class:`UnixMailbox` except that individual messages are separated by only ``From`` lines. - For more information, see `Configuring Netscape Mail on Unix: Why the Content- - Length Format is Bad `_. + For more information, see `Configuring Netscape Mail on Unix: Why the + Content-Length Format is Bad + `_. .. class:: PortableUnixMailbox(fp[, factory]) Modified: doctools/trunk/Doc-3k/library/math.rst ============================================================================== --- doctools/trunk/Doc-3k/library/math.rst (original) +++ doctools/trunk/Doc-3k/library/math.rst Sun Aug 5 00:45:13 2007 @@ -209,15 +209,15 @@ .. note:: The :mod:`math` module consists mostly of thin wrappers around the platform C - math library functions. Behavior in exceptional cases is loosely specified by - the C standards, and Python inherits much of its math-function error-reporting - behavior from the platform C implementation. As a result, the specific - exceptions raised in error cases (and even whether some arguments are considered - to be exceptional at all) are not defined in any useful cross-platform or cross- - release way. For example, whether ``math.log(0)`` returns ``-Inf`` or raises - :exc:`ValueError` or :exc:`OverflowError` isn't defined, and in cases where - ``math.log(0)`` raises :exc:`OverflowError`, ``math.log(0L)`` may raise - :exc:`ValueError` instead. + math library functions. Behavior in exceptional cases is loosely specified + by the C standards, and Python inherits much of its math-function + error-reporting behavior from the platform C implementation. As a result, + the specific exceptions raised in error cases (and even whether some + arguments are considered to be exceptional at all) are not defined in any + useful cross-platform or cross-release way. For example, whether + ``math.log(0)`` returns ``-Inf`` or raises :exc:`ValueError` or + :exc:`OverflowError` isn't defined, and in cases where ``math.log(0)`` raises + :exc:`OverflowError`, ``math.log(0L)`` may raise :exc:`ValueError` instead. .. seealso:: Modified: doctools/trunk/Doc-3k/library/mimetypes.rst ============================================================================== --- doctools/trunk/Doc-3k/library/mimetypes.rst (original) +++ doctools/trunk/Doc-3k/library/mimetypes.rst Sun Aug 5 00:45:13 2007 @@ -39,11 +39,12 @@ Encoding suffixes are case sensitive; type suffixes are first tried case sensitively, then case insensitively. - Optional *strict* is a flag specifying whether the list of known MIME types is - limited to only the official types `registered with IANA `_ are recognized. When *strict* is true - (the default), only the IANA types are supported; when *strict* is false, some - additional non-standard but commonly used MIME types are also recognized. + Optional *strict* is a flag specifying whether the list of known MIME types + is limited to only the official types `registered with IANA + `_ are recognized. + When *strict* is true (the default), only the IANA types are supported; when + *strict* is false, some additional non-standard but commonly used MIME types + are also recognized. .. function:: guess_all_extensions(type[, strict]) Modified: doctools/trunk/Doc-3k/library/mmap.rst ============================================================================== --- doctools/trunk/Doc-3k/library/mmap.rst (original) +++ doctools/trunk/Doc-3k/library/mmap.rst Sun Aug 5 00:45:13 2007 @@ -147,8 +147,8 @@ .. method:: mmap.size() - Return the length of the file, which can be larger than the size of the memory- - mapped area. + Return the length of the file, which can be larger than the size of the + memory-mapped area. .. method:: mmap.tell() Modified: doctools/trunk/Doc-3k/library/msilib.rst ============================================================================== --- doctools/trunk/Doc-3k/library/msilib.rst (original) +++ doctools/trunk/Doc-3k/library/msilib.rst Sun Aug 5 00:45:13 2007 @@ -424,7 +424,7 @@ belongs to, and *name* is the control's name. -.. method:: Control.event(event, argument[, condition = ``1''[, ordering]]) +.. method:: Control.event(event, argument[, condition=1[, ordering]]) Make an entry into the ``ControlEvent`` table for this control. Modified: doctools/trunk/Doc-3k/library/multifile.rst ============================================================================== --- doctools/trunk/Doc-3k/library/multifile.rst (original) +++ doctools/trunk/Doc-3k/library/multifile.rst Sun Aug 5 00:45:13 2007 @@ -33,8 +33,8 @@ It will be useful to know that in :class:`MultiFile`'s view of the world, text is composed of three kinds of lines: data, section-dividers, and end-markers. MultiFile is designed to support parsing of messages that may have multiple -nested message parts, each with its own pattern for section-divider and end- -marker lines. +nested message parts, each with its own pattern for section-divider and +end-marker lines. .. seealso:: @@ -110,9 +110,9 @@ return the empty string to indicate end-of-file, until a call to :meth:`pop` removes the boundary a or :meth:`next` call reenables it. - It is possible to push more than one boundary. Encountering the most-recently- - pushed boundary will return EOF; encountering any other boundary will raise an - error. + It is possible to push more than one boundary. Encountering the + most-recently-pushed boundary will return EOF; encountering any other + boundary will raise an error. .. method:: MultiFile.pop() @@ -122,19 +122,19 @@ .. method:: MultiFile.section_divider(str) - Turn a boundary into a section-divider line. By default, this method prepends - ``'-``\ ``-'`` (which MIME section boundaries have) but it is declared so it can - be overridden in derived classes. This method need not append LF or CR-LF, as - comparison with the result ignores trailing whitespace. + Turn a boundary into a section-divider line. By default, this method + prepends ``'--'`` (which MIME section boundaries have) but it is declared so + it can be overridden in derived classes. This method need not append LF or + CR-LF, as comparison with the result ignores trailing whitespace. .. method:: MultiFile.end_marker(str) Turn a boundary string into an end-marker line. By default, this method - prepends ``'-``\ ``-'`` and appends ``'-``\ ``-'`` (like a MIME-multipart end- - of-message marker) but it is declared so it can be overridden in derived - classes. This method need not append LF or CR-LF, as comparison with the result - ignores trailing whitespace. + prepends ``'--'`` and appends ``'--'`` (like a MIME-multipart end-of-message + marker) but it is declared so it can be overridden in derived classes. This + method need not append LF or CR-LF, as comparison with the result ignores + trailing whitespace. Finally, :class:`MultiFile` instances have two public instance variables: Modified: doctools/trunk/Doc-3k/library/netrc.rst ============================================================================== --- doctools/trunk/Doc-3k/library/netrc.rst (original) +++ doctools/trunk/Doc-3k/library/netrc.rst Sun Aug 5 00:45:13 2007 @@ -70,9 +70,9 @@ .. note:: - Passwords are limited to a subset of the ASCII character set. Versions of this - module prior to 2.3 were extremely limited. Starting with 2.3, all ASCII - punctuation is allowed in passwords. However, note that whitespace and non- - printable characters are not allowed in passwords. This is a limitation of the - way the .netrc file is parsed and may be removed in the future. + Passwords are limited to a subset of the ASCII character set. Versions of + this module prior to 2.3 were extremely limited. Starting with 2.3, all + ASCII punctuation is allowed in passwords. However, note that whitespace and + non-printable characters are not allowed in passwords. This is a limitation + of the way the .netrc file is parsed and may be removed in the future. Modified: doctools/trunk/Doc-3k/library/new.rst ============================================================================== --- doctools/trunk/Doc-3k/library/new.rst (original) +++ doctools/trunk/Doc-3k/library/new.rst Sun Aug 5 00:45:13 2007 @@ -11,8 +11,8 @@ functions. This is for use primarily in marshal-type functions, when a new object needs to be created "magically" and not by using the regular creation functions. This module provides a low-level interface to the interpreter, so -care must be exercised when using this module. It is possible to supply non- -sensical arguments which crash the interpreter when the object is used. +care must be exercised when using this module. It is possible to supply +non-sensical arguments which crash the interpreter when the object is used. The :mod:`new` module defines the following functions: Modified: doctools/trunk/Doc-3k/library/nntplib.rst ============================================================================== --- doctools/trunk/Doc-3k/library/nntplib.rst (original) +++ doctools/trunk/Doc-3k/library/nntplib.rst Sun Aug 5 00:45:13 2007 @@ -53,18 +53,18 @@ .. class:: NNTP(host[, port [, user[, password [, readermode] [, usenetrc]]]]) - Return a new instance of the :class:`NNTP` class, representing a connection to - the NNTP server running on host *host*, listening at port *port*. The default - *port* is 119. If the optional *user* and *password* are provided, or if - suitable credentials are present in :file:`/.netrc` and the optional flag - *usenetrc* is true (the default), the ``AUTHINFO USER`` and ``AUTHINFO PASS`` - commands are used to identify and authenticate the user to the server. If the - optional flag *readermode* is true, then a ``mode reader`` command is sent - before authentication is performed. Reader mode is sometimes necessary if you - are connecting to an NNTP server on the local machine and intend to call reader- - specific commands, such as ``group``. If you get unexpected - :exc:`NNTPPermanentError`\ s, you might need to set *readermode*. *readermode* - defaults to ``None``. *usenetrc* defaults to ``True``. + Return a new instance of the :class:`NNTP` class, representing a connection + to the NNTP server running on host *host*, listening at port *port*. The + default *port* is 119. If the optional *user* and *password* are provided, + or if suitable credentials are present in :file:`/.netrc` and the optional + flag *usenetrc* is true (the default), the ``AUTHINFO USER`` and ``AUTHINFO + PASS`` commands are used to identify and authenticate the user to the server. + If the optional flag *readermode* is true, then a ``mode reader`` command is + sent before authentication is performed. Reader mode is sometimes necessary + if you are connecting to an NNTP server on the local machine and intend to + call reader-specific commands, such as ``group``. If you get unexpected + :exc:`NNTPPermanentError`\ s, you might need to set *readermode*. + *readermode* defaults to ``None``. *usenetrc* defaults to ``True``. .. versionchanged:: 2.4 *usenetrc* argument added. Modified: doctools/trunk/Doc-3k/library/optparse.rst ============================================================================== --- doctools/trunk/Doc-3k/library/optparse.rst (original) +++ doctools/trunk/Doc-3k/library/optparse.rst Sun Aug 5 00:45:13 2007 @@ -117,18 +117,18 @@ Some other option syntaxes that the world has seen include: -* a hyphen followed by a few letters, e.g. ``"-pf"`` (this is *not* the same - as multiple options merged into a single argument) + * a hyphen followed by a few letters, e.g. ``"-pf"`` (this is *not* the same + as multiple options merged into a single argument) -* a hyphen followed by a whole word, e.g. ``"-file"`` (this is technically - equivalent to the previous syntax, but they aren't usually seen in the same - program) + * a hyphen followed by a whole word, e.g. ``"-file"`` (this is technically + equivalent to the previous syntax, but they aren't usually seen in the same + program) -* a plus sign followed by a single letter, or a few letters, or a word, e.g. - ``"+f"``, ``"+rgb"`` + * a plus sign followed by a single letter, or a few letters, or a word, e.g. + ``"+f"``, ``"+rgb"`` -* a slash followed by a letter, or a few letters, or a word, e.g. ``"/f"``, - ``"/file"`` + * a slash followed by a letter, or a few letters, or a word, e.g. ``"/f"``, + ``"/file"`` These option syntaxes are not supported by :mod:`optparse`, and they never will be. This is deliberate: the first three are non-standard on any environment, @@ -470,8 +470,8 @@ :mod:`optparse`'s ability to generate help and usage text automatically is useful for creating user-friendly command-line interfaces. All you have to do is supply a :attr:`help` value for each option, and optionally a short usage -message for your whole program. Here's an OptionParser populated with user- -friendly (documented) options:: +message for your whole program. Here's an OptionParser populated with +user-friendly (documented) options:: usage = "usage: %prog [options] arg1 arg2" parser = OptionParser(usage=usage) @@ -488,9 +488,9 @@ help="interaction mode: novice, intermediate, " "or expert [default: %default]") -If :mod:`optparse` encounters either ``"-h"`` or ``"--help"`` on the command- -line, or if you just call :meth:`parser.print_help`, it prints the following to -standard output:: +If :mod:`optparse` encounters either ``"-h"`` or ``"--help"`` on the +command-line, or if you just call :meth:`parser.print_help`, it prints the +following to standard output:: usage: [options] arg1 arg2 @@ -521,12 +521,12 @@ default: ``"usage: %prog [options]"``, which is fine if your script doesn't take any positional arguments. -* every option defines a help string, and doesn't worry about line- - wrapping---\ :mod:`optparse` takes care of wrapping lines and making the help - output look good. +* every option defines a help string, and doesn't worry about line-wrapping--- + :mod:`optparse` takes care of wrapping lines and making the help output look + good. -* options that take a value indicate this fact in their automatically- - generated help message, e.g. for the "mode" option:: +* options that take a value indicate this fact in their automatically-generated + help message, e.g. for the "mode" option:: -m MODE, --mode=MODE @@ -1663,14 +1663,14 @@ where ``option`` is an :class:`Option` instance, ``opt`` is an option string (e.g., ``"-f"``), and ``value`` is the string from the command line that must be checked and converted to your desired type. ``check_mytype()`` should return an -object of the hypothetical type ``mytype``. The value returned by a type- -checking function will wind up in the OptionValues instance returned by +object of the hypothetical type ``mytype``. The value returned by a +type-checking function will wind up in the OptionValues instance returned by :meth:`OptionParser.parse_args`, or be passed to a callback as the ``value`` parameter. Your type-checking function should raise OptionValueError if it encounters any -problems. OptionValueError takes a single string argument, which is passed as- -is to OptionParser's :meth:`error` method, which in turn prepends the program +problems. OptionValueError takes a single string argument, which is passed +as-is to OptionParser's :meth:`error` method, which in turn prepends the program name and the string ``"error:"`` and prints everything to stderr before terminating the process. Modified: doctools/trunk/Doc-3k/library/os.rst ============================================================================== --- doctools/trunk/Doc-3k/library/os.rst (original) +++ doctools/trunk/Doc-3k/library/os.rst Sun Aug 5 00:45:13 2007 @@ -568,9 +568,9 @@ .. function:: ttyname(fd) - Return a string which specifies the terminal device associated with file- - descriptor *fd*. If *fd* is not associated with a terminal device, an exception - is raised. Availability:Macintosh, Unix. + Return a string which specifies the terminal device associated with + file-descriptor *fd*. If *fd* is not associated with a terminal device, an + exception is raised. Availability:Macintosh, Unix. .. function:: write(fd, str) @@ -600,8 +600,8 @@ O_EXCL O_TRUNC - Options for the *flag* argument to the :func:`open` function. These can be bit- - wise OR'd together. Availability: Macintosh, Unix, Windows. + Options for the *flag* argument to the :func:`open` function. These can be + bit-wise OR'd together. Availability: Macintosh, Unix, Windows. .. data:: O_DSYNC @@ -619,8 +619,8 @@ .. data:: O_BINARY - Option for the *flag* argument to the :func:`open` function. This can be bit- - wise OR'd together with those listed above. Availability: Windows. + Option for the *flag* argument to the :func:`open` function. This can be + bit-wise OR'd together with those listed above. Availability: Windows. .. % XXX need to check on the availability of this one. @@ -632,8 +632,8 @@ O_SEQUENTIAL O_TEXT - Options for the *flag* argument to the :func:`open` function. These can be bit- - wise OR'd together. Availability: Windows. + Options for the *flag* argument to the :func:`open` function. These can be + bit-wise OR'd together. Availability: Windows. .. data:: SEEK_SET @@ -737,25 +737,16 @@ Set the flags of *path* to the numeric *flags*. *flags* may take a combination (bitwise OR) of the following values (as defined in the :mod:`stat` module): -* ``UF_NODUMP`` - -* ``UF_IMMUTABLE`` - -* ``UF_APPEND`` - -* ``UF_OPAQUE`` - -* ``UF_NOUNLINK`` - -* ``SF_ARCHIVED`` - -* ``SF_IMMUTABLE`` - -* ``SF_APPEND`` - -* ``SF_NOUNLINK`` - -* ``SF_SNAPSHOT`` + * ``UF_NODUMP`` + * ``UF_IMMUTABLE`` + * ``UF_APPEND`` + * ``UF_OPAQUE`` + * ``UF_NOUNLINK`` + * ``SF_ARCHIVED`` + * ``SF_IMMUTABLE`` + * ``SF_APPEND`` + * ``SF_NOUNLINK`` + * ``SF_SNAPSHOT`` Availability: Macintosh, Unix. @@ -776,43 +767,25 @@ following values (as defined in the :mod:`stat` module) or bitwise or-ed combinations of them: -* ``stat.S_ISUID`` - -* ``stat.S_ISGID`` - -* ``stat.S_ENFMT`` - -* ``stat.S_ISVTX`` - -* ``stat.S_IREAD`` - -* ``stat.S_IWRITE`` - -* ``stat.S_IEXEC`` - -* ``stat.S_IRWXU`` - -* ``stat.S_IRUSR`` - -* ``stat.S_IWUSR`` - -* ``stat.S_IXUSR`` - -* ``stat.S_IRWXG`` - -* ``stat.S_IRGRP`` - -* ``stat.S_IWGRP`` - -* ``stat.S_IXGRP`` - -* ``stat.S_IRWXO`` - -* ``stat.S_IROTH`` - -* ``stat.S_IWOTH`` - -* ``stat.S_IXOTH`` + * ``stat.S_ISUID`` + * ``stat.S_ISGID`` + * ``stat.S_ENFMT`` + * ``stat.S_ISVTX`` + * ``stat.S_IREAD`` + * ``stat.S_IWRITE`` + * ``stat.S_IEXEC`` + * ``stat.S_IRWXU`` + * ``stat.S_IRUSR`` + * ``stat.S_IWUSR`` + * ``stat.S_IXUSR`` + * ``stat.S_IRWXG`` + * ``stat.S_IRGRP`` + * ``stat.S_IWGRP`` + * ``stat.S_IXGRP`` + * ``stat.S_IRWXO`` + * ``stat.S_IROTH`` + * ``stat.S_IWOTH`` + * ``stat.S_IXOTH`` Availability: Macintosh, Unix, Windows. @@ -1241,7 +1214,7 @@ Availability: Macintosh, Unix, Windows. -.. function:: walk(top[, topdown\ ``=True`` [, onerror\ ``=None``[, followlinks\ ``=False``]]]) +.. function:: walk(top[, topdown=True [, onerror=None[, followlinks=False]]]) .. index:: single: directory; walking Modified: doctools/trunk/Doc-3k/library/ossaudiodev.rst ============================================================================== --- doctools/trunk/Doc-3k/library/ossaudiodev.rst (original) +++ doctools/trunk/Doc-3k/library/ossaudiodev.rst Sun Aug 5 00:45:13 2007 @@ -78,11 +78,12 @@ module first looks in the environment variable :envvar:`AUDIODEV` for a device to use. If not found, it falls back to :file:`/dev/dsp`. - *mode* is one of ``'r'`` for read-only (record) access, ``'w'`` for write-only - (playback) access and ``'rw'`` for both. Since many sound cards only allow one - process to have the recorder or player open at a time, it is a good idea to open - the device only for the activity needed. Further, some sound cards are half- - duplex: they can be opened for reading or writing, but not both at once. + *mode* is one of ``'r'`` for read-only (record) access, ``'w'`` for + write-only (playback) access and ``'rw'`` for both. Since many sound cards + only allow one process to have the recorder or player open at a time, it is a + good idea to open the device only for the activity needed. Further, some + sound cards are half-duplex: they can be opened for reading or writing, but + not both at once. Note the unusual calling syntax: the *first* argument is optional, and the second is required. This is a historical artifact for compatibility with the Modified: doctools/trunk/Doc-3k/library/othergui.rst ============================================================================== --- doctools/trunk/Doc-3k/library/othergui.rst (original) +++ doctools/trunk/Doc-3k/library/othergui.rst Sun Aug 5 00:45:13 2007 @@ -61,18 +61,18 @@ Summerfield. `wxPython `_ - wxPython is a cross-platform GUI toolkit for Python that is built around the - popular `wxWidgets `_ (formerly - wxWindows) C++ toolkit. ?It provides a - native look and feel for applications on Windows, Mac OS X, and Unix systems by - using each platform's native widgets where ever possible, (GTK+ on Unix-like - systems). ?In addition to an extensive set of widgets, wxPython provides classes - for online documentation and context sensitive help, printing, HTML viewing, - low-level device context drawing, drag and drop, system clipboard access, an - XML-based resource format and more, including an ever growing library of user- - contributed modules. ?wxPython has a book, - `wxPython in Action `_, - by Noel Rappin and Robin Dunn. + wxPython is a cross-platform GUI toolkit for Python that is built around + the popular `wxWidgets `_ (formerly wxWindows) + C++ toolkit. ?It provides a native look and feel for applications on + Windows, Mac OS X, and Unix systems by using each platform's native + widgets where ever possible, (GTK+ on Unix-like systems). ?In addition to + an extensive set of widgets, wxPython provides classes for online + documentation and context sensitive help, printing, HTML viewing, + low-level device context drawing, drag and drop, system clipboard access, + an XML-based resource format and more, including an ever growing library + of user-contributed modules. ?wxPython has a book, `wxPython in Action + `_, by Noel Rappin and + Robin Dunn. PyGTK, PyQt, and wxPython, all have a modern look and feel and far more widgets and better documentation than Tkinter. In addition, Modified: doctools/trunk/Doc-3k/library/parser.rst ============================================================================== --- doctools/trunk/Doc-3k/library/parser.rst (original) +++ doctools/trunk/Doc-3k/library/parser.rst Sun Aug 5 00:45:13 2007 @@ -189,7 +189,7 @@ information is omitted if the flag is false or omitted. -.. function:: compileast(ast[, filename\ ``= ''``]) +.. function:: compileast(ast[, filename='']) .. index:: builtin: exec Modified: doctools/trunk/Doc-3k/library/pickle.rst ============================================================================== --- doctools/trunk/Doc-3k/library/pickle.rst (original) +++ doctools/trunk/Doc-3k/library/pickle.rst Sun Aug 5 00:45:13 2007 @@ -91,8 +91,8 @@ with the same internal structure. Perhaps the most obvious thing to do with these byte streams is to write them onto a file, but it is also conceivable to send them across a network or store them in a database. The module -:mod:`shelve` provides a simple interface to pickle and unpickle objects on DBM- -style database files. +:mod:`shelve` provides a simple interface to pickle and unpickle objects on +DBM-style database files. Data stream format @@ -689,9 +689,9 @@ output.close() -The following example reads the resulting pickled data. When reading a pickle- -containing file, you should open the file in binary mode because you can't be -sure if the ASCII or binary format was used. :: +The following example reads the resulting pickled data. When reading a +pickle-containing file, you should open the file in binary mode because you +can't be sure if the ASCII or binary format was used. :: import pprint, pickle Modified: doctools/trunk/Doc-3k/library/profile.rst ============================================================================== --- doctools/trunk/Doc-3k/library/profile.rst (original) +++ doctools/trunk/Doc-3k/library/profile.rst Sun Aug 5 00:45:13 2007 @@ -298,10 +298,10 @@ This function takes a single argument that can be passed to the :func:`exec` function, and an optional file name. In all cases this routine attempts to :func:`exec` its first argument, and gather profiling statistics from the - execution. If no file name is present, then this function automatically prints a - simple profiling report, sorted by the standard name string (file/line/function- - name) that is presented in each line. The following is a typical output from - such a call:: + execution. If no file name is present, then this function automatically + prints a simple profiling report, sorted by the standard name string + (file/line/function-name) that is presented in each line. The following is a + typical output from such a call:: 2706 function calls (2004 primitive calls) in 4.504 CPU seconds @@ -527,12 +527,12 @@ argument is also identical. Each caller is reported on its own line. The format differs slightly depending on the profiler that produced the stats: -* With :mod:`profile`, a number is shown in parentheses after each caller to - show how many times this specific call was made. For convenience, a second non- - parenthesized number repeats the cumulative time spent in the function at the - right. + * With :mod:`profile`, a number is shown in parentheses after each caller to + show how many times this specific call was made. For convenience, a second + non-parenthesized number repeats the cumulative time spent in the function + at the right. -* With :mod:`cProfile`, each caller is preceeded by three numbers: the number of + * With :mod:`cProfile`, each caller is preceeded by three numbers: the number of times this specific call was made, and the total and cumulative times spent in the current function while it was invoked by this specific caller. Modified: doctools/trunk/Doc-3k/library/pyexpat.rst ============================================================================== --- doctools/trunk/Doc-3k/library/pyexpat.rst (original) +++ doctools/trunk/Doc-3k/library/pyexpat.rst Sun Aug 5 00:45:13 2007 @@ -20,8 +20,8 @@ .. index:: single: Expat -The :mod:`xml.parsers.expat` module is a Python interface to the Expat non- -validating XML parser. The module provides a single extension type, +The :mod:`xml.parsers.expat` module is a Python interface to the Expat +non-validating XML parser. The module provides a single extension type, :class:`xmlparser`, that represents the current state of an XML parser. After an :class:`xmlparser` object has been created, various attributes of the object can be set to handler functions. When an XML document is then fed to the Modified: doctools/trunk/Doc-3k/library/random.rst ============================================================================== --- doctools/trunk/Doc-3k/library/random.rst (original) +++ doctools/trunk/Doc-3k/library/random.rst Sun Aug 5 00:45:13 2007 @@ -10,8 +10,8 @@ distributions. For integers, uniform selection from a range. For sequences, uniform selection -of a random element, a function to generate a random permutation of a list in- -place, and a function for random sampling without replacement. +of a random element, a function to generate a random permutation of a list +in-place, and a function for random sampling without replacement. On the real line, there are functions to compute uniform, normal (Gaussian), lognormal, negative exponential, gamma, and beta distributions. For generating Modified: doctools/trunk/Doc-3k/library/re.rst ============================================================================== --- doctools/trunk/Doc-3k/library/re.rst (original) +++ doctools/trunk/Doc-3k/library/re.rst Sun Aug 5 00:45:13 2007 @@ -134,10 +134,10 @@ ``{m,n}?`` Causes the resulting RE to match from *m* to *n* repetitions of the preceding - RE, attempting to match as *few* repetitions as possible. This is the non- - greedy version of the previous qualifier. For example, on the 6-character - string ``'aaaaaa'``, ``a{3,5}`` will match 5 ``'a'`` characters, while - ``a{3,5}?`` will only match 3 characters. + RE, attempting to match as *few* repetitions as possible. This is the + non-greedy version of the previous qualifier. For example, on the + 6-character string ``'aaaaaa'``, ``a{3,5}`` will match 5 ``'a'`` characters, + while ``a{3,5}?`` will only match 3 characters. ``'\'`` Either escapes special characters (permitting you to match characters like @@ -519,7 +519,7 @@ If you want to locate a match anywhere in *string*, use :meth:`search` instead. -.. function:: split(pattern, string[, maxsplit\ ``= 0``]) +.. function:: split(pattern, string[, maxsplit=0]) Split *string* by the occurrences of *pattern*. If capturing parentheses are used in *pattern*, then the text of all groups in the pattern are also returned @@ -673,7 +673,7 @@ :meth:`match` method. -.. method:: RegexObject.split(string[, maxsplit\ ``= 0``]) +.. method:: RegexObject.split(string[, maxsplit=0]) Identical to the :func:`split` function, using the compiled pattern. @@ -688,12 +688,12 @@ Identical to the :func:`finditer` function, using the compiled pattern. -.. method:: RegexObject.sub(repl, string[, count\ ``= 0``]) +.. method:: RegexObject.sub(repl, string[, count=0]) Identical to the :func:`sub` function, using the compiled pattern. -.. method:: RegexObject.subn(repl, string[, count\ ``= 0``]) +.. method:: RegexObject.subn(repl, string[, count=0]) Identical to the :func:`subn` function, using the compiled pattern. Modified: doctools/trunk/Doc-3k/library/repr.rst ============================================================================== --- doctools/trunk/Doc-3k/library/repr.rst (original) +++ doctools/trunk/Doc-3k/library/repr.rst Sun Aug 5 00:45:13 2007 @@ -65,8 +65,6 @@ .. versionadded:: 2.4 :attr:`maxset`, :attr:`maxfrozenset`, and :attr:`set`. - . - .. attribute:: Repr.maxlong Modified: doctools/trunk/Doc-3k/library/rfc822.rst ============================================================================== --- doctools/trunk/Doc-3k/library/rfc822.rst (original) +++ doctools/trunk/Doc-3k/library/rfc822.rst Sun Aug 5 00:45:13 2007 @@ -256,9 +256,9 @@ :class:`Message` instances also support a limited mapping interface. In particular: ``m[name]`` is like ``m.getheader(name)`` but raises :exc:`KeyError` -if there is no matching header; and ``len(m)``, ``m.get(name[, *default*])``, +if there is no matching header; and ``len(m)``, ``m.get(name[, default])``, ``m.has_key(name)``, ``m.keys()``, ``m.values()`` ``m.items()``, and -``m.setdefault(name[, *default*])`` act as expected, with the one difference +``m.setdefault(name[, default])`` act as expected, with the one difference that :meth:`setdefault` uses an empty string as the default value. :class:`Message` instances also support the mapping writable interface ``m[name] = value`` and ``del m[name]``. :class:`Message` objects do not support the Modified: doctools/trunk/Doc-3k/library/select.rst ============================================================================== --- doctools/trunk/Doc-3k/library/select.rst (original) +++ doctools/trunk/Doc-3k/library/select.rst Sun Aug 5 00:45:13 2007 @@ -33,16 +33,16 @@ .. function:: select(iwtd, owtd, ewtd[, timeout]) This is a straightforward interface to the Unix :cfunc:`select` system call. - The first three arguments are sequences of 'waitable objects': either integers - representing file descriptors or objects with a parameterless method named - :meth:`fileno` returning such an integer. The three sequences of waitable - objects are for input, output and 'exceptional conditions', respectively. Empty - sequences are allowed, but acceptance of three empty sequences is platform- - dependent. (It is known to work on Unix but not on Windows.) The optional - *timeout* argument specifies a time-out as a floating point number in seconds. - When the *timeout* argument is omitted the function blocks until at least one - file descriptor is ready. A time-out value of zero specifies a poll and never - blocks. + The first three arguments are sequences of 'waitable objects': either + integers representing file descriptors or objects with a parameterless method + named :meth:`fileno` returning such an integer. The three sequences of + waitable objects are for input, output and 'exceptional conditions', + respectively. Empty sequences are allowed, but acceptance of three empty + sequences is platform-dependent. (It is known to work on Unix but not on + Windows.) The optional *timeout* argument specifies a time-out as a floating + point number in seconds. When the *timeout* argument is omitted the function + blocks until at least one file descriptor is ready. A time-out value of zero + specifies a poll and never blocks. The return value is a triple of lists of objects that are ready: subsets of the first three arguments. When the time-out is reached without a file descriptor Modified: doctools/trunk/Doc-3k/library/sgmllib.rst ============================================================================== --- doctools/trunk/Doc-3k/library/sgmllib.rst (original) +++ doctools/trunk/Doc-3k/library/sgmllib.rst Sun Aug 5 00:45:13 2007 @@ -21,14 +21,14 @@ The :class:`SGMLParser` class is instantiated without arguments. The parser is hardcoded to recognize the following constructs: -* Opening and closing tags of the form ```` and + * Opening and closing tags of the form ```` and ````, respectively. -* Numeric character references of the form ``&#name;``. + * Numeric character references of the form ``&#name;``. -* Entity references of the form ``&name;``. + * Entity references of the form ``&name;``. -* SGML comments of the form ````. Note that spaces, tabs, and + * SGML comments of the form ````. Note that spaces, tabs, and newlines are allowed between the trailing ``>`` and the immediately preceding ``--``. Modified: doctools/trunk/Doc-3k/library/shelve.rst ============================================================================== --- doctools/trunk/Doc-3k/library/shelve.rst (original) +++ doctools/trunk/Doc-3k/library/shelve.rst Sun Aug 5 00:45:13 2007 @@ -15,7 +15,7 @@ lots of shared sub-objects. The keys are ordinary strings. -.. function:: open(filename[,flag='c'[,protocol=``None``[,writeback=``False``]]]) +.. function:: open(filename[, flag='c'[, protocol=None[, writeback=False]]]) Open a persistent dictionary. The filename specified is the base filename for the underlying database. As a side-effect, an extension may be added to the Modified: doctools/trunk/Doc-3k/library/shlex.rst ============================================================================== --- doctools/trunk/Doc-3k/library/shlex.rst (original) +++ doctools/trunk/Doc-3k/library/shlex.rst Sun Aug 5 00:45:13 2007 @@ -29,8 +29,8 @@ Split the string *s* using shell-like syntax. If *comments* is :const:`False` (the default), the parsing of comments in the given string will be disabled (setting the :attr:`commenters` member of the :class:`shlex` instance to the - empty string). This function operates in POSIX mode by default, but uses non- - POSIX mode if the *posix* argument is false. + empty string). This function operates in POSIX mode by default, but uses + non-POSIX mode if the *posix* argument is false. .. versionadded:: 2.3 @@ -292,7 +292,7 @@ next character that follows; * Enclosing characters in quotes which are not part of :attr:`escapedquotes` - (e.g. ``'''``) preserve the literal value of all characters within the quotes; + (e.g. ``"'"``) preserve the literal value of all characters within the quotes; * Enclosing characters in quotes which are part of :attr:`escapedquotes` (e.g. ``'"'``) preserves the literal value of all characters within the quotes, with Modified: doctools/trunk/Doc-3k/library/simplehttpserver.rst ============================================================================== --- doctools/trunk/Doc-3k/library/simplehttpserver.rst (original) +++ doctools/trunk/Doc-3k/library/simplehttpserver.rst Sun Aug 5 00:45:13 2007 @@ -7,9 +7,9 @@ .. sectionauthor:: Moshe Zadka -The :mod:`SimpleHTTPServer` module defines a request-handler class, interface- -compatible with :class:`BaseHTTPServer.BaseHTTPRequestHandler`, that serves -files only from a base directory. +The :mod:`SimpleHTTPServer` module defines a request-handler class, +interface-compatible with :class:`BaseHTTPServer.BaseHTTPRequestHandler`, that +serves files only from a base directory. The :mod:`SimpleHTTPServer` module defines the following class: Modified: doctools/trunk/Doc-3k/library/simplexmlrpcserver.rst ============================================================================== --- doctools/trunk/Doc-3k/library/simplexmlrpcserver.rst (original) +++ doctools/trunk/Doc-3k/library/simplexmlrpcserver.rst Sun Aug 5 00:45:13 2007 @@ -10,8 +10,8 @@ .. versionadded:: 2.2 -The :mod:`SimpleXMLRPCServer` module provides a basic server framework for XML- -RPC servers written in Python. Servers can either be free standing, using +The :mod:`SimpleXMLRPCServer` module provides a basic server framework for +XML-RPC servers written in Python. Servers can either be free standing, using :class:`SimpleXMLRPCServer`, or embedded in a CGI environment, using :class:`CGIXMLRPCRequestHandler`. Modified: doctools/trunk/Doc-3k/library/site.rst ============================================================================== --- doctools/trunk/Doc-3k/library/site.rst (original) +++ doctools/trunk/Doc-3k/library/site.rst Sun Aug 5 00:45:13 2007 @@ -42,10 +42,10 @@ triple: path; configuration; file For example, suppose ``sys.prefix`` and ``sys.exec_prefix`` are set to -:file:`/usr/local`. The Python |release| library is then installed in -:file:`/usr/local/lib/python|version|` (where only the first three characters of +:file:`/usr/local`. The Python X.Y library is then installed in +:file:`/usr/local/lib/python{X.Y}` (where only the first three characters of ``sys.version`` are used to form the installation path name). Suppose this has -a subdirectory :file:`/usr/local/lib/python|version|/site-packages` with three +a subdirectory :file:`/usr/local/lib/python{X.Y}/site-packages` with three subsubdirectories, :file:`foo`, :file:`bar` and :file:`spam`, and two path configuration files, :file:`foo.pth` and :file:`bar.pth`. Assume :file:`foo.pth` contains the following:: Modified: doctools/trunk/Doc-3k/library/socket.rst ============================================================================== --- doctools/trunk/Doc-3k/library/socket.rst (original) +++ doctools/trunk/Doc-3k/library/socket.rst Sun Aug 5 00:45:13 2007 @@ -686,11 +686,11 @@ Some notes on socket blocking and timeouts: A socket object can be in one of three modes: blocking, non-blocking, or timeout. Sockets are always created in -blocking mode. In blocking mode, operations block until complete. In non- -blocking mode, operations fail (with an error that is unfortunately system- -dependent) if they cannot be completed immediately. In timeout mode, operations -fail if they cannot be completed within the timeout specified for the socket. -The :meth:`setblocking` method is simply a shorthand for certain +blocking mode. In blocking mode, operations block until complete. In +non-blocking mode, operations fail (with an error that is unfortunately +system-dependent) if they cannot be completed immediately. In timeout mode, +operations fail if they cannot be completed within the timeout specified for the +socket. The :meth:`setblocking` method is simply a shorthand for certain :meth:`settimeout` calls. Timeout mode internally sets the socket in non-blocking mode. The blocking and Modified: doctools/trunk/Doc-3k/library/socketserver.rst ============================================================================== --- doctools/trunk/Doc-3k/library/socketserver.rst (original) +++ doctools/trunk/Doc-3k/library/socketserver.rst Sun Aug 5 00:45:13 2007 @@ -13,8 +13,9 @@ server. :class:`UDPServer` uses datagrams, which are discrete packets of information that may arrive out of order or be lost while in transit. The more infrequently used :class:`UnixStreamServer` and :class:`UnixDatagramServer` -classes are similar, but use Unix domain sockets; they're not available on non- -Unix platforms. For more details on network programming, consult a book such as +classes are similar, but use Unix domain sockets; they're not available on +non-Unix platforms. For more details on network programming, consult a book +such as W. Richard Steven's UNIX Network Programming or Ralph Davis's Win32 Network Programming. Modified: doctools/trunk/Doc-3k/library/sqlite3.rst ============================================================================== --- doctools/trunk/Doc-3k/library/sqlite3.rst (original) +++ doctools/trunk/Doc-3k/library/sqlite3.rst Sun Aug 5 00:45:13 2007 @@ -324,9 +324,9 @@ The first argument to the callback signifies what kind of operation is to be authorized. The second and third argument will be arguments or :const:`None` depending on the first argument. The 4th argument is the name of the database - ("main", "temp", etc.) if applicable. The 5th argument is the name of the inner- - most trigger or view that is responsible for the access attempt or :const:`None` - if this access attempt is directly from input SQL code. + ("main", "temp", etc.) if applicable. The 5th argument is the name of the + inner-most trigger or view that is responsible for the access attempt or + :const:`None` if this access attempt is directly from input SQL code. Please consult the SQLite documentation about the possible values for the first argument and the meaning of the second and third argument depending on the first @@ -344,12 +344,12 @@ .. literalinclude:: ../includes/sqlite3/row_factory.py - If returning a tuple doesn't suffice and you want name-based access to columns, - you should consider setting :attr:`row_factory` to the highly-optimized - :class:`sqlite3.Row` type. :class:`Row` provides both index-based and case- - insensitive name-based access to columns with almost no memory overhead. It will - probably be better than your own custom dictionary-based approach or even a - db_row based solution. + If returning a tuple doesn't suffice and you want name-based access to + columns, you should consider setting :attr:`row_factory` to the + highly-optimized :class:`sqlite3.Row` type. :class:`Row` provides both + index-based and case-insensitive name-based access to columns with almost no + memory overhead. It will probably be better than your own custom + dictionary-based approach or even a db_row based solution. .. % XXX what's a db_row-based solution? Modified: doctools/trunk/Doc-3k/library/stdtypes.rst ============================================================================== --- doctools/trunk/Doc-3k/library/stdtypes.rst (original) +++ doctools/trunk/Doc-3k/library/stdtypes.rst Sun Aug 5 00:45:13 2007 @@ -432,12 +432,13 @@ .. method:: container.__iter__() Return an iterator object. The object is required to support the iterator - protocol described below. If a container supports different types of iteration, - additional methods can be provided to specifically request iterators for those - iteration types. (An example of an object supporting multiple forms of - iteration would be a tree structure which supports both breadth-first and depth- - first traversal.) This method corresponds to the :attr:`tp_iter` slot of the - type structure for Python objects in the Python/C API. + protocol described below. If a container supports different types of + iteration, additional methods can be provided to specifically request + iterators for those iteration types. (An example of an object supporting + multiple forms of iteration would be a tree structure which supports both + breadth-first and depth-first traversal.) This method corresponds to the + :attr:`tp_iter` slot of the type structure for Python objects in the Python/C + API. The iterator objects themselves are required to support the following two methods, which together form the :dfn:`iterator protocol`: @@ -1177,9 +1178,9 @@ Notes: (1) - The alternate form causes a leading zero (``'0'``) to be inserted between left- - hand padding and the formatting of the number if the leading character of the - result is not already a zero. + The alternate form causes a leading zero (``'0'``) to be inserted between + left-hand padding and the formatting of the number if the leading character + of the result is not already a zero. (2) The alternate form causes a leading ``'0x'`` or ``'0X'`` (depending on whether @@ -1287,13 +1288,13 @@ | ``s.count(x)`` | return number of *i*'s for | | | | which ``s[i] == x`` | | +------------------------------+--------------------------------+---------------------+ -| ``s.index(x[, *i*[, *j*]])`` | return smallest *k* such that | \(4) | +| ``s.index(x[, i[, j]])`` | return smallest *k* such that | \(4) | | | ``s[k] == x`` and ``i <= k < | | | | j`` | | +------------------------------+--------------------------------+---------------------+ | ``s.insert(i, x)`` | same as ``s[i:i] = [x]`` | \(5) | +------------------------------+--------------------------------+---------------------+ -| ``s.pop([*i*])`` | same as ``x = s[i]; del s[i]; | \(6) | +| ``s.pop([i])`` | same as ``x = s[i]; del s[i]; | \(6) | | | return x`` | | +------------------------------+--------------------------------+---------------------+ | ``s.remove(x)`` | same as ``del s[s.index(x)]`` | \(4) | @@ -1301,8 +1302,8 @@ | ``s.reverse()`` | reverses the items of *s* in | \(7) | | | place | | +------------------------------+--------------------------------+---------------------+ -| ``s.sort([*cmp*[, *key*[, | sort the items of *s* in place | (7), (8), (9), (10) | -| *reverse*]]])`` | | | +| ``s.sort([cmp[, key[, | sort the items of *s* in place | (7), (8), (9), (10) | +| reverse]]])`` | | | +------------------------------+--------------------------------+---------------------+ .. index:: @@ -1614,23 +1615,23 @@ +--------------------------------+---------------------------------+-----------+ | ``a.keys()`` | a copy of *a*'s list of keys | \(3) | +--------------------------------+---------------------------------+-----------+ -| ``a.update([*b*])`` | updates *a* with key/value | \(9) | +| ``a.update([b])`` | updates *a* with key/value | \(9) | | | pairs from *b*, overwriting | | | | existing keys, returns ``None`` | | +--------------------------------+---------------------------------+-----------+ -| ``a.fromkeys(seq[, *value*])`` | Creates a new dictionary with | \(7) | +| ``a.fromkeys(seq[, value])`` | Creates a new dictionary with | \(7) | | | keys from *seq* and values set | | | | to *value* | | +--------------------------------+---------------------------------+-----------+ | ``a.values()`` | a copy of *a*'s list of values | \(3) | +--------------------------------+---------------------------------+-----------+ -| ``a.get(k[, *x*])`` | ``a[k]`` if ``k in a``, else | \(4) | +| ``a.get(k[, x])`` | ``a[k]`` if ``k in a``, else | \(4) | | | *x* | | +--------------------------------+---------------------------------+-----------+ -| ``a.setdefault(k[, *x*])`` | ``a[k]`` if ``k in a``, else | \(5) | +| ``a.setdefault(k[, x])`` | ``a[k]`` if ``k in a``, else | \(5) | | | *x* (also setting it) | | +--------------------------------+---------------------------------+-----------+ -| ``a.pop(k[, *x*])`` | ``a[k]`` if ``k in a``, else | \(8) | +| ``a.pop(k[, x])`` | ``a[k]`` if ``k in a``, else | \(8) | | | *x* (and remove k) | | +--------------------------------+---------------------------------+-----------+ | ``a.popitem()`` | remove and return an arbitrary | \(6) | @@ -1705,13 +1706,13 @@ (10) If a subclass of dict defines a method :meth:`__missing__`, if the key *k* is - not present, the *a*[*k*] operation calls that method with the key *k* as - argument. The *a*[*k*] operation then returns or raises whatever is returned or - raised by the :func:`__missing__`\ (*k*) call if the key is not present. No - other operations or methods invoke :meth:`__missing__`\ (). If - :meth:`__missing__` is not defined, :exc:`KeyError` is raised. - :meth:`__missing__` must be a method; it cannot be an instance variable. For an - example, see :mod:`collections`.\ :class:`defaultdict`. + not present, the ``a[k]`` operation calls that method with the key *k* as + argument. The ``a[k]`` operation then returns or raises whatever is returned + or raised by the ``__missing__(k)`` call if the key is not present. No other + operations or methods invoke :meth:`__missing__`. If :meth:`__missing__` is + not defined, :exc:`KeyError` is raised. :meth:`__missing__` must be a + method; it cannot be an instance variable. For an example, see + :class:`collections.defaultdict`. .. versionadded:: 2.5 @@ -1777,8 +1778,8 @@ .. method:: file.flush() - Flush the internal buffer, like ``stdio``'s :cfunc:`fflush`. This may be a no- - op on some file-like objects. + Flush the internal buffer, like ``stdio``'s :cfunc:`fflush`. This may be a + no-op on some file-like objects. .. method:: file.fileno() @@ -1857,11 +1858,11 @@ .. method:: file.readlines([sizehint]) Read until EOF using :meth:`readline` and return a list containing the lines - thus read. If the optional *sizehint* argument is present, instead of reading - up to EOF, whole lines totalling approximately *sizehint* bytes (possibly after - rounding up to an internal buffer size) are read. Objects implementing a file- - like interface may choose to ignore *sizehint* if it cannot be implemented, or - cannot be implemented efficiently. + thus read. If the optional *sizehint* argument is present, instead of + reading up to EOF, whole lines totalling approximately *sizehint* bytes + (possibly after rounding up to an internal buffer size) are read. Objects + implementing a file-like interface may choose to ignore *sizehint* if it + cannot be implemented, or cannot be implemented efficiently. .. method:: file.seek(offset[, whence]) @@ -1880,9 +1881,8 @@ Note that not all file objects are seekable. - .. versionchanged:: Passing float values as offset has been deprecated - - [2.6] + .. versionchanged:: 2.6 + Passing float values as offset has been deprecated .. method:: file.tell() @@ -1960,9 +1960,9 @@ .. attribute:: file.name If the file object was created using :func:`open`, the name of the file. - Otherwise, some string that indicates the source of the file object, of the form - ``<...>``. This is a read-only attribute and may not be present on all file- - like objects. + Otherwise, some string that indicates the source of the file object, of the + form ``<...>``. This is a read-only attribute and may not be present on all + file-like objects. .. attribute:: file.newlines @@ -2015,7 +2015,7 @@ to be provided for a context manager object to define a runtime context: -.. method:: context manager.__enter__() +.. method:: contextmanager.__enter__() Enter the runtime context and return either this object or another object related to the runtime context. The value returned by this method is bound to @@ -2034,7 +2034,7 @@ :keyword:`with` statement. -.. method:: context manager.__exit__(exc_type, exc_val, exc_tb) +.. method:: contextmanager.__exit__(exc_type, exc_val, exc_tb) Exit the runtime context and return a Boolean flag indicating if any expection that occurred should be suppressed. If an exception occurred while executing the @@ -2103,7 +2103,7 @@ Modules built into the interpreter are written like this: ````. If loaded from a file, they are written as ````. +'/usr/local/lib/pythonX.Y/os.pyc'>``. .. _typesobjects: @@ -2124,9 +2124,9 @@ Function objects are created by function definitions. The only operation on a function object is to call it: ``func(argument-list)``. -There are really two flavors of function objects: built-in functions and user- -defined functions. Both support the same operation (to call the function), but -the implementation is different, hence the different object types. +There are really two flavors of function objects: built-in functions and +user-defined functions. Both support the same operation (to call the function), +but the implementation is different, hence the different object types. See :ref:`function` for more information. Modified: doctools/trunk/Doc-3k/library/string.rst ============================================================================== --- doctools/trunk/Doc-3k/library/string.rst (original) +++ doctools/trunk/Doc-3k/library/string.rst Sun Aug 5 00:45:13 2007 @@ -109,13 +109,13 @@ * ``$$`` is an escape; it is replaced with a single ``$``. * ``$identifier`` names a substitution placeholder matching a mapping key of - "identifier". By default, "identifier" must spell a Python identifier. The - first non-identifier character after the ``$`` character terminates this - placeholder specification. + ``"identifier"``. By default, ``"identifier"`` must spell a Python + identifier. The first non-identifier character after the ``$`` character + terminates this placeholder specification. * ``${identifier}`` is equivalent to ``$identifier``. It is required when valid identifier characters follow the placeholder but are not part of the - placeholder, such as "${noun}ification". + placeholder, such as ``"${noun}ification"``. Any other appearance of ``$`` in the string will result in a :exc:`ValueError` being raised. @@ -190,9 +190,10 @@ expression, as the implementation will call :meth:`re.escape` on this string as needed. -* *idpattern* -- This is the regular expression describing the pattern for non- - braced placeholders (the braces will be added automatically as appropriate). - The default value is the regular expression ``[_a-z][_a-z0-9]*``. +* *idpattern* -- This is the regular expression describing the pattern for + non-braced placeholders (the braces will be added automatically as + appropriate). The default value is the regular expression + ``[_a-z][_a-z0-9]*``. Alternatively, you can provide the entire regular expression pattern by overriding the class attribute *pattern*. If you do this, the value must be a Modified: doctools/trunk/Doc-3k/library/stringprep.rst ============================================================================== --- doctools/trunk/Doc-3k/library/stringprep.rst (original) +++ doctools/trunk/Doc-3k/library/stringprep.rst Sun Aug 5 00:45:13 2007 @@ -50,14 +50,14 @@ .. function:: map_table_b2(code) - Return the mapped value for *code* according to tableB.2 (Mapping for case- - folding used with NFKC). + Return the mapped value for *code* according to tableB.2 (Mapping for + case-folding used with NFKC). .. function:: map_table_b3(code) - Return the mapped value for *code* according to tableB.3 (Mapping for case- - folding used with no normalization). + Return the mapped value for *code* according to tableB.3 (Mapping for + case-folding used with no normalization). .. function:: in_table_c11(code) Modified: doctools/trunk/Doc-3k/library/struct.rst ============================================================================== --- doctools/trunk/Doc-3k/library/struct.rst (original) +++ doctools/trunk/Doc-3k/library/struct.rst Sun Aug 5 00:45:13 2007 @@ -48,7 +48,7 @@ (``len(string)`` must equal ``calcsize(fmt)``). -.. function:: unpack_from(fmt, buffer[,offset ``= 0``]) +.. function:: unpack_from(fmt, buffer[,offset=0]) Unpack the *buffer* according to tthe given format. The result is a tuple even if it contains exactly one item. The *buffer* must contain at least the amount @@ -280,7 +280,7 @@ (``len(string)`` must equal :attr:`self.size`). -.. method:: Struct.unpack_from(buffer[,offset ``= 0``]) +.. method:: Struct.unpack_from(buffer[, offset=0]) Identical to the :func:`unpack_from` function, using the compiled format. (``len(buffer[offset:])`` must be at least :attr:`self.size`). Modified: doctools/trunk/Doc-3k/library/sys.rst ============================================================================== --- doctools/trunk/Doc-3k/library/sys.rst (original) +++ doctools/trunk/Doc-3k/library/sys.rst Sun Aug 5 00:45:13 2007 @@ -23,8 +23,8 @@ .. data:: byteorder An indicator of the native byte order. This will have the value ``'big'`` on - big-endian (most-significant byte first) platforms, and ``'little'`` on little- - endian (least-significant byte first) platforms. + big-endian (most-significant byte first) platforms, and ``'little'`` on + little-endian (least-significant byte first) platforms. .. versionadded:: 2.0 @@ -217,14 +217,14 @@ file names, or ``None`` if the system default encoding is used. The result value depends on the operating system: -* On Windows 9x, the encoding is "mbcs". + * On Windows 9x, the encoding is "mbcs". -* On Mac OS X, the encoding is "utf-8". + * On Mac OS X, the encoding is "utf-8". -* On Unix, the encoding is the user's preference according to the result of + * On Unix, the encoding is the user's preference according to the result of nl_langinfo(CODESET), or :const:`None` if the ``nl_langinfo(CODESET)`` failed. -* On Windows NT+, file names are Unicode natively, so no conversion is + * On Windows NT+, file names are Unicode natively, so no conversion is performed. :func:`getfilesystemencoding` still returns ``'mbcs'``, as this is the encoding that applications should use when they explicitly want to convert Unicode strings to byte strings that are equivalent when used as file names. @@ -335,8 +335,9 @@ more information.) The meaning of the variables is the same as that of the return values from - :func:`exc_info` above. (Since there is only one interactive thread, thread- - safety is not a concern for these variables, unlike for ``exc_type`` etc.) + :func:`exc_info` above. (Since there is only one interactive thread, + thread-safety is not a concern for these variables, unlike for ``exc_type`` + etc.) .. data:: maxint Modified: doctools/trunk/Doc-3k/library/tempfile.rst ============================================================================== --- doctools/trunk/Doc-3k/library/tempfile.rst (original) +++ doctools/trunk/Doc-3k/library/tempfile.rst Sun Aug 5 00:45:13 2007 @@ -32,7 +32,7 @@ The module defines the following user-callable functions: -.. function:: TemporaryFile([mode=``'w+b'``[, bufsize=``-1``[, suffix[, prefix[, dir]]]]]) +.. function:: TemporaryFile([mode='w+b'[, bufsize=-1[, suffix[, prefix[, dir]]]]]) Return a file (or file-like) object that can be used as a temporary storage area. The file is created using :func:`mkstemp`. It will be destroyed as soon @@ -50,7 +50,7 @@ The *dir*, *prefix* and *suffix* parameters are passed to :func:`mkstemp`. -.. function:: NamedTemporaryFile([mode=``'w+b'``[, bufsize=``-1``[, suffix[, prefix[, dir[, delete]]]]]]) +.. function:: NamedTemporaryFile([mode='w+b'[, bufsize=-1[, suffix[, prefix[, dir[, delete]]]]]]) This function operates exactly as :func:`TemporaryFile` does, except that the file is guaranteed to have a visible name in the file system (on Unix, the @@ -66,7 +66,7 @@ The *delete* parameter. -.. function:: SpooledTemporaryFile([max_size=``0``, [mode=``'w+b'``[, bufsize=``-1``[, suffix[, prefix[, dir]]]]]]) +.. function:: SpooledTemporaryFile([max_size=0, [mode='w+b'[, bufsize=-1[, suffix[, prefix[, dir]]]]]]) This function operates exactly as :func:`TemporaryFile` does, except that data is spooled in memory until the file size exceeds *max_size*, or until the file's @@ -98,13 +98,13 @@ If *prefix* is specified, the file name will begin with that prefix; otherwise, a default prefix is used. - If *dir* is specified, the file will be created in that directory; otherwise, a - default directory is used. The default directory is chosen from a platform- - dependent list, but the user of the application can control the directory - location by setting the *TMPDIR*, *TEMP* or *TMP* environment variables. There - is thus no guarantee that the generated filename will have any nice properties, - such as not requiring quoting when passed to external commands via - ``os.popen()``. + If *dir* is specified, the file will be created in that directory; otherwise, + a default directory is used. The default directory is chosen from a + platform-dependent list, but the user of the application can control the + directory location by setting the *TMPDIR*, *TEMP* or *TMP* environment + variables. There is thus no guarantee that the generated filename will have + any nice properties, such as not requiring quoting when passed to external + commands via ``os.popen()``. If *text* is specified, it indicates whether to open the file in binary mode (the default) or text mode. On some platforms, this makes no difference. @@ -162,24 +162,24 @@ Python searches a standard list of directories and sets *tempdir* to the first one which the calling user can create files in. The list is: -#. The directory named by the :envvar:`TMPDIR` environment variable. + #. The directory named by the :envvar:`TMPDIR` environment variable. -#. The directory named by the :envvar:`TEMP` environment variable. + #. The directory named by the :envvar:`TEMP` environment variable. -#. The directory named by the :envvar:`TMP` environment variable. + #. The directory named by the :envvar:`TMP` environment variable. -#. A platform-specific location: + #. A platform-specific location: -* On RiscOS, the directory named by the :envvar:`Wimp$ScrapDir` environment + * On RiscOS, the directory named by the :envvar:`Wimp$ScrapDir` environment variable. -* On Windows, the directories :file:`C:$\\TEMP`, :file:`C:$\\TMP`, + * On Windows, the directories :file:`C:$\\TEMP`, :file:`C:$\\TMP`, :file:`\\TEMP`, and :file:`\\TMP`, in that order. -* On all other platforms, the directories :file:`/tmp`, :file:`/var/tmp`, and + * On all other platforms, the directories :file:`/tmp`, :file:`/var/tmp`, and :file:`/usr/tmp`, in that order. -#. As a last resort, the current working directory. + #. As a last resort, the current working directory. .. function:: gettempdir() Modified: doctools/trunk/Doc-3k/library/termios.rst ============================================================================== --- doctools/trunk/Doc-3k/library/termios.rst (original) +++ doctools/trunk/Doc-3k/library/termios.rst Sun Aug 5 00:45:13 2007 @@ -31,12 +31,12 @@ .. function:: tcgetattr(fd) Return a list containing the tty attributes for file descriptor *fd*, as - follows: ``[``*iflag*, *oflag*, *cflag*, *lflag*, *ispeed*, *ospeed*, *cc*``]`` - where *cc* is a list of the tty special characters (each a string of length 1, - except the items with indices :const:`VMIN` and :const:`VTIME`, which are - integers when these fields are defined). The interpretation of the flags and - the speeds as well as the indexing in the *cc* array must be done using the - symbolic constants defined in the :mod:`termios` module. + follows: ``[iflag, oflag, cflag, lflag, ispeed, ospeed, cc]`` where *cc* is a + list of the tty special characters (each a string of length 1, except the + items with indices :const:`VMIN` and :const:`VTIME`, which are integers when + these fields are defined). The interpretation of the flags and the speeds as + well as the indexing in the *cc* array must be done using the symbolic + constants defined in the :mod:`termios` module. .. function:: tcsetattr(fd, when, attributes) Modified: doctools/trunk/Doc-3k/library/textwrap.rst ============================================================================== --- doctools/trunk/Doc-3k/library/textwrap.rst (original) +++ doctools/trunk/Doc-3k/library/textwrap.rst Sun Aug 5 00:45:13 2007 @@ -147,7 +147,7 @@ This is generally desired for text in a monospaced font. However, the sentence detection algorithm is imperfect: it assumes that a sentence ending consists of a lowercase letter followed by one of ``'.'``, ``'!'``, or ``'?'``, possibly - followed by one of ``'"'`` or ``'''``, followed by a space. One problem with + followed by one of ``'"'`` or ``"'"``, followed by a space. One problem with this is algorithm is that it is unable to detect the difference between "Dr." in :: @@ -160,9 +160,9 @@ :attr:`fix_sentence_endings` is false by default. Since the sentence detection algorithm relies on ``string.lowercase`` for the - definition of "lowercase letter," and a convention of using two spaces after a - period to separate sentences on the same line, it is specific to English- - language texts. + definition of "lowercase letter," and a convention of using two spaces after + a period to separate sentences on the same line, it is specific to + English-language texts. .. attribute:: TextWrapper.break_long_words @@ -173,8 +173,8 @@ (Long words will be put on a line by themselves, in order to minimize the amount by which :attr:`width` is exceeded.) -:class:`TextWrapper` also provides two public methods, analogous to the module- -level convenience functions: +:class:`TextWrapper` also provides two public methods, analogous to the +module-level convenience functions: .. method:: TextWrapper.wrap(text) Modified: doctools/trunk/Doc-3k/library/threading.rst ============================================================================== --- doctools/trunk/Doc-3k/library/threading.rst (original) +++ doctools/trunk/Doc-3k/library/threading.rst Sun Aug 5 00:45:13 2007 @@ -197,7 +197,7 @@ All methods are executed atomically. -.. method:: Lock.acquire([blocking\ ``= 1``]) +.. method:: Lock.acquire([blocking=1]) Acquire a lock, blocking or non-blocking. @@ -244,7 +244,7 @@ :meth:`acquire` to proceed. -.. method:: RLock.acquire([blocking\ ``= 1``]) +.. method:: RLock.acquire([blocking=1]) Acquire a lock, blocking or non-blocking. Modified: doctools/trunk/Doc-3k/library/timeit.rst ============================================================================== --- doctools/trunk/Doc-3k/library/timeit.rst (original) +++ doctools/trunk/Doc-3k/library/timeit.rst Sun Aug 5 00:45:13 2007 @@ -20,7 +20,7 @@ The module defines the following public class: -.. class:: Timer([stmt=``'pass'`` [, setup=``'pass'`` [, timer=]]]) +.. class:: Timer([stmt='pass' [, setup='pass' [, timer=]]]) Class for timing execution speed of small code snippets. @@ -40,7 +40,7 @@ larger in this case because of the extra function calls. -.. method:: Timer.print_exc([file=:const:`None`]) +.. method:: Timer.print_exc([file=None]) Helper to print a traceback from the timed code. @@ -57,7 +57,7 @@ traceback is sent; it defaults to ``sys.stderr``. -.. method:: Timer.repeat([repeat\ ``=3`` [, number\ ``=1000000``]]) +.. method:: Timer.repeat([repeat=3 [, number=1000000]]) Call :meth:`timeit` a few times. @@ -78,7 +78,7 @@ and apply common sense rather than statistics. -.. method:: Timer.timeit([number\ ``=1000000``]) +.. method:: Timer.timeit([number=1000000]) Time *number* executions of the main statement. This executes the setup statement once, and then returns the time it takes to execute the main statement @@ -99,7 +99,7 @@ Starting with version 2.6, the module also defines two convenience functions: -.. function:: repeat(stmt[, setup[, timer[, repeat\ ``=3`` [, number\ ``=1000000``]]]]) +.. function:: repeat(stmt[, setup[, timer[, repeat=3 [, number=1000000]]]]) Create a :class:`Timer` instance with the given statement, setup code and timer function and run its :meth:`repeat` method with the given repeat count and @@ -108,7 +108,7 @@ .. versionadded:: 2.6 -.. function:: timeit(stmt[, setup[, timer[, number\ ``=1000000``]]]) +.. function:: timeit(stmt[, setup[, timer[, number=1000000]]]) Create a :class:`Timer` instance with the given statement, setup code and timer function and run its :meth:`timeit` method with *number* executions. Modified: doctools/trunk/Doc-3k/library/tix.rst ============================================================================== --- doctools/trunk/Doc-3k/library/tix.rst (original) +++ doctools/trunk/Doc-3k/library/tix.rst Sun Aug 5 00:45:13 2007 @@ -263,10 +263,10 @@ .. class:: DirSelectBox() - The :class:`DirSelectBox` is similar to the standard Motif(TM) directory- - selection box. It is generally used for the user to choose a directory. - DirSelectBox stores the directories mostly recently selected into a ComboBox - widget so that they can be quickly selected again. + The :class:`DirSelectBox` is similar to the standard Motif(TM) + directory-selection box. It is generally used for the user to choose a + directory. DirSelectBox stores the directories mostly recently selected into + a ComboBox widget so that they can be quickly selected again. .. class:: ExFileSelectBox() Modified: doctools/trunk/Doc-3k/library/tkinter.rst ============================================================================== --- doctools/trunk/Doc-3k/library/tkinter.rst (original) +++ doctools/trunk/Doc-3k/library/tkinter.rst Sun Aug 5 00:45:13 2007 @@ -798,21 +798,21 @@ Some options and methods for menus manipulate specific menu entries. Anytime a menu index is needed for an option or a parameter, you may pass in: -* an integer which refers to the numeric position of the entry in the widget, + * an integer which refers to the numeric position of the entry in the widget, counted from the top, starting with 0; -* the string ``'active'``, which refers to the menu position that is currently + * the string ``'active'``, which refers to the menu position that is currently under the cursor; -* the string ``"last"`` which refers to the last menu item; + * the string ``"last"`` which refers to the last menu item; -* An integer preceded by ``@``, as in ``@6``, where the integer is interpreted + * An integer preceded by ``@``, as in ``@6``, where the integer is interpreted as a y pixel coordinate in the menu's coordinate system; -* the string ``"none"``, which indicates no menu entry at all, most often used + * the string ``"none"``, which indicates no menu entry at all, most often used with menu.activate() to deactivate all entries, and finally, -* a text string that is pattern matched against the label of the menu entry, as + * a text string that is pattern matched against the label of the menu entry, as scanned from the top of the menu to the bottom. Note that this index type is considered after all the others, which means that matches for menu items labelled ``last``, ``active``, or ``none`` may be interpreted as the above Modified: doctools/trunk/Doc-3k/library/turtle.rst ============================================================================== --- doctools/trunk/Doc-3k/library/turtle.rst (original) +++ doctools/trunk/Doc-3k/library/turtle.rst Sun Aug 5 00:45:13 2007 @@ -11,9 +11,9 @@ .. sectionauthor:: Moshe Zadka -The :mod:`turtle` module provides turtle graphics primitives, in both an object- -oriented and procedure-oriented ways. Because it uses :mod:`Tkinter` for the -underlying graphics, it needs a version of python installed with Tk support. +The :mod:`turtle` module provides turtle graphics primitives, in both an +object-oriented and procedure-oriented ways. Because it uses :mod:`Tkinter` for +the underlying graphics, it needs a version of python installed with Tk support. The procedural interface uses a pen and a canvas which are automagically created when any of the functions are called. @@ -35,16 +35,16 @@ Sets the size and position of the main window. Keywords are: -* ``width``: either a size in pixels or a fraction of the screen. The default is + * ``width``: either a size in pixels or a fraction of the screen. The default is 50% of the screen. -* ``height``: either a size in pixels or a fraction of the screen. The default + * ``height``: either a size in pixels or a fraction of the screen. The default is 50% of the screen. -* ``startx``: starting position in pixels from the left edge of the screen. + * ``startx``: starting position in pixels from the left edge of the screen. ``None`` is the default value and centers the window horizontally on screen. -* ``starty``: starting position in pixels from the top edge of the screen. + * ``starty``: starting position in pixels from the top edge of the screen. ``None`` is the default value and centers the window vertically on screen. Examples:: Modified: doctools/trunk/Doc-3k/library/urllib.rst ============================================================================== --- doctools/trunk/Doc-3k/library/urllib.rst (original) +++ doctools/trunk/Doc-3k/library/urllib.rst Sun Aug 5 00:45:13 2007 @@ -12,10 +12,10 @@ single: URL This module provides a high-level interface for fetching data across the World -Wide Web. In particular, the :func:`urlopen` function is similar to the built- -in function :func:`open`, but accepts Universal Resource Locators (URLs) instead -of filenames. Some restrictions apply --- it can only open URLs for reading, -and no seek operations are available. +Wide Web. In particular, the :func:`urlopen` function is similar to the +built-in function :func:`open`, but accepts Universal Resource Locators (URLs) +instead of filenames. Some restrictions apply --- it can only open URLs for +reading, and no seek operations are available. It defines the following public functions: @@ -42,16 +42,16 @@ .. index:: module: mimetools The :meth:`info` method returns an instance of the class - :class:`mimetools.Message` containing meta-information associated with the URL. - When the method is HTTP, these headers are those returned by the server at the - head of the retrieved HTML page (including Content-Length and Content-Type). - When the method is FTP, a Content-Length header will be present if (as is now - usual) the server passed back a file length in response to the FTP retrieval - request. A Content-Type header will be present if the MIME type can be guessed. - When the method is local-file, returned headers will include a Date representing - the file's last-modified time, a Content-Length giving file size, and a Content- - Type containing a guess at the file's type. See also the description of the - :mod:`mimetools` module. + :class:`mimetools.Message` containing meta-information associated with the + URL. When the method is HTTP, these headers are those returned by the server + at the head of the retrieved HTML page (including Content-Length and + Content-Type). When the method is FTP, a Content-Length header will be + present if (as is now usual) the server passed back a file length in response + to the FTP retrieval request. A Content-Type header will be present if the + MIME type can be guessed. When the method is local-file, returned headers + will include a Date representing the file's last-modified time, a + Content-Length giving file size, and a Content-Type containing a guess at the + file's type. See also the description of the :mod:`mimetools` module. The :meth:`geturl` method returns the real URL of the page. In some cases, the HTTP server redirects a client to another URL. The :func:`urlopen` function Modified: doctools/trunk/Doc-3k/library/urllib2.rst ============================================================================== --- doctools/trunk/Doc-3k/library/urllib2.rst (original) +++ doctools/trunk/Doc-3k/library/urllib2.rst Sun Aug 5 00:45:13 2007 @@ -33,9 +33,9 @@ This function returns a file-like object with two additional methods: -* :meth:`geturl` --- return the URL of the resource retrieved + * :meth:`geturl` --- return the URL of the resource retrieved -* :meth:`info` --- return the meta-information of the page, as a dictionary-like + * :meth:`info` --- return the meta-information of the page, as a dictionary-like object Raises :exc:`URLError` on errors. @@ -87,9 +87,10 @@ .. exception:: HTTPError - A subclass of :exc:`URLError`, it can also function as a non-exceptional file- - like return value (the same thing that :func:`urlopen` returns). This is useful - when handling exotic HTTP errors, such as requests for authentication. + A subclass of :exc:`URLError`, it can also function as a non-exceptional + file-like return value (the same thing that :func:`urlopen` returns). This + is useful when handling exotic HTTP errors, such as requests for + authentication. The following classes are provided: @@ -365,20 +366,20 @@ are searched, and added to the possible chains (note that HTTP errors are a special case). -* :meth:`protocol_open` --- signal that the handler knows how to open *protocol* + * :meth:`protocol_open` --- signal that the handler knows how to open *protocol* URLs. -* :meth:`http_error_type` --- signal that the handler knows how to handle HTTP + * :meth:`http_error_type` --- signal that the handler knows how to handle HTTP errors with HTTP error code *type*. -* :meth:`protocol_error` --- signal that the handler knows how to handle errors + * :meth:`protocol_error` --- signal that the handler knows how to handle errors from (non-\ ``http``) *protocol*. -* :meth:`protocol_request` --- signal that the handler knows how to pre-process + * :meth:`protocol_request` --- signal that the handler knows how to pre-process *protocol* requests. -* :meth:`protocol_response` --- signal that the handler knows how to post- - process *protocol* responses. + * :meth:`protocol_response` --- signal that the handler knows how to + post-process *protocol* responses. .. method:: OpenerDirector.open(url[, data][, timeout]) Modified: doctools/trunk/Doc-3k/library/user.rst ============================================================================== --- doctools/trunk/Doc-3k/library/user.rst (original) +++ doctools/trunk/Doc-3k/library/user.rst Sun Aug 5 00:45:13 2007 @@ -51,8 +51,8 @@ (The three-argument form of :func:`getattr` is used in case the user has not defined ``spam_verbose`` in their :file:`.pythonrc.py` file.) -Programs with extensive customization needs are better off reading a program- -specific customization file. +Programs with extensive customization needs are better off reading a +program-specific customization file. Programs with security or privacy concerns should *not* import this module; a user can easily break into a program by placing arbitrary code in the Modified: doctools/trunk/Doc-3k/library/winsound.rst ============================================================================== --- doctools/trunk/Doc-3k/library/winsound.rst (original) +++ doctools/trunk/Doc-3k/library/winsound.rst Sun Aug 5 00:45:13 2007 @@ -41,7 +41,7 @@ :exc:`RuntimeError` is raised. -.. function:: MessageBeep([type=``MB_OK``]) +.. function:: MessageBeep([type=MB_OK]) Call the underlying :cfunc:`MessageBeep` function from the Platform API. This plays a sound as specified in the registry. The *type* argument specifies which Modified: doctools/trunk/Doc-3k/library/wsgiref.rst ============================================================================== --- doctools/trunk/Doc-3k/library/wsgiref.rst (original) +++ doctools/trunk/Doc-3k/library/wsgiref.rst Sun Aug 5 00:45:13 2007 @@ -234,7 +234,7 @@ :mod:`wsgiref.util`.) -.. function:: make_server(host, port, app [, server_class=WSGIServer [, handler_class=:class:`WSGIRequestHandler`]]) +.. function:: make_server(host, port, app [, server_class=WSGIServer [, handler_class=WSGIRequestHandler]]) Create a new WSGI server listening on *host* and *port*, accepting connections for *app*. The return value is an instance of the supplied *server_class*, and Modified: doctools/trunk/Doc-3k/library/xml.dom.rst ============================================================================== --- doctools/trunk/Doc-3k/library/xml.dom.rst (original) +++ doctools/trunk/Doc-3k/library/xml.dom.rst Sun Aug 5 00:45:13 2007 @@ -136,8 +136,8 @@ .. data:: XMLNS_NAMESPACE The namespace URI for namespace declarations, as defined by `Document Object - Model (DOM) Level 2 Core Specification `_ (section 1.1.8). + Model (DOM) Level 2 Core Specification + `_ (section 1.1.8). .. versionadded:: 2.2 @@ -281,12 +281,12 @@ .. attribute:: Node.previousSibling - The node that immediately precedes this one with the same parent. For instance - the element with an end-tag that comes just before the *self* element's start- - tag. Of course, XML documents are made up of more than just elements so the - previous sibling could be text, a comment, or something else. If this node is - the first child of the parent, this attribute will be ``None``. This is a read- - only attribute. + The node that immediately precedes this one with the same parent. For + instance the element with an end-tag that comes just before the *self* + element's start-tag. Of course, XML documents are made up of more than just + elements so the previous sibling could be text, a comment, or something else. + If this node is the first child of the parent, this attribute will be + ``None``. This is a read-only attribute. .. attribute:: Node.nextSibling Modified: doctools/trunk/Doc-3k/library/xml.etree.elementtree.rst ============================================================================== --- doctools/trunk/Doc-3k/library/xml.etree.elementtree.rst (original) +++ doctools/trunk/Doc-3k/library/xml.etree.elementtree.rst Sun Aug 5 00:45:13 2007 @@ -354,8 +354,8 @@ .. method:: ElementTree.write(file[, encoding]) Writes the element tree to a file, as XML. *file* is a file name, or a file - object opened for writing. *encoding* is the output encoding (default is US- - ASCII). + object opened for writing. *encoding* is the output encoding (default is + US-ASCII). .. _elementtree-qname-objects: Modified: doctools/trunk/Doc-3k/library/xml.sax.handler.rst ============================================================================== --- doctools/trunk/Doc-3k/library/xml.sax.handler.rst (original) +++ doctools/trunk/Doc-3k/library/xml.sax.handler.rst Sun Aug 5 00:45:13 2007 @@ -60,11 +60,11 @@ .. data:: feature_namespace_prefixes - Value: ``"http://xml.org/sax/features/namespace-prefixes"`` --- true: Report - the original prefixed names and attributes used for Namespace declarations. --- - false: Do not report attributes used for Namespace declarations, and optionally - do not report original prefixed names (default). --- access: (parsing) read- - only; (not parsing) read/write + Value: ``"http://xml.org/sax/features/namespace-prefixes"`` --- true: Report + the original prefixed names and attributes used for Namespace + declarations. --- false: Do not report attributes used for Namespace + declarations, and optionally do not report original prefixed names + (default). --- access: (parsing) read-only; (not parsing) read/write .. data:: feature_string_interning @@ -78,10 +78,10 @@ .. data:: feature_validation - Value: ``"http://xml.org/sax/features/validation"`` --- true: Report all - validation errors (implies external-general-entities and external-parameter- - entities). --- false: Do not report validation errors. --- access: (parsing) - read-only; (not parsing) read/write + Value: ``"http://xml.org/sax/features/validation"`` --- true: Report all + validation errors (implies external-general-entities and + external-parameter-entities). --- false: Do not report validation errors. --- + access: (parsing) read-only; (not parsing) read/write .. data:: feature_external_ges Modified: doctools/trunk/Doc-3k/library/xml.sax.reader.rst ============================================================================== --- doctools/trunk/Doc-3k/library/xml.sax.reader.rst (original) +++ doctools/trunk/Doc-3k/library/xml.sax.reader.rst Sun Aug 5 00:45:13 2007 @@ -288,8 +288,8 @@ .. method:: InputSource.setByteStream(bytefile) - Set the byte stream (a Python file-like object which does not perform byte-to- - character conversion) for this input source. + Set the byte stream (a Python file-like object which does not perform + byte-to-character conversion) for this input source. The SAX parser will ignore this if there is also a character stream specified, but it will use a byte stream in preference to opening a URI connection itself. Modified: doctools/trunk/Doc-3k/library/xml.sax.utils.rst ============================================================================== --- doctools/trunk/Doc-3k/library/xml.sax.utils.rst (original) +++ doctools/trunk/Doc-3k/library/xml.sax.utils.rst Sun Aug 5 00:45:13 2007 @@ -37,13 +37,14 @@ .. function:: quoteattr(data[, entities]) - Similar to :func:`escape`, but also prepares *data* to be used as an attribute - value. The return value is a quoted version of *data* with any additional - required replacements. :func:`quoteattr` will select a quote character based on - the content of *data*, attempting to avoid encoding any quote characters in the - string. If both single- and double-quote characters are already in *data*, the - double-quote characters will be encoded and *data* will be wrapped in double- - quotes. The resulting string can be used directly as an attribute value:: + Similar to :func:`escape`, but also prepares *data* to be used as an + attribute value. The return value is a quoted version of *data* with any + additional required replacements. :func:`quoteattr` will select a quote + character based on the content of *data*, attempting to avoid encoding any + quote characters in the string. If both single- and double-quote characters + are already in *data*, the double-quote characters will be encoded and *data* + will be wrapped in double-quotes. The resulting string can be used directly + as an attribute value:: >>> print "" % quoteattr("ab ' cd \" ef") Modified: doctools/trunk/Doc-3k/license.rst ============================================================================== --- doctools/trunk/Doc-3k/license.rst (original) +++ doctools/trunk/Doc-3k/license.rst Sun Aug 5 00:45:13 2007 @@ -105,7 +105,7 @@ ============================================================ -.. centered:: **PSF LICENSE AGREEMENT FOR PYTHON |release|** +.. centered:: **PSF LICENSE AGREEMENT FOR PYTHON** |release| #. This LICENSE AGREEMENT is between the Python Software Foundation ("PSF"), and the Individual or Organization ("Licensee") accessing and otherwise using Python Modified: doctools/trunk/Doc-3k/maclib/using.rst ============================================================================== --- doctools/trunk/Doc-3k/maclib/using.rst (original) +++ doctools/trunk/Doc-3k/maclib/using.rst Sun Aug 5 00:45:13 2007 @@ -43,8 +43,8 @@ The Apple-provided build of Python is installed in :file:`/System/Library/Frameworks/Python.framework` and :file:`/usr/bin/python`, -respectively. You should never modify or delete these, as they are Apple- -controlled and are used by Apple- or third-party software. +respectively. You should never modify or delete these, as they are +Apple-controlled and are used by Apple- or third-party software. IDLE includes a help menu that allows you to access Python documentation. If you are completely new to Python you should start reading the tutorial introduction Modified: doctools/trunk/Doc-3k/reference/datamodel.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/datamodel.rst (original) +++ doctools/trunk/Doc-3k/reference/datamodel.rst Sun Aug 5 00:45:13 2007 @@ -250,10 +250,10 @@ single: item selection single: subscription - These represent finite ordered sets indexed by non-negative numbers. The built- - in function :func:`len` returns the number of items of a sequence. When the - length of a sequence is *n*, the index set contains the numbers 0, 1, ..., - *n*-1. Item *i* of sequence *a* is selected by ``a[i]``. + These represent finite ordered sets indexed by non-negative numbers. The + built-in function :func:`len` returns the number of items of a sequence. When + the length of a sequence is *n*, the index set contains the numbers 0, 1, + ..., *n*-1. Item *i* of sequence *a* is selected by ``a[i]``. .. index:: single: slicing @@ -595,13 +595,13 @@ single: im_self (method attribute) When a user-defined method object is created by retrieving a user-defined - function object from a class, its :attr:`im_self` attribute is ``None`` and the - method object is said to be unbound. When one is created by retrieving a user- - defined function object from a class via one of its instances, its - :attr:`im_self` attribute is the instance, and the method object is said to be - bound. In either case, the new method's :attr:`im_class` attribute is the class - from which the retrieval takes place, and its :attr:`im_func` attribute is the - original function object. + function object from a class, its :attr:`im_self` attribute is ``None`` + and the method object is said to be unbound. When one is created by + retrieving a user-defined function object from a class via one of its + instances, its :attr:`im_self` attribute is the instance, and the method + object is said to be bound. In either case, the new method's + :attr:`im_class` attribute is the class from which the retrieval takes + place, and its :attr:`im_func` attribute is the original function object. .. index:: single: im_func (method attribute) @@ -667,14 +667,14 @@ object: function pair: C; language - A built-in function object is a wrapper around a C function. Examples of built- - in functions are :func:`len` and :func:`math.sin` (:mod:`math` is a standard - built-in module). The number and type of the arguments are determined by the C - function. Special read-only attributes: :attr:`__doc__` is the function's - documentation string, or ``None`` if unavailable; :attr:`__name__` is the - function's name; :attr:`__self__` is set to ``None`` (but see the next item); - :attr:`__module__` is the name of the module the function was defined in or - ``None`` if unavailable. + A built-in function object is a wrapper around a C function. Examples of + built-in functions are :func:`len` and :func:`math.sin` (:mod:`math` is a + standard built-in module). The number and type of the arguments are + determined by the C function. Special read-only attributes: + :attr:`__doc__` is the function's documentation string, or ``None`` if + unavailable; :attr:`__name__` is the function's name; :attr:`__self__` is + set to ``None`` (but see the next item); :attr:`__module__` is the name of + the module the function was defined in or ``None`` if unavailable. Built-in methods .. index:: @@ -753,12 +753,12 @@ of the shared library file. Classes - Class objects are created by class definitions (see section :ref:`class`). - A class has a namespace implemented by a dictionary object. Class - attribute references are translated to lookups in this dictionary, e.g., ``C.x`` - is translated to ``C.__dict__["x"]``. When the attribute name is not found - there, the attribute search continues in the base classes. The search is depth- - first, left-to-right in the order of occurrence in the base class list. + Class objects are created by class definitions (see section :ref:`class`). A + class has a namespace implemented by a dictionary object. Class attribute + references are translated to lookups in this dictionary, e.g., ``C.x`` is + translated to ``C.__dict__["x"]``. When the attribute name is not found + there, the attribute search continues in the base classes. The search is + depth-first, left-to-right in the order of occurrence in the base class list. .. index:: object: class @@ -769,17 +769,17 @@ object: dictionary pair: class; attribute - When a class attribute reference (for class :class:`C`, say) would yield a user- - defined function object or an unbound user-defined method object whose + When a class attribute reference (for class :class:`C`, say) would yield a + user-defined function object or an unbound user-defined method object whose associated class is either :class:`C` or one of its base classes, it is transformed into an unbound user-defined method object whose :attr:`im_class` attribute is :class:`C`. When it would yield a class method object, it is - transformed into a bound user-defined method object whose :attr:`im_class` and - :attr:`im_self` attributes are both :class:`C`. When it would yield a static - method object, it is transformed into the object wrapped by the static method - object. See section :ref:`descriptors` for another way in which attributes - retrieved from a class may differ from those actually contained in its - :attr:`__dict__`. + transformed into a bound user-defined method object whose :attr:`im_class` + and :attr:`im_self` attributes are both :class:`C`. When it would yield a + static method object, it is transformed into the object wrapped by the static + method object. See section :ref:`descriptors` for another way in which + attributes retrieved from a class may differ from those actually contained in + its :attr:`__dict__`. .. index:: triple: class; attribute; assignment @@ -2036,14 +2036,14 @@ These methods are called to implement the augmented arithmetic operations (``+=``, ``-=``, ``*=``, ``/=``, ``//=``, ``%=``, ``**=``, ``<<=``, ``>>=``, - ``&=``, ``^=``, ``|=``). These methods should attempt to do the operation in- - place (modifying *self*) and return the result (which could be, but does not - have to be, *self*). If a specific method is not defined, the augmented + ``&=``, ``^=``, ``|=``). These methods should attempt to do the operation + in-place (modifying *self*) and return the result (which could be, but does + not have to be, *self*). If a specific method is not defined, the augmented operation falls back to the normal methods. For instance, to evaluate the expression *x*``+=``*y*, where *x* is an instance of a class that has an - :meth:`__iadd__` method, ``x.__iadd__(y)`` is called. If *x* is an instance of - a class that does not define a :meth:`__iadd__` method, ``x.__add__(y)`` and - ``y.__radd__(x)`` are considered, as with the evaluation of *x*``+``*y*. + :meth:`__iadd__` method, ``x.__iadd__(y)`` is called. If *x* is an instance + of a class that does not define a :meth:`__iadd__` method, ``x.__add__(y)`` + and ``y.__radd__(x)`` are considered, as with the evaluation of *x*``+``*y*. .. method:: numeric object.__neg__(self) Modified: doctools/trunk/Doc-3k/reference/executionmodel.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/executionmodel.rst (original) +++ doctools/trunk/Doc-3k/reference/executionmodel.rst Sun Aug 5 00:45:13 2007 @@ -199,8 +199,8 @@ Python uses the "termination" model of error handling: an exception handler can find out what happened and continue execution at an outer level, but it cannot -repair the cause of the error and retry the failing operation (except by re- -entering the offending piece of code from the top). +repair the cause of the error and retry the failing operation (except by +re-entering the offending piece of code from the top). .. index:: single: SystemExit (built-in exception) Modified: doctools/trunk/Doc-3k/reference/expressions.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/expressions.rst (original) +++ doctools/trunk/Doc-3k/reference/expressions.rst Sun Aug 5 00:45:13 2007 @@ -198,9 +198,9 @@ pair: empty; list A list display yields a new list object. Its contents are specified by -providing either a list of expressions or a list comprehension. When a comma- -separated list of expressions is supplied, its elements are evaluated from left -to right and placed into the list object in that order. When a list +providing either a list of expressions or a list comprehension. When a +comma-separated list of expressions is supplied, its elements are evaluated from +left to right and placed into the list object in that order. When a list comprehension is supplied, it consists of a single expression followed by at least one :keyword:`for` clause and zero or more :keyword:`for` or :keyword:`if` clauses. In this case, the elements of the new list are those that would be Modified: doctools/trunk/Doc-3k/reference/lexical_analysis.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/lexical_analysis.rst (original) +++ doctools/trunk/Doc-3k/reference/lexical_analysis.rst Sun Aug 5 00:45:13 2007 @@ -456,14 +456,14 @@ In plain English: String literals can be enclosed in matching single quotes (``'``) or double quotes (``"``). They can also be enclosed in matching groups -of three single or double quotes (these are generally referred to as *triple- -quoted strings*). The backslash (``\``) character is used to escape characters -that otherwise have a special meaning, such as newline, backslash itself, or the -quote character. String literals may optionally be prefixed with a letter -``'r'`` or ``'R'``; such strings are called :dfn:`raw strings` and use different -rules for interpreting backslash escape sequences. A prefix of ``'u'`` or -``'U'`` makes the string a Unicode string. Unicode strings use the Unicode -character set as defined by the Unicode Consortium and ISO 10646. Some +of three single or double quotes (these are generally referred to as +*triple-quoted strings*). The backslash (``\``) character is used to escape +characters that otherwise have a special meaning, such as newline, backslash +itself, or the quote character. String literals may optionally be prefixed with +a letter ``'r'`` or ``'R'``; such strings are called :dfn:`raw strings` and use +different rules for interpreting backslash escape sequences. A prefix of +``'u'`` or ``'U'`` makes the string a Unicode string. Unicode strings use the +Unicode character set as defined by the Unicode Consortium and ISO 10646. Some additional escape sequences, described below, are available in Unicode strings. The two prefix characters may be combined; in this case, ``'u'`` must appear before ``'r'``. Modified: doctools/trunk/Doc-3k/reference/simple_stmts.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/simple_stmts.rst (original) +++ doctools/trunk/Doc-3k/reference/simple_stmts.rst Sun Aug 5 00:45:13 2007 @@ -727,11 +727,8 @@ can appear before a future statement are: * the module docstring (if any), - * comments, - * blank lines, and - * other future statements. The features recognized by Python 2.5 are ``absolute_import``, ``division``, Modified: doctools/trunk/Doc-3k/tutorial/appetite.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/appetite.rst (original) +++ doctools/trunk/Doc-3k/tutorial/appetite.rst Sun Aug 5 00:45:13 2007 @@ -5,10 +5,10 @@ ********************** If you do much work on computers, eventually you find that there's some task -you'd like to automate. For example, you may wish to perform a search-and- -replace over a large number of text files, or rename and rearrange a bunch of -photo files in a complicated way. Perhaps you'd like to write a small custom -database, or a specialized GUI application, or a simple game. +you'd like to automate. For example, you may wish to perform a +search-and-replace over a large number of text files, or rename and rearrange a +bunch of photo files in a complicated way. Perhaps you'd like to write a small +custom database, or a specialized GUI application, or a simple game. If you're a professional software developer, you may have to work with several C/C++/Java libraries but find the usual write/compile/test/re-compile cycle is Modified: doctools/trunk/Doc-3k/tutorial/datastructures.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/datastructures.rst (original) +++ doctools/trunk/Doc-3k/tutorial/datastructures.rst Sun Aug 5 00:45:13 2007 @@ -420,8 +420,8 @@ >>> 'guido' in tel True -The :func:`dict` constructor builds dictionaries directly from lists of key- -value pairs stored as tuples. When the pairs form a pattern, list +The :func:`dict` constructor builds dictionaries directly from lists of +key-value pairs stored as tuples. When the pairs form a pattern, list comprehensions can compactly specify the key-value list. :: >>> dict([('sape', 4139), ('guido', 4127), ('jack', 4098)]) Modified: doctools/trunk/Doc-3k/tutorial/errors.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/errors.rst (original) +++ doctools/trunk/Doc-3k/tutorial/errors.rst Sun Aug 5 00:45:13 2007 @@ -234,8 +234,8 @@ fine, but there seems to be a growing stylistic preference for the latter. If you need to determine whether an exception was raised but don't intend to -handle it, a simpler form of the :keyword:`raise` statement allows you to re- -raise the exception:: +handle it, a simpler form of the :keyword:`raise` statement allows you to +re-raise the exception:: >>> try: ... raise NameError, 'HiThere' Modified: doctools/trunk/Doc-3k/tutorial/glossary.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/glossary.rst (original) +++ doctools/trunk/Doc-3k/tutorial/glossary.rst Sun Aug 5 00:45:13 2007 @@ -138,13 +138,14 @@ .. index:: single: global interpreter lock global interpreter lock - The lock used by Python threads to assure that only one thread can be run at a - time. This simplifies Python by assuring that no two processes can access the - same memory at the same time. Locking the entire interpreter makes it easier - for the interpreter to be multi-threaded, at the expense of some parallelism on - multi-processor machines. Efforts have been made in the past to create a "free- - threaded" interpreter (one which locks shared data at a much finer granularity), - but performance suffered in the common single-processor case. + The lock used by Python threads to assure that only one thread can be run at + a time. This simplifies Python by assuring that no two processes can access + the same memory at the same time. Locking the entire interpreter makes it + easier for the interpreter to be multi-threaded, at the expense of some + parallelism on multi-processor machines. Efforts have been made in the past + to create a "free-threaded" interpreter (one which locks shared data at a + much finer granularity), but performance suffered in the common + single-processor case. .. index:: single: IDLE Modified: doctools/trunk/Doc-3k/tutorial/introduction.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/introduction.rst (original) +++ doctools/trunk/Doc-3k/tutorial/introduction.rst Sun Aug 5 00:45:13 2007 @@ -429,9 +429,10 @@ characters of Latin-1. For experts, there is also a raw mode just like the one for normal strings. You -have to prefix the opening quote with 'ur' to have Python use the *Raw-Unicode- -Escape* encoding. It will only apply the above ``\uXXXX`` conversion if there is -an uneven number of backslashes in front of the small 'u'. :: +have to prefix the opening quote with 'ur' to have Python use the +*Raw-Unicode-Escape* encoding. It will only apply the above ``\uXXXX`` +conversion if there is an uneven number of backslashes in front of the small +'u'. :: >>> ur'Hello\u0020World !' u'Hello World !' Modified: doctools/trunk/Doc-3k/tutorial/modules.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/modules.rst (original) +++ doctools/trunk/Doc-3k/tutorial/modules.rst Sun Aug 5 00:45:13 2007 @@ -168,9 +168,9 @@ As an important speed-up of the start-up time for short programs that use a lot of standard modules, if a file called :file:`spam.pyc` exists in the directory -where :file:`spam.py` is found, this is assumed to contain an already-"byte- -compiled" version of the module :mod:`spam`. The modification time of the -version of :file:`spam.py` used to create :file:`spam.pyc` is recorded in +where :file:`spam.py` is found, this is assumed to contain an +already-"byte-compiled" version of the module :mod:`spam`. The modification time +of the version of :file:`spam.py` used to create :file:`spam.pyc` is recorded in :file:`spam.pyc`, and the :file:`.pyc` file is ignored if these don't match. Normally, you don't need to do anything to create the :file:`spam.pyc` file. Modified: doctools/trunk/Doc-3k/tutorial/whatnow.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/whatnow.rst (original) +++ doctools/trunk/Doc-3k/tutorial/whatnow.rst Sun Aug 5 00:45:13 2007 @@ -49,12 +49,12 @@ Cookbook (O'Reilly & Associates, ISBN 0-596-00797-3.) For Python-related questions and problem reports, you can post to the newsgroup -:newsgroup:`comp.lang.python`, or send them to the mailing list at python- -list at python.org. The newsgroup and mailing list are gatewayed, so messages -posted to one will automatically be forwarded to the other. There are around -120 postings a day (with peaks up to several hundred), asking (and answering) -questions, suggesting new features, and announcing new modules. Before posting, -be sure to check the list of `Frequently Asked Questions +:newsgroup:`comp.lang.python`, or send them to the mailing list at +python-list at python.org. The newsgroup and mailing list are gatewayed, so +messages posted to one will automatically be forwarded to the other. There are +around 120 postings a day (with peaks up to several hundred), asking (and +answering) questions, suggesting new features, and announcing new modules. +Before posting, be sure to check the list of `Frequently Asked Questions `_ (also called the FAQ), or look for it in the :file:`Misc/` directory of the Python source distribution. Mailing list archives are available at http://mail.python.org/pipermail/. The FAQ answers Modified: doctools/trunk/Doc-3k/whatsnew/2.0.rst ============================================================================== --- doctools/trunk/Doc-3k/whatsnew/2.0.rst (original) +++ doctools/trunk/Doc-3k/whatsnew/2.0.rst Sun Aug 5 00:45:13 2007 @@ -181,7 +181,7 @@ * ``ord(u)``, where *u* is a 1-character regular or Unicode string, returns the number of the character as an integer. -* ``unicode(string [, *encoding*] [, *errors*] )`` creates a Unicode string +* ``unicode(string [, encoding] [, errors] )`` creates a Unicode string from an 8-bit string. ``encoding`` is a string naming the encoding to use. The ``errors`` parameter specifies the treatment of characters that are invalid for the current encoding; passing ``'strict'`` as the value causes an exception to Modified: doctools/trunk/Doc-3k/whatsnew/2.1.rst ============================================================================== --- doctools/trunk/Doc-3k/whatsnew/2.1.rst (original) +++ doctools/trunk/Doc-3k/whatsnew/2.1.rst Sun Aug 5 00:45:13 2007 @@ -755,12 +755,12 @@ Wolfson, but after some python-dev discussion, a weaker final version was checked in. -* Applying :func:`repr` to strings previously used octal escapes for non- - printable characters; for example, a newline was ``'\012'``. This was a +* Applying :func:`repr` to strings previously used octal escapes for + non-printable characters; for example, a newline was ``'\012'``. This was a vestigial trace of Python's C ancestry, but today octal is of very little practical use. Ka-Ping Yee suggested using hex escapes instead of octal ones, - and using the ``\n``, ``\t``, ``\r`` escapes for the appropriate characters, and - implemented this new formatting. + and using the ``\n``, ``\t``, ``\r`` escapes for the appropriate characters, + and implemented this new formatting. * Syntax errors detected at compile-time can now raise exceptions containing the filename and line number of the error, a pleasant side effect of the compiler Modified: doctools/trunk/Doc-3k/whatsnew/2.3.rst ============================================================================== --- doctools/trunk/Doc-3k/whatsnew/2.3.rst (original) +++ doctools/trunk/Doc-3k/whatsnew/2.3.rst Sun Aug 5 00:45:13 2007 @@ -1660,12 +1660,13 @@ >{}>{}> u"www.Alliancefran?aise.nu".encode("idna") 'www.xn--alliancefranaise-npb.nu' - The :mod:`socket` module has also been extended to transparently convert Unicode - hostnames to the ACE version before passing them to the C library. Modules that - deal with hostnames such as :mod:`httplib` and :mod:`ftplib`) also support - Unicode host names; :mod:`httplib` also sends HTTP ``Host`` headers using the - ACE version of the domain name. :mod:`urllib` supports Unicode URLs with non- - ASCII host names as long as the ``path`` part of the URL is ASCII only. + The :mod:`socket` module has also been extended to transparently convert + Unicode hostnames to the ACE version before passing them to the C library. + Modules that deal with hostnames such as :mod:`httplib` and :mod:`ftplib`) + also support Unicode host names; :mod:`httplib` also sends HTTP ``Host`` + headers using the ACE version of the domain name. :mod:`urllib` supports + Unicode URLs with non-ASCII host names as long as the ``path`` part of the URL + is ASCII only. To implement this change, the :mod:`stringprep` module, the ``mkstringprep`` tool and the ``punycode`` encoding have been added. Modified: doctools/trunk/Doc-3k/whatsnew/2.5.rst ============================================================================== --- doctools/trunk/Doc-3k/whatsnew/2.5.rst (original) +++ doctools/trunk/Doc-3k/whatsnew/2.5.rst Sun Aug 5 00:45:13 2007 @@ -1037,12 +1037,12 @@ returned by the iterator evaluate as true. (Suggested by Guido van Rossum, and implemented by Raymond Hettinger.) -* The result of a class's :meth:`__hash__` method can now be either a long +* The result of a class's :meth:`__hash__` method can now be either a long integer or a regular integer. If a long integer is returned, the hash of that - value is taken. In earlier versions the hash value was required to be a regular - integer, but in 2.5 the :func:`id` built-in was changed to always return non- - negative numbers, and users often seem to use ``id(self)`` in :meth:`__hash__` - methods (though this is discouraged). + value is taken. In earlier versions the hash value was required to be a + regular integer, but in 2.5 the :func:`id` built-in was changed to always + return non-negative numbers, and users often seem to use ``id(self)`` in + :meth:`__hash__` methods (though this is discouraged). .. % Bug #1536021 Modified: doctools/trunk/sphinx/directives.py ============================================================================== --- doctools/trunk/sphinx/directives.py (original) +++ doctools/trunk/sphinx/directives.py Sun Aug 5 00:45:13 2007 @@ -154,7 +154,6 @@ signode += addnodes.desc_parameterlist() stack = [signode[-1]] - arglist = arglist.replace('`', '').replace(r'\ ', '') # remove markup for token in py_paramlist_re.split(arglist): if token == '[': opt = addnodes.desc_optional() @@ -394,7 +393,7 @@ def seealso_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): rv = admonitions.make_admonition( - addnodes.seealso, name, ['See also:'], options, content, + addnodes.seealso, name, ['See also'], options, content, lineno, content_offset, block_text, state, state_machine) return rv From python-checkins at python.org Sun Aug 5 00:52:20 2007 From: python-checkins at python.org (georg.brandl) Date: Sun, 5 Aug 2007 00:52:20 +0200 (CEST) Subject: [Python-checkins] r56745 - doctools/trunk/README Message-ID: <20070804225220.7CD7D1E4339@bag.python.org> Author: georg.brandl Date: Sun Aug 5 00:51:34 2007 New Revision: 56745 Modified: doctools/trunk/README Log: Update readme. Modified: doctools/trunk/README ============================================================================== --- doctools/trunk/README (original) +++ doctools/trunk/README Sun Aug 5 00:51:34 2007 @@ -15,6 +15,13 @@ installable from PyPI. Jinja, the template engine, is included as a SVN external. + +Converting the LaTeX sources +---------------------------- + +**This paragraph is obsolete.** The conversion has been done, and reST docs +trees are now maintained for 2.6 and 3.0 branches. + For the rest of this document, let's assume that you have a Python checkout (you need the 2.6 line, i.e. the trunk -- the SVN URL for readonly access is http://svn.python.org/projects/python/trunk) in ~/devel/python @@ -47,7 +54,7 @@ Then, create a target directory and run :: mkdir build-html - python sphinx-build.py -b html sources build-html + python sphinx-build.py -b html Doc-26 build-html This will create HTML files in the ``build-html`` directory. @@ -64,7 +71,7 @@ First, you need to build the source with the "web" builder:: mkdir build-web - python sphinx-build.py -b web sources build-web + python sphinx-build.py -b web Doc-26 build-web This will create files with pickled contents for the web application in the target directory. From python-checkins at python.org Sun Aug 5 01:07:58 2007 From: python-checkins at python.org (georg.brandl) Date: Sun, 5 Aug 2007 01:07:58 +0200 (CEST) Subject: [Python-checkins] r56746 - doctools/trunk/sphinx/addnodes.py doctools/trunk/sphinx/roles.py doctools/trunk/sphinx/writer.py Message-ID: <20070804230758.371DF1E4018@bag.python.org> Author: georg.brandl Date: Sun Aug 5 01:07:57 2007 New Revision: 56746 Modified: doctools/trunk/sphinx/addnodes.py doctools/trunk/sphinx/roles.py doctools/trunk/sphinx/writer.py Log: Don't mangle "--" in option names. Modified: doctools/trunk/sphinx/addnodes.py ============================================================================== --- doctools/trunk/sphinx/addnodes.py (original) +++ doctools/trunk/sphinx/addnodes.py Sun Aug 5 01:07:57 2007 @@ -50,6 +50,9 @@ # sets the highlighting language for literal blocks class highlightlang(nodes.Element): pass +# doesn't apply further text processors, e.g. smartypants +class literal_emphasis(nodes.emphasis): pass + # make them known to docutils. this is needed, because the HTMl writer # will choke at some point if these are not added nodes._add_node_class_names("""index desc desc_content desc_signature Modified: doctools/trunk/sphinx/roles.py ============================================================================== --- doctools/trunk/sphinx/roles.py (original) +++ doctools/trunk/sphinx/roles.py Sun Aug 5 01:07:57 2007 @@ -20,16 +20,16 @@ generic_docroles = { 'command' : nodes.strong, - 'dfn' : nodes.emphasis, + 'dfn' : addnodes.literal_emphasis, 'guilabel' : nodes.strong, 'kbd' : nodes.literal, 'keyword' : nodes.literal, - 'mailheader' : nodes.emphasis, + 'mailheader' : addnodes.literal_emphasis, 'makevar' : nodes.Text, - 'manpage' : nodes.emphasis, - 'mimetype' : nodes.emphasis, - 'newsgroup' : nodes.emphasis, - 'option' : nodes.emphasis, + 'manpage' : addnodes.literal_emphasis, + 'mimetype' : addnodes.literal_emphasis, + 'newsgroup' : addnodes.literal_emphasis, + 'option' : addnodes.literal_emphasis, 'program' : nodes.strong, 'regexp' : nodes.literal, } Modified: doctools/trunk/sphinx/writer.py ============================================================================== --- doctools/trunk/sphinx/writer.py (original) +++ doctools/trunk/sphinx/writer.py Sun Aug 5 01:07:57 2007 @@ -196,6 +196,12 @@ def visit_index(self, node): raise nodes.SkipNode + # these are only handled specially in the SmartyPantsHTMLTranslator + def visit_literal_emphasis(self, node): + return self.visit_emphasis(node) + def depart_literal_emphasis(self, node): + return self.depart_emphasis(node) + class SmartyPantsHTMLTranslator(HTMLTranslator): """ @@ -215,6 +221,14 @@ finally: self.no_smarty -= 1 + def visit_literal_emphasis(self, node): + self.no_smarty += 1 + self.visit_emphasis(node) + + def depart_literal_emphasis(self, node): + self.depart_emphasis(node) + self.no_smarty -= 1 + def visit_productionlist(self, node): self.no_smarty += 1 try: From python-checkins at python.org Sun Aug 5 01:33:35 2007 From: python-checkins at python.org (georg.brandl) Date: Sun, 5 Aug 2007 01:33:35 +0200 (CEST) Subject: [Python-checkins] r56747 - in doctools/trunk/sphinx: addnodes.py highlighting.py style/default.css style/traditional.css Message-ID: <20070804233335.796DD1E4942@bag.python.org> Author: georg.brandl Date: Sun Aug 5 01:33:10 2007 New Revision: 56747 Modified: doctools/trunk/sphinx/addnodes.py doctools/trunk/sphinx/highlighting.py doctools/trunk/sphinx/style/default.css doctools/trunk/sphinx/style/traditional.css Log: Only highlight snippets as Python if they can be parsed as Python. Modified: doctools/trunk/sphinx/addnodes.py ============================================================================== --- doctools/trunk/sphinx/addnodes.py (original) +++ doctools/trunk/sphinx/addnodes.py Sun Aug 5 01:33:10 2007 @@ -50,7 +50,7 @@ # sets the highlighting language for literal blocks class highlightlang(nodes.Element): pass -# doesn't apply further text processors, e.g. smartypants +# like emphasis, but doesn't apply further text processors, e.g. smartypants class literal_emphasis(nodes.emphasis): pass # make them known to docutils. this is needed, because the HTMl writer Modified: doctools/trunk/sphinx/highlighting.py ============================================================================== --- doctools/trunk/sphinx/highlighting.py (original) +++ doctools/trunk/sphinx/highlighting.py Sun Aug 5 01:33:10 2007 @@ -10,6 +10,7 @@ """ import cgi +import parser from collections import defaultdict try: @@ -57,15 +58,22 @@ return '
      ' + cgi.escape(source) + '
      \n' if lang == 'python': if source.startswith('>>>'): + # interactive session lexer = lexers['pycon'] else: - lexer = lexers['python'] + # maybe Python -- try parsing it + try: + parser.suite(source + '\n') + except SyntaxError: + return '
      ' + cgi.escape(source) + '
      \n' + else: + lexer = lexers['python'] else: lexer = lexers[lang] try: return highlight(source, lexer, fmter) except ErrorToken: - # this is most probably not Python, so let it pass textonly + # this is most probably not Python, so let it pass unhighlighted return '
      ' + cgi.escape(source) + '
      \n' def get_stylesheet(): Modified: doctools/trunk/sphinx/style/default.css ============================================================================== --- doctools/trunk/sphinx/style/default.css (original) +++ doctools/trunk/sphinx/style/default.css Sun Aug 5 01:33:10 2007 @@ -643,7 +643,7 @@ } table.docutils td, table.docutils th { - padding: 0 8px 2px 0; + padding: 1px 8px 1px 0; border-top: 0; border-left: 0; border-right: 0; @@ -704,7 +704,7 @@ tt { font-family: 'Bitstream Vera Sans Mono', monospace; background-color: #ecf0f3; - padding: 1px; + padding: 0 1px 0 1px; } tt.descname { Modified: doctools/trunk/sphinx/style/traditional.css ============================================================================== --- doctools/trunk/sphinx/style/traditional.css (original) +++ doctools/trunk/sphinx/style/traditional.css Sun Aug 5 01:33:10 2007 @@ -606,7 +606,7 @@ tt { font-family: 'Bitstream Vera Sans Mono', monospace; background-color: #ecf0f3; - padding: 1px; + padding: 0 1px 0 1px; } tt.descname { From python-checkins at python.org Sun Aug 5 04:21:19 2007 From: python-checkins at python.org (neal.norwitz) Date: Sun, 5 Aug 2007 04:21:19 +0200 (CEST) Subject: [Python-checkins] r56749 - peps/trunk/pep-3100.txt Message-ID: <20070805022119.D3DF31E4E2F@bag.python.org> Author: neal.norwitz Date: Sun Aug 5 04:20:27 2007 New Revision: 56749 Modified: peps/trunk/pep-3100.txt Log: Make from X import * outside module scope an error. Modified: peps/trunk/pep-3100.txt ============================================================================== --- peps/trunk/pep-3100.txt (original) +++ peps/trunk/pep-3100.txt Sun Aug 5 04:20:27 2007 @@ -80,7 +80,7 @@ will raise an exception unless explicitly supported by the type [6]_ [done] * floats will not be acceptable as arguments in place of ints for operations where floats are inadvertantly accepted (PyArg_ParseTuple() i & l formats) -* Remove from ... import * at function scope. This means that functions +* Remove from ... import * at function scope. [done] This means that functions can always be optimized and support for unoptimized functions can go away. * Imports [#pep328]_ + Imports will be absolute by default. [done] From python-checkins at python.org Sun Aug 5 05:24:17 2007 From: python-checkins at python.org (neal.norwitz) Date: Sun, 5 Aug 2007 05:24:17 +0200 (CEST) Subject: [Python-checkins] r56751 - python/trunk/Python/structmember.c Message-ID: <20070805032417.E05A81E538A@bag.python.org> Author: neal.norwitz Date: Sun Aug 5 05:23:31 2007 New Revision: 56751 Modified: python/trunk/Python/structmember.c Log: Handle errors when generating a warning. The value is always written to the returned pointer if getting it was successful, even if a warning causes an error. (This probably doesn't matter as the caller will probably discard the value.) Will backport. Modified: python/trunk/Python/structmember.c ============================================================================== --- python/trunk/Python/structmember.c (original) +++ python/trunk/Python/structmember.c Sun Aug 5 05:23:31 2007 @@ -156,6 +156,12 @@ return -1; } +#define WARN(msg) \ + do { \ + if (PyErr_Warn(PyExc_RuntimeWarning, msg) < 0) \ + return -1; \ + } while (0) + int PyMember_SetOne(char *addr, PyMemberDef *l, PyObject *v) { @@ -178,60 +184,54 @@ addr += l->offset; switch (l->type) { case T_BYTE:{ - long long_val; - long_val = PyInt_AsLong(v); + long long_val = PyInt_AsLong(v); if ((long_val == -1) && PyErr_Occurred()) return -1; + *(char*)addr = (char)long_val; /* XXX: For compatibility, only warn about truncations for now. */ if ((long_val > CHAR_MAX) || (long_val < CHAR_MIN)) - PyErr_Warn(PyExc_RuntimeWarning, "Truncation of value to char"); - *(char*)addr = (char)long_val; + WARN("Truncation of value to char"); break; } case T_UBYTE:{ - long long_val; - long_val = PyInt_AsLong(v); + long long_val = PyInt_AsLong(v); if ((long_val == -1) && PyErr_Occurred()) return -1; - if ((long_val > UCHAR_MAX) || (long_val < 0)) - PyErr_Warn(PyExc_RuntimeWarning, "Truncation of value to unsigned char"); *(unsigned char*)addr = (unsigned char)long_val; + if ((long_val > UCHAR_MAX) || (long_val < 0)) + WARN("Truncation of value to unsigned char"); break; } case T_SHORT:{ - long long_val; - long_val = PyInt_AsLong(v); + long long_val = PyInt_AsLong(v); if ((long_val == -1) && PyErr_Occurred()) return -1; - if ((long_val > SHRT_MAX) || (long_val < SHRT_MIN)) - PyErr_Warn(PyExc_RuntimeWarning, "Truncation of value to short"); *(short*)addr = (short)long_val; + if ((long_val > SHRT_MAX) || (long_val < SHRT_MIN)) + WARN("Truncation of value to short"); break; } case T_USHORT:{ - long long_val; - long_val = PyInt_AsLong(v); + long long_val = PyInt_AsLong(v); if ((long_val == -1) && PyErr_Occurred()) return -1; - if ((long_val > USHRT_MAX) || (long_val < 0)) - PyErr_Warn(PyExc_RuntimeWarning, "Truncation of value to unsigned short"); *(unsigned short*)addr = (unsigned short)long_val; + if ((long_val > USHRT_MAX) || (long_val < 0)) + WARN("Truncation of value to unsigned short"); break; } case T_INT:{ - long long_val; - long_val = PyInt_AsLong(v); + long long_val = PyInt_AsLong(v); if ((long_val == -1) && PyErr_Occurred()) return -1; - if ((long_val > INT_MAX) || (long_val < INT_MIN)) - PyErr_Warn(PyExc_RuntimeWarning, "Truncation of value to int"); *(int *)addr = (int)long_val; + if ((long_val > INT_MAX) || (long_val < INT_MIN)) + WARN("Truncation of value to int"); break; } case T_UINT:{ - unsigned long ulong_val; - ulong_val = PyLong_AsUnsignedLong(v); + unsigned long ulong_val = PyLong_AsUnsignedLong(v); if ((ulong_val == (unsigned int)-1) && PyErr_Occurred()) { /* XXX: For compatibility, accept negative int values as well. */ @@ -239,11 +239,12 @@ ulong_val = PyLong_AsLong(v); if ((ulong_val == (unsigned int)-1) && PyErr_Occurred()) return -1; - PyErr_Warn(PyExc_RuntimeWarning, "Writing negative value into unsigned field"); - } + *(unsigned int *)addr = (unsigned int)ulong_val; + WARN("Writing negative value into unsigned field"); + } else + *(unsigned int *)addr = (unsigned int)ulong_val; if (ulong_val > UINT_MAX) - PyErr_Warn(PyExc_RuntimeWarning, "Truncation of value to unsigned int"); - *(unsigned int *)addr = (unsigned int)ulong_val; + WARN("Truncation of value to unsigned int"); break; } case T_LONG:{ @@ -260,9 +261,10 @@ as well. */ PyErr_Clear(); *(unsigned long*)addr = PyLong_AsLong(v); - if ((*(unsigned long*)addr == (unsigned int)-1) && PyErr_Occurred()) + if ((*(unsigned long*)addr == (unsigned int)-1) + && PyErr_Occurred()) return -1; - PyErr_Warn(PyExc_RuntimeWarning, "Writing negative value into unsigned field"); + WARN("Writing negative value into unsigned field"); } break; } @@ -274,8 +276,7 @@ break; } case T_FLOAT:{ - double double_val; - double_val = PyFloat_AsDouble(v); + double double_val = PyFloat_AsDouble(v); if ((double_val == -1) && PyErr_Occurred()) return -1; *(float*)addr = (float)double_val; From buildbot at python.org Sun Aug 5 05:59:32 2007 From: buildbot at python.org (buildbot at python.org) Date: Sun, 05 Aug 2007 03:59:32 +0000 Subject: [Python-checkins] buildbot warnings in x86 XP-3 trunk Message-ID: <20070805035933.440611E4051@bag.python.org> The Buildbot has detected a new failure of x86 XP-3 trunk. Full details are available at: http://www.python.org/dev/buildbot/all/x86%2520XP-3%2520trunk/builds/117 Buildbot URL: http://www.python.org/dev/buildbot/all/ Build Reason: Build Source Stamp: [branch trunk] HEAD Blamelist: neal.norwitz Build had warnings: warnings test Excerpt from the test logfile: 1 test failed: test_timeout sincerely, -The Buildbot From buildbot at python.org Sun Aug 5 06:38:41 2007 From: buildbot at python.org (buildbot at python.org) Date: Sun, 05 Aug 2007 04:38:41 +0000 Subject: [Python-checkins] buildbot warnings in ia64 Ubuntu trunk trunk Message-ID: <20070805043844.49B3D1E40F1@bag.python.org> The Buildbot has detected a new failure of ia64 Ubuntu trunk trunk. Full details are available at: http://www.python.org/dev/buildbot/all/ia64%2520Ubuntu%2520trunk%2520trunk/builds/787 Buildbot URL: http://www.python.org/dev/buildbot/all/ Build Reason: Build Source Stamp: [branch trunk] HEAD Blamelist: neal.norwitz Build had warnings: warnings test Excerpt from the test logfile: sincerely, -The Buildbot From buildbot at python.org Sun Aug 5 06:50:12 2007 From: buildbot at python.org (buildbot at python.org) Date: Sun, 05 Aug 2007 04:50:12 +0000 Subject: [Python-checkins] buildbot warnings in x86 XP trunk Message-ID: <20070805045013.A1F0B1E4129@bag.python.org> The Buildbot has detected a new failure of x86 XP trunk. Full details are available at: http://www.python.org/dev/buildbot/all/x86%2520XP%2520trunk/builds/551 Buildbot URL: http://www.python.org/dev/buildbot/all/ Build Reason: Build Source Stamp: [branch trunk] HEAD Blamelist: neal.norwitz Build had warnings: warnings test Excerpt from the test logfile: 1 test failed: test_timeout sincerely, -The Buildbot From python-checkins at python.org Sun Aug 5 14:26:56 2007 From: python-checkins at python.org (georg.brandl) Date: Sun, 5 Aug 2007 14:26:56 +0200 (CEST) Subject: [Python-checkins] r56752 - in doctools/trunk: Doc-26/library/codecs.rst Doc-26/library/datetime.rst Doc-26/library/functools.rst Doc-26/library/time.rst Doc-26/license.rst Doc-3k/library/codecs.rst Doc-3k/library/datetime.rst Doc-3k/library/functools.rst Doc-3k/license.rst sphinx/style/default.css sphinx/style/traditional.css sphinx/writer.py Message-ID: <20070805122656.2C9D71E4002@bag.python.org> Author: georg.brandl Date: Sun Aug 5 14:26:55 2007 New Revision: 56752 Modified: doctools/trunk/Doc-26/library/codecs.rst doctools/trunk/Doc-26/library/datetime.rst doctools/trunk/Doc-26/library/functools.rst doctools/trunk/Doc-26/library/time.rst doctools/trunk/Doc-26/license.rst doctools/trunk/Doc-3k/library/codecs.rst doctools/trunk/Doc-3k/library/datetime.rst doctools/trunk/Doc-3k/library/functools.rst doctools/trunk/Doc-3k/license.rst doctools/trunk/sphinx/style/default.css doctools/trunk/sphinx/style/traditional.css doctools/trunk/sphinx/writer.py Log: Other minor fixes. Modified: doctools/trunk/Doc-26/library/codecs.rst ============================================================================== --- doctools/trunk/Doc-26/library/codecs.rst (original) +++ doctools/trunk/Doc-26/library/codecs.rst Sun Aug 5 14:26:55 2007 @@ -734,24 +734,24 @@ Unicode strings are stored internally as sequences of codepoints (to be precise as :ctype:`Py_UNICODE` arrays). Depending on the way Python is compiled (either -via :option:`--enable-unicode=ucs2` or :option:`--enable-unicode=ucs4`, with -the former being the default) :ctype:`Py_UNICODE` is either a 16-bit or 32-bit -data type. Once a Unicode object is used outside of CPU and memory, CPU -endianness and how these arrays are stored as bytes become an issue. -Transforming a unicode object into a sequence of bytes is called encoding and -recreating the unicode object from the sequence of bytes is known as decoding. -There are many different methods for how this transformation can be done (these -methods are also called encodings). The simplest method is to map the codepoints -0-255 to the bytes ``0x0``\ -\ ``0xff``. This means that a unicode object that -contains codepoints above ``U+00FF`` can't be encoded with this method (which -is called ``'latin-1'`` or ``'iso-8859-1'``). :func:`unicode.encode` will raise -a :exc:`UnicodeEncodeError` that looks like this: ``UnicodeEncodeError: -'latin-1' codec can't encode character u'\u1234' in position 3: ordinal not in +via :option:`--enable-unicode=ucs2` or :option:`--enable-unicode=ucs4`, with the +former being the default) :ctype:`Py_UNICODE` is either a 16-bit or 32-bit data +type. Once a Unicode object is used outside of CPU and memory, CPU endianness +and how these arrays are stored as bytes become an issue. Transforming a +unicode object into a sequence of bytes is called encoding and recreating the +unicode object from the sequence of bytes is known as decoding. There are many +different methods for how this transformation can be done (these methods are +also called encodings). The simplest method is to map the codepoints 0-255 to +the bytes ``0x0``-``0xff``. This means that a unicode object that contains +codepoints above ``U+00FF`` can't be encoded with this method (which is called +``'latin-1'`` or ``'iso-8859-1'``). :func:`unicode.encode` will raise a +:exc:`UnicodeEncodeError` that looks like this: ``UnicodeEncodeError: 'latin-1' +codec can't encode character u'\u1234' in position 3: ordinal not in range(256)``. There's another group of encodings (the so called charmap encodings) that choose a different subset of all unicode code points and how these codepoints are -mapped to the bytes ``0x0``\ -\ ``0xff.`` To see how this is done simply open +mapped to the bytes ``0x0``-``0xff``. To see how this is done simply open e.g. :file:`encodings/cp1252.py` (which is an encoding that is used primarily on Windows). There's a string constant with 256 characters that shows you which character is mapped to which byte value. @@ -824,8 +824,9 @@ that any charmap encoded file starts with these byte values (which would e.g. map to -LATIN SMALL LETTER I WITH DIAERESIS --- RIGHT-POINTING DOUBLE ANGLE QUOTATION -MARK --- INVERTED QUESTION MARK + | LATIN SMALL LETTER I WITH DIAERESIS + | RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK + | INVERTED QUESTION MARK in iso-8859-1), this increases the probability that a utf-8-sig encoding can be correctly guessed from the byte sequence. So here the BOM is not used to be able @@ -1152,14 +1153,14 @@ These RFCs together define a protocol to support non-ASCII characters in domain names. A domain name containing non-ASCII characters (such as -"www.Alliancefran?aise.nu") is converted into an ASCII-compatible encoding (ACE, -such as "www.xn--alliancefranaise-npb.nu"). The ACE form of the domain name is -then used in all places where arbitrary characters are not allowed by the -protocol, such as DNS queries, HTTP :mailheader:`Host` fields, and so on. This -conversion is carried out in the application; if possible invisible to the user: -The application should transparently convert Unicode domain labels to IDNA on -the wire, and convert back ACE labels to Unicode before presenting them to the -user. +``www.Alliancefran?aise.nu``) is converted into an ASCII-compatible encoding +(ACE, such as ``www.xn--alliancefranaise-npb.nu``). The ACE form of the domain +name is then used in all places where arbitrary characters are not allowed by +the protocol, such as DNS queries, HTTP :mailheader:`Host` fields, and so +on. This conversion is carried out in the application; if possible invisible to +the user: The application should transparently convert Unicode domain labels to +IDNA on the wire, and convert back ACE labels to Unicode before presenting them +to the user. Python supports this conversion in several ways: The ``idna`` codec allows to convert between Unicode and the ACE. Furthermore, the :mod:`socket` module Modified: doctools/trunk/Doc-26/library/datetime.rst ============================================================================== --- doctools/trunk/Doc-26/library/datetime.rst (original) +++ doctools/trunk/Doc-26/library/datetime.rst Sun Aug 5 14:26:55 2007 @@ -473,8 +473,8 @@ .. method:: date.ctime() - Return a string representing the date, for example date(2002, 12, 4).ctime() == - 'Wed Dec 4 00:00:00 2002'. ``d.ctime()`` is equivalent to + Return a string representing the date, for example ``date(2002, 12, + 4).ctime() == 'Wed Dec 4 00:00:00 2002'``. ``d.ctime()`` is equivalent to ``time.ctime(time.mktime(d.timetuple()))`` on platforms where the native C :cfunc:`ctime` function (which :func:`time.ctime` invokes, but which :meth:`date.ctime` does not invoke) conforms to the C standard. Modified: doctools/trunk/Doc-26/library/functools.rst ============================================================================== --- doctools/trunk/Doc-26/library/functools.rst (original) +++ doctools/trunk/Doc-26/library/functools.rst Sun Aug 5 14:26:55 2007 @@ -73,25 +73,25 @@ wrapped=wrapped, assigned=assigned, updated=updated)`` as a function decorator when defining a wrapper function. For example:: - >>> def my_decorator(f): - ... @wraps(f) - ... def wrapper(*args, **kwds): - ... print 'Calling decorated function' - ... return f(*args, **kwds) - ... return wrapper - ... - >>> @my_decorator - ... def example(): - ... """Docstring""" - ... print 'Called example function' - ... - >>> example() - Calling decorated function - Called example function - >>> example.__name__ - 'example' - >>> example.__doc__ - 'Docstring' + >>> def my_decorator(f): + ... @wraps(f) + ... def wrapper(*args, **kwds): + ... print 'Calling decorated function' + ... return f(*args, **kwds) + ... return wrapper + ... + >>> @my_decorator + ... def example(): + ... """Docstring""" + ... print 'Called example function' + ... + >>> example() + Calling decorated function + Called example function + >>> example.__name__ + 'example' + >>> example.__doc__ + 'Docstring' Without the use of this decorator factory, the name of the example function would have been ``'wrapper'``, and the docstring of the original :func:`example` Modified: doctools/trunk/Doc-26/library/time.rst ============================================================================== --- doctools/trunk/Doc-26/library/time.rst (original) +++ doctools/trunk/Doc-26/library/time.rst Sun Aug 5 14:26:55 2007 @@ -102,29 +102,12 @@ +-------+-------------------+---------------------------------+ | 8 | :attr:`tm_isdst` | 0, 1 or -1; see below | +-------+-------------------+---------------------------------+ - | - | :attr:`tm_gmtoff` | offset from UTC/GMT in seconds | - | | | east of the Prime Meridian; see | - | | | below | - +-------+-------------------+---------------------------------+ - | - | :attr:`tm_zone` | time zone name; see below | - +-------+-------------------+---------------------------------+ Note that unlike the C structure, the month value is a range of 1-12, not 0-11. A year value will be handled as described under "Year 2000 (Y2K) issues" above. A ``-1`` argument as the daylight savings flag, passed to :func:`mktime` will usually result in the correct daylight savings state to be filled in. - To maintain backwards compatibility, the :attr:`tm_gmtoff` and :attr:`tm_zone` - attributes are not included in the visual representation of each - :class:`struct_time`, but they can be inspected as named, read-only attributes. - Since functions such as :func:`mktime` accept either a 9-tuple or a - :class:`struct_time`, to manually construct a time with specific values of these - attributes, first construct an 11-tuple using the normal 9-tuple extended to - include values for :attr:`tm_gmtoff` and :attr:`tm_zone` as the last two - elements, then pass this tuple to the :class:`struct_time` constructor. It is - also possible to omit :attr:`tm_zone` and to provide a 10-tuple to the - :class:`struct_time` constructor. - When a tuple with an incorrect length is passed to a function expecting a :class:`struct_time`, or having elements of the wrong type, a :exc:`TypeError` is raised. @@ -133,13 +116,9 @@ The time value sequence was changed from a tuple to a :class:`struct_time`, with the addition of attribute names for the fields. - .. versionchanged:: 2.6 - The time value sequence was extended to provide the :attr:`tm_gmtoff` and - :attr:`tm_zone` attributes as described above. The module defines the following functions and data items: - .. data:: accept2dyear Boolean value indicating whether two-digit year values will be accepted. This @@ -249,25 +228,6 @@ The earliest date for which it can generate a time is platform-dependent. -.. function:: mktimetz(t) - - This function interprets times in arbitrary time zones, producing a value - indicating the number of seconds since the epoch for each time. It combines the - ability of :func:`mktime` to convert local times with the ability of - :func:`timegm` to convert GMT/UTC times, but is not constrained by the system's - current time zone, instead obtaining time zone information directly from its - argument where possible. Its argument is the :class:`struct_time` (which may - provide time zone information) or a 9-tuple (which does not, causing the - argument to be interpreted as a time in the GMT/UTC zone). It returns a - floating point number, for compatibility with :func:`time`. If the input value - cannot be represented as a valid time, either :exc:`OverflowError` or - :exc:`ValueError` will be raised (which depends on whether the invalid value is - caught by Python or the underlying C libraries). The earliest date for which it - can generate a time is platform-dependent. - - .. versionadded:: 2.6 - - .. function:: sleep(secs) Suspend execution for the given number of seconds. The argument may be a @@ -371,14 +331,6 @@ | ``%Y`` | Year with century as a decimal | | | | number. | | +-----------+--------------------------------+-------+ - | ``%z`` | Time zone offset indicating a | | - | | positive or negative time | | - | | difference from UTC/GMT of the | | - | | form +HHMM or -HHMM, where H | | - | | represents decimal hour digits | | - | | and M represents decimal | | - | | minute digits [00,59]. | | - +-----------+--------------------------------+-------+ | ``%Z`` | Time zone name (no characters | | | | if no time zone exists). | | +-----------+--------------------------------+-------+ @@ -463,20 +415,6 @@ the two calls. -.. function:: timegm(t) - - This is the inverse function of :func:`gmtime`. Its argument is a - :class:`struct_time` or full 9-tuple which expresses the time in *GMT/UTC* time, - not local time as expected by :func:`mktime`. It returns a floating point - number, for compatibility with :func:`time`. If the input value cannot be - represented as a valid time, either :exc:`OverflowError` or :exc:`ValueError` - will be raised (which depends on whether the invalid value is caught by Python - or the underlying C libraries). The earliest date for which it can generate a - time is platform-dependent. - - .. versionadded:: 2.6 - - .. data:: timezone The offset of the local (non-DST) timezone, in seconds west of UTC (negative in @@ -586,8 +524,7 @@ Module :mod:`calendar` General calendar-related functions. :func:`timegm` is the inverse of - :func:`gmtime` from this module, offering an alternative implementation of - :func:`timegm` from this module. + :func:`gmtime` from this module. .. rubric:: Footnotes Modified: doctools/trunk/Doc-26/license.rst ============================================================================== --- doctools/trunk/Doc-26/license.rst (original) +++ doctools/trunk/Doc-26/license.rst Sun Aug 5 14:26:55 2007 @@ -105,7 +105,7 @@ ============================================================ -.. centered:: **PSF LICENSE AGREEMENT FOR PYTHON** |release| +.. centered:: PSF LICENSE AGREEMENT FOR PYTHON |release| #. This LICENSE AGREEMENT is between the Python Software Foundation ("PSF"), and the Individual or Organization ("Licensee") accessing and otherwise using Python @@ -150,10 +150,10 @@ to be bound by the terms and conditions of this License Agreement. -.. centered:: **BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0** +.. centered:: BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0 -.. centered:: **BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1** +.. centered:: BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1 #. This LICENSE AGREEMENT is between BeOpen.com ("BeOpen"), having an office at 160 Saratoga Avenue, Santa Clara, CA 95051, and the Individual or Organization @@ -195,7 +195,7 @@ bound by the terms and conditions of this License Agreement. -.. centered:: **CNRI LICENSE AGREEMENT FOR PYTHON 1.6.1** +.. centered:: CNRI LICENSE AGREEMENT FOR PYTHON 1.6.1 #. This LICENSE AGREEMENT is between the Corporation for National Research Initiatives, having an office at 1895 Preston White Drive, Reston, VA 20191 @@ -260,7 +260,7 @@ .. centered:: ACCEPT -.. centered:: **CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2** +.. centered:: CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2 Copyright ? 1991 - 1995, Stichting Mathematisch Centrum Amsterdam, The Netherlands. All rights reserved. Modified: doctools/trunk/Doc-3k/library/codecs.rst ============================================================================== --- doctools/trunk/Doc-3k/library/codecs.rst (original) +++ doctools/trunk/Doc-3k/library/codecs.rst Sun Aug 5 14:26:55 2007 @@ -778,24 +778,24 @@ Unicode strings are stored internally as sequences of codepoints (to be precise as :ctype:`Py_UNICODE` arrays). Depending on the way Python is compiled (either -via :option:`--enable-unicode=ucs2` or :option:`--enable-unicode=ucs4`, with -the former being the default) :ctype:`Py_UNICODE` is either a 16-bit or 32-bit -data type. Once a Unicode object is used outside of CPU and memory, CPU -endianness and how these arrays are stored as bytes become an issue. -Transforming a unicode object into a sequence of bytes is called encoding and -recreating the unicode object from the sequence of bytes is known as decoding. -There are many different methods for how this transformation can be done (these -methods are also called encodings). The simplest method is to map the codepoints -0-255 to the bytes ``0x0``\ -\ ``0xff``. This means that a unicode object that -contains codepoints above ``U+00FF`` can't be encoded with this method (which -is called ``'latin-1'`` or ``'iso-8859-1'``). :func:`unicode.encode` will raise -a :exc:`UnicodeEncodeError` that looks like this: ``UnicodeEncodeError: -'latin-1' codec can't encode character u'\u1234' in position 3: ordinal not in +via :option:`--enable-unicode=ucs2` or :option:`--enable-unicode=ucs4`, with the +former being the default) :ctype:`Py_UNICODE` is either a 16-bit or 32-bit data +type. Once a Unicode object is used outside of CPU and memory, CPU endianness +and how these arrays are stored as bytes become an issue. Transforming a +unicode object into a sequence of bytes is called encoding and recreating the +unicode object from the sequence of bytes is known as decoding. There are many +different methods for how this transformation can be done (these methods are +also called encodings). The simplest method is to map the codepoints 0-255 to +the bytes ``0x0``-``0xff``. This means that a unicode object that contains +codepoints above ``U+00FF`` can't be encoded with this method (which is called +``'latin-1'`` or ``'iso-8859-1'``). :func:`unicode.encode` will raise a +:exc:`UnicodeEncodeError` that looks like this: ``UnicodeEncodeError: 'latin-1' +codec can't encode character u'\u1234' in position 3: ordinal not in range(256)``. There's another group of encodings (the so called charmap encodings) that choose a different subset of all unicode code points and how these codepoints are -mapped to the bytes ``0x0``\ -\ ``0xff.`` To see how this is done simply open +mapped to the bytes ``0x0``-``0xff``. To see how this is done simply open e.g. :file:`encodings/cp1252.py` (which is an encoding that is used primarily on Windows). There's a string constant with 256 characters that shows you which character is mapped to which byte value. @@ -868,8 +868,9 @@ that any charmap encoded file starts with these byte values (which would e.g. map to -LATIN SMALL LETTER I WITH DIAERESIS --- RIGHT-POINTING DOUBLE ANGLE QUOTATION -MARK --- INVERTED QUESTION MARK + | LATIN SMALL LETTER I WITH DIAERESIS + | RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK + | INVERTED QUESTION MARK in iso-8859-1), this increases the probability that a utf-8-sig encoding can be correctly guessed from the byte sequence. So here the BOM is not used to be able @@ -1168,14 +1169,14 @@ These RFCs together define a protocol to support non-ASCII characters in domain names. A domain name containing non-ASCII characters (such as -"www.Alliancefran?aise.nu") is converted into an ASCII-compatible encoding (ACE, -such as "www.xn--alliancefranaise-npb.nu"). The ACE form of the domain name is -then used in all places where arbitrary characters are not allowed by the -protocol, such as DNS queries, HTTP :mailheader:`Host` fields, and so on. This -conversion is carried out in the application; if possible invisible to the user: -The application should transparently convert Unicode domain labels to IDNA on -the wire, and convert back ACE labels to Unicode before presenting them to the -user. +``www.Alliancefran?aise.nu``) is converted into an ASCII-compatible encoding +(ACE, such as ``www.xn--alliancefranaise-npb.nu``). The ACE form of the domain +name is then used in all places where arbitrary characters are not allowed by +the protocol, such as DNS queries, HTTP :mailheader:`Host` fields, and so +on. This conversion is carried out in the application; if possible invisible to +the user: The application should transparently convert Unicode domain labels to +IDNA on the wire, and convert back ACE labels to Unicode before presenting them +to the user. Python supports this conversion in several ways: The ``idna`` codec allows to convert between Unicode and the ACE. Furthermore, the :mod:`socket` module Modified: doctools/trunk/Doc-3k/library/datetime.rst ============================================================================== --- doctools/trunk/Doc-3k/library/datetime.rst (original) +++ doctools/trunk/Doc-3k/library/datetime.rst Sun Aug 5 14:26:55 2007 @@ -473,8 +473,8 @@ .. method:: date.ctime() - Return a string representing the date, for example date(2002, 12, 4).ctime() == - 'Wed Dec 4 00:00:00 2002'. ``d.ctime()`` is equivalent to + Return a string representing the date, for example ``date(2002, 12, + 4).ctime() == 'Wed Dec 4 00:00:00 2002'``. ``d.ctime()`` is equivalent to ``time.ctime(time.mktime(d.timetuple()))`` on platforms where the native C :cfunc:`ctime` function (which :func:`time.ctime` invokes, but which :meth:`date.ctime` does not invoke) conforms to the C standard. Modified: doctools/trunk/Doc-3k/library/functools.rst ============================================================================== --- doctools/trunk/Doc-3k/library/functools.rst (original) +++ doctools/trunk/Doc-3k/library/functools.rst Sun Aug 5 14:26:55 2007 @@ -85,25 +85,25 @@ wrapped=wrapped, assigned=assigned, updated=updated)`` as a function decorator when defining a wrapper function. For example:: - >>> def my_decorator(f): - ... @wraps(f) - ... def wrapper(*args, **kwds): - ... print 'Calling decorated function' - ... return f(*args, **kwds) - ... return wrapper - ... - >>> @my_decorator - ... def example(): - ... """Docstring""" - ... print 'Called example function' - ... - >>> example() - Calling decorated function - Called example function - >>> example.__name__ - 'example' - >>> example.__doc__ - 'Docstring' + >>> def my_decorator(f): + ... @wraps(f) + ... def wrapper(*args, **kwds): + ... print 'Calling decorated function' + ... return f(*args, **kwds) + ... return wrapper + ... + >>> @my_decorator + ... def example(): + ... """Docstring""" + ... print 'Called example function' + ... + >>> example() + Calling decorated function + Called example function + >>> example.__name__ + 'example' + >>> example.__doc__ + 'Docstring' Without the use of this decorator factory, the name of the example function would have been ``'wrapper'``, and the docstring of the original :func:`example` Modified: doctools/trunk/Doc-3k/license.rst ============================================================================== --- doctools/trunk/Doc-3k/license.rst (original) +++ doctools/trunk/Doc-3k/license.rst Sun Aug 5 14:26:55 2007 @@ -105,7 +105,7 @@ ============================================================ -.. centered:: **PSF LICENSE AGREEMENT FOR PYTHON** |release| +.. centered:: PSF LICENSE AGREEMENT FOR PYTHON |release| #. This LICENSE AGREEMENT is between the Python Software Foundation ("PSF"), and the Individual or Organization ("Licensee") accessing and otherwise using Python @@ -150,10 +150,10 @@ to be bound by the terms and conditions of this License Agreement. -.. centered:: **BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0** +.. centered:: BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0 -.. centered:: **BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1** +.. centered:: BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1 #. This LICENSE AGREEMENT is between BeOpen.com ("BeOpen"), having an office at 160 Saratoga Avenue, Santa Clara, CA 95051, and the Individual or Organization @@ -195,7 +195,7 @@ bound by the terms and conditions of this License Agreement. -.. centered:: **CNRI LICENSE AGREEMENT FOR PYTHON 1.6.1** +.. centered:: CNRI LICENSE AGREEMENT FOR PYTHON 1.6.1 #. This LICENSE AGREEMENT is between the Corporation for National Research Initiatives, having an office at 1895 Preston White Drive, Reston, VA 20191 @@ -260,7 +260,7 @@ .. centered:: ACCEPT -.. centered:: **CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2** +.. centered:: CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2 Copyright ? 1991 - 1995, Stichting Mathematisch Centrum Amsterdam, The Netherlands. All rights reserved. Modified: doctools/trunk/sphinx/style/default.css ============================================================================== --- doctools/trunk/sphinx/style/default.css (original) +++ doctools/trunk/sphinx/style/default.css Sun Aug 5 14:26:55 2007 @@ -638,6 +638,11 @@ content: ":"; } +div.body p.centered { + text-align: center; + margin-top: 25px; +} + table.docutils { border: 0; } Modified: doctools/trunk/sphinx/style/traditional.css ============================================================================== --- doctools/trunk/sphinx/style/traditional.css (original) +++ doctools/trunk/sphinx/style/traditional.css Sun Aug 5 14:26:55 2007 @@ -547,6 +547,11 @@ content: ":"; } +div.body p.centered { + text-align: center; + margin-top: 25px; +} + table.docutils { border: 0; } Modified: doctools/trunk/sphinx/writer.py ============================================================================== --- doctools/trunk/sphinx/writer.py (original) +++ doctools/trunk/sphinx/writer.py Sun Aug 5 14:26:55 2007 @@ -174,9 +174,9 @@ pass def visit_centered(self, node): - self.body.append(self.starttag(node, 'center') + '') + self.body.append(self.starttag(node, 'p', CLASS="centered") + '') def depart_centered(self, node): - self.body.append('') + self.body.append('

      ') def visit_compact_paragraph(self, node): pass From python-checkins at python.org Sun Aug 5 23:42:34 2007 From: python-checkins at python.org (senthil.kumaran) Date: Sun, 5 Aug 2007 23:42:34 +0200 (CEST) Subject: [Python-checkins] r56756 - sandbox/trunk/urilib/libcgi.tex sandbox/trunk/urilib/liburllib2.tex sandbox/trunk/urilib/liburlparse.tex sandbox/trunk/urilib/test_urllib2.py sandbox/trunk/urilib/urllib2.py Message-ID: <20070805214234.8E6FA1E4006@bag.python.org> Author: senthil.kumaran Date: Sun Aug 5 23:42:33 2007 New Revision: 56756 Added: sandbox/trunk/urilib/libcgi.tex (contents, props changed) sandbox/trunk/urilib/liburllib2.tex (contents, props changed) sandbox/trunk/urilib/liburlparse.tex (contents, props changed) sandbox/trunk/urilib/test_urllib2.py (contents, props changed) sandbox/trunk/urilib/urllib2.py (contents, props changed) Log: SoC Tasks update. Added Docs, urllib2 cache redirection Added: sandbox/trunk/urilib/libcgi.tex ============================================================================== --- (empty file) +++ sandbox/trunk/urilib/libcgi.tex Sun Aug 5 23:42:33 2007 @@ -0,0 +1,609 @@ +\section{\module{cgi} --- + Common Gateway Interface support.} +\declaremodule{standard}{cgi} + +\modulesynopsis{Common Gateway Interface support, used to interpret +forms in server-side scripts.} + +\indexii{WWW}{server} +\indexii{CGI}{protocol} +\indexii{HTTP}{protocol} +\indexii{MIME}{headers} +\index{URL} + + +Support module for Common Gateway Interface (CGI) scripts.% +\index{Common Gateway Interface} + +This module defines a number of utilities for use by CGI scripts +written in Python. + +\subsection{Introduction} +\nodename{cgi-intro} + +A CGI script is invoked by an HTTP server, usually to process user +input submitted through an HTML \code{
      } or \code{} element. + +Most often, CGI scripts live in the server's special \file{cgi-bin} +directory. The HTTP server places all sorts of information about the +request (such as the client's hostname, the requested URL, the query +string, and lots of other goodies) in the script's shell environment, +executes the script, and sends the script's output back to the client. + +The script's input is connected to the client too, and sometimes the +form data is read this way; at other times the form data is passed via +the ``query string'' part of the URL. This module is intended +to take care of the different cases and provide a simpler interface to +the Python script. It also provides a number of utilities that help +in debugging scripts, and the latest addition is support for file +uploads from a form (if your browser supports it). + +The output of a CGI script should consist of two sections, separated +by a blank line. The first section contains a number of headers, +telling the client what kind of data is following. Python code to +generate a minimal header section looks like this: + +\begin{verbatim} +print "Content-Type: text/html" # HTML is following +print # blank line, end of headers +\end{verbatim} + +The second section is usually HTML, which allows the client software +to display nicely formatted text with header, in-line images, etc. +Here's Python code that prints a simple piece of HTML: + +\begin{verbatim} +print "CGI script output" +print "

      This is my first CGI script

      " +print "Hello, world!" +\end{verbatim} + +\subsection{Using the cgi module} +\nodename{Using the cgi module} + +Begin by writing \samp{import cgi}. Do not use \samp{from cgi import +*} --- the module defines all sorts of names for its own use or for +backward compatibility that you don't want in your namespace. + +When you write a new script, consider adding the line: + +\begin{verbatim} +import cgitb; cgitb.enable() +\end{verbatim} + +This activates a special exception handler that will display detailed +reports in the Web browser if any errors occur. If you'd rather not +show the guts of your program to users of your script, you can have +the reports saved to files instead, with a line like this: + +\begin{verbatim} +import cgitb; cgitb.enable(display=0, logdir="/tmp") +\end{verbatim} + +It's very helpful to use this feature during script development. +The reports produced by \refmodule{cgitb} provide information that +can save you a lot of time in tracking down bugs. You can always +remove the \code{cgitb} line later when you have tested your script +and are confident that it works correctly. + +To get at submitted form data, +it's best to use the \class{FieldStorage} class. The other classes +defined in this module are provided mostly for backward compatibility. +Instantiate it exactly once, without arguments. This reads the form +contents from standard input or the environment (depending on the +value of various environment variables set according to the CGI +standard). Since it may consume standard input, it should be +instantiated only once. + +The \class{FieldStorage} instance can be indexed like a Python +dictionary, and also supports the standard dictionary methods +\method{has_key()} and \method{keys()}. The built-in \function{len()} +is also supported. Form fields containing empty strings are ignored +and do not appear in the dictionary; to keep such values, provide +a true value for the optional \var{keep_blank_values} keyword +parameter when creating the \class{FieldStorage} instance. + +For instance, the following code (which assumes that the +\mailheader{Content-Type} header and blank line have already been +printed) checks that the fields \code{name} and \code{addr} are both +set to a non-empty string: + +\begin{verbatim} +form = cgi.FieldStorage() +if not (form.has_key("name") and form.has_key("addr")): + print "

      Error

      " + print "Please fill in the name and addr fields." + return +print "

      name:", form["name"].value +print "

      addr:", form["addr"].value +...further form processing here... +\end{verbatim} + +Here the fields, accessed through \samp{form[\var{key}]}, are +themselves instances of \class{FieldStorage} (or +\class{MiniFieldStorage}, depending on the form encoding). +The \member{value} attribute of the instance yields the string value +of the field. The \method{getvalue()} method returns this string value +directly; it also accepts an optional second argument as a default to +return if the requested key is not present. + +If the submitted form data contains more than one field with the same +name, the object retrieved by \samp{form[\var{key}]} is not a +\class{FieldStorage} or \class{MiniFieldStorage} +instance but a list of such instances. Similarly, in this situation, +\samp{form.getvalue(\var{key})} would return a list of strings. +If you expect this possibility +(when your HTML form contains multiple fields with the same name), use +the \function{getlist()} function, which always returns a list of values (so that you +do not need to special-case the single item case). For example, this +code concatenates any number of username fields, separated by +commas: + +\begin{verbatim} +value = form.getlist("username") +usernames = ",".join(value) +\end{verbatim} + +If a field represents an uploaded file, accessing the value via the +\member{value} attribute or the \function{getvalue()} method reads the +entire file in memory as a string. This may not be what you want. +You can test for an uploaded file by testing either the \member{filename} +attribute or the \member{file} attribute. You can then read the data at +leisure from the \member{file} attribute: + +\begin{verbatim} +fileitem = form["userfile"] +if fileitem.file: + # It's an uploaded file; count lines + linecount = 0 + while 1: + line = fileitem.file.readline() + if not line: break + linecount = linecount + 1 +\end{verbatim} + +The file upload draft standard entertains the possibility of uploading +multiple files from one field (using a recursive +\mimetype{multipart/*} encoding). When this occurs, the item will be +a dictionary-like \class{FieldStorage} item. This can be determined +by testing its \member{type} attribute, which should be +\mimetype{multipart/form-data} (or perhaps another MIME type matching +\mimetype{multipart/*}). In this case, it can be iterated over +recursively just like the top-level form object. + +When a form is submitted in the ``old'' format (as the query string or +as a single data part of type +\mimetype{application/x-www-form-urlencoded}), the items will actually +be instances of the class \class{MiniFieldStorage}. In this case, the +\member{list}, \member{file}, and \member{filename} attributes are +always \code{None}. + + +\subsection{Higher Level Interface} + +\versionadded{2.2} % XXX: Is this true ? + +The previous section explains how to read CGI form data using the +\class{FieldStorage} class. This section describes a higher level +interface which was added to this class to allow one to do it in a +more readable and intuitive way. The interface doesn't make the +techniques described in previous sections obsolete --- they are still +useful to process file uploads efficiently, for example. + +The interface consists of two simple methods. Using the methods +you can process form data in a generic way, without the need to worry +whether only one or more values were posted under one name. + +In the previous section, you learned to write following code anytime +you expected a user to post more than one value under one name: + +\begin{verbatim} +item = form.getvalue("item") +if isinstance(item, list): + # The user is requesting more than one item. +else: + # The user is requesting only one item. +\end{verbatim} + +This situation is common for example when a form contains a group of +multiple checkboxes with the same name: + +\begin{verbatim} + + +\end{verbatim} + +In most situations, however, there's only one form control with a +particular name in a form and then you expect and need only one value +associated with this name. So you write a script containing for +example this code: + +\begin{verbatim} +user = form.getvalue("user").upper() +\end{verbatim} + +The problem with the code is that you should never expect that a +client will provide valid input to your scripts. For example, if a +curious user appends another \samp{user=foo} pair to the query string, +then the script would crash, because in this situation the +\code{getvalue("user")} method call returns a list instead of a +string. Calling the \method{toupper()} method on a list is not valid +(since lists do not have a method of this name) and results in an +\exception{AttributeError} exception. + +Therefore, the appropriate way to read form data values was to always +use the code which checks whether the obtained value is a single value +or a list of values. That's annoying and leads to less readable +scripts. + +A more convenient approach is to use the methods \method{getfirst()} +and \method{getlist()} provided by this higher level interface. + +\begin{methoddesc}[FieldStorage]{getfirst}{name\optional{, default}} + This method always returns only one value associated with form field + \var{name}. The method returns only the first value in case that + more values were posted under such name. Please note that the order + in which the values are received may vary from browser to browser + and should not be counted on.\footnote{Note that some recent + versions of the HTML specification do state what order the + field values should be supplied in, but knowing whether a + request was received from a conforming browser, or even from a + browser at all, is tedious and error-prone.} If no such form + field or value exists then the method returns the value specified by + the optional parameter \var{default}. This parameter defaults to + \code{None} if not specified. +\end{methoddesc} + +\begin{methoddesc}[FieldStorage]{getlist}{name} + This method always returns a list of values associated with form + field \var{name}. The method returns an empty list if no such form + field or value exists for \var{name}. It returns a list consisting + of one item if only one such value exists. +\end{methoddesc} + +Using these methods you can write nice compact code: + +\begin{verbatim} +import cgi +form = cgi.FieldStorage() +user = form.getfirst("user", "").upper() # This way it's safe. +for item in form.getlist("item"): + do_something(item) +\end{verbatim} + + +\subsection{Old classes} + +These classes, present in earlier versions of the \module{cgi} module, +are still supported for backward compatibility. New applications +should use the \class{FieldStorage} class. + +\class{SvFormContentDict} stores single value form content as +dictionary; it assumes each field name occurs in the form only once. + +\class{FormContentDict} stores multiple value form content as a +dictionary (the form items are lists of values). Useful if your form +contains multiple fields with the same name. + +Other classes (\class{FormContent}, \class{InterpFormContentDict}) are +present for backwards compatibility with really old applications only. +If you still use these and would be inconvenienced when they +disappeared from a next version of this module, drop me a note. + + +\subsection{Functions} +\nodename{Functions in cgi module} + +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. + +\begin{funcdesc}{parse}{fp\optional{, keep_blank_values\optional{, + strict_parsing}}} + Parse a query in the environment or from a file (the file defaults + to \code{sys.stdin}). The \var{keep_blank_values} and + \var{strict_parsing} parameters are passed to \function{parse_qs()} + unchanged. +\end{funcdesc} + +\begin{funcdesc}{parse_qs}{qs\optional{, keep_blank_values\optional{, + strict_parsing}}} +Parse a query string given as a string argument (data of type +\mimetype{application/x-www-form-urlencoded}). Data are +returned as a dictionary. The dictionary keys are the unique query +variable names and the values are lists of values for each name. + +The optional argument \var{keep_blank_values} is +a flag indicating whether blank values in +URL encoded queries should be treated as blank strings. +A true value indicates that blanks should be retained as +blank strings. The default false value indicates that +blank values are to be ignored and treated as if they were +not included. + +The optional argument \var{strict_parsing} is a flag indicating what +to do with parsing errors. If false (the default), errors +are silently ignored. If true, errors raise a \exception{ValueError} +exception. + +Use the \function{\refmodule{urllib}.urlencode()} function to convert +such dictionaries into query strings. + +\function{\refmodule{urlparse}.parse_qs()} is internally called to return the +parsed query string. + +\end{funcdesc} + +\begin{funcdesc}{parse_qsl}{qs\optional{, keep_blank_values\optional{, + strict_parsing}}} +Parse a query string given as a string argument (data of type +\mimetype{application/x-www-form-urlencoded}). Data are +returned as a list of name, value pairs. + +The optional argument \var{keep_blank_values} is +a flag indicating whether blank values in +URL encoded queries should be treated as blank strings. +A true value indicates that blanks should be retained as +blank strings. The default false value indicates that +blank values are to be ignored and treated as if they were +not included. + +The optional argument \var{strict_parsing} is a flag indicating what +to do with parsing errors. If false (the default), errors +are silently ignored. If true, errors raise a \exception{ValueError} +exception. + +Use the \function{\refmodule{urllib}.urlencode()} function to convert +such lists of pairs into query strings. + +\function{\refmodule{urlparse}.parse_qsl()} is internally called to return the +parsed query string list. + +\end{funcdesc} + +\begin{funcdesc}{parse_multipart}{fp, pdict} +Parse input of type \mimetype{multipart/form-data} (for +file uploads). Arguments are \var{fp} for the input file and +\var{pdict} for a dictionary containing other parameters in +the \mailheader{Content-Type} header. + +Returns a dictionary just like \function{parse_qs()} keys are the +field names, each value is a list of values for that field. This is +easy to use but not much good if you are expecting megabytes to be +uploaded --- in that case, use the \class{FieldStorage} class instead +which is much more flexible. + +Note that this does not parse nested multipart parts --- use +\class{FieldStorage} for that. +\end{funcdesc} + +\begin{funcdesc}{parse_header}{string} +Parse a MIME header (such as \mailheader{Content-Type}) into a main +value and a dictionary of parameters. +\end{funcdesc} + +\begin{funcdesc}{test}{} +Robust test CGI script, usable as main program. +Writes minimal HTTP headers and formats all information provided to +the script in HTML form. +\end{funcdesc} + +\begin{funcdesc}{print_environ}{} +Format the shell environment in HTML. +\end{funcdesc} + +\begin{funcdesc}{print_form}{form} +Format a form in HTML. +\end{funcdesc} + +\begin{funcdesc}{print_directory}{} +Format the current directory in HTML. +\end{funcdesc} + +\begin{funcdesc}{print_environ_usage}{} +Print a list of useful (used by CGI) environment variables in +HTML. +\end{funcdesc} + +\begin{funcdesc}{escape}{s\optional{, quote}} +Convert the characters +\character{\&}, \character{<} and \character{>} in string \var{s} to +HTML-safe sequences. Use this if you need to display text that might +contain such characters in HTML. If the optional flag \var{quote} is +true, the quotation mark character (\character{"}) is also translated; +this helps for inclusion in an HTML attribute value, as in \code{}. If the value to be quoted might include single- or +double-quote characters, or both, consider using the +\function{quoteattr()} function in the \refmodule{xml.sax.saxutils} +module instead. +\end{funcdesc} + + +\subsection{Caring about security \label{cgi-security}} + +\indexii{CGI}{security} + +There's one important rule: if you invoke an external program (via the +\function{os.system()} or \function{os.popen()} functions. or others +with similar functionality), make very sure you don't pass arbitrary +strings received from the client to the shell. This is a well-known +security hole whereby clever hackers anywhere on the Web can exploit a +gullible CGI script to invoke arbitrary shell commands. Even parts of +the URL or field names cannot be trusted, since the request doesn't +have to come from your form! + +To be on the safe side, if you must pass a string gotten from a form +to a shell command, you should make sure the string contains only +alphanumeric characters, dashes, underscores, and periods. + + +\subsection{Installing your CGI script on a \UNIX\ system} + +Read the documentation for your HTTP server and check with your local +system administrator to find the directory where CGI scripts should be +installed; usually this is in a directory \file{cgi-bin} in the server tree. + +Make sure that your script is readable and executable by ``others''; the +\UNIX{} file mode should be \code{0755} octal (use \samp{chmod 0755 +\var{filename}}). Make sure that the first line of the script contains +\code{\#!} starting in column 1 followed by the pathname of the Python +interpreter, for instance: + +\begin{verbatim} +#!/usr/local/bin/python +\end{verbatim} + +Make sure the Python interpreter exists and is executable by ``others''. + +Make sure that any files your script needs to read or write are +readable or writable, respectively, by ``others'' --- their mode +should be \code{0644} for readable and \code{0666} for writable. This +is because, for security reasons, the HTTP server executes your script +as user ``nobody'', without any special privileges. It can only read +(write, execute) files that everybody can read (write, execute). The +current directory at execution time is also different (it is usually +the server's cgi-bin directory) and the set of environment variables +is also different from what you get when you log in. In particular, don't +count on the shell's search path for executables (\envvar{PATH}) or +the Python module search path (\envvar{PYTHONPATH}) to be set to +anything interesting. + +If you need to load modules from a directory which is not on Python's +default module search path, you can change the path in your script, +before importing other modules. For example: + +\begin{verbatim} +import sys +sys.path.insert(0, "/usr/home/joe/lib/python") +sys.path.insert(0, "/usr/local/lib/python") +\end{verbatim} + +(This way, the directory inserted last will be searched first!) + +Instructions for non-\UNIX{} systems will vary; check your HTTP server's +documentation (it will usually have a section on CGI scripts). + + +\subsection{Testing your CGI script} + +Unfortunately, a CGI script will generally not run when you try it +from the command line, and a script that works perfectly from the +command line may fail mysteriously when run from the server. There's +one reason why you should still test your script from the command +line: if it contains a syntax error, the Python interpreter won't +execute it at all, and the HTTP server will most likely send a cryptic +error to the client. + +Assuming your script has no syntax errors, yet it does not work, you +have no choice but to read the next section. + + +\subsection{Debugging CGI scripts} \indexii{CGI}{debugging} + +First of all, check for trivial installation errors --- reading the +section above on installing your CGI script carefully can save you a +lot of time. If you wonder whether you have understood the +installation procedure correctly, try installing a copy of this module +file (\file{cgi.py}) as a CGI script. When invoked as a script, the file +will dump its environment and the contents of the form in HTML form. +Give it the right mode etc, and send it a request. If it's installed +in the standard \file{cgi-bin} directory, it should be possible to send it a +request by entering a URL into your browser of the form: + +\begin{verbatim} +http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home +\end{verbatim} + +If this gives an error of type 404, the server cannot find the script +-- perhaps you need to install it in a different directory. If it +gives another error, there's an installation problem that +you should fix before trying to go any further. If you get a nicely +formatted listing of the environment and form content (in this +example, the fields should be listed as ``addr'' with value ``At Home'' +and ``name'' with value ``Joe Blow''), the \file{cgi.py} script has been +installed correctly. If you follow the same procedure for your own +script, you should now be able to debug it. + +The next step could be to call the \module{cgi} module's +\function{test()} function from your script: replace its main code +with the single statement + +\begin{verbatim} +cgi.test() +\end{verbatim} + +This should produce the same results as those gotten from installing +the \file{cgi.py} file itself. + +When an ordinary Python script raises an unhandled exception (for +whatever reason: of a typo in a module name, a file that can't be +opened, etc.), the Python interpreter prints a nice traceback and +exits. While the Python interpreter will still do this when your CGI +script raises an exception, most likely the traceback will end up in +one of the HTTP server's log files, or be discarded altogether. + +Fortunately, once you have managed to get your script to execute +\emph{some} code, you can easily send tracebacks to the Web browser +using the \refmodule{cgitb} module. If you haven't done so already, +just add the line: + +\begin{verbatim} +import cgitb; cgitb.enable() +\end{verbatim} + +to the top of your script. Then try running it again; when a +problem occurs, you should see a detailed report that will +likely make apparent the cause of the crash. + +If you suspect that there may be a problem in importing the +\refmodule{cgitb} module, you can use an even more robust approach +(which only uses built-in modules): + +\begin{verbatim} +import sys +sys.stderr = sys.stdout +print "Content-Type: text/plain" +print +...your code here... +\end{verbatim} + +This relies on the Python interpreter to print the traceback. The +content type of the output is set to plain text, which disables all +HTML processing. If your script works, the raw HTML will be displayed +by your client. If it raises an exception, most likely after the +first two lines have been printed, a traceback will be displayed. +Because no HTML interpretation is going on, the traceback will be +readable. + + +\subsection{Common problems and solutions} + +\begin{itemize} +\item Most HTTP servers buffer the output from CGI scripts until the +script is completed. This means that it is not possible to display a +progress report on the client's display while the script is running. + +\item Check the installation instructions above. + +\item Check the HTTP server's log files. (\samp{tail -f logfile} in a +separate window may be useful!) + +\item Always check a script for syntax errors first, by doing something +like \samp{python script.py}. + +\item If your script does not have any syntax errors, try adding +\samp{import cgitb; cgitb.enable()} to the top of the script. + +\item When invoking external programs, make sure they can be found. +Usually, this means using absolute path names --- \envvar{PATH} is +usually not set to a very useful value in a CGI script. + +\item When reading or writing external files, make sure they can be read +or written by the userid under which your CGI script will be running: +this is typically the userid under which the web server is running, or some +explicitly specified userid for a web server's \samp{suexec} feature. + +\item Don't try to give a CGI script a set-uid mode. This doesn't work on +most systems, and is a security liability as well. +\end{itemize} + Added: sandbox/trunk/urilib/liburllib2.tex ============================================================================== --- (empty file) +++ sandbox/trunk/urilib/liburllib2.tex Sun Aug 5 23:42:33 2007 @@ -0,0 +1,873 @@ +\section{\module{urllib2} --- + extensible library for opening URLs} + +\declaremodule{standard}{urllib2} +\moduleauthor{Jeremy Hylton}{jhylton at users.sourceforge.net} +\sectionauthor{Moshe Zadka}{moshez at users.sourceforge.net} + +\modulesynopsis{An extensible library for opening URLs using a variety of + protocols} + +The \module{urllib2} module defines functions and classes which help +in opening URLs (mostly HTTP) in a complex world --- basic and digest +authentication, redirections, cookies and more. + +The \module{urllib2} module defines the following functions: + +\begin{funcdesc}{urlopen}{url\optional{, data}\optional{, timeout}} +Open the URL \var{url}, which can be either a string or a \class{Request} +object. + +\var{data} may be a string specifying additional data to send to the +server, or \code{None} if no such data is needed. +Currently HTTP requests are the only ones that use \var{data}; +the HTTP request will be a POST instead of a GET when the \var{data} +parameter is provided. \var{data} should be a buffer in the standard +\mimetype{application/x-www-form-urlencoded} format. The +\function{urllib.urlencode()} function takes a mapping or sequence of +2-tuples and returns a string in this format. + +The optional \var{timeout} parameter specifies a timeout in seconds for the +connection attempt (if not specified, or passed as None, the global default +timeout setting will be used). This actually only work for HTTP, HTTPS, FTP +and FTPS connections. + +This function returns a file-like object with two additional methods: + +\begin{itemize} + \item \method{geturl()} --- return the URL of the resource retrieved + \item \method{info()} --- return the meta-information of the page, as + a dictionary-like object +\end{itemize} + +Raises \exception{URLError} on errors. + +Note that \code{None} may be returned if no handler handles the +request (though the default installed global \class{OpenerDirector} +uses \class{UnknownHandler} to ensure this never happens). + +\versionchanged[\var{timeout} was added]{2.6} +\end{funcdesc} + +\begin{funcdesc}{install_opener}{opener} +Install an \class{OpenerDirector} instance as the default global +opener. Installing an opener is only necessary if you want urlopen to +use that opener; otherwise, simply call \method{OpenerDirector.open()} +instead of \function{urlopen()}. The code does not check for a real +\class{OpenerDirector}, and any class with the appropriate interface +will work. +\end{funcdesc} + +\begin{funcdesc}{build_opener}{\optional{handler, \moreargs}} +Return an \class{OpenerDirector} instance, which chains the +handlers in the order given. \var{handler}s can be either instances +of \class{BaseHandler}, or subclasses of \class{BaseHandler} (in +which case it must be possible to call the constructor without +any parameters). Instances of the following classes will be in +front of the \var{handler}s, unless the \var{handler}s contain +them, instances of them or subclasses of them: +\class{ProxyHandler}, \class{UnknownHandler}, \class{HTTPHandler}, +\class{HTTPDefaultErrorHandler}, \class{HTTPRedirectHandler}, +\class{FTPHandler}, \class{FileHandler}, \class{HTTPErrorProcessor}. + +If the Python installation has SSL support (\function{socket.ssl()} +exists), \class{HTTPSHandler} will also be added. + +Beginning in Python 2.3, a \class{BaseHandler} subclass may also +change its \member{handler_order} member variable to modify its +position in the handlers list. +\end{funcdesc} + + +The following exceptions are raised as appropriate: + +\begin{excdesc}{URLError} +The handlers raise this exception (or derived exceptions) when they +run into a problem. It is a subclass of \exception{IOError}. +\end{excdesc} + +\begin{excdesc}{HTTPError} +A subclass of \exception{URLError}, it can also function as a +non-exceptional file-like return value (the same thing that +\function{urlopen()} returns). This is useful when handling exotic +HTTP errors, such as requests for authentication. +\end{excdesc} + + +The following classes are provided: + +\begin{classdesc}{Request}{url\optional{, data}\optional{, headers} + \optional{, origin_req_host}\optional{, unverifiable}} +This class is an abstraction of a URL request. + +\var{url} should be a string containing a valid URL. + +\var{data} may be a string specifying additional data to send to the +server, or \code{None} if no such data is needed. +Currently HTTP requests are the only ones that use \var{data}; +the HTTP request will be a POST instead of a GET when the \var{data} +parameter is provided. \var{data} should be a buffer in the standard +\mimetype{application/x-www-form-urlencoded} format. The +\function{urllib.urlencode()} function takes a mapping or sequence of +2-tuples and returns a string in this format. + +\var{headers} should be a dictionary, and will be treated as if +\method{add_header()} was called with each key and value as arguments. + +The final two arguments are only of interest for correct handling of +third-party HTTP cookies: + +\var{origin_req_host} should be the request-host of the origin +transaction, as defined by \rfc{2965}. It defaults to +\code{cookielib.request_host(self)}. This is the host name or IP +address of the original request that was initiated by the user. For +example, if the request is for an image in an HTML document, this +should be the request-host of the request for the page containing the +image. + +\var{unverifiable} should indicate whether the request is +unverifiable, as defined by RFC 2965. It defaults to False. An +unverifiable request is one whose URL the user did not have the option +to approve. For example, if the request is for an image in an HTML +document, and the user had no option to approve the automatic fetching +of the image, this should be true. +\end{classdesc} + +\begin{classdesc}{OpenerDirector}{} +The \class{OpenerDirector} class opens URLs via \class{BaseHandler}s +chained together. It manages the chaining of handlers, and recovery +from errors. +\end{classdesc} + +\begin{classdesc}{BaseHandler}{} +This is the base class for all registered handlers --- and handles only +the simple mechanics of registration. +\end{classdesc} + +\begin{classdesc}{HTTPDefaultErrorHandler}{} +A class which defines a default handler for HTTP error responses; all +responses are turned into \exception{HTTPError} exceptions. +\end{classdesc} + +\begin{classdesc}{HTTPRedirectHandler}{} +A class to handle redirections. +\end{classdesc} + +\begin{classdesc}{HTTPCookieProcessor}{\optional{cookiejar}} +A class to handle HTTP Cookies. +\end{classdesc} + +\begin{classdesc}{ProxyHandler}{\optional{proxies}} +Cause requests to go through a proxy. +If \var{proxies} is given, it must be a dictionary mapping +protocol names to URLs of proxies. +The default is to read the list of proxies from the environment +variables \envvar{_proxy}. +\end{classdesc} + +\begin{classdesc}{HTTPPasswordMgr}{} +Keep a database of +\code{(\var{realm}, \var{uri}) -> (\var{user}, \var{password})} +mappings. +\end{classdesc} + +\begin{classdesc}{HTTPPasswordMgrWithDefaultRealm}{} +Keep a database of +\code{(\var{realm}, \var{uri}) -> (\var{user}, \var{password})} mappings. +A realm of \code{None} is considered a catch-all realm, which is searched +if no other realm fits. +\end{classdesc} + +\begin{classdesc}{AbstractBasicAuthHandler}{\optional{password_mgr}} +This is a mixin class that helps with HTTP authentication, both +to the remote host and to a proxy. +\var{password_mgr}, if given, should be something that is compatible +with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr} +for information on the interface that must be supported. +\end{classdesc} + +\begin{classdesc}{HTTPBasicAuthHandler}{\optional{password_mgr}} +Handle authentication with the remote host. +\var{password_mgr}, if given, should be something that is compatible +with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr} +for information on the interface that must be supported. +\end{classdesc} + +\begin{classdesc}{ProxyBasicAuthHandler}{\optional{password_mgr}} +Handle authentication with the proxy. +\var{password_mgr}, if given, should be something that is compatible +with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr} +for information on the interface that must be supported. +\end{classdesc} + +\begin{classdesc}{AbstractDigestAuthHandler}{\optional{password_mgr}} +This is a mixin class that helps with HTTP authentication, both +to the remote host and to a proxy. +\var{password_mgr}, if given, should be something that is compatible +with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr} +for information on the interface that must be supported. +\end{classdesc} + +\begin{classdesc}{HTTPDigestAuthHandler}{\optional{password_mgr}} +Handle authentication with the remote host. +\var{password_mgr}, if given, should be something that is compatible +with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr} +for information on the interface that must be supported. +\end{classdesc} + +\begin{classdesc}{ProxyDigestAuthHandler}{\optional{password_mgr}} +Handle authentication with the proxy. +\var{password_mgr}, if given, should be something that is compatible +with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr} +for information on the interface that must be supported. +\end{classdesc} + +\begin{classdesc}{HTTPHandler}{} +A class to handle opening of HTTP URLs. +\end{classdesc} + +\begin{classdesc}{HTTPSHandler}{} +A class to handle opening of HTTPS URLs. +\end{classdesc} + +\begin{classdesc}{FileHandler}{} +Open local files. +\end{classdesc} + +\begin{classdesc}{FTPHandler}{} +Open FTP URLs. +\end{classdesc} + +\begin{classdesc}{CacheFTPHandler}{} +Open FTP URLs, keeping a cache of open FTP connections to minimize +delays. +\end{classdesc} + +\begin{classdesc}{UnknownHandler}{} +A catch-all class to handle unknown URLs. +\end{classdesc} + + +\subsection{Request Objects \label{request-objects}} + +The following methods describe all of \class{Request}'s public interface, +and so all must be overridden in subclasses. + +\begin{methoddesc}[Request]{add_data}{data} +Set the \class{Request} data to \var{data}. This is ignored by all +handlers except HTTP handlers --- and there it should be a byte +string, and will change the request to be \code{POST} rather than +\code{GET}. +\end{methoddesc} + +\begin{methoddesc}[Request]{get_method}{} +Return a string indicating the HTTP request method. This is only +meaningful for HTTP requests, and currently always returns +\code{'GET'} or \code{'POST'}. +\end{methoddesc} + +\begin{methoddesc}[Request]{has_data}{} +Return whether the instance has a non-\code{None} data. +\end{methoddesc} + +\begin{methoddesc}[Request]{get_data}{} +Return the instance's data. +\end{methoddesc} + +\begin{methoddesc}[Request]{add_header}{key, val} +Add another header to the request. Headers are currently ignored by +all handlers except HTTP handlers, where they are added to the list +of headers sent to the server. Note that there cannot be more than +one header with the same name, and later calls will overwrite +previous calls in case the \var{key} collides. Currently, this is +no loss of HTTP functionality, since all headers which have meaning +when used more than once have a (header-specific) way of gaining the +same functionality using only one header. +\end{methoddesc} + +\begin{methoddesc}[Request]{add_unredirected_header}{key, header} +Add a header that will not be added to a redirected request. +\versionadded{2.4} +\end{methoddesc} + +\begin{methoddesc}[Request]{has_header}{header} +Return whether the instance has the named header (checks both regular +and unredirected). +\versionadded{2.4} +\end{methoddesc} + +\begin{methoddesc}[Request]{get_full_url}{} +Return the URL given in the constructor. +\end{methoddesc} + +\begin{methoddesc}[Request]{get_type}{} +Return the type of the URL --- also known as the scheme. +\end{methoddesc} + +\begin{methoddesc}[Request]{get_host}{} +Return the host to which a connection will be made. +\end{methoddesc} + +\begin{methoddesc}[Request]{get_selector}{} +Return the selector --- the part of the URL that is sent to +the server. +\end{methoddesc} + +\begin{methoddesc}[Request]{set_proxy}{host, type} +Prepare the request by connecting to a proxy server. The \var{host} +and \var{type} will replace those of the instance, and the instance's +selector will be the original URL given in the constructor. +\end{methoddesc} + +\begin{methoddesc}[Request]{get_origin_req_host}{} +Return the request-host of the origin transaction, as defined by +\rfc{2965}. See the documentation for the \class{Request} +constructor. +\end{methoddesc} + +\begin{methoddesc}[Request]{is_unverifiable}{} +Return whether the request is unverifiable, as defined by RFC 2965. +See the documentation for the \class{Request} constructor. +\end{methoddesc} + + +\subsection{OpenerDirector Objects \label{opener-director-objects}} + +\class{OpenerDirector} instances have the following methods: + +\begin{methoddesc}[OpenerDirector]{add_handler}{handler} +\var{handler} should be an instance of \class{BaseHandler}. The +following methods are searched, and added to the possible chains (note +that HTTP errors are a special case). + +\begin{itemize} + \item \method{\var{protocol}_open()} --- + signal that the handler knows how to open \var{protocol} URLs. + \item \method{http_error_\var{type}()} --- + signal that the handler knows how to handle HTTP errors with HTTP + error code \var{type}. + \item \method{\var{protocol}_error()} --- + signal that the handler knows how to handle errors from + (non-\code{http}) \var{protocol}. + \item \method{\var{protocol}_request()} --- + signal that the handler knows how to pre-process \var{protocol} + requests. + \item \method{\var{protocol}_response()} --- + signal that the handler knows how to post-process \var{protocol} + responses. +\end{itemize} +\end{methoddesc} + +\begin{methoddesc}[OpenerDirector]{open}{url\optional{, data}{\optional{, timeout}}} +Open the given \var{url} (which can be a request object or a string), +optionally passing the given \var{data}. +Arguments, return values and exceptions raised are the same as those +of \function{urlopen()} (which simply calls the \method{open()} method +on the currently installed global \class{OpenerDirector}). The optional +\var{timeout} parameter specifies a timeout in seconds for the connection +attempt (if not specified, or passed as None, the global default timeout +setting will be used; this actually only work for HTTP, HTTPS, FTP +and FTPS connections). + +\versionchanged[\var{timeout} was added]{2.6} +\end{methoddesc} + +\begin{methoddesc}[OpenerDirector]{error}{proto\optional{, + arg\optional{, \moreargs}}} +Handle an error of the given protocol. This will call the registered +error handlers for the given protocol with the given arguments (which +are protocol specific). The HTTP protocol is a special case which +uses the HTTP response code to determine the specific error handler; +refer to the \method{http_error_*()} methods of the handler classes. + +Return values and exceptions raised are the same as those +of \function{urlopen()}. +\end{methoddesc} + +OpenerDirector objects open URLs in three stages: + +The order in which these methods are called within each stage is +determined by sorting the handler instances. + +\begin{enumerate} + \item Every handler with a method named like + \method{\var{protocol}_request()} has that method called to + pre-process the request. + + \item Handlers with a method named like + \method{\var{protocol}_open()} are called to handle the request. + This stage ends when a handler either returns a + non-\constant{None} value (ie. a response), or raises an exception + (usually \exception{URLError}). Exceptions are allowed to propagate. + + In fact, the above algorithm is first tried for methods named + \method{default_open}. If all such methods return + \constant{None}, the algorithm is repeated for methods named like + \method{\var{protocol}_open()}. If all such methods return + \constant{None}, the algorithm is repeated for methods named + \method{unknown_open()}. + + Note that the implementation of these methods may involve calls of + the parent \class{OpenerDirector} instance's \method{.open()} and + \method{.error()} methods. + + \item Every handler with a method named like + \method{\var{protocol}_response()} has that method called to + post-process the response. + +\end{enumerate} + +\subsection{BaseHandler Objects \label{base-handler-objects}} + +\class{BaseHandler} objects provide a couple of methods that are +directly useful, and others that are meant to be used by derived +classes. These are intended for direct use: + +\begin{methoddesc}[BaseHandler]{add_parent}{director} +Add a director as parent. +\end{methoddesc} + +\begin{methoddesc}[BaseHandler]{close}{} +Remove any parents. +\end{methoddesc} + +The following members and methods should only be used by classes +derived from \class{BaseHandler}. \note{The convention has been +adopted that subclasses defining \method{\var{protocol}_request()} or +\method{\var{protocol}_response()} methods are named +\class{*Processor}; all others are named \class{*Handler}.} + + +\begin{memberdesc}[BaseHandler]{parent} +A valid \class{OpenerDirector}, which can be used to open using a +different protocol, or handle errors. +\end{memberdesc} + +\begin{methoddesc}[BaseHandler]{default_open}{req} +This method is \emph{not} defined in \class{BaseHandler}, but +subclasses should define it if they want to catch all URLs. + +This method, if implemented, will be called by the parent +\class{OpenerDirector}. It should return a file-like object as +described in the return value of the \method{open()} of +\class{OpenerDirector}, or \code{None}. It should raise +\exception{URLError}, unless a truly exceptional thing happens (for +example, \exception{MemoryError} should not be mapped to +\exception{URLError}). + +This method will be called before any protocol-specific open method. +\end{methoddesc} + +\begin{methoddescni}[BaseHandler]{\var{protocol}_open}{req} +This method is \emph{not} defined in \class{BaseHandler}, but +subclasses should define it if they want to handle URLs with the given +protocol. + +This method, if defined, will be called by the parent +\class{OpenerDirector}. Return values should be the same as for +\method{default_open()}. +\end{methoddescni} + +\begin{methoddesc}[BaseHandler]{unknown_open}{req} +This method is \var{not} defined in \class{BaseHandler}, but +subclasses should define it if they want to catch all URLs with no +specific registered handler to open it. + +This method, if implemented, will be called by the \member{parent} +\class{OpenerDirector}. Return values should be the same as for +\method{default_open()}. +\end{methoddesc} + +\begin{methoddesc}[BaseHandler]{http_error_default}{req, fp, code, msg, hdrs} +This method is \emph{not} defined in \class{BaseHandler}, but +subclasses should override it if they intend to provide a catch-all +for otherwise unhandled HTTP errors. It will be called automatically +by the \class{OpenerDirector} getting the error, and should not +normally be called in other circumstances. + +\var{req} will be a \class{Request} object, \var{fp} will be a +file-like object with the HTTP error body, \var{code} will be the +three-digit code of the error, \var{msg} will be the user-visible +explanation of the code and \var{hdrs} will be a mapping object with +the headers of the error. + +Return values and exceptions raised should be the same as those +of \function{urlopen()}. +\end{methoddesc} + +\begin{methoddesc}[BaseHandler]{http_error_\var{nnn}}{req, fp, code, msg, hdrs} +\var{nnn} should be a three-digit HTTP error code. This method is +also not defined in \class{BaseHandler}, but will be called, if it +exists, on an instance of a subclass, when an HTTP error with code +\var{nnn} occurs. + +Subclasses should override this method to handle specific HTTP +errors. + +Arguments, return values and exceptions raised should be the same as +for \method{http_error_default()}. +\end{methoddesc} + +\begin{methoddescni}[BaseHandler]{\var{protocol}_request}{req} +This method is \emph{not} defined in \class{BaseHandler}, but +subclasses should define it if they want to pre-process requests of +the given protocol. + +This method, if defined, will be called by the parent +\class{OpenerDirector}. \var{req} will be a \class{Request} object. +The return value should be a \class{Request} object. +\end{methoddescni} + +\begin{methoddescni}[BaseHandler]{\var{protocol}_response}{req, response} +This method is \emph{not} defined in \class{BaseHandler}, but +subclasses should define it if they want to post-process responses of +the given protocol. + +This method, if defined, will be called by the parent +\class{OpenerDirector}. \var{req} will be a \class{Request} object. +\var{response} will be an object implementing the same interface as +the return value of \function{urlopen()}. The return value should +implement the same interface as the return value of +\function{urlopen()}. +\end{methoddescni} + +\subsection{HTTPRedirectHandler Objects \label{http-redirect-handler}} + +\note{Some HTTP redirections require action from this module's client + code. If this is the case, \exception{HTTPError} is raised. See + \rfc{2616} for details of the precise meanings of the various + redirection codes.} + +\begin{methoddesc}[HTTPRedirectHandler]{redirect_request}{req, + fp, code, msg, hdrs} +Return a \class{Request} or \code{None} in response to a redirect. +This is called by the default implementations of the +\method{http_error_30*()} methods when a redirection is received from +the server. If a redirection should take place, return a new +\class{Request} to allow \method{http_error_30*()} to perform the +redirect. Otherwise, raise \exception{HTTPError} if no other handler +should try to handle this URL, or return \code{None} if you can't but +another handler might. + +\begin{notice} + The default implementation of this method does not strictly + follow \rfc{2616}, which says that 301 and 302 responses to \code{POST} + requests must not be automatically redirected without confirmation by + the user. In reality, browsers do allow automatic redirection of + these responses, changing the POST to a \code{GET}, and the default + implementation reproduces this behavior. +\end{notice} +\end{methoddesc} + + +\begin{methoddesc}[HTTPRedirectHandler]{http_error_301}{req, + fp, code, msg, hdrs} +Redirect to the \code{Location:} URL. This method is called by +the parent \class{OpenerDirector} when getting an HTTP +`moved permanently' response. The 301 redirection is cached as per +\rfc{2616}. +\end{methoddesc} + +\begin{methoddesc}[HTTPRedirectHandler]{http_error_302}{req, + fp, code, msg, hdrs} +The same as \method{http_error_301()}, but called for the +`found' response. +\end{methoddesc} + +\begin{methoddesc}[HTTPRedirectHandler]{http_error_303}{req, + fp, code, msg, hdrs} +The same as \method{http_error_301()}, but called for the +`see other' response. +\end{methoddesc} + +\begin{methoddesc}[HTTPRedirectHandler]{http_error_307}{req, + fp, code, msg, hdrs} +The same as \method{http_error_301()}, but called for the +`temporary redirect' response. +\end{methoddesc} + + +\subsection{HTTPCookieProcessor Objects \label{http-cookie-processor}} + +\versionadded{2.4} + +\class{HTTPCookieProcessor} instances have one attribute: + +\begin{memberdesc}[HTTPCookieProcessor]{cookiejar} +The \class{cookielib.CookieJar} in which cookies are stored. +\end{memberdesc} + + +\subsection{ProxyHandler Objects \label{proxy-handler}} + +\begin{methoddescni}[ProxyHandler]{\var{protocol}_open}{request} +The \class{ProxyHandler} will have a method +\method{\var{protocol}_open()} for every \var{protocol} which has a +proxy in the \var{proxies} dictionary given in the constructor. The +method will modify requests to go through the proxy, by calling +\code{request.set_proxy()}, and call the next handler in the chain to +actually execute the protocol. +\end{methoddescni} + + +\subsection{HTTPPasswordMgr Objects \label{http-password-mgr}} + +These methods are available on \class{HTTPPasswordMgr} and +\class{HTTPPasswordMgrWithDefaultRealm} objects. + +\begin{methoddesc}[HTTPPasswordMgr]{add_password}{realm, uri, user, passwd} +\var{uri} can be either a single URI, or a sequence of URIs. \var{realm}, +\var{user} and \var{passwd} must be strings. This causes +\code{(\var{user}, \var{passwd})} to be used as authentication tokens +when authentication for \var{realm} and a super-URI of any of the +given URIs is given. +\end{methoddesc} + +\begin{methoddesc}[HTTPPasswordMgr]{find_user_password}{realm, authuri} +Get user/password for given realm and URI, if any. This method will +return \code{(None, None)} if there is no matching user/password. + +For \class{HTTPPasswordMgrWithDefaultRealm} objects, the realm +\code{None} will be searched if the given \var{realm} has no matching +user/password. +\end{methoddesc} + + +\subsection{AbstractBasicAuthHandler Objects + \label{abstract-basic-auth-handler}} + +\begin{methoddesc}[AbstractBasicAuthHandler]{http_error_auth_reqed} + {authreq, host, req, headers} +Handle an authentication request by getting a user/password pair, and +re-trying the request. \var{authreq} should be the name of the header +where the information about the realm is included in the request, +\var{host} specifies the URL and path to authenticate for, \var{req} +should be the (failed) \class{Request} object, and \var{headers} +should be the error headers. + +\var{host} is either an authority (e.g. \code{"python.org"}) or a URL +containing an authority component (e.g. \code{"http://python.org/"}). +In either case, the authority must not contain a userinfo component +(so, \code{"python.org"} and \code{"python.org:80"} are fine, +\code{"joe:password at python.org"} is not). +\end{methoddesc} + + +\subsection{HTTPBasicAuthHandler Objects + \label{http-basic-auth-handler}} + +\begin{methoddesc}[HTTPBasicAuthHandler]{http_error_401}{req, fp, code, + msg, hdrs} +Retry the request with authentication information, if available. +\end{methoddesc} + + +\subsection{ProxyBasicAuthHandler Objects + \label{proxy-basic-auth-handler}} + +\begin{methoddesc}[ProxyBasicAuthHandler]{http_error_407}{req, fp, code, + msg, hdrs} +Retry the request with authentication information, if available. +\end{methoddesc} + + +\subsection{AbstractDigestAuthHandler Objects + \label{abstract-digest-auth-handler}} + +\begin{methoddesc}[AbstractDigestAuthHandler]{http_error_auth_reqed} + {authreq, host, req, headers} +\var{authreq} should be the name of the header where the information about +the realm is included in the request, \var{host} should be the host to +authenticate to, \var{req} should be the (failed) \class{Request} +object, and \var{headers} should be the error headers. +\end{methoddesc} + + +\subsection{HTTPDigestAuthHandler Objects + \label{http-digest-auth-handler}} + +\begin{methoddesc}[HTTPDigestAuthHandler]{http_error_401}{req, fp, code, + msg, hdrs} +Retry the request with authentication information, if available. +\end{methoddesc} + + +\subsection{ProxyDigestAuthHandler Objects + \label{proxy-digest-auth-handler}} + +\begin{methoddesc}[ProxyDigestAuthHandler]{http_error_407}{req, fp, code, + msg, hdrs} +Retry the request with authentication information, if available. +\end{methoddesc} + + +\subsection{HTTPHandler Objects \label{http-handler-objects}} + +\begin{methoddesc}[HTTPHandler]{http_open}{req} +Send an HTTP request, which can be either GET or POST, depending on +\code{\var{req}.has_data()}. +\end{methoddesc} + + +\subsection{HTTPSHandler Objects \label{https-handler-objects}} + +\begin{methoddesc}[HTTPSHandler]{https_open}{req} +Send an HTTPS request, which can be either GET or POST, depending on +\code{\var{req}.has_data()}. +\end{methoddesc} + + +\subsection{FileHandler Objects \label{file-handler-objects}} + +\begin{methoddesc}[FileHandler]{file_open}{req} +Open the file locally, if there is no host name, or +the host name is \code{'localhost'}. Change the +protocol to \code{ftp} otherwise, and retry opening +it using \member{parent}. +\end{methoddesc} + + +\subsection{FTPHandler Objects \label{ftp-handler-objects}} + +\begin{methoddesc}[FTPHandler]{ftp_open}{req} +Open the FTP file indicated by \var{req}. +The login is always done with empty username and password. +\end{methoddesc} + + +\subsection{CacheFTPHandler Objects \label{cacheftp-handler-objects}} + +\class{CacheFTPHandler} objects are \class{FTPHandler} objects with +the following additional methods: + +\begin{methoddesc}[CacheFTPHandler]{setTimeout}{t} +Set timeout of connections to \var{t} seconds. +\end{methoddesc} + +\begin{methoddesc}[CacheFTPHandler]{setMaxConns}{m} +Set maximum number of cached connections to \var{m}. +\end{methoddesc} + + +\subsection{UnknownHandler Objects \label{unknown-handler-objects}} + +\begin{methoddesc}[UnknownHandler]{unknown_open}{} +Raise a \exception{URLError} exception. +\end{methoddesc} + + +\subsection{HTTPErrorProcessor Objects \label{http-error-processor-objects}} + +\versionadded{2.4} + +\begin{methoddesc}[HTTPErrorProcessor]{unknown_open}{} +Process HTTP error responses. + +For 200 error codes, the response object is returned immediately. + +For non-200 error codes, this simply passes the job on to the +\method{\var{protocol}_error_\var{code}()} handler methods, via +\method{OpenerDirector.error()}. Eventually, +\class{urllib2.HTTPDefaultErrorHandler} will raise an +\exception{HTTPError} if no other handler handles the error. +\end{methoddesc} + + +\subsection{Examples \label{urllib2-examples}} + +This example gets the python.org main page and displays the first 100 +bytes of it: + +\begin{verbatim} +>>> import urllib2 +>>> f = urllib2.urlopen('http://www.python.org/') +>>> print f.read(100) + +>> import urllib2 +>>> req = urllib2.Request(url='https://localhost/cgi-bin/test.cgi', +... data='This data is passed to stdin of the CGI') +>>> f = urllib2.urlopen(req) +>>> print f.read() +Got Data: "This data is passed to stdin of the CGI" +\end{verbatim} + +The code for the sample CGI used in the above example is: + +\begin{verbatim} +#!/usr/bin/env python +import sys +data = sys.stdin.read() +print 'Content-type: text-plain\n\nGot Data: "%s"' % data +\end{verbatim} + + +Use of Basic HTTP Authentication: + +\begin{verbatim} +import urllib2 +# Create an OpenerDirector with support for Basic HTTP Authentication... +auth_handler = urllib2.HTTPBasicAuthHandler() +auth_handler.add_password(realm='PDQ Application', + uri='https://mahler:8092/site-updates.py', + user='klem', + passwd='kadidd!ehopper') +opener = urllib2.build_opener(auth_handler) +# ...and install it globally so it can be used with urlopen. +urllib2.install_opener(opener) +urllib2.urlopen('http://www.example.com/login.html') +\end{verbatim} + +\function{build_opener()} provides many handlers by default, including a +\class{ProxyHandler}. By default, \class{ProxyHandler} uses the +environment variables named \code{_proxy}, where \code{} +is the URL scheme involved. For example, the \envvar{http_proxy} +environment variable is read to obtain the HTTP proxy's URL. + +This example replaces the default \class{ProxyHandler} with one that uses +programatically-supplied proxy URLs, and adds proxy authorization support +with \class{ProxyBasicAuthHandler}. + +\begin{verbatim} +proxy_handler = urllib2.ProxyHandler({'http': 'http://www.example.com:3128/'}) +proxy_auth_handler = urllib2.HTTPBasicAuthHandler() +proxy_auth_handler.add_password('realm', 'host', 'username', 'password') + +opener = build_opener(proxy_handler, proxy_auth_handler) +# This time, rather than install the OpenerDirector, we use it directly: +opener.open('http://www.example.com/login.html') +\end{verbatim} + + +Adding HTTP headers: + +Use the \var{headers} argument to the \class{Request} constructor, or: + +\begin{verbatim} +import urllib2 +req = urllib2.Request('http://www.example.com/') +req.add_header('Referer', 'http://www.python.org/') +r = urllib2.urlopen(req) +\end{verbatim} + +\class{OpenerDirector} automatically adds a \mailheader{User-Agent} +header to every \class{Request}. To change this: + +\begin{verbatim} +import urllib2 +opener = urllib2.build_opener() +opener.addheaders = [('User-agent', 'Mozilla/5.0')] +opener.open('http://www.example.com/') +\end{verbatim} + +Also, remember that a few standard headers +(\mailheader{Content-Length}, \mailheader{Content-Type} and +\mailheader{Host}) are added when the \class{Request} is passed to +\function{urlopen()} (or \method{OpenerDirector.open()}). Added: sandbox/trunk/urilib/liburlparse.tex ============================================================================== --- (empty file) +++ sandbox/trunk/urilib/liburlparse.tex Sun Aug 5 23:42:33 2007 @@ -0,0 +1,310 @@ +\section{\module{urlparse} --- + Parse URLs into components} +\declaremodule{standard}{urlparse} + +\modulesynopsis{Parse URLs into components.} + +\index{WWW} +\index{World Wide Web} +\index{URL} +\indexii{URL}{parsing} +\indexii{relative}{URL} + + +This module defines a standard interface to break Uniform Resource +Locator (URL) strings up in components (addressing scheme, network +location, path etc.), to combine the components back into a URL +string, and to convert a ``relative URL'' to an absolute URL given a +``base URL.'' + +The module has been designed to match the Internet RFC on Relative +Uniform Resource Locators (and discovered a bug in an earlier +draft!). It supports the following URL schemes: +\code{file}, \code{ftp}, \code{gopher}, \code{hdl}, \code{http}, +\code{https}, \code{imap}, \code{mailto}, \code{mms}, \code{news}, +\code{nntp}, \code{prospero}, \code{rsync}, \code{rtsp}, \code{rtspu}, +\code{sftp}, \code{shttp}, \code{sip}, \code{sips}, \code{snews}, \code{svn}, +\code{svn+ssh}, \code{telnet}, \code{wais}. + +\versionadded[Support for the \code{sftp} and \code{sips} schemes]{2.5} + +The \module{urlparse} module defines the following functions: + +\begin{funcdesc}{urlparse}{urlstring\optional{, + default_scheme\optional{, allow_fragments}}} +Parse a URL into six components, returning a 6-tuple. This +corresponds to the general structure of a URL: +\code{\var{scheme}://\var{netloc}/\var{path};\var{parameters}?\var{query}\#\var{fragment}}. +Each tuple item is a string, possibly empty. +The components are not broken up in smaller parts (for example, the network +location is a single string), and \% escapes are not expanded. +The delimiters as shown above are not part of the result, +except for a leading slash in the \var{path} component, which is +retained if present. For example: + +\begin{verbatim} +>>> from urlparse import urlparse +>>> o = urlparse('http://www.cwi.nl:80/%7Eguido/Python.html') +>>> o +('http', 'www.cwi.nl:80', '/%7Eguido/Python.html', '', '', '') +>>> o.scheme +'http' +>>> o.port +80 +>>> o.geturl() +'http://www.cwi.nl:80/%7Eguido/Python.html' +\end{verbatim} + +If the \var{default_scheme} argument is specified, it gives the +default addressing scheme, to be used only if the URL does not +specify one. The default value for this argument is the empty string. + +If the \var{allow_fragments} argument is false, fragment identifiers +are not allowed, even if the URL's addressing scheme normally does +support them. The default value for this argument is \constant{True}. + +The return value is actually an instance of a subclass of +\pytype{tuple}. This class has the following additional read-only +convenience attributes: + +\begin{tableiv}{l|c|l|c}{member}{Attribute}{Index}{Value}{Value if not present} + \lineiv{scheme} {0} {URL scheme specifier} {empty string} + \lineiv{netloc} {1} {Network location part} {empty string} + \lineiv{path} {2} {Hierarchical path} {empty string} + \lineiv{params} {3} {Parameters for last path element} {empty string} + \lineiv{query} {4} {Query component} {empty string} + \lineiv{fragment}{5} {Fragment identifier} {empty string} + \lineiv{username}{ } {User name} {\constant{None}} + \lineiv{password}{ } {Password} {\constant{None}} + \lineiv{hostname}{ } {Host name (lower case)} {\constant{None}} + \lineiv{port} { } {Port number as integer, if present} {\constant{None}} +\end{tableiv} + +See section~\ref{urlparse-result-object}, ``Results of +\function{urlparse()} and \function{urlsplit()},'' for more +information on the result object. + +\versionchanged[Added attributes to return value]{2.5} +\end{funcdesc} + +\begin{funcdesc}{urlunparse}{parts} +Construct a URL from a tuple as returned by \code{urlparse()}. +The \var{parts} argument can be any six-item iterable. +This may result in a slightly different, but equivalent URL, if the +URL that was parsed originally had unnecessary delimiters (for example, +a ? with an empty query; the RFC states that these are equivalent). +\end{funcdesc} + +\begin{funcdesc}{urlsplit}{urlstring\optional{, + default_scheme\optional{, allow_fragments}}} +This is similar to \function{urlparse()}, but does not split the +params from the URL. This should generally be used instead of +\function{urlparse()} if the more recent URL syntax allowing +parameters to be applied to each segment of the \var{path} portion of +the URL (see \rfc{2396}) is wanted. A separate function is needed to +separate the path segments and parameters. This function returns a +5-tuple: (addressing scheme, network location, path, query, fragment +identifier). + +The return value is actually an instance of a subclass of +\pytype{tuple}. This class has the following additional read-only +convenience attributes: + +\begin{tableiv}{l|c|l|c}{member}{Attribute}{Index}{Value}{Value if not present} + \lineiv{scheme} {0} {URL scheme specifier} {empty string} + \lineiv{netloc} {1} {Network location part} {empty string} + \lineiv{path} {2} {Hierarchical path} {empty string} + \lineiv{query} {3} {Query component} {empty string} + \lineiv{fragment} {4} {Fragment identifier} {empty string} + \lineiv{username} { } {User name} {\constant{None}} + \lineiv{password} { } {Password} {\constant{None}} + \lineiv{hostname} { } {Host name (lower case)} {\constant{None}} + \lineiv{port} { } {Port number as integer, if present} {\constant{None}} + \lineiv{parsedquery} { } {parsed query string} {empty string} + \lineiv{parsedquerylist} { } {parsed query string as list} {empty string} +\end{tableiv} + +See section~\ref{urlparse-result-object}, ``Results of +\function{urlparse()} and \function{urlsplit()},'' for more +information on the result object. + +\versionadded{2.2} +\versionchanged[Added attributes to return value]{2.5} +\end{funcdesc} + +\begin{funcdesc}{urlunsplit}{parts} +Combine the elements of a tuple as returned by \function{urlsplit()} +into a complete URL as a string. +The \var{parts} argument can be any five-item iterable. +This may result in a slightly different, but equivalent URL, if the +URL that was parsed originally had unnecessary delimiters (for example, +a ? with an empty query; the RFC states that these are equivalent). +\versionadded{2.2} +\end{funcdesc} + +\begin{funcdesc}{urljoin}{base, url\optional{, allow_fragments}} +Construct a full (``absolute'') URL by combining a ``base URL'' +(\var{base}) with another URL (\var{url}). Informally, this +uses components of the base URL, in particular the addressing scheme, +the network location and (part of) the path, to provide missing +components in the relative URL. For example: + +\begin{verbatim} +>>> from urlparse import urljoin +>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html') +'http://www.cwi.nl/%7Eguido/FAQ.html' +\end{verbatim} + +The \var{allow_fragments} argument has the same meaning and default as +for \function{urlparse()}. + +\note{If \var{url} is an absolute URL (that is, starting with \code{//} + or \code{scheme://}), the \var{url}'s host name and/or scheme + will be present in the result. For example:} + +\begin{verbatim} +>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', +... '//www.python.org/%7Eguido') +'http://www.python.org/%7Eguido' +\end{verbatim} + +If you do not want that behavior, preprocess +the \var{url} with \function{urlsplit()} and \function{urlunsplit()}, +removing possible \emph{scheme} and \emph{netloc} parts. +\end{funcdesc} + +\begin{funcdesc}{urldefrag}{url} +If \var{url} contains a fragment identifier, returns a modified +version of \var{url} with no fragment identifier, and the fragment +identifier as a separate string. If there is no fragment identifier +in \var{url}, returns \var{url} unmodified and an empty string. +\end{funcdesc} + +\begin{funcdesc}{parse_qs}{qs\optional{, keep_blank_values\optional{, + strict_parsing}}} +Parse a query string given as a string argument (data of type +\mimetype{application/x-www-form-urlencoded}). Data are +returned as a dictionary. The dictionary keys are the unique query +variable names and the values are lists of values for each name. + +The optional argument \var{keep_blank_values} is +a flag indicating whether blank values in +URL encoded queries should be treated as blank strings. +A true value indicates that blanks should be retained as +blank strings. The default false value indicates that +blank values are to be ignored and treated as if they were +not included. + +The optional argument \var{strict_parsing} is a flag indicating what +to do with parsing errors. If false (the default), errors +are silently ignored. If true, errors raise a \exception{ValueError} +exception. + +Use the \function{\refmodule{urllib}.urlencode()} function to convert +such dictionaries into query strings. + +This is also available as \function{parsedquery()} function at the instance of +urlparse. + +\end{funcdesc} + +\begin{funcdesc}{parse_qsl}{qs\optional{, keep_blank_values\optional{, + strict_parsing}}} +Parse a query string given as a string argument (data of type +\mimetype{application/x-www-form-urlencoded}). Data are +returned as a list of name, value pairs. + +The optional argument \var{keep_blank_values} is +a flag indicating whether blank values in +URL encoded queries should be treated as blank strings. +A true value indicates that blanks should be retained as +blank strings. The default false value indicates that +blank values are to be ignored and treated as if they were +not included. + +The optional argument \var{strict_parsing} is a flag indicating what +to do with parsing errors. If false (the default), errors +are silently ignored. If true, errors raise a \exception{ValueError} +exception. + +Use the \function{\refmodule{urllib}.urlencode()} function to convert +such lists of pairs into query strings. +\end{funcdesc} + +This is also available as \function{parsedquerylist()} function at the +instance of urlparse. + + + +\begin{seealso} + \seerfc{1738}{Uniform Resource Locators (URL)}{ + This specifies the formal syntax and semantics of absolute + URLs.} + \seerfc{1808}{Relative Uniform Resource Locators}{ + This Request For Comments includes the rules for joining an + absolute and a relative URL, including a fair number of + ``Abnormal Examples'' which govern the treatment of border + cases.} + \seerfc{2396}{Uniform Resource Identifiers (URI): Generic Syntax}{ + Document describing the generic syntactic requirements for + both Uniform Resource Names (URNs) and Uniform Resource + Locators (URLs).} +\end{seealso} + + +\subsection{Results of \function{urlparse()} and \function{urlsplit()} + \label{urlparse-result-object}} + +The result objects from the \function{urlparse()} and +\function{urlsplit()} functions are subclasses of the \pytype{tuple} +type. These subclasses add the attributes described in those +functions, as well as provide an additional method: + +\begin{methoddesc}[ParseResult]{geturl}{} + Return the re-combined version of the original URL as a string. + This may differ from the original URL in that the scheme will always + be normalized to lower case and empty components may be dropped. + Specifically, empty parameters, queries, and fragment identifiers + will be removed. + + The result of this method is a fixpoint if passed back through the + original parsing function: + +\begin{verbatim} +>>> import urlparse +>>> url = 'HTTP://www.Python.org/doc/#' + +>>> r1 = urlparse.urlsplit(url) +>>> r1.geturl() +'http://www.Python.org/doc/' + +>>> r2 = urlparse.urlsplit(r1.geturl()) +>>> r2.geturl() +'http://www.Python.org/doc/' +\end{verbatim} + +\versionadded{2.5} +\end{methoddesc} + +The following classes provide the implementations of the parse results:: + +\begin{classdesc*}{BaseResult} + Base class for the concrete result classes. This provides most of + the attribute definitions. It does not provide a \method{geturl()} + method. It is derived from \class{tuple}, but does not override the + \method{__init__()} or \method{__new__()} methods. +\end{classdesc*} + + +\begin{classdesc}{ParseResult}{scheme, netloc, path, params, query, fragment} + Concrete class for \function{urlparse()} results. The + \method{__new__()} method is overridden to support checking that the + right number of arguments are passed. +\end{classdesc} + + +\begin{classdesc}{SplitResult}{scheme, netloc, path, query, fragment} + Concrete class for \function{urlsplit()} results. The + \method{__new__()} method is overridden to support checking that the + right number of arguments are passed. +\end{classdesc} Added: sandbox/trunk/urilib/test_urllib2.py ============================================================================== --- (empty file) +++ sandbox/trunk/urilib/test_urllib2.py Sun Aug 5 23:42:33 2007 @@ -0,0 +1,1089 @@ +import unittest +from test import test_support + +import os, socket +import StringIO + +import urllib2 +from urllib2 import Request, OpenerDirector + +# XXX +# Request +# CacheFTPHandler (hard to write) +# parse_keqv_list, parse_http_list, HTTPDigestAuthHandler + +class TrivialTests(unittest.TestCase): + def test_trivial(self): + # A couple trivial tests + + self.assertRaises(ValueError, urllib2.urlopen, 'bogus url') + + # XXX Name hacking to get this to work on Windows. + fname = os.path.abspath(urllib2.__file__).replace('\\', '/') + if fname[1:2] == ":": + fname = fname[2:] + # And more hacking to get it to work on MacOS. This assumes + # urllib.pathname2url works, unfortunately... + if os.name == 'mac': + fname = '/' + fname.replace(':', '/') + elif os.name == 'riscos': + import string + fname = os.expand(fname) + fname = fname.translate(string.maketrans("/.", "./")) + + file_url = "file://%s" % fname + f = urllib2.urlopen(file_url) + + buf = f.read() + f.close() + + def test_parse_http_list(self): + tests = [('a,b,c', ['a', 'b', 'c']), + ('path"o,l"og"i"cal, example', ['path"o,l"og"i"cal', 'example']), + ('a, b, "c", "d", "e,f", g, h', ['a', 'b', '"c"', '"d"', '"e,f"', 'g', 'h']), + ('a="b\\"c", d="e\\,f", g="h\\\\i"', ['a="b"c"', 'd="e,f"', 'g="h\\i"'])] + for string, list in tests: + self.assertEquals(urllib2.parse_http_list(string), list) + + +def test_request_headers_dict(): + """ + The Request.headers dictionary is not a documented interface. It should + stay that way, because the complete set of headers are only accessible + through the .get_header(), .has_header(), .header_items() interface. + However, .headers pre-dates those methods, and so real code will be using + the dictionary. + + The introduction in 2.4 of those methods was a mistake for the same reason: + code that previously saw all (urllib2 user)-provided headers in .headers + now sees only a subset (and the function interface is ugly and incomplete). + A better change would have been to replace .headers dict with a dict + subclass (or UserDict.DictMixin instance?) that preserved the .headers + interface and also provided access to the "unredirected" headers. It's + probably too late to fix that, though. + + + Check .capitalize() case normalization: + + >>> url = "http://example.com" + >>> Request(url, headers={"Spam-eggs": "blah"}).headers["Spam-eggs"] + 'blah' + >>> Request(url, headers={"spam-EggS": "blah"}).headers["Spam-eggs"] + 'blah' + + Currently, Request(url, "Spam-eggs").headers["Spam-Eggs"] raises KeyError, + but that could be changed in future. + + """ + +def test_request_headers_methods(): + """ + Note the case normalization of header names here, to .capitalize()-case. + This should be preserved for backwards-compatibility. (In the HTTP case, + normalization to .title()-case is done by urllib2 before sending headers to + httplib). + + >>> url = "http://example.com" + >>> r = Request(url, headers={"Spam-eggs": "blah"}) + >>> r.has_header("Spam-eggs") + True + >>> r.header_items() + [('Spam-eggs', 'blah')] + >>> r.add_header("Foo-Bar", "baz") + >>> items = r.header_items() + >>> items.sort() + >>> items + [('Foo-bar', 'baz'), ('Spam-eggs', 'blah')] + + Note that e.g. r.has_header("spam-EggS") is currently False, and + r.get_header("spam-EggS") returns None, but that could be changed in + future. + + >>> r.has_header("Not-there") + False + >>> print r.get_header("Not-there") + None + >>> r.get_header("Not-there", "default") + 'default' + + """ + + +def test_password_manager(self): + """ + >>> mgr = urllib2.HTTPPasswordMgr() + >>> add = mgr.add_password + >>> add("Some Realm", "http://example.com/", "joe", "password") + >>> add("Some Realm", "http://example.com/ni", "ni", "ni") + >>> add("c", "http://example.com/foo", "foo", "ni") + >>> add("c", "http://example.com/bar", "bar", "nini") + >>> add("b", "http://example.com/", "first", "blah") + >>> add("b", "http://example.com/", "second", "spam") + >>> add("a", "http://example.com", "1", "a") + >>> add("Some Realm", "http://c.example.com:3128", "3", "c") + >>> add("Some Realm", "d.example.com", "4", "d") + >>> add("Some Realm", "e.example.com:3128", "5", "e") + + >>> mgr.find_user_password("Some Realm", "example.com") + ('joe', 'password') + >>> mgr.find_user_password("Some Realm", "http://example.com") + ('joe', 'password') + >>> mgr.find_user_password("Some Realm", "http://example.com/") + ('joe', 'password') + >>> mgr.find_user_password("Some Realm", "http://example.com/spam") + ('joe', 'password') + >>> mgr.find_user_password("Some Realm", "http://example.com/spam/spam") + ('joe', 'password') + >>> mgr.find_user_password("c", "http://example.com/foo") + ('foo', 'ni') + >>> mgr.find_user_password("c", "http://example.com/bar") + ('bar', 'nini') + + Actually, this is really undefined ATM +## Currently, we use the highest-level path where more than one match: + +## >>> mgr.find_user_password("Some Realm", "http://example.com/ni") +## ('joe', 'password') + + Use latest add_password() in case of conflict: + + >>> mgr.find_user_password("b", "http://example.com/") + ('second', 'spam') + + No special relationship between a.example.com and example.com: + + >>> mgr.find_user_password("a", "http://example.com/") + ('1', 'a') + >>> mgr.find_user_password("a", "http://a.example.com/") + (None, None) + + Ports: + + >>> mgr.find_user_password("Some Realm", "c.example.com") + (None, None) + >>> mgr.find_user_password("Some Realm", "c.example.com:3128") + ('3', 'c') + >>> mgr.find_user_password("Some Realm", "http://c.example.com:3128") + ('3', 'c') + >>> mgr.find_user_password("Some Realm", "d.example.com") + ('4', 'd') + >>> mgr.find_user_password("Some Realm", "e.example.com:3128") + ('5', 'e') + + """ + pass + + +def test_password_manager_default_port(self): + """ + >>> mgr = urllib2.HTTPPasswordMgr() + >>> add = mgr.add_password + + The point to note here is that we can't guess the default port if there's + no scheme. This applies to both add_password and find_user_password. + + >>> add("f", "http://g.example.com:80", "10", "j") + >>> add("g", "http://h.example.com", "11", "k") + >>> add("h", "i.example.com:80", "12", "l") + >>> add("i", "j.example.com", "13", "m") + >>> mgr.find_user_password("f", "g.example.com:100") + (None, None) + >>> mgr.find_user_password("f", "g.example.com:80") + ('10', 'j') + >>> mgr.find_user_password("f", "g.example.com") + (None, None) + >>> mgr.find_user_password("f", "http://g.example.com:100") + (None, None) + >>> mgr.find_user_password("f", "http://g.example.com:80") + ('10', 'j') + >>> mgr.find_user_password("f", "http://g.example.com") + ('10', 'j') + >>> mgr.find_user_password("g", "h.example.com") + ('11', 'k') + >>> mgr.find_user_password("g", "h.example.com:80") + ('11', 'k') + >>> mgr.find_user_password("g", "http://h.example.com:80") + ('11', 'k') + >>> mgr.find_user_password("h", "i.example.com") + (None, None) + >>> mgr.find_user_password("h", "i.example.com:80") + ('12', 'l') + >>> mgr.find_user_password("h", "http://i.example.com:80") + ('12', 'l') + >>> mgr.find_user_password("i", "j.example.com") + ('13', 'm') + >>> mgr.find_user_password("i", "j.example.com:80") + (None, None) + >>> mgr.find_user_password("i", "http://j.example.com") + ('13', 'm') + >>> mgr.find_user_password("i", "http://j.example.com:80") + (None, None) + + """ + +class MockOpener: + addheaders = [] + def open(self, req, data=None): + self.req, self.data = req, data + def error(self, proto, *args): + self.proto, self.args = proto, args + +class MockFile: + def read(self, count=None): pass + def readline(self, count=None): pass + def close(self): pass + +class MockHeaders(dict): + def getheaders(self, name): + return self.values() + +class MockResponse(StringIO.StringIO): + def __init__(self, code, msg, headers, data, url=None): + StringIO.StringIO.__init__(self, data) + self.code, self.msg, self.headers, self.url = code, msg, headers, url + def info(self): + return self.headers + def geturl(self): + return self.url + +class MockCookieJar: + def add_cookie_header(self, request): + self.ach_req = request + def extract_cookies(self, response, request): + self.ec_req, self.ec_r = request, response + +class FakeMethod: + def __init__(self, meth_name, action, handle): + self.meth_name = meth_name + self.handle = handle + self.action = action + def __call__(self, *args): + return self.handle(self.meth_name, self.action, *args) + +class MockHandler: + # useful for testing handler machinery + # see add_ordered_mock_handlers() docstring + handler_order = 500 + def __init__(self, methods): + self._define_methods(methods) + def _define_methods(self, methods): + for spec in methods: + if len(spec) == 2: name, action = spec + else: name, action = spec, None + meth = FakeMethod(name, action, self.handle) + setattr(self.__class__, name, meth) + def handle(self, fn_name, action, *args, **kwds): + self.parent.calls.append((self, fn_name, args, kwds)) + if action is None: + return None + elif action == "return self": + return self + elif action == "return response": + res = MockResponse(200, "OK", {}, "") + return res + elif action == "return request": + return Request("http://blah/") + elif action.startswith("error"): + code = action[action.rfind(" ")+1:] + try: + code = int(code) + except ValueError: + pass + res = MockResponse(200, "OK", {}, "") + return self.parent.error("http", args[0], res, code, "", {}) + elif action == "raise": + raise urllib2.URLError("blah") + assert False + def close(self): pass + def add_parent(self, parent): + self.parent = parent + self.parent.calls = [] + def __lt__(self, other): + if not hasattr(other, "handler_order"): + # No handler_order, leave in original order. Yuck. + return True + return self.handler_order < other.handler_order + +def add_ordered_mock_handlers(opener, meth_spec): + """Create MockHandlers and add them to an OpenerDirector. + + meth_spec: list of lists of tuples and strings defining methods to define + on handlers. eg: + + [["http_error", "ftp_open"], ["http_open"]] + + defines methods .http_error() and .ftp_open() on one handler, and + .http_open() on another. These methods just record their arguments and + return None. Using a tuple instead of a string causes the method to + perform some action (see MockHandler.handle()), eg: + + [["http_error"], [("http_open", "return request")]] + + defines .http_error() on one handler (which simply returns None), and + .http_open() on another handler, which returns a Request object. + + """ + handlers = [] + count = 0 + for meths in meth_spec: + class MockHandlerSubclass(MockHandler): pass + h = MockHandlerSubclass(meths) + h.handler_order += count + h.add_parent(opener) + count = count + 1 + handlers.append(h) + opener.add_handler(h) + return handlers + +def build_test_opener(*handler_instances): + opener = OpenerDirector() + for h in handler_instances: + opener.add_handler(h) + return opener + +class MockHTTPHandler(urllib2.BaseHandler): + # useful for testing redirections and auth + # sends supplied headers and code as first response + # sends 200 OK as second response + def __init__(self, code, headers): + self.code = code + self.headers = headers + self.reset() + def reset(self): + self._count = 0 + self.requests = [] + def http_open(self, req): + import mimetools, httplib, copy + from StringIO import StringIO + self.requests.append(copy.deepcopy(req)) + if self._count == 0: + self._count = self._count + 1 + name = httplib.responses[self.code] + msg = mimetools.Message(StringIO(self.headers)) + return self.parent.error( + "http", req, MockFile(), self.code, name, msg) + else: + self.req = req + msg = mimetools.Message(StringIO("\r\n\r\n")) + return MockResponse(200, "OK", msg, "", req.get_full_url()) + +class MockPasswordManager: + def add_password(self, realm, uri, user, password): + self.realm = realm + self.url = uri + self.user = user + self.password = password + def find_user_password(self, realm, authuri): + self.target_realm = realm + self.target_url = authuri + return self.user, self.password + + +class OpenerDirectorTests(unittest.TestCase): + + def test_add_non_handler(self): + class NonHandler(object): + pass + self.assertRaises(TypeError, + OpenerDirector().add_handler, NonHandler()) + + def test_badly_named_methods(self): + # test work-around for three methods that accidentally follow the + # naming conventions for handler methods + # (*_open() / *_request() / *_response()) + + # These used to call the accidentally-named methods, causing a + # TypeError in real code; here, returning self from these mock + # methods would either cause no exception, or AttributeError. + + from urllib2 import URLError + + o = OpenerDirector() + meth_spec = [ + [("do_open", "return self"), ("proxy_open", "return self")], + [("redirect_request", "return self")], + ] + handlers = add_ordered_mock_handlers(o, meth_spec) + o.add_handler(urllib2.UnknownHandler()) + for scheme in "do", "proxy", "redirect": + self.assertRaises(URLError, o.open, scheme+"://example.com/") + + def test_handled(self): + # handler returning non-None means no more handlers will be called + o = OpenerDirector() + meth_spec = [ + ["http_open", "ftp_open", "http_error_302"], + ["ftp_open"], + [("http_open", "return self")], + [("http_open", "return self")], + ] + handlers = add_ordered_mock_handlers(o, meth_spec) + + req = Request("http://example.com/") + r = o.open(req) + # Second .http_open() gets called, third doesn't, since second returned + # non-None. Handlers without .http_open() never get any methods called + # on them. + # In fact, second mock handler defining .http_open() returns self + # (instead of response), which becomes the OpenerDirector's return + # value. + self.assertEqual(r, handlers[2]) + calls = [(handlers[0], "http_open"), (handlers[2], "http_open")] + for expected, got in zip(calls, o.calls): + handler, name, args, kwds = got + self.assertEqual((handler, name), expected) + self.assertEqual(args, (req,)) + + def test_handler_order(self): + o = OpenerDirector() + handlers = [] + for meths, handler_order in [ + ([("http_open", "return self")], 500), + (["http_open"], 0), + ]: + class MockHandlerSubclass(MockHandler): pass + h = MockHandlerSubclass(meths) + h.handler_order = handler_order + handlers.append(h) + o.add_handler(h) + + r = o.open("http://example.com/") + # handlers called in reverse order, thanks to their sort order + self.assertEqual(o.calls[0][0], handlers[1]) + self.assertEqual(o.calls[1][0], handlers[0]) + + def test_raise(self): + # raising URLError stops processing of request + o = OpenerDirector() + meth_spec = [ + [("http_open", "raise")], + [("http_open", "return self")], + ] + handlers = add_ordered_mock_handlers(o, meth_spec) + + req = Request("http://example.com/") + self.assertRaises(urllib2.URLError, o.open, req) + self.assertEqual(o.calls, [(handlers[0], "http_open", (req,), {})]) + +## def test_error(self): +## # XXX this doesn't actually seem to be used in standard library, +## # but should really be tested anyway... + + def test_http_error(self): + # XXX http_error_default + # http errors are a special case + o = OpenerDirector() + meth_spec = [ + [("http_open", "error 302")], + [("http_error_400", "raise"), "http_open"], + [("http_error_302", "return response"), "http_error_303", + "http_error"], + [("http_error_302")], + ] + handlers = add_ordered_mock_handlers(o, meth_spec) + + class Unknown: + def __eq__(self, other): return True + + req = Request("http://example.com/") + r = o.open(req) + assert len(o.calls) == 2 + calls = [(handlers[0], "http_open", (req,)), + (handlers[2], "http_error_302", + (req, Unknown(), 302, "", {}))] + for expected, got in zip(calls, o.calls): + handler, method_name, args = expected + self.assertEqual((handler, method_name), got[:2]) + self.assertEqual(args, got[2]) + + def test_processors(self): + # *_request / *_response methods get called appropriately + o = OpenerDirector() + meth_spec = [ + [("http_request", "return request"), + ("http_response", "return response")], + [("http_request", "return request"), + ("http_response", "return response")], + ] + handlers = add_ordered_mock_handlers(o, meth_spec) + + req = Request("http://example.com/") + r = o.open(req) + # processor methods are called on *all* handlers that define them, + # not just the first handler that handles the request + calls = [ + (handlers[0], "http_request"), (handlers[1], "http_request"), + (handlers[0], "http_response"), (handlers[1], "http_response")] + + for i, (handler, name, args, kwds) in enumerate(o.calls): + if i < 2: + # *_request + self.assertEqual((handler, name), calls[i]) + self.assertEqual(len(args), 1) + self.assert_(isinstance(args[0], Request)) + else: + # *_response + self.assertEqual((handler, name), calls[i]) + self.assertEqual(len(args), 2) + self.assert_(isinstance(args[0], Request)) + # response from opener.open is None, because there's no + # handler that defines http_open to handle it + self.assert_(args[1] is None or + isinstance(args[1], MockResponse)) + + +def sanepathname2url(path): + import urllib + urlpath = urllib.pathname2url(path) + if os.name == "nt" and urlpath.startswith("///"): + urlpath = urlpath[2:] + # XXX don't ask me about the mac... + return urlpath + +class HandlerTests(unittest.TestCase): + + def test_ftp(self): + class MockFTPWrapper: + def __init__(self, data): self.data = data + def retrfile(self, filename, filetype): + self.filename, self.filetype = filename, filetype + return StringIO.StringIO(self.data), len(self.data) + + class NullFTPHandler(urllib2.FTPHandler): + def __init__(self, data): self.data = data + def connect_ftp(self, user, passwd, host, port, dirs, timeout=None): + self.user, self.passwd = user, passwd + self.host, self.port = host, port + self.dirs = dirs + self.ftpwrapper = MockFTPWrapper(self.data) + return self.ftpwrapper + + import ftplib, socket + data = "rheum rhaponicum" + h = NullFTPHandler(data) + o = h.parent = MockOpener() + + for url, host, port, type_, dirs, filename, mimetype in [ + ("ftp://localhost/foo/bar/baz.html", + "localhost", ftplib.FTP_PORT, "I", + ["foo", "bar"], "baz.html", "text/html"), + ("ftp://localhost:80/foo/bar/", + "localhost", 80, "D", + ["foo", "bar"], "", None), + ("ftp://localhost/baz.gif;type=a", + "localhost", ftplib.FTP_PORT, "A", + [], "baz.gif", None), # XXX really this should guess image/gif + ]: + req = Request(url) + req.timeout = None + r = h.ftp_open(req) + # ftp authentication not yet implemented by FTPHandler + self.assert_(h.user == h.passwd == "") + self.assertEqual(h.host, socket.gethostbyname(host)) + self.assertEqual(h.port, port) + self.assertEqual(h.dirs, dirs) + self.assertEqual(h.ftpwrapper.filename, filename) + self.assertEqual(h.ftpwrapper.filetype, type_) + headers = r.info() + self.assertEqual(headers.get("Content-type"), mimetype) + self.assertEqual(int(headers["Content-length"]), len(data)) + + def test_file(self): + import time, rfc822, socket + h = urllib2.FileHandler() + o = h.parent = MockOpener() + + TESTFN = test_support.TESTFN + urlpath = sanepathname2url(os.path.abspath(TESTFN)) + towrite = "hello, world\n" + urls = [ + "file://localhost%s" % urlpath, + "file://%s" % urlpath, + "file://%s%s" % (socket.gethostbyname('localhost'), urlpath), + ] + try: + localaddr = socket.gethostbyname(socket.gethostname()) + except socket.gaierror: + localaddr = '' + if localaddr: + urls.append("file://%s%s" % (localaddr, urlpath)) + + for url in urls: + f = open(TESTFN, "wb") + try: + try: + f.write(towrite) + finally: + f.close() + + r = h.file_open(Request(url)) + try: + data = r.read() + headers = r.info() + newurl = r.geturl() + finally: + r.close() + stats = os.stat(TESTFN) + modified = rfc822.formatdate(stats.st_mtime) + finally: + os.remove(TESTFN) + self.assertEqual(data, towrite) + self.assertEqual(headers["Content-type"], "text/plain") + self.assertEqual(headers["Content-length"], "13") + self.assertEqual(headers["Last-modified"], modified) + + for url in [ + "file://localhost:80%s" % urlpath, + "file:///file_does_not_exist.txt", + "file://%s:80%s/%s" % (socket.gethostbyname('localhost'), + os.getcwd(), TESTFN), + "file://somerandomhost.ontheinternet.com%s/%s" % + (os.getcwd(), TESTFN), + ]: + try: + f = open(TESTFN, "wb") + try: + f.write(towrite) + finally: + f.close() + + self.assertRaises(urllib2.URLError, + h.file_open, Request(url)) + finally: + os.remove(TESTFN) + + h = urllib2.FileHandler() + o = h.parent = MockOpener() + # XXXX why does // mean ftp (and /// mean not ftp!), and where + # is file: scheme specified? I think this is really a bug, and + # what was intended was to distinguish between URLs like: + # file:/blah.txt (a file) + # file://localhost/blah.txt (a file) + # file:///blah.txt (a file) + # file://ftp.example.com/blah.txt (an ftp URL) + for url, ftp in [ + ("file://ftp.example.com//foo.txt", True), + ("file://ftp.example.com///foo.txt", False), +# XXXX bug: fails with OSError, should be URLError + ("file://ftp.example.com/foo.txt", False), + ]: + req = Request(url) + try: + h.file_open(req) + # XXXX remove OSError when bug fixed + except (urllib2.URLError, OSError): + self.assert_(not ftp) + else: + self.assert_(o.req is req) + self.assertEqual(req.type, "ftp") + + def test_http(self): + class MockHTTPResponse: + def __init__(self, fp, msg, status, reason): + self.fp = fp + self.msg = msg + self.status = status + self.reason = reason + def read(self): + return '' + class MockHTTPClass: + def __init__(self): + self.req_headers = [] + self.data = None + self.raise_on_endheaders = False + def __call__(self, host, timeout=None): + self.host = host + self.timeout = timeout + return self + def set_debuglevel(self, level): + self.level = level + def request(self, method, url, body=None, headers={}): + self.method = method + self.selector = url + self.req_headers += headers.items() + self.req_headers.sort() + if body: + self.data = body + if self.raise_on_endheaders: + import socket + raise socket.error() + def getresponse(self): + return MockHTTPResponse(MockFile(), {}, 200, "OK") + + h = urllib2.AbstractHTTPHandler() + o = h.parent = MockOpener() + + url = "http://example.com/" + for method, data in [("GET", None), ("POST", "blah")]: + req = Request(url, data, {"Foo": "bar"}) + req.timeout = None + req.add_unredirected_header("Spam", "eggs") + http = MockHTTPClass() + r = h.do_open(http, req) + + # result attributes + r.read; r.readline # wrapped MockFile methods + r.info; r.geturl # addinfourl methods + r.code, r.msg == 200, "OK" # added from MockHTTPClass.getreply() + hdrs = r.info() + hdrs.get; hdrs.has_key # r.info() gives dict from .getreply() + self.assertEqual(r.geturl(), url) + + self.assertEqual(http.host, "example.com") + self.assertEqual(http.level, 0) + self.assertEqual(http.method, method) + self.assertEqual(http.selector, "/") + self.assertEqual(http.req_headers, + [("Connection", "close"), + ("Foo", "bar"), ("Spam", "eggs")]) + self.assertEqual(http.data, data) + + # check socket.error converted to URLError + http.raise_on_endheaders = True + self.assertRaises(urllib2.URLError, h.do_open, http, req) + + # check adding of standard headers + o.addheaders = [("Spam", "eggs")] + for data in "", None: # POST, GET + req = Request("http://example.com/", data) + r = MockResponse(200, "OK", {}, "") + newreq = h.do_request_(req) + if data is None: # GET + self.assert_("Content-length" not in req.unredirected_hdrs) + self.assert_("Content-type" not in req.unredirected_hdrs) + else: # POST + self.assertEqual(req.unredirected_hdrs["Content-length"], "0") + self.assertEqual(req.unredirected_hdrs["Content-type"], + "application/x-www-form-urlencoded") + # XXX the details of Host could be better tested + self.assertEqual(req.unredirected_hdrs["Host"], "example.com") + self.assertEqual(req.unredirected_hdrs["Spam"], "eggs") + + # don't clobber existing headers + req.add_unredirected_header("Content-length", "foo") + req.add_unredirected_header("Content-type", "bar") + req.add_unredirected_header("Host", "baz") + req.add_unredirected_header("Spam", "foo") + newreq = h.do_request_(req) + self.assertEqual(req.unredirected_hdrs["Content-length"], "foo") + self.assertEqual(req.unredirected_hdrs["Content-type"], "bar") + self.assertEqual(req.unredirected_hdrs["Host"], "baz") + self.assertEqual(req.unredirected_hdrs["Spam"], "foo") + + def test_errors(self): + h = urllib2.HTTPErrorProcessor() + o = h.parent = MockOpener() + + url = "http://example.com/" + req = Request(url) + # all 2xx are passed through + r = MockResponse(200, "OK", {}, "", url) + newr = h.http_response(req, r) + self.assert_(r is newr) + self.assert_(not hasattr(o, "proto")) # o.error not called + r = MockResponse(202, "Accepted", {}, "", url) + newr = h.http_response(req, r) + self.assert_(r is newr) + self.assert_(not hasattr(o, "proto")) # o.error not called + r = MockResponse(206, "Partial content", {}, "", url) + newr = h.http_response(req, r) + self.assert_(r is newr) + self.assert_(not hasattr(o, "proto")) # o.error not called + # anything else calls o.error (and MockOpener returns None, here) + r = MockResponse(502, "Bad gateway", {}, "", url) + self.assert_(h.http_response(req, r) is None) + self.assertEqual(o.proto, "http") # o.error called + self.assertEqual(o.args, (req, r, 502, "Bad gateway", {})) + + def test_cookies(self): + cj = MockCookieJar() + h = urllib2.HTTPCookieProcessor(cj) + o = h.parent = MockOpener() + + req = Request("http://example.com/") + r = MockResponse(200, "OK", {}, "") + newreq = h.http_request(req) + self.assert_(cj.ach_req is req is newreq) + self.assertEquals(req.get_origin_req_host(), "example.com") + self.assert_(not req.is_unverifiable()) + newr = h.http_response(req, r) + self.assert_(cj.ec_req is req) + self.assert_(cj.ec_r is r is newr) + + def test_redirect(self): + from_url = "http://example.com/a.html" + to_url = "http://example.com/b.html" + h = urllib2.HTTPRedirectHandler() + o = h.parent = MockOpener() + + # ordinary redirect behaviour + for code in 301, 302, 303, 307: + for data in None, "blah\nblah\n": + method = getattr(h, "http_error_%s" % code) + req = Request(from_url, data) + req.add_header("Nonsense", "viking=withhold") + req.add_unredirected_header("Spam", "spam") + try: + method(req, MockFile(), code, "Blah", + MockHeaders({"location": to_url})) + except urllib2.HTTPError: + # 307 in response to POST requires user OK + self.assert_(code == 307 and data is not None) + self.assertEqual(o.req.get_full_url(), to_url) + try: + self.assertEqual(o.req.get_method(), "GET") + except AttributeError: + self.assert_(not o.req.has_data()) + self.assertEqual(o.req.headers["Nonsense"], + "viking=withhold") + self.assert_("Spam" not in o.req.headers) + self.assert_("Spam" not in o.req.unredirected_hdrs) + + # loop detection + req = Request(from_url) + def redirect(h, req, url=to_url): + h.http_error_302(req, MockFile(), 302, "Blah", + MockHeaders({"location": url})) + # Note that the *original* request shares the same record of + # redirections with the sub-requests caused by the redirections. + + # detect infinite loop redirect of a URL to itself + req = Request(from_url, origin_req_host="example.com") + count = 0 + try: + while 1: + redirect(h, req, "http://example.com/") + count = count + 1 + except urllib2.HTTPError: + # don't stop until max_repeats, because cookies may introduce state + self.assertEqual(count, urllib2.HTTPRedirectHandler.max_repeats) + + # detect endless non-repeating chain of redirects + req = Request(from_url, origin_req_host="example.com") + count = 0 + try: + while 1: + redirect(h, req, "http://example.com/%d" % count) + count = count + 1 + except urllib2.HTTPError: + self.assertEqual(count, + urllib2.HTTPRedirectHandler.max_redirections) + # test cached redirection implemented for 301 redirection + def cached_redirect(h, req, url=to_url): + h.http_error_301(req, MockFile(), 301, "Blah", + MockHeaders({"location":url})) + req = Request(from_url, origin_req_host="example.com") + count = 0 + try: + while 1: + cached_redirect(h, req, "http://example.com/") + count = count + 1 + if count > 1: + # Check for presence of a cached dictionary. + # Content not checked as tests returns None. + # Independent redirection tests for 301 handled,however. + self.assert_(h.cache) + except urllib2.HTTPError: + self.assertEqual(count, urllib2.HTTPRedirectHandler.max_repeats) + + def test_cookie_redirect(self): + # cookies shouldn't leak into redirected requests + from cookielib import CookieJar + + from test.test_cookielib import interact_netscape + + cj = CookieJar() + interact_netscape(cj, "http://www.example.com/", "spam=eggs") + hh = MockHTTPHandler(302, "Location: http://www.cracker.com/\r\n\r\n") + hdeh = urllib2.HTTPDefaultErrorHandler() + hrh = urllib2.HTTPRedirectHandler() + cp = urllib2.HTTPCookieProcessor(cj) + o = build_test_opener(hh, hdeh, hrh, cp) + o.open("http://www.example.com/") + self.assert_(not hh.req.has_header("Cookie")) + + def test_proxy(self): + o = OpenerDirector() + ph = urllib2.ProxyHandler(dict(http="proxy.example.com:3128")) + o.add_handler(ph) + meth_spec = [ + [("http_open", "return response")] + ] + handlers = add_ordered_mock_handlers(o, meth_spec) + + req = Request("http://acme.example.com/") + self.assertEqual(req.get_host(), "acme.example.com") + r = o.open(req) + self.assertEqual(req.get_host(), "proxy.example.com:3128") + + self.assertEqual([(handlers[0], "http_open")], + [tup[0:2] for tup in o.calls]) + + def test_basic_auth(self): + opener = OpenerDirector() + password_manager = MockPasswordManager() + auth_handler = urllib2.HTTPBasicAuthHandler(password_manager) + realm = "ACME Widget Store" + http_handler = MockHTTPHandler( + 401, 'WWW-Authenticate: Basic realm="%s"\r\n\r\n' % realm) + opener.add_handler(auth_handler) + opener.add_handler(http_handler) + self._test_basic_auth(opener, auth_handler, "Authorization", + realm, http_handler, password_manager, + "http://acme.example.com/protected", + "http://acme.example.com/protected", + ) + + def test_proxy_basic_auth(self): + opener = OpenerDirector() + ph = urllib2.ProxyHandler(dict(http="proxy.example.com:3128")) + opener.add_handler(ph) + password_manager = MockPasswordManager() + auth_handler = urllib2.ProxyBasicAuthHandler(password_manager) + realm = "ACME Networks" + http_handler = MockHTTPHandler( + 407, 'Proxy-Authenticate: Basic realm="%s"\r\n\r\n' % realm) + opener.add_handler(auth_handler) + opener.add_handler(http_handler) + self._test_basic_auth(opener, auth_handler, "Proxy-authorization", + realm, http_handler, password_manager, + "http://acme.example.com:3128/protected", + "proxy.example.com:3128", + ) + + def test_basic_and_digest_auth_handlers(self): + # HTTPDigestAuthHandler threw an exception if it couldn't handle a 40* + # response (http://python.org/sf/1479302), where it should instead + # return None to allow another handler (especially + # HTTPBasicAuthHandler) to handle the response. + + # Also (http://python.org/sf/14797027, RFC 2617 section 1.2), we must + # try digest first (since it's the strongest auth scheme), so we record + # order of calls here to check digest comes first: + class RecordingOpenerDirector(OpenerDirector): + def __init__(self): + OpenerDirector.__init__(self) + self.recorded = [] + def record(self, info): + self.recorded.append(info) + class TestDigestAuthHandler(urllib2.HTTPDigestAuthHandler): + def http_error_401(self, *args, **kwds): + self.parent.record("digest") + urllib2.HTTPDigestAuthHandler.http_error_401(self, + *args, **kwds) + class TestBasicAuthHandler(urllib2.HTTPBasicAuthHandler): + def http_error_401(self, *args, **kwds): + self.parent.record("basic") + urllib2.HTTPBasicAuthHandler.http_error_401(self, + *args, **kwds) + + opener = RecordingOpenerDirector() + password_manager = MockPasswordManager() + digest_handler = TestDigestAuthHandler(password_manager) + basic_handler = TestBasicAuthHandler(password_manager) + realm = "ACME Networks" + http_handler = MockHTTPHandler( + 401, 'WWW-Authenticate: Basic realm="%s"\r\n\r\n' % realm) + opener.add_handler(basic_handler) + opener.add_handler(digest_handler) + opener.add_handler(http_handler) + + # check basic auth isn't blocked by digest handler failing + self._test_basic_auth(opener, basic_handler, "Authorization", + realm, http_handler, password_manager, + "http://acme.example.com/protected", + "http://acme.example.com/protected", + ) + # check digest was tried before basic (twice, because + # _test_basic_auth called .open() twice) + self.assertEqual(opener.recorded, ["digest", "basic"]*2) + + def _test_basic_auth(self, opener, auth_handler, auth_header, + realm, http_handler, password_manager, + request_url, protected_url): + import base64, httplib + user, password = "wile", "coyote" + + # .add_password() fed through to password manager + auth_handler.add_password(realm, request_url, user, password) + self.assertEqual(realm, password_manager.realm) + self.assertEqual(request_url, password_manager.url) + self.assertEqual(user, password_manager.user) + self.assertEqual(password, password_manager.password) + + r = opener.open(request_url) + + # should have asked the password manager for the username/password + self.assertEqual(password_manager.target_realm, realm) + self.assertEqual(password_manager.target_url, protected_url) + + # expect one request without authorization, then one with + self.assertEqual(len(http_handler.requests), 2) + self.assertFalse(http_handler.requests[0].has_header(auth_header)) + userpass = '%s:%s' % (user, password) + auth_hdr_value = 'Basic '+base64.encodestring(userpass).strip() + self.assertEqual(http_handler.requests[1].get_header(auth_header), + auth_hdr_value) + + # if the password manager can't find a password, the handler won't + # handle the HTTP auth error + password_manager.user = password_manager.password = None + http_handler.reset() + r = opener.open(request_url) + self.assertEqual(len(http_handler.requests), 1) + self.assertFalse(http_handler.requests[0].has_header(auth_header)) + + +class MiscTests(unittest.TestCase): + + def test_build_opener(self): + class MyHTTPHandler(urllib2.HTTPHandler): pass + class FooHandler(urllib2.BaseHandler): + def foo_open(self): pass + class BarHandler(urllib2.BaseHandler): + def bar_open(self): pass + + build_opener = urllib2.build_opener + + o = build_opener(FooHandler, BarHandler) + self.opener_has_handler(o, FooHandler) + self.opener_has_handler(o, BarHandler) + + # can take a mix of classes and instances + o = build_opener(FooHandler, BarHandler()) + self.opener_has_handler(o, FooHandler) + self.opener_has_handler(o, BarHandler) + + # subclasses of default handlers override default handlers + o = build_opener(MyHTTPHandler) + self.opener_has_handler(o, MyHTTPHandler) + + # a particular case of overriding: default handlers can be passed + # in explicitly + o = build_opener() + self.opener_has_handler(o, urllib2.HTTPHandler) + o = build_opener(urllib2.HTTPHandler) + self.opener_has_handler(o, urllib2.HTTPHandler) + o = build_opener(urllib2.HTTPHandler()) + self.opener_has_handler(o, urllib2.HTTPHandler) + + def opener_has_handler(self, opener, handler_class): + for h in opener.handlers: + if h.__class__ == handler_class: + break + else: + self.assert_(False) + + +def test_main(verbose=None): + from test import test_urllib2 + test_support.run_doctest(test_urllib2, verbose) + test_support.run_doctest(urllib2, verbose) + tests = (TrivialTests, + OpenerDirectorTests, + HandlerTests, + MiscTests) + test_support.run_unittest(*tests) + +if __name__ == "__main__": + test_main(verbose=True) Added: sandbox/trunk/urilib/urllib2.py ============================================================================== --- (empty file) +++ sandbox/trunk/urilib/urllib2.py Sun Aug 5 23:42:33 2007 @@ -0,0 +1,1371 @@ +"""An extensible library for opening URLs using a variety of protocols + +The simplest way to use this module is to call the urlopen function, +which accepts a string containing a URL or a Request object (described +below). It opens the URL and returns the results as file-like +object; the returned object has some extra methods described below. + +The OpenerDirector manages a collection of Handler objects that do +all the actual work. Each Handler implements a particular protocol or +option. The OpenerDirector is a composite object that invokes the +Handlers needed to open the requested URL. For example, the +HTTPHandler performs HTTP GET and POST requests and deals with +non-error returns. The HTTPRedirectHandler automatically deals with +HTTP 301, 302, 303 and 307 redirect errors, and the HTTPDigestAuthHandler +deals with digest authentication. + +urlopen(url, data=None) -- Basic usage is the same as original +urllib. pass the url and optionally data to post to an HTTP URL, and +get a file-like object back. One difference is that you can also pass +a Request instance instead of URL. Raises a URLError (subclass of +IOError); for HTTP errors, raises an HTTPError, which can also be +treated as a valid response. + +build_opener -- Function that creates a new OpenerDirector instance. +Will install the default handlers. Accepts one or more Handlers as +arguments, either instances or Handler classes that it will +instantiate. If one of the argument is a subclass of the default +handler, the argument will be installed instead of the default. + +install_opener -- Installs a new opener as the default opener. + +objects of interest: +OpenerDirector -- + +Request -- An object that encapsulates the state of a request. The +state can be as simple as the URL. It can also include extra HTTP +headers, e.g. a User-Agent. + +BaseHandler -- + +exceptions: +URLError -- A subclass of IOError, individual protocols have their own +specific subclass. + +HTTPError -- Also a valid HTTP response, so you can treat an HTTP error +as an exceptional event or valid response. + +internals: +BaseHandler and parent +_call_chain conventions + +Example usage: + +import urllib2 + +# set up authentication info +authinfo = urllib2.HTTPBasicAuthHandler() +authinfo.add_password(realm='PDQ Application', + uri='https://mahler:8092/site-updates.py', + user='klem', + passwd='geheim$parole') + +proxy_support = urllib2.ProxyHandler({"http" : "http://ahad-haam:3128"}) + +# build a new opener that adds authentication and caching FTP handlers +opener = urllib2.build_opener(proxy_support, authinfo, urllib2.CacheFTPHandler) + +# install it +urllib2.install_opener(opener) + +f = urllib2.urlopen('http://www.python.org/') + + +""" + +# XXX issues: +# If an authentication error handler that tries to perform +# authentication for some reason but fails, how should the error be +# signalled? The client needs to know the HTTP error code. But if +# the handler knows that the problem was, e.g., that it didn't know +# that hash algo that requested in the challenge, it would be good to +# pass that information along to the client, too. +# ftp errors aren't handled cleanly +# check digest against correct (i.e. non-apache) implementation + +# Possible extensions: +# complex proxies XXX not sure what exactly was meant by this +# abstract factory for opener + +import base64 +import hashlib +import httplib +import mimetools +import os +import posixpath +import random +import re +import socket +import sys +import time +import urlparse +import bisect + +try: + from cStringIO import StringIO +except ImportError: + from StringIO import StringIO + +from urllib import (unwrap, unquote, splittype, splithost, quote, + addinfourl, splitport, splitquery, + splitattr, ftpwrapper, noheaders, splituser, splitpasswd, splitvalue) + +# support for FileHandler, proxies via environment variables +from urllib import localhost, url2pathname, getproxies + +# used in User-Agent header sent +__version__ = sys.version[:3] + +_opener = None +def urlopen(url, data=None, timeout=None): + global _opener + if _opener is None: + _opener = build_opener() + return _opener.open(url, data, timeout) + +def install_opener(opener): + global _opener + _opener = opener + +# do these error classes make sense? +# make sure all of the IOError stuff is overridden. we just want to be +# subtypes. + +class URLError(IOError): + # URLError is a sub-type of IOError, but it doesn't share any of + # the implementation. need to override __init__ and __str__. + # It sets self.args for compatibility with other EnvironmentError + # subclasses, but args doesn't have the typical format with errno in + # slot 0 and strerror in slot 1. This may be better than nothing. + def __init__(self, reason): + self.args = reason, + self.reason = reason + + def __str__(self): + return '' % self.reason + +class HTTPError(URLError, addinfourl): + """Raised when HTTP error occurs, but also acts like non-error return""" + __super_init = addinfourl.__init__ + + def __init__(self, url, code, msg, hdrs, fp): + self.code = code + self.msg = msg + self.hdrs = hdrs + self.fp = fp + self.filename = url + # The addinfourl classes depend on fp being a valid file + # object. In some cases, the HTTPError may not have a valid + # file object. If this happens, the simplest workaround is to + # not initialize the base classes. + if fp is not None: + self.__super_init(fp, hdrs, url) + + def __str__(self): + return 'HTTP Error %s: %s' % (self.code, self.msg) + +# copied from cookielib.py +_cut_port_re = re.compile(r":\d+$") +def request_host(request): + """Return request-host, as defined by RFC 2965. + + Variation from RFC: returned value is lowercased, for convenient + comparison. + + """ + url = request.get_full_url() + host = urlparse.urlparse(url)[1] + if host == "": + host = request.get_header("Host", "") + + # remove port, if present + host = _cut_port_re.sub("", host, 1) + return host.lower() + +class Request: + + def __init__(self, url, data=None, headers={}, + origin_req_host=None, unverifiable=False): + # unwrap('') --> 'type://host/path' + self.__original = unwrap(url) + self.type = None + # self.__r_type is what's left after doing the splittype + self.host = None + self.port = None + self.data = data + self.headers = {} + for key, value in headers.items(): + self.add_header(key, value) + self.unredirected_hdrs = {} + if origin_req_host is None: + origin_req_host = request_host(self) + self.origin_req_host = origin_req_host + self.unverifiable = unverifiable + + def __getattr__(self, attr): + # XXX this is a fallback mechanism to guard against these + # methods getting called in a non-standard order. this may be + # too complicated and/or unnecessary. + # XXX should the __r_XXX attributes be public? + if attr[:12] == '_Request__r_': + name = attr[12:] + if hasattr(Request, 'get_' + name): + getattr(self, 'get_' + name)() + return getattr(self, attr) + raise AttributeError, attr + + def get_method(self): + if self.has_data(): + return "POST" + else: + return "GET" + + # XXX these helper methods are lame + + def add_data(self, data): + self.data = data + + def has_data(self): + return self.data is not None + + def get_data(self): + return self.data + + def get_full_url(self): + return self.__original + + def get_type(self): + if self.type is None: + self.type, self.__r_type = splittype(self.__original) + if self.type is None: + raise ValueError, "unknown url type: %s" % self.__original + return self.type + + def get_host(self): + if self.host is None: + self.host, self.__r_host = splithost(self.__r_type) + if self.host: + self.host = unquote(self.host) + return self.host + + def get_selector(self): + return self.__r_host + + def set_proxy(self, host, type): + self.host, self.type = host, type + self.__r_host = self.__original + + def get_origin_req_host(self): + return self.origin_req_host + + def is_unverifiable(self): + return self.unverifiable + + def add_header(self, key, val): + # useful for something like authentication + self.headers[key.capitalize()] = val + + def add_unredirected_header(self, key, val): + # will not be added to a redirected request + self.unredirected_hdrs[key.capitalize()] = val + + def has_header(self, header_name): + return (header_name in self.headers or + header_name in self.unredirected_hdrs) + + def get_header(self, header_name, default=None): + return self.headers.get( + header_name, + self.unredirected_hdrs.get(header_name, default)) + + def header_items(self): + hdrs = self.unredirected_hdrs.copy() + hdrs.update(self.headers) + return hdrs.items() + +class OpenerDirector: + def __init__(self): + client_version = "Python-urllib/%s" % __version__ + self.addheaders = [('User-agent', client_version)] + # manage the individual handlers + self.handlers = [] + self.handle_open = {} + self.handle_error = {} + self.process_response = {} + self.process_request = {} + + def add_handler(self, handler): + if not hasattr(handler, "add_parent"): + raise TypeError("expected BaseHandler instance, got %r" % + type(handler)) + + added = False + for meth in dir(handler): + if meth in ["redirect_request", "do_open", "proxy_open"]: + # oops, coincidental match + continue + + i = meth.find("_") + protocol = meth[:i] + condition = meth[i+1:] + + if condition.startswith("error"): + j = condition.find("_") + i + 1 + kind = meth[j+1:] + try: + kind = int(kind) + except ValueError: + pass + lookup = self.handle_error.get(protocol, {}) + self.handle_error[protocol] = lookup + elif condition == "open": + kind = protocol + lookup = self.handle_open + elif condition == "response": + kind = protocol + lookup = self.process_response + elif condition == "request": + kind = protocol + lookup = self.process_request + else: + continue + + handlers = lookup.setdefault(kind, []) + if handlers: + bisect.insort(handlers, handler) + else: + handlers.append(handler) + added = True + + if added: + # the handlers must work in an specific order, the order + # is specified in a Handler attribute + bisect.insort(self.handlers, handler) + handler.add_parent(self) + + def close(self): + # Only exists for backwards compatibility. + pass + + def _call_chain(self, chain, kind, meth_name, *args): + # Handlers raise an exception if no one else should try to handle + # the request, or return None if they can't but another handler + # could. Otherwise, they return the response. + handlers = chain.get(kind, ()) + for handler in handlers: + func = getattr(handler, meth_name) + + result = func(*args) + if result is not None: + return result + + def open(self, fullurl, data=None, timeout=None): + # accept a URL or a Request object + if isinstance(fullurl, basestring): + req = Request(fullurl, data) + else: + req = fullurl + if data is not None: + req.add_data(data) + + req.timeout = timeout + protocol = req.get_type() + + # pre-process request + meth_name = protocol+"_request" + for processor in self.process_request.get(protocol, []): + meth = getattr(processor, meth_name) + req = meth(req) + + response = self._open(req, data) + + # post-process response + meth_name = protocol+"_response" + for processor in self.process_response.get(protocol, []): + meth = getattr(processor, meth_name) + response = meth(req, response) + + return response + + def _open(self, req, data=None): + result = self._call_chain(self.handle_open, 'default', + 'default_open', req) + if result: + return result + + protocol = req.get_type() + result = self._call_chain(self.handle_open, protocol, protocol + + '_open', req) + if result: + return result + + return self._call_chain(self.handle_open, 'unknown', + 'unknown_open', req) + + def error(self, proto, *args): + if proto in ('http', 'https'): + # XXX http[s] protocols are special-cased + dict = self.handle_error['http'] # https is not different than http + proto = args[2] # YUCK! + meth_name = 'http_error_%s' % proto + http_err = 1 + orig_args = args + else: + dict = self.handle_error + meth_name = proto + '_error' + http_err = 0 + args = (dict, proto, meth_name) + args + result = self._call_chain(*args) + if result: + return result + + if http_err: + args = (dict, 'default', 'http_error_default') + orig_args + return self._call_chain(*args) + +# XXX probably also want an abstract factory that knows when it makes +# sense to skip a superclass in favor of a subclass and when it might +# make sense to include both + +def build_opener(*handlers): + """Create an opener object from a list of handlers. + + The opener will use several default handlers, including support + for HTTP and FTP. + + If any of the handlers passed as arguments are subclasses of the + default handlers, the default handlers will not be used. + """ + import types + def isclass(obj): + return isinstance(obj, types.ClassType) or hasattr(obj, "__bases__") + + opener = OpenerDirector() + default_classes = [ProxyHandler, UnknownHandler, HTTPHandler, + HTTPDefaultErrorHandler, HTTPRedirectHandler, + FTPHandler, FileHandler, HTTPErrorProcessor] + if hasattr(httplib, 'HTTPS'): + default_classes.append(HTTPSHandler) + skip = [] + for klass in default_classes: + for check in handlers: + if isclass(check): + if issubclass(check, klass): + skip.append(klass) + elif isinstance(check, klass): + skip.append(klass) + for klass in skip: + default_classes.remove(klass) + + for klass in default_classes: + opener.add_handler(klass()) + + for h in handlers: + if isclass(h): + h = h() + opener.add_handler(h) + return opener + +class BaseHandler: + handler_order = 500 + + def add_parent(self, parent): + self.parent = parent + + def close(self): + # Only exists for backwards compatibility + pass + + def __lt__(self, other): + if not hasattr(other, "handler_order"): + # Try to preserve the old behavior of having custom classes + # inserted after default ones (works only for custom user + # classes which are not aware of handler_order). + return True + return self.handler_order < other.handler_order + + +class HTTPErrorProcessor(BaseHandler): + """Process HTTP error responses.""" + handler_order = 1000 # after all other processing + + def http_response(self, request, response): + code, msg, hdrs = response.code, response.msg, response.info() + + # According to RFC 2616, "2xx" code indicates that the client's + # request was successfully received, understood, and accepted. + if not (200 <= code < 300): + response = self.parent.error( + 'http', request, response, code, msg, hdrs) + + return response + + https_response = http_response + +class HTTPDefaultErrorHandler(BaseHandler): + def http_error_default(self, req, fp, code, msg, hdrs): + raise HTTPError(req.get_full_url(), code, msg, hdrs, fp) + +class HTTPRedirectHandler(BaseHandler): + # maximum number of redirections to any single URL + # this is needed because of the state that cookies introduce + max_repeats = 4 + # maximum total number of redirections (regardless of URL) before + # assuming we're in a loop + max_redirections = 10 + + def __init__(self): + self.cache = {} + + def redirect_request(self, req, fp, code, msg, headers, newurl): + """Return a Request or None in response to a redirect. + + This is called by the http_error_30x methods when a + redirection response is received. If a redirection should + take place, return a new Request to allow http_error_30x to + perform the redirect. Otherwise, raise HTTPError if no-one + else should try to handle this url. Return None if you can't + but another Handler might. + """ + m = req.get_method() + if (code in (301, 302, 303, 307) and m in ("GET", "HEAD") + or code in (301, 302, 303) and m == "POST"): + # Strictly (according to RFC 2616), 301 or 302 in response + # to a POST MUST NOT cause a redirection without confirmation + # from the user (of urllib2, in this case). In practice, + # essentially all clients do redirect in this case, so we + # do the same. + # be conciliant with URIs containing a space + newurl = newurl.replace(' ', '%20') + return Request(newurl, + headers=req.headers, + origin_req_host=req.get_origin_req_host(), + unverifiable=True) + else: + raise HTTPError(req.get_full_url(), code, msg, headers, fp) + + # Implementation note: To avoid the server sending us into an + # infinite loop, the request object needs to track what URLs we + # have already seen. Do this by adding a handler-specific + # attribute to the Request object. + + def http_error_301(self, req, fp, code, msg, headers): + if req in self.cache: + if 'location' in headers: + newurl = headers.getheaders('location')[0] + elif 'uri' in headers: + newurl = headers.getheaders('uri')[0] + else: + return + if hasattr(req, 'redirect_dict'): + visited = req.redirect_dict + if (visited.get(newurl, 0) > (self.max_repeats -1 ) or + len(visited) >= (self.max_redirections - 1)): + raise HTTPError(req.get_full_url(), code, self.inf_msg + + msg, headers, fp) + else: + visited = req.redirect_dict = {} + visited[newurl] = visited.get(newurl, 0) + 1 + return self.cache[req] + self.cache[req] = self.http_error_302(req, fp, code, msg, headers) + return self.cache[req] + + def http_error_302(self, req, fp, code, msg, headers): + # Some servers (incorrectly) return multiple Location headers + # (so probably same goes for URI). Use first header. + if 'location' in headers: + newurl = headers.getheaders('location')[0] + elif 'uri' in headers: + newurl = headers.getheaders('uri')[0] + else: + return + newurl = urlparse.urljoin(req.get_full_url(), newurl) + + # XXX Probably want to forget about the state of the current + # request, although that might interact poorly with other + # handlers that also use handler-specific request attributes + new = self.redirect_request(req, fp, code, msg, headers, newurl) + if new is None: + return + + # loop detection + # .redirect_dict has a key url if url was previously visited. + if hasattr(req, 'redirect_dict'): + visited = new.redirect_dict = req.redirect_dict + if (visited.get(newurl, 0) >= self.max_repeats or + len(visited) >= self.max_redirections): + raise HTTPError(req.get_full_url(), code, + self.inf_msg + msg, headers, fp) + else: + visited = new.redirect_dict = req.redirect_dict = {} + visited[newurl] = visited.get(newurl, 0) + 1 + + # Don't close the fp until we are sure that we won't use it + # with HTTPError. + fp.read() + fp.close() + + return self.parent.open(new) + + http_error_303 = http_error_307 = http_error_302 + + inf_msg = "The HTTP server returned a redirect error that would " \ + "lead to an infinite loop.\n" \ + "The last 30x error message was:\n" + + +def _parse_proxy(proxy): + """Return (scheme, user, password, host/port) given a URL or an authority. + + If a URL is supplied, it must have an authority (host:port) component. + According to RFC 3986, having an authority component means the URL must + have two slashes after the scheme: + + >>> _parse_proxy('file:/ftp.example.com/') + Traceback (most recent call last): + ValueError: proxy URL with no authority: 'file:/ftp.example.com/' + + The first three items of the returned tuple may be None. + + Examples of authority parsing: + + >>> _parse_proxy('proxy.example.com') + (None, None, None, 'proxy.example.com') + >>> _parse_proxy('proxy.example.com:3128') + (None, None, None, 'proxy.example.com:3128') + + The authority component may optionally include userinfo (assumed to be + username:password): + + >>> _parse_proxy('joe:password at proxy.example.com') + (None, 'joe', 'password', 'proxy.example.com') + >>> _parse_proxy('joe:password at proxy.example.com:3128') + (None, 'joe', 'password', 'proxy.example.com:3128') + + Same examples, but with URLs instead: + + >>> _parse_proxy('http://proxy.example.com/') + ('http', None, None, 'proxy.example.com') + >>> _parse_proxy('http://proxy.example.com:3128/') + ('http', None, None, 'proxy.example.com:3128') + >>> _parse_proxy('http://joe:password at proxy.example.com/') + ('http', 'joe', 'password', 'proxy.example.com') + >>> _parse_proxy('http://joe:password at proxy.example.com:3128') + ('http', 'joe', 'password', 'proxy.example.com:3128') + + Everything after the authority is ignored: + + >>> _parse_proxy('ftp://joe:password at proxy.example.com/rubbish:3128') + ('ftp', 'joe', 'password', 'proxy.example.com') + + Test for no trailing '/' case: + + >>> _parse_proxy('http://joe:password at proxy.example.com') + ('http', 'joe', 'password', 'proxy.example.com') + + """ + scheme, r_scheme = splittype(proxy) + if not r_scheme.startswith("/"): + # authority + scheme = None + authority = proxy + else: + # URL + if not r_scheme.startswith("//"): + raise ValueError("proxy URL with no authority: %r" % proxy) + # We have an authority, so for RFC 3986-compliant URLs (by ss 3. + # and 3.3.), path is empty or starts with '/' + end = r_scheme.find("/", 2) + if end == -1: + end = None + authority = r_scheme[2:end] + userinfo, hostport = splituser(authority) + if userinfo is not None: + user, password = splitpasswd(userinfo) + else: + user = password = None + return scheme, user, password, hostport + +class ProxyHandler(BaseHandler): + # Proxies must be in front + handler_order = 100 + + def __init__(self, proxies=None): + if proxies is None: + proxies = getproxies() + assert hasattr(proxies, 'has_key'), "proxies must be a mapping" + self.proxies = proxies + for type, url in proxies.items(): + setattr(self, '%s_open' % type, + lambda r, proxy=url, type=type, meth=self.proxy_open: \ + meth(r, proxy, type)) + + def proxy_open(self, req, proxy, type): + orig_type = req.get_type() + proxy_type, user, password, hostport = _parse_proxy(proxy) + if proxy_type is None: + proxy_type = orig_type + if user and password: + user_pass = '%s:%s' % (unquote(user), unquote(password)) + creds = base64.b64encode(user_pass).strip() + req.add_header('Proxy-authorization', 'Basic ' + creds) + hostport = unquote(hostport) + req.set_proxy(hostport, proxy_type) + if orig_type == proxy_type: + # let other handlers take care of it + return None + else: + # need to start over, because the other handlers don't + # grok the proxy's URL type + # e.g. if we have a constructor arg proxies like so: + # {'http': 'ftp://proxy.example.com'}, we may end up turning + # a request for http://acme.example.com/a into one for + # ftp://proxy.example.com/a + return self.parent.open(req) + +class HTTPPasswordMgr: + + def __init__(self): + self.passwd = {} + + def add_password(self, realm, uri, user, passwd): + # uri could be a single URI or a sequence + if isinstance(uri, basestring): + uri = [uri] + if not realm in self.passwd: + self.passwd[realm] = {} + for default_port in True, False: + reduced_uri = tuple( + [self.reduce_uri(u, default_port) for u in uri]) + self.passwd[realm][reduced_uri] = (user, passwd) + + def find_user_password(self, realm, authuri): + domains = self.passwd.get(realm, {}) + for default_port in True, False: + reduced_authuri = self.reduce_uri(authuri, default_port) + for uris, authinfo in domains.iteritems(): + for uri in uris: + if self.is_suburi(uri, reduced_authuri): + return authinfo + return None, None + + def reduce_uri(self, uri, default_port=True): + """Accept authority or URI and extract only the authority and path.""" + # note HTTP URLs do not have a userinfo component + parts = urlparse.urlsplit(uri) + if parts[1]: + # URI + scheme = parts[0] + authority = parts[1] + path = parts[2] or '/' + else: + # host or host:port + scheme = None + authority = uri + path = '/' + host, port = splitport(authority) + if default_port and port is None and scheme is not None: + dport = {"http": 80, + "https": 443, + }.get(scheme) + if dport is not None: + authority = "%s:%d" % (host, dport) + return authority, path + + def is_suburi(self, base, test): + """Check if test is below base in a URI tree + + Both args must be URIs in reduced form. + """ + if base == test: + return True + if base[0] != test[0]: + return False + common = posixpath.commonprefix((base[1], test[1])) + if len(common) == len(base[1]): + return True + return False + + +class HTTPPasswordMgrWithDefaultRealm(HTTPPasswordMgr): + + def find_user_password(self, realm, authuri): + user, password = HTTPPasswordMgr.find_user_password(self, realm, + authuri) + if user is not None: + return user, password + return HTTPPasswordMgr.find_user_password(self, None, authuri) + + +class AbstractBasicAuthHandler: + + # XXX this allows for multiple auth-schemes, but will stupidly pick + # the last one with a realm specified. + + rx = re.compile('(?:.*,)*[ \t]*([^ \t]+)[ \t]+realm="([^"]*)"', re.I) + + # XXX could pre-emptively send auth info already accepted (RFC 2617, + # end of section 2, and section 1.2 immediately after "credentials" + # production). + + def __init__(self, password_mgr=None): + if password_mgr is None: + password_mgr = HTTPPasswordMgr() + self.passwd = password_mgr + self.add_password = self.passwd.add_password + + def http_error_auth_reqed(self, authreq, host, req, headers): + # host may be an authority (without userinfo) or a URL with an + # authority + # XXX could be multiple headers + authreq = headers.get(authreq, None) + if authreq: + mo = AbstractBasicAuthHandler.rx.search(authreq) + if mo: + scheme, realm = mo.groups() + if scheme.lower() == 'basic': + return self.retry_http_basic_auth(host, req, realm) + + def retry_http_basic_auth(self, host, req, realm): + user, pw = self.passwd.find_user_password(realm, host) + if pw is not None: + raw = "%s:%s" % (user, pw) + auth = 'Basic %s' % base64.b64encode(raw).strip() + if req.headers.get(self.auth_header, None) == auth: + return None + req.add_header(self.auth_header, auth) + return self.parent.open(req) + else: + return None + + +class HTTPBasicAuthHandler(AbstractBasicAuthHandler, BaseHandler): + + auth_header = 'Authorization' + + def http_error_401(self, req, fp, code, msg, headers): + url = req.get_full_url() + return self.http_error_auth_reqed('www-authenticate', + url, req, headers) + + +class ProxyBasicAuthHandler(AbstractBasicAuthHandler, BaseHandler): + + auth_header = 'Proxy-authorization' + + def http_error_407(self, req, fp, code, msg, headers): + # http_error_auth_reqed requires that there is no userinfo component in + # authority. Assume there isn't one, since urllib2 does not (and + # should not, RFC 3986 s. 3.2.1) support requests for URLs containing + # userinfo. + authority = req.get_host() + return self.http_error_auth_reqed('proxy-authenticate', + authority, req, headers) + + +def randombytes(n): + """Return n random bytes.""" + # Use /dev/urandom if it is available. Fall back to random module + # if not. It might be worthwhile to extend this function to use + # other platform-specific mechanisms for getting random bytes. + if os.path.exists("/dev/urandom"): + f = open("/dev/urandom") + s = f.read(n) + f.close() + return s + else: + L = [chr(random.randrange(0, 256)) for i in range(n)] + return "".join(L) + +class AbstractDigestAuthHandler: + # Digest authentication is specified in RFC 2617. + + # XXX The client does not inspect the Authentication-Info header + # in a successful response. + + # XXX It should be possible to test this implementation against + # a mock server that just generates a static set of challenges. + + # XXX qop="auth-int" supports is shaky + + def __init__(self, passwd=None): + if passwd is None: + passwd = HTTPPasswordMgr() + self.passwd = passwd + self.add_password = self.passwd.add_password + self.retried = 0 + self.nonce_count = 0 + + def reset_retry_count(self): + self.retried = 0 + + def http_error_auth_reqed(self, auth_header, host, req, headers): + authreq = headers.get(auth_header, None) + if self.retried > 5: + # Don't fail endlessly - if we failed once, we'll probably + # fail a second time. Hm. Unless the Password Manager is + # prompting for the information. Crap. This isn't great + # but it's better than the current 'repeat until recursion + # depth exceeded' approach + raise HTTPError(req.get_full_url(), 401, "digest auth failed", + headers, None) + else: + self.retried += 1 + if authreq: + scheme = authreq.split()[0] + if scheme.lower() == 'digest': + return self.retry_http_digest_auth(req, authreq) + + def retry_http_digest_auth(self, req, auth): + token, challenge = auth.split(' ', 1) + chal = parse_keqv_list(parse_http_list(challenge)) + auth = self.get_authorization(req, chal) + if auth: + auth_val = 'Digest %s' % auth + if req.headers.get(self.auth_header, None) == auth_val: + return None + req.add_unredirected_header(self.auth_header, auth_val) + resp = self.parent.open(req) + return resp + + def get_cnonce(self, nonce): + # The cnonce-value is an opaque + # quoted string value provided by the client and used by both client + # and server to avoid chosen plaintext attacks, to provide mutual + # authentication, and to provide some message integrity protection. + # This isn't a fabulous effort, but it's probably Good Enough. + dig = hashlib.sha1("%s:%s:%s:%s" % (self.nonce_count, nonce, time.ctime(), + randombytes(8))).hexdigest() + return dig[:16] + + def get_authorization(self, req, chal): + try: + realm = chal['realm'] + nonce = chal['nonce'] + qop = chal.get('qop') + algorithm = chal.get('algorithm', 'MD5') + # mod_digest doesn't send an opaque, even though it isn't + # supposed to be optional + opaque = chal.get('opaque', None) + except KeyError: + return None + + H, KD = self.get_algorithm_impls(algorithm) + if H is None: + return None + + user, pw = self.passwd.find_user_password(realm, req.get_full_url()) + if user is None: + return None + + # XXX not implemented yet + if req.has_data(): + entdig = self.get_entity_digest(req.get_data(), chal) + else: + entdig = None + + A1 = "%s:%s:%s" % (user, realm, pw) + A2 = "%s:%s" % (req.get_method(), + # XXX selector: what about proxies and full urls + req.get_selector()) + if qop == 'auth': + self.nonce_count += 1 + ncvalue = '%08x' % self.nonce_count + cnonce = self.get_cnonce(nonce) + noncebit = "%s:%s:%s:%s:%s" % (nonce, ncvalue, cnonce, qop, H(A2)) + respdig = KD(H(A1), noncebit) + elif qop is None: + respdig = KD(H(A1), "%s:%s" % (nonce, H(A2))) + else: + # XXX handle auth-int. + raise URLError("qop '%s' is not supported." % qop) + + # XXX should the partial digests be encoded too? + + base = 'username="%s", realm="%s", nonce="%s", uri="%s", ' \ + 'response="%s"' % (user, realm, nonce, req.get_selector(), + respdig) + if opaque: + base += ', opaque="%s"' % opaque + if entdig: + base += ', digest="%s"' % entdig + base += ', algorithm="%s"' % algorithm + if qop: + base += ', qop=auth, nc=%s, cnonce="%s"' % (ncvalue, cnonce) + return base + + def get_algorithm_impls(self, algorithm): + # lambdas assume digest modules are imported at the top level + if algorithm == 'MD5': + H = lambda x: hashlib.md5(x).hexdigest() + elif algorithm == 'SHA': + H = lambda x: hashlib.sha1(x).hexdigest() + # XXX MD5-sess + KD = lambda s, d: H("%s:%s" % (s, d)) + return H, KD + + def get_entity_digest(self, data, chal): + # XXX not implemented yet + return None + + +class HTTPDigestAuthHandler(BaseHandler, AbstractDigestAuthHandler): + """An authentication protocol defined by RFC 2069 + + Digest authentication improves on basic authentication because it + does not transmit passwords in the clear. + """ + + auth_header = 'Authorization' + handler_order = 490 # before Basic auth + + def http_error_401(self, req, fp, code, msg, headers): + host = urlparse.urlparse(req.get_full_url())[1] + retry = self.http_error_auth_reqed('www-authenticate', + host, req, headers) + self.reset_retry_count() + return retry + + +class ProxyDigestAuthHandler(BaseHandler, AbstractDigestAuthHandler): + + auth_header = 'Proxy-Authorization' + handler_order = 490 # before Basic auth + + def http_error_407(self, req, fp, code, msg, headers): + host = req.get_host() + retry = self.http_error_auth_reqed('proxy-authenticate', + host, req, headers) + self.reset_retry_count() + return retry + +class AbstractHTTPHandler(BaseHandler): + + def __init__(self, debuglevel=0): + self._debuglevel = debuglevel + + def set_http_debuglevel(self, level): + self._debuglevel = level + + def do_request_(self, request): + host = request.get_host() + if not host: + raise URLError('no host given') + + if request.has_data(): # POST + data = request.get_data() + if not request.has_header('Content-type'): + request.add_unredirected_header( + 'Content-type', + 'application/x-www-form-urlencoded') + if not request.has_header('Content-length'): + request.add_unredirected_header( + 'Content-length', '%d' % len(data)) + + scheme, sel = splittype(request.get_selector()) + sel_host, sel_path = splithost(sel) + if not request.has_header('Host'): + request.add_unredirected_header('Host', sel_host or host) + for name, value in self.parent.addheaders: + name = name.capitalize() + if not request.has_header(name): + request.add_unredirected_header(name, value) + + return request + + def do_open(self, http_class, req): + """Return an addinfourl object for the request, using http_class. + + http_class must implement the HTTPConnection API from httplib. + The addinfourl return value is a file-like object. It also + has methods and attributes including: + - info(): return a mimetools.Message object for the headers + - geturl(): return the original request URL + - code: HTTP status code + """ + host = req.get_host() + if not host: + raise URLError('no host given') + + h = http_class(host, timeout=req.timeout) # will parse host:port + h.set_debuglevel(self._debuglevel) + + headers = dict(req.headers) + headers.update(req.unredirected_hdrs) + # We want to make an HTTP/1.1 request, but the addinfourl + # class isn't prepared to deal with a persistent connection. + # It will try to read all remaining data from the socket, + # which will block while the server waits for the next request. + # So make sure the connection gets closed after the (only) + # request. + headers["Connection"] = "close" + headers = dict( + (name.title(), val) for name, val in headers.items()) + try: + h.request(req.get_method(), req.get_selector(), req.data, headers) + r = h.getresponse() + except socket.error, err: # XXX what error? + raise URLError(err) + + # Pick apart the HTTPResponse object to get the addinfourl + # object initialized properly. + + # Wrap the HTTPResponse object in socket's file object adapter + # for Windows. That adapter calls recv(), so delegate recv() + # to read(). This weird wrapping allows the returned object to + # have readline() and readlines() methods. + + # XXX It might be better to extract the read buffering code + # out of socket._fileobject() and into a base class. + + r.recv = r.read + fp = socket._fileobject(r, close=True) + + resp = addinfourl(fp, r.msg, req.get_full_url()) + resp.code = r.status + resp.msg = r.reason + return resp + + +class HTTPHandler(AbstractHTTPHandler): + + def http_open(self, req): + return self.do_open(httplib.HTTPConnection, req) + + http_request = AbstractHTTPHandler.do_request_ + +if hasattr(httplib, 'HTTPS'): + class HTTPSHandler(AbstractHTTPHandler): + + def https_open(self, req): + return self.do_open(httplib.HTTPSConnection, req) + + https_request = AbstractHTTPHandler.do_request_ + +class HTTPCookieProcessor(BaseHandler): + def __init__(self, cookiejar=None): + import cookielib + if cookiejar is None: + cookiejar = cookielib.CookieJar() + self.cookiejar = cookiejar + + def http_request(self, request): + self.cookiejar.add_cookie_header(request) + return request + + def http_response(self, request, response): + self.cookiejar.extract_cookies(response, request) + return response + + https_request = http_request + https_response = http_response + +class UnknownHandler(BaseHandler): + def unknown_open(self, req): + type = req.get_type() + raise URLError('unknown url type: %s' % type) + +def parse_keqv_list(l): + """Parse list of key=value strings where keys are not duplicated.""" + parsed = {} + for elt in l: + k, v = elt.split('=', 1) + if v[0] == '"' and v[-1] == '"': + v = v[1:-1] + parsed[k] = v + return parsed + +def parse_http_list(s): + """Parse lists as described by RFC 2068 Section 2. + + In particular, parse comma-separated lists where the elements of + the list may include quoted-strings. A quoted-string could + contain a comma. A non-quoted string could have quotes in the + middle. Neither commas nor quotes count if they are escaped. + Only double-quotes count, not single-quotes. + """ + res = [] + part = '' + + escape = quote = False + for cur in s: + if escape: + part += cur + escape = False + continue + if quote: + if cur == '\\': + escape = True + continue + elif cur == '"': + quote = False + part += cur + continue + + if cur == ',': + res.append(part) + part = '' + continue + + if cur == '"': + quote = True + + part += cur + + # append last part + if part: + res.append(part) + + return [part.strip() for part in res] + +class FileHandler(BaseHandler): + # Use local file or FTP depending on form of URL + def file_open(self, req): + url = req.get_selector() + if url[:2] == '//' and url[2:3] != '/': + req.type = 'ftp' + return self.parent.open(req) + else: + return self.open_local_file(req) + + # names for the localhost + names = None + def get_names(self): + if FileHandler.names is None: + try: + FileHandler.names = (socket.gethostbyname('localhost'), + socket.gethostbyname(socket.gethostname())) + except socket.gaierror: + FileHandler.names = (socket.gethostbyname('localhost'),) + return FileHandler.names + + # not entirely sure what the rules are here + def open_local_file(self, req): + import email.utils + import mimetypes + host = req.get_host() + file = req.get_selector() + localfile = url2pathname(file) + try: + stats = os.stat(localfile) + size = stats.st_size + modified = email.utils.formatdate(stats.st_mtime, usegmt=True) + mtype = mimetypes.guess_type(file)[0] + headers = mimetools.Message(StringIO( + 'Content-type: %s\nContent-length: %d\nLast-modified: %s\n' % + (mtype or 'text/plain', size, modified))) + if host: + host, port = splitport(host) + if not host or \ + (not port and socket.gethostbyname(host) in self.get_names()): + return addinfourl(open(localfile, 'rb'), + headers, 'file:'+file) + except OSError, msg: + # urllib2 users shouldn't expect OSErrors coming from urlopen() + raise URLError(msg) + raise URLError('file not on local host') + +class FTPHandler(BaseHandler): + def ftp_open(self, req): + import ftplib + import mimetypes + host = req.get_host() + if not host: + raise IOError, ('ftp error', 'no host given') + host, port = splitport(host) + if port is None: + port = ftplib.FTP_PORT + else: + port = int(port) + + # username/password handling + user, host = splituser(host) + if user: + user, passwd = splitpasswd(user) + else: + passwd = None + host = unquote(host) + user = unquote(user or '') + passwd = unquote(passwd or '') + + try: + host = socket.gethostbyname(host) + except socket.error, msg: + raise URLError(msg) + path, attrs = splitattr(req.get_selector()) + dirs = path.split('/') + dirs = map(unquote, dirs) + dirs, file = dirs[:-1], dirs[-1] + if dirs and not dirs[0]: + dirs = dirs[1:] + try: + fw = self.connect_ftp(user, passwd, host, port, dirs, req.timeout) + type = file and 'I' or 'D' + for attr in attrs: + attr, value = splitvalue(attr) + if attr.lower() == 'type' and \ + value in ('a', 'A', 'i', 'I', 'd', 'D'): + type = value.upper() + fp, retrlen = fw.retrfile(file, type) + headers = "" + mtype = mimetypes.guess_type(req.get_full_url())[0] + if mtype: + headers += "Content-type: %s\n" % mtype + if retrlen is not None and retrlen >= 0: + headers += "Content-length: %d\n" % retrlen + sf = StringIO(headers) + headers = mimetools.Message(sf) + return addinfourl(fp, headers, req.get_full_url()) + except ftplib.all_errors, msg: + raise IOError, ('ftp error', msg), sys.exc_info()[2] + + def connect_ftp(self, user, passwd, host, port, dirs, timeout): + fw = ftpwrapper(user, passwd, host, port, dirs, timeout) +## fw.ftp.set_debuglevel(1) + return fw + +class CacheFTPHandler(FTPHandler): + # XXX would be nice to have pluggable cache strategies + # XXX this stuff is definitely not thread safe + def __init__(self): + self.cache = {} + self.timeout = {} + self.soonest = 0 + self.delay = 60 + self.max_conns = 16 + + def setTimeout(self, t): + self.delay = t + + def setMaxConns(self, m): + self.max_conns = m + + def connect_ftp(self, user, passwd, host, port, dirs, timeout): + key = user, host, port, '/'.join(dirs), timeout + if key in self.cache: + self.timeout[key] = time.time() + self.delay + else: + self.cache[key] = ftpwrapper(user, passwd, host, port, dirs, timeout) + self.timeout[key] = time.time() + self.delay + self.check_cache() + return self.cache[key] + + def check_cache(self): + # first check for old ones + t = time.time() + if self.soonest <= t: + for k, v in self.timeout.items(): + if v < t: + self.cache[k].close() + del self.cache[k] + del self.timeout[k] + self.soonest = min(self.timeout.values()) + + # then check the size + if len(self.cache) == self.max_conns: + for k, v in self.timeout.items(): + if v == self.soonest: + del self.cache[k] + del self.timeout[k] + break + self.soonest = min(self.timeout.values()) From python-checkins at python.org Mon Aug 6 00:52:44 2007 From: python-checkins at python.org (facundo.batista) Date: Mon, 6 Aug 2007 00:52:44 +0200 (CEST) Subject: [Python-checkins] r56758 - python/branches/decimal-branch/Lib/decimal.py Message-ID: <20070805225244.9FE871E4006@bag.python.org> Author: facundo.batista Date: Mon Aug 6 00:52:44 2007 New Revision: 56758 Modified: python/branches/decimal-branch/Lib/decimal.py Log: Coded compare_total_mag() function, all tests pass ok. Also taken out the optional context from copy_abs(), as never used. Modified: python/branches/decimal-branch/Lib/decimal.py ============================================================================== --- python/branches/decimal-branch/Lib/decimal.py (original) +++ python/branches/decimal-branch/Lib/decimal.py Mon Aug 6 00:52:44 2007 @@ -2383,13 +2383,16 @@ return Decimal(0) - def compare_total_mag (self, other, context=None): + def compare_total_mag(self, other): """Compares self to other using abstract repr., ignoring sign. Like compare_total, but with operand's sign ignored and assumed to be 0. """ + s = self.copy_abs() + o = other.copy_abs() + return s.compare_total(o) - def copy_abs(self, context=None): + def copy_abs(self): """Returns a copy with the sign set to 0. """ return Decimal((0, self._int, self._exp)) @@ -3187,12 +3190,12 @@ """ return a.compare_total(b, context=self) - def compare_total_mag (self, a, b): + def compare_total_mag(self, a, b): """Compares two operands using their abstract representation ignoring sign. Like compare_total, but with operand's sign ignored and assumed to be 0. """ - return a.compare_total_mag (b, context=self) + return a.compare_total_mag(b) def copy_abs(self, a): """Returns a copy of the operand with the sign set to 0. @@ -3202,7 +3205,7 @@ >>> ExtendedContext.copy_abs(Decimal('-100')) Decimal("100") """ - return a.copy_abs(context=self) + return a.copy_abs() def copy_decimal(self, a): """Returns a copy of the decimal objet. From python-checkins at python.org Mon Aug 6 01:00:51 2007 From: python-checkins at python.org (facundo.batista) Date: Mon, 6 Aug 2007 01:00:51 +0200 (CEST) Subject: [Python-checkins] r56759 - python/branches/decimal-branch/Lib/decimal.py Message-ID: <20070805230051.220761E4006@bag.python.org> Author: facundo.batista Date: Mon Aug 6 01:00:50 2007 New Revision: 56759 Modified: python/branches/decimal-branch/Lib/decimal.py Log: Fixed number_class() doc tests Modified: python/branches/decimal-branch/Lib/decimal.py ============================================================================== --- python/branches/decimal-branch/Lib/decimal.py (original) +++ python/branches/decimal-branch/Lib/decimal.py Mon Aug 6 01:00:50 2007 @@ -3751,32 +3751,35 @@ +Normal +Infinity - >>> ExtendedContext.number_class(Decimal('Infinity')) - "+Infinity" - >>> ExtendedContext.number_class(Decimal('1E-10')) - "+Normal" - >>> ExtendedContext.number_class(Decimal('2.50')) - "+Normal" - >>> ExtendedContext.number_class(Decimal('0.1E-999')) - "+Subnormal" - >>> ExtendedContext.number_class(Decimal('0')) - "+Zero" - >>> ExtendedContext.number_class(Decimal('-0')) - "-Zero" - >>> ExtendedContext.number_class(Decimal('-0.1E-999')) - "-Subnormal" - >>> ExtendedContext.number_class(Decimal('-1E-10')) - "-Normal" - >>> ExtendedContext.number_class(Decimal('-2.50')) - "-Normal" - >>> ExtendedContext.number_class(Decimal('-Infinity')) - "-Infinity" - >>> ExtendedContext.number_class(Decimal('NaN')) - "NaN" - >>> ExtendedContext.number_class(Decimal('-NaN')) - "NaN" - >>> ExtendedContext.number_class(Decimal('sNaN')) - "sNaN" + >>> c = Context(ExtendedContext) + >>> c.Emin = -999 + >>> c.Emax = 999 + >>> c.number_class(Decimal('Infinity')) + '+Infinity' + >>> c.number_class(Decimal('1E-10')) + '+Normal' + >>> c.number_class(Decimal('2.50')) + '+Normal' + >>> c.number_class(Decimal('0.1E-999')) + '+Subnormal' + >>> c.number_class(Decimal('0')) + '+Zero' + >>> c.number_class(Decimal('-0')) + '-Zero' + >>> c.number_class(Decimal('-0.1E-999')) + '-Subnormal' + >>> c.number_class(Decimal('-1E-10')) + '-Normal' + >>> c.number_class(Decimal('-2.50')) + '-Normal' + >>> c.number_class(Decimal('-Infinity')) + '-Infinity' + >>> c.number_class(Decimal('NaN')) + 'NaN' + >>> c.number_class(Decimal('-NaN')) + 'NaN' + >>> c.number_class(Decimal('sNaN')) + 'sNaN' """ return a.number_class(context=self) From python-checkins at python.org Mon Aug 6 09:31:28 2007 From: python-checkins at python.org (georg.brandl) Date: Mon, 6 Aug 2007 09:31:28 +0200 (CEST) Subject: [Python-checkins] r56761 - in doctools/trunk/Doc-3k: c-api/concrete.rst library/bsddb.rst Message-ID: <20070806073128.9868C1E400A@bag.python.org> Author: georg.brandl Date: Mon Aug 6 09:31:28 2007 New Revision: 56761 Modified: doctools/trunk/Doc-3k/c-api/concrete.rst doctools/trunk/Doc-3k/library/bsddb.rst Log: Port rev. 56754, 56755. Modified: doctools/trunk/Doc-3k/c-api/concrete.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/concrete.rst (original) +++ doctools/trunk/Doc-3k/c-api/concrete.rst Mon Aug 6 09:31:28 2007 @@ -1153,10 +1153,10 @@ is *NULL*. -.. cfunction:: PyObject* PyUnicode_FromString(const char *u) +.. cfunction:: PyObject* PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size) - Create a Unicode Object from the char buffer *u*. *u* must be 0-terminated, the - bytes will be interpreted as being latin-1 encoded. *u* may also be *NULL* which + Create a Unicode Object from the char buffer *u*. The bytes will be interpreted + as being UTF-8 encoded. *u* may also be *NULL* which causes the contents to be undefined. It is the user's responsibility to fill in the needed data. The buffer is copied into the new object. If the buffer is not *NULL*, the return value might be a shared object. Therefore, modification of @@ -1165,6 +1165,14 @@ .. versionadded:: 3.0 +.. cfunction:: PyObject *PyUnicode_FromString(const char *u) + + Create a Unicode object from an UTF-8 encoded null-terminated char buffer + *u*. + + .. versionadded:: 3.0 + + .. cfunction:: PyObject* PyUnicode_FromFormat(const char *format, ...) Take a C :cfunc:`printf`\ -style *format* string and a variable number of Modified: doctools/trunk/Doc-3k/library/bsddb.rst ============================================================================== --- doctools/trunk/Doc-3k/library/bsddb.rst (original) +++ doctools/trunk/Doc-3k/library/bsddb.rst Mon Aug 6 09:31:28 2007 @@ -78,6 +78,22 @@ Consult the Berkeley DB documentation for their use and interpretation. +.. class:: StringKeys(db) + + Wrapper class around a DB object that supports string keys (rather than bytes). + All keys are encoded as UTF-8, then passed to the underlying object. + + .. versionadded:: 3.0 + + +.. class:: StringValues(db) + + Wrapper class around a DB object that supports string values (rather than bytes). + All values are encoded as UTF-8, then passed to the underlying object. + + .. versionadded:: 3.0 + + .. seealso:: Module :mod:`dbhash` From python-checkins at python.org Mon Aug 6 09:37:59 2007 From: python-checkins at python.org (georg.brandl) Date: Mon, 6 Aug 2007 09:37:59 +0200 (CEST) Subject: [Python-checkins] r56762 - python/trunk/Python/ast.c Message-ID: <20070806073759.0AE221E4006@bag.python.org> Author: georg.brandl Date: Mon Aug 6 09:37:58 2007 New Revision: 56762 Modified: python/trunk/Python/ast.c Log: Place #ifdef Py_USING_UNICODE around decode_unicode(). Modified: python/trunk/Python/ast.c ============================================================================== --- python/trunk/Python/ast.c (original) +++ python/trunk/Python/ast.c Mon Aug 6 09:37:58 2007 @@ -3143,6 +3143,7 @@ #endif } +#ifdef Py_USING_UNICODE static PyObject * decode_unicode(const char *s, size_t len, int rawmode, const char *encoding) { @@ -3204,6 +3205,7 @@ Py_XDECREF(u); return v; } +#endif /* s is a Python string literal, including the bracketing quote characters, * and r &/or u prefixes (if any), and embedded escape sequences (if any). From python-checkins at python.org Mon Aug 6 09:39:09 2007 From: python-checkins at python.org (georg.brandl) Date: Mon, 6 Aug 2007 09:39:09 +0200 (CEST) Subject: [Python-checkins] r56763 - python/trunk/Lib/sgmllib.py Message-ID: <20070806073909.BB5F11E4006@bag.python.org> Author: georg.brandl Date: Mon Aug 6 09:39:09 2007 New Revision: 56763 Modified: python/trunk/Lib/sgmllib.py Log: Replace unnecessary function call. Modified: python/trunk/Lib/sgmllib.py ============================================================================== --- python/trunk/Lib/sgmllib.py (original) +++ python/trunk/Lib/sgmllib.py Mon Aug 6 09:39:09 2007 @@ -428,7 +428,7 @@ if replacement is None: self.unknown_entityref(name) else: - self.handle_data(self.convert_entityref(name)) + self.handle_data(replacement) # Example -- handle data, should be overridden def handle_data(self, data): From python-checkins at python.org Mon Aug 6 09:52:22 2007 From: python-checkins at python.org (georg.brandl) Date: Mon, 6 Aug 2007 09:52:22 +0200 (CEST) Subject: [Python-checkins] r56764 - python/trunk/Doc/howto/urllib2.rst Message-ID: <20070806075222.75D5F1E400C@bag.python.org> Author: georg.brandl Date: Mon Aug 6 09:52:20 2007 New Revision: 56764 Modified: python/trunk/Doc/howto/urllib2.rst Log: Patch #1765839: add link to https+proxy urllib2 opener. Modified: python/trunk/Doc/howto/urllib2.rst ============================================================================== --- python/trunk/Doc/howto/urllib2.rst (original) +++ python/trunk/Doc/howto/urllib2.rst Mon Aug 6 09:52:20 2007 @@ -541,7 +541,9 @@ .. note:: Currently ``urllib2`` *does not* support fetching of ``https`` - locations through a proxy. This can be a problem. + locations through a proxy. However, this can be enabled by extending + urllib2 as shown in the recipe [#]_. + Sockets and Layers ================== @@ -596,3 +598,6 @@ is set to use the proxy, which urllib2 picks up on. In order to test scripts with a localhost server, I have to prevent urllib2 from using the proxy. +.. [#] urllib2 opener for SSL proxy (CONNECT method): `ASPN Cookbook Recipe + `_. + From python-checkins at python.org Mon Aug 6 09:57:07 2007 From: python-checkins at python.org (georg.brandl) Date: Mon, 6 Aug 2007 09:57:07 +0200 (CEST) Subject: [Python-checkins] r56765 - doctools/trunk/sphinx/templates/download.html Message-ID: <20070806075707.B920B1E400D@bag.python.org> Author: georg.brandl Date: Mon Aug 6 09:57:06 2007 New Revision: 56765 Added: doctools/trunk/sphinx/templates/download.html Log: Add missing file... Added: doctools/trunk/sphinx/templates/download.html ============================================================================== --- (empty file) +++ doctools/trunk/sphinx/templates/download.html Mon Aug 6 09:57:06 2007 @@ -0,0 +1,56 @@ +{% extends "layout.html" %} +{% set title = 'Download' %} +{% block body %} + +

      Download Python {{ release }} Documentation + {%- if last_updated %} (last updated on {{ last_updated }}){% endif %}

      + +

      To download an archive containing all the documents for this version of +Python in one of various formats, follow one of links in this table. The numbers +in the table are the size of the download files in Kilobytes.

      + +{# XXX download links, relative to download_base_url #} + + +

      These archives contain all the content in the documentation section.

      + +

      Unpacking

      + +

      Unix users should download the .tar.bz2 archives; these are bzipped tar +archives and can be handled in the usual way using tar and the bzip2 +program. The InfoZIP unzip program can be +used to handle the ZIP archives if desired. The .tar.bz2 archives provide the +best compression and fastest download times.

      + +

      Windows users can use the ZIP archives since those are customary on that +platform. These are created on Unix using the InfoZIP zip program. They may be +unpacked using the free WiZ tool (from the InfoZIP developers) or the +proprietary WinZip 7.0 tool. Many other +tools for handling ZIP archives are available; any of them should work. WinZip +can also handle the gzipped tar archives if needed, but be careful that the +filenames may be mangled if you download these using a Web browser.

      + +

      Note that the .tar.bz2 files are smaller than the other archives; Windows +users may want to install the bzip2 tools on their systems as well. Windows +binaries for a command-line tool are available at The bzip2 and libbzip2 official home page, but +most other archiving utilities support the tar and bzip2 formats as well.

      + + +

      Problems

      + +

      Printing PDFs using Adobe Acrobat Reader 5.0: Adobe has +reportedly admitted that there is a bug in Acrobat Reader 5.0 which causes it +not to print at least some PDF files generated by pdfTeX. This software is used +to produce the PDF version of the Python documentation, and our documents +definately trigger this bug in Acrobat Reader. To print the PDF files, use +Acrobat Reader 4.x, ghostscript, or xpdf.

      + +

      Reportedly, Acrobat Reader 6.0 can print these documents without this +problem, but we've not yet had an opportunity to confirm the report. Sadly, +version 6.0 is not yet available on Unix platforms.

      + +

      If you have comments or suggestions for the Python documentation, please send +email to docs at python.org.

      + +{% endblock %} \ No newline at end of file From python-checkins at python.org Mon Aug 6 10:07:24 2007 From: python-checkins at python.org (georg.brandl) Date: Mon, 6 Aug 2007 10:07:24 +0200 (CEST) Subject: [Python-checkins] r56766 - in doctools/trunk: Doc-26/howto/urllib2.rst Doc-3k/howto/urllib2.rst Message-ID: <20070806080724.C63111E400C@bag.python.org> Author: georg.brandl Date: Mon Aug 6 10:07:23 2007 New Revision: 56766 Modified: doctools/trunk/Doc-26/howto/urllib2.rst doctools/trunk/Doc-3k/howto/urllib2.rst Log: Port rev. 56764. Modified: doctools/trunk/Doc-26/howto/urllib2.rst ============================================================================== --- doctools/trunk/Doc-26/howto/urllib2.rst (original) +++ doctools/trunk/Doc-26/howto/urllib2.rst Mon Aug 6 10:07:23 2007 @@ -518,7 +518,9 @@ .. note:: Currently ``urllib2`` *does not* support fetching of ``https`` locations - through a proxy. This can be a problem. + through a proxy. However, this can be enabled by extending urllib2 as + shown in the recipe [#]_. + Sockets and Layers ================== @@ -571,3 +573,6 @@ is set to use the proxy, which urllib2 picks up on. In order to test scripts with a localhost server, I have to prevent urllib2 from using the proxy. +.. [#] urllib2 opener for SSL proxy (CONNECT method): `ASPN Cookbook Recipe + `_. + Modified: doctools/trunk/Doc-3k/howto/urllib2.rst ============================================================================== --- doctools/trunk/Doc-3k/howto/urllib2.rst (original) +++ doctools/trunk/Doc-3k/howto/urllib2.rst Mon Aug 6 10:07:23 2007 @@ -518,7 +518,9 @@ .. note:: Currently ``urllib2`` *does not* support fetching of ``https`` locations - through a proxy. This can be a problem. + through a proxy. However, this can be enabled by extending urllib2 as + shown in the recipe [#]_. + Sockets and Layers ================== @@ -571,3 +573,6 @@ is set to use the proxy, which urllib2 picks up on. In order to test scripts with a localhost server, I have to prevent urllib2 from using the proxy. +.. [#] urllib2 opener for SSL proxy (CONNECT method): `ASPN Cookbook Recipe + `_. + From python-checkins at python.org Mon Aug 6 10:54:04 2007 From: python-checkins at python.org (mark.summerfield) Date: Mon, 6 Aug 2007 10:54:04 +0200 (CEST) Subject: [Python-checkins] r56767 - doctools/trunk/Doc-26/library/collections.rst Message-ID: <20070806085404.818EB1E4006@bag.python.org> Author: mark.summerfield Date: Mon Aug 6 10:54:04 2007 New Revision: 56767 Modified: doctools/trunk/Doc-26/library/collections.rst Log: Added to the description: mention of and links to dict, list, and tuple, and mention of bsddb.btopen(). Modified: doctools/trunk/Doc-26/library/collections.rst ============================================================================== --- doctools/trunk/Doc-26/library/collections.rst (original) +++ doctools/trunk/Doc-26/library/collections.rst Mon Aug 6 10:54:04 2007 @@ -10,10 +10,16 @@ .. versionadded:: 2.4 -This module implements high-performance container datatypes. Currently, there -are two datatypes, deque and defaultdict, and one datatype factory function, -:func:`NamedTuple`. Future additions may include balanced trees and ordered -dictionaries. +This module implements high-performance container datatypes. Currently, +there are two datatypes, :class:`deque` and :class:`defaultdict`, and +one datatype factory function, :func:`NamedTuple`. Python already +includes built-in containers, :func:`dict`, :func:`list`, and +:func:`tuple`. The optional :mod:`bsddb` module has a :meth:`btopen` +method that can be used to create in-memory or file based ordered +dictionaries with string keys. + +Future editions of the standard library may include balanced trees and +ordered dictionaries. .. versionchanged:: 2.5 Added defaultdict. From python-checkins at python.org Mon Aug 6 11:21:32 2007 From: python-checkins at python.org (mark.summerfield) Date: Mon, 6 Aug 2007 11:21:32 +0200 (CEST) Subject: [Python-checkins] r56768 - doctools/trunk/Doc-26/library/stdtypes.rst doctools/trunk/Doc-26/library/string.rst doctools/trunk/Doc-26/library/strings.rst Message-ID: <20070806092132.ABAA81E4006@bag.python.org> Author: mark.summerfield Date: Mon Aug 6 11:21:32 2007 New Revision: 56768 Modified: doctools/trunk/Doc-26/library/stdtypes.rst doctools/trunk/Doc-26/library/string.rst doctools/trunk/Doc-26/library/strings.rst Log: Added more cross-references for strings. And one more for open(). Modified: doctools/trunk/Doc-26/library/stdtypes.rst ============================================================================== --- doctools/trunk/Doc-26/library/stdtypes.rst (original) +++ doctools/trunk/Doc-26/library/stdtypes.rst Mon Aug 6 11:21:32 2007 @@ -657,9 +657,13 @@ .. index:: pair: string; methods -These are the string methods which both 8-bit strings and Unicode objects -support: - +Below are listed the string methods which both 8-bit strings and Unicode +objects support. In addition, Python's strings support the +sequence type methods described in the +:ref:`typesseq` section (above). To output formatted strings use +template strings or the ``%`` operator described in the +:ref:`typesseq-strings` section (below). Also, see the :mod:`re` module for +string functions based on regular expressions. .. method:: str.capitalize() @@ -1744,11 +1748,12 @@ module: os module: socket -File objects are implemented using C's ``stdio`` package and can be created with -the built-in constructor :func:`file` described in section -:ref:`built-in-funcs`. [#]_ File objects are also returned by some other -built-in functions and methods, such as :func:`os.popen` and :func:`os.fdopen` -and the :meth:`makefile` method of socket objects. +File objects are implemented using C's ``stdio`` package and can be +created with the built-in :func:`file` and (more usually) :func:`open` +constructors described in the :ref:`built-in-funcs` section. [#]_ File +objects are also returned by some other built-in functions and methods, +such as :func:`os.popen` and :func:`os.fdopen` and the :meth:`makefile` +method of socket objects. When a file operation fails for an I/O-related reason, the exception :exc:`IOError` is raised. This includes situations where the operation is not Modified: doctools/trunk/Doc-26/library/string.rst ============================================================================== --- doctools/trunk/Doc-26/library/string.rst (original) +++ doctools/trunk/Doc-26/library/string.rst Mon Aug 6 11:21:32 2007 @@ -8,10 +8,15 @@ .. index:: module: re -The :mod:`string` module contains a number of useful constants and classes, as -well as some deprecated legacy functions that are also available as methods on -strings. See the module :mod:`re` for string functions based on regular -expressions. +The :mod:`string` module contains a number of useful constants and +classes, as well as some deprecated legacy functions that are also +available as methods on strings. In addition, Python's built-in string +classes support the sequence type methods described in the +:ref:`typesseq` section, and also the string-specific methods described +in the :ref:`string-methods` section. To output formatted strings use +template strings or the ``%`` operator described in the +:ref:`typesseq-strings` section. Also, see the :mod:`re` module for +string functions based on regular expressions. String constants Modified: doctools/trunk/Doc-26/library/strings.rst ============================================================================== --- doctools/trunk/Doc-26/library/strings.rst (original) +++ doctools/trunk/Doc-26/library/strings.rst Mon Aug 6 11:21:32 2007 @@ -12,7 +12,8 @@ methods described in the :ref:`typesseq` section, and also the string-specific methods described in the :ref:`string-methods` section. To output formatted strings use template strings or the ``%`` operator -described in the :ref:`typesseq-strings` section. +described in the :ref:`typesseq-strings` section. Also, see the +:mod:`re` module for string functions based on regular expressions. .. toctree:: From python-checkins at python.org Mon Aug 6 12:49:53 2007 From: python-checkins at python.org (georg.brandl) Date: Mon, 6 Aug 2007 12:49:53 +0200 (CEST) Subject: [Python-checkins] r56769 - in doctools/trunk: Doc-26/conf.py Doc-26/documenting/markup.rst Doc-26/library/time.rst Doc-3k/conf.py Doc-3k/documenting/markup.rst Doc-3k/library/time.rst sphinx/directives.py sphinx/environment.py sphinx/roles.py Message-ID: <20070806104953.579621E400F@bag.python.org> Author: georg.brandl Date: Mon Aug 6 12:49:52 2007 New Revision: 56769 Modified: doctools/trunk/Doc-26/conf.py doctools/trunk/Doc-26/documenting/markup.rst doctools/trunk/Doc-26/library/time.rst doctools/trunk/Doc-3k/conf.py doctools/trunk/Doc-3k/documenting/markup.rst doctools/trunk/Doc-3k/library/time.rst doctools/trunk/sphinx/directives.py doctools/trunk/sphinx/environment.py doctools/trunk/sphinx/roles.py Log: Add module names even to names in classes. Add a config option for that. Add a :samp: role for highlighting text inside literal code. Fix the time module docs. Modified: doctools/trunk/Doc-26/conf.py ============================================================================== --- doctools/trunk/Doc-26/conf.py (original) +++ doctools/trunk/Doc-26/conf.py Mon Aug 6 12:49:52 2007 @@ -23,6 +23,9 @@ # Else, today_fmt is used as the format for a strftime call. today_fmt = '%B %d, %Y' +# The base URL for download links. +download_base_url = 'http://docs.python.org/ftp/python/doc/' + # List of files that shouldn't be included in the build. unused_files = [ 'whatsnew/2.0.rst', @@ -47,5 +50,6 @@ # If true, '()' will be appended to :func: etc. cross-reference text. add_function_parentheses = True -# The base URL for download links. -download_base_url = 'http://docs.python.org/ftp/python/doc/' +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +add_module_names = True Modified: doctools/trunk/Doc-26/documenting/markup.rst ============================================================================== --- doctools/trunk/Doc-26/documenting/markup.rst (original) +++ doctools/trunk/Doc-26/documenting/markup.rst Mon Aug 6 12:49:52 2007 @@ -474,6 +474,14 @@ A regular expression. Quotes should not be included. +.. describe:: samp + + A piece of literal text, such as code. Within the contents, you can use + curly braces to indicate a "variable" part, as in ``:file:``. + + If you don't need the "variable part" indication, use the standard + ````code```` instead. + .. describe:: var A Python or C variable or parameter name. Modified: doctools/trunk/Doc-26/library/time.rst ============================================================================== --- doctools/trunk/Doc-26/library/time.rst (original) +++ doctools/trunk/Doc-26/library/time.rst Mon Aug 6 12:49:52 2007 @@ -445,44 +445,44 @@ The :envvar:`TZ` environment variable should contain no whitespace. - The standard format of the :envvar:`TZ` environment variable is: (whitespace - added for clarity) + The standard format of the :envvar:`TZ` environment variable is (whitespace + added for clarity):: - std offset [dst [offset - [,start[/time], end[/time]]]] + std offset [dst [offset [,start[/time], end[/time]]]] - Where: + Where the components are: - std and dst + ``std`` and ``dst`` Three or more alphanumerics giving the timezone abbreviations. These will be propagated into time.tzname - offset - The offset has the form: ? hh[:mm[:ss]]. This indicates the value added the - local time to arrive at UTC. If preceded by a '-', the timezone is east of the - Prime Meridian; otherwise, it is west. If no offset follows dst, summer time is - assumed to be one hour ahead of standard time. + ``offset`` + The offset has the form: ``? hh[:mm[:ss]]``. This indicates the value + added the local time to arrive at UTC. If preceded by a '-', the timezone + is east of the Prime Meridian; otherwise, it is west. If no offset follows + dst, summer time is assumed to be one hour ahead of standard time. - start[/time - ,end[/time]] Indicates when to change to and back from DST. The format of the + ``start[/time], end[/time]`` + Indicates when to change to and back from DST. The format of the start and end dates are one of the following: - J*n* - The Julian day *n* (1 <= *n* <= 365). Leap days are not counted, so in all - years February 28 is day 59 and March 1 is day 60. - - *n* - The zero-based Julian day (0 <= *n* <= 365). Leap days are counted, and it is - possible to refer to February 29. - - M*m*.*n*.*d* - The *d*'th day (0 <= *d* <= 6) or week *n* of month *m* of the year (1 <= *n* - <= 5, 1 <= *m* <= 12, where week 5 means "the last *d* day in month *m*" which - may occur in either the fourth or the fifth week). Week 1 is the first week in - which the *d*'th day occurs. Day zero is Sunday. + :samp:`J{n}` + The Julian day *n* (1 <= *n* <= 365). Leap days are not counted, so in + all years February 28 is day 59 and March 1 is day 60. + + :samp:`{n}` + The zero-based Julian day (0 <= *n* <= 365). Leap days are counted, and + it is possible to refer to February 29. + + :samp:`M{m}.{n}.{d}` + The *d*'th day (0 <= *d* <= 6) or week *n* of month *m* of the year (1 + <= *n* <= 5, 1 <= *m* <= 12, where week 5 means "the last *d* day in + month *m*" which may occur in either the fourth or the fifth + week). Week 1 is the first week in which the *d*'th day occurs. Day + zero is Sunday. - time has the same format as offset except that no leading sign ('-' or '+') is - allowed. The default, if time is not given, is 02:00:00. + ``time`` has the same format as ``offset`` except that no leading sign + ('-' or '+') is allowed. The default, if time is not given, is 02:00:00. :: Modified: doctools/trunk/Doc-3k/conf.py ============================================================================== --- doctools/trunk/Doc-3k/conf.py (original) +++ doctools/trunk/Doc-3k/conf.py Mon Aug 6 12:49:52 2007 @@ -23,6 +23,9 @@ # Else, today_fmt is used as the format for a strftime call. today_fmt = '%B %d, %Y' +# The base URL for download links. +download_base_url = 'http://docs.python.org/ftp/python/doc/' + # List of files that shouldn't be included in the build. unused_files = [ 'whatsnew/2.0.rst', @@ -48,5 +51,6 @@ # If true, '()' will be appended to :func: etc. cross-reference text. add_function_parentheses = True -# The base URL for download links. -download_base_url = 'http://docs.python.org/ftp/python/doc/' +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +add_module_names = True Modified: doctools/trunk/Doc-3k/documenting/markup.rst ============================================================================== --- doctools/trunk/Doc-3k/documenting/markup.rst (original) +++ doctools/trunk/Doc-3k/documenting/markup.rst Mon Aug 6 12:49:52 2007 @@ -474,6 +474,14 @@ A regular expression. Quotes should not be included. +.. describe:: samp + + A piece of literal text, such as code. Within the contents, you can use + curly braces to indicate a "variable" part, as in ``:file:``. + + If you don't need the "variable part" indication, use the standard + ````code```` instead. + .. describe:: var A Python or C variable or parameter name. Modified: doctools/trunk/Doc-3k/library/time.rst ============================================================================== --- doctools/trunk/Doc-3k/library/time.rst (original) +++ doctools/trunk/Doc-3k/library/time.rst Mon Aug 6 12:49:52 2007 @@ -445,44 +445,44 @@ The :envvar:`TZ` environment variable should contain no whitespace. - The standard format of the :envvar:`TZ` environment variable is: (whitespace - added for clarity) + The standard format of the :envvar:`TZ` environment variable is (whitespace + added for clarity):: - std offset [dst [offset - [,start[/time], end[/time]]]] + std offset [dst [offset [,start[/time], end[/time]]]] - Where: + Where the components are: - std and dst + ``std`` and ``dst`` Three or more alphanumerics giving the timezone abbreviations. These will be propagated into time.tzname - offset - The offset has the form: ? hh[:mm[:ss]]. This indicates the value added the - local time to arrive at UTC. If preceded by a '-', the timezone is east of the - Prime Meridian; otherwise, it is west. If no offset follows dst, summer time is - assumed to be one hour ahead of standard time. + ``offset`` + The offset has the form: ``? hh[:mm[:ss]]``. This indicates the value + added the local time to arrive at UTC. If preceded by a '-', the timezone + is east of the Prime Meridian; otherwise, it is west. If no offset follows + dst, summer time is assumed to be one hour ahead of standard time. - start[/time - ,end[/time]] Indicates when to change to and back from DST. The format of the + ``start[/time], end[/time]`` + Indicates when to change to and back from DST. The format of the start and end dates are one of the following: - J*n* - The Julian day *n* (1 <= *n* <= 365). Leap days are not counted, so in all - years February 28 is day 59 and March 1 is day 60. - - *n* - The zero-based Julian day (0 <= *n* <= 365). Leap days are counted, and it is - possible to refer to February 29. - - M*m*.*n*.*d* - The *d*'th day (0 <= *d* <= 6) or week *n* of month *m* of the year (1 <= *n* - <= 5, 1 <= *m* <= 12, where week 5 means "the last *d* day in month *m*" which - may occur in either the fourth or the fifth week). Week 1 is the first week in - which the *d*'th day occurs. Day zero is Sunday. + :samp:`J{n}` + The Julian day *n* (1 <= *n* <= 365). Leap days are not counted, so in + all years February 28 is day 59 and March 1 is day 60. + + :samp:`{n}` + The zero-based Julian day (0 <= *n* <= 365). Leap days are counted, and + it is possible to refer to February 29. + + :samp:`M{m}.{n}.{d}` + The *d*'th day (0 <= *d* <= 6) or week *n* of month *m* of the year (1 + <= *n* <= 5, 1 <= *m* <= 12, where week 5 means "the last *d* day in + month *m*" which may occur in either the fourth or the fifth + week). Week 1 is the first week in which the *d*'th day occurs. Day + zero is Sunday. - time has the same format as offset except that no leading sign ('-' or '+') is - allowed. The default, if time is not given, is 02:00:00. + ``time`` has the same format as ``offset`` except that no leading sign + ('-' or '+') is allowed. The default, if time is not given, is 02:00:00. :: Modified: doctools/trunk/sphinx/directives.py ============================================================================== --- doctools/trunk/sphinx/directives.py (original) +++ doctools/trunk/sphinx/directives.py Mon Aug 6 12:49:52 2007 @@ -113,7 +113,7 @@ py_paramlist_re = re.compile(r'([\[\],])') # split at '[', ']' and ',' -def parse_py_signature(signode, sig, desctype, currmodule, currclass): +def parse_py_signature(signode, sig, desctype, env): """ Transform a python signature into RST nodes. Return the fully qualified name of the thing. @@ -126,24 +126,27 @@ if m is None: raise ValueError classname, name, arglist = m.groups() - if currclass: - if classname and classname.startswith(currclass): + if env.currclass: + if classname and classname.startswith(env.currclass): fullname = classname + name - classname = classname[len(currclass):].lstrip('.') + classname = classname[len(env.currclass):].lstrip('.') elif classname: - fullname = currclass + '.' + classname + name + fullname = env.currclass + '.' + classname + name else: - fullname = currclass + '.' + name + fullname = env.currclass + '.' + name else: fullname = classname + name if classname else name - if classname: - signode += addnodes.desc_classname(classname, classname) - # only add the module name for module globals # exceptions are a special case, since they are documented in the # 'exceptions' module. - elif currmodule and currmodule != 'exceptions': - signode += addnodes.desc_classname(currmodule+'.', currmodule+'.') + if env.config.get('add_module_names', True) and \ + env.currmodule and env.currmodule != 'exceptions': + nodetext = env.currmodule + '.' + if classname: + nodetext += classname + signode += addnodes.desc_classname(nodetext, nodetext) + elif classname: + signode += addnodes.desc_classname(classname, classname) signode += addnodes.desc_name(name, name) if not arglist: @@ -287,8 +290,7 @@ try: if desctype in ('function', 'data', 'class', 'exception', 'method', 'attribute'): - name = parse_py_signature(signode, sig, desctype, - env.currmodule, env.currclass) + name = parse_py_signature(signode, sig, desctype, env) elif desctype in ('cfunction', 'cmember', 'cmacro', 'ctype', 'cvar'): name = parse_c_signature(signode, sig, desctype) elif desctype == 'opcode': Modified: doctools/trunk/sphinx/environment.py ============================================================================== --- doctools/trunk/sphinx/environment.py (original) +++ doctools/trunk/sphinx/environment.py Mon Aug 6 12:49:52 2007 @@ -281,10 +281,10 @@ if newmtime == mtime: continue # check the MD5 - with file(path.join(self.srcdir, filename), 'rb') as f: - newmd5 = hashlib.md5(f.read()).digest() - if newmd5 != md5: - changed.append(filename) + #with file(path.join(self.srcdir, filename), 'rb') as f: + # newmd5 = hashlib.md5(f.read()).digest() + #if newmd5 != md5: + changed.append(filename) return removed, changed Modified: doctools/trunk/sphinx/roles.py ============================================================================== --- doctools/trunk/sphinx/roles.py (original) +++ doctools/trunk/sphinx/roles.py Mon Aug 6 12:49:52 2007 @@ -112,13 +112,13 @@ rawtext, utils.unescape(text).replace('-->', u'\N{TRIANGULAR BULLET}'))], [] -_filevar_re = re.compile('{([^}]+)}') +_litvar_re = re.compile('{([^}]+)}') -def file_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): +def emph_literal_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): text = utils.unescape(text) retnodes = [] pos = 0 - for m in _filevar_re.finditer(text): + for m in _litvar_re.finditer(text): if m.start() > pos: txt = text[pos:m.start()] retnodes.append(nodes.literal(txt, txt)) @@ -149,7 +149,8 @@ 'token' : xfileref_role, 'menuselection' : menusel_role, - 'file' : file_role, + 'file' : emph_literal_role, + 'samp' : emph_literal_role, } for rolename, func in specific_docroles.iteritems(): From python-checkins at python.org Mon Aug 6 18:29:32 2007 From: python-checkins at python.org (georg.brandl) Date: Mon, 6 Aug 2007 18:29:32 +0200 (CEST) Subject: [Python-checkins] r56770 - doctools/trunk/Doc-3k/library/collections.rst doctools/trunk/Doc-3k/library/stdtypes.rst doctools/trunk/Doc-3k/library/string.rst doctools/trunk/Doc-3k/library/strings.rst Message-ID: <20070806162932.648D01E4006@bag.python.org> Author: georg.brandl Date: Mon Aug 6 18:29:32 2007 New Revision: 56770 Modified: doctools/trunk/Doc-3k/library/collections.rst doctools/trunk/Doc-3k/library/stdtypes.rst doctools/trunk/Doc-3k/library/string.rst doctools/trunk/Doc-3k/library/strings.rst Log: Port rev. 56767f. Modified: doctools/trunk/Doc-3k/library/collections.rst ============================================================================== --- doctools/trunk/Doc-3k/library/collections.rst (original) +++ doctools/trunk/Doc-3k/library/collections.rst Mon Aug 6 18:29:32 2007 @@ -10,10 +10,16 @@ .. versionadded:: 2.4 -This module implements high-performance container datatypes. Currently, there -are two datatypes, deque and defaultdict, and one datatype factory function, -:func:`NamedTuple`. Future additions may include balanced trees and ordered -dictionaries. +This module implements high-performance container datatypes. Currently, +there are two datatypes, :class:`deque` and :class:`defaultdict`, and +one datatype factory function, :func:`NamedTuple`. Python already +includes built-in containers, :func:`dict`, :func:`list`, and +:func:`tuple`. The optional :mod:`bsddb` module has a :meth:`btopen` +method that can be used to create in-memory or file based ordered +dictionaries with string keys. + +Future editions of the standard library may include balanced trees and +ordered dictionaries. .. versionchanged:: 2.5 Added defaultdict. Modified: doctools/trunk/Doc-3k/library/stdtypes.rst ============================================================================== --- doctools/trunk/Doc-3k/library/stdtypes.rst (original) +++ doctools/trunk/Doc-3k/library/stdtypes.rst Mon Aug 6 18:29:32 2007 @@ -650,9 +650,13 @@ .. index:: pair: string; methods -These are the string methods which both 8-bit strings and Unicode objects -support: - +Below are listed the string methods which both 8-bit strings and Unicode +objects support. In addition, Python's strings support the +sequence type methods described in the +:ref:`typesseq` section (above). To output formatted strings use +template strings or the ``%`` operator described in the +:ref:`typesseq-strings` section (below). Also, see the :mod:`re` module for +string functions based on regular expressions. .. method:: str.capitalize() @@ -1728,11 +1732,12 @@ module: os module: socket -File objects are implemented using C's ``stdio`` package and can be created with -the built-in constructor :func:`file` described in section -:ref:`built-in-funcs`. [#]_ File objects are also returned by some other -built-in functions and methods, such as :func:`os.popen` and :func:`os.fdopen` -and the :meth:`makefile` method of socket objects. +File objects are implemented using C's ``stdio`` package and can be +created with the built-in :func:`file` and (more usually) :func:`open` +constructors described in the :ref:`built-in-funcs` section. [#]_ File +objects are also returned by some other built-in functions and methods, +such as :func:`os.popen` and :func:`os.fdopen` and the :meth:`makefile` +method of socket objects. When a file operation fails for an I/O-related reason, the exception :exc:`IOError` is raised. This includes situations where the operation is not Modified: doctools/trunk/Doc-3k/library/string.rst ============================================================================== --- doctools/trunk/Doc-3k/library/string.rst (original) +++ doctools/trunk/Doc-3k/library/string.rst Mon Aug 6 18:29:32 2007 @@ -8,10 +8,15 @@ .. index:: module: re -The :mod:`string` module contains a number of useful constants and classes, as -well as some deprecated legacy functions that are also available as methods on -strings. See the module :mod:`re` for string functions based on regular -expressions. +The :mod:`string` module contains a number of useful constants and +classes, as well as some deprecated legacy functions that are also +available as methods on strings. In addition, Python's built-in string +classes support the sequence type methods described in the +:ref:`typesseq` section, and also the string-specific methods described +in the :ref:`string-methods` section. To output formatted strings use +template strings or the ``%`` operator described in the +:ref:`typesseq-strings` section. Also, see the :mod:`re` module for +string functions based on regular expressions. String constants Modified: doctools/trunk/Doc-3k/library/strings.rst ============================================================================== --- doctools/trunk/Doc-3k/library/strings.rst (original) +++ doctools/trunk/Doc-3k/library/strings.rst Mon Aug 6 18:29:32 2007 @@ -12,7 +12,8 @@ methods described in the :ref:`typesseq` section, and also the string-specific methods described in the :ref:`string-methods` section. To output formatted strings use template strings or the ``%`` operator -described in the :ref:`typesseq-strings` section. +described in the :ref:`typesseq-strings` section. Also, see the +:mod:`re` module for string functions based on regular expressions. .. toctree:: From python-checkins at python.org Mon Aug 6 18:50:05 2007 From: python-checkins at python.org (georg.brandl) Date: Mon, 6 Aug 2007 18:50:05 +0200 (CEST) Subject: [Python-checkins] r56771 - in doctools/trunk: Doc-26/c-api/utilities.rst Doc-26/library/csv.rst Doc-26/library/functions.rst Doc-26/library/logging.rst Doc-26/library/ossaudiodev.rst Doc-26/library/pyclbr.rst Doc-26/library/stdtypes.rst Doc-26/library/string.rst Doc-26/library/strings.rst Doc-26/reference/datamodel.rst Doc-26/reference/expressions.rst Doc-26/tutorial/introduction.rst Doc-3k/c-api/utilities.rst Doc-3k/library/csv.rst Doc-3k/library/functions.rst Doc-3k/library/logging.rst Doc-3k/library/ossaudiodev.rst Doc-3k/library/pyclbr.rst Doc-3k/library/stdtypes.rst Doc-3k/library/string.rst Doc-3k/library/strings.rst Doc-3k/reference/datamodel.rst Doc-3k/reference/expressions.rst Doc-3k/tutorial/introduction.rst sphinx/highlighting.py Message-ID: <20070806165005.8C4811E4006@bag.python.org> Author: georg.brandl Date: Mon Aug 6 18:50:04 2007 New Revision: 56771 Modified: doctools/trunk/Doc-26/c-api/utilities.rst doctools/trunk/Doc-26/library/csv.rst doctools/trunk/Doc-26/library/functions.rst doctools/trunk/Doc-26/library/logging.rst doctools/trunk/Doc-26/library/ossaudiodev.rst doctools/trunk/Doc-26/library/pyclbr.rst doctools/trunk/Doc-26/library/stdtypes.rst doctools/trunk/Doc-26/library/string.rst doctools/trunk/Doc-26/library/strings.rst doctools/trunk/Doc-26/reference/datamodel.rst doctools/trunk/Doc-26/reference/expressions.rst doctools/trunk/Doc-26/tutorial/introduction.rst doctools/trunk/Doc-3k/c-api/utilities.rst doctools/trunk/Doc-3k/library/csv.rst doctools/trunk/Doc-3k/library/functions.rst doctools/trunk/Doc-3k/library/logging.rst doctools/trunk/Doc-3k/library/ossaudiodev.rst doctools/trunk/Doc-3k/library/pyclbr.rst doctools/trunk/Doc-3k/library/stdtypes.rst doctools/trunk/Doc-3k/library/string.rst doctools/trunk/Doc-3k/library/strings.rst doctools/trunk/Doc-3k/reference/datamodel.rst doctools/trunk/Doc-3k/reference/expressions.rst doctools/trunk/Doc-3k/tutorial/introduction.rst doctools/trunk/sphinx/highlighting.py Log: Make the "standard types" docs more standard. Add links from all constructors in "built-in functions" to stdtypes. Modified: doctools/trunk/Doc-26/c-api/utilities.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/utilities.rst (original) +++ doctools/trunk/Doc-26/c-api/utilities.rst Mon Aug 6 18:50:04 2007 @@ -929,7 +929,7 @@ set and *NULL* returned. -.. _string-formatting: +.. _string-conversion: String conversion and formatting ================================ Modified: doctools/trunk/Doc-26/library/csv.rst ============================================================================== --- doctools/trunk/Doc-26/library/csv.rst (original) +++ doctools/trunk/Doc-26/library/csv.rst Mon Aug 6 18:50:04 2007 @@ -334,7 +334,7 @@ :func:`reader` function) have the following public methods: -.. method:: csv reader.next() +.. method:: csvreader.next() Return the next row of the reader's iterable object as a list, parsed according to the current dialect. @@ -342,12 +342,12 @@ Reader objects have the following public attributes: -.. attribute:: csv reader.dialect +.. attribute:: csvreader.dialect A read-only description of the dialect in use by the parser. -.. attribute:: csv reader.line_num +.. attribute:: csvreader.line_num The number of lines read from the source iterator. This is not the same as the number of records returned, as records can span multiple lines. @@ -367,13 +367,13 @@ read CSV files (assuming they support complex numbers at all). -.. method:: csv writer.writerow(row) +.. method:: csvwriter.writerow(row) Write the *row* parameter to the writer's file object, formatted according to the current dialect. -.. method:: csv writer.writerows(rows) +.. method:: csvwriter.writerows(rows) Write all the *rows* parameters (a list of *row* objects as described above) to the writer's file object, formatted according to the current dialect. @@ -381,7 +381,7 @@ Writer objects have the following public attribute: -.. attribute:: csv writer.dialect +.. attribute:: csvwriter.dialect A read-only description of the dialect in use by the writer. Modified: doctools/trunk/Doc-26/library/functions.rst ============================================================================== --- doctools/trunk/Doc-26/library/functions.rst (original) +++ doctools/trunk/Doc-26/library/functions.rst Mon Aug 6 18:50:04 2007 @@ -232,6 +232,7 @@ the function serves as a numeric conversion function like :func:`int`, :func:`long` and :func:`float`. If both arguments are omitted, returns ``0j``. + The complex type is described in :ref:`typesnumeric`. .. function:: delattr(object, name) @@ -242,42 +243,10 @@ .. function:: dict([arg]) + :noindex: - Return a new dictionary initialized from an optional positional argument or from - a set of keyword arguments. If no arguments are given, return a new empty - dictionary. If the positional argument *arg* is a mapping object, return a - dictionary mapping the same keys to the same values as does the mapping object. - Otherwise the positional argument must be a sequence, a container that supports - iteration, or an iterator object. The elements of the argument must each also - be of one of those kinds, and each must in turn contain exactly two objects. - The first is used as a key in the new dictionary, and the second as the key's - value. If a given key is seen more than once, the last value associated with it - is retained in the new dictionary. - - If keyword arguments are given, the keywords themselves with their associated - values are added as items to the dictionary. If a key is specified both in the - positional argument and as a keyword argument, the value associated with the - keyword is retained in the dictionary. For example, these all return a - dictionary equal to ``{"one": 2, "two": 3}``: - - * ``dict({'one': 2, 'two': 3})`` - - * ``dict({'one': 2, 'two': 3}.items())`` - - * ``dict({'one': 2, 'two': 3}.iteritems())`` - - * ``dict(zip(('one', 'two'), (2, 3)))`` - - * ``dict([['two', 3], ['one', 2]])`` - - * ``dict(one=2, two=3)`` - - * ``dict([(['one', 'two'][i-2], i) for i in (2, 3)])`` - - .. versionadded:: 2.2 - - .. versionchanged:: 2.3 - Support for building a dictionary from keyword arguments added. + Create a new dictionary. The dictionary type is described in + :ref:`typesmapping`. .. function:: dir([object]) @@ -477,6 +446,7 @@ these values to be returned depends entirely on the C library and is known to vary. + The float type is described in :ref:`typesnumeric`. .. function:: frozenset([iterable]) @@ -487,6 +457,8 @@ :class:`frozenset` objects. If *iterable* is not specified, returns a new empty set, ``frozenset([])``. + The frozenset type is described in :ref:`types-set`. + .. versionadded:: 2.4 @@ -583,6 +555,8 @@ the integer range a long object will be returned instead. If no arguments are given, returns ``0``. + The integer type is described in :ref:`typesnumeric`. + .. function:: isinstance(object, classinfo) @@ -642,6 +616,8 @@ returns ``['a', 'b', 'c']`` and ``list( (1, 2, 3) )`` returns ``[1, 2, 3]``. If no argument is given, returns a new empty list, ``[]``. + :class:`list` is a mutable sequence type, as documented in :ref:`typesseq`. + .. function:: locals() @@ -667,6 +643,7 @@ with the same value is returned. Conversion of floating point numbers to integers truncates (towards zero). If no arguments are given, returns ``0L``. + The long type is described in :ref:`typesnumeric`. .. function:: map(function, iterable, ...) @@ -1011,6 +988,8 @@ :class:`frozenset` objects. If *iterable* is not specified, returns a new empty set, ``set([])``. + The set type is described in :ref:`types-set`. + .. versionadded:: 2.4 @@ -1101,13 +1080,12 @@ acceptable to :func:`eval`; its goal is to return a printable string. If no argument is given, returns the empty string, ``''``. - For more information on strings see :ref:`typesseq` which describes - sequence functionality (strings are sequences), and also the - string-specific methods described in the :ref:`string-methods` - section. To output formatted strings use template strings or the - ``%`` operator described in the :ref:`typesseq-strings` section. In - addition see the :ref:`stringservices` section. See also - :func:`unicode`. + For more information on strings see :ref:`typesseq` which describes sequence + functionality (strings are sequences), and also the string-specific methods + described in the :ref:`string-methods` section. To output formatted strings + use template strings or the ``%`` operator described in the + :ref:`string-formatting` section. In addition see the :ref:`stringservices` + section. See also :func:`unicode`. .. function:: sum(iterable[, start]) @@ -1152,6 +1130,7 @@ 3])`` returns ``(1, 2, 3)``. If no argument is given, returns a new empty tuple, ``()``. + :class:`tuple` is a mutable sequence type, as documented in :ref:`typesseq`. .. function:: type(object) @@ -1222,11 +1201,10 @@ For more information on Unicode strings see :ref:`typesseq` which describes sequence functionality (Unicode strings are sequences), and also the - string-specific methods described in the :ref:`string-methods` - section. To output formatted strings use template strings or the - ``%`` operator described in the :ref:`typesseq-strings` section. In - addition see the :ref:`stringservices` section. See also - :func:`str`. + string-specific methods described in the :ref:`string-methods` section. To + output formatted strings use template strings or the ``%`` operator described + in the :ref:`string-formatting` section. In addition see the + :ref:`stringservices` section. See also :func:`str`. .. versionadded:: 2.0 Modified: doctools/trunk/Doc-26/library/logging.rst ============================================================================== --- doctools/trunk/Doc-26/library/logging.rst (original) +++ doctools/trunk/Doc-26/library/logging.rst Mon Aug 6 18:50:04 2007 @@ -612,7 +612,7 @@ rather than the console. Formatting uses standard Python string formatting - see section -:ref:`typesseq-strings`. The format string takes the following common +:ref:`string-formatting`. The format string takes the following common specifiers. For a complete list of specifiers, consult the :class:`Formatter` documentation. @@ -1483,7 +1483,7 @@ of the :class:`LogRecord` attributes - such as the default value mentioned above making use of the fact that the user's message and arguments are pre-formatted into a :class:`LogRecord`'s *message* attribute. This format string contains -standard python %-style mapping keys. See section :ref:`typesseq-strings` +standard python %-style mapping keys. See section :ref:`string-formatting` for more information on string formatting. Currently, the useful mapping keys in a :class:`LogRecord` are: Modified: doctools/trunk/Doc-26/library/ossaudiodev.rst ============================================================================== --- doctools/trunk/Doc-26/library/ossaudiodev.rst (original) +++ doctools/trunk/Doc-26/library/ossaudiodev.rst Mon Aug 6 18:50:04 2007 @@ -124,19 +124,19 @@ and (read-only) attributes: -.. method:: audio device.close() +.. method:: oss_audio_device.close() Explicitly close the audio device. When you are done writing to or reading from an audio device, you should explicitly close it. A closed device cannot be used again. -.. method:: audio device.fileno() +.. method:: oss_audio_device.fileno() Return the file descriptor associated with the device. -.. method:: audio device.read(size) +.. method:: oss_audio_device.read(size) Read *size* bytes from the audio input and return them as a Python string. Unlike most Unix device drivers, OSS audio devices in blocking mode (the @@ -144,7 +144,7 @@ available. -.. method:: audio device.write(data) +.. method:: oss_audio_device.write(data) Write the Python string *data* to the audio device and return the number of bytes written. If the audio device is in blocking mode (the default), the @@ -153,7 +153,7 @@ ---see :meth:`writeall`. -.. method:: audio device.writeall(data) +.. method:: oss_audio_device.writeall(data) Write the entire Python string *data* to the audio device: waits until the audio device is able to accept data, writes as much data as it will accept, and @@ -169,13 +169,13 @@ :func:`ioctl` fails, they all raise :exc:`IOError`. -.. method:: audio device.nonblock() +.. method:: oss_audio_device.nonblock() Put the device into non-blocking mode. Once in non-blocking mode, there is no way to return it to blocking mode. -.. method:: audio device.getfmts() +.. method:: oss_audio_device.getfmts() Return a bitmask of the audio output formats supported by the soundcard. Some of the formats supported by OSS are: @@ -212,7 +212,7 @@ :const:`AFMT_S16_LE`. -.. method:: audio device.setfmt(format) +.. method:: oss_audio_device.setfmt(format) Try to set the current audio format to *format*---see :meth:`getfmts` for a list. Returns the audio format that the device was set to, which may not be the @@ -220,7 +220,7 @@ by passing an "audio format" of :const:`AFMT_QUERY`. -.. method:: audio device.channels(nchannels) +.. method:: oss_audio_device.channels(nchannels) Set the number of output channels to *nchannels*. A value of 1 indicates monophonic sound, 2 stereophonic. Some devices may have more than 2 channels, @@ -228,7 +228,7 @@ the device was set to. -.. method:: audio device.speed(samplerate) +.. method:: oss_audio_device.speed(samplerate) Try to set the audio sampling rate to *samplerate* samples per second. Returns the rate actually set. Most sound devices don't support arbitrary sampling @@ -250,21 +250,21 @@ +-------+-------------------------------------------+ -.. method:: audio device.sync() +.. method:: oss_audio_device.sync() Wait until the sound device has played every byte in its buffer. (This happens implicitly when the device is closed.) The OSS documentation recommends closing and re-opening the device rather than using :meth:`sync`. -.. method:: audio device.reset() +.. method:: oss_audio_device.reset() Immediately stop playing or recording and return the device to a state where it can accept commands. The OSS documentation recommends closing and re-opening the device after calling :meth:`reset`. -.. method:: audio device.post() +.. method:: oss_audio_device.post() Tell the driver that there is likely to be a pause in the output, making it possible for the device to handle the pause more intelligently. You might use @@ -275,7 +275,7 @@ simple calculations. -.. method:: audio device.setparameters(format, nchannels, samplerate [, strict=False]) +.. method:: oss_audio_device.setparameters(format, nchannels, samplerate [, strict=False]) Set the key audio sampling parameters---sample format, number of channels, and sampling rate---in one method call. *format*, *nchannels*, and *samplerate* @@ -298,17 +298,17 @@ rate = dsp.rate(channels) -.. method:: audio device.bufsize() +.. method:: oss_audio_device.bufsize() Returns the size of the hardware buffer, in samples. -.. method:: audio device.obufcount() +.. method:: oss_audio_device.obufcount() Returns the number of samples that are in the hardware buffer yet to be played. -.. method:: audio device.obuffree() +.. method:: oss_audio_device.obuffree() Returns the number of samples that could be queued into the hardware buffer to be played without blocking. @@ -316,17 +316,17 @@ Audio device objects also support several read-only attributes: -.. attribute:: audio device.closed +.. attribute:: oss_audio_device.closed Boolean indicating whether the device has been closed. -.. attribute:: audio device.name +.. attribute:: oss_audio_device.name String containing the name of the device file. -.. attribute:: audio device.mode +.. attribute:: oss_audio_device.mode The I/O mode for the file, either ``"r"``, ``"rw"``, or ``"w"``. @@ -339,20 +339,20 @@ The mixer object provides two file-like methods: -.. method:: mixer device.close() +.. method:: oss_mixer_device.close() This method closes the open mixer device file. Any further attempts to use the mixer after this file is closed will raise an :exc:`IOError`. -.. method:: mixer device.fileno() +.. method:: oss_mixer_device.fileno() Returns the file handle number of the open mixer device file. The remaining methods are specific to audio mixing: -.. method:: mixer device.controls() +.. method:: oss_mixer_device.controls() This method returns a bitmask specifying the available mixer controls ("Control" being a specific mixable "channel", such as :const:`SOUND_MIXER_PCM` or @@ -372,7 +372,7 @@ Ultrasound, for example, :const:`SOUND_MIXER_VOLUME` does not exist. -.. method:: mixer device.stereocontrols() +.. method:: oss_mixer_device.stereocontrols() Returns a bitmask indicating stereo mixer controls. If a bit is set, the corresponding control is stereo; if it is unset, the control is either @@ -383,13 +383,13 @@ data from a bitmask. -.. method:: mixer device.reccontrols() +.. method:: oss_mixer_device.reccontrols() Returns a bitmask specifying the mixer controls that may be used to record. See the code example for :meth:`controls` for an example of reading from a bitmask. -.. method:: mixer device.get(control) +.. method:: oss_mixer_device.get(control) Returns the volume of a given mixer control. The returned volume is a 2-tuple ``(left_volume,right_volume)``. Volumes are specified as numbers from 0 @@ -400,7 +400,7 @@ :exc:`IOError` if an unsupported control is specified. -.. method:: mixer device.set(control, (left, right)) +.. method:: oss_mixer_device.set(control, (left, right)) Sets the volume for a given mixer control to ``(left,right)``. ``left`` and ``right`` must be ints and between 0 (silent) and 100 (full volume). On @@ -412,13 +412,13 @@ specified volumes were out-of-range. -.. method:: mixer device.get_recsrc() +.. method:: oss_mixer_device.get_recsrc() This method returns a bitmask indicating which control(s) are currently being used as a recording source. -.. method:: mixer device.set_recsrc(bitmask) +.. method:: oss_mixer_device.set_recsrc(bitmask) Call this function to specify a recording source. Returns a bitmask indicating the new recording source (or sources) if successful; raises :exc:`IOError` if an Modified: doctools/trunk/Doc-26/library/pyclbr.rst ============================================================================== --- doctools/trunk/Doc-26/library/pyclbr.rst (original) +++ doctools/trunk/Doc-26/library/pyclbr.rst Mon Aug 6 18:50:04 2007 @@ -47,17 +47,17 @@ :func:`readmodule` and :func:`readmodule_ex` provide the following data members: -.. attribute:: class descriptor.module +.. attribute:: class_descriptor.module The name of the module defining the class described by the class descriptor. -.. attribute:: class descriptor.name +.. attribute:: class_descriptor.name The name of the class. -.. attribute:: class descriptor.super +.. attribute:: class_descriptor.super A list of class descriptors which describe the immediate base classes of the class being described. Classes which are named as superclasses but which are @@ -65,17 +65,17 @@ name instead of class descriptors. -.. attribute:: class descriptor.methods +.. attribute:: class_descriptor.methods A dictionary mapping method names to line numbers. -.. attribute:: class descriptor.file +.. attribute:: class_descriptor.file Name of the file containing the ``class`` statement defining the class. -.. attribute:: class descriptor.lineno +.. attribute:: class_descriptor.lineno The line number of the ``class`` statement within the file named by :attr:`file`. @@ -90,23 +90,23 @@ :func:`readmodule_ex` provide the following data members: -.. attribute:: function descriptor.module +.. attribute:: function_descriptor.module The name of the module defining the function described by the function descriptor. -.. attribute:: function descriptor.name +.. attribute:: function_descriptor.name The name of the function. -.. attribute:: function descriptor.file +.. attribute:: function_descriptor.file Name of the file containing the ``def`` statement defining the function. -.. attribute:: function descriptor.lineno +.. attribute:: function_descriptor.lineno The line number of the ``def`` statement within the file named by :attr:`file`. Modified: doctools/trunk/Doc-26/library/stdtypes.rst ============================================================================== --- doctools/trunk/Doc-26/library/stdtypes.rst (original) +++ doctools/trunk/Doc-26/library/stdtypes.rst Mon Aug 6 18:50:04 2007 @@ -1,3 +1,5 @@ +.. XXX: reference/datamodel and this have quite a few overlaps! + .. _bltin-types: @@ -497,6 +499,8 @@ object: Unicode object: tuple object: list + object: buffer + object: xrange String literals are written in single or double quotes: ``'xyzzy'``, ``"frobozz"``. See :ref:`strings` for more about string literals. Unicode @@ -508,18 +512,10 @@ ``a, b, c`` or ``()``. A single item tuple must have a trailing comma, such as ``(d,)``. -.. index:: - builtin: buffer - object: buffer - Buffer objects are not directly supported by Python syntax, but can be created by calling the builtin function :func:`buffer`. They don't support concatenation or repetition. -.. index:: - builtin: xrange - object: xrange - Xrange objects are similar to buffers in that there is no specific syntax to create them, but they are created using the :func:`xrange` function. They don't support slicing, concatenation or repetition, and using ``in``, ``not in``, @@ -657,12 +653,11 @@ .. index:: pair: string; methods -Below are listed the string methods which both 8-bit strings and Unicode -objects support. In addition, Python's strings support the -sequence type methods described in the -:ref:`typesseq` section (above). To output formatted strings use -template strings or the ``%`` operator described in the -:ref:`typesseq-strings` section (below). Also, see the :mod:`re` module for +Below are listed the string methods which both 8-bit strings and Unicode objects +support. In addition, Python's strings support the sequence type methods +described in the :ref:`typesseq` section (above). To output formatted strings +use template strings or the ``%`` operator described in the +:ref:`string-formatting` section (below). Also, see the :mod:`re` module for string functions based on regular expressions. .. method:: str.capitalize() @@ -1038,7 +1033,7 @@ .. versionadded:: 2.2.2 -.. _typesseq-strings: +.. _string-formatting: String Formatting Operations ---------------------------- @@ -1105,86 +1100,72 @@ The conversion flag characters are: -+---------+-----------------------------------------------+ -| Flag | Meaning | -+=========+===============================================+ -| ``'#'`` | The value conversion will use the "alternate | -| | form" (where defined below). | -+---------+-----------------------------------------------+ -| ``'0'`` | The conversion will be zero padded for | -| | numeric values. | -+---------+-----------------------------------------------+ -| ``'-'`` | The converted value is left adjusted | -| | (overrides the ``'0'`` conversion if both are | -| | given). | -+---------+-----------------------------------------------+ -| ``' '`` | (a space) A blank should be left before a | -| | positive number (or empty string) produced by | -| | a signed conversion. | -+---------+-----------------------------------------------+ -| ``'+'`` | A sign character (``'+'`` or ``'-'``) will | -| | precede the conversion (overrides a "space" | -| | flag). | -+---------+-----------------------------------------------+ ++---------+---------------------------------------------------------------------+ +| Flag | Meaning | ++=========+=====================================================================+ +| ``'#'`` | The value conversion will use the "alternate form" (where defined | +| | below). | ++---------+---------------------------------------------------------------------+ +| ``'0'`` | The conversion will be zero padded for numeric values. | ++---------+---------------------------------------------------------------------+ +| ``'-'`` | The converted value is left adjusted (overrides the ``'0'`` | +| | conversion if both are given). | ++---------+---------------------------------------------------------------------+ +| ``' '`` | (a space) A blank should be left before a positive number (or empty | +| | string) produced by a signed conversion. | ++---------+---------------------------------------------------------------------+ +| ``'+'`` | A sign character (``'+'`` or ``'-'``) will precede the conversion | +| | (overrides a "space" flag). | ++---------+---------------------------------------------------------------------+ A length modifier (``h``, ``l``, or ``L``) may be present, but is ignored as it is not necessary for Python. The conversion types are: -+------------+---------------------------------+-------+ -| Conversion | Meaning | Notes | -+============+=================================+=======+ -| ``'d'`` | Signed integer decimal. | | -+------------+---------------------------------+-------+ -| ``'i'`` | Signed integer decimal. | | -+------------+---------------------------------+-------+ -| ``'o'`` | Unsigned octal. | \(1) | -+------------+---------------------------------+-------+ -| ``'u'`` | Unsigned decimal. | | -+------------+---------------------------------+-------+ -| ``'x'`` | Unsigned hexadecimal | \(2) | -| | (lowercase). | | -+------------+---------------------------------+-------+ -| ``'X'`` | Unsigned hexadecimal | \(2) | -| | (uppercase). | | -+------------+---------------------------------+-------+ -| ``'e'`` | Floating point exponential | \(3) | -| | format (lowercase). | | -+------------+---------------------------------+-------+ -| ``'E'`` | Floating point exponential | \(3) | -| | format (uppercase). | | -+------------+---------------------------------+-------+ -| ``'f'`` | Floating point decimal format. | \(3) | -+------------+---------------------------------+-------+ -| ``'F'`` | Floating point decimal format. | \(3) | -+------------+---------------------------------+-------+ -| ``'g'`` | Floating point format. Uses | \(4) | -| | exponential format if exponent | | -| | is greater than -4 or less than | | -| | precision, decimal format | | -| | otherwise. | | -+------------+---------------------------------+-------+ -| ``'G'`` | Floating point format. Uses | \(4) | -| | exponential format if exponent | | -| | is greater than -4 or less than | | -| | precision, decimal format | | -| | otherwise. | | -+------------+---------------------------------+-------+ -| ``'c'`` | Single character (accepts | | -| | integer or single character | | -| | string). | | -+------------+---------------------------------+-------+ -| ``'r'`` | String (converts any python | \(5) | -| | object using :func:`repr`). | | -+------------+---------------------------------+-------+ -| ``'s'`` | String (converts any python | \(6) | -| | object using :func:`str`). | | -+------------+---------------------------------+-------+ -| ``'%'`` | No argument is converted, | | -| | results in a ``'%'`` character | | -| | in the result. | | -+------------+---------------------------------+-------+ ++------------+-----------------------------------------------------+-------+ +| Conversion | Meaning | Notes | ++============+=====================================================+=======+ +| ``'d'`` | Signed integer decimal. | | ++------------+-----------------------------------------------------+-------+ +| ``'i'`` | Signed integer decimal. | | ++------------+-----------------------------------------------------+-------+ +| ``'o'`` | Unsigned octal. | \(1) | ++------------+-----------------------------------------------------+-------+ +| ``'u'`` | Unsigned decimal. | | ++------------+-----------------------------------------------------+-------+ +| ``'x'`` | Unsigned hexadecimal (lowercase). | \(2) | ++------------+-----------------------------------------------------+-------+ +| ``'X'`` | Unsigned hexadecimal (uppercase). | \(2) | ++------------+-----------------------------------------------------+-------+ +| ``'e'`` | Floating point exponential format (lowercase). | \(3) | ++------------+-----------------------------------------------------+-------+ +| ``'E'`` | Floating point exponential format (uppercase). | \(3) | ++------------+-----------------------------------------------------+-------+ +| ``'f'`` | Floating point decimal format. | \(3) | ++------------+-----------------------------------------------------+-------+ +| ``'F'`` | Floating point decimal format. | \(3) | ++------------+-----------------------------------------------------+-------+ +| ``'g'`` | Floating point format. Uses exponential format if | \(4) | +| | exponent is greater than -4 or less than precision, | | +| | decimal format otherwise. | | ++------------+-----------------------------------------------------+-------+ +| ``'G'`` | Floating point format. Uses exponential format if | \(4) | +| | exponent is greater than -4 or less than precision, | | +| | decimal format otherwise. | | ++------------+-----------------------------------------------------+-------+ +| ``'c'`` | Single character (accepts integer or single | | +| | character string). | | ++------------+-----------------------------------------------------+-------+ +| ``'r'`` | String (converts any python object using | \(5) | +| | :func:`repr`). | | ++------------+-----------------------------------------------------+-------+ +| ``'s'`` | String (converts any python object using | \(6) | +| | :func:`str`). | | ++------------+-----------------------------------------------------+-------+ +| ``'%'`` | No argument is converted, results in a ``'%'`` | | +| | character in the result. | | ++------------+-----------------------------------------------------+-------+ Notes: @@ -1444,37 +1425,52 @@ Instances of :class:`set` and :class:`frozenset` provide the following operations: -+-------------------------------+------------+---------------------------------+ -| Operation | Equivalent | Result | -+===============================+============+=================================+ -| ``len(s)`` | | cardinality of set *s* | -+-------------------------------+------------+---------------------------------+ -| ``x in s`` | | test *x* for membership in *s* | -+-------------------------------+------------+---------------------------------+ -| ``x not in s`` | | test *x* for non-membership in | -| | | *s* | -+-------------------------------+------------+---------------------------------+ -| ``s.issubset(t)`` | ``s <= t`` | test whether every element in | -| | | *s* is in *t* | -+-------------------------------+------------+---------------------------------+ -| ``s.issuperset(t)`` | ``s >= t`` | test whether every element in | -| | | *t* is in *s* | -+-------------------------------+------------+---------------------------------+ -| ``s.union(t)`` | *s* \| *t* | new set with elements from both | -| | | *s* and *t* | -+-------------------------------+------------+---------------------------------+ -| ``s.intersection(t)`` | *s* & *t* | new set with elements common to | -| | | *s* and *t* | -+-------------------------------+------------+---------------------------------+ -| ``s.difference(t)`` | *s* - *t* | new set with elements in *s* | -| | | but not in *t* | -+-------------------------------+------------+---------------------------------+ -| ``s.symmetric_difference(t)`` | *s* ^ *t* | new set with elements in either | -| | | *s* or *t* but not both | -+-------------------------------+------------+---------------------------------+ -| ``s.copy()`` | | new set with a shallow copy of | -| | | *s* | -+-------------------------------+------------+---------------------------------+ +.. describe:: len(s) + + Return the cardinality of set *s*. + +.. describe:: x in s + + Test *x* for membership in *s*. + +.. describe:: x not in s + + Test *x* for non-membership in *s*. + +.. method:: set.issubset(other) + set <= other + + Test whether every element in the set is in *other*. + +.. method:: set.issuperset(other) + set >= other + + Test whether every element in *other* is in the set. + +.. method:: set.union(other) + set | other + + Return a new set with elements from both sets. + +.. method:: set.intersection(other) + set & other + + Return a new set with elements common to both sets. + +.. method:: set.difference(other) + set - other + + Return a new set with elements in the set that are not in *other*. + +.. method:: set.symmetric_difference(other) + set ^ other + + Return a new set with elements in either the set or *other* but not both. + +.. method:: set.copy() + + Return a new set with a shallow copy of *s*. + Note, the non-operator versions of :meth:`union`, :meth:`intersection`, :meth:`difference`, and :meth:`symmetric_difference`, :meth:`issubset`, and @@ -1512,46 +1508,56 @@ The following table lists operations available for :class:`set` that do not apply to immutable instances of :class:`frozenset`: -+--------------------------------------+-------------+---------------------------------+ -| Operation | Equivalent | Result | -+======================================+=============+=================================+ -| ``s.update(t)`` | *s* \|= *t* | update set *s*, adding elements | -| | | from *t* | -+--------------------------------------+-------------+---------------------------------+ -| ``s.intersection_update(t)`` | *s* &= *t* | update set *s*, keeping only | -| | | elements found in both *s* and | -| | | *t* | -+--------------------------------------+-------------+---------------------------------+ -| ``s.difference_update(t)`` | *s* -= *t* | update set *s*, removing | -| | | elements found in *t* | -+--------------------------------------+-------------+---------------------------------+ -| ``s.symmetric_difference_update(t)`` | *s* ^= *t* | update set *s*, keeping only | -| | | elements found in either *s* or | -| | | *t* but not in both | -+--------------------------------------+-------------+---------------------------------+ -| ``s.add(x)`` | | add element *x* to set *s* | -+--------------------------------------+-------------+---------------------------------+ -| ``s.remove(x)`` | | remove *x* from set *s*; raises | -| | | :exc:`KeyError` if not present | -+--------------------------------------+-------------+---------------------------------+ -| ``s.discard(x)`` | | removes *x* from set *s* if | -| | | present | -+--------------------------------------+-------------+---------------------------------+ -| ``s.pop()`` | | remove and return an arbitrary | -| | | element from *s*; raises | -| | | :exc:`KeyError` if empty | -+--------------------------------------+-------------+---------------------------------+ -| ``s.clear()`` | | remove all elements from set | -| | | *s* | -+--------------------------------------+-------------+---------------------------------+ +.. method:: set.update(other) + set |= other + + Update the set, adding elements from *other*. + +.. method:: set.intersection_update(other) + set &= other + + Update the set, keeping only elements found in it and *other*. + +.. method:: set.difference_update(other) + set -= other + + Update the set, removing elements found in *other*. + +.. method:: set.symmetric_difference_update(other) + set ^= other + + Update the set, keeping only elements found in either set, but not in both. + +.. method:: set.add(el) + + Add element *el* to the set. + +.. method:: set.remove(el) + + Remove element *el* from the set. Raises :exc:`KeyError` if *el* is not + contained in the set. + +.. method:: set.discard(el) + + Remove element *el* from the set if it is present. + +.. method:: set.pop() + + Remove and return an arbitrary element from the set. Raises :exc:`KeyError` + if the set is empty. + +.. method:: set.clear() + + Remove all elements from the set. + Note, the non-operator versions of the :meth:`update`, :meth:`intersection_update`, :meth:`difference_update`, and :meth:`symmetric_difference_update` methods will accept any iterable as an argument. -The design of the set types was based on lessons learned from the :mod:`sets` -module. +The design of the set types was based on lessons learned from the Python +implementation found in the :mod:`sets` module. .. seealso:: @@ -1568,173 +1574,216 @@ .. index:: object: mapping object: dictionary + triple: operations on; mapping; types + triple: operations on; dictionary; type + statement: del + builtin: len -A :dfn:`mapping` object maps immutable values to arbitrary objects. Mappings +A :dfn:`mapping` object maps immutable values to arbitrary objects. Mappings are mutable objects. There is currently only one standard mapping type, the -:dfn:`dictionary`. A dictionary's keys are almost arbitrary values. Only +:dfn:`dictionary`. A dictionary's keys are *almost* arbitrary values. Only values containing lists, dictionaries or other mutable types (that are compared by value rather than by object identity) may not be used as keys. Numeric types used for keys obey the normal rules for numeric comparison: if two numbers compare equal (such as ``1`` and ``1.0``) then they can be used interchangeably to index the same dictionary entry. -Dictionaries are created by placing a comma-separated list of ``key: value`` +Dictionaries can be created by placing a comma-separated list of ``key: value`` pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098: -'jack', 4127: 'sjoerd'}``. +'jack', 4127: 'sjoerd'}``, or by the :class:`dict` constructor. -.. index:: - triple: operations on; mapping; types - triple: operations on; dictionary; type - statement: del - builtin: len - single: clear() (dictionary method) - single: copy() (dictionary method) - single: has_key() (dictionary method) - single: fromkeys() (dictionary method) - single: items() (dictionary method) - single: keys() (dictionary method) - single: update() (dictionary method) - single: values() (dictionary method) - single: get() (dictionary method) - single: setdefault() (dictionary method) - single: pop() (dictionary method) - single: popitem() (dictionary method) - single: iteritems() (dictionary method) - single: iterkeys() (dictionary method) - single: itervalues() (dictionary method) - -The following operations are defined on mappings (where *a* and *b* are -mappings, *k* is a key, and *v* and *x* are arbitrary objects): - -+--------------------------------+---------------------------------+-----------+ -| Operation | Result | Notes | -+================================+=================================+===========+ -| ``len(a)`` | the number of items in *a* | | -+--------------------------------+---------------------------------+-----------+ -| ``a[k]`` | the item of *a* with key *k* | (1), (10) | -+--------------------------------+---------------------------------+-----------+ -| ``a[k] = v`` | set ``a[k]`` to *v* | | -+--------------------------------+---------------------------------+-----------+ -| ``del a[k]`` | remove ``a[k]`` from *a* | \(1) | -+--------------------------------+---------------------------------+-----------+ -| ``a.clear()`` | remove all items from ``a`` | | -+--------------------------------+---------------------------------+-----------+ -| ``a.copy()`` | a (shallow) copy of ``a`` | | -+--------------------------------+---------------------------------+-----------+ -| ``k in a`` | ``True`` if *a* has a key *k*, | \(2) | -| | else ``False`` | | -+--------------------------------+---------------------------------+-----------+ -| ``k not in a`` | Equivalent to ``not`` *k* in | \(2) | -| | *a* | | -+--------------------------------+---------------------------------+-----------+ -| ``a.has_key(k)`` | Equivalent to *k* ``in`` *a*, | | -| | use that form in new code | | -+--------------------------------+---------------------------------+-----------+ -| ``a.items()`` | a copy of *a*'s list of (*key*, | \(3) | -| | *value*) pairs | | -+--------------------------------+---------------------------------+-----------+ -| ``a.keys()`` | a copy of *a*'s list of keys | \(3) | -+--------------------------------+---------------------------------+-----------+ -| ``a.update([b])`` | updates *a* with key/value | \(9) | -| | pairs from *b*, overwriting | | -| | existing keys, returns ``None`` | | -+--------------------------------+---------------------------------+-----------+ -| ``a.fromkeys(seq[, value])`` | Creates a new dictionary with | \(7) | -| | keys from *seq* and values set | | -| | to *value* | | -+--------------------------------+---------------------------------+-----------+ -| ``a.values()`` | a copy of *a*'s list of values | \(3) | -+--------------------------------+---------------------------------+-----------+ -| ``a.get(k[, x])`` | ``a[k]`` if ``k in a``, else | \(4) | -| | *x* | | -+--------------------------------+---------------------------------+-----------+ -| ``a.setdefault(k[, x])`` | ``a[k]`` if ``k in a``, else | \(5) | -| | *x* (also setting it) | | -+--------------------------------+---------------------------------+-----------+ -| ``a.pop(k[, x])`` | ``a[k]`` if ``k in a``, else | \(8) | -| | *x* (and remove k) | | -+--------------------------------+---------------------------------+-----------+ -| ``a.popitem()`` | remove and return an arbitrary | \(6) | -| | (*key*, *value*) pair | | -+--------------------------------+---------------------------------+-----------+ -| ``a.iteritems()`` | return an iterator over (*key*, | (2), (3) | -| | *value*) pairs | | -+--------------------------------+---------------------------------+-----------+ -| ``a.iterkeys()`` | return an iterator over the | (2), (3) | -| | mapping's keys | | -+--------------------------------+---------------------------------+-----------+ -| ``a.itervalues()`` | return an iterator over the | (2), (3) | -| | mapping's values | | -+--------------------------------+---------------------------------+-----------+ +.. class:: dict([arg]) -Notes: + Return a new dictionary initialized from an optional positional argument or from + a set of keyword arguments. If no arguments are given, return a new empty + dictionary. If the positional argument *arg* is a mapping object, return a + dictionary mapping the same keys to the same values as does the mapping object. + Otherwise the positional argument must be a sequence, a container that supports + iteration, or an iterator object. The elements of the argument must each also + be of one of those kinds, and each must in turn contain exactly two objects. + The first is used as a key in the new dictionary, and the second as the key's + value. If a given key is seen more than once, the last value associated with it + is retained in the new dictionary. -(1) - Raises a :exc:`KeyError` exception if *k* is not in the map. + If keyword arguments are given, the keywords themselves with their associated + values are added as items to the dictionary. If a key is specified both in the + positional argument and as a keyword argument, the value associated with the + keyword is retained in the dictionary. For example, these all return a + dictionary equal to ``{"one": 2, "two": 3}``: + + * ``dict({'one': 2, 'two': 3})`` + + * ``dict({'one': 2, 'two': 3}.items())`` + + * ``dict({'one': 2, 'two': 3}.iteritems())`` + + * ``dict(zip(('one', 'two'), (2, 3)))`` + + * ``dict([['two', 3], ['one', 2]])`` + + * ``dict(one=2, two=3)`` + + * ``dict([(['one', 'two'][i-2], i) for i in (2, 3)])`` -(2) .. versionadded:: 2.2 -(3) - Keys and values are listed in an arbitrary order which is non-random, varies - across Python implementations, and depends on the dictionary's history of - insertions and deletions. If :meth:`items`, :meth:`keys`, :meth:`values`, - :meth:`iteritems`, :meth:`iterkeys`, and :meth:`itervalues` are called with no - intervening modifications to the dictionary, the lists will directly correspond. - This allows the creation of ``(value, key)`` pairs using :func:`zip`: ``pairs = - zip(a.values(), a.keys())``. The same relationship holds for the - :meth:`iterkeys` and :meth:`itervalues` methods: ``pairs = zip(a.itervalues(), - a.iterkeys())`` provides the same value for ``pairs``. Another way to create the - same list is ``pairs = [(v, k) for (k, v) in a.iteritems()]``. + .. versionchanged:: 2.3 + Support for building a dictionary from keyword arguments added. -(4) - Never raises an exception if *k* is not in the map, instead it returns *x*. *x* - is optional; when *x* is not provided and *k* is not in the map, ``None`` is - returned. -(5) - :func:`setdefault` is like :func:`get`, except that if *k* is missing, *x* is - both returned and inserted into the dictionary as the value of *k*. *x* defaults - to ``None``. +These are the operations that dictionaries support (and therefore, custom mapping +types should support too): -(6) - :func:`popitem` is useful to destructively iterate over a dictionary, as often - used in set algorithms. If the dictionary is empty, calling :func:`popitem` - raises a :exc:`KeyError`. +.. describe:: len(d) + + Return the number of items in the dictionary *d*. + +.. describe:: d[key] + + Return the item of *d* with key *key*. Raises a :exc:`KeyError` if *key* is + not in the map. + + .. versionadded:: 2.5 + If a subclass of dict defines a method :meth:`__missing__`, if the key + *key* is not present, the ``d[key]`` operation calls that method with the + key *key* as argument. The ``d[key]`` operation then returns or raises + whatever is returned or raised by the ``__missing__(key)`` call if the key + is not present. No other operations or methods invoke + :meth:`__missing__`. If :meth:`__missing__` is not defined, + :exc:`KeyError` is raised. :meth:`__missing__` must be a method; it + cannot be an instance variable. For an example, see + :class:`collections.defaultdict`. + +.. describe:: d[key] = value + + Set ``d[key]`` to *value*. + +.. describe:: del d[key] + + Remove ``d[key]`` from *d*. Raises a :exc:`KeyError` if *key* is not in the + map. + +.. describe:: key in d + + Return ``True`` if *d* has a key *key*, else ``False``. + + .. versionadded:: 2.2 + +.. describe:: key not in d + + Equivalent to ``not key in d``. + + .. versionadded:: 2.2 + +.. method:: dict.clear() + + Remove all items from the dictionary. + +.. method:: dict.copy() + + Return a shallow copy of the dictionary. + +.. method:: dict.fromkeys(seq[, value]) + + Create a new dictionary with keys from *seq* and values set to *value*. -(7) :func:`fromkeys` is a class method that returns a new dictionary. *value* defaults to ``None``. .. versionadded:: 2.3 -(8) - :func:`pop` raises a :exc:`KeyError` when no default value is given and the key - is not found. +.. method:: dict.get(key[, default]) + + Return the value for *key* if *key* is in the dictionary, else *default*. If + *default* is not given, it defaults to ``None``, so that this method never + raises a :exc:`KeyError`. + +.. method:: dict.has_key(key) + + ``d.has_key(key)`` is equivalent to ``key in d``, but deprecated. + +.. method:: dict.items() + + Return a copy of the dictionary's list of ``(key, value)`` pairs. + + .. note:: + + Keys and values are listed in an arbitrary order which is non-random, varies + across Python implementations, and depends on the dictionary's history of + insertions and deletions. If :meth:`items`, :meth:`keys`, :meth:`values`, + :meth:`iteritems`, :meth:`iterkeys`, and :meth:`itervalues` are called with no + intervening modifications to the dictionary, the lists will directly correspond. + This allows the creation of ``(value, key)`` pairs using :func:`zip`: ``pairs = + zip(d.values(), d.keys())``. The same relationship holds for the + :meth:`iterkeys` and :meth:`itervalues` methods: ``pairs = zip(d.itervalues(), + d.iterkeys())`` provides the same value for ``pairs``. Another way to create the + same list is ``pairs = [(v, k) for (k, v) in d.iteritems()]``. + +.. method:: dict.iteritems() + + Return an iterator over the dictionary's ``(key, value)`` pairs. + See the note for :meth:`dict.items`. + + .. versionadded:: 2.2 + +.. method:: dict.iterkeys() + + Return an iterator over the dictionary's keys. See the note for + :meth:`dict.items`. + + .. versionadded:: 2.2 + +.. method:: dict.itervalues() + + Return an iterator over the dictionary's values. See the note for + :meth:`dict.items`. + + .. versionadded:: 2.2 + +.. method:: dict.keys() + + Return a copy of the dictionary's list of keys. See the note for + :meth:`dict.items`. + +.. method:: dict.pop(key[, default]) + + If *key* is in the dictionary, remove it and return its value, else return + *default*. If *default* is not given and *key* is not in the dictionary, a + :exc:`KeyError` is raised. .. versionadded:: 2.3 -(9) - :func:`update` accepts either another mapping object or an iterable of key/value - pairs (as a tuple or other iterable of length two). If keyword arguments are - specified, the mapping is then is updated with those key/value pairs: - ``d.update(red=1, blue=2)``. +.. method:: dict.popitem() + + Remove and return an arbitrary ``(key, value)`` pair from the dictionary. + + :func:`popitem` is useful to destructively iterate over a dictionary, as + often used in set algorithms. If the dictionary is empty, calling + :func:`popitem` raises a :exc:`KeyError`. + +.. method:: dict.setdefault(key[, default]) + + If *key* is in the dictionary, return its value. If not, insert *key* with a + value of *default* and return *default*. *default* defaults to ``None``. + +.. method:: dict.update([other]) + + Update the dictionary with the key/value pairs from *other*, overwriting existing + keys. Return ``None``. + + :func:`update` accepts either another dictionary object or an iterable of + key/value pairs (as a tuple or other iterable of length two). If keyword + arguments are specified, the dictionary is then is updated with those + key/value pairs: ``d.update(red=1, blue=2)``. .. versionchanged:: 2.4 - Allowed the argument to be an iterable of key/value pairs and allowed keyword - arguments. + Allowed the argument to be an iterable of key/value pairs and allowed + keyword arguments. -(10) - If a subclass of dict defines a method :meth:`__missing__`, if the key *k* is - not present, the ``a[k]`` operation calls that method with the key *k* as - argument. The ``a[k]`` operation then returns or raises whatever is returned - or raised by the ``__missing__(k)`` call if the key is not present. No other - operations or methods invoke :meth:`__missing__`. If :meth:`__missing__` is - not defined, :exc:`KeyError` is raised. :meth:`__missing__` must be a - method; it cannot be an instance variable. For an example, see - :class:`collections.defaultdict`. +.. method:: dict.values() - .. versionadded:: 2.5 + Return a copy of the dictionary's list of values. See the note for + :meth:`mapping.items`. .. _bltin-file-objects: Modified: doctools/trunk/Doc-26/library/string.rst ============================================================================== --- doctools/trunk/Doc-26/library/string.rst (original) +++ doctools/trunk/Doc-26/library/string.rst Mon Aug 6 18:50:04 2007 @@ -15,7 +15,7 @@ :ref:`typesseq` section, and also the string-specific methods described in the :ref:`string-methods` section. To output formatted strings use template strings or the ``%`` operator described in the -:ref:`typesseq-strings` section. Also, see the :mod:`re` module for +:ref:`string-formatting` section. Also, see the :mod:`re` module for string functions based on regular expressions. Modified: doctools/trunk/Doc-26/library/strings.rst ============================================================================== --- doctools/trunk/Doc-26/library/strings.rst (original) +++ doctools/trunk/Doc-26/library/strings.rst Mon Aug 6 18:50:04 2007 @@ -12,7 +12,7 @@ methods described in the :ref:`typesseq` section, and also the string-specific methods described in the :ref:`string-methods` section. To output formatted strings use template strings or the ``%`` operator -described in the :ref:`typesseq-strings` section. Also, see the +described in the :ref:`string-formatting` section. Also, see the :mod:`re` module for string functions based on regular expressions. Modified: doctools/trunk/Doc-26/reference/datamodel.rst ============================================================================== --- doctools/trunk/Doc-26/reference/datamodel.rst (original) +++ doctools/trunk/Doc-26/reference/datamodel.rst Mon Aug 6 18:50:04 2007 @@ -1701,41 +1701,6 @@ Emulating container types ------------------------- -.. index:: - single: keys() (mapping object method) - single: values() (mapping object method) - single: items() (mapping object method) - single: iterkeys() (mapping object method) - single: itervalues() (mapping object method) - single: iteritems() (mapping object method) - single: has_key() (mapping object method) - single: get() (mapping object method) - single: setdefault() (mapping object method) - single: pop() (mapping object method) - single: popitem() (mapping object method) - single: clear() (mapping object method) - single: copy() (mapping object method) - single: update() (mapping object method) - single: __contains__() (mapping object method) - single: append() (sequence object method) - single: count() (sequence object method) - single: extend() (sequence object method) - single: index() (sequence object method) - single: insert() (sequence object method) - single: pop() (sequence object method) - single: remove() (sequence object method) - single: reverse() (sequence object method) - single: sort() (sequence object method) - single: __add__() (sequence object method) - single: __radd__() (sequence object method) - single: __iadd__() (sequence object method) - single: __mul__() (sequence object method) - single: __rmul__() (sequence object method) - single: __imul__() (sequence object method) - single: __contains__() (sequence object method) - single: __iter__() (sequence object method) - single: __coerce__() (numeric object method) - The following methods can be defined to implement container objects. Containers usually are sequences (such as lists or tuples) or mappings (like dictionaries), but can represent other containers as well. The first set of methods is used @@ -1768,7 +1733,7 @@ sequences, it should iterate through the values. -.. method:: container object.__len__(self) +.. method:: object.__len__(self) .. index:: builtin: len @@ -1780,7 +1745,7 @@ considered to be false in a Boolean context. -.. method:: container object.__getitem__(self, key) +.. method:: object.__getitem__(self, key) .. index:: object: slice @@ -1799,7 +1764,7 @@ indexes to allow proper detection of the end of the sequence. -.. method:: container object.__setitem__(self, key, value) +.. method:: object.__setitem__(self, key, value) Called to implement assignment to ``self[key]``. Same note as for :meth:`__getitem__`. This should only be implemented for mappings if the @@ -1808,7 +1773,7 @@ for improper *key* values as for the :meth:`__getitem__` method. -.. method:: container object.__delitem__(self, key) +.. method:: object.__delitem__(self, key) Called to implement deletion of ``self[key]``. Same note as for :meth:`__getitem__`. This should only be implemented for mappings if the @@ -1817,7 +1782,7 @@ values as for the :meth:`__getitem__` method. -.. method:: container object.__iter__(self) +.. method:: object.__iter__(self) This method is called when an iterator is required for a container. This method should return a new iterator object that can iterate over all the objects in the @@ -1833,7 +1798,7 @@ also does not require the object be a sequence. -.. method:: container object.__contains__(self, item) +.. method:: object.__contains__(self, item) Called to implement membership test operators. Should return true if *item* is in *self*, false otherwise. For mapping objects, this should consider the keys @@ -1850,7 +1815,7 @@ :meth:`__getslice__`; mutable sequences might define all three methods. -.. method:: sequence object.__getslice__(self, i, j) +.. method:: object.__getslice__(self, i, j) .. deprecated:: 2.0 Support slice objects as parameters to the :meth:`__getitem__` method. @@ -1866,7 +1831,7 @@ is created instead, and passed to :meth:`__getitem__` instead. -.. method:: sequence object.__setslice__(self, i, j, sequence) +.. method:: object.__setslice__(self, i, j, sequence) Called to implement assignment to ``self[i:j]``. Same notes for *i* and *j* as for :meth:`__getslice__`. @@ -1876,7 +1841,7 @@ :meth:`__setitem__`, instead of :meth:`__setslice__` being called. -.. method:: sequence object.__delslice__(self, i, j) +.. method:: object.__delslice__(self, i, j) Called to implement deletion of ``self[i:j]``. Same notes for *i* and *j* as for :meth:`__getslice__`. This method is deprecated. If no :meth:`__delslice__` is @@ -1940,18 +1905,18 @@ left undefined. -.. method:: numeric object.__add__(self, other) - numeric object.__sub__(self, other) - numeric object.__mul__(self, other) - numeric object.__floordiv__(self, other) - numeric object.__mod__(self, other) - numeric object.__divmod__(self, other) - numeric object.__pow__(self, other[, modulo]) - numeric object.__lshift__(self, other) - numeric object.__rshift__(self, other) - numeric object.__and__(self, other) - numeric object.__xor__(self, other) - numeric object.__or__(self, other) +.. method:: object.__add__(self, other) + object.__sub__(self, other) + object.__mul__(self, other) + object.__floordiv__(self, other) + object.__mod__(self, other) + object.__divmod__(self, other) + object.__pow__(self, other[, modulo]) + object.__lshift__(self, other) + object.__rshift__(self, other) + object.__and__(self, other) + object.__xor__(self, other) + object.__or__(self, other) .. index:: builtin: divmod @@ -1972,8 +1937,8 @@ arguments, it should return ``NotImplemented``. -.. method:: numeric object.__div__(self, other) - numeric object.__truediv__(self, other) +.. method:: object.__div__(self, other) + object.__truediv__(self, other) The division operator (``/``) is implemented by these methods. The :meth:`__truediv__` method is used when ``__future__.division`` is in effect, @@ -1982,20 +1947,20 @@ will be raised instead. -.. method:: numeric object.__radd__(self, other) - numeric object.__rsub__(self, other) - numeric object.__rmul__(self, other) - numeric object.__rdiv__(self, other) - numeric object.__rtruediv__(self, other) - numeric object.__rfloordiv__(self, other) - numeric object.__rmod__(self, other) - numeric object.__rdivmod__(self, other) - numeric object.__rpow__(self, other) - numeric object.__rlshift__(self, other) - numeric object.__rrshift__(self, other) - numeric object.__rand__(self, other) - numeric object.__rxor__(self, other) - numeric object.__ror__(self, other) +.. method:: object.__radd__(self, other) + object.__rsub__(self, other) + object.__rmul__(self, other) + object.__rdiv__(self, other) + object.__rtruediv__(self, other) + object.__rfloordiv__(self, other) + object.__rmod__(self, other) + object.__rdivmod__(self, other) + object.__rpow__(self, other) + object.__rlshift__(self, other) + object.__rrshift__(self, other) + object.__rand__(self, other) + object.__rxor__(self, other) + object.__ror__(self, other) .. index:: builtin: divmod @@ -2023,19 +1988,19 @@ subclasses to override their ancestors' operations. -.. method:: numeric object.__iadd__(self, other) - numeric object.__isub__(self, other) - numeric object.__imul__(self, other) - numeric object.__idiv__(self, other) - numeric object.__itruediv__(self, other) - numeric object.__ifloordiv__(self, other) - numeric object.__imod__(self, other) - numeric object.__ipow__(self, other[, modulo]) - numeric object.__ilshift__(self, other) - numeric object.__irshift__(self, other) - numeric object.__iand__(self, other) - numeric object.__ixor__(self, other) - numeric object.__ior__(self, other) +.. method:: object.__iadd__(self, other) + object.__isub__(self, other) + object.__imul__(self, other) + object.__idiv__(self, other) + object.__itruediv__(self, other) + object.__ifloordiv__(self, other) + object.__imod__(self, other) + object.__ipow__(self, other[, modulo]) + object.__ilshift__(self, other) + object.__irshift__(self, other) + object.__iand__(self, other) + object.__ixor__(self, other) + object.__ior__(self, other) These methods are called to implement the augmented arithmetic operations (``+=``, ``-=``, ``*=``, ``/=``, ``//=``, ``%=``, ``**=``, ``<<=``, ``>>=``, @@ -2049,10 +2014,10 @@ and ``y.__radd__(x)`` are considered, as with the evaluation of *x*``+``*y*. -.. method:: numeric object.__neg__(self) - numeric object.__pos__(self) - numeric object.__abs__(self) - numeric object.__invert__(self) +.. method:: object.__neg__(self) + object.__pos__(self) + object.__abs__(self) + object.__invert__(self) .. index:: builtin: abs @@ -2060,10 +2025,10 @@ and ``~``). -.. method:: numeric object.__complex__(self) - numeric object.__int__(self) - numeric object.__long__(self) - numeric object.__float__(self) +.. method:: object.__complex__(self) + object.__int__(self) + object.__long__(self) + object.__float__(self) .. index:: builtin: complex @@ -2075,8 +2040,8 @@ :func:`long`, and :func:`float`. Should return a value of the appropriate type. -.. method:: numeric object.__oct__(self) - numeric object.__hex__(self) +.. method:: object.__oct__(self) + object.__hex__(self) .. index:: builtin: oct @@ -2086,7 +2051,7 @@ return a string value. -.. method:: numeric object.__index__(self) +.. method:: object.__index__(self) Called to implement :func:`operator.index`. Also called whenever Python needs an integer object (such as in slicing). Must return an integer (int or long). @@ -2094,7 +2059,7 @@ .. versionadded:: 2.5 -.. method:: numeric object.__coerce__(self, other) +.. method:: object.__coerce__(self, other) Called to implement "mixed-mode" numeric arithmetic. Should either return a 2-tuple containing *self* and *other* converted to a common numeric type, or @@ -2233,14 +2198,14 @@ For more information on context managers, see :ref:`typecontextmanager`. -.. method:: context manager.__enter__(self) +.. method:: object.__enter__(self) Enter the runtime context related to this object. The :keyword:`with` statement will bind this method's return value to the target(s) specified in the :keyword:`as` clause of the statement, if any. -.. method:: context manager.__exit__(self, exc_type, exc_value, traceback) +.. method:: object.__exit__(self, exc_type, exc_value, traceback) Exit the runtime context related to this object. The parameters describe the exception that caused the context to be exited. If the context was exited Modified: doctools/trunk/Doc-26/reference/expressions.rst ============================================================================== --- doctools/trunk/Doc-26/reference/expressions.rst (original) +++ doctools/trunk/Doc-26/reference/expressions.rst Mon Aug 6 18:50:04 2007 @@ -902,7 +902,7 @@ In addition to performing the modulo operation on numbers, the ``%`` operator is also overloaded by string and unicode objects to perform string formatting (also known as interpolation). The syntax for string formatting is described in the -Python Library Reference, section :ref:`typesseq-strings`. +Python Library Reference, section :ref:`string-formatting`. .. deprecated:: 2.3 The floor division operator, the modulo operator, and the :func:`divmod` Modified: doctools/trunk/Doc-26/tutorial/introduction.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/introduction.rst (original) +++ doctools/trunk/Doc-26/tutorial/introduction.rst Mon Aug 6 18:50:04 2007 @@ -379,7 +379,7 @@ Both strings and Unicode strings support a large number of methods for basic transformations and searching. - :ref:`typesseq-strings` + :ref:`string-formatting` The formatting operations invoked when strings and Unicode strings are the left operand of the ``%`` operator are described in more detail here. Modified: doctools/trunk/Doc-3k/c-api/utilities.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/utilities.rst (original) +++ doctools/trunk/Doc-3k/c-api/utilities.rst Mon Aug 6 18:50:04 2007 @@ -942,7 +942,7 @@ set and *NULL* returned. -.. _string-formatting: +.. _string-conversion: String conversion and formatting ================================ Modified: doctools/trunk/Doc-3k/library/csv.rst ============================================================================== --- doctools/trunk/Doc-3k/library/csv.rst (original) +++ doctools/trunk/Doc-3k/library/csv.rst Mon Aug 6 18:50:04 2007 @@ -334,7 +334,7 @@ :func:`reader` function) have the following public methods: -.. method:: csv reader.next() +.. method:: csvreader.next() Return the next row of the reader's iterable object as a list, parsed according to the current dialect. @@ -342,12 +342,12 @@ Reader objects have the following public attributes: -.. attribute:: csv reader.dialect +.. attribute:: csvreader.dialect A read-only description of the dialect in use by the parser. -.. attribute:: csv reader.line_num +.. attribute:: csvreader.line_num The number of lines read from the source iterator. This is not the same as the number of records returned, as records can span multiple lines. @@ -367,13 +367,13 @@ read CSV files (assuming they support complex numbers at all). -.. method:: csv writer.writerow(row) +.. method:: csvwriter.writerow(row) Write the *row* parameter to the writer's file object, formatted according to the current dialect. -.. method:: csv writer.writerows(rows) +.. method:: csvwriter.writerows(rows) Write all the *rows* parameters (a list of *row* objects as described above) to the writer's file object, formatted according to the current dialect. @@ -381,7 +381,7 @@ Writer objects have the following public attribute: -.. attribute:: csv writer.dialect +.. attribute:: csvwriter.dialect A read-only description of the dialect in use by the writer. Modified: doctools/trunk/Doc-3k/library/functions.rst ============================================================================== --- doctools/trunk/Doc-3k/library/functions.rst (original) +++ doctools/trunk/Doc-3k/library/functions.rst Mon Aug 6 18:50:04 2007 @@ -231,6 +231,7 @@ the function serves as a numeric conversion function like :func:`int`, :func:`long` and :func:`float`. If both arguments are omitted, returns ``0j``. + The complex type is described in :ref:`typesnumeric`. .. function:: delattr(object, name) @@ -241,42 +242,10 @@ .. function:: dict([arg]) + :noindex: - Return a new dictionary initialized from an optional positional argument or from - a set of keyword arguments. If no arguments are given, return a new empty - dictionary. If the positional argument *arg* is a mapping object, return a - dictionary mapping the same keys to the same values as does the mapping object. - Otherwise the positional argument must be a sequence, a container that supports - iteration, or an iterator object. The elements of the argument must each also - be of one of those kinds, and each must in turn contain exactly two objects. - The first is used as a key in the new dictionary, and the second as the key's - value. If a given key is seen more than once, the last value associated with it - is retained in the new dictionary. - - If keyword arguments are given, the keywords themselves with their associated - values are added as items to the dictionary. If a key is specified both in the - positional argument and as a keyword argument, the value associated with the - keyword is retained in the dictionary. For example, these all return a - dictionary equal to ``{"one": 2, "two": 3}``: - - * ``dict({'one': 2, 'two': 3})`` - - * ``dict({'one': 2, 'two': 3}.items())`` - - * ``dict({'one': 2, 'two': 3}.iteritems())`` - - * ``dict(zip(('one', 'two'), (2, 3)))`` - - * ``dict([['two', 3], ['one', 2]])`` - - * ``dict(one=2, two=3)`` - - * ``dict([(['one', 'two'][i-2], i) for i in (2, 3)])`` - - .. versionadded:: 2.2 - - .. versionchanged:: 2.3 - Support for building a dictionary from keyword arguments added. + Create a new dictionary. The dictionary type is described in + :ref:`typesmapping`. .. function:: dir([object]) @@ -508,6 +477,7 @@ these values to be returned depends entirely on the C library and is known to vary. + The float type is described in :ref:`typesnumeric`. .. function:: frozenset([iterable]) @@ -518,6 +488,8 @@ :class:`frozenset` objects. If *iterable* is not specified, returns a new empty set, ``frozenset([])``. + The frozenset type is described in :ref:`types-set`. + .. versionadded:: 2.4 @@ -596,6 +568,8 @@ is outside the integer range a long object will be returned instead. If no arguments are given, returns ``0``. + The integer type is described in :ref:`typesnumeric`. + .. function:: isinstance(object, classinfo) @@ -655,6 +629,8 @@ returns ``['a', 'b', 'c']`` and ``list( (1, 2, 3) )`` returns ``[1, 2, 3]``. If no argument is given, returns a new empty list, ``[]``. + :class:`list` is a mutable sequence type, as documented in :ref:`typesseq`. + .. function:: locals() @@ -680,6 +656,7 @@ with the same value is returned. Conversion of floating point numbers to integers truncates (towards zero). If no arguments are given, returns ``0L``. + The long type is described in :ref:`typesnumeric`. .. function:: map(function, iterable, ...) @@ -942,6 +919,8 @@ :class:`frozenset` objects. If *iterable* is not specified, returns a new empty set, ``set([])``. + The set type is described in :ref:`types-set`. + .. versionadded:: 2.4 @@ -1032,13 +1011,12 @@ acceptable to :func:`eval`; its goal is to return a printable string. If no argument is given, returns the empty string, ``''``. - For more information on strings see :ref:`typesseq` which describes - sequence functionality (strings are sequences), and also the - string-specific methods described in the :ref:`string-methods` - section. To output formatted strings use template strings or the - ``%`` operator described in the :ref:`typesseq-strings` section. In - addition see the :ref:`stringservices` section. See also - :func:`unicode`. + For more information on strings see :ref:`typesseq` which describes sequence + functionality (strings are sequences), and also the string-specific methods + described in the :ref:`string-methods` section. To output formatted strings + use template strings or the ``%`` operator described in the + :ref:`string-formatting` section. In addition see the :ref:`stringservices` + section. See also :func:`unicode`. .. function:: sum(iterable[, start]) @@ -1082,6 +1060,7 @@ 3])`` returns ``(1, 2, 3)``. If no argument is given, returns a new empty tuple, ``()``. + :class:`tuple` is a mutable sequence type, as documented in :ref:`typesseq`. .. function:: type(object) @@ -1152,11 +1131,10 @@ For more information on Unicode strings see :ref:`typesseq` which describes sequence functionality (Unicode strings are sequences), and also the - string-specific methods described in the :ref:`string-methods` - section. To output formatted strings use template strings or the - ``%`` operator described in the :ref:`typesseq-strings` section. In - addition see the :ref:`stringservices` section. See also - :func:`str`. + string-specific methods described in the :ref:`string-methods` section. To + output formatted strings use template strings or the ``%`` operator described + in the :ref:`string-formatting` section. In addition see the + :ref:`stringservices` section. See also :func:`str`. .. versionadded:: 2.0 Modified: doctools/trunk/Doc-3k/library/logging.rst ============================================================================== --- doctools/trunk/Doc-3k/library/logging.rst (original) +++ doctools/trunk/Doc-3k/library/logging.rst Mon Aug 6 18:50:04 2007 @@ -612,7 +612,7 @@ rather than the console. Formatting uses standard Python string formatting - see section -:ref:`typesseq-strings`. The format string takes the following common +:ref:`string-formatting`. The format string takes the following common specifiers. For a complete list of specifiers, consult the :class:`Formatter` documentation. @@ -1483,7 +1483,7 @@ of the :class:`LogRecord` attributes - such as the default value mentioned above making use of the fact that the user's message and arguments are pre-formatted into a :class:`LogRecord`'s *message* attribute. This format string contains -standard python %-style mapping keys. See section :ref:`typesseq-strings` +standard python %-style mapping keys. See section :ref:`string-formatting` for more information on string formatting. Currently, the useful mapping keys in a :class:`LogRecord` are: Modified: doctools/trunk/Doc-3k/library/ossaudiodev.rst ============================================================================== --- doctools/trunk/Doc-3k/library/ossaudiodev.rst (original) +++ doctools/trunk/Doc-3k/library/ossaudiodev.rst Mon Aug 6 18:50:04 2007 @@ -124,19 +124,19 @@ and (read-only) attributes: -.. method:: audio device.close() +.. method:: oss_audio_device.close() Explicitly close the audio device. When you are done writing to or reading from an audio device, you should explicitly close it. A closed device cannot be used again. -.. method:: audio device.fileno() +.. method:: oss_audio_device.fileno() Return the file descriptor associated with the device. -.. method:: audio device.read(size) +.. method:: oss_audio_device.read(size) Read *size* bytes from the audio input and return them as a Python string. Unlike most Unix device drivers, OSS audio devices in blocking mode (the @@ -144,7 +144,7 @@ available. -.. method:: audio device.write(data) +.. method:: oss_audio_device.write(data) Write the Python string *data* to the audio device and return the number of bytes written. If the audio device is in blocking mode (the default), the @@ -153,7 +153,7 @@ ---see :meth:`writeall`. -.. method:: audio device.writeall(data) +.. method:: oss_audio_device.writeall(data) Write the entire Python string *data* to the audio device: waits until the audio device is able to accept data, writes as much data as it will accept, and @@ -169,13 +169,13 @@ :func:`ioctl` fails, they all raise :exc:`IOError`. -.. method:: audio device.nonblock() +.. method:: oss_audio_device.nonblock() Put the device into non-blocking mode. Once in non-blocking mode, there is no way to return it to blocking mode. -.. method:: audio device.getfmts() +.. method:: oss_audio_device.getfmts() Return a bitmask of the audio output formats supported by the soundcard. Some of the formats supported by OSS are: @@ -212,7 +212,7 @@ :const:`AFMT_S16_LE`. -.. method:: audio device.setfmt(format) +.. method:: oss_audio_device.setfmt(format) Try to set the current audio format to *format*---see :meth:`getfmts` for a list. Returns the audio format that the device was set to, which may not be the @@ -220,7 +220,7 @@ by passing an "audio format" of :const:`AFMT_QUERY`. -.. method:: audio device.channels(nchannels) +.. method:: oss_audio_device.channels(nchannels) Set the number of output channels to *nchannels*. A value of 1 indicates monophonic sound, 2 stereophonic. Some devices may have more than 2 channels, @@ -228,7 +228,7 @@ the device was set to. -.. method:: audio device.speed(samplerate) +.. method:: oss_audio_device.speed(samplerate) Try to set the audio sampling rate to *samplerate* samples per second. Returns the rate actually set. Most sound devices don't support arbitrary sampling @@ -250,21 +250,21 @@ +-------+-------------------------------------------+ -.. method:: audio device.sync() +.. method:: oss_audio_device.sync() Wait until the sound device has played every byte in its buffer. (This happens implicitly when the device is closed.) The OSS documentation recommends closing and re-opening the device rather than using :meth:`sync`. -.. method:: audio device.reset() +.. method:: oss_audio_device.reset() Immediately stop playing or recording and return the device to a state where it can accept commands. The OSS documentation recommends closing and re-opening the device after calling :meth:`reset`. -.. method:: audio device.post() +.. method:: oss_audio_device.post() Tell the driver that there is likely to be a pause in the output, making it possible for the device to handle the pause more intelligently. You might use @@ -275,7 +275,7 @@ simple calculations. -.. method:: audio device.setparameters(format, nchannels, samplerate [, strict=False]) +.. method:: oss_audio_device.setparameters(format, nchannels, samplerate [, strict=False]) Set the key audio sampling parameters---sample format, number of channels, and sampling rate---in one method call. *format*, *nchannels*, and *samplerate* @@ -298,17 +298,17 @@ rate = dsp.rate(channels) -.. method:: audio device.bufsize() +.. method:: oss_audio_device.bufsize() Returns the size of the hardware buffer, in samples. -.. method:: audio device.obufcount() +.. method:: oss_audio_device.obufcount() Returns the number of samples that are in the hardware buffer yet to be played. -.. method:: audio device.obuffree() +.. method:: oss_audio_device.obuffree() Returns the number of samples that could be queued into the hardware buffer to be played without blocking. @@ -316,17 +316,17 @@ Audio device objects also support several read-only attributes: -.. attribute:: audio device.closed +.. attribute:: oss_audio_device.closed Boolean indicating whether the device has been closed. -.. attribute:: audio device.name +.. attribute:: oss_audio_device.name String containing the name of the device file. -.. attribute:: audio device.mode +.. attribute:: oss_audio_device.mode The I/O mode for the file, either ``"r"``, ``"rw"``, or ``"w"``. @@ -339,20 +339,20 @@ The mixer object provides two file-like methods: -.. method:: mixer device.close() +.. method:: oss_mixer_device.close() This method closes the open mixer device file. Any further attempts to use the mixer after this file is closed will raise an :exc:`IOError`. -.. method:: mixer device.fileno() +.. method:: oss_mixer_device.fileno() Returns the file handle number of the open mixer device file. The remaining methods are specific to audio mixing: -.. method:: mixer device.controls() +.. method:: oss_mixer_device.controls() This method returns a bitmask specifying the available mixer controls ("Control" being a specific mixable "channel", such as :const:`SOUND_MIXER_PCM` or @@ -372,7 +372,7 @@ Ultrasound, for example, :const:`SOUND_MIXER_VOLUME` does not exist. -.. method:: mixer device.stereocontrols() +.. method:: oss_mixer_device.stereocontrols() Returns a bitmask indicating stereo mixer controls. If a bit is set, the corresponding control is stereo; if it is unset, the control is either @@ -383,13 +383,13 @@ data from a bitmask. -.. method:: mixer device.reccontrols() +.. method:: oss_mixer_device.reccontrols() Returns a bitmask specifying the mixer controls that may be used to record. See the code example for :meth:`controls` for an example of reading from a bitmask. -.. method:: mixer device.get(control) +.. method:: oss_mixer_device.get(control) Returns the volume of a given mixer control. The returned volume is a 2-tuple ``(left_volume,right_volume)``. Volumes are specified as numbers from 0 @@ -400,7 +400,7 @@ :exc:`IOError` if an unsupported control is specified. -.. method:: mixer device.set(control, (left, right)) +.. method:: oss_mixer_device.set(control, (left, right)) Sets the volume for a given mixer control to ``(left,right)``. ``left`` and ``right`` must be ints and between 0 (silent) and 100 (full volume). On @@ -412,13 +412,13 @@ specified volumes were out-of-range. -.. method:: mixer device.get_recsrc() +.. method:: oss_mixer_device.get_recsrc() This method returns a bitmask indicating which control(s) are currently being used as a recording source. -.. method:: mixer device.set_recsrc(bitmask) +.. method:: oss_mixer_device.set_recsrc(bitmask) Call this function to specify a recording source. Returns a bitmask indicating the new recording source (or sources) if successful; raises :exc:`IOError` if an Modified: doctools/trunk/Doc-3k/library/pyclbr.rst ============================================================================== --- doctools/trunk/Doc-3k/library/pyclbr.rst (original) +++ doctools/trunk/Doc-3k/library/pyclbr.rst Mon Aug 6 18:50:04 2007 @@ -47,17 +47,17 @@ :func:`readmodule` and :func:`readmodule_ex` provide the following data members: -.. attribute:: class descriptor.module +.. attribute:: class_descriptor.module The name of the module defining the class described by the class descriptor. -.. attribute:: class descriptor.name +.. attribute:: class_descriptor.name The name of the class. -.. attribute:: class descriptor.super +.. attribute:: class_descriptor.super A list of class descriptors which describe the immediate base classes of the class being described. Classes which are named as superclasses but which are @@ -65,17 +65,17 @@ name instead of class descriptors. -.. attribute:: class descriptor.methods +.. attribute:: class_descriptor.methods A dictionary mapping method names to line numbers. -.. attribute:: class descriptor.file +.. attribute:: class_descriptor.file Name of the file containing the ``class`` statement defining the class. -.. attribute:: class descriptor.lineno +.. attribute:: class_descriptor.lineno The line number of the ``class`` statement within the file named by :attr:`file`. @@ -90,23 +90,23 @@ :func:`readmodule_ex` provide the following data members: -.. attribute:: function descriptor.module +.. attribute:: function_descriptor.module The name of the module defining the function described by the function descriptor. -.. attribute:: function descriptor.name +.. attribute:: function_descriptor.name The name of the function. -.. attribute:: function descriptor.file +.. attribute:: function_descriptor.file Name of the file containing the ``def`` statement defining the function. -.. attribute:: function descriptor.lineno +.. attribute:: function_descriptor.lineno The line number of the ``def`` statement within the file named by :attr:`file`. Modified: doctools/trunk/Doc-3k/library/stdtypes.rst ============================================================================== --- doctools/trunk/Doc-3k/library/stdtypes.rst (original) +++ doctools/trunk/Doc-3k/library/stdtypes.rst Mon Aug 6 18:50:04 2007 @@ -1,3 +1,5 @@ +.. XXX: reference/datamodel and this have quite a few overlaps! + .. _bltin-types: @@ -490,6 +492,8 @@ object: Unicode object: tuple object: list + object: buffer + object: range String literals are written in single or double quotes: ``'xyzzy'``, ``"frobozz"``. See :ref:`strings` for more about string literals. Unicode @@ -501,18 +505,10 @@ ``a, b, c`` or ``()``. A single item tuple must have a trailing comma, such as ``(d,)``. -.. index:: - builtin: buffer - object: buffer - Buffer objects are not directly supported by Python syntax, but can be created by calling the builtin function :func:`buffer`. They don't support concatenation or repetition. -.. index:: - builtin: range - object: range - Xrange objects are similar to buffers in that there is no specific syntax to create them, but they are created using the :func:`range` function. They don't support slicing, concatenation or repetition, and using ``in``, ``not in``, @@ -650,12 +646,11 @@ .. index:: pair: string; methods -Below are listed the string methods which both 8-bit strings and Unicode -objects support. In addition, Python's strings support the -sequence type methods described in the -:ref:`typesseq` section (above). To output formatted strings use -template strings or the ``%`` operator described in the -:ref:`typesseq-strings` section (below). Also, see the :mod:`re` module for +Below are listed the string methods which both 8-bit strings and Unicode objects +support. In addition, Python's strings support the sequence type methods +described in the :ref:`typesseq` section (above). To output formatted strings +use template strings or the ``%`` operator described in the +:ref:`string-formatting` section (below). Also, see the :mod:`re` module for string functions based on regular expressions. .. method:: str.capitalize() @@ -1031,7 +1026,7 @@ .. versionadded:: 2.2.2 -.. _typesseq-strings: +.. _string-formatting: String Formatting Operations ---------------------------- @@ -1098,86 +1093,72 @@ The conversion flag characters are: -+---------+-----------------------------------------------+ -| Flag | Meaning | -+=========+===============================================+ -| ``'#'`` | The value conversion will use the "alternate | -| | form" (where defined below). | -+---------+-----------------------------------------------+ -| ``'0'`` | The conversion will be zero padded for | -| | numeric values. | -+---------+-----------------------------------------------+ -| ``'-'`` | The converted value is left adjusted | -| | (overrides the ``'0'`` conversion if both are | -| | given). | -+---------+-----------------------------------------------+ -| ``' '`` | (a space) A blank should be left before a | -| | positive number (or empty string) produced by | -| | a signed conversion. | -+---------+-----------------------------------------------+ -| ``'+'`` | A sign character (``'+'`` or ``'-'``) will | -| | precede the conversion (overrides a "space" | -| | flag). | -+---------+-----------------------------------------------+ ++---------+---------------------------------------------------------------------+ +| Flag | Meaning | ++=========+=====================================================================+ +| ``'#'`` | The value conversion will use the "alternate form" (where defined | +| | below). | ++---------+---------------------------------------------------------------------+ +| ``'0'`` | The conversion will be zero padded for numeric values. | ++---------+---------------------------------------------------------------------+ +| ``'-'`` | The converted value is left adjusted (overrides the ``'0'`` | +| | conversion if both are given). | ++---------+---------------------------------------------------------------------+ +| ``' '`` | (a space) A blank should be left before a positive number (or empty | +| | string) produced by a signed conversion. | ++---------+---------------------------------------------------------------------+ +| ``'+'`` | A sign character (``'+'`` or ``'-'``) will precede the conversion | +| | (overrides a "space" flag). | ++---------+---------------------------------------------------------------------+ A length modifier (``h``, ``l``, or ``L``) may be present, but is ignored as it is not necessary for Python. The conversion types are: -+------------+---------------------------------+-------+ -| Conversion | Meaning | Notes | -+============+=================================+=======+ -| ``'d'`` | Signed integer decimal. | | -+------------+---------------------------------+-------+ -| ``'i'`` | Signed integer decimal. | | -+------------+---------------------------------+-------+ -| ``'o'`` | Unsigned octal. | \(1) | -+------------+---------------------------------+-------+ -| ``'u'`` | Unsigned decimal. | | -+------------+---------------------------------+-------+ -| ``'x'`` | Unsigned hexadecimal | \(2) | -| | (lowercase). | | -+------------+---------------------------------+-------+ -| ``'X'`` | Unsigned hexadecimal | \(2) | -| | (uppercase). | | -+------------+---------------------------------+-------+ -| ``'e'`` | Floating point exponential | \(3) | -| | format (lowercase). | | -+------------+---------------------------------+-------+ -| ``'E'`` | Floating point exponential | \(3) | -| | format (uppercase). | | -+------------+---------------------------------+-------+ -| ``'f'`` | Floating point decimal format. | \(3) | -+------------+---------------------------------+-------+ -| ``'F'`` | Floating point decimal format. | \(3) | -+------------+---------------------------------+-------+ -| ``'g'`` | Floating point format. Uses | \(4) | -| | exponential format if exponent | | -| | is greater than -4 or less than | | -| | precision, decimal format | | -| | otherwise. | | -+------------+---------------------------------+-------+ -| ``'G'`` | Floating point format. Uses | \(4) | -| | exponential format if exponent | | -| | is greater than -4 or less than | | -| | precision, decimal format | | -| | otherwise. | | -+------------+---------------------------------+-------+ -| ``'c'`` | Single character (accepts | | -| | integer or single character | | -| | string). | | -+------------+---------------------------------+-------+ -| ``'r'`` | String (converts any python | \(5) | -| | object using :func:`repr`). | | -+------------+---------------------------------+-------+ -| ``'s'`` | String (converts any python | \(6) | -| | object using :func:`str`). | | -+------------+---------------------------------+-------+ -| ``'%'`` | No argument is converted, | | -| | results in a ``'%'`` character | | -| | in the result. | | -+------------+---------------------------------+-------+ ++------------+-----------------------------------------------------+-------+ +| Conversion | Meaning | Notes | ++============+=====================================================+=======+ +| ``'d'`` | Signed integer decimal. | | ++------------+-----------------------------------------------------+-------+ +| ``'i'`` | Signed integer decimal. | | ++------------+-----------------------------------------------------+-------+ +| ``'o'`` | Unsigned octal. | \(1) | ++------------+-----------------------------------------------------+-------+ +| ``'u'`` | Unsigned decimal. | | ++------------+-----------------------------------------------------+-------+ +| ``'x'`` | Unsigned hexadecimal (lowercase). | \(2) | ++------------+-----------------------------------------------------+-------+ +| ``'X'`` | Unsigned hexadecimal (uppercase). | \(2) | ++------------+-----------------------------------------------------+-------+ +| ``'e'`` | Floating point exponential format (lowercase). | \(3) | ++------------+-----------------------------------------------------+-------+ +| ``'E'`` | Floating point exponential format (uppercase). | \(3) | ++------------+-----------------------------------------------------+-------+ +| ``'f'`` | Floating point decimal format. | \(3) | ++------------+-----------------------------------------------------+-------+ +| ``'F'`` | Floating point decimal format. | \(3) | ++------------+-----------------------------------------------------+-------+ +| ``'g'`` | Floating point format. Uses exponential format if | \(4) | +| | exponent is greater than -4 or less than precision, | | +| | decimal format otherwise. | | ++------------+-----------------------------------------------------+-------+ +| ``'G'`` | Floating point format. Uses exponential format if | \(4) | +| | exponent is greater than -4 or less than precision, | | +| | decimal format otherwise. | | ++------------+-----------------------------------------------------+-------+ +| ``'c'`` | Single character (accepts integer or single | | +| | character string). | | ++------------+-----------------------------------------------------+-------+ +| ``'r'`` | String (converts any python object using | \(5) | +| | :func:`repr`). | | ++------------+-----------------------------------------------------+-------+ +| ``'s'`` | String (converts any python object using | \(6) | +| | :func:`str`). | | ++------------+-----------------------------------------------------+-------+ +| ``'%'`` | No argument is converted, results in a ``'%'`` | | +| | character in the result. | | ++------------+-----------------------------------------------------+-------+ Notes: @@ -1437,37 +1418,52 @@ Instances of :class:`set` and :class:`frozenset` provide the following operations: -+-------------------------------+------------+---------------------------------+ -| Operation | Equivalent | Result | -+===============================+============+=================================+ -| ``len(s)`` | | cardinality of set *s* | -+-------------------------------+------------+---------------------------------+ -| ``x in s`` | | test *x* for membership in *s* | -+-------------------------------+------------+---------------------------------+ -| ``x not in s`` | | test *x* for non-membership in | -| | | *s* | -+-------------------------------+------------+---------------------------------+ -| ``s.issubset(t)`` | ``s <= t`` | test whether every element in | -| | | *s* is in *t* | -+-------------------------------+------------+---------------------------------+ -| ``s.issuperset(t)`` | ``s >= t`` | test whether every element in | -| | | *t* is in *s* | -+-------------------------------+------------+---------------------------------+ -| ``s.union(t)`` | *s* \| *t* | new set with elements from both | -| | | *s* and *t* | -+-------------------------------+------------+---------------------------------+ -| ``s.intersection(t)`` | *s* & *t* | new set with elements common to | -| | | *s* and *t* | -+-------------------------------+------------+---------------------------------+ -| ``s.difference(t)`` | *s* - *t* | new set with elements in *s* | -| | | but not in *t* | -+-------------------------------+------------+---------------------------------+ -| ``s.symmetric_difference(t)`` | *s* ^ *t* | new set with elements in either | -| | | *s* or *t* but not both | -+-------------------------------+------------+---------------------------------+ -| ``s.copy()`` | | new set with a shallow copy of | -| | | *s* | -+-------------------------------+------------+---------------------------------+ +.. describe:: len(s) + + Return the cardinality of set *s*. + +.. describe:: x in s + + Test *x* for membership in *s*. + +.. describe:: x not in s + + Test *x* for non-membership in *s*. + +.. method:: set.issubset(other) + set <= other + + Test whether every element in the set is in *other*. + +.. method:: set.issuperset(other) + set >= other + + Test whether every element in *other* is in the set. + +.. method:: set.union(other) + set | other + + Return a new set with elements from both sets. + +.. method:: set.intersection(other) + set & other + + Return a new set with elements common to both sets. + +.. method:: set.difference(other) + set - other + + Return a new set with elements in the set that are not in *other*. + +.. method:: set.symmetric_difference(other) + set ^ other + + Return a new set with elements in either the set or *other* but not both. + +.. method:: set.copy() + + Return a new set with a shallow copy of *s*. + Note, the non-operator versions of :meth:`union`, :meth:`intersection`, :meth:`difference`, and :meth:`symmetric_difference`, :meth:`issubset`, and @@ -1505,38 +1501,48 @@ The following table lists operations available for :class:`set` that do not apply to immutable instances of :class:`frozenset`: -+--------------------------------------+-------------+---------------------------------+ -| Operation | Equivalent | Result | -+======================================+=============+=================================+ -| ``s.update(t)`` | *s* \|= *t* | update set *s*, adding elements | -| | | from *t* | -+--------------------------------------+-------------+---------------------------------+ -| ``s.intersection_update(t)`` | *s* &= *t* | update set *s*, keeping only | -| | | elements found in both *s* and | -| | | *t* | -+--------------------------------------+-------------+---------------------------------+ -| ``s.difference_update(t)`` | *s* -= *t* | update set *s*, removing | -| | | elements found in *t* | -+--------------------------------------+-------------+---------------------------------+ -| ``s.symmetric_difference_update(t)`` | *s* ^= *t* | update set *s*, keeping only | -| | | elements found in either *s* or | -| | | *t* but not in both | -+--------------------------------------+-------------+---------------------------------+ -| ``s.add(x)`` | | add element *x* to set *s* | -+--------------------------------------+-------------+---------------------------------+ -| ``s.remove(x)`` | | remove *x* from set *s*; raises | -| | | :exc:`KeyError` if not present | -+--------------------------------------+-------------+---------------------------------+ -| ``s.discard(x)`` | | removes *x* from set *s* if | -| | | present | -+--------------------------------------+-------------+---------------------------------+ -| ``s.pop()`` | | remove and return an arbitrary | -| | | element from *s*; raises | -| | | :exc:`KeyError` if empty | -+--------------------------------------+-------------+---------------------------------+ -| ``s.clear()`` | | remove all elements from set | -| | | *s* | -+--------------------------------------+-------------+---------------------------------+ +.. method:: set.update(other) + set |= other + + Update the set, adding elements from *other*. + +.. method:: set.intersection_update(other) + set &= other + + Update the set, keeping only elements found in it and *other*. + +.. method:: set.difference_update(other) + set -= other + + Update the set, removing elements found in *other*. + +.. method:: set.symmetric_difference_update(other) + set ^= other + + Update the set, keeping only elements found in either set, but not in both. + +.. method:: set.add(el) + + Add element *el* to the set. + +.. method:: set.remove(el) + + Remove element *el* from the set. Raises :exc:`KeyError` if *el* is not + contained in the set. + +.. method:: set.discard(el) + + Remove element *el* from the set if it is present. + +.. method:: set.pop() + + Remove and return an arbitrary element from the set. Raises :exc:`KeyError` + if the set is empty. + +.. method:: set.clear() + + Remove all elements from the set. + Note, the non-operator versions of the :meth:`update`, :meth:`intersection_update`, :meth:`difference_update`, and @@ -1552,173 +1558,216 @@ .. index:: object: mapping object: dictionary + triple: operations on; mapping; types + triple: operations on; dictionary; type + statement: del + builtin: len -A :dfn:`mapping` object maps immutable values to arbitrary objects. Mappings +A :dfn:`mapping` object maps immutable values to arbitrary objects. Mappings are mutable objects. There is currently only one standard mapping type, the -:dfn:`dictionary`. A dictionary's keys are almost arbitrary values. Only +:dfn:`dictionary`. A dictionary's keys are *almost* arbitrary values. Only values containing lists, dictionaries or other mutable types (that are compared by value rather than by object identity) may not be used as keys. Numeric types used for keys obey the normal rules for numeric comparison: if two numbers compare equal (such as ``1`` and ``1.0``) then they can be used interchangeably to index the same dictionary entry. -Dictionaries are created by placing a comma-separated list of ``key: value`` +Dictionaries can be created by placing a comma-separated list of ``key: value`` pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098: -'jack', 4127: 'sjoerd'}``. +'jack', 4127: 'sjoerd'}``, or by the :class:`dict` constructor. -.. index:: - triple: operations on; mapping; types - triple: operations on; dictionary; type - statement: del - builtin: len - single: clear() (dictionary method) - single: copy() (dictionary method) - single: has_key() (dictionary method) - single: fromkeys() (dictionary method) - single: items() (dictionary method) - single: keys() (dictionary method) - single: update() (dictionary method) - single: values() (dictionary method) - single: get() (dictionary method) - single: setdefault() (dictionary method) - single: pop() (dictionary method) - single: popitem() (dictionary method) - single: iteritems() (dictionary method) - single: iterkeys() (dictionary method) - single: itervalues() (dictionary method) - -The following operations are defined on mappings (where *a* and *b* are -mappings, *k* is a key, and *v* and *x* are arbitrary objects): - -+--------------------------------+---------------------------------+-----------+ -| Operation | Result | Notes | -+================================+=================================+===========+ -| ``len(a)`` | the number of items in *a* | | -+--------------------------------+---------------------------------+-----------+ -| ``a[k]`` | the item of *a* with key *k* | (1), (10) | -+--------------------------------+---------------------------------+-----------+ -| ``a[k] = v`` | set ``a[k]`` to *v* | | -+--------------------------------+---------------------------------+-----------+ -| ``del a[k]`` | remove ``a[k]`` from *a* | \(1) | -+--------------------------------+---------------------------------+-----------+ -| ``a.clear()`` | remove all items from ``a`` | | -+--------------------------------+---------------------------------+-----------+ -| ``a.copy()`` | a (shallow) copy of ``a`` | | -+--------------------------------+---------------------------------+-----------+ -| ``k in a`` | ``True`` if *a* has a key *k*, | \(2) | -| | else ``False`` | | -+--------------------------------+---------------------------------+-----------+ -| ``k not in a`` | Equivalent to ``not`` *k* in | \(2) | -| | *a* | | -+--------------------------------+---------------------------------+-----------+ -| ``a.has_key(k)`` | Equivalent to *k* ``in`` *a*, | | -| | use that form in new code | | -+--------------------------------+---------------------------------+-----------+ -| ``a.items()`` | a copy of *a*'s list of (*key*, | \(3) | -| | *value*) pairs | | -+--------------------------------+---------------------------------+-----------+ -| ``a.keys()`` | a copy of *a*'s list of keys | \(3) | -+--------------------------------+---------------------------------+-----------+ -| ``a.update([b])`` | updates *a* with key/value | \(9) | -| | pairs from *b*, overwriting | | -| | existing keys, returns ``None`` | | -+--------------------------------+---------------------------------+-----------+ -| ``a.fromkeys(seq[, value])`` | Creates a new dictionary with | \(7) | -| | keys from *seq* and values set | | -| | to *value* | | -+--------------------------------+---------------------------------+-----------+ -| ``a.values()`` | a copy of *a*'s list of values | \(3) | -+--------------------------------+---------------------------------+-----------+ -| ``a.get(k[, x])`` | ``a[k]`` if ``k in a``, else | \(4) | -| | *x* | | -+--------------------------------+---------------------------------+-----------+ -| ``a.setdefault(k[, x])`` | ``a[k]`` if ``k in a``, else | \(5) | -| | *x* (also setting it) | | -+--------------------------------+---------------------------------+-----------+ -| ``a.pop(k[, x])`` | ``a[k]`` if ``k in a``, else | \(8) | -| | *x* (and remove k) | | -+--------------------------------+---------------------------------+-----------+ -| ``a.popitem()`` | remove and return an arbitrary | \(6) | -| | (*key*, *value*) pair | | -+--------------------------------+---------------------------------+-----------+ -| ``a.iteritems()`` | return an iterator over (*key*, | (2), (3) | -| | *value*) pairs | | -+--------------------------------+---------------------------------+-----------+ -| ``a.iterkeys()`` | return an iterator over the | (2), (3) | -| | mapping's keys | | -+--------------------------------+---------------------------------+-----------+ -| ``a.itervalues()`` | return an iterator over the | (2), (3) | -| | mapping's values | | -+--------------------------------+---------------------------------+-----------+ +.. class:: dict([arg]) -Notes: + Return a new dictionary initialized from an optional positional argument or from + a set of keyword arguments. If no arguments are given, return a new empty + dictionary. If the positional argument *arg* is a mapping object, return a + dictionary mapping the same keys to the same values as does the mapping object. + Otherwise the positional argument must be a sequence, a container that supports + iteration, or an iterator object. The elements of the argument must each also + be of one of those kinds, and each must in turn contain exactly two objects. + The first is used as a key in the new dictionary, and the second as the key's + value. If a given key is seen more than once, the last value associated with it + is retained in the new dictionary. -(1) - Raises a :exc:`KeyError` exception if *k* is not in the map. + If keyword arguments are given, the keywords themselves with their associated + values are added as items to the dictionary. If a key is specified both in the + positional argument and as a keyword argument, the value associated with the + keyword is retained in the dictionary. For example, these all return a + dictionary equal to ``{"one": 2, "two": 3}``: + + * ``dict({'one': 2, 'two': 3})`` + + * ``dict({'one': 2, 'two': 3}.items())`` + + * ``dict({'one': 2, 'two': 3}.iteritems())`` + + * ``dict(zip(('one', 'two'), (2, 3)))`` + + * ``dict([['two', 3], ['one', 2]])`` + + * ``dict(one=2, two=3)`` + + * ``dict([(['one', 'two'][i-2], i) for i in (2, 3)])`` -(2) .. versionadded:: 2.2 -(3) - Keys and values are listed in an arbitrary order which is non-random, varies - across Python implementations, and depends on the dictionary's history of - insertions and deletions. If :meth:`items`, :meth:`keys`, :meth:`values`, - :meth:`iteritems`, :meth:`iterkeys`, and :meth:`itervalues` are called with no - intervening modifications to the dictionary, the lists will directly correspond. - This allows the creation of ``(value, key)`` pairs using :func:`zip`: ``pairs = - zip(a.values(), a.keys())``. The same relationship holds for the - :meth:`iterkeys` and :meth:`itervalues` methods: ``pairs = zip(a.itervalues(), - a.iterkeys())`` provides the same value for ``pairs``. Another way to create the - same list is ``pairs = [(v, k) for (k, v) in a.iteritems()]``. + .. versionchanged:: 2.3 + Support for building a dictionary from keyword arguments added. -(4) - Never raises an exception if *k* is not in the map, instead it returns *x*. *x* - is optional; when *x* is not provided and *k* is not in the map, ``None`` is - returned. -(5) - :func:`setdefault` is like :func:`get`, except that if *k* is missing, *x* is - both returned and inserted into the dictionary as the value of *k*. *x* defaults - to ``None``. +These are the operations that dictionaries support (and therefore, custom mapping +types should support too): -(6) - :func:`popitem` is useful to destructively iterate over a dictionary, as often - used in set algorithms. If the dictionary is empty, calling :func:`popitem` - raises a :exc:`KeyError`. +.. describe:: len(d) + + Return the number of items in the dictionary *d*. + +.. describe:: d[key] + + Return the item of *d* with key *key*. Raises a :exc:`KeyError` if *key* is + not in the map. + + .. versionadded:: 2.5 + If a subclass of dict defines a method :meth:`__missing__`, if the key + *key* is not present, the ``d[key]`` operation calls that method with the + key *key* as argument. The ``d[key]`` operation then returns or raises + whatever is returned or raised by the ``__missing__(key)`` call if the key + is not present. No other operations or methods invoke + :meth:`__missing__`. If :meth:`__missing__` is not defined, + :exc:`KeyError` is raised. :meth:`__missing__` must be a method; it + cannot be an instance variable. For an example, see + :class:`collections.defaultdict`. + +.. describe:: d[key] = value + + Set ``d[key]`` to *value*. + +.. describe:: del d[key] + + Remove ``d[key]`` from *d*. Raises a :exc:`KeyError` if *key* is not in the + map. + +.. describe:: key in d + + Return ``True`` if *d* has a key *key*, else ``False``. + + .. versionadded:: 2.2 + +.. describe:: key not in d + + Equivalent to ``not key in d``. + + .. versionadded:: 2.2 + +.. method:: dict.clear() + + Remove all items from the dictionary. + +.. method:: dict.copy() + + Return a shallow copy of the dictionary. + +.. method:: dict.fromkeys(seq[, value]) + + Create a new dictionary with keys from *seq* and values set to *value*. -(7) :func:`fromkeys` is a class method that returns a new dictionary. *value* defaults to ``None``. .. versionadded:: 2.3 -(8) - :func:`pop` raises a :exc:`KeyError` when no default value is given and the key - is not found. +.. method:: dict.get(key[, default]) + + Return the value for *key* if *key* is in the dictionary, else *default*. If + *default* is not given, it defaults to ``None``, so that this method never + raises a :exc:`KeyError`. + +.. method:: dict.has_key(key) + + ``d.has_key(key)`` is equivalent to ``key in d``, but deprecated. + +.. method:: dict.items() + + Return a copy of the dictionary's list of ``(key, value)`` pairs. + + .. note:: + + Keys and values are listed in an arbitrary order which is non-random, varies + across Python implementations, and depends on the dictionary's history of + insertions and deletions. If :meth:`items`, :meth:`keys`, :meth:`values`, + :meth:`iteritems`, :meth:`iterkeys`, and :meth:`itervalues` are called with no + intervening modifications to the dictionary, the lists will directly correspond. + This allows the creation of ``(value, key)`` pairs using :func:`zip`: ``pairs = + zip(d.values(), d.keys())``. The same relationship holds for the + :meth:`iterkeys` and :meth:`itervalues` methods: ``pairs = zip(d.itervalues(), + d.iterkeys())`` provides the same value for ``pairs``. Another way to create the + same list is ``pairs = [(v, k) for (k, v) in d.iteritems()]``. + +.. method:: dict.iteritems() + + Return an iterator over the dictionary's ``(key, value)`` pairs. + See the note for :meth:`dict.items`. + + .. versionadded:: 2.2 + +.. method:: dict.iterkeys() + + Return an iterator over the dictionary's keys. See the note for + :meth:`dict.items`. + + .. versionadded:: 2.2 + +.. method:: dict.itervalues() + + Return an iterator over the dictionary's values. See the note for + :meth:`dict.items`. + + .. versionadded:: 2.2 + +.. method:: dict.keys() + + Return a copy of the dictionary's list of keys. See the note for + :meth:`dict.items`. + +.. method:: dict.pop(key[, default]) + + If *key* is in the dictionary, remove it and return its value, else return + *default*. If *default* is not given and *key* is not in the dictionary, a + :exc:`KeyError` is raised. .. versionadded:: 2.3 -(9) - :func:`update` accepts either another mapping object or an iterable of key/value - pairs (as a tuple or other iterable of length two). If keyword arguments are - specified, the mapping is then is updated with those key/value pairs: - ``d.update(red=1, blue=2)``. +.. method:: dict.popitem() + + Remove and return an arbitrary ``(key, value)`` pair from the dictionary. + + :func:`popitem` is useful to destructively iterate over a dictionary, as + often used in set algorithms. If the dictionary is empty, calling + :func:`popitem` raises a :exc:`KeyError`. + +.. method:: dict.setdefault(key[, default]) + + If *key* is in the dictionary, return its value. If not, insert *key* with a + value of *default* and return *default*. *default* defaults to ``None``. + +.. method:: dict.update([other]) + + Update the dictionary with the key/value pairs from *other*, overwriting existing + keys. Return ``None``. + + :func:`update` accepts either another dictionary object or an iterable of + key/value pairs (as a tuple or other iterable of length two). If keyword + arguments are specified, the dictionary is then is updated with those + key/value pairs: ``d.update(red=1, blue=2)``. .. versionchanged:: 2.4 - Allowed the argument to be an iterable of key/value pairs and allowed keyword - arguments. + Allowed the argument to be an iterable of key/value pairs and allowed + keyword arguments. -(10) - If a subclass of dict defines a method :meth:`__missing__`, if the key *k* is - not present, the ``a[k]`` operation calls that method with the key *k* as - argument. The ``a[k]`` operation then returns or raises whatever is returned - or raised by the ``__missing__(k)`` call if the key is not present. No other - operations or methods invoke :meth:`__missing__`. If :meth:`__missing__` is - not defined, :exc:`KeyError` is raised. :meth:`__missing__` must be a - method; it cannot be an instance variable. For an example, see - :class:`collections.defaultdict`. +.. method:: dict.values() - .. versionadded:: 2.5 + Return a copy of the dictionary's list of values. See the note for + :meth:`mapping.items`. .. _bltin-file-objects: Modified: doctools/trunk/Doc-3k/library/string.rst ============================================================================== --- doctools/trunk/Doc-3k/library/string.rst (original) +++ doctools/trunk/Doc-3k/library/string.rst Mon Aug 6 18:50:04 2007 @@ -15,7 +15,7 @@ :ref:`typesseq` section, and also the string-specific methods described in the :ref:`string-methods` section. To output formatted strings use template strings or the ``%`` operator described in the -:ref:`typesseq-strings` section. Also, see the :mod:`re` module for +:ref:`string-formatting` section. Also, see the :mod:`re` module for string functions based on regular expressions. Modified: doctools/trunk/Doc-3k/library/strings.rst ============================================================================== --- doctools/trunk/Doc-3k/library/strings.rst (original) +++ doctools/trunk/Doc-3k/library/strings.rst Mon Aug 6 18:50:04 2007 @@ -12,7 +12,7 @@ methods described in the :ref:`typesseq` section, and also the string-specific methods described in the :ref:`string-methods` section. To output formatted strings use template strings or the ``%`` operator -described in the :ref:`typesseq-strings` section. Also, see the +described in the :ref:`string-formatting` section. Also, see the :mod:`re` module for string functions based on regular expressions. Modified: doctools/trunk/Doc-3k/reference/datamodel.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/datamodel.rst (original) +++ doctools/trunk/Doc-3k/reference/datamodel.rst Mon Aug 6 18:50:04 2007 @@ -1699,40 +1699,6 @@ Emulating container types ------------------------- -.. index:: - single: keys() (mapping object method) - single: values() (mapping object method) - single: items() (mapping object method) - single: iterkeys() (mapping object method) - single: itervalues() (mapping object method) - single: iteritems() (mapping object method) - single: has_key() (mapping object method) - single: get() (mapping object method) - single: setdefault() (mapping object method) - single: pop() (mapping object method) - single: popitem() (mapping object method) - single: clear() (mapping object method) - single: copy() (mapping object method) - single: update() (mapping object method) - single: __contains__() (mapping object method) - single: append() (sequence object method) - single: count() (sequence object method) - single: extend() (sequence object method) - single: index() (sequence object method) - single: insert() (sequence object method) - single: pop() (sequence object method) - single: remove() (sequence object method) - single: reverse() (sequence object method) - single: sort() (sequence object method) - single: __add__() (sequence object method) - single: __radd__() (sequence object method) - single: __iadd__() (sequence object method) - single: __mul__() (sequence object method) - single: __rmul__() (sequence object method) - single: __imul__() (sequence object method) - single: __contains__() (sequence object method) - single: __iter__() (sequence object method) - The following methods can be defined to implement container objects. Containers usually are sequences (such as lists or tuples) or mappings (like dictionaries), but can represent other containers as well. The first set of methods is used @@ -1765,7 +1731,7 @@ values. -.. method:: container object.__len__(self) +.. method:: object.__len__(self) .. index:: builtin: len @@ -1777,7 +1743,7 @@ considered to be false in a Boolean context. -.. method:: container object.__getitem__(self, key) +.. method:: object.__getitem__(self, key) .. index:: object: slice @@ -1796,7 +1762,7 @@ indexes to allow proper detection of the end of the sequence. -.. method:: container object.__setitem__(self, key, value) +.. method:: object.__setitem__(self, key, value) Called to implement assignment to ``self[key]``. Same note as for :meth:`__getitem__`. This should only be implemented for mappings if the @@ -1805,7 +1771,7 @@ for improper *key* values as for the :meth:`__getitem__` method. -.. method:: container object.__delitem__(self, key) +.. method:: object.__delitem__(self, key) Called to implement deletion of ``self[key]``. Same note as for :meth:`__getitem__`. This should only be implemented for mappings if the @@ -1814,7 +1780,7 @@ values as for the :meth:`__getitem__` method. -.. method:: container object.__iter__(self) +.. method:: object.__iter__(self) This method is called when an iterator is required for a container. This method should return a new iterator object that can iterate over all the objects in the @@ -1830,7 +1796,7 @@ also does not require the object be a sequence. -.. method:: container object.__contains__(self, item) +.. method:: object.__contains__(self, item) Called to implement membership test operators. Should return true if *item* is in *self*, false otherwise. For mapping objects, this should consider the keys @@ -1847,7 +1813,7 @@ :meth:`__getslice__`; mutable sequences might define all three methods. -.. method:: sequence object.__getslice__(self, i, j) +.. method:: object.__getslice__(self, i, j) .. deprecated:: 2.0 Support slice objects as parameters to the :meth:`__getitem__` method. @@ -1863,7 +1829,7 @@ is created instead, and passed to :meth:`__getitem__` instead. -.. method:: sequence object.__setslice__(self, i, j, sequence) +.. method:: object.__setslice__(self, i, j, sequence) Called to implement assignment to ``self[i:j]``. Same notes for *i* and *j* as for :meth:`__getslice__`. @@ -1873,7 +1839,7 @@ :meth:`__setitem__`, instead of :meth:`__setslice__` being called. -.. method:: sequence object.__delslice__(self, i, j) +.. method:: object.__delslice__(self, i, j) Called to implement deletion of ``self[i:j]``. Same notes for *i* and *j* as for :meth:`__getslice__`. This method is deprecated. If no :meth:`__delslice__` is @@ -1937,18 +1903,18 @@ left undefined. -.. method:: numeric object.__add__(self, other) - numeric object.__sub__(self, other) - numeric object.__mul__(self, other) - numeric object.__floordiv__(self, other) - numeric object.__mod__(self, other) - numeric object.__divmod__(self, other) - numeric object.__pow__(self, other[, modulo]) - numeric object.__lshift__(self, other) - numeric object.__rshift__(self, other) - numeric object.__and__(self, other) - numeric object.__xor__(self, other) - numeric object.__or__(self, other) +.. method:: object.__add__(self, other) + object.__sub__(self, other) + object.__mul__(self, other) + object.__floordiv__(self, other) + object.__mod__(self, other) + object.__divmod__(self, other) + object.__pow__(self, other[, modulo]) + object.__lshift__(self, other) + object.__rshift__(self, other) + object.__and__(self, other) + object.__xor__(self, other) + object.__or__(self, other) .. index:: builtin: divmod @@ -1969,8 +1935,8 @@ arguments, it should return ``NotImplemented``. -.. method:: numeric object.__div__(self, other) - numeric object.__truediv__(self, other) +.. method:: object.__div__(self, other) + object.__truediv__(self, other) The division operator (``/``) is implemented by these methods. The :meth:`__truediv__` method is used when ``__future__.division`` is in effect, @@ -1979,20 +1945,20 @@ will be raised instead. -.. method:: numeric object.__radd__(self, other) - numeric object.__rsub__(self, other) - numeric object.__rmul__(self, other) - numeric object.__rdiv__(self, other) - numeric object.__rtruediv__(self, other) - numeric object.__rfloordiv__(self, other) - numeric object.__rmod__(self, other) - numeric object.__rdivmod__(self, other) - numeric object.__rpow__(self, other) - numeric object.__rlshift__(self, other) - numeric object.__rrshift__(self, other) - numeric object.__rand__(self, other) - numeric object.__rxor__(self, other) - numeric object.__ror__(self, other) +.. method:: object.__radd__(self, other) + object.__rsub__(self, other) + object.__rmul__(self, other) + object.__rdiv__(self, other) + object.__rtruediv__(self, other) + object.__rfloordiv__(self, other) + object.__rmod__(self, other) + object.__rdivmod__(self, other) + object.__rpow__(self, other) + object.__rlshift__(self, other) + object.__rrshift__(self, other) + object.__rand__(self, other) + object.__rxor__(self, other) + object.__ror__(self, other) .. index:: builtin: divmod @@ -2020,19 +1986,19 @@ subclasses to override their ancestors' operations. -.. method:: numeric object.__iadd__(self, other) - numeric object.__isub__(self, other) - numeric object.__imul__(self, other) - numeric object.__idiv__(self, other) - numeric object.__itruediv__(self, other) - numeric object.__ifloordiv__(self, other) - numeric object.__imod__(self, other) - numeric object.__ipow__(self, other[, modulo]) - numeric object.__ilshift__(self, other) - numeric object.__irshift__(self, other) - numeric object.__iand__(self, other) - numeric object.__ixor__(self, other) - numeric object.__ior__(self, other) +.. method:: object.__iadd__(self, other) + object.__isub__(self, other) + object.__imul__(self, other) + object.__idiv__(self, other) + object.__itruediv__(self, other) + object.__ifloordiv__(self, other) + object.__imod__(self, other) + object.__ipow__(self, other[, modulo]) + object.__ilshift__(self, other) + object.__irshift__(self, other) + object.__iand__(self, other) + object.__ixor__(self, other) + object.__ior__(self, other) These methods are called to implement the augmented arithmetic operations (``+=``, ``-=``, ``*=``, ``/=``, ``//=``, ``%=``, ``**=``, ``<<=``, ``>>=``, @@ -2046,10 +2012,10 @@ and ``y.__radd__(x)`` are considered, as with the evaluation of *x*``+``*y*. -.. method:: numeric object.__neg__(self) - numeric object.__pos__(self) - numeric object.__abs__(self) - numeric object.__invert__(self) +.. method:: object.__neg__(self) + object.__pos__(self) + object.__abs__(self) + object.__invert__(self) .. index:: builtin: abs @@ -2057,10 +2023,10 @@ and ``~``). -.. method:: numeric object.__complex__(self) - numeric object.__int__(self) - numeric object.__long__(self) - numeric object.__float__(self) +.. method:: object.__complex__(self) + object.__int__(self) + object.__long__(self) + object.__float__(self) .. index:: builtin: complex @@ -2072,7 +2038,7 @@ :func:`long`, and :func:`float`. Should return a value of the appropriate type. -.. method:: numeric object.__index__(self) +.. method:: object.__index__(self) Called to implement :func:`operator.index`. Also called whenever Python needs an integer object (such as in slicing, or in the built-in :func:`bin`, @@ -2105,14 +2071,14 @@ For more information on context managers, see :ref:`typecontextmanager`. -.. method:: context manager.__enter__(self) +.. method:: object.__enter__(self) Enter the runtime context related to this object. The :keyword:`with` statement will bind this method's return value to the target(s) specified in the :keyword:`as` clause of the statement, if any. -.. method:: context manager.__exit__(self, exc_type, exc_value, traceback) +.. method:: object.__exit__(self, exc_type, exc_value, traceback) Exit the runtime context related to this object. The parameters describe the exception that caused the context to be exited. If the context was exited Modified: doctools/trunk/Doc-3k/reference/expressions.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/expressions.rst (original) +++ doctools/trunk/Doc-3k/reference/expressions.rst Mon Aug 6 18:50:04 2007 @@ -854,7 +854,7 @@ In addition to performing the modulo operation on numbers, the ``%`` operator is also overloaded by string and unicode objects to perform string formatting (also known as interpolation). The syntax for string formatting is described in the -Python Library Reference, section :ref:`typesseq-strings`. +Python Library Reference, section :ref:`string-formatting`. .. deprecated:: 2.3 The floor division operator, the modulo operator, and the :func:`divmod` Modified: doctools/trunk/Doc-3k/tutorial/introduction.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/introduction.rst (original) +++ doctools/trunk/Doc-3k/tutorial/introduction.rst Mon Aug 6 18:50:04 2007 @@ -379,7 +379,7 @@ Both strings and Unicode strings support a large number of methods for basic transformations and searching. - :ref:`typesseq-strings` + :ref:`string-formatting` The formatting operations invoked when strings and Unicode strings are the left operand of the ``%`` operator are described in more detail here. Modified: doctools/trunk/sphinx/highlighting.py ============================================================================== --- doctools/trunk/sphinx/highlighting.py (original) +++ doctools/trunk/sphinx/highlighting.py Mon Aug 6 18:50:04 2007 @@ -64,7 +64,7 @@ # maybe Python -- try parsing it try: parser.suite(source + '\n') - except SyntaxError: + except (SyntaxError, UnicodeEncodeError): return '
      ' + cgi.escape(source) + '
      \n' else: lexer = lexers['python'] From python-checkins at python.org Mon Aug 6 18:51:47 2007 From: python-checkins at python.org (georg.brandl) Date: Mon, 6 Aug 2007 18:51:47 +0200 (CEST) Subject: [Python-checkins] r56772 - in doctools/trunk/sphinx: style/doctools.js writer.py Message-ID: <20070806165147.972311E4006@bag.python.org> Author: georg.brandl Date: Mon Aug 6 18:51:47 2007 New Revision: 56772 Modified: doctools/trunk/sphinx/style/doctools.js doctools/trunk/sphinx/writer.py Log: Add header links statically. Modified: doctools/trunk/sphinx/style/doctools.js ============================================================================== --- doctools/trunk/sphinx/style/doctools.js (original) +++ doctools/trunk/sphinx/style/doctools.js Mon Aug 6 18:51:47 2007 @@ -94,7 +94,7 @@ var Documentation = { init : function() { - this.addContextElements(); + /* this.addContextElements(); -- now done statically */ this.fixFirefoxAnchorBug(); this.highlightSearchWords(); this.initModIndex(); Modified: doctools/trunk/sphinx/writer.py ============================================================================== --- doctools/trunk/sphinx/writer.py (original) +++ doctools/trunk/sphinx/writer.py Mon Aug 6 18:51:47 2007 @@ -54,6 +54,9 @@ if node.parent['desctype'] in ('class', 'exception'): self.body.append('%s ' % node.parent['desctype']) def depart_desc_signature(self, node): + if node['ids']: + self.body.append(u'\u00B6') self.body.append('\n') def visit_desc_classname(self, node): @@ -202,6 +205,16 @@ def depart_literal_emphasis(self, node): return self.depart_emphasis(node) + def depart_title(self, node): + close_tag = self.context[-1] + if close_tag.startswith(('\u00B6') + BaseTranslator.depart_title(self, node) + class SmartyPantsHTMLTranslator(HTMLTranslator): """ From python-checkins at python.org Mon Aug 6 18:54:17 2007 From: python-checkins at python.org (georg.brandl) Date: Mon, 6 Aug 2007 18:54:17 +0200 (CEST) Subject: [Python-checkins] r56773 - doctools/trunk/sphinx/builder.py Message-ID: <20070806165417.695BA1E4006@bag.python.org> Author: georg.brandl Date: Mon Aug 6 18:54:17 2007 New Revision: 56773 Modified: doctools/trunk/sphinx/builder.py Log: Apply config overrides before searching for version info. Modified: doctools/trunk/sphinx/builder.py ============================================================================== --- doctools/trunk/sphinx/builder.py (original) +++ doctools/trunk/sphinx/builder.py Mon Aug 6 18:54:17 2007 @@ -97,6 +97,8 @@ for key, val in self.config.items(): if isinstance(val, types.ModuleType): del self.config[key] + if confoverrides: + self.config.update(confoverrides) # replace version info if 'auto' if self.config['version'] == 'auto' or self.config['revision'] == 'auto': try: @@ -109,8 +111,6 @@ self.config['version'] = version if self.config['release'] == 'auto': self.config['release'] = release - if confoverrides: - self.config.update(confoverrides) self.status_stream = status_stream or sys.stdout self.warning_stream = warning_stream or sys.stderr From python-checkins at python.org Mon Aug 6 19:04:14 2007 From: python-checkins at python.org (georg.brandl) Date: Mon, 6 Aug 2007 19:04:14 +0200 (CEST) Subject: [Python-checkins] r56774 - doctools/trunk/sphinx/web/application.py Message-ID: <20070806170414.02FF91E400A@bag.python.org> Author: georg.brandl Date: Mon Aug 6 19:04:12 2007 New Revision: 56774 Modified: doctools/trunk/sphinx/web/application.py Log: Fix module index cloud size calculation. Modified: doctools/trunk/sphinx/web/application.py ============================================================================== --- doctools/trunk/sphinx/web/application.py (original) +++ doctools/trunk/sphinx/web/application.py Mon Aug 6 19:04:12 2007 @@ -340,7 +340,7 @@ most_frequent = heapq.nlargest(30, self.freqmodules.iteritems(), lambda x: x[1]) if most_frequent: - base_count = most_frequent[0][1] + base_count = most_frequent[-1][1] most_frequent = [{ 'name': x[0], 'size': 100 + math.log((x[1] - base_count) + 1) * 20, From python-checkins at python.org Mon Aug 6 20:19:06 2007 From: python-checkins at python.org (facundo.batista) Date: Mon, 6 Aug 2007 20:19:06 +0200 (CEST) Subject: [Python-checkins] r56775 - python/branches/decimal-branch/Lib/decimal.py Message-ID: <20070806181906.72DBE1E4006@bag.python.org> Author: facundo.batista Date: Mon Aug 6 20:19:06 2007 New Revision: 56775 Modified: python/branches/decimal-branch/Lib/decimal.py Log: Coded next_plus() function, all tests pass ok. Also cleaned slightly next_minus(). Modified: python/branches/decimal-branch/Lib/decimal.py ============================================================================== --- python/branches/decimal-branch/Lib/decimal.py (original) +++ python/branches/decimal-branch/Lib/decimal.py Mon Aug 6 20:19:06 2007 @@ -2698,21 +2698,68 @@ d = Decimal((newself._sign, newself._int+(0,)*expdif, newself._exp-expdif)) dif = Decimal((0, (0,)*(len(d._int)-1)+(1,), d._exp)) d = d - dif - if d._isinfinity(): - return d digdif = context.prec - len(d._int) if digdif > 0 and d._exp-digdif > context.Emin: d = Decimal((d._sign, d._int + (9,)*digdif, d._exp-digdif)) if d.adjusted() > context.Emax: - if d._sign: - return negInf - else: - return Inf + return negInf return d def next_plus(self, context=None): """Returns the smallest representable number larger than itself.""" + if context is None: + context = getcontext() + + ans = self._check_nans(self, context) + if ans: + return ans + + if self._isinfinity() == 1: + return self + if self._isinfinity() == -1: + return Decimal((1, (9,)*context.prec, context.Emax-context.prec+1)) + + minime = context.Emin-context.prec+1 + if self._exp < minime: + newself = Decimal((self._sign, self._int, minime)) + if newself._sign == 0: + return newself + else: + newself = Decimal(self) + + if not newself: + return Decimal((0, (1,), minime)) + expdif = context.prec - len(newself._int) + + if expdif < 0: + resto = newself._int[context.prec:] + if resto != (0,)*(-expdif): + # the rest is not all zeroes + d = newself._round_ceiling(context.prec, expdif, context) + return d + # negative expdif, but all zeroes + d = Decimal((newself._sign, newself._int[:expdif], newself._exp-expdif)) + else: + # positive expdif + if newself._exp-expdif < minime: + expdif = newself._exp - minime + d = Decimal((newself._sign, newself._int+(0,)*expdif, newself._exp-expdif)) + + dif = Decimal((0, (0,)*(len(d._int)-1)+(1,), d._exp)) + d = d + dif + if not d: + # restablish previos sign + d._sign = newself._sign + return d + + digdif = context.prec - len(d._int) + if digdif > 0 and d._exp-digdif > context.Emin: + d = Decimal((d._sign, d._int + (9,)*digdif, d._exp-digdif)) + if d.adjusted() > context.Emax: + return Inf + return d + def next_toward(self, other, context=None): """Returns the number closest to itself, in direction towards other. From python-checkins at python.org Mon Aug 6 21:05:14 2007 From: python-checkins at python.org (georg.brandl) Date: Mon, 6 Aug 2007 21:05:14 +0200 (CEST) Subject: [Python-checkins] r56776 - doctools/trunk/sphinx/builder.py Message-ID: <20070806190514.AC0BE1E400A@bag.python.org> Author: georg.brandl Date: Mon Aug 6 21:05:14 2007 New Revision: 56776 Modified: doctools/trunk/sphinx/builder.py Log: Fix a key name. Modified: doctools/trunk/sphinx/builder.py ============================================================================== --- doctools/trunk/sphinx/builder.py (original) +++ doctools/trunk/sphinx/builder.py Mon Aug 6 21:05:14 2007 @@ -100,7 +100,7 @@ if confoverrides: self.config.update(confoverrides) # replace version info if 'auto' - if self.config['version'] == 'auto' or self.config['revision'] == 'auto': + if self.config['version'] == 'auto' or self.config['release'] == 'auto': try: version, release = get_version_info(srcdirname) except (IOError, OSError): From python-checkins at python.org Mon Aug 6 22:13:26 2007 From: python-checkins at python.org (erik.forsberg) Date: Mon, 6 Aug 2007 22:13:26 +0200 (CEST) Subject: [Python-checkins] r56778 - tracker/importer/xmlexport2handlers.py Message-ID: <20070806201326.67C571E4011@bag.python.org> Author: erik.forsberg Date: Mon Aug 6 22:13:25 2007 New Revision: 56778 Modified: tracker/importer/xmlexport2handlers.py Log: Set 'link' in history of msg and file entries - this makes it easier to find which issue is related to each msg/file. Modified: tracker/importer/xmlexport2handlers.py ============================================================================== --- tracker/importer/xmlexport2handlers.py (original) +++ tracker/importer/xmlexport2handlers.py Mon Aug 6 22:13:25 2007 @@ -428,10 +428,18 @@ roundupdata['creator'], 'create', {})) db.setjournal("issue", nodeid, journal) - - - - - - - + + for fileid in roundupdata['files']: + fitem = db.getnode('file', fileid) + fj = [(fileid, fitem['creation'], fitem['creator'], 'link', + ('issue', nodeid, 'files')), + (fileid, fitem['creation'], fitem['creator'], 'create', {})] + db.setjournal('file', fileid, fj) + + for msgid in roundupdata['messages']: + mitem = db.getnode('msg', msgid) + fj = [(msgid, mitem['creation'], mitem['creator'], 'link', + ('issue', nodeid, 'messages')), + (msgid, mitem['creation'], mitem['creator'], 'create', {})] + db.setjournal('msg', msgid, fj) + From python-checkins at python.org Tue Aug 7 06:26:19 2007 From: python-checkins at python.org (brett.cannon) Date: Tue, 7 Aug 2007 06:26:19 +0200 (CEST) Subject: [Python-checkins] r56786 - in sandbox/trunk/import_in_py: docs docs/pseudocode.py pseudocode.py Message-ID: <20070807042619.1D27D1E4006@bag.python.org> Author: brett.cannon Date: Tue Aug 7 06:26:18 2007 New Revision: 56786 Added: sandbox/trunk/import_in_py/docs/ sandbox/trunk/import_in_py/docs/pseudocode.py - copied unchanged from r55955, sandbox/trunk/import_in_py/pseudocode.py Removed: sandbox/trunk/import_in_py/pseudocode.py Log: Move pseudocode to a docs directory. Deleted: /sandbox/trunk/import_in_py/pseudocode.py ============================================================================== --- /sandbox/trunk/import_in_py/pseudocode.py Tue Aug 7 06:26:18 2007 +++ (empty file) @@ -1,177 +0,0 @@ -raise ImportError("module is just pseudocode") - -import sys -def __import__(name, globals, locals, fromlist, level): - """Pseudocode to explain how importing works. - - Caveats: - + Classic relative import semantics are not covered. - + Assume all code runs with the import lock held. - + Some structure (e.g., using importers for built-in and frozen - modules) is purely conceptual and not used in the C - implementation of import. - - """ - path = globals.get('__path__') - # If a relative import, figure out absolute name of requested module. - if level != 0: - # Adjust relative import based on whether caller is a package and - # the specified level in the call. - # Also make sure import does not go beyond top-level. - name = resolve_name(name, globals['__name__'], path, level) - # Import each parent in the name, starting at the top. - # Assume each_parent iterates through each parent of the module request, - # starting at the top-level parent. - # Since loaders are required to set the module in sys.modules, a successful - # import should be followed by 'continue' to let the next module be - # imported. - for name in each_parent(name): - # If the module is already cached in sys.modules then move along. - if name in sys.modules: - continue - # Try to find a __path__ attribute on the (possibly non-existent) - # parent. - immediate_parent = name.rsplit('.', 1)[0] - try: - path = sys.modules[immediate_parent].__path__ - except (KeyError, AttributeError): - path = None - # Search sys.meta_path. - for meta_importer in sys.meta_path: - loader = meta_importer.find_module(name, path) - if loader: - loader.load_module(name) - continue - # Check built-in and frozen modules. - else: - for module_finder in (builtin_importer, frozen_importer): - loader = module_finder(name, path) - if loader: - loader.load_module(name) - continue - # With sys.meta_path, built-ins, and frozen modules checked, now look - # at sys.path or parent.__path__. - search_path = path if path else sys.path - for path_entry in search_path - # Look for a cached importer. - if path_entry in sys.path_importer_cache: - importer = sys.path_importer_cache[path_entry] - # Found an importer. - if importer: - loader = importer.find_module(name) - # If the import can handle the module, load it. Otherwise - # fall through to the default import. - if loader: - loader.load_module(name) - continue - # A pre-existing importer was not found; try to make one. - else: - for importer_factory in sys.path_hooks: - try: - # If an importer is found, cache it and try to use it. - # If it can't be used, then fall through to the default - # import. - importer = importer_factory(path_entry) - sys.path_importer_cache[path_entry] = importer - loader = importer.find_module(name) - if loader: - loader.load_module(name) - except ImportError: - continue - else: - # No importer could be created, so set to None in - # sys.path_import_cache to skip trying to make one in the - # future, then fall through to the default import. - sys.path_importer_cache[path_entry] = None - # As no importer was found for the sys.path entry, use the default - # importer for extension modules, Python bytecode, and Python - # source modules. - loader = find_extension_module(name, path_entry) - if loader: - loader.load_module(name) - continue - loader = find_py_pyc_module(name, path_entry) - if loader: - loader.load_module(name) - continue - # All available places to look for a module have been exhausted; raise - # an ImportError. - raise ImportError - # With the module now imported and store in sys.modules, figure out exactly - # what module to return based on fromlist and how the module name was - # specified. - if not fromlist: - # The fromlist is empty, so return the top-most parent module. - # Whether the import was relative or absolute must be considered. - if level: - return top_relative_name(name, level) - else: - return sys.modules[name.split('.', 1)[0]] - else: - # As fromlist is not empty, return the module specified by the import. - # Must also handle possible imports of modules if the module imported - # was a package and thus names in the fromlist are modules within the - # package and not object within a module. - module = sys.modules[name] - # If not a module, then can just return the module as the names - # specified in fromlist are supposed to be attributes on the module. - if not hasattr(module, '__path__'): - return module - # The imported module was a package, which means everything in the - # fromlist are supposed to be modules within the package. That means - # that an *attempt* must be made to try to import every name in - # fromlist. - if '*' in fromlist and hasattr(module, '__all__'): - fromlist = list(fromlist).extend(module.__all__) - for item in fromlist: - if item == '*': - continue - if not hasattr(module, item): - try: - __import__('.'.join([name, item]), module.__dict__, level=0) - except ImportError: - pass - return module - - -from imp import get_suffixes, C_EXTENSION -def find_extension_module(name, path_entry): - """Try to locate a C extension module for the requested module.""" - # Get the immediate name of the module being searched for as the extension - # module's file name will be based on it. - immediate_name = name.rsplit('.', 1)[-1] - # Check every possible C extension suffix with the immediate module name - # (typically two; '.so' and 'module.so'). - for suffix in (suffix[0] for suffix in get_suffixes() - if suffix[2] == C_EXTENSION): - file_path = os.path.join(path_entry, immediate_name + suffix) - if os.path.isfile(file_path): # I/O - return extension_loader(name, file_path) - else: - return None - - -from imp import PY_SOURCE, PY_COMPILED -def find_py_pyc_module(name, path_entry): - """Try to locate a Python source code or bytecode module for the requested - module.""" - # Get the immediate name of the module being imported as the Python file's - # name will be based on it. - immediate_name = name.rsplit('.', 1)[-1] - # Check every valid Python code suffix for possible files (typically two; - # '.py' and either '.pyc' or '.pyo'). - for suffix in (suffix[0] for suffix in get_suffixes() - if suffix[2] in (PY_SOURCE, PY_COMPILED)): - # See if the module is actually a package. - pkg_init_path = os.path.join(path_entry, immediate_name, - '__init__' + suffix) - if os.path.isfile(pkg_init_path): # I/O - return py_loader(name, pkg_init_path, is_pkg=True) - # If module is not a package, see if it is a file by itself. - file_path = os.path.join(path_entry, immediate_name + suffix) - if os.path.isfile(file_path): # I/O - return py_loader(name, file_path, is_pkg=False) - - -def py_loader(name, file_path, is_pkg): - pass From python-checkins at python.org Tue Aug 7 06:26:50 2007 From: python-checkins at python.org (brett.cannon) Date: Tue, 7 Aug 2007 06:26:50 +0200 (CEST) Subject: [Python-checkins] r56787 - sandbox/trunk/import_in_py/zipimport_ sandbox/trunk/import_in_py/zipimport_/__init__.py sandbox/trunk/import_in_py/zipimport_/tests.py sandbox/trunk/import_in_py/zipimport_/zipimport.py Message-ID: <20070807042650.C45CB1E4012@bag.python.org> Author: brett.cannon Date: Tue Aug 7 06:26:50 2007 New Revision: 56787 Added: sandbox/trunk/import_in_py/zipimport_/ sandbox/trunk/import_in_py/zipimport_/__init__.py (contents, props changed) sandbox/trunk/import_in_py/zipimport_/tests.py (contents, props changed) sandbox/trunk/import_in_py/zipimport_/zipimport.py (contents, props changed) Log: Begin a re-implementation of zipimport using importlib. Added: sandbox/trunk/import_in_py/zipimport_/__init__.py ============================================================================== Added: sandbox/trunk/import_in_py/zipimport_/tests.py ============================================================================== --- (empty file) +++ sandbox/trunk/import_in_py/zipimport_/tests.py Tue Aug 7 06:26:50 2007 @@ -0,0 +1,21 @@ +from zipimport_ import zipimport + +from test import test_support +import unittest + +class ZipImportErrorTests(unittest.TestCase): + + """Test ZipImportError.""" + + def test_inheritance(self): + # Should inherit from ImportError. + self.assert_(issubclass(zipimport.ZipImportError, ImportError)) + + + +def test_main(): + test_support.run_unittest(ZipImportErrorTests) + + +if __name__ == '__main__': + test_main() Added: sandbox/trunk/import_in_py/zipimport_/zipimport.py ============================================================================== --- (empty file) +++ sandbox/trunk/import_in_py/zipimport_/zipimport.py Tue Aug 7 06:26:50 2007 @@ -0,0 +1,42 @@ +"""A re-implementation of zipimport to use importlib.""" +import importlib + +import zipfile + + +class ZipImportError(ImportError): + pass + + +class zipimporter(object): + + """XXX Might need to implement 'archive', 'prefix' attributes.""" + + def __init__(self, archivepath): + """Open the specified zip file. + + Meant to be used from sys.path_hooks, meaning that if something other + than a zip file is passed in then ZipImportError is raised. + + """ + if not zipfile.is_zipfile(archivepath): + raise ZipImportError("the specified path must be a zip file") + self._zip = zipfile.ZipFile(archivepath, 'r') + + def find_module(self, fullname, path=None): + raise NotImplementedError + + def get_code(self, fullname): + raise NotImplementedError + + def get_data(self, fullname): + raise NotImplementedError + + def get_source(self, fullname): + raise NotImplementedError + + def is_package(self, fullname): + raise NotImplementedError + + def load_module(self, fullname): + raise NotImplementedError From python-checkins at python.org Tue Aug 7 06:58:53 2007 From: python-checkins at python.org (brett.cannon) Date: Tue, 7 Aug 2007 06:58:53 +0200 (CEST) Subject: [Python-checkins] r56788 - sandbox/trunk/import_in_py/zipimport_/tests.py Message-ID: <20070807045853.C86841E4007@bag.python.org> Author: brett.cannon Date: Tue Aug 7 06:58:53 2007 New Revision: 56788 Modified: sandbox/trunk/import_in_py/zipimport_/tests.py Log: Add tests for the constructor. Modified: sandbox/trunk/import_in_py/zipimport_/tests.py ============================================================================== --- sandbox/trunk/import_in_py/zipimport_/tests.py (original) +++ sandbox/trunk/import_in_py/zipimport_/tests.py Tue Aug 7 06:58:53 2007 @@ -1,7 +1,24 @@ from zipimport_ import zipimport +#import zipimport +import contextlib +import os from test import test_support import unittest +import zipfile + + at contextlib.contextmanager +def temp_zipfile(): + """Create a temporary zip file for testing.""" + path = test_support.TESTFN + '.zip' + zip_file = zipfile.ZipFile(path, 'w') + try: + zip_file.writestr('_top_level.py', 'attr = None') + zip_file.close() + yield path + finally: + os.unlink(path) + class ZipImportErrorTests(unittest.TestCase): @@ -12,9 +29,29 @@ self.assert_(issubclass(zipimport.ZipImportError, ImportError)) +class ZipImportCreation(unittest.TestCase): + + """Test the creation of a zipimport.zipimporter instance.""" + + def test_nonzip(self): + # ZipImportError should be raised if a non-zip file is specified. + with open(test_support.TESTFN, 'w') as test_file: + test_file.write("# Test file for zipimport.") + try: + self.assertRaises(zipimport.ZipImportError, + zipimport.zipimporter, test_support.TESTFN) + finally: + os.unlink(test_support.TESTFN) + + def test_zipfile(self): + # A zipfile should return an instance of zipimporter. + with temp_zipfile() as zip_path: + zip_importer = zipimport.zipimporter(zip_path) + self.assert_(isinstance(zip_importer, zipimport.zipimporter)) + def test_main(): - test_support.run_unittest(ZipImportErrorTests) + test_support.run_unittest(ZipImportErrorTests, ZipImportCreation) if __name__ == '__main__': From python-checkins at python.org Tue Aug 7 07:18:01 2007 From: python-checkins at python.org (brett.cannon) Date: Tue, 7 Aug 2007 07:18:01 +0200 (CEST) Subject: [Python-checkins] r56789 - sandbox/trunk/import_in_py/zipimport_/tests.py Message-ID: <20070807051801.3E6DF1E4006@bag.python.org> Author: brett.cannon Date: Tue Aug 7 07:18:00 2007 New Revision: 56789 Modified: sandbox/trunk/import_in_py/zipimport_/tests.py Log: Fix constructor tests. Modified: sandbox/trunk/import_in_py/zipimport_/tests.py ============================================================================== --- sandbox/trunk/import_in_py/zipimport_/tests.py (original) +++ sandbox/trunk/import_in_py/zipimport_/tests.py Tue Aug 7 07:18:00 2007 @@ -3,21 +3,32 @@ import contextlib import os +import py_compile from test import test_support import unittest import zipfile + @contextlib.contextmanager def temp_zipfile(): """Create a temporary zip file for testing.""" - path = test_support.TESTFN + '.zip' - zip_file = zipfile.ZipFile(path, 'w') + zip_path = test_support.TESTFN + '.zip' + zip_file = zipfile.ZipFile(zip_path, 'w') try: - zip_file.writestr('_top_level.py', 'attr = None') + for module_path in ['_top_level.py']: + with open(module_path, 'w') as temp_file: + temp_file.write('attr = None') + try: + py_compile.compile(module_path, doraise=True) + zip_file.write(module_path) + zip_file.write(module_path + 'c' if __debug__ else 'o') + finally: + test_support.unlink(module_path) + test_support.unlink(module_path + 'c' if __debug__ else 'o') zip_file.close() - yield path + yield zip_path finally: - os.unlink(path) + os.unlink(zip_path) class ZipImportErrorTests(unittest.TestCase): @@ -41,7 +52,7 @@ self.assertRaises(zipimport.ZipImportError, zipimport.zipimporter, test_support.TESTFN) finally: - os.unlink(test_support.TESTFN) + test_support.unlink(test_support.TESTFN) def test_zipfile(self): # A zipfile should return an instance of zipimporter. From python-checkins at python.org Tue Aug 7 07:48:33 2007 From: python-checkins at python.org (travis.oliphant) Date: Tue, 7 Aug 2007 07:48:33 +0200 (CEST) Subject: [Python-checkins] r56793 - peps/trunk/pep-3118.txt Message-ID: <20070807054833.390A51E4006@bag.python.org> Author: travis.oliphant Date: Tue Aug 7 07:48:32 2007 New Revision: 56793 Modified: peps/trunk/pep-3118.txt Log: A few changes to PEP 3118 prompted by its implementation Modified: peps/trunk/pep-3118.txt ============================================================================== --- peps/trunk/pep-3118.txt (original) +++ peps/trunk/pep-3118.txt Tue Aug 7 07:48:32 2007 @@ -175,7 +175,8 @@ simpler view of its memory. The exporter should always fill in all elements of the buffer -structure (with defaults if nothing else is requested). +structure (with defaults or NULLs if nothing else is requested). The +PyBuffer_FillInfo function can be used for simple cases. Some flags are useful for requesting a specific kind of memory segment, while others indicate to the exporter what kind of @@ -201,9 +202,10 @@ The returned buffer must be readonly. If the object is already read-only or it can make its memory read-only (and there are no - other views on the object) then it should do so and return the - buffer information. If the object does not have read-only memory - (or cannot make it read-only), then an error should be raised. + other writeable views on the object) then it should do so and + return the buffer information. If the object does not have + read-only memory (or cannot make it read-only), then an error + should be raised. ``PyBUF_REQ_FORMAT`` @@ -214,25 +216,21 @@ format is not explicitly requested then the format must be returned as ``NULL`` (which means "B") -``PyBUF_REQ_ALIGNED`` (implies ``PyBUF_REQ_FORMAT``) - - The returned buffer must have all (primitive data-type entries) - aligned as the compiler would align them - ``PyBUF_ALW_ND`` The returned buffer must provide shape information. The memory will be assumed C-style contiguous (last dimension varies the fastest). The exporter may raise an error if it cannot provide this kind of - contiguous buffer. + contiguous buffer. If this is not given then shape will be NULL. ``PyBUF_ALW_STRIDES`` (implies ``PyBUF_ALW_ND``) - The returned buffer must provide strides information. This would be - used when the consumer can handle strided, discontiguous arrays. - Handling strides automatically assumes you can handle shape. - The exporter may raise an error if cannot provide a strided-only - representation of the data (i.e. without the suboffsets). + The returned buffer must provide strides information (i.e. the + strides cannot be NULL). This would be used when the consumer can + handle strided, discontiguous arrays. Handling strides + automatically assumes you can handle shape. The exporter may raise + an error if cannot provide a strided-only representation of the + data (i.e. without the suboffsets). | ``PyBUF_REQ_C_CONTIGUOUS`` | ``PyBUF_REQ_F_CONTIGUOUS`` @@ -247,24 +245,25 @@ ``PyBUF_ALW_INDIRECT`` (implies ``PyBUF_ALW_STRIDES``) - The returned buffer must have suboffsets information. This would - be used when the consumer can handle indirect array referencing - implied by these suboffsets. + The returned buffer must have suboffsets information (which can be + NULL if no suboffsets are needed). This would be used when the + consumer can handle indirect array referencing implied by these + suboffsets. Specialized combinations of flags for specific kinds of memory_sharing. Multi-dimensional (but contiguous) - | ``PyBUF_CONTIG`` (``PyBUF_ALW_ND | PyBUF_REQ_WRITEABLE | PyBUF_REQ_ALIGNED``) - | ``PyBUF_CONTIG_RO`` (``PyBUF_ALW_ND | PyBUF_REQ_ALIGNED``) - | ``PyBUF_CONTIG_LCK`` (``PyBUF_ALW_ND | PyBUF_REQ_LOCKDATA | PyBUF_REQ_ALIGNED``) + | ``PyBUF_CONTIG`` (``PyBUF_ALW_ND | PyBUF_REQ_WRITEABLE``) + | ``PyBUF_CONTIG_RO`` (``PyBUF_ALW_ND``) + | ``PyBUF_CONTIG_LCK`` (``PyBUF_ALW_ND | PyBUF_REQ_LOCKDATA``) Multi-dimensional using strides but aligned - | ``PyBUF_STRIDED`` (``PyBUF_ALW_STRIDES | PyBUF_REQ_WRITEABLE | PyBUF_REQ_ALIGNED``) - | ``PyBUF_STRIDED_RO`` (``PyBUF_ALW_STRIDES | PyBUF_REQ_ALIGNED``) - | ``PyBUF_STRIDED_LCK`` (``PyBUF_ALW_STRIDES | PyBUF_REQ_LOCKDATA | PyBUF_REQ_ALIGNED``) + | ``PyBUF_STRIDED`` (``PyBUF_ALW_STRIDES | PyBUF_REQ_WRITEABLE``) + | ``PyBUF_STRIDED_RO`` (``PyBUF_ALW_STRIDES``) + | ``PyBUF_STRIDED_LCK`` (``PyBUF_ALW_STRIDES | PyBUF_REQ_LOCKDATA``) Multi-dimensional using strides and not necessarily aligned @@ -290,7 +289,6 @@ buffer info structure correctly according to the provided flags if a contiguous chunk of "unsigned bytes" is all that can be exported. - The bufferinfo structure is:: struct bufferinfo { @@ -357,7 +355,8 @@ if ``ndims`` is 0). indicating the number of bytes to skip to get to the next element in each dimension. If this is not requested by the caller (``PyBUF_ALW_STRIDES`` is not set), then this should be set - to NULL which indicates a C-style contiguous array. + to NULL which indicates a C-style contiguous array or a + PyExc_BufferError raised if this is not possible. ``suboffsets`` address of a ``Py_ssize_t *`` variable that will be filled with a @@ -368,7 +367,9 @@ suboffset value that it negative indicates that no de-referencing should occur (striding in a contiguous memory block). If all suboffsets are negative (i.e. no de-referencing is needed, then - this must be NULL (the default value). + this must be NULL (the default value). If this is not requested + by the caller (PyBUF_ALW_INDIRECT is not set), then this should be + set to NULL or an PyExc_BufferError raised if this is not possible. For clarity, here is a function that returns a pointer to the element in an N-D array pointed to by an N-dimesional index when @@ -395,7 +396,7 @@ ``itemsize`` This is a storage for the itemsize of each element of the shared - memory. It is strictly un-necessary as it can be obtained using + memory. It is technically un-necessary as it can be obtained using ``PyBuffer_SizeFromFormat``, however an exporter may know this information without parsing the format string and it is necessary to know the itemsize for proper interpretation of striding. @@ -420,9 +421,9 @@ The same bufferinfo struct should be used in the release-buffer interface call. The caller is responsible for the memory of the -bufferinfo structure itself. +PyBuffer structure itself. -``typedef int (*releasebufferproc)(PyObject *obj, PyBuffer *view)`` +``typedef void (*releasebufferproc)(PyObject *obj, PyBuffer *view)`` Callers of getbufferproc must make sure that this function is called when memory previously acquired from the object is no longer needed. The exporter of the interface must make sure that @@ -469,13 +470,11 @@ success. :: - - int PyObject_ReleaseBuffer(PyObject *obj, PyBuffer *view) + void PyObject_ReleaseBuffer(PyObject *obj, PyBuffer *view) This is a C-API version of the releasebuffer function call. It checks to make sure the object has the required function pointer and issues -the call. Returns 0 on success and -1 (with an error raised) on -failure. This function always succeeds if there is no releasebuffer +the call. This function always succeeds even if there is no releasebuffer function for the object. :: @@ -554,19 +553,24 @@ :: int PyObject_GetContiguous(PyObject *obj, void **buf, Py_ssize_t *len, - char **format, char fortran) + char **format, int writeable, char fortran) Return a contiguous chunk of memory representing the buffer. If a copy is made then return 1. If no copy was needed return 0. If an error occurred in probing the buffer interface, then return -1. The contiguous chunk of memory is pointed to by ``*buf`` and the length of -that memory is ``*len``. If the object is multi-dimensional, then if -fortran is 'F', the first dimension of the underlying array will vary -the fastest in the buffer. If fortran is 'C', then the last dimension -will vary the fastest (C-style contiguous). If fortran is 'A', then it -does not matter and you will get whatever the object decides is more -efficient. If a copy is made, then the memory must be freed by calling -``PyMem_Free``. +that memory is ``*len``. If writeable is 1, then the returned memory +must be writeable or else an error is raised. Otherwise, the memory +may or may not be writeable. If the object is multi-dimensional, then +if fortran is 'F', the first dimension of the underlying array will +vary the fastest in the buffer. If fortran is 'C', then the last +dimension will vary the fastest (C-style contiguous). If fortran is +'A', then it does not matter and you will get whatever the object +decides is more efficient. If a copy is made, then the memory must be +freed by calling ``PyMem_Free``. + +PyObject_ReleaseBuffer must be called on obj after you are done with the +memory even if a copy is made. :: @@ -579,11 +583,13 @@ object does not have a writeable buffer, then an error is raised. If fortran is 'F', then if the object is multi-dimensional, then the data will be copied into the array in Fortran-style (first dimension varies -the fastest). If fortran is 'C', then the data will be copied into the -array in C-style (last dimension varies the fastest). If fortran is 'A', then -it does not matter and the copy will be made in whatever way is more -efficient. +the fastest). If fortran is 'C', then the data will be copied into +the array in C-style (last dimension varies the fastest). If fortran +is 'A', then it does not matter and the copy will be made in whatever +way is more efficient. +:: + int PyObject_CopyData(PyObject *dest, PyObject *src) These last three C-API calls allow a standard way of getting data in and out of Python objects into contiguous memory areas no matter how it is @@ -600,19 +606,12 @@ :: - int PyBuffer_IsAligned(PyBuffer *view) - -Return 1 if the memory at all elements of the array implied by the -view object is aligned - -:: - - void PyBuffer_FillContiguousStrides(int *ndims, Py_ssize_t *shape, - int itemsize, - Py_ssize_t *strides, char fortran) + void PyBuffer_FillContiguousStrides(int ndim, Py_ssize_t *shape, + Py_ssize_t *strides, int itemsize, + char fortran) Fill the strides array with byte-strides of a contiguous (C-style if -fortran is 0 or Fortran-style if fortran is 1) array of the given +fortran is 'C' or Fortran-style if fortran is 'F' array of the given shape with the given number of bytes per element. :: @@ -627,7 +626,7 @@ :: - PyErr_BufferError + PyExc_BufferError A new error object for returning buffer errors which arise because an exporter cannot provide the kind of buffer that a consumer expects. @@ -754,6 +753,7 @@ * buffer object * bytes object * string object +* unicode object * array module * struct module * mmap module @@ -847,7 +847,7 @@ int Image_getbuffer(PyObject *self, PyBuffer *view, int flags) { - static Py_ssize_t suboffsets[2] = { -1, 0 }; + static Py_ssize_t suboffsets[2] = { 0, -1}; view->buf = self->lines; view->len = self->height*self->width; @@ -938,8 +938,10 @@ void *buf; Py_ssize_t len; char *format; + int copy; - if (PyObject_GetContiguous(obj, &buf, &len, &format, 0) < 0) { + copy = PyObject_GetContiguous(obj, &buf, &len, &format, 0, 'A'); + if (copy < 0) { /* error return */ } @@ -953,9 +955,12 @@ we could do */ - if (PyObject_CopyToObject(obj, buf, len, 0) < 0) { + if (PyObject_CopyToObject(obj, buf, len, 'A') < 0) { /* error return */ } + + /* Make sure that if a copy was made, the memory is freed */ + if (copy == 1) PyMem_Free(buf); Copyright From python-checkins at python.org Tue Aug 7 08:30:03 2007 From: python-checkins at python.org (georg.brandl) Date: Tue, 7 Aug 2007 08:30:03 +0200 (CEST) Subject: [Python-checkins] r56794 - in doctools/trunk/Doc-3k: library/runpy.rst library/xmlrpclib.rst tutorial/errors.rst whatsnew/2.5.rst Message-ID: <20070807063003.F2B9B1E4008@bag.python.org> Author: georg.brandl Date: Tue Aug 7 08:30:02 2007 New Revision: 56794 Modified: doctools/trunk/Doc-3k/library/runpy.rst doctools/trunk/Doc-3k/library/xmlrpclib.rst doctools/trunk/Doc-3k/tutorial/errors.rst doctools/trunk/Doc-3k/whatsnew/2.5.rst Log: Port rev. 56782. Modified: doctools/trunk/Doc-3k/library/runpy.rst ============================================================================== --- doctools/trunk/Doc-3k/library/runpy.rst (original) +++ doctools/trunk/Doc-3k/library/runpy.rst Tue Aug 7 08:30:02 2007 @@ -52,9 +52,11 @@ If the argument *alter_sys* is supplied and evaluates to ``True``, then ``sys.argv[0]`` is updated with the value of ``__file__`` and - ``sys.modules[__name__]`` is updated with a temporary module object for the - module being executed. Both ``sys.argv[0]`` and ``sys.modules[__name__]`` are - restored to their original values before the function returns. + ``sys.modules[__name__]`` is updated with a new module object for the module + being executed. Note that neither ``sys.argv[0]`` nor ``sys.modules[__name__]`` + are restored to their original values before the function returns -- if client + code needs these values preserved, it must either save them explicitly or + else avoid enabling the automatic alterations to :mod:`sys`. Note that this manipulation of :mod:`sys` is not thread-safe. Other threads may see the partially initialised module, as well as the altered list of arguments. Modified: doctools/trunk/Doc-3k/library/xmlrpclib.rst ============================================================================== --- doctools/trunk/Doc-3k/library/xmlrpclib.rst (original) +++ doctools/trunk/Doc-3k/library/xmlrpclib.rst Tue Aug 7 08:30:02 2007 @@ -101,10 +101,10 @@ When passing strings, characters special to XML such as ``<``, ``>``, and ``&`` will be automatically escaped. However, it's the caller's responsibility to ensure that the string is free of characters that aren't allowed in XML, such as - the control characters with ASCII values between 0 and 31; failing to do this - will result in an XML-RPC request that isn't well-formed XML. If you have to - pass arbitrary strings via XML-RPC, use the :class:`Binary` wrapper class - described below. + the control characters with ASCII values between 0 and 31 (except, of course, + tab, newline and carriage return); failing to do this will result in an XML-RPC + request that isn't well-formed XML. If you have to pass arbitrary strings via + XML-RPC, use the :class:`Binary` wrapper class described below. :class:`Server` is retained as an alias for :class:`ServerProxy` for backwards compatibility. New code should use :class:`ServerProxy`. Modified: doctools/trunk/Doc-3k/tutorial/errors.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/errors.rst (original) +++ doctools/trunk/Doc-3k/tutorial/errors.rst Tue Aug 7 08:30:02 2007 @@ -352,7 +352,8 @@ been executed. The :keyword:`finally` clause is also executed "on the way out" when any other clause of the :keyword:`try` statement is left via a :keyword:`break`, :keyword:`continue` or :keyword:`return` statement. A more -complicated example:: +complicated example (having :keyword:`except` and :keyword:`finally` clauses in +the same :keyword:`try` statement works as of Python 2.5):: >>> def divide(x, y): ... try: Modified: doctools/trunk/Doc-3k/whatsnew/2.5.rst ============================================================================== --- doctools/trunk/Doc-3k/whatsnew/2.5.rst (original) +++ doctools/trunk/Doc-3k/whatsnew/2.5.rst Tue Aug 7 08:30:02 2007 @@ -6,7 +6,7 @@ .. |release| replace:: 1.01 -.. % $Id: whatsnew25.tex 55005 2007-04-27 19:54:29Z guido.van.rossum $ +.. % $Id: whatsnew25.tex 56611 2007-07-29 08:26:10Z georg.brandl $ .. % Fix XXX comments This article explains the new features in Python 2.5. The final release of @@ -574,13 +574,19 @@ with-block The expression is evaluated, and it should result in an object that supports the -context management protocol. This object may return a value that can optionally -be bound to the name *variable*. (Note carefully that *variable* is *not* -assigned the result of *expression*.) The object can then run set-up code -before *with-block* is executed and some clean-up code is executed after the -block is done, even if the block raised an exception. +context management protocol (that is, has :meth:`__enter__` and :meth:`__exit__` +methods. -To enable the statement in Python 2.5, you need to add the following directive +The object's :meth:`__enter__` is called before *with-block* is executed and +therefore can run set-up code. It also may return a value that is bound to the +name *variable*, if given. (Note carefully that *variable* is *not* assigned +the result of *expression*.) + +After execution of the *with-block* is finished, the object's :meth:`__exit__` +method is called, even if the block raised an exception, and can therefore run +clean-up code. + +To enable the statement in Python 2.5, you need to add the following directive to your module:: from __future__ import with_statement @@ -596,8 +602,13 @@ ... more processing code ... After this statement has executed, the file object in *f* will have been -automatically closed, even if the 'for' loop raised an exception part-way -through the block. +automatically closed, even if the :keyword:`for` loop raised an exception part- +way through the block. + +.. note:: + + In this case, *f* is the same object created by :func:`open`, because + :meth:`file.__enter__` returns *self*. The :mod:`threading` module's locks and condition variables also support the ':keyword:`with`' statement:: From python-checkins at python.org Tue Aug 7 08:30:37 2007 From: python-checkins at python.org (georg.brandl) Date: Tue, 7 Aug 2007 08:30:37 +0200 (CEST) Subject: [Python-checkins] r56795 - doctools/trunk/Doc-3k/includes/sqlite3/adapter_datetime.py doctools/trunk/Doc-3k/includes/sqlite3/adapter_point_1.py doctools/trunk/Doc-3k/includes/sqlite3/adapter_point_2.py doctools/trunk/Doc-3k/includes/sqlite3/collation_reverse.py doctools/trunk/Doc-3k/includes/sqlite3/complete_statement.py doctools/trunk/Doc-3k/includes/sqlite3/converter_point.py doctools/trunk/Doc-3k/includes/sqlite3/countcursors.py doctools/trunk/Doc-3k/includes/sqlite3/execsql_fetchonerow.py doctools/trunk/Doc-3k/includes/sqlite3/execsql_printall_1.py doctools/trunk/Doc-3k/includes/sqlite3/execute_1.py doctools/trunk/Doc-3k/includes/sqlite3/execute_2.py doctools/trunk/Doc-3k/includes/sqlite3/execute_3.py doctools/trunk/Doc-3k/includes/sqlite3/executemany_1.py doctools/trunk/Doc-3k/includes/sqlite3/executemany_2.py doctools/trunk/Doc-3k/includes/sqlite3/md5func.py doctools/trunk/Doc-3k/includes/sqlite3/mysumaggr.py doctools/trunk/Doc-3k/includes/sqlite3/parse_colnames.py doctools/trunk/Doc-3k/includes/sqlite3/pysqlite_datetime.py doctools/trunk/Doc-3k/includes/sqlite3/row_factory.py doctools/trunk/Doc-3k/includes/sqlite3/shortcut_methods.py doctools/trunk/Doc-3k/includes/sqlite3/simple_tableprinter.py doctools/trunk/Doc-3k/includes/sqlite3/text_factory.py Message-ID: <20070807063037.36BA71E4007@bag.python.org> Author: georg.brandl Date: Tue Aug 7 08:30:36 2007 New Revision: 56795 Modified: doctools/trunk/Doc-3k/includes/sqlite3/adapter_datetime.py doctools/trunk/Doc-3k/includes/sqlite3/adapter_point_1.py doctools/trunk/Doc-3k/includes/sqlite3/adapter_point_2.py doctools/trunk/Doc-3k/includes/sqlite3/collation_reverse.py doctools/trunk/Doc-3k/includes/sqlite3/complete_statement.py doctools/trunk/Doc-3k/includes/sqlite3/converter_point.py doctools/trunk/Doc-3k/includes/sqlite3/countcursors.py doctools/trunk/Doc-3k/includes/sqlite3/execsql_fetchonerow.py doctools/trunk/Doc-3k/includes/sqlite3/execsql_printall_1.py doctools/trunk/Doc-3k/includes/sqlite3/execute_1.py doctools/trunk/Doc-3k/includes/sqlite3/execute_2.py doctools/trunk/Doc-3k/includes/sqlite3/execute_3.py doctools/trunk/Doc-3k/includes/sqlite3/executemany_1.py doctools/trunk/Doc-3k/includes/sqlite3/executemany_2.py doctools/trunk/Doc-3k/includes/sqlite3/md5func.py doctools/trunk/Doc-3k/includes/sqlite3/mysumaggr.py doctools/trunk/Doc-3k/includes/sqlite3/parse_colnames.py doctools/trunk/Doc-3k/includes/sqlite3/pysqlite_datetime.py doctools/trunk/Doc-3k/includes/sqlite3/row_factory.py doctools/trunk/Doc-3k/includes/sqlite3/shortcut_methods.py doctools/trunk/Doc-3k/includes/sqlite3/simple_tableprinter.py doctools/trunk/Doc-3k/includes/sqlite3/text_factory.py Log: Port rev. 56784. Modified: doctools/trunk/Doc-3k/includes/sqlite3/adapter_datetime.py ============================================================================== --- doctools/trunk/Doc-3k/includes/sqlite3/adapter_datetime.py (original) +++ doctools/trunk/Doc-3k/includes/sqlite3/adapter_datetime.py Tue Aug 7 08:30:36 2007 @@ -11,4 +11,4 @@ now = datetime.datetime.now() cur.execute("select ?", (now,)) -print cur.fetchone()[0] +print(cur.fetchone()[0]) Modified: doctools/trunk/Doc-3k/includes/sqlite3/adapter_point_1.py ============================================================================== --- doctools/trunk/Doc-3k/includes/sqlite3/adapter_point_1.py (original) +++ doctools/trunk/Doc-3k/includes/sqlite3/adapter_point_1.py Tue Aug 7 08:30:36 2007 @@ -13,4 +13,4 @@ p = Point(4.0, -3.2) cur.execute("select ?", (p,)) -print cur.fetchone()[0] +print(cur.fetchone()[0]) Modified: doctools/trunk/Doc-3k/includes/sqlite3/adapter_point_2.py ============================================================================== --- doctools/trunk/Doc-3k/includes/sqlite3/adapter_point_2.py (original) +++ doctools/trunk/Doc-3k/includes/sqlite3/adapter_point_2.py Tue Aug 7 08:30:36 2007 @@ -14,4 +14,4 @@ p = Point(4.0, -3.2) cur.execute("select ?", (p,)) -print cur.fetchone()[0] +print(cur.fetchone()[0]) Modified: doctools/trunk/Doc-3k/includes/sqlite3/collation_reverse.py ============================================================================== --- doctools/trunk/Doc-3k/includes/sqlite3/collation_reverse.py (original) +++ doctools/trunk/Doc-3k/includes/sqlite3/collation_reverse.py Tue Aug 7 08:30:36 2007 @@ -11,5 +11,5 @@ cur.executemany("insert into test(x) values (?)", [("a",), ("b",)]) cur.execute("select x from test order by x collate reverse") for row in cur: - print row + print(row) con.close() Modified: doctools/trunk/Doc-3k/includes/sqlite3/complete_statement.py ============================================================================== --- doctools/trunk/Doc-3k/includes/sqlite3/complete_statement.py (original) +++ doctools/trunk/Doc-3k/includes/sqlite3/complete_statement.py Tue Aug 7 08:30:36 2007 @@ -8,11 +8,11 @@ buffer = "" -print "Enter your SQL commands to execute in sqlite3." -print "Enter a blank line to exit." +print("Enter your SQL commands to execute in sqlite3.") +print("Enter a blank line to exit.") while True: - line = raw_input() + line = input() if line == "": break buffer += line @@ -22,9 +22,9 @@ cur.execute(buffer) if buffer.lstrip().upper().startswith("SELECT"): - print cur.fetchall() + print(cur.fetchall()) except sqlite3.Error as e: - print "An error occurred:", e.args[0] + print("An error occurred:", e.args[0]) buffer = "" con.close() Modified: doctools/trunk/Doc-3k/includes/sqlite3/converter_point.py ============================================================================== --- doctools/trunk/Doc-3k/includes/sqlite3/converter_point.py (original) +++ doctools/trunk/Doc-3k/includes/sqlite3/converter_point.py Tue Aug 7 08:30:36 2007 @@ -11,7 +11,7 @@ return "%f;%f" % (point.x, point.y) def convert_point(s): - x, y = map(float, s.split(";")) + x, y = list(map(float, s.split(";"))) return Point(x, y) # Register the adapter @@ -30,7 +30,7 @@ cur.execute("insert into test(p) values (?)", (p,)) cur.execute("select p from test") -print "with declared types:", cur.fetchone()[0] +print("with declared types:", cur.fetchone()[0]) cur.close() con.close() @@ -42,6 +42,6 @@ cur.execute("insert into test(p) values (?)", (p,)) cur.execute('select p as "p [point]" from test') -print "with column names:", cur.fetchone()[0] +print("with column names:", cur.fetchone()[0]) cur.close() con.close() Modified: doctools/trunk/Doc-3k/includes/sqlite3/countcursors.py ============================================================================== --- doctools/trunk/Doc-3k/includes/sqlite3/countcursors.py (original) +++ doctools/trunk/Doc-3k/includes/sqlite3/countcursors.py Tue Aug 7 08:30:36 2007 @@ -12,4 +12,4 @@ con = sqlite3.connect(":memory:", factory=CountCursorsConnection) cur1 = con.cursor() cur2 = con.cursor() -print con.numcursors +print(con.numcursors) Modified: doctools/trunk/Doc-3k/includes/sqlite3/execsql_fetchonerow.py ============================================================================== --- doctools/trunk/Doc-3k/includes/sqlite3/execsql_fetchonerow.py (original) +++ doctools/trunk/Doc-3k/includes/sqlite3/execsql_fetchonerow.py Tue Aug 7 08:30:36 2007 @@ -9,9 +9,9 @@ # resulting sequences to yield their elements (name_last, age): cur.execute(SELECT) for (name_last, age) in cur: - print '%s is %d years old.' % (name_last, age) + print('%s is %d years old.' % (name_last, age)) # 2. Equivalently: cur.execute(SELECT) for row in cur: - print '%s is %d years old.' % (row[0], row[1]) + print('%s is %d years old.' % (row[0], row[1])) Modified: doctools/trunk/Doc-3k/includes/sqlite3/execsql_printall_1.py ============================================================================== --- doctools/trunk/Doc-3k/includes/sqlite3/execsql_printall_1.py (original) +++ doctools/trunk/Doc-3k/includes/sqlite3/execsql_printall_1.py Tue Aug 7 08:30:36 2007 @@ -10,4 +10,4 @@ cur.execute("select * from people order by age") # Retrieve all rows as a sequence and print that sequence: -print cur.fetchall() +print(cur.fetchall()) Modified: doctools/trunk/Doc-3k/includes/sqlite3/execute_1.py ============================================================================== --- doctools/trunk/Doc-3k/includes/sqlite3/execute_1.py (original) +++ doctools/trunk/Doc-3k/includes/sqlite3/execute_1.py Tue Aug 7 08:30:36 2007 @@ -8,4 +8,4 @@ age = 72 cur.execute("select name_last, age from people where name_last=? and age=?", (who, age)) -print cur.fetchone() +print(cur.fetchone()) Modified: doctools/trunk/Doc-3k/includes/sqlite3/execute_2.py ============================================================================== --- doctools/trunk/Doc-3k/includes/sqlite3/execute_2.py (original) +++ doctools/trunk/Doc-3k/includes/sqlite3/execute_2.py Tue Aug 7 08:30:36 2007 @@ -9,4 +9,4 @@ cur.execute("select name_last, age from people where name_last=:who and age=:age", {"who": who, "age": age}) -print cur.fetchone() +print(cur.fetchone()) Modified: doctools/trunk/Doc-3k/includes/sqlite3/execute_3.py ============================================================================== --- doctools/trunk/Doc-3k/includes/sqlite3/execute_3.py (original) +++ doctools/trunk/Doc-3k/includes/sqlite3/execute_3.py Tue Aug 7 08:30:36 2007 @@ -9,4 +9,4 @@ cur.execute("select name_last, age from people where name_last=:who and age=:age", locals()) -print cur.fetchone() +print(cur.fetchone()) Modified: doctools/trunk/Doc-3k/includes/sqlite3/executemany_1.py ============================================================================== --- doctools/trunk/Doc-3k/includes/sqlite3/executemany_1.py (original) +++ doctools/trunk/Doc-3k/includes/sqlite3/executemany_1.py Tue Aug 7 08:30:36 2007 @@ -21,4 +21,4 @@ cur.executemany("insert into characters(c) values (?)", theIter) cur.execute("select c from characters") -print cur.fetchall() +print(cur.fetchall()) Modified: doctools/trunk/Doc-3k/includes/sqlite3/executemany_2.py ============================================================================== --- doctools/trunk/Doc-3k/includes/sqlite3/executemany_2.py (original) +++ doctools/trunk/Doc-3k/includes/sqlite3/executemany_2.py Tue Aug 7 08:30:36 2007 @@ -12,4 +12,4 @@ cur.executemany("insert into characters(c) values (?)", char_generator()) cur.execute("select c from characters") -print cur.fetchall() +print(cur.fetchall()) Modified: doctools/trunk/Doc-3k/includes/sqlite3/md5func.py ============================================================================== --- doctools/trunk/Doc-3k/includes/sqlite3/md5func.py (original) +++ doctools/trunk/Doc-3k/includes/sqlite3/md5func.py Tue Aug 7 08:30:36 2007 @@ -1,11 +1,11 @@ import sqlite3 -import md5 +import hashlib def md5sum(t): - return md5.md5(t).hexdigest() + return hashlib.md5(t).hexdigest() con = sqlite3.connect(":memory:") con.create_function("md5", 1, md5sum) cur = con.cursor() cur.execute("select md5(?)", ("foo",)) -print cur.fetchone()[0] +print(cur.fetchone()[0]) Modified: doctools/trunk/Doc-3k/includes/sqlite3/mysumaggr.py ============================================================================== --- doctools/trunk/Doc-3k/includes/sqlite3/mysumaggr.py (original) +++ doctools/trunk/Doc-3k/includes/sqlite3/mysumaggr.py Tue Aug 7 08:30:36 2007 @@ -17,4 +17,4 @@ cur.execute("insert into test(i) values (1)") cur.execute("insert into test(i) values (2)") cur.execute("select mysum(i) from test") -print cur.fetchone()[0] +print(cur.fetchone()[0]) Modified: doctools/trunk/Doc-3k/includes/sqlite3/parse_colnames.py ============================================================================== --- doctools/trunk/Doc-3k/includes/sqlite3/parse_colnames.py (original) +++ doctools/trunk/Doc-3k/includes/sqlite3/parse_colnames.py Tue Aug 7 08:30:36 2007 @@ -5,4 +5,4 @@ cur = con.cursor() cur.execute('select ? as "x [timestamp]"', (datetime.datetime.now(),)) dt = cur.fetchone()[0] -print dt, type(dt) +print(dt, type(dt)) Modified: doctools/trunk/Doc-3k/includes/sqlite3/pysqlite_datetime.py ============================================================================== --- doctools/trunk/Doc-3k/includes/sqlite3/pysqlite_datetime.py (original) +++ doctools/trunk/Doc-3k/includes/sqlite3/pysqlite_datetime.py Tue Aug 7 08:30:36 2007 @@ -11,10 +11,10 @@ cur.execute("insert into test(d, ts) values (?, ?)", (today, now)) cur.execute("select d, ts from test") row = cur.fetchone() -print today, "=>", row[0], type(row[0]) -print now, "=>", row[1], type(row[1]) +print(today, "=>", row[0], type(row[0])) +print(now, "=>", row[1], type(row[1])) cur.execute('select current_date as "d [date]", current_timestamp as "ts [timestamp]"') row = cur.fetchone() -print "current_date", row[0], type(row[0]) -print "current_timestamp", row[1], type(row[1]) +print("current_date", row[0], type(row[0])) +print("current_timestamp", row[1], type(row[1])) Modified: doctools/trunk/Doc-3k/includes/sqlite3/row_factory.py ============================================================================== --- doctools/trunk/Doc-3k/includes/sqlite3/row_factory.py (original) +++ doctools/trunk/Doc-3k/includes/sqlite3/row_factory.py Tue Aug 7 08:30:36 2007 @@ -10,4 +10,4 @@ con.row_factory = dict_factory cur = con.cursor() cur.execute("select 1 as a") -print cur.fetchone()["a"] +print(cur.fetchone()["a"]) Modified: doctools/trunk/Doc-3k/includes/sqlite3/shortcut_methods.py ============================================================================== --- doctools/trunk/Doc-3k/includes/sqlite3/shortcut_methods.py (original) +++ doctools/trunk/Doc-3k/includes/sqlite3/shortcut_methods.py Tue Aug 7 08:30:36 2007 @@ -15,7 +15,7 @@ # Print the table contents for row in con.execute("select firstname, lastname from person"): - print row + print(row) # Using a dummy WHERE clause to not let SQLite take the shortcut table deletes. -print "I just deleted", con.execute("delete from person where 1=1").rowcount, "rows" +print("I just deleted", con.execute("delete from person where 1=1").rowcount, "rows") Modified: doctools/trunk/Doc-3k/includes/sqlite3/simple_tableprinter.py ============================================================================== --- doctools/trunk/Doc-3k/includes/sqlite3/simple_tableprinter.py (original) +++ doctools/trunk/Doc-3k/includes/sqlite3/simple_tableprinter.py Tue Aug 7 08:30:36 2007 @@ -11,9 +11,9 @@ # Print a header. for fieldDesc in cur.description: - print fieldDesc[0].ljust(FIELD_MAX_WIDTH) , -print # Finish the header with a newline. -print '-' * 78 + print(fieldDesc[0].ljust(FIELD_MAX_WIDTH), end=' ') +print() # Finish the header with a newline. +print('-' * 78) # For each row, print the value of each field left-justified within # the maximum possible width of that field. @@ -21,6 +21,6 @@ for row in cur: for fieldIndex in fieldIndices: fieldValue = str(row[fieldIndex]) - print fieldValue.ljust(FIELD_MAX_WIDTH) , + print(fieldValue.ljust(FIELD_MAX_WIDTH), end=' ') - print # Finish the row with a newline. + print() # Finish the row with a newline. Modified: doctools/trunk/Doc-3k/includes/sqlite3/text_factory.py ============================================================================== --- doctools/trunk/Doc-3k/includes/sqlite3/text_factory.py (original) +++ doctools/trunk/Doc-3k/includes/sqlite3/text_factory.py Tue Aug 7 08:30:36 2007 @@ -6,7 +6,7 @@ # Create the table con.execute("create table person(lastname, firstname)") -AUSTRIA = u"\xd6sterreich" +AUSTRIA = "\xd6sterreich" # by default, rows are returned as Unicode cur.execute("select ?", (AUSTRIA,)) @@ -25,17 +25,17 @@ # we can also implement a custom text_factory ... # here we implement one that will ignore Unicode characters that cannot be # decoded from UTF-8 -con.text_factory = lambda x: unicode(x, "utf-8", "ignore") -cur.execute("select ?", ("this is latin1 and would normally create errors" + u"\xe4\xf6\xfc".encode("latin1"),)) +con.text_factory = lambda x: str(x, "utf-8", "ignore") +cur.execute("select ?", ("this is latin1 and would normally create errors" + "\xe4\xf6\xfc".encode("latin1"),)) row = cur.fetchone() -assert type(row[0]) == unicode +assert type(row[0]) == str # pysqlite offers a builtin optimized text_factory that will return bytestring # objects, if the data is in ASCII only, and otherwise return unicode objects con.text_factory = sqlite3.OptimizedUnicode cur.execute("select ?", (AUSTRIA,)) row = cur.fetchone() -assert type(row[0]) == unicode +assert type(row[0]) == str cur.execute("select ?", ("Germany",)) row = cur.fetchone() From python-checkins at python.org Tue Aug 7 08:45:25 2007 From: python-checkins at python.org (erik.forsberg) Date: Tue, 7 Aug 2007 08:45:25 +0200 (CEST) Subject: [Python-checkins] r56796 - tracker/instances/python-dev/html/page.html Message-ID: <20070807064525.C9E451E400B@bag.python.org> Author: erik.forsberg Date: Tue Aug 7 08:45:24 2007 New Revision: 56796 Modified: tracker/instances/python-dev/html/page.html Log: Added a link to Meta tracker. Should fix http://psf.upfronthosting.co.za/roundup/meta/issue95. Modified: tracker/instances/python-dev/html/page.html ============================================================================== --- tracker/instances/python-dev/html/page.html (original) +++ tracker/instances/python-dev/html/page.html Tue Aug 7 08:45:24 2007 @@ -197,7 +197,11 @@ Help
      Tracker Documentation + + Report + Tracker Problem
      + From python-checkins at python.org Tue Aug 7 09:13:24 2007 From: python-checkins at python.org (georg.brandl) Date: Tue, 7 Aug 2007 09:13:24 +0200 (CEST) Subject: [Python-checkins] r56797 - python/trunk/Doc/tut/tut.tex Message-ID: <20070807071324.700D61E4006@bag.python.org> Author: georg.brandl Date: Tue Aug 7 09:13:24 2007 New Revision: 56797 Modified: python/trunk/Doc/tut/tut.tex Log: Bug #1769002: fix a now-wrong sentence in the tutorial. Modified: python/trunk/Doc/tut/tut.tex ============================================================================== --- python/trunk/Doc/tut/tut.tex (original) +++ python/trunk/Doc/tut/tut.tex Tue Aug 7 09:13:24 2007 @@ -2966,15 +2966,14 @@ statement looks for a top-level module with the given name. When packages are structured into subpackages (as with the -\module{sound} package in the example), there's no shortcut to refer -to submodules of sibling packages - the full name of the subpackage -must be used. For example, if the module -\module{sound.filters.vocoder} needs to use the \module{echo} module -in the \module{sound.effects} package, it can use \code{from -sound.effects import echo}. +\module{sound} package in the example), you can use absolute +imports to refer to submodules of siblings packages. +For example, if the module \module{sound.filters.vocoder} needs to +use the \module{echo} module in the \module{sound.effects} package, +it can use \code{from sound.effects import echo}. Starting with Python 2.5, in addition to the implicit relative imports -described above, you can write explicit relative imports with the +described above, you can also write explicit relative imports with the \code{from module import name} form of import statement. These explicit relative imports use leading dots to indicate the current and parent packages involved in the relative import. From the \module{surround} From python-checkins at python.org Tue Aug 7 09:13:28 2007 From: python-checkins at python.org (georg.brandl) Date: Tue, 7 Aug 2007 09:13:28 +0200 (CEST) Subject: [Python-checkins] r56798 - python/branches/release25-maint/Doc/tut/tut.tex Message-ID: <20070807071328.613F61E4006@bag.python.org> Author: georg.brandl Date: Tue Aug 7 09:13:27 2007 New Revision: 56798 Modified: python/branches/release25-maint/Doc/tut/tut.tex Log: Bug #1769002: fix a now-wrong sentence in the tutorial. (backport from rev. 56797) Modified: python/branches/release25-maint/Doc/tut/tut.tex ============================================================================== --- python/branches/release25-maint/Doc/tut/tut.tex (original) +++ python/branches/release25-maint/Doc/tut/tut.tex Tue Aug 7 09:13:27 2007 @@ -2966,15 +2966,14 @@ statement looks for a top-level module with the given name. When packages are structured into subpackages (as with the -\module{sound} package in the example), there's no shortcut to refer -to submodules of sibling packages - the full name of the subpackage -must be used. For example, if the module -\module{sound.filters.vocoder} needs to use the \module{echo} module -in the \module{sound.effects} package, it can use \code{from -sound.effects import echo}. +\module{sound} package in the example), you can use absolute +imports to refer to submodules of siblings packages. +For example, if the module \module{sound.filters.vocoder} needs to +use the \module{echo} module in the \module{sound.effects} package, +it can use \code{from sound.effects import echo}. Starting with Python 2.5, in addition to the implicit relative imports -described above, you can write explicit relative imports with the +described above, you can also write explicit relative imports with the \code{from module import name} form of import statement. These explicit relative imports use leading dots to indicate the current and parent packages involved in the relative import. From the \module{surround} From python-checkins at python.org Tue Aug 7 19:54:38 2007 From: python-checkins at python.org (facundo.batista) Date: Tue, 7 Aug 2007 19:54:38 +0200 (CEST) Subject: [Python-checkins] r56801 - python/branches/decimal-branch/Lib/decimal.py Message-ID: <20070807175438.E14AC1E4010@bag.python.org> Author: facundo.batista Date: Tue Aug 7 19:54:38 2007 New Revision: 56801 Modified: python/branches/decimal-branch/Lib/decimal.py Log: Three minor English corrections (thanks Mark Dickinson). Modified: python/branches/decimal-branch/Lib/decimal.py ============================================================================== --- python/branches/decimal-branch/Lib/decimal.py (original) +++ python/branches/decimal-branch/Lib/decimal.py Tue Aug 7 19:54:38 2007 @@ -2304,7 +2304,7 @@ """Returns the same Decimal object. As we do not have different encodings for the same number, the - received object already is in it's canonical form. + received object already is in its canonical form. """ return self @@ -3171,7 +3171,7 @@ """Returns the same Decimal object. As we do not have different encodings for the same number, the - received object already is in it's canonical form. + received object already is in its canonical form. >>> ExtendedContext.canonical(Decimal('2.50')) Decimal("2.50") @@ -3275,7 +3275,7 @@ return a.copy_negate(context=self) def copy_sign(self, a, b): - """Copys the second operand's sign to the first one. + """Copies the second operand's sign to the first one. In detail, it returns a copy of the first operand with the sign equal to the sign of the second operand. From python-checkins at python.org Tue Aug 7 22:43:52 2007 From: python-checkins at python.org (martin.v.loewis) Date: Tue, 7 Aug 2007 22:43:52 +0200 (CEST) Subject: [Python-checkins] r56807 - tracker/importer/fixsfmojibake.py Message-ID: <20070807204352.6B4D71E4027@bag.python.org> Author: martin.v.loewis Date: Tue Aug 7 22:43:52 2007 New Revision: 56807 Modified: tracker/importer/fixsfmojibake.py Log: Add missing assignment of input data. Modified: tracker/importer/fixsfmojibake.py ============================================================================== --- tracker/importer/fixsfmojibake.py (original) +++ tracker/importer/fixsfmojibake.py Tue Aug 7 22:43:52 2007 @@ -14,6 +14,8 @@ # ASCII, and that non-ASCII characters are always encoded # as decimal character references. +# Usage: fixsfmojibake.py < xml_export.php > sf.xml + import sys, re expr = re.compile('(&#[0-9]+;)+') @@ -30,6 +32,7 @@ chars = ['&#%d;' % ord(c) for c in chars] return ''.join(chars) +indata = sys.stdin.read() print >>sys.stderr, len(indata) # Make sure that there are only &#decimal; references, From python-checkins at python.org Wed Aug 8 05:58:49 2007 From: python-checkins at python.org (collin.winter) Date: Wed, 8 Aug 2007 05:58:49 +0200 (CEST) Subject: [Python-checkins] r56817 - in sandbox/trunk/2to3: fixes/fix_map.py tests/test_fixers.py Message-ID: <20070808035849.E9EC11E400A@bag.python.org> Author: collin.winter Date: Wed Aug 8 05:58:49 2007 New Revision: 56817 Modified: sandbox/trunk/2to3/ (props changed) sandbox/trunk/2to3/fixes/fix_map.py sandbox/trunk/2to3/tests/test_fixers.py Log: Add a warning to fix_map when map() is found in void context. Modified: sandbox/trunk/2to3/fixes/fix_map.py ============================================================================== --- sandbox/trunk/2to3/fixes/fix_map.py (original) +++ sandbox/trunk/2to3/fixes/fix_map.py Wed Aug 8 05:58:49 2007 @@ -53,7 +53,10 @@ """ def transform(self, node, results): - if "map_lambda" in results: + if node.parent.type == syms.simple_stmt: + self.warning(node, "You should use a for loop here") + return + elif "map_lambda" in results: new = ListComp(results.get("xp").clone(), results.get("fp").clone(), results.get("it").clone()) Modified: sandbox/trunk/2to3/tests/test_fixers.py ============================================================================== --- sandbox/trunk/2to3/tests/test_fixers.py (original) +++ sandbox/trunk/2to3/tests/test_fixers.py Wed Aug 8 05:58:49 2007 @@ -2301,6 +2301,13 @@ a = """(x for x in map(f, 'abc'))""" self.unchanged(a) + def test_warn(self): + a = """ + foo() + map(f, x) + """ + self.warns_unchanged(a, "You should use a for loop here") + if __name__ == "__main__": import __main__ From python-checkins at python.org Wed Aug 8 07:41:41 2007 From: python-checkins at python.org (erik.forsberg) Date: Wed, 8 Aug 2007 07:41:41 +0200 (CEST) Subject: [Python-checkins] r56821 - tracker/instances/python-dev/html/issue.item.html Message-ID: <20070808054141.791061E4003@bag.python.org> Author: erik.forsberg Date: Wed Aug 8 07:41:41 2007 New Revision: 56821 Modified: tracker/instances/python-dev/html/issue.item.html Log: Be more restrictive - don't show remove buttons if user may not edit file/msg. Modified: tracker/instances/python-dev/html/issue.item.html ============================================================================== --- tracker/instances/python-dev/html/issue.item.html (original) +++ tracker/instances/python-dev/html/issue.item.html Wed Aug 8 07:41:41 2007 @@ -212,7 +212,7 @@ tal:attributes="href string:file${file/id}">edit
      		- @@ -233,7 +233,7 @@ Date: - From python-checkins at python.org Wed Aug 8 08:23:22 2007 From: python-checkins at python.org (georg.brandl) Date: Wed, 8 Aug 2007 08:23:22 +0200 (CEST) Subject: [Python-checkins] r56822 - doctools/trunk/Doc-3k/extending/newtypes.rst Message-ID: <20070808062322.F06981E4009@bag.python.org> Author: georg.brandl Date: Wed Aug 8 08:23:21 2007 New Revision: 56822 Modified: doctools/trunk/Doc-3k/extending/newtypes.rst Log: Port rev. 56806. Modified: doctools/trunk/Doc-3k/extending/newtypes.rst ============================================================================== --- doctools/trunk/Doc-3k/extending/newtypes.rst (original) +++ doctools/trunk/Doc-3k/extending/newtypes.rst Wed Aug 8 08:23:21 2007 @@ -1025,21 +1025,14 @@ builtin: repr builtin: str -In Python, there are three ways to generate a textual representation of an -object: the :func:`repr` function (or equivalent back-tick syntax), the -:func:`str` function, and the :keyword:`print` statement. For most objects, the -:keyword:`print` statement is equivalent to the :func:`str` function, but it is -possible to special-case printing to a :ctype:`FILE\*` if necessary; this should -only be done if efficiency is identified as a problem and profiling suggests -that creating a temporary string object to be written to a file is too -expensive. +In Python, there are two ways to generate a textual representation of an object: +the :func:`repr` function, and the :func:`str` function. (The :func:`print` +function just calls :func:`str`.) These handlers are both optional. -These handlers are all optional, and most types at most need to implement the -:attr:`tp_str` and :attr:`tp_repr` handlers. :: +:: reprfunc tp_repr; reprfunc tp_str; - printfunc tp_print; The :attr:`tp_repr` handler should return a string object containing a representation of the instance for which it is called. Here is a simple @@ -1553,8 +1546,8 @@ In order to learn how to implement any specific method for your new data type, do the following: Download and unpack the Python source distribution. Go the :file:`Objects` directory, then search the C source files for ``tp_`` plus the -function you want (for example, ``tp_print`` or ``tp_compare``). You will find -examples of the function you want to implement. +function you want (for example, ``tp_compare``). You will find examples of the +function you want to implement. When you need to verify that an object is an instance of the type you are implementing, use the :cfunc:`PyObject_TypeCheck` function. A sample of its use From python-checkins at python.org Wed Aug 8 09:33:13 2007 From: python-checkins at python.org (georg.brandl) Date: Wed, 8 Aug 2007 09:33:13 +0200 (CEST) Subject: [Python-checkins] r56825 - in doctools/trunk: Doc-26/bugs.rst Doc-3k/bugs.rst Message-ID: <20070808073313.346C71E400E@bag.python.org> Author: georg.brandl Date: Wed Aug 8 09:33:11 2007 New Revision: 56825 Modified: doctools/trunk/Doc-26/bugs.rst doctools/trunk/Doc-3k/bugs.rst Log: Update bug reporting page for roundup. Modified: doctools/trunk/Doc-26/bugs.rst ============================================================================== --- doctools/trunk/Doc-26/bugs.rst (original) +++ doctools/trunk/Doc-26/bugs.rst Wed Aug 8 09:33:11 2007 @@ -1,46 +1,47 @@ .. _reporting-bugs: -************** -Reporting Bugs -************** +************************ +Reporting Bugs in Python +************************ Python is a mature programming language which has established a reputation for stability. In order to maintain this reputation, the developers would like to -know of any deficiencies you find in Python or its documentation. +know of any deficiencies you find in Python. -Before submitting a report, you will be required to log into SourceForge; this -will make it possible for the developers to contact you for additional -information if needed. It is not possible to submit a bug report anonymously. - -All bug reports should be submitted via the Python Bug Tracker on SourceForge -(http://sourceforge.net/bugs/?group_id=5470). The bug tracker offers a Web form -which allows pertinent information to be entered and submitted to the -developers. +If you find errors in the documentation, please use either the "Add a comment" +or the "Suggest a change" features of the relevant page in the most recent +online documentation at http://docs.python.org/. + +All other bug reports should be submitted via the Python Bug Tracker +(http://bugs.python.org/). The bug tracker offers a Web form which allows +pertinent information to be entered and submitted to the developers. The first step in filing a report is to determine whether the problem has already been reported. The advantage in doing so, aside from saving the developers time, is that you learn what has been done to fix it; it may be that the problem has already been fixed for the next release, or additional information is needed (in which case you are welcome to provide it if you can!). -To do this, search the bug database using the search box on the left side of the -page. +To do this, search the bug database using the search box on the top of the page. If the problem you're reporting is not already in the bug tracker, go back to -the Python Bug Tracker (http://sourceforge.net/bugs/?group_id=5470). Select the -"Submit a Bug" link at the top of the page to open the bug reporting form. +the Python Bug Tracker. If you don't already have a tracker account, select the +"Register" link in the sidebar and undergo the registration procedure. +Otherwise, if you're not logged in, enter your credentials and select "Login". +It is not possible to submit a bug report anonymously. + +Being now logged in, you can submit a bug. Select the "Create New" link in the +sidebar to open the bug reporting form. + +The submission form has a number of fields. For the "Title" field, enter a +*very* short description of the problem; less than ten words is good. In the +"Type" field, select the type of your problem; also select the "Component" and +"Versions" to which the bug relates. -The submission form has a number of fields. The only fields that are required -are the "Summary" and "Details" fields. For the summary, enter a *very* short -description of the problem; less than ten words is good. In the Details field, -describe the problem in detail, including what you expected to happen and what -did happen. Be sure to include the version of Python you used, whether any +In the "Change Note" field, describe the problem in detail, including what you +expected to happen and what did happen. Be sure to include whether any extension modules were involved, and what hardware and software platform you were using (including version information as appropriate). -The only other field that you may want to set is the "Category" field, which -allows you to place the bug report into a broad category (such as -"Documentation" or "Library"). - Each bug report will be assigned to a developer who will determine what needs to be done to correct the problem. You will receive an update each time action is taken on the bug. Modified: doctools/trunk/Doc-3k/bugs.rst ============================================================================== --- doctools/trunk/Doc-3k/bugs.rst (original) +++ doctools/trunk/Doc-3k/bugs.rst Wed Aug 8 09:33:11 2007 @@ -1,46 +1,47 @@ .. _reporting-bugs: -************** -Reporting Bugs -************** +************************ +Reporting Bugs in Python +************************ Python is a mature programming language which has established a reputation for stability. In order to maintain this reputation, the developers would like to -know of any deficiencies you find in Python or its documentation. +know of any deficiencies you find in Python. -Before submitting a report, you will be required to log into SourceForge; this -will make it possible for the developers to contact you for additional -information if needed. It is not possible to submit a bug report anonymously. - -All bug reports should be submitted via the Python Bug Tracker on SourceForge -(http://sourceforge.net/bugs/?group_id=5470). The bug tracker offers a Web form -which allows pertinent information to be entered and submitted to the -developers. +If you find errors in the documentation, please use either the "Add a comment" +or the "Suggest a change" features of the relevant page in the most recent +online documentation at http://docs.python.org/. + +All other bug reports should be submitted via the Python Bug Tracker +(http://bugs.python.org/). The bug tracker offers a Web form which allows +pertinent information to be entered and submitted to the developers. The first step in filing a report is to determine whether the problem has already been reported. The advantage in doing so, aside from saving the developers time, is that you learn what has been done to fix it; it may be that the problem has already been fixed for the next release, or additional information is needed (in which case you are welcome to provide it if you can!). -To do this, search the bug database using the search box on the left side of the -page. +To do this, search the bug database using the search box on the top of the page. If the problem you're reporting is not already in the bug tracker, go back to -the Python Bug Tracker (http://sourceforge.net/bugs/?group_id=5470). Select the -"Submit a Bug" link at the top of the page to open the bug reporting form. +the Python Bug Tracker. If you don't already have a tracker account, select the +"Register" link in the sidebar and undergo the registration procedure. +Otherwise, if you're not logged in, enter your credentials and select "Login". +It is not possible to submit a bug report anonymously. + +Being now logged in, you can submit a bug. Select the "Create New" link in the +sidebar to open the bug reporting form. + +The submission form has a number of fields. For the "Title" field, enter a +*very* short description of the problem; less than ten words is good. In the +"Type" field, select the type of your problem; also select the "Component" and +"Versions" to which the bug relates. -The submission form has a number of fields. The only fields that are required -are the "Summary" and "Details" fields. For the summary, enter a *very* short -description of the problem; less than ten words is good. In the Details field, -describe the problem in detail, including what you expected to happen and what -did happen. Be sure to include the version of Python you used, whether any +In the "Change Note" field, describe the problem in detail, including what you +expected to happen and what did happen. Be sure to include whether any extension modules were involved, and what hardware and software platform you were using (including version information as appropriate). -The only other field that you may want to set is the "Category" field, which -allows you to place the bug report into a broad category (such as -"Documentation" or "Library"). - Each bug report will be assigned to a developer who will determine what needs to be done to correct the problem. You will receive an update each time action is taken on the bug. From python-checkins at python.org Wed Aug 8 13:09:20 2007 From: python-checkins at python.org (mark.summerfield) Date: Wed, 8 Aug 2007 13:09:20 +0200 (CEST) Subject: [Python-checkins] r56826 - doctools/trunk/Doc-26/library/index.rst Message-ID: <20070808110920.BE0331E4009@bag.python.org> Author: mark.summerfield Date: Wed Aug 8 13:09:20 2007 New Revision: 56826 Modified: doctools/trunk/Doc-26/library/index.rst Log: I have reordered the table of contents for the library. Modified: doctools/trunk/Doc-26/library/index.rst ============================================================================== --- doctools/trunk/Doc-26/library/index.rst (original) +++ doctools/trunk/Doc-26/library/index.rst Wed Aug 8 13:09:20 2007 @@ -48,22 +48,21 @@ strings.rst datatypes.rst numeric.rst - netdata.rst - markup.rst - fileformats.rst - crypto.rst filesys.rst - archiving.rst persistence.rst + archiving.rst + fileformats.rst + crypto.rst allos.rst someos.rst - unix.rst ipc.rst + netdata.rst + markup.rst internet.rst mm.rst - tk.rst i18n.rst frameworks.rst + tk.rst development.rst pdb.rst profile.rst @@ -77,7 +76,8 @@ language.rst compiler.rst misc.rst + windows.rst + unix.rst sgi.rst sun.rst - windows.rst undoc.rst From python-checkins at python.org Wed Aug 8 13:10:09 2007 From: python-checkins at python.org (mark.summerfield) Date: Wed, 8 Aug 2007 13:10:09 +0200 (CEST) Subject: [Python-checkins] r56827 - doctools/trunk/Doc-26/library/calendar.rst doctools/trunk/Doc-26/library/collections.rst doctools/trunk/Doc-26/library/datetime.rst doctools/trunk/Doc-26/library/functions.rst doctools/trunk/Doc-26/library/os.path.rst doctools/trunk/Doc-26/library/os.rst doctools/trunk/Doc-26/library/stdtypes.rst doctools/trunk/Doc-26/library/sys.rst doctools/trunk/Doc-26/library/time.rst Message-ID: <20070808111009.962FA1E400F@bag.python.org> Author: mark.summerfield Date: Wed Aug 8 13:10:08 2007 New Revision: 56827 Modified: doctools/trunk/Doc-26/library/calendar.rst doctools/trunk/Doc-26/library/collections.rst doctools/trunk/Doc-26/library/datetime.rst doctools/trunk/Doc-26/library/functions.rst doctools/trunk/Doc-26/library/os.path.rst doctools/trunk/Doc-26/library/os.rst doctools/trunk/Doc-26/library/stdtypes.rst doctools/trunk/Doc-26/library/sys.rst doctools/trunk/Doc-26/library/time.rst Log: Added more cross-references between containers & regarding strings. Deleted some of the dict constructor examples to avoid confusing newcomers. Added mild warning about using float keys for dicts. Added cross-references between time, datetime, and calendar. Added other cross-references. Modified: doctools/trunk/Doc-26/library/calendar.rst ============================================================================== --- doctools/trunk/Doc-26/library/calendar.rst (original) +++ doctools/trunk/Doc-26/library/calendar.rst Wed Aug 8 13:10:08 2007 @@ -13,7 +13,8 @@ these calendars have Monday as the first day of the week, and Sunday as the last (the European convention). Use :func:`setfirstweekday` to set the first day of the week to Sunday (6) or to any other weekday. Parameters that specify dates -are given as integers. +are given as integers. For related +functionality, see also the :mod:`datetime` and :mod:`time` modules. Most of these functions and classses rely on the :mod:`datetime` module which uses an idealized calendar, the current Gregorian calendar indefinitely extended Modified: doctools/trunk/Doc-26/library/collections.rst ============================================================================== --- doctools/trunk/Doc-26/library/collections.rst (original) +++ doctools/trunk/Doc-26/library/collections.rst Wed Aug 8 13:10:08 2007 @@ -13,10 +13,10 @@ This module implements high-performance container datatypes. Currently, there are two datatypes, :class:`deque` and :class:`defaultdict`, and one datatype factory function, :func:`NamedTuple`. Python already -includes built-in containers, :func:`dict`, :func:`list`, and -:func:`tuple`. The optional :mod:`bsddb` module has a :meth:`btopen` -method that can be used to create in-memory or file based ordered -dictionaries with string keys. +includes built-in containers, :class:`dict`, :class:`list`, +:class:`set`, and :class:`tuple`. In addition, the optional :mod:`bsddb` +module has a :meth:`bsddb.btopen` method that can be used to create in-memory +or file based ordered dictionaries with string keys. Future editions of the standard library may include balanced trees and ordered dictionaries. Modified: doctools/trunk/Doc-26/library/datetime.rst ============================================================================== --- doctools/trunk/Doc-26/library/datetime.rst (original) +++ doctools/trunk/Doc-26/library/datetime.rst Wed Aug 8 13:10:08 2007 @@ -16,7 +16,8 @@ The :mod:`datetime` module supplies classes for manipulating dates and times in both simple and complex ways. While date and time arithmetic is supported, the focus of the implementation is on efficient member extraction for output -formatting and manipulation. +formatting and manipulation. For related +functionality, see also the :mod:`time` and :mod:`calendar` modules. There are two kinds of date and time objects: "naive" and "aware". This distinction refers to whether the object has any notion of time zone, daylight Modified: doctools/trunk/Doc-26/library/functions.rst ============================================================================== --- doctools/trunk/Doc-26/library/functions.rst (original) +++ doctools/trunk/Doc-26/library/functions.rst Wed Aug 8 13:10:08 2007 @@ -245,8 +245,10 @@ .. function:: dict([arg]) :noindex: - Create a new dictionary. The dictionary type is described in - :ref:`typesmapping`. + Create a new data dictionary. The dictionary type is described in + :ref:`typesmapping`. For other containers see the built in + :class:`list`, :class:`set`, and :class:`tuple` classes, and the + :mod:`collections` module. .. function:: dir([object]) @@ -326,7 +328,7 @@ ``(1, seq[1])``, ``(2, seq[2])``, .... For example:: >>> for i, season in enumerate(['Spring', 'Summer', 'Fall', 'Winter')]: - >>> print i, season + >>> print i, season 0 Spring 1 Summer 2 Fall @@ -457,7 +459,9 @@ :class:`frozenset` objects. If *iterable* is not specified, returns a new empty set, ``frozenset([])``. - The frozenset type is described in :ref:`types-set`. + The frozenset type is described in :ref:`types-set`. For other containers see the built in + :class:`dict`, :class:`list`, and :class:`tuple` classes, and the + :mod:`collections` module. .. versionadded:: 2.4 @@ -616,7 +620,9 @@ returns ``['a', 'b', 'c']`` and ``list( (1, 2, 3) )`` returns ``[1, 2, 3]``. If no argument is given, returns a new empty list, ``[]``. - :class:`list` is a mutable sequence type, as documented in :ref:`typesseq`. + :class:`list` is a mutable sequence type, as documented in + :ref:`typesseq`. For other containers see the built in :class:`dict`, + :class:`set`, and :class:`tuple` classes, and the :mod:`collections` module. .. function:: locals() @@ -761,6 +767,8 @@ Python enforces that the mode, after stripping ``'U'``, begins with ``'r'``, ``'w'`` or ``'a'``. + See also the :mod:`fileinput` module. + .. versionchanged:: 2.5 Restriction on first letter of mode string introduced. @@ -988,7 +996,9 @@ :class:`frozenset` objects. If *iterable* is not specified, returns a new empty set, ``set([])``. - The set type is described in :ref:`types-set`. + The set type is described in :ref:`types-set`. For other containers see the built in + :class:`dict`, :class:`list`, and :class:`tuple` classes, and the + :mod:`collections` module. .. versionadded:: 2.4 @@ -1130,7 +1140,10 @@ 3])`` returns ``(1, 2, 3)``. If no argument is given, returns a new empty tuple, ``()``. - :class:`tuple` is a mutable sequence type, as documented in :ref:`typesseq`. + :class:`tuple` is an immutable sequence type, as documented in + :ref:`typesseq`. For other containers see the built in :class:`dict`, + :class:`list`, and :class:`set` classes, and the :mod:`collections` module. + .. function:: type(object) Modified: doctools/trunk/Doc-26/library/os.path.rst ============================================================================== --- doctools/trunk/Doc-26/library/os.path.rst (original) +++ doctools/trunk/Doc-26/library/os.path.rst Wed Aug 8 13:10:08 2007 @@ -8,7 +8,9 @@ .. index:: single: path; operations -This module implements some useful functions on pathnames. +This module implements some useful functions on pathnames. To read or +write files see :func:`open`, and for accessing the filesystem see the +:mod:`os` module. .. warning:: Modified: doctools/trunk/Doc-26/library/os.rst ============================================================================== --- doctools/trunk/Doc-26/library/os.rst (original) +++ doctools/trunk/Doc-26/library/os.rst Wed Aug 8 13:10:08 2007 @@ -9,7 +9,8 @@ This module provides a more portable way of using operating system dependent functionality than importing a operating system dependent built-in module like :mod:`posix` or :mod:`nt`. (If you just want to read or write a file see -:func:`open`.) +:func:`open`, and if you want to manipulate paths, see the :mod:`os.path` +module.) This module searches for an operating system dependent built-in module like :mod:`mac` or :mod:`posix` and exports the same functions and data as found Modified: doctools/trunk/Doc-26/library/stdtypes.rst ============================================================================== --- doctools/trunk/Doc-26/library/stdtypes.rst (original) +++ doctools/trunk/Doc-26/library/stdtypes.rst Wed Aug 8 13:10:08 2007 @@ -492,6 +492,10 @@ There are six sequence types: strings, Unicode strings, lists, tuples, buffers, and xrange objects. +(For other containers see the built in :class:`dict`, :class:`list`, +:class:`set`, and :class:`tuple` classes, and the :mod:`collections` +module.) + .. index:: object: sequence @@ -503,20 +507,22 @@ object: xrange String literals are written in single or double quotes: ``'xyzzy'``, -``"frobozz"``. See :ref:`strings` for more about string literals. Unicode -strings are much like strings, but are specified in the syntax using a preceding -``'u'`` character: ``u'abc'``, ``u"def"``. Lists are constructed with square -brackets, separating items with commas: ``[a, b, c]``. Tuples are constructed -by the comma operator (not within square brackets), with or without enclosing -parentheses, but an empty tuple must have the enclosing parentheses, such as -``a, b, c`` or ``()``. A single item tuple must have a trailing comma, such as -``(d,)``. +``"frobozz"``. See :ref:`strings` for more about string literals. +Unicode strings are much like strings, but are specified in the syntax +using a preceding ``'u'`` character: ``u'abc'``, ``u"def"``. In addition +to the functionality described here, there are also string-specific +methods described in the :ref:`string-methods` section. Lists are +constructed with square brackets, separating items with commas: ``[a, b, c]``. +Tuples are constructed by the comma operator (not within square +brackets), with or without enclosing parentheses, but an empty tuple +must have the enclosing parentheses, such as ``a, b, c`` or ``()``. A +single item tuple must have a trailing comma, such as ``(d,)``. Buffer objects are not directly supported by Python syntax, but can be created by calling the builtin function :func:`buffer`. They don't support concatenation or repetition. -Xrange objects are similar to buffers in that there is no specific syntax to +Objects of type xrange are similar to buffers in that there is no specific syntax to create them, but they are created using the :func:`xrange` function. They don't support slicing, concatenation or repetition, and using ``in``, ``not in``, :func:`min` or :func:`max` on them is inefficient. @@ -655,9 +661,9 @@ Below are listed the string methods which both 8-bit strings and Unicode objects support. In addition, Python's strings support the sequence type methods -described in the :ref:`typesseq` section (above). To output formatted strings +described in the :ref:`typesseq` section. To output formatted strings use template strings or the ``%`` operator described in the -:ref:`string-formatting` section (below). Also, see the :mod:`re` module for +:ref:`string-formatting` section. Also, see the :mod:`re` module for string functions based on regular expressions. .. method:: str.capitalize() @@ -1406,6 +1412,9 @@ Common uses include membership testing, removing duplicates from a sequence, and computing mathematical operations such as intersection, union, difference, and symmetric difference. +(For other containers see the built in :class:`dict`, :class:`list`, +and :class:`tuple` classes, and the :mod:`collections` module.) + .. versionadded:: 2.4 @@ -1581,12 +1590,19 @@ A :dfn:`mapping` object maps immutable values to arbitrary objects. Mappings are mutable objects. There is currently only one standard mapping type, the -:dfn:`dictionary`. A dictionary's keys are *almost* arbitrary values. Only +:dfn:`dictionary`. +(For other containers see the built in :class:`list`, +:class:`set`, and :class:`tuple` classes, and the :mod:`collections` +module.) + +A dictionary's keys are *almost* arbitrary values. Only values containing lists, dictionaries or other mutable types (that are compared by value rather than by object identity) may not be used as keys. Numeric types used for keys obey the normal rules for numeric comparison: if two numbers compare equal (such as ``1`` and ``1.0``) then they can be used interchangeably -to index the same dictionary entry. +to index the same dictionary entry. (Note however, that since computers +store floating-point numbers as approximations it is usually unwise to +use them as dictionary keys.) Dictionaries can be created by placing a comma-separated list of ``key: value`` pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098: @@ -1611,19 +1627,16 @@ keyword is retained in the dictionary. For example, these all return a dictionary equal to ``{"one": 2, "two": 3}``: - * ``dict({'one': 2, 'two': 3})`` - - * ``dict({'one': 2, 'two': 3}.items())`` + * ``dict(one=2, two=3)`` - * ``dict({'one': 2, 'two': 3}.iteritems())`` + * ``dict({'one': 2, 'two': 3})`` * ``dict(zip(('one', 'two'), (2, 3)))`` * ``dict([['two', 3], ['one', 2]])`` - * ``dict(one=2, two=3)`` - - * ``dict([(['one', 'two'][i-2], i) for i in (2, 3)])`` + The first example only works for keys that are valid Python + identifiers; the others work with any valid keys. .. versionadded:: 2.2 Modified: doctools/trunk/Doc-26/library/sys.rst ============================================================================== --- doctools/trunk/Doc-26/library/sys.rst (original) +++ doctools/trunk/Doc-26/library/sys.rst Wed Aug 8 13:10:08 2007 @@ -19,6 +19,9 @@ the interpreter, ``argv[0]`` is set to the string ``'-c'``. If no script name was passed to the Python interpreter, ``argv[0]`` is the empty string. + To loop over the standard input, or the list of files given on the + command line, see the :mod:`fileinput` module. + .. data:: byteorder Modified: doctools/trunk/Doc-26/library/time.rst ============================================================================== --- doctools/trunk/Doc-26/library/time.rst (original) +++ doctools/trunk/Doc-26/library/time.rst Wed Aug 8 13:10:08 2007 @@ -6,8 +6,11 @@ :synopsis: Time access and conversions. -This module provides various time-related functions. It is always available, -but not all functions are available on all platforms. Most of the functions +This module provides various time-related functions. For related +functionality, see also the :mod:`datetime` and :mod:`calendar` modules. + +Although this module is always available, +not all functions are available on all platforms. Most of the functions defined in this module call platform C library functions with the same name. It may sometimes be helpful to consult the platform documentation, because the semantics of these functions varies among platforms. From python-checkins at python.org Wed Aug 8 13:53:22 2007 From: python-checkins at python.org (georg.brandl) Date: Wed, 8 Aug 2007 13:53:22 +0200 (CEST) Subject: [Python-checkins] r56828 - in doctools/trunk: Doc-26/ACKS Doc-26/TODO Doc-26/about.rst Doc-3k/ACKS Doc-3k/TODO Doc-3k/about.rst Doc-3k/library/calendar.rst Doc-3k/library/collections.rst Doc-3k/library/datetime.rst Doc-3k/library/functions.rst Doc-3k/library/index.rst Doc-3k/library/os.path.rst Doc-3k/library/os.rst Doc-3k/library/stdtypes.rst Doc-3k/library/sys.rst Doc-3k/library/time.rst Message-ID: <20070808115322.7E4E71E400F@bag.python.org> Author: georg.brandl Date: Wed Aug 8 13:53:20 2007 New Revision: 56828 Modified: doctools/trunk/Doc-26/ACKS doctools/trunk/Doc-26/TODO doctools/trunk/Doc-26/about.rst doctools/trunk/Doc-3k/ACKS doctools/trunk/Doc-3k/TODO doctools/trunk/Doc-3k/about.rst doctools/trunk/Doc-3k/library/calendar.rst doctools/trunk/Doc-3k/library/collections.rst doctools/trunk/Doc-3k/library/datetime.rst doctools/trunk/Doc-3k/library/functions.rst doctools/trunk/Doc-3k/library/index.rst doctools/trunk/Doc-3k/library/os.path.rst doctools/trunk/Doc-3k/library/os.rst doctools/trunk/Doc-3k/library/stdtypes.rst doctools/trunk/Doc-3k/library/sys.rst doctools/trunk/Doc-3k/library/time.rst Log: Merge latest two revs, write about. Modified: doctools/trunk/Doc-26/ACKS ============================================================================== --- doctools/trunk/Doc-26/ACKS (original) +++ doctools/trunk/Doc-26/ACKS Wed Aug 8 13:53:20 2007 @@ -6,10 +6,6 @@ anyone else should be on this list, please let us know (send email to docs at python.org), and we'll be glad to correct the problem. -It is only with the input and contributions of the Python community -that Python has such wonderful documentation -- Thank You! - - * Aahz * Michael Abbott * Steve Alexander @@ -28,9 +24,11 @@ * Robin Boerdijk * Michal Bozon * Aaron Brancotti +* Georg Brandl * Keith Briggs * Lee Busby * Lorenzo M. Catucci +* Carl Cerecke * Mauro Cicognini * Gilles Civario * Mike Clarkson Modified: doctools/trunk/Doc-26/TODO ============================================================================== --- doctools/trunk/Doc-26/TODO (original) +++ doctools/trunk/Doc-26/TODO Wed Aug 8 13:53:20 2007 @@ -3,5 +3,4 @@ * split very large files and add toctrees * find out which files get "comments disabled" metadata -* write "About these documents" * finish "Documenting Python" Modified: doctools/trunk/Doc-26/about.rst ============================================================================== --- doctools/trunk/Doc-26/about.rst (original) +++ doctools/trunk/Doc-26/about.rst Wed Aug 8 13:53:20 2007 @@ -14,8 +14,20 @@ docs at python.org mailing list. We're always looking for volunteers wanting to help with the docs, so feel free to send a mail there! -See :ref:`reporting-bugs` for information how to report bugs in Python itself. +Many thanks go to: + +* Fred L. Drake, Jr., the creator of the original Python documentation toolset + and writer of much of the content; +* the `docutils `_ project for creating + reStructuredText and the docutils suite; +* Fredrik Lundh for his `Alternative Python Reference + `_ project from which Sphinx got many good + ideas. -.. % include the ACKS file here so that it can be maintained separately +See :ref:`reporting-bugs` for information how to report bugs in Python itself. +.. including the ACKS file here so that it can be maintained separately .. include:: ACKS + +It is only with the input and contributions of the Python community +that Python has such wonderful documentation -- Thank You! Modified: doctools/trunk/Doc-3k/ACKS ============================================================================== --- doctools/trunk/Doc-3k/ACKS (original) +++ doctools/trunk/Doc-3k/ACKS Wed Aug 8 13:53:20 2007 @@ -6,10 +6,6 @@ anyone else should be on this list, please let us know (send email to docs at python.org), and we'll be glad to correct the problem. -It is only with the input and contributions of the Python community -that Python has such wonderful documentation -- Thank You! - - * Aahz * Michael Abbott * Steve Alexander @@ -28,9 +24,11 @@ * Robin Boerdijk * Michal Bozon * Aaron Brancotti +* Georg Brandl * Keith Briggs * Lee Busby * Lorenzo M. Catucci +* Carl Cerecke * Mauro Cicognini * Gilles Civario * Mike Clarkson Modified: doctools/trunk/Doc-3k/TODO ============================================================================== --- doctools/trunk/Doc-3k/TODO (original) +++ doctools/trunk/Doc-3k/TODO Wed Aug 8 13:53:20 2007 @@ -3,5 +3,4 @@ * split very large files and add toctrees * find out which files get "comments disabled" metadata -* write "About these documents" * finish "Documenting Python" Modified: doctools/trunk/Doc-3k/about.rst ============================================================================== --- doctools/trunk/Doc-3k/about.rst (original) +++ doctools/trunk/Doc-3k/about.rst Wed Aug 8 13:53:20 2007 @@ -14,8 +14,20 @@ docs at python.org mailing list. We're always looking for volunteers wanting to help with the docs, so feel free to send a mail there! -See :ref:`reporting-bugs` for information how to report bugs in Python itself. +Many thanks go to: + +* Fred L. Drake, Jr., the creator of the original Python documentation toolset + and writer of much of the content; +* the `docutils `_ project for creating + reStructuredText and the docutils suite; +* Fredrik Lundh for his `Alternative Python Reference + `_ project from which Sphinx got many good + ideas. -.. % include the ACKS file here so that it can be maintained separately +See :ref:`reporting-bugs` for information how to report bugs in Python itself. +.. including the ACKS file here so that it can be maintained separately .. include:: ACKS + +It is only with the input and contributions of the Python community +that Python has such wonderful documentation -- Thank You! Modified: doctools/trunk/Doc-3k/library/calendar.rst ============================================================================== --- doctools/trunk/Doc-3k/library/calendar.rst (original) +++ doctools/trunk/Doc-3k/library/calendar.rst Wed Aug 8 13:53:20 2007 @@ -13,7 +13,8 @@ these calendars have Monday as the first day of the week, and Sunday as the last (the European convention). Use :func:`setfirstweekday` to set the first day of the week to Sunday (6) or to any other weekday. Parameters that specify dates -are given as integers. +are given as integers. For related +functionality, see also the :mod:`datetime` and :mod:`time` modules. Most of these functions and classses rely on the :mod:`datetime` module which uses an idealized calendar, the current Gregorian calendar indefinitely extended Modified: doctools/trunk/Doc-3k/library/collections.rst ============================================================================== --- doctools/trunk/Doc-3k/library/collections.rst (original) +++ doctools/trunk/Doc-3k/library/collections.rst Wed Aug 8 13:53:20 2007 @@ -13,10 +13,10 @@ This module implements high-performance container datatypes. Currently, there are two datatypes, :class:`deque` and :class:`defaultdict`, and one datatype factory function, :func:`NamedTuple`. Python already -includes built-in containers, :func:`dict`, :func:`list`, and -:func:`tuple`. The optional :mod:`bsddb` module has a :meth:`btopen` -method that can be used to create in-memory or file based ordered -dictionaries with string keys. +includes built-in containers, :class:`dict`, :class:`list`, +:class:`set`, and :class:`tuple`. In addition, the optional :mod:`bsddb` +module has a :meth:`bsddb.btopen` method that can be used to create in-memory +or file based ordered dictionaries with string keys. Future editions of the standard library may include balanced trees and ordered dictionaries. Modified: doctools/trunk/Doc-3k/library/datetime.rst ============================================================================== --- doctools/trunk/Doc-3k/library/datetime.rst (original) +++ doctools/trunk/Doc-3k/library/datetime.rst Wed Aug 8 13:53:20 2007 @@ -16,7 +16,8 @@ The :mod:`datetime` module supplies classes for manipulating dates and times in both simple and complex ways. While date and time arithmetic is supported, the focus of the implementation is on efficient member extraction for output -formatting and manipulation. +formatting and manipulation. For related +functionality, see also the :mod:`time` and :mod:`calendar` modules. There are two kinds of date and time objects: "naive" and "aware". This distinction refers to whether the object has any notion of time zone, daylight Modified: doctools/trunk/Doc-3k/library/functions.rst ============================================================================== --- doctools/trunk/Doc-3k/library/functions.rst (original) +++ doctools/trunk/Doc-3k/library/functions.rst Wed Aug 8 13:53:20 2007 @@ -244,8 +244,10 @@ .. function:: dict([arg]) :noindex: - Create a new dictionary. The dictionary type is described in - :ref:`typesmapping`. + Create a new data dictionary. The dictionary type is described in + :ref:`typesmapping`. For other containers see the built in + :class:`list`, :class:`set`, and :class:`tuple` classes, and the + :mod:`collections` module. .. function:: dir([object]) @@ -325,7 +327,7 @@ ``(1, seq[1])``, ``(2, seq[2])``, .... For example:: >>> for i, season in enumerate(['Spring', 'Summer', 'Fall', 'Winter')]: - >>> print i, season + >>> print i, season 0 Spring 1 Summer 2 Fall @@ -488,7 +490,9 @@ :class:`frozenset` objects. If *iterable* is not specified, returns a new empty set, ``frozenset([])``. - The frozenset type is described in :ref:`types-set`. + The frozenset type is described in :ref:`types-set`. For other containers see the built in + :class:`dict`, :class:`list`, and :class:`tuple` classes, and the + :mod:`collections` module. .. versionadded:: 2.4 @@ -629,7 +633,9 @@ returns ``['a', 'b', 'c']`` and ``list( (1, 2, 3) )`` returns ``[1, 2, 3]``. If no argument is given, returns a new empty list, ``[]``. - :class:`list` is a mutable sequence type, as documented in :ref:`typesseq`. + :class:`list` is a mutable sequence type, as documented in + :ref:`typesseq`. For other containers see the built in :class:`dict`, + :class:`set`, and :class:`tuple` classes, and the :mod:`collections` module. .. function:: locals() @@ -782,6 +788,8 @@ Python enforces that the mode, after stripping ``'U'``, begins with ``'r'``, ``'w'`` or ``'a'``. + See also the :mod:`fileinput` module. + .. versionchanged:: 2.5 Restriction on first letter of mode string introduced. @@ -919,7 +927,9 @@ :class:`frozenset` objects. If *iterable* is not specified, returns a new empty set, ``set([])``. - The set type is described in :ref:`types-set`. + The set type is described in :ref:`types-set`. For other containers see the built in + :class:`dict`, :class:`list`, and :class:`tuple` classes, and the + :mod:`collections` module. .. versionadded:: 2.4 @@ -1060,7 +1070,10 @@ 3])`` returns ``(1, 2, 3)``. If no argument is given, returns a new empty tuple, ``()``. - :class:`tuple` is a mutable sequence type, as documented in :ref:`typesseq`. + :class:`tuple` is an immutable sequence type, as documented in + :ref:`typesseq`. For other containers see the built in :class:`dict`, + :class:`list`, and :class:`set` classes, and the :mod:`collections` module. + .. function:: type(object) Modified: doctools/trunk/Doc-3k/library/index.rst ============================================================================== --- doctools/trunk/Doc-3k/library/index.rst (original) +++ doctools/trunk/Doc-3k/library/index.rst Wed Aug 8 13:53:20 2007 @@ -48,22 +48,21 @@ strings.rst datatypes.rst numeric.rst - netdata.rst - markup.rst - fileformats.rst - crypto.rst filesys.rst - archiving.rst persistence.rst + archiving.rst + fileformats.rst + crypto.rst allos.rst someos.rst - unix.rst ipc.rst + netdata.rst + markup.rst internet.rst mm.rst - tk.rst i18n.rst frameworks.rst + tk.rst development.rst pdb.rst profile.rst @@ -76,4 +75,5 @@ language.rst misc.rst windows.rst + unix.rst undoc.rst Modified: doctools/trunk/Doc-3k/library/os.path.rst ============================================================================== --- doctools/trunk/Doc-3k/library/os.path.rst (original) +++ doctools/trunk/Doc-3k/library/os.path.rst Wed Aug 8 13:53:20 2007 @@ -8,7 +8,9 @@ .. index:: single: path; operations -This module implements some useful functions on pathnames. +This module implements some useful functions on pathnames. To read or +write files see :func:`open`, and for accessing the filesystem see the +:mod:`os` module. .. warning:: Modified: doctools/trunk/Doc-3k/library/os.rst ============================================================================== --- doctools/trunk/Doc-3k/library/os.rst (original) +++ doctools/trunk/Doc-3k/library/os.rst Wed Aug 8 13:53:20 2007 @@ -9,7 +9,8 @@ This module provides a more portable way of using operating system dependent functionality than importing a operating system dependent built-in module like :mod:`posix` or :mod:`nt`. (If you just want to read or write a file see -:func:`open`.) +:func:`open`, and if you want to manipulate paths, see the :mod:`os.path` +module.) This module searches for an operating system dependent built-in module like :mod:`mac` or :mod:`posix` and exports the same functions and data as found Modified: doctools/trunk/Doc-3k/library/stdtypes.rst ============================================================================== --- doctools/trunk/Doc-3k/library/stdtypes.rst (original) +++ doctools/trunk/Doc-3k/library/stdtypes.rst Wed Aug 8 13:53:20 2007 @@ -485,31 +485,34 @@ There are six sequence types: strings, Unicode strings, lists, tuples, buffers, and range objects. +(For other containers see the built in :class:`dict`, :class:`list`, +:class:`set`, and :class:`tuple` classes, and the :mod:`collections` +module.) + .. index:: object: sequence object: string - object: Unicode object: tuple object: list object: buffer object: range String literals are written in single or double quotes: ``'xyzzy'``, -``"frobozz"``. See :ref:`strings` for more about string literals. Unicode -strings are much like strings, but are specified in the syntax using a preceding -``'u'`` character: ``u'abc'``, ``u"def"``. Lists are constructed with square -brackets, separating items with commas: ``[a, b, c]``. Tuples are constructed -by the comma operator (not within square brackets), with or without enclosing -parentheses, but an empty tuple must have the enclosing parentheses, such as -``a, b, c`` or ``()``. A single item tuple must have a trailing comma, such as -``(d,)``. +``"frobozz"``. See :ref:`strings` for more about string literals. In addition +to the functionality described here, there are also string-specific methods +described in the :ref:`string-methods` section. Lists are constructed with +square brackets, separating items with commas: ``[a, b, c]``. Tuples are +constructed by the comma operator (not within square brackets), with or without +enclosing parentheses, but an empty tuple must have the enclosing parentheses, +such as ``a, b, c`` or ``()``. A single item tuple must have a trailing comma, +such as ``(d,)``. Buffer objects are not directly supported by Python syntax, but can be created by calling the builtin function :func:`buffer`. They don't support concatenation or repetition. -Xrange objects are similar to buffers in that there is no specific syntax to +Objects of type range are similar to buffers in that there is no specific syntax to create them, but they are created using the :func:`range` function. They don't support slicing, concatenation or repetition, and using ``in``, ``not in``, :func:`min` or :func:`max` on them is inefficient. @@ -648,9 +651,9 @@ Below are listed the string methods which both 8-bit strings and Unicode objects support. In addition, Python's strings support the sequence type methods -described in the :ref:`typesseq` section (above). To output formatted strings +described in the :ref:`typesseq` section. To output formatted strings use template strings or the ``%`` operator described in the -:ref:`string-formatting` section (below). Also, see the :mod:`re` module for +:ref:`string-formatting` section. Also, see the :mod:`re` module for string functions based on regular expressions. .. method:: str.capitalize() @@ -1399,6 +1402,9 @@ Common uses include membership testing, removing duplicates from a sequence, and computing mathematical operations such as intersection, union, difference, and symmetric difference. +(For other containers see the built in :class:`dict`, :class:`list`, +and :class:`tuple` classes, and the :mod:`collections` module.) + .. versionadded:: 2.4 @@ -1565,12 +1571,19 @@ A :dfn:`mapping` object maps immutable values to arbitrary objects. Mappings are mutable objects. There is currently only one standard mapping type, the -:dfn:`dictionary`. A dictionary's keys are *almost* arbitrary values. Only +:dfn:`dictionary`. +(For other containers see the built in :class:`list`, +:class:`set`, and :class:`tuple` classes, and the :mod:`collections` +module.) + +A dictionary's keys are *almost* arbitrary values. Only values containing lists, dictionaries or other mutable types (that are compared by value rather than by object identity) may not be used as keys. Numeric types used for keys obey the normal rules for numeric comparison: if two numbers compare equal (such as ``1`` and ``1.0``) then they can be used interchangeably -to index the same dictionary entry. +to index the same dictionary entry. (Note however, that since computers +store floating-point numbers as approximations it is usually unwise to +use them as dictionary keys.) Dictionaries can be created by placing a comma-separated list of ``key: value`` pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098: @@ -1595,19 +1608,16 @@ keyword is retained in the dictionary. For example, these all return a dictionary equal to ``{"one": 2, "two": 3}``: - * ``dict({'one': 2, 'two': 3})`` - - * ``dict({'one': 2, 'two': 3}.items())`` + * ``dict(one=2, two=3)`` - * ``dict({'one': 2, 'two': 3}.iteritems())`` + * ``dict({'one': 2, 'two': 3})`` * ``dict(zip(('one', 'two'), (2, 3)))`` * ``dict([['two', 3], ['one', 2]])`` - * ``dict(one=2, two=3)`` - - * ``dict([(['one', 'two'][i-2], i) for i in (2, 3)])`` + The first example only works for keys that are valid Python + identifiers; the others work with any valid keys. .. versionadded:: 2.2 Modified: doctools/trunk/Doc-3k/library/sys.rst ============================================================================== --- doctools/trunk/Doc-3k/library/sys.rst (original) +++ doctools/trunk/Doc-3k/library/sys.rst Wed Aug 8 13:53:20 2007 @@ -19,6 +19,9 @@ the interpreter, ``argv[0]`` is set to the string ``'-c'``. If no script name was passed to the Python interpreter, ``argv[0]`` is the empty string. + To loop over the standard input, or the list of files given on the + command line, see the :mod:`fileinput` module. + .. data:: byteorder Modified: doctools/trunk/Doc-3k/library/time.rst ============================================================================== --- doctools/trunk/Doc-3k/library/time.rst (original) +++ doctools/trunk/Doc-3k/library/time.rst Wed Aug 8 13:53:20 2007 @@ -6,8 +6,11 @@ :synopsis: Time access and conversions. -This module provides various time-related functions. It is always available, -but not all functions are available on all platforms. Most of the functions +This module provides various time-related functions. For related +functionality, see also the :mod:`datetime` and :mod:`calendar` modules. + +Although this module is always available, +not all functions are available on all platforms. Most of the functions defined in this module call platform C library functions with the same name. It may sometimes be helpful to consult the platform documentation, because the semantics of these functions varies among platforms. From python-checkins at python.org Wed Aug 8 14:07:33 2007 From: python-checkins at python.org (georg.brandl) Date: Wed, 8 Aug 2007 14:07:33 +0200 (CEST) Subject: [Python-checkins] r56829 - in doctools/trunk: Doc-26/library/functions.rst Doc-26/library/stdtypes.rst Doc-3k/library/functions.rst Doc-3k/library/stdtypes.rst Message-ID: <20070808120733.8A5B51E400F@bag.python.org> Author: georg.brandl Date: Wed Aug 8 14:07:32 2007 New Revision: 56829 Modified: doctools/trunk/Doc-26/library/functions.rst doctools/trunk/Doc-26/library/stdtypes.rst doctools/trunk/Doc-3k/library/functions.rst doctools/trunk/Doc-3k/library/stdtypes.rst Log: Document set constructors in stdtypes. Modified: doctools/trunk/Doc-26/library/functions.rst ============================================================================== --- doctools/trunk/Doc-26/library/functions.rst (original) +++ doctools/trunk/Doc-26/library/functions.rst Wed Aug 8 14:07:32 2007 @@ -234,6 +234,7 @@ The complex type is described in :ref:`typesnumeric`. + .. function:: delattr(object, name) This is a relative of :func:`setattr`. The arguments are an object and a @@ -245,10 +246,11 @@ .. function:: dict([arg]) :noindex: - Create a new data dictionary. The dictionary type is described in - :ref:`typesmapping`. For other containers see the built in - :class:`list`, :class:`set`, and :class:`tuple` classes, and the - :mod:`collections` module. + Create a new data dictionary, optionally with items taken from *arg*. + The dictionary type is described in :ref:`typesmapping`. + + For other containers see the built in :class:`list`, :class:`set`, and + :class:`tuple` classes, and the :mod:`collections` module. .. function:: dir([object]) @@ -451,17 +453,13 @@ The float type is described in :ref:`typesnumeric`. .. function:: frozenset([iterable]) + :noindex: - Return a frozenset object whose elements are taken from *iterable*. Frozensets - are sets that have no update methods but can be hashed and used as members of - other sets or as dictionary keys. The elements of a frozenset must be immutable - themselves. To represent sets of sets, the inner sets should also be - :class:`frozenset` objects. If *iterable* is not specified, returns a new empty - set, ``frozenset([])``. - - The frozenset type is described in :ref:`types-set`. For other containers see the built in - :class:`dict`, :class:`list`, and :class:`tuple` classes, and the - :mod:`collections` module. + Return a frozenset object, optionally with elements taken from *iterable*. + The frozenset type is described in :ref:`types-set`. + + For other containers see the built in :class:`dict`, :class:`list`, and + :class:`tuple` classes, and the :mod:`collections` module. .. versionadded:: 2.4 @@ -990,15 +988,13 @@ .. function:: set([iterable]) + :noindex: + + Return a new set, optionally with elements are taken from *iterable*. + The set type is described in :ref:`types-set`. - Return a set whose elements are taken from *iterable*. The elements must be - immutable. To represent sets of sets, the inner sets should be - :class:`frozenset` objects. If *iterable* is not specified, returns a new empty - set, ``set([])``. - - The set type is described in :ref:`types-set`. For other containers see the built in - :class:`dict`, :class:`list`, and :class:`tuple` classes, and the - :mod:`collections` module. + For other containers see the built in :class:`dict`, :class:`list`, and + :class:`tuple` classes, and the :mod:`collections` module. .. versionadded:: 2.4 Modified: doctools/trunk/Doc-26/library/stdtypes.rst ============================================================================== --- doctools/trunk/Doc-26/library/stdtypes.rst (original) +++ doctools/trunk/Doc-26/library/stdtypes.rst Wed Aug 8 14:07:32 2007 @@ -1428,8 +1428,18 @@ like :meth:`add` and :meth:`remove`. Since it is mutable, it has no hash value and cannot be used as either a dictionary key or as an element of another set. The :class:`frozenset` type is immutable and hashable --- its contents cannot be -altered after is created; however, it can be used as a dictionary key or as an -element of another set. +altered after it is created; it can therefore be used as a dictionary key or as +an element of another set. + +The constructors for both classes work the same: + +.. class:: set([iterable]) + frozenset([iterable]) + + Return a new set or frozenset object whose elements are taken from + *iterable*. The elements of a set must be hashable. To represent sets of + sets, the inner sets must be :class:`frozenset` objects. If *iterable* is + not specified, a new empty set is returned. Instances of :class:`set` and :class:`frozenset` provide the following operations: Modified: doctools/trunk/Doc-3k/library/functions.rst ============================================================================== --- doctools/trunk/Doc-3k/library/functions.rst (original) +++ doctools/trunk/Doc-3k/library/functions.rst Wed Aug 8 14:07:32 2007 @@ -233,6 +233,7 @@ The complex type is described in :ref:`typesnumeric`. + .. function:: delattr(object, name) This is a relative of :func:`setattr`. The arguments are an object and a @@ -244,10 +245,11 @@ .. function:: dict([arg]) :noindex: - Create a new data dictionary. The dictionary type is described in - :ref:`typesmapping`. For other containers see the built in - :class:`list`, :class:`set`, and :class:`tuple` classes, and the - :mod:`collections` module. + Create a new data dictionary, optionally with items taken from *arg*. + The dictionary type is described in :ref:`typesmapping`. + + For other containers see the built in :class:`list`, :class:`set`, and + :class:`tuple` classes, and the :mod:`collections` module. .. function:: dir([object]) @@ -482,17 +484,13 @@ The float type is described in :ref:`typesnumeric`. .. function:: frozenset([iterable]) + :noindex: - Return a frozenset object whose elements are taken from *iterable*. Frozensets - are sets that have no update methods but can be hashed and used as members of - other sets or as dictionary keys. The elements of a frozenset must be immutable - themselves. To represent sets of sets, the inner sets should also be - :class:`frozenset` objects. If *iterable* is not specified, returns a new empty - set, ``frozenset([])``. - - The frozenset type is described in :ref:`types-set`. For other containers see the built in - :class:`dict`, :class:`list`, and :class:`tuple` classes, and the - :mod:`collections` module. + Return a frozenset object, optionally with elements taken from *iterable*. + The frozenset type is described in :ref:`types-set`. + + For other containers see the built in :class:`dict`, :class:`list`, and + :class:`tuple` classes, and the :mod:`collections` module. .. versionadded:: 2.4 @@ -921,15 +919,13 @@ .. function:: set([iterable]) + :noindex: + + Return a new set, optionally with elements are taken from *iterable*. + The set type is described in :ref:`types-set`. - Return a set whose elements are taken from *iterable*. The elements must be - immutable. To represent sets of sets, the inner sets should be - :class:`frozenset` objects. If *iterable* is not specified, returns a new empty - set, ``set([])``. - - The set type is described in :ref:`types-set`. For other containers see the built in - :class:`dict`, :class:`list`, and :class:`tuple` classes, and the - :mod:`collections` module. + For other containers see the built in :class:`dict`, :class:`list`, and + :class:`tuple` classes, and the :mod:`collections` module. .. versionadded:: 2.4 Modified: doctools/trunk/Doc-3k/library/stdtypes.rst ============================================================================== --- doctools/trunk/Doc-3k/library/stdtypes.rst (original) +++ doctools/trunk/Doc-3k/library/stdtypes.rst Wed Aug 8 14:07:32 2007 @@ -1418,8 +1418,18 @@ like :meth:`add` and :meth:`remove`. Since it is mutable, it has no hash value and cannot be used as either a dictionary key or as an element of another set. The :class:`frozenset` type is immutable and hashable --- its contents cannot be -altered after is created; however, it can be used as a dictionary key or as an -element of another set. +altered after it is created; it can therefore be used as a dictionary key or as +an element of another set. + +The constructors for both classes work the same: + +.. class:: set([iterable]) + frozenset([iterable]) + + Return a new set or frozenset object whose elements are taken from + *iterable*. The elements of a set must be hashable. To represent sets of + sets, the inner sets must be :class:`frozenset` objects. If *iterable* is + not specified, a new empty set is returned. Instances of :class:`set` and :class:`frozenset` provide the following operations: From python-checkins at python.org Wed Aug 8 15:03:42 2007 From: python-checkins at python.org (georg.brandl) Date: Wed, 8 Aug 2007 15:03:42 +0200 (CEST) Subject: [Python-checkins] r56830 - in python/trunk: Doc/lib/libstringio.tex Lib/test/test_StringIO.py Misc/NEWS Modules/cStringIO.c Message-ID: <20070808130342.2A7DE1E4006@bag.python.org> Author: georg.brandl Date: Wed Aug 8 15:03:41 2007 New Revision: 56830 Modified: python/trunk/Doc/lib/libstringio.tex python/trunk/Lib/test/test_StringIO.py python/trunk/Misc/NEWS python/trunk/Modules/cStringIO.c Log: Revert the fix for #1548891, it broke backwards compatibility with arbitrary read buffers. Fixes #1730114. Modified: python/trunk/Doc/lib/libstringio.tex ============================================================================== --- python/trunk/Doc/lib/libstringio.tex (original) +++ python/trunk/Doc/lib/libstringio.tex Wed Aug 8 15:03:41 2007 @@ -78,6 +78,10 @@ module, those provided by this module are not able to accept Unicode strings that cannot be encoded as plain \ASCII{} strings. +Calling \function{StringIO()} with a Unicode string parameter populates +the object with the buffer representation of the Unicode string, instead of +encoding the string. + Another difference from the \refmodule{StringIO} module is that calling \function{StringIO()} with a string parameter creates a read-only object. Unlike an object created without a string parameter, it does not have Modified: python/trunk/Lib/test/test_StringIO.py ============================================================================== --- python/trunk/Lib/test/test_StringIO.py (original) +++ python/trunk/Lib/test/test_StringIO.py Wed Aug 8 15:03:41 2007 @@ -121,28 +121,6 @@ class TestcStringIO(TestGenericStringIO): MODULE = cStringIO - def test_unicode(self): - - if not test_support.have_unicode: return - - # The cStringIO module converts Unicode strings to character - # strings when writing them to cStringIO objects. - # Check that this works. - - f = self.MODULE.StringIO() - f.write(unicode(self._line[:5])) - s = f.getvalue() - self.assertEqual(s, 'abcde') - self.assertEqual(type(s), types.StringType) - - f = self.MODULE.StringIO(unicode(self._line[:5])) - s = f.getvalue() - self.assertEqual(s, 'abcde') - self.assertEqual(type(s), types.StringType) - - self.assertRaises(UnicodeEncodeError, self.MODULE.StringIO, - unicode('\xf4', 'latin-1')) - import sys if sys.platform.startswith('java'): # Jython doesn't have a buffer object, so we just do a useless Modified: python/trunk/Misc/NEWS ============================================================================== --- python/trunk/Misc/NEWS (original) +++ python/trunk/Misc/NEWS Wed Aug 8 15:03:41 2007 @@ -782,10 +782,6 @@ - Patch #1576166: Support os.utime for directories on Windows NT+. -- Bug #1548891: The cStringIO.StringIO() constructor now encodes unicode - arguments with the system default encoding just like the write() - method does, instead of converting it to a raw buffer. - - Patch #1572724: fix typo ('=' instead of '==') in _msi.c. - Bug #1572832: fix a bug in ISO-2022 codecs which may cause segfault Modified: python/trunk/Modules/cStringIO.c ============================================================================== --- python/trunk/Modules/cStringIO.c (original) +++ python/trunk/Modules/cStringIO.c Wed Aug 8 15:03:41 2007 @@ -673,8 +673,11 @@ char *buf; Py_ssize_t size; - if (PyObject_AsCharBuffer(s, (const char **)&buf, &size) != 0) - return NULL; + if (PyObject_AsReadBuffer(s, (const char **)&buf, &size)) { + PyErr_Format(PyExc_TypeError, "expected read buffer, %.200s found", + s->ob_type->tp_name); + return NULL; + } self = PyObject_New(Iobject, &Itype); if (!self) return NULL; From python-checkins at python.org Wed Aug 8 15:03:45 2007 From: python-checkins at python.org (georg.brandl) Date: Wed, 8 Aug 2007 15:03:45 +0200 (CEST) Subject: [Python-checkins] r56831 - in python/branches/release25-maint: Doc/lib/libstringio.tex Lib/test/test_StringIO.py Misc/NEWS Modules/cStringIO.c Message-ID: <20070808130345.8C6F51E400A@bag.python.org> Author: georg.brandl Date: Wed Aug 8 15:03:45 2007 New Revision: 56831 Modified: python/branches/release25-maint/Doc/lib/libstringio.tex python/branches/release25-maint/Lib/test/test_StringIO.py python/branches/release25-maint/Misc/NEWS python/branches/release25-maint/Modules/cStringIO.c Log: Revert the fix for #1548891, it broke backwards compatibility with arbitrary read buffers. Fixes #1730114. (backport from rev. 56830) Modified: python/branches/release25-maint/Doc/lib/libstringio.tex ============================================================================== --- python/branches/release25-maint/Doc/lib/libstringio.tex (original) +++ python/branches/release25-maint/Doc/lib/libstringio.tex Wed Aug 8 15:03:45 2007 @@ -78,6 +78,10 @@ module, those provided by this module are not able to accept Unicode strings that cannot be encoded as plain \ASCII{} strings. +Calling \function{StringIO()} with a Unicode string parameter populates +the object with the buffer representation of the Unicode string, instead of +encoding the string. + Another difference from the \refmodule{StringIO} module is that calling \function{StringIO()} with a string parameter creates a read-only object. Unlike an object created without a string parameter, it does not have Modified: python/branches/release25-maint/Lib/test/test_StringIO.py ============================================================================== --- python/branches/release25-maint/Lib/test/test_StringIO.py (original) +++ python/branches/release25-maint/Lib/test/test_StringIO.py Wed Aug 8 15:03:45 2007 @@ -120,28 +120,6 @@ class TestcStringIO(TestGenericStringIO): MODULE = cStringIO - def test_unicode(self): - - if not test_support.have_unicode: return - - # The cStringIO module converts Unicode strings to character - # strings when writing them to cStringIO objects. - # Check that this works. - - f = self.MODULE.StringIO() - f.write(unicode(self._line[:5])) - s = f.getvalue() - self.assertEqual(s, 'abcde') - self.assertEqual(type(s), types.StringType) - - f = self.MODULE.StringIO(unicode(self._line[:5])) - s = f.getvalue() - self.assertEqual(s, 'abcde') - self.assertEqual(type(s), types.StringType) - - self.assertRaises(UnicodeEncodeError, self.MODULE.StringIO, - unicode('\xf4', 'latin-1')) - import sys if sys.platform.startswith('java'): # Jython doesn't have a buffer object, so we just do a useless Modified: python/branches/release25-maint/Misc/NEWS ============================================================================== --- python/branches/release25-maint/Misc/NEWS (original) +++ python/branches/release25-maint/Misc/NEWS Wed Aug 8 15:03:45 2007 @@ -26,6 +26,9 @@ Library ------- +- Reverted the fix for bug #1548891 because it broke compatibility with + arbitrary read buffers. Added a note in the documentation. + - GB18030 codec now can encode additional two-byte characters that are missing in GBK. Modified: python/branches/release25-maint/Modules/cStringIO.c ============================================================================== --- python/branches/release25-maint/Modules/cStringIO.c (original) +++ python/branches/release25-maint/Modules/cStringIO.c Wed Aug 8 15:03:45 2007 @@ -665,8 +665,11 @@ char *buf; Py_ssize_t size; - if (PyObject_AsCharBuffer(s, (const char **)&buf, &size) != 0) - return NULL; + if (PyObject_AsReadBuffer(s, (const char **)&buf, &size)) { + PyErr_Format(PyExc_TypeError, "expected read buffer, %.200s found", + s->ob_type->tp_name); + return NULL; + } self = PyObject_New(Iobject, &Itype); if (!self) return NULL; From python-checkins at python.org Wed Aug 8 15:05:17 2007 From: python-checkins at python.org (georg.brandl) Date: Wed, 8 Aug 2007 15:05:17 +0200 (CEST) Subject: [Python-checkins] r56832 - in doctools/trunk: Doc-26/library/stringio.rst Doc-3k/library/stringio.rst Message-ID: <20070808130517.7CF831E4006@bag.python.org> Author: georg.brandl Date: Wed Aug 8 15:05:17 2007 New Revision: 56832 Modified: doctools/trunk/Doc-26/library/stringio.rst doctools/trunk/Doc-3k/library/stringio.rst Log: Port rev. 56830. Modified: doctools/trunk/Doc-26/library/stringio.rst ============================================================================== --- doctools/trunk/Doc-26/library/stringio.rst (original) +++ doctools/trunk/Doc-26/library/stringio.rst Wed Aug 8 15:05:17 2007 @@ -77,6 +77,10 @@ provided by this module are not able to accept Unicode strings that cannot be encoded as plain ASCII strings. +Calling :func:`StringIO` with a Unicode string parameter populates +the object with the buffer representation of the Unicode string, instead of +encoding the string. + Another difference from the :mod:`StringIO` module is that calling :func:`StringIO` with a string parameter creates a read-only object. Unlike an object created without a string parameter, it does not have write methods. Modified: doctools/trunk/Doc-3k/library/stringio.rst ============================================================================== --- doctools/trunk/Doc-3k/library/stringio.rst (original) +++ doctools/trunk/Doc-3k/library/stringio.rst Wed Aug 8 15:05:17 2007 @@ -77,6 +77,10 @@ provided by this module are not able to accept Unicode strings that cannot be encoded as plain ASCII strings. +Calling :func:`StringIO` with a Unicode string parameter populates +the object with the buffer representation of the Unicode string, instead of +encoding the string. + Another difference from the :mod:`StringIO` module is that calling :func:`StringIO` with a string parameter creates a read-only object. Unlike an object created without a string parameter, it does not have write methods. From buildbot at python.org Wed Aug 8 15:39:14 2007 From: buildbot at python.org (buildbot at python.org) Date: Wed, 08 Aug 2007 13:39:14 +0000 Subject: [Python-checkins] buildbot warnings in x86 gentoo trunk Message-ID: <20070808133914.653621E4006@bag.python.org> The Buildbot has detected a new failure of x86 gentoo trunk. Full details are available at: http://www.python.org/dev/buildbot/all/x86%2520gentoo%2520trunk/builds/2347 Buildbot URL: http://www.python.org/dev/buildbot/all/ Build Reason: Build Source Stamp: [branch trunk] HEAD Blamelist: georg.brandl Build had warnings: warnings test Excerpt from the test logfile: 1 test failed: test_ftplib make: *** [buildbottest] Error 1 sincerely, -The Buildbot From python-checkins at python.org Wed Aug 8 15:50:02 2007 From: python-checkins at python.org (georg.brandl) Date: Wed, 8 Aug 2007 15:50:02 +0200 (CEST) Subject: [Python-checkins] r56833 - python/trunk/Modules/cStringIO.c Message-ID: <20070808135002.7E86F1E4006@bag.python.org> Author: georg.brandl Date: Wed Aug 8 15:50:02 2007 New Revision: 56833 Modified: python/trunk/Modules/cStringIO.c Log: Fix compilation warning. Modified: python/trunk/Modules/cStringIO.c ============================================================================== --- python/trunk/Modules/cStringIO.c (original) +++ python/trunk/Modules/cStringIO.c Wed Aug 8 15:50:02 2007 @@ -673,7 +673,7 @@ char *buf; Py_ssize_t size; - if (PyObject_AsReadBuffer(s, (const char **)&buf, &size)) { + if (PyObject_AsReadBuffer(s, (const void **)&buf, &size)) { PyErr_Format(PyExc_TypeError, "expected read buffer, %.200s found", s->ob_type->tp_name); return NULL; From python-checkins at python.org Wed Aug 8 15:50:05 2007 From: python-checkins at python.org (georg.brandl) Date: Wed, 8 Aug 2007 15:50:05 +0200 (CEST) Subject: [Python-checkins] r56834 - python/branches/release25-maint/Modules/cStringIO.c Message-ID: <20070808135005.A01B21E400C@bag.python.org> Author: georg.brandl Date: Wed Aug 8 15:50:04 2007 New Revision: 56834 Modified: python/branches/release25-maint/Modules/cStringIO.c Log: Fix compilation warning. (backport from rev. 56833) Modified: python/branches/release25-maint/Modules/cStringIO.c ============================================================================== --- python/branches/release25-maint/Modules/cStringIO.c (original) +++ python/branches/release25-maint/Modules/cStringIO.c Wed Aug 8 15:50:04 2007 @@ -665,7 +665,7 @@ char *buf; Py_ssize_t size; - if (PyObject_AsReadBuffer(s, (const char **)&buf, &size)) { + if (PyObject_AsReadBuffer(s, (const void **)&buf, &size)) { PyErr_Format(PyExc_TypeError, "expected read buffer, %.200s found", s->ob_type->tp_name); return NULL; From buildbot at python.org Wed Aug 8 16:08:50 2007 From: buildbot at python.org (buildbot at python.org) Date: Wed, 08 Aug 2007 14:08:50 +0000 Subject: [Python-checkins] buildbot warnings in ia64 Ubuntu trunk trunk Message-ID: <20070808140850.44F4E1E4011@bag.python.org> The Buildbot has detected a new failure of ia64 Ubuntu trunk trunk. Full details are available at: http://www.python.org/dev/buildbot/all/ia64%2520Ubuntu%2520trunk%2520trunk/builds/789 Buildbot URL: http://www.python.org/dev/buildbot/all/ Build Reason: Build Source Stamp: [branch trunk] HEAD Blamelist: georg.brandl Build had warnings: warnings test Excerpt from the test logfile: 1 test failed: test_socket_ssl make: *** [buildbottest] Error 1 sincerely, -The Buildbot From buildbot at python.org Wed Aug 8 17:17:02 2007 From: buildbot at python.org (buildbot at python.org) Date: Wed, 08 Aug 2007 15:17:02 +0000 Subject: [Python-checkins] buildbot warnings in PPC64 Debian trunk Message-ID: <20070808151702.ED6381E400D@bag.python.org> The Buildbot has detected a new failure of PPC64 Debian trunk. Full details are available at: http://www.python.org/dev/buildbot/all/PPC64%2520Debian%2520trunk/builds/92 Buildbot URL: http://www.python.org/dev/buildbot/all/ Build Reason: Build Source Stamp: [branch trunk] HEAD Blamelist: georg.brandl Build had warnings: warnings test Excerpt from the test logfile: make: *** [buildbottest] Segmentation fault sincerely, -The Buildbot From buildbot at python.org Wed Aug 8 17:51:41 2007 From: buildbot at python.org (buildbot at python.org) Date: Wed, 08 Aug 2007 15:51:41 +0000 Subject: [Python-checkins] buildbot warnings in S-390 Debian trunk Message-ID: <20070808155142.664741E400D@bag.python.org> The Buildbot has detected a new failure of S-390 Debian trunk. Full details are available at: http://www.python.org/dev/buildbot/all/S-390%2520Debian%2520trunk/builds/1082 Buildbot URL: http://www.python.org/dev/buildbot/all/ Build Reason: Build Source Stamp: [branch trunk] HEAD Blamelist: georg.brandl Build had warnings: warnings test Excerpt from the test logfile: 1 test failed: test_time make: *** [buildbottest] Error 1 sincerely, -The Buildbot From python-checkins at python.org Thu Aug 9 05:41:42 2007 From: python-checkins at python.org (brett.cannon) Date: Thu, 9 Aug 2007 05:41:42 +0200 (CEST) Subject: [Python-checkins] r56842 - sandbox/trunk/import_in_py/zipimport_/tests.py sandbox/trunk/import_in_py/zipimport_/zipimport.py Message-ID: <20070809034142.49D621E4162@bag.python.org> Author: brett.cannon Date: Thu Aug 9 05:41:41 2007 New Revision: 56842 Modified: sandbox/trunk/import_in_py/zipimport_/tests.py sandbox/trunk/import_in_py/zipimport_/zipimport.py Log: Implement zipimport.zipimporter.find_module(). Modified: sandbox/trunk/import_in_py/zipimport_/tests.py ============================================================================== --- sandbox/trunk/import_in_py/zipimport_/tests.py (original) +++ sandbox/trunk/import_in_py/zipimport_/tests.py Thu Aug 9 05:41:41 2007 @@ -10,24 +10,30 @@ @contextlib.contextmanager -def temp_zipfile(): +def temp_zipfile(source=True, bytecode=True): """Create a temporary zip file for testing.""" zip_path = test_support.TESTFN + '.zip' zip_file = zipfile.ZipFile(zip_path, 'w') try: - for module_path in ['_top_level.py']: + os.mkdir('_pkg') + for module_path in ['_top_level.py', os.path.join('_pkg', '__init__.py'), + os.path.join('_pkg', 'submodule.py')]: with open(module_path, 'w') as temp_file: temp_file.write('attr = None') try: - py_compile.compile(module_path, doraise=True) - zip_file.write(module_path) - zip_file.write(module_path + 'c' if __debug__ else 'o') + if source: + zip_file.write(module_path) + if bytecode: + py_compile.compile(module_path, doraise=True) + zip_file.write(module_path + 'c' if __debug__ else 'o') finally: test_support.unlink(module_path) test_support.unlink(module_path + 'c' if __debug__ else 'o') zip_file.close() yield zip_path finally: + if os.path.exists('_pkg'): + os.rmdir('_pkg') os.unlink(zip_path) @@ -61,8 +67,43 @@ self.assert_(isinstance(zip_importer, zipimport.zipimporter)) +class FindModule(unittest.TestCase): + + """Test the finding of modules.""" + + def look_for(self, module_name): + """Return what zipimporter.find_module() returns.""" + for args in [[True, True], [True, False], [False, True]]: + with temp_zipfile(*args) as zip_path: + importer = zipimport.zipimporter(zip_path) + yield (importer, importer.find_module(module_name)) + + def test_top_level(self): + # Should be able to find a top-level module if there is source, + # bytecode, or both. + for importer, result in self.look_for('_pkg'): + self.assert_(importer is result) + for importer, result in self.look_for('_bogus'): + self.assert_(result is None) + + def test_pkg(self): + # Finding a package should work. + for importer, result in self.look_for('_pkg'): + self.assert_(importer is result) + + def test_submodule(self): + # A submodule in a package should work. + for importer, result in self.look_for('_pkg.submodule'): + self.assert_(importer is result) + for importer, result in self.look_for('_bogus.submodule'): + self.assert_(result is None) + for importer, result in self.look_for('_pkg.bogus'): + self.assert_(result is None) + + def test_main(): - test_support.run_unittest(ZipImportErrorTests, ZipImportCreation) + test_support.run_unittest(ZipImportErrorTests, ZipImportCreation, + FindModule) if __name__ == '__main__': Modified: sandbox/trunk/import_in_py/zipimport_/zipimport.py ============================================================================== --- sandbox/trunk/import_in_py/zipimport_/zipimport.py (original) +++ sandbox/trunk/import_in_py/zipimport_/zipimport.py Thu Aug 9 05:41:41 2007 @@ -1,6 +1,7 @@ """A re-implementation of zipimport to use importlib.""" import importlib +import os import zipfile @@ -24,7 +25,24 @@ self._zip = zipfile.ZipFile(archivepath, 'r') def find_module(self, fullname, path=None): - raise NotImplementedError + """Check if the specified module is contained within the zip file, + returning self if it is or None if it is not.""" + path_name = fullname.replace('.', os.sep) + # XXX Really should use imp.getprefixes(). + path_name_source = path_name + '.py' + path_name_bytecode = path_name_source + ('c' if __debug__ else 'o') + path_pkg_name_source = os.path.join(path_name, '__init__.py') + path_pkg_name_bytecode = path_pkg_name_source + ('c' if __debug__ else 'o') + for possible_name in (path_pkg_name_source, path_pkg_name_bytecode, + path_name_bytecode, path_name_source): + try: + self._zip.getinfo(possible_name) + except KeyError: + continue + else: + return self + else: + return None def get_code(self, fullname): raise NotImplementedError From python-checkins at python.org Thu Aug 9 06:10:54 2007 From: python-checkins at python.org (brett.cannon) Date: Thu, 9 Aug 2007 06:10:54 +0200 (CEST) Subject: [Python-checkins] r56843 - sandbox/trunk/import_in_py/zipimport_/tests.py sandbox/trunk/import_in_py/zipimport_/zipimport.py Message-ID: <20070809041054.7C7411E4007@bag.python.org> Author: brett.cannon Date: Thu Aug 9 06:10:53 2007 New Revision: 56843 Modified: sandbox/trunk/import_in_py/zipimport_/tests.py sandbox/trunk/import_in_py/zipimport_/zipimport.py Log: Implement zipimporter.get_data() and zipimporter.is_package(). Modified: sandbox/trunk/import_in_py/zipimport_/tests.py ============================================================================== --- sandbox/trunk/import_in_py/zipimport_/tests.py (original) +++ sandbox/trunk/import_in_py/zipimport_/tests.py Thu Aug 9 06:10:53 2007 @@ -8,6 +8,7 @@ import unittest import zipfile +example_code = 'attr = None' @contextlib.contextmanager def temp_zipfile(source=True, bytecode=True): @@ -19,7 +20,7 @@ for module_path in ['_top_level.py', os.path.join('_pkg', '__init__.py'), os.path.join('_pkg', 'submodule.py')]: with open(module_path, 'w') as temp_file: - temp_file.write('attr = None') + temp_file.write(example_code) try: if source: zip_file.write(module_path) @@ -101,9 +102,35 @@ self.assert_(result is None) +class GetData(unittest.TestCase): + + """Test zipimporter.get_data().""" + + def test_text(self): + # Reading some text should work. + with temp_zipfile(bytecode=False) as zip_path: + importer = zipimport.zipimporter(zip_path) + self.assertEqual(importer.get_data('_top_level.py'), example_code) + # XXX Test that file reading is done in binary mode. + + +class IsPackage(unittest.TestCase): + + """test zipimporter.is_package().""" + + def test_pkg(self): + # A package should always return True. + for args in [[True, True], [True, False], [False, True]]: + with temp_zipfile(*args) as zip_path: + importer = zipimport.zipimporter(zip_path) + self.assert_(importer.is_package('_pkg')) + self.assert_(not importer.is_package('_top_level')) + self.assert_(not importer.is_package('_pkg.submodule')) + + def test_main(): test_support.run_unittest(ZipImportErrorTests, ZipImportCreation, - FindModule) + FindModule, GetData, IsPackage) if __name__ == '__main__': Modified: sandbox/trunk/import_in_py/zipimport_/zipimport.py ============================================================================== --- sandbox/trunk/import_in_py/zipimport_/zipimport.py (original) +++ sandbox/trunk/import_in_py/zipimport_/zipimport.py Thu Aug 9 06:10:53 2007 @@ -23,6 +23,7 @@ if not zipfile.is_zipfile(archivepath): raise ZipImportError("the specified path must be a zip file") self._zip = zipfile.ZipFile(archivepath, 'r') + self._path = archivepath def find_module(self, fullname, path=None): """Check if the specified module is contained within the zip file, @@ -45,16 +46,47 @@ return None def get_code(self, fullname): + """Return the code object for the module, raising ZipImportError if the + module is not found.""" raise NotImplementedError - def get_data(self, fullname): - raise NotImplementedError + def get_data(self, pathname): + """Return the data (raw source or bytecode) for the specified module, + or raise IOError if the path does not exist. + + All files are opened in binary mode, regardless of whether they are + source or bytecode files. + + """ + try: + return self._zip.open(pathname, 'r').read() + except KeyError: + raise IOError('%s does not exist in the zip file %s' % (pathname, + self._path)) def get_source(self, fullname): + """Get the source code for the specified module, raising ZipImportError + if the module does not exist, or None if only bytecode exists.""" raise NotImplementedError def is_package(self, fullname): - raise NotImplementedError + """Return True if the module name represents a package, False if it + does not.""" + path_name = fullname.replace('.', os.sep) + init_path = os.path.join(path_name, '__init__.py') + try: + self._zip.getinfo(init_path) + except KeyError: + try: + self._zip.getinfo(init_path + ('c' if __debug__ else 'o')) + except KeyError: + return False + else: + return True + else: + return True def load_module(self, fullname): + """Load the specified module, returning the module or raising + ZipImportError if the module could not be found.""" raise NotImplementedError From python-checkins at python.org Thu Aug 9 06:39:36 2007 From: python-checkins at python.org (kurt.kaiser) Date: Thu, 9 Aug 2007 06:39:36 +0200 (CEST) Subject: [Python-checkins] r56844 - sandbox/trunk/2to3/pytree.py Message-ID: <20070809043936.D3E551E4007@bag.python.org> Author: kurt.kaiser Date: Thu Aug 9 06:39:36 2007 New Revision: 56844 Modified: sandbox/trunk/2to3/pytree.py Log: Eliminate DeprecationWarning from 2.6a0 Modified: sandbox/trunk/2to3/pytree.py ============================================================================== --- sandbox/trunk/2to3/pytree.py (original) +++ sandbox/trunk/2to3/pytree.py Thu Aug 9 06:39:36 2007 @@ -34,7 +34,7 @@ def __new__(cls, *args, **kwds): """Constructor that prevents Base from being instantiated.""" assert cls is not Base, "Cannot instantiate Base" - return object.__new__(cls, *args, **kwds) + return object.__new__(cls) def __eq__(self, other): """Compares two nodes for equality. @@ -369,7 +369,7 @@ def __new__(cls, *args, **kwds): """Constructor that prevents BasePattern from being instantiated.""" assert cls is not BasePattern, "Cannot instantiate BasePattern" - return object.__new__(cls, *args, **kwds) + return object.__new__(cls) def __repr__(self): args = [self.type, self.content, self.name] From python-checkins at python.org Thu Aug 9 11:19:38 2007 From: python-checkins at python.org (georg.brandl) Date: Thu, 9 Aug 2007 11:19:38 +0200 (CEST) Subject: [Python-checkins] r56845 - in doctools/trunk: sphinx-web.py sphinx/web/__init__.py Message-ID: <20070809091938.29BF81E4009@bag.python.org> Author: georg.brandl Date: Thu Aug 9 11:19:37 2007 New Revision: 56845 Modified: doctools/trunk/sphinx-web.py doctools/trunk/sphinx/web/__init__.py Log: Move web startup code to __init__.py. Modified: doctools/trunk/sphinx-web.py ============================================================================== --- doctools/trunk/sphinx-web.py (original) +++ doctools/trunk/sphinx-web.py Thu Aug 9 11:19:37 2007 @@ -6,54 +6,9 @@ :copyright: 2007 by Armin Ronacher, Georg Brandl. :license: Python license. """ -import os -import sys -import getopt - -import sphinx -from sphinx.web.application import setup_app -from sphinx.web.serve import run_simple - -try: - from werkzeug.debug import DebuggedApplication -except ImportError: - DebuggedApplication = lambda x, y: x - - -def main(argv): - opts, args = getopt.getopt(argv[1:], "dhf:") - opts = dict(opts) - if len(args) != 1 or '-h' in opts: - print 'usage: %s [-d] [-f cfg.py] ' % argv[0] - print ' -d: debug mode, use werkzeug debugger if installed' - print ' -f: use "cfg.py" file instead of doc_root/webconf.py' - return 2 - - conffile = opts.get('-f', os.path.join(args[0], 'webconf.py')) - config = {} - execfile(conffile, config) - - port = config.get('listen_port', 3000) - hostname = config.get('listen_addr', 'localhost') - debug = ('-d' in opts) or (hostname == 'localhost') - - config['data_root_path'] = args[0] - config['debug'] = debug - - def make_app(): - app = setup_app(config, check_superuser=True) - if debug: - app = DebuggedApplication(app, True) - return app - - if os.environ.get('RUN_MAIN') != 'true': - print '* Sphinx %s- Python documentation web application' % \ - sphinx.__version__.replace('$', '').replace('Revision:', 'rev.') - if debug: - print '* Running in debug mode' - - run_simple(hostname, port, make_app, use_reloader=debug) +import sys if __name__ == '__main__': + from sphinx.web import main sys.exit(main(sys.argv)) Modified: doctools/trunk/sphinx/web/__init__.py ============================================================================== --- doctools/trunk/sphinx/web/__init__.py (original) +++ doctools/trunk/sphinx/web/__init__.py Thu Aug 9 11:19:37 2007 @@ -8,3 +8,55 @@ :copyright: 2007 by Georg Brandl. :license: Python license. """ + +import os +import sys +import getopt + +import sphinx +from sphinx.web.application import setup_app +from sphinx.web.serve import run_simple + +try: + from werkzeug.debug import DebuggedApplication +except ImportError: + DebuggedApplication = lambda x, y: x + + +def main(argv): + opts, args = getopt.getopt(argv[1:], "dhf:") + opts = dict(opts) + if len(args) != 1 or '-h' in opts: + print 'usage: %s [-d] [-f cfg.py] ' % argv[0] + print ' -d: debug mode, use werkzeug debugger if installed' + print ' -f: use "cfg.py" file instead of doc_root/webconf.py' + return 2 + + conffile = opts.get('-f', os.path.join(args[0], 'webconf.py')) + config = {} + execfile(conffile, config) + + port = config.get('listen_port', 3000) + hostname = config.get('listen_addr', 'localhost') + debug = ('-d' in opts) or (hostname == 'localhost') + + config['data_root_path'] = args[0] + config['debug'] = debug + + def make_app(): + app = setup_app(config, check_superuser=True) + if debug: + app = DebuggedApplication(app, True) + return app + + if os.environ.get('RUN_MAIN') != 'true': + print '* Sphinx %s- Python documentation web application' % \ + sphinx.__version__.replace('$', '').replace('Revision:', 'rev.') + if debug: + print '* Running in debug mode' + + run_simple(hostname, port, make_app, use_reloader=debug) + + +if __name__ == '__main__': + sys.exit(main(sys.argv)) From python-checkins at python.org Thu Aug 9 11:47:25 2007 From: python-checkins at python.org (georg.brandl) Date: Thu, 9 Aug 2007 11:47:25 +0200 (CEST) Subject: [Python-checkins] r56846 - doctools/trunk/sphinx/__init__.py doctools/trunk/sphinx/builder.py Message-ID: <20070809094725.494561E4008@bag.python.org> Author: georg.brandl Date: Thu Aug 9 11:47:24 2007 New Revision: 56846 Modified: doctools/trunk/sphinx/__init__.py doctools/trunk/sphinx/builder.py Log: Add an explicit doctreedir option. Modified: doctools/trunk/sphinx/__init__.py ============================================================================== --- doctools/trunk/sphinx/__init__.py (original) +++ doctools/trunk/sphinx/__init__.py Thu Aug 9 11:47:24 2007 @@ -27,6 +27,7 @@ usage: %s [options] sourcedir outdir [filenames...]" options: -b -- builder to use (one of %s) -a -- write all files; default is to only write new and changed files + -d -- path for the cached doctree files (default outdir/.doctrees) -O -- give option to to the builder (-O help for list) -D -- override a setting in sourcedir/conf.py -N -- do not do colored output @@ -38,7 +39,7 @@ def main(argv): try: - opts, args = getopt.getopt(argv[1:], 'ab:O:D:N') + opts, args = getopt.getopt(argv[1:], 'ab:d:O:D:N') srcdirname = path.abspath(args[0]) if not path.isdir(srcdirname): print >>sys.stderr, 'Error: Cannot find source directory.' @@ -67,6 +68,7 @@ opt_help = False options = {} confoverrides = {} + doctreedir = path.join(outdirname, '.doctrees') for opt, val in opts: if opt == '-b': if val not in builders: @@ -78,6 +80,8 @@ usage(argv, 'Cannot combine -a option and filenames.') return 1 all_files = True + elif opt == '-d': + doctreedir = val elif opt == '-O': if val == 'help': opt_help = True @@ -115,7 +119,7 @@ print ' * %s: %s' % (optname, description) return 0 - builderobj = builderobj(srcdirname, outdirname, options, + builderobj = builderobj(srcdirname, outdirname, doctreedir, options, status_stream=sys.stdout, warning_stream=sys.stderr, confoverrides=confoverrides) Modified: doctools/trunk/sphinx/builder.py ============================================================================== --- doctools/trunk/sphinx/builder.py (original) +++ doctools/trunk/sphinx/builder.py Thu Aug 9 11:47:24 2007 @@ -76,13 +76,14 @@ 'freshenv': 'Don\'t use a pickled environment', } - def __init__(self, srcdirname, outdirname, options, env=None, - status_stream=None, warning_stream=None, - confoverrides=None): + def __init__(self, srcdirname, outdirname, doctreedirname, + options, confoverrides=None, env=None, + status_stream=None, warning_stream=None): self.srcdir = srcdirname self.outdir = outdirname - if not path.isdir(path.join(outdirname, '.doctrees')): - os.mkdir(path.join(outdirname, '.doctrees')) + self.doctreedir = doctreedirname + if not path.isdir(doctreedirname): + os.mkdir(doctreedirname) self.options = attrdict(options) self.validate_options() @@ -104,9 +105,10 @@ try: version, release = get_version_info(srcdirname) except (IOError, OSError): - print >>warning_stream, 'WARNING: Can\'t get version info from ' \ - 'Include/patchlevel.h, using version of this interpreter.' version, release = get_sys_version_info() + print >>warning_stream, 'WARNING: Can\'t get version info from ' \ + 'Include/patchlevel.h, using version of this ' \ + 'interpreter (%s).' % release if self.config['version'] == 'auto': self.config['version'] = version if self.config['release'] == 'auto': @@ -163,15 +165,13 @@ try: self.msg('trying to load pickled env...', nonl=True) self.env = BuildEnvironment.frompickle( - path.join(self.outdir, ENV_PICKLE_FILENAME)) + path.join(self.doctreedir, ENV_PICKLE_FILENAME)) self.msg('done', nobold=True) except Exception, err: self.msg('failed: %s' % err, nobold=True) - self.env = BuildEnvironment(self.srcdir, - path.join(self.outdir, '.doctrees')) + self.env = BuildEnvironment(self.srcdir, self.doctreedir) else: - self.env = BuildEnvironment(self.srcdir, - path.join(self.outdir, '.doctrees')) + self.env = BuildEnvironment(self.srcdir, self.doctreedir) def build_all(self): """Build all source files.""" @@ -214,7 +214,7 @@ # save the environment self.msg('pickling the env...', nonl=True) - self.env.topickle(path.join(self.outdir, ENV_PICKLE_FILENAME)) + self.env.topickle(path.join(self.doctreedir, ENV_PICKLE_FILENAME)) self.msg('done', nobold=True) # global actions From python-checkins at python.org Thu Aug 9 17:43:22 2007 From: python-checkins at python.org (georg.brandl) Date: Thu, 9 Aug 2007 17:43:22 +0200 (CEST) Subject: [Python-checkins] r56855 - in external/Pygments-0.8.1: AUTHORS CHANGES LICENSE MANIFEST.in Makefile PKG-INFO Pygments.egg-info Pygments.egg-info/PKG-INFO Pygments.egg-info/SOURCES.txt Pygments.egg-info/dependency_links.txt Pygments.egg-info/not-zip-safe Pygments.egg-info/top_level.txt TODO docs docs/build docs/build/api.html docs/build/authors.html docs/build/changelog.html docs/build/cmdline.html docs/build/filterdevelopment.html docs/build/filters.html docs/build/formatterdevelopment.html docs/build/formatters.html docs/build/index.html docs/build/installation.html docs/build/integrate.html docs/build/lexerdevelopment.html docs/build/lexers.html docs/build/moinmoin.html docs/build/plugins.html docs/build/quickstart.html docs/build/rstdirective.html docs/build/styles.html docs/build/tokens.html docs/build/unicode.html docs/generate.py docs/pygmentize.1 docs/src docs/src/api.txt docs/src/authors.txt docs/src/changelog.txt docs/src/cmdline.txt docs/src/filterdevelopment.txt docs/src/filters.txt docs/src/formatterdevelopment.txt docs/src/formatters.txt docs/src/index.txt docs/src/installation.txt docs/src/integrate.txt docs/src/lexerdevelopment.txt docs/src/lexers.txt docs/src/moinmoin.txt docs/src/plugins.txt docs/src/quickstart.txt docs/src/rstdirective.txt docs/src/styles.txt docs/src/tokens.txt docs/src/unicode.txt external external/moin-parser.py ez_setup.py pygmentize pygments pygments/__init__.py pygments/cmdline.py pygments/console.py pygments/filter.py pygments/filters pygments/filters/__init__.py pygments/formatter.py pygments/formatters pygments/formatters/__init__.py pygments/formatters/_mapping.py pygments/formatters/bbcode.py pygments/formatters/html.py pygments/formatters/latex.py pygments/formatters/other.py pygments/formatters/rtf.py pygments/formatters/terminal.py pygments/lexer.py pygments/lexers pygments/lexers/__init__.py pygments/lexers/_luabuiltins.py pygments/lexers/_mapping.py pygments/lexers/_phpbuiltins.py pygments/lexers/_vimbuiltins.py pygments/lexers/agile.py pygments/lexers/compiled.py pygments/lexers/dotnet.py pygments/lexers/functional.py pygments/lexers/math.py pygments/lexers/other.py pygments/lexers/special.py pygments/lexers/templates.py pygments/lexers/text.py pygments/lexers/web.py pygments/plugin.py pygments/scanner.py pygments/style.py pygments/styles pygments/styles/__init__.py pygments/styles/autumn.py pygments/styles/borland.py pygments/styles/colorful.py pygments/styles/default.py pygments/styles/emacs.py pygments/styles/friendly.py pygments/styles/fruity.py pygments/styles/manni.py pygments/styles/murphy.py pygments/styles/native.py pygments/styles/pastie.py pygments/styles/perldoc.py pygments/styles/trac.py pygments/token.py pygments/unistring.py pygments/util.py scripts scripts/check_sources.py scripts/count_loc.py scripts/epydoc.css scripts/find_codetags.py scripts/find_error.py scripts/fix_epydoc_markup.py scripts/get_vimkw.py scripts/pylintrc scripts/reindent.py scripts/vim2pygments.py setup.cfg setup.py tests tests/dtds tests/dtds/HTML4-f.dtd tests/dtds/HTML4-s.dtd tests/dtds/HTML4.dcl tests/dtds/HTML4.dtd tests/dtds/HTML4.soc tests/dtds/HTMLlat1.ent tests/dtds/HTMLspec.ent tests/dtds/HTMLsym.ent tests/examplefiles tests/examplefiles/AlternatingGroup.mu tests/examplefiles/Intro.java tests/examplefiles/Makefile tests/examplefiles/SmallCheck.hs tests/examplefiles/apache2.conf tests/examplefiles/batchfile.bat tests/examplefiles/boot-9.scm tests/examplefiles/ceval.c tests/examplefiles/classes.dylan tests/examplefiles/condensed_ruby.rb tests/examplefiles/database.pytb tests/examplefiles/django_sample.html+django tests/examplefiles/dwarf.cw tests/examplefiles/example.c tests/examplefiles/example.cpp tests/examplefiles/example.pas tests/examplefiles/example.rb tests/examplefiles/example.rhtml tests/examplefiles/example.xhtml tests/examplefiles/example.xml tests/examplefiles/format.ml tests/examplefiles/fucked_up.rb tests/examplefiles/functional.rst tests/examplefiles/genshi_example.xml+genshi tests/examplefiles/genshitext_example.genshitext tests/examplefiles/html+php_faulty.php tests/examplefiles/jinjadesignerdoc.rst tests/examplefiles/ltmain.sh tests/examplefiles/moin_SyntaxReference.txt tests/examplefiles/multiline_regexes.rb tests/examplefiles/numbers.c tests/examplefiles/perl5db.pl tests/examplefiles/perlfunc.1 tests/examplefiles/phpcomplete.vim tests/examplefiles/pleac.in.rb tests/examplefiles/simple.md tests/examplefiles/smarty_example.html tests/examplefiles/sources.list tests/examplefiles/test.bas tests/examplefiles/test.boo tests/examplefiles/test.cs tests/examplefiles/test.css tests/examplefiles/test.d tests/examplefiles/test.html tests/examplefiles/test.java tests/examplefiles/test.jsp tests/examplefiles/test.myt tests/examplefiles/test.pas tests/examplefiles/test.php tests/examplefiles/test.rb tests/examplefiles/test.rhtml tests/run.py tests/test_basic_api.py tests/test_clexer.py tests/test_cmdline.py tests/test_examplefiles.py tests/test_html_formatter.py tests/test_latex_formatter.py tests/test_token.py tests/test_using_api.py tests/test_util.py Message-ID: <20070809154322.AC3BB1E4009@bag.python.org> Author: georg.brandl Date: Thu Aug 9 17:43:13 2007 New Revision: 56855 Added: external/Pygments-0.8.1/ external/Pygments-0.8.1/AUTHORS external/Pygments-0.8.1/CHANGES external/Pygments-0.8.1/LICENSE external/Pygments-0.8.1/MANIFEST.in external/Pygments-0.8.1/Makefile external/Pygments-0.8.1/PKG-INFO external/Pygments-0.8.1/Pygments.egg-info/ external/Pygments-0.8.1/Pygments.egg-info/PKG-INFO external/Pygments-0.8.1/Pygments.egg-info/SOURCES.txt external/Pygments-0.8.1/Pygments.egg-info/dependency_links.txt external/Pygments-0.8.1/Pygments.egg-info/not-zip-safe external/Pygments-0.8.1/Pygments.egg-info/top_level.txt external/Pygments-0.8.1/TODO external/Pygments-0.8.1/docs/ external/Pygments-0.8.1/docs/build/ external/Pygments-0.8.1/docs/build/api.html external/Pygments-0.8.1/docs/build/authors.html external/Pygments-0.8.1/docs/build/changelog.html external/Pygments-0.8.1/docs/build/cmdline.html external/Pygments-0.8.1/docs/build/filterdevelopment.html external/Pygments-0.8.1/docs/build/filters.html external/Pygments-0.8.1/docs/build/formatterdevelopment.html external/Pygments-0.8.1/docs/build/formatters.html external/Pygments-0.8.1/docs/build/index.html external/Pygments-0.8.1/docs/build/installation.html external/Pygments-0.8.1/docs/build/integrate.html external/Pygments-0.8.1/docs/build/lexerdevelopment.html external/Pygments-0.8.1/docs/build/lexers.html external/Pygments-0.8.1/docs/build/moinmoin.html external/Pygments-0.8.1/docs/build/plugins.html external/Pygments-0.8.1/docs/build/quickstart.html external/Pygments-0.8.1/docs/build/rstdirective.html external/Pygments-0.8.1/docs/build/styles.html external/Pygments-0.8.1/docs/build/tokens.html external/Pygments-0.8.1/docs/build/unicode.html external/Pygments-0.8.1/docs/generate.py external/Pygments-0.8.1/docs/pygmentize.1 external/Pygments-0.8.1/docs/src/ external/Pygments-0.8.1/docs/src/api.txt external/Pygments-0.8.1/docs/src/authors.txt external/Pygments-0.8.1/docs/src/changelog.txt external/Pygments-0.8.1/docs/src/cmdline.txt external/Pygments-0.8.1/docs/src/filterdevelopment.txt external/Pygments-0.8.1/docs/src/filters.txt external/Pygments-0.8.1/docs/src/formatterdevelopment.txt external/Pygments-0.8.1/docs/src/formatters.txt external/Pygments-0.8.1/docs/src/index.txt external/Pygments-0.8.1/docs/src/installation.txt external/Pygments-0.8.1/docs/src/integrate.txt external/Pygments-0.8.1/docs/src/lexerdevelopment.txt external/Pygments-0.8.1/docs/src/lexers.txt external/Pygments-0.8.1/docs/src/moinmoin.txt external/Pygments-0.8.1/docs/src/plugins.txt external/Pygments-0.8.1/docs/src/quickstart.txt external/Pygments-0.8.1/docs/src/rstdirective.txt external/Pygments-0.8.1/docs/src/styles.txt external/Pygments-0.8.1/docs/src/tokens.txt external/Pygments-0.8.1/docs/src/unicode.txt external/Pygments-0.8.1/external/ external/Pygments-0.8.1/external/moin-parser.py external/Pygments-0.8.1/ez_setup.py external/Pygments-0.8.1/pygmentize (contents, props changed) external/Pygments-0.8.1/pygments/ external/Pygments-0.8.1/pygments/__init__.py external/Pygments-0.8.1/pygments/cmdline.py external/Pygments-0.8.1/pygments/console.py external/Pygments-0.8.1/pygments/filter.py external/Pygments-0.8.1/pygments/filters/ external/Pygments-0.8.1/pygments/filters/__init__.py external/Pygments-0.8.1/pygments/formatter.py external/Pygments-0.8.1/pygments/formatters/ external/Pygments-0.8.1/pygments/formatters/__init__.py external/Pygments-0.8.1/pygments/formatters/_mapping.py (contents, props changed) external/Pygments-0.8.1/pygments/formatters/bbcode.py external/Pygments-0.8.1/pygments/formatters/html.py external/Pygments-0.8.1/pygments/formatters/latex.py external/Pygments-0.8.1/pygments/formatters/other.py external/Pygments-0.8.1/pygments/formatters/rtf.py external/Pygments-0.8.1/pygments/formatters/terminal.py external/Pygments-0.8.1/pygments/lexer.py external/Pygments-0.8.1/pygments/lexers/ external/Pygments-0.8.1/pygments/lexers/__init__.py external/Pygments-0.8.1/pygments/lexers/_luabuiltins.py external/Pygments-0.8.1/pygments/lexers/_mapping.py external/Pygments-0.8.1/pygments/lexers/_phpbuiltins.py external/Pygments-0.8.1/pygments/lexers/_vimbuiltins.py external/Pygments-0.8.1/pygments/lexers/agile.py external/Pygments-0.8.1/pygments/lexers/compiled.py external/Pygments-0.8.1/pygments/lexers/dotnet.py external/Pygments-0.8.1/pygments/lexers/functional.py external/Pygments-0.8.1/pygments/lexers/math.py external/Pygments-0.8.1/pygments/lexers/other.py external/Pygments-0.8.1/pygments/lexers/special.py external/Pygments-0.8.1/pygments/lexers/templates.py external/Pygments-0.8.1/pygments/lexers/text.py external/Pygments-0.8.1/pygments/lexers/web.py external/Pygments-0.8.1/pygments/plugin.py external/Pygments-0.8.1/pygments/scanner.py external/Pygments-0.8.1/pygments/style.py external/Pygments-0.8.1/pygments/styles/ external/Pygments-0.8.1/pygments/styles/__init__.py external/Pygments-0.8.1/pygments/styles/autumn.py external/Pygments-0.8.1/pygments/styles/borland.py external/Pygments-0.8.1/pygments/styles/colorful.py external/Pygments-0.8.1/pygments/styles/default.py external/Pygments-0.8.1/pygments/styles/emacs.py external/Pygments-0.8.1/pygments/styles/friendly.py external/Pygments-0.8.1/pygments/styles/fruity.py external/Pygments-0.8.1/pygments/styles/manni.py external/Pygments-0.8.1/pygments/styles/murphy.py external/Pygments-0.8.1/pygments/styles/native.py external/Pygments-0.8.1/pygments/styles/pastie.py external/Pygments-0.8.1/pygments/styles/perldoc.py external/Pygments-0.8.1/pygments/styles/trac.py external/Pygments-0.8.1/pygments/token.py external/Pygments-0.8.1/pygments/unistring.py external/Pygments-0.8.1/pygments/util.py external/Pygments-0.8.1/scripts/ external/Pygments-0.8.1/scripts/check_sources.py (contents, props changed) external/Pygments-0.8.1/scripts/count_loc.py external/Pygments-0.8.1/scripts/epydoc.css external/Pygments-0.8.1/scripts/find_codetags.py (contents, props changed) external/Pygments-0.8.1/scripts/find_error.py external/Pygments-0.8.1/scripts/fix_epydoc_markup.py (contents, props changed) external/Pygments-0.8.1/scripts/get_vimkw.py external/Pygments-0.8.1/scripts/pylintrc external/Pygments-0.8.1/scripts/reindent.py (contents, props changed) external/Pygments-0.8.1/scripts/vim2pygments.py external/Pygments-0.8.1/setup.cfg external/Pygments-0.8.1/setup.py external/Pygments-0.8.1/tests/ external/Pygments-0.8.1/tests/dtds/ external/Pygments-0.8.1/tests/dtds/HTML4-f.dtd external/Pygments-0.8.1/tests/dtds/HTML4-s.dtd external/Pygments-0.8.1/tests/dtds/HTML4.dcl external/Pygments-0.8.1/tests/dtds/HTML4.dtd external/Pygments-0.8.1/tests/dtds/HTML4.soc external/Pygments-0.8.1/tests/dtds/HTMLlat1.ent external/Pygments-0.8.1/tests/dtds/HTMLspec.ent external/Pygments-0.8.1/tests/dtds/HTMLsym.ent external/Pygments-0.8.1/tests/examplefiles/ external/Pygments-0.8.1/tests/examplefiles/AlternatingGroup.mu external/Pygments-0.8.1/tests/examplefiles/Intro.java external/Pygments-0.8.1/tests/examplefiles/Makefile external/Pygments-0.8.1/tests/examplefiles/SmallCheck.hs external/Pygments-0.8.1/tests/examplefiles/apache2.conf external/Pygments-0.8.1/tests/examplefiles/batchfile.bat external/Pygments-0.8.1/tests/examplefiles/boot-9.scm external/Pygments-0.8.1/tests/examplefiles/ceval.c external/Pygments-0.8.1/tests/examplefiles/classes.dylan external/Pygments-0.8.1/tests/examplefiles/condensed_ruby.rb external/Pygments-0.8.1/tests/examplefiles/database.pytb external/Pygments-0.8.1/tests/examplefiles/django_sample.html+django external/Pygments-0.8.1/tests/examplefiles/dwarf.cw external/Pygments-0.8.1/tests/examplefiles/example.c external/Pygments-0.8.1/tests/examplefiles/example.cpp external/Pygments-0.8.1/tests/examplefiles/example.pas external/Pygments-0.8.1/tests/examplefiles/example.rb external/Pygments-0.8.1/tests/examplefiles/example.rhtml external/Pygments-0.8.1/tests/examplefiles/example.xhtml external/Pygments-0.8.1/tests/examplefiles/example.xml external/Pygments-0.8.1/tests/examplefiles/format.ml external/Pygments-0.8.1/tests/examplefiles/fucked_up.rb external/Pygments-0.8.1/tests/examplefiles/functional.rst external/Pygments-0.8.1/tests/examplefiles/genshi_example.xml+genshi external/Pygments-0.8.1/tests/examplefiles/genshitext_example.genshitext external/Pygments-0.8.1/tests/examplefiles/html+php_faulty.php external/Pygments-0.8.1/tests/examplefiles/jinjadesignerdoc.rst external/Pygments-0.8.1/tests/examplefiles/ltmain.sh external/Pygments-0.8.1/tests/examplefiles/moin_SyntaxReference.txt external/Pygments-0.8.1/tests/examplefiles/multiline_regexes.rb external/Pygments-0.8.1/tests/examplefiles/numbers.c external/Pygments-0.8.1/tests/examplefiles/perl5db.pl external/Pygments-0.8.1/tests/examplefiles/perlfunc.1 external/Pygments-0.8.1/tests/examplefiles/phpcomplete.vim external/Pygments-0.8.1/tests/examplefiles/pleac.in.rb external/Pygments-0.8.1/tests/examplefiles/simple.md external/Pygments-0.8.1/tests/examplefiles/smarty_example.html external/Pygments-0.8.1/tests/examplefiles/sources.list external/Pygments-0.8.1/tests/examplefiles/test.bas external/Pygments-0.8.1/tests/examplefiles/test.boo external/Pygments-0.8.1/tests/examplefiles/test.cs external/Pygments-0.8.1/tests/examplefiles/test.css external/Pygments-0.8.1/tests/examplefiles/test.d external/Pygments-0.8.1/tests/examplefiles/test.html external/Pygments-0.8.1/tests/examplefiles/test.java external/Pygments-0.8.1/tests/examplefiles/test.jsp external/Pygments-0.8.1/tests/examplefiles/test.myt external/Pygments-0.8.1/tests/examplefiles/test.pas external/Pygments-0.8.1/tests/examplefiles/test.php external/Pygments-0.8.1/tests/examplefiles/test.rb external/Pygments-0.8.1/tests/examplefiles/test.rhtml external/Pygments-0.8.1/tests/run.py external/Pygments-0.8.1/tests/test_basic_api.py external/Pygments-0.8.1/tests/test_clexer.py external/Pygments-0.8.1/tests/test_cmdline.py external/Pygments-0.8.1/tests/test_examplefiles.py external/Pygments-0.8.1/tests/test_html_formatter.py external/Pygments-0.8.1/tests/test_latex_formatter.py external/Pygments-0.8.1/tests/test_token.py external/Pygments-0.8.1/tests/test_using_api.py external/Pygments-0.8.1/tests/test_util.py Log: Add Pygments as an external. Added: external/Pygments-0.8.1/AUTHORS ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/AUTHORS Thu Aug 9 17:43:13 2007 @@ -0,0 +1,16 @@ +Pygments is written and maintained by Georg Brandl . + +Other contributors (as mentionend in :copyright:s) are: + +- Armin Ronacher +- Lukas Meuser +- Matt Good +- Tim Hatch +- Ronny Pfannschmidt +- Dennis Kaarsemaker +- Marek Kubica +- Ben Bangert +- Tiberius Teng +- Adam Blinkinsop +- Kirk McDonald +- Christopher Creutzig Added: external/Pygments-0.8.1/CHANGES ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/CHANGES Thu Aug 9 17:43:13 2007 @@ -0,0 +1,191 @@ +Pygments changelog (0.8 maintenance branch) +=========================================== + +Version 0.8.1 +------------- +(released Jun 27, 2007) + +- Fixed POD highlighting in the Ruby lexer. + +- Fixed Unicode class and namespace name highlighting in the C# lexer. + +- Fixed Unicode string prefix highlighting in the Python lexer. + +- Fixed a bug in the D and MiniD lexers. + +- Fixed the included MoinMoin parser. + + +Version 0.8 +----------- +(codename Maik??fer, released May 30, 2007) + +- Lexers added: + + * Haskell, thanks to Adam Blinkinsop + * Redcode, thanks to Adam Blinkinsop + * D, thanks to Kirk McDonald + * MuPad, thanks to Christopher Creutzig + * MiniD, thanks to Jarrett Billingsley + * Vim Script, by Tim Hatch + +- The HTML formatter now has a second line-numbers mode in which it will + just integrate the numbers in the same ``
      `` tag as the code.
+
+- The `CSharpLexer` now is Unicode-aware, which means that it has an
+  option that can be set so that it correctly lexes Unicode identifiers
+  allowed by the C# specs.
+
+- Added a `RaiseOnErrorTokenFilter` that raises an exception when the
+  lexer generates an error token, and a `VisibleWhitespaceFilter` that
+  converts whitespace (spaces, tabs, newlines) into visible characters.
+
+- Fixed the `do_insertions()` helper function to yield correct indices.
+
+- The ReST lexer now automatically highlights source code blocks in
+  ".. sourcecode:: language" and ".. code:: language" directive blocks.
+
+- Improved the default style (thanks to Tiberius Teng). The old default
+  is still available as the "emacs" style (which was an alias before).
+
+- The `get_style_defs` method of HTML formatters now uses the `cssclass`
+  option as the default selector if it was given.
+
+- Improved the ReST and Bash lexers a bit.
+
+- Fixed a few bugs in the Makefile and Bash lexers, thanks to Tim Hatch.
+
+- Fixed a bug in the command line code that disallowed ``-O`` options
+  when using the ``-S`` option.
+
+- Fixed a bug in the `RawTokenFormatter`.
+
+
+Version 0.7.1
+-------------
+(released Feb 15, 2007)
+
+- Fixed little highlighting bugs in the Python, Java, Scheme and Apache
+  Config lexers.
+
+- Updated the included manpage.
+
+- Included a built version of the documentation in the source tarball.
+
+
+Version 0.7
+-----------
+(codename Faschingskrapfn, released Feb 14, 2007)
+
+- Added a MoinMoin parser that uses Pygments. With it, you get Pygments
+  highlighting in Moin Wiki pages.
+
+- Changed the exception raised if no suitable lexer, formatter etc. is
+  found in one of the `get_*_by_*` functions to a custom exception,
+  `pygments.util.ClassNotFound`. It is, however, a subclass of `ValueError`
+  in order to retain backwards compatibility.
+
+- Added a `-H` command line option which can be used to get the docstring
+  of a lexer, formatter or filter.
+
+- Made the handling of lexers and formatters more consistent. The aliases
+  and filename patterns of formatters are now attributes on them. 
+
+- Added an OCaml lexer, thanks to Adam Blinkinsop.
+
+- Made the HTML formatter more flexible, and easily subclassable in order
+  to make it easy to implement custom wrappers, e.g. alternate line
+  number markup. See the documentation.
+
+- Added an `outencoding` option to all formatters, making it possible
+  to override the `encoding` (which is used by lexers and formatters) when
+  using the command line interface. Also, if using the terminal formatter
+  and the output file is a terminal and has an encoding attribute, use it
+  if no encoding is given.
+
+- Made it possible to just drop style modules into the `styles` subpackage
+  of the Pygments installation.
+
+- Added a "state" keyword argument to the `using` helper.
+
+- Added a `commandprefix` option to the `LatexFormatter` which allows to
+  control how the command names are constructed.
+
+- Added quite a few new lexers, thanks to Tim Hatch:
+
+  * Java Server Pages
+  * Windows batch files
+  * Trac Wiki markup
+  * Python tracebacks
+  * ReStructuredText
+  * Dylan
+  * and the Befunge esoteric programming language (yay!)
+
+- Added Mako lexers by Ben Bangert.
+
+- Added "fruity" style, another dark background originally vim-based theme.
+
+- Added sources.list lexer by Dennis Kaarsemaker.
+
+- Added token stream filters, and a pygmentize option to use them.
+
+- Changed behavior of `in` Operator for tokens. 
+
+- Added mimetypes for all lexers.
+
+- Fixed some problems lexing Python strings.
+
+- Fixed tickets: #167, #178, #179, #180, #185, #201.
+
+
+Version 0.6
+-----------
+(codename Zimtstern, released Dec 20, 2006)
+
+- Added option for the HTML formatter to write the CSS to an external file
+  in "full document" mode.
+
+- Added RTF formatter.
+
+- Added Bash and Apache configuration lexers (thanks to Tim Hatch).
+
+- Improved guessing methods for various lexers.
+
+- Added `@media` support to CSS lexer (thanks to Tim Hatch).
+
+- Added a Groff lexer (thanks to Tim Hatch).
+
+- License change to BSD.
+
+- Added lexers for the Myghty template language.
+
+- Added a Scheme lexer (thanks to Marek Kubica).
+
+- Added some functions to iterate over existing lexers, formatters
+  and lexers.
+
+- The HtmlFormatter's `get_style_defs()` can now take a list as an
+  argument to generate CSS with multiple prefixes.
+
+- Support for guessing input encoding added.
+
+- Encoding support added: all processing is now done with Unicode
+  strings, input and output are converted from and optionally to
+  byte strings (see the ``encoding`` option of lexers and formatters).
+
+- Some improvements in the C(++) lexers handling comments and line
+  continuations.
+
+
+Version 0.5.1
+-------------
+(released Oct 30, 2006)
+
+- Fixed traceback in ``pygmentize -L`` (thanks to Piotr Ozarowski).
+
+
+Version 0.5
+-----------
+(codename PyKleur, released Oct 30, 2006)
+
+- Initial public release.

Added: external/Pygments-0.8.1/LICENSE
==============================================================================
--- (empty file)
+++ external/Pygments-0.8.1/LICENSE	Thu Aug  9 17:43:13 2007
@@ -0,0 +1,30 @@
+Copyright (c) 2006 by the respective authors (see AUTHORS file).
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+
+    * The names of the contributors may not be used to endorse or
+      promote products derived from this software without specific
+      prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Added: external/Pygments-0.8.1/MANIFEST.in
==============================================================================
--- (empty file)
+++ external/Pygments-0.8.1/MANIFEST.in	Thu Aug  9 17:43:13 2007
@@ -0,0 +1 @@
+include docs/build/*.html

Added: external/Pygments-0.8.1/Makefile
==============================================================================
--- (empty file)
+++ external/Pygments-0.8.1/Makefile	Thu Aug  9 17:43:13 2007
@@ -0,0 +1,74 @@
+#
+# Makefile for Pygments
+# ~~~~~~~~~~~~~~~~~~~~~
+#
+# Combines scripts for common tasks.
+#
+# :copyright: 2006-2007 by Georg Brandl.
+# :license: GNU GPL, see LICENSE for more details.
+#
+
+PYTHON ?= python
+
+export PYTHONPATH = $(shell echo "$$PYTHONPATH"):$(shell python -c 'import os; print ":".join(os.path.abspath(line.strip()) for line in file("PYTHONPATH"))' 2>/dev/null)
+
+.PHONY: all apidocs check clean clean-pyc codetags docs epydoc mapfiles \
+	pylint reindent test test-coverage
+
+all: clean-pyc check test
+
+apidocs: epydoc
+
+check:
+	@$(PYTHON) scripts/check_sources.py -i apidocs -i pygments/lexers/_mapping.py \
+		   -i docs/build -i pygments/formatters/_mapping.py -i pygments/unistring.py \
+		   -i pygments/lexers/_vimbuiltins.py
+
+clean: clean-pyc
+	rm -f codetags.html
+	rm -rf apidocs
+
+clean-pyc:
+	find . -name '*.pyc' -exec rm -f {} +
+	find . -name '*.pyo' -exec rm -f {} +
+	find . -name '*~' -exec rm -f {} +
+
+codetags:
+	@$(PYTHON) scripts/find_codetags.py -i apidocs -i scripts/pylintrc \
+		   -i scripts/find_codetags.py -o codetags.html .
+
+docs: docs/build
+
+docs/build: docs/src/*.txt
+	$(PYTHON) docs/generate.py html docs/build $?
+	touch docs/build
+
+epydoc:
+	@rm -rf apidocs
+	@$(PYTHON) -Wi:default_transform `which epydoc` -o apidocs --css scripts/epydoc.css \
+		   --url http://trac.pocoo.org/pygments --no-frames --docformat restructuredtext \
+		   -v pygments
+	@sed -i -e 's|^
      ||' \
+			-e 's|\s\+$$||' \
+			-e 's|^\s\+
      ||' \ + -e 's|\(`__ + is installable via *easy_install* with ``easy_install Pygments==dev``. + + :copyright: 2006-2007 by Georg Brandl, Armin Ronacher and others. + :license: BSD, see LICENSE for more details. + +Keywords: syntax highlighting +Platform: any +Classifier: License :: OSI Approved :: BSD License +Classifier: Intended Audience :: Developers +Classifier: Intended Audience :: End Users/Desktop +Classifier: Intended Audience :: System Administrators +Classifier: Development Status :: 5 - Production/Stable +Classifier: Programming Language :: Python +Classifier: Operating System :: OS Independent Added: external/Pygments-0.8.1/Pygments.egg-info/PKG-INFO ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/Pygments.egg-info/PKG-INFO Thu Aug 9 17:43:13 2007 @@ -0,0 +1,40 @@ +Metadata-Version: 1.0 +Name: Pygments +Version: 0.8.1 +Summary: Pygments is a syntax highlighting package written in Python. +Home-page: http://pygments.org/ +Author: Georg Brandl +Author-email: g.brandl at gmx.net +License: BSD License +Description: + Pygments + ~~~~~~~~ + + Pygments is a syntax highlighting package written in Python. + + It is a generic syntax highlighter for general use in all kinds of software + such as forum systems, wikis or other applications that need to prettify + source code. Highlights are: + + * a wide range of common languages and markup formats is supported + * special attention is paid to details, increasing quality by a fair amount + * support for new languages and formats are added easily + * a number of output formats, presently HTML, LaTeX, RTF and ANSI sequences + * it is usable as a command-line tool and as a library + * ... and it highlights even Brainfuck! + + The `Pygments trunk `__ + is installable via *easy_install* with ``easy_install Pygments==dev``. + + :copyright: 2006-2007 by Georg Brandl, Armin Ronacher and others. + :license: BSD, see LICENSE for more details. + +Keywords: syntax highlighting +Platform: any +Classifier: License :: OSI Approved :: BSD License +Classifier: Intended Audience :: Developers +Classifier: Intended Audience :: End Users/Desktop +Classifier: Intended Audience :: System Administrators +Classifier: Development Status :: 5 - Production/Stable +Classifier: Programming Language :: Python +Classifier: Operating System :: OS Independent Added: external/Pygments-0.8.1/Pygments.egg-info/SOURCES.txt ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/Pygments.egg-info/SOURCES.txt Thu Aug 9 17:43:13 2007 @@ -0,0 +1,187 @@ +AUTHORS +CHANGES +LICENSE +MANIFEST.in +Makefile +TODO +ez_setup.py +pygmentize +setup.cfg +setup.py +Pygments.egg-info/PKG-INFO +Pygments.egg-info/SOURCES.txt +Pygments.egg-info/dependency_links.txt +Pygments.egg-info/not-zip-safe +Pygments.egg-info/top_level.txt +docs/generate.py +docs/pygmentize.1 +docs/build/api.html +docs/build/authors.html +docs/build/changelog.html +docs/build/cmdline.html +docs/build/filterdevelopment.html +docs/build/filters.html +docs/build/formatterdevelopment.html +docs/build/formatters.html +docs/build/index.html +docs/build/installation.html +docs/build/integrate.html +docs/build/lexerdevelopment.html +docs/build/lexers.html +docs/build/moinmoin.html +docs/build/plugins.html +docs/build/quickstart.html +docs/build/rstdirective.html +docs/build/styles.html +docs/build/tokens.html +docs/build/unicode.html +docs/src/api.txt +docs/src/authors.txt +docs/src/changelog.txt +docs/src/cmdline.txt +docs/src/filterdevelopment.txt +docs/src/filters.txt +docs/src/formatterdevelopment.txt +docs/src/formatters.txt +docs/src/index.txt +docs/src/installation.txt +docs/src/integrate.txt +docs/src/lexerdevelopment.txt +docs/src/lexers.txt +docs/src/moinmoin.txt +docs/src/plugins.txt +docs/src/quickstart.txt +docs/src/rstdirective.txt +docs/src/styles.txt +docs/src/tokens.txt +docs/src/unicode.txt +external/moin-parser.py +pygments/__init__.py +pygments/cmdline.py +pygments/console.py +pygments/filter.py +pygments/formatter.py +pygments/lexer.py +pygments/plugin.py +pygments/scanner.py +pygments/style.py +pygments/token.py +pygments/unistring.py +pygments/util.py +pygments/filters/__init__.py +pygments/formatters/__init__.py +pygments/formatters/_mapping.py +pygments/formatters/bbcode.py +pygments/formatters/html.py +pygments/formatters/latex.py +pygments/formatters/other.py +pygments/formatters/rtf.py +pygments/formatters/terminal.py +pygments/lexers/__init__.py +pygments/lexers/_luabuiltins.py +pygments/lexers/_mapping.py +pygments/lexers/_phpbuiltins.py +pygments/lexers/_vimbuiltins.py +pygments/lexers/agile.py +pygments/lexers/compiled.py +pygments/lexers/dotnet.py +pygments/lexers/functional.py +pygments/lexers/math.py +pygments/lexers/other.py +pygments/lexers/special.py +pygments/lexers/templates.py +pygments/lexers/text.py +pygments/lexers/web.py +pygments/styles/__init__.py +pygments/styles/autumn.py +pygments/styles/borland.py +pygments/styles/colorful.py +pygments/styles/default.py +pygments/styles/emacs.py +pygments/styles/friendly.py +pygments/styles/fruity.py +pygments/styles/manni.py +pygments/styles/murphy.py +pygments/styles/native.py +pygments/styles/pastie.py +pygments/styles/perldoc.py +pygments/styles/trac.py +scripts/check_sources.py +scripts/count_loc.py +scripts/epydoc.css +scripts/find_codetags.py +scripts/find_error.py +scripts/fix_epydoc_markup.py +scripts/get_vimkw.py +scripts/pylintrc +scripts/reindent.py +scripts/vim2pygments.py +tests/run.py +tests/test_basic_api.py +tests/test_clexer.py +tests/test_cmdline.py +tests/test_examplefiles.py +tests/test_html_formatter.py +tests/test_latex_formatter.py +tests/test_token.py +tests/test_using_api.py +tests/test_util.py +tests/dtds/HTML4-f.dtd +tests/dtds/HTML4-s.dtd +tests/dtds/HTML4.dcl +tests/dtds/HTML4.dtd +tests/dtds/HTML4.soc +tests/dtds/HTMLlat1.ent +tests/dtds/HTMLspec.ent +tests/dtds/HTMLsym.ent +tests/examplefiles/AlternatingGroup.mu +tests/examplefiles/Intro.java +tests/examplefiles/Makefile +tests/examplefiles/SmallCheck.hs +tests/examplefiles/apache2.conf +tests/examplefiles/batchfile.bat +tests/examplefiles/boot-9.scm +tests/examplefiles/ceval.c +tests/examplefiles/classes.dylan +tests/examplefiles/condensed_ruby.rb +tests/examplefiles/database.pytb +tests/examplefiles/django_sample.html+django +tests/examplefiles/dwarf.cw +tests/examplefiles/example.c +tests/examplefiles/example.cpp +tests/examplefiles/example.pas +tests/examplefiles/example.rb +tests/examplefiles/example.rhtml +tests/examplefiles/example.xhtml +tests/examplefiles/example.xml +tests/examplefiles/format.ml +tests/examplefiles/fucked_up.rb +tests/examplefiles/functional.rst +tests/examplefiles/genshi_example.xml+genshi +tests/examplefiles/genshitext_example.genshitext +tests/examplefiles/html+php_faulty.php +tests/examplefiles/jinjadesignerdoc.rst +tests/examplefiles/ltmain.sh +tests/examplefiles/moin_SyntaxReference.txt +tests/examplefiles/multiline_regexes.rb +tests/examplefiles/numbers.c +tests/examplefiles/perl5db.pl +tests/examplefiles/perlfunc.1 +tests/examplefiles/phpcomplete.vim +tests/examplefiles/pleac.in.rb +tests/examplefiles/simple.md +tests/examplefiles/smarty_example.html +tests/examplefiles/sources.list +tests/examplefiles/test.bas +tests/examplefiles/test.boo +tests/examplefiles/test.cs +tests/examplefiles/test.css +tests/examplefiles/test.d +tests/examplefiles/test.html +tests/examplefiles/test.java +tests/examplefiles/test.jsp +tests/examplefiles/test.myt +tests/examplefiles/test.pas +tests/examplefiles/test.php +tests/examplefiles/test.rb +tests/examplefiles/test.rhtml Added: external/Pygments-0.8.1/Pygments.egg-info/dependency_links.txt ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/Pygments.egg-info/dependency_links.txt Thu Aug 9 17:43:13 2007 @@ -0,0 +1 @@ + Added: external/Pygments-0.8.1/Pygments.egg-info/not-zip-safe ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/Pygments.egg-info/not-zip-safe Thu Aug 9 17:43:13 2007 @@ -0,0 +1 @@ + Added: external/Pygments-0.8.1/Pygments.egg-info/top_level.txt ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/Pygments.egg-info/top_level.txt Thu Aug 9 17:43:13 2007 @@ -0,0 +1 @@ +pygments Added: external/Pygments-0.8.1/TODO ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/TODO Thu Aug 9 17:43:13 2007 @@ -0,0 +1,25 @@ +Todo +==== + +suggested new lexers +-------------------- + +* Lisp +* IPython sessions +* Nemerle +* Assembler +* MySQL/PostgreSQL/SQLite +* Tcl + +for 1.0 +------- + +- lexers that need work: + * review perl lexer (numerous bugs, but so far no one had complaints ;) + * readd property support for C# lexer? that is, find a regex that doesn't + backtrack to death... + * add support for function name highlighting to C++ lexer + +- allow "overlay" token types to highlight specials: nth line, a word etc. + +- pygmentize option presets, more sophisticated method to output styles? Added: external/Pygments-0.8.1/docs/build/api.html ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/docs/build/api.html Thu Aug 9 17:43:13 2007 @@ -0,0 +1,456 @@ + + + + The full Pygments API — Pygments + + + + +
      +

      Pygments

      +

      The full Pygments API

      + + « Back To Index + + +
      +

      Contents

      + +
      + + +

      This page describes the Pygments API.

      +
      +

      High-level API

      +

      Functions from the pygments module:

      +
      +
      def lex(code, lexer):
      +
      Lex code with the lexer (must be a Lexer instance) +and return an iterable of tokens. Currently, this only calls +lexer.get_tokens().
      +
      def format(tokens, formatter, outfile=None):
      +
      Format a token stream (iterable of tokens) tokens with the +formatter (must be a Formatter instance). The result is +written to outfile, or if that is None, returned as a +string.
      +
      def highlight(code, lexer, formatter, outfile=None):
      +
      This is the most high-level highlighting function. +It combines lex and format in one function.
      +
      +

      Functions from pygments.lexers:

      +
      +
      def get_lexer_by_name(alias, **options):
      +

      Return an instance of a Lexer subclass that has alias in its +aliases list. The lexer is given the options at its +instantiation.

      +

      Will raise pygments.util.ClassNotFound if no lexer with that alias is +found.

      +
      +
      def get_lexer_for_filename(fn, **options):
      +

      Return a Lexer subclass instance that has a filename pattern +matching fn. The lexer is given the options at its +instantiation.

      +

      Will raise pygments.util.ClassNotFound if no lexer for that filename is +found.

      +
      +
      def get_lexer_for_mimetype(mime, **options):
      +

      Return a Lexer subclass instance that has mime in its mimetype +list. The lexer is given the options at its instantiation.

      +

      Will raise pygments.util.ClassNotFound if not lexer for that mimetype is +found.

      +
      +
      def guess_lexer(text, **options):
      +

      Return a Lexer subclass instance that's guessed from the text +in text. For that, the analyze_text() method of every known +lexer class is called with the text as argument, and the lexer +which returned the highest value will be instantiated and returned.

      +

      pygments.util.ClassNotFound is raised if no lexer thinks it can handle the +content.

      +
      +
      def guess_lexer_for_filename(text, filename, **options):
      +

      As guess_lexer(), but only lexers which have a pattern in filenames +or alias_filenames that matches filename are taken into consideration.

      +

      pygments.util.ClassNotFound is raised if no lexer thinks it can handle the +content.

      +
      +
      def get_all_lexers():
      +

      Return an iterable over all registered lexers, yielding tuples in the +format:

      +
      +(longname, tuple of aliases, tuple of filename patterns, tuple of mimetypes)
+
      +

      New in Pygments 0.6.

      +
      +
      +

      Functions from pygments.formatters:

      +
      +
      def get_formatter_by_name(alias, **options):
      +

      Return an instance of a Formatter subclass that has alias in its +aliases list. The formatter is given the options at its +instantiation.

      +

      Will raise pygments.util.ClassNotFound if no formatter with that alias is +found.

      +
      +
      def get_formatter_for_filename(fn, **options):
      +

      Return a Formatter subclass instance that has a filename pattern +matching fn. The formatter is given the options at its +instantiation.

      +

      Will raise pygments.util.ClassNotFound if no formatter for that filename +is found.

      +
      +
      +

      Functions from pygments.styles:

      +
      +
      def get_style_by_name(name):
      +

      Return a style class by its short name. The names of the builtin styles +are listed in pygments.styles.STYLE_MAP.

      +

      Will raise pygments.util.ClassNotFound if no style of that name is found.

      +
      +
      def get_all_styles():
      +

      Return an iterable over all registered styles, yielding their names.

      +

      New in Pygments 0.6.

      +
      +
      +
      +
      +

      Lexers

      +

      A lexer (derived from pygments.lexer.Lexer) has the following functions:

      +
      +
      def __init__(self, **options):
      +

      The constructor. Takes a **keywords dictionary of options. +Every subclass must first process its own options and then call +the Lexer constructor, since it processes the stripnl, +stripall and tabsize options.

      +

      An example looks like this:

      +
      def __init__(self, **options):
+    self.compress = options.get('compress', '')
+    Lexer.__init__(self, **options)
+
      +

      As these options must all be specifiable as strings (due to the +command line usage), there are various utility functions +available to help with that, see Option processing.

      +
      +
      def get_tokens(self, text):
      +

      This method is the basic interface of a lexer. It is called by +the highlight() function. It must process the text and return an +iterable of (tokentype, value) pairs from text.

      +

      Normally, you don't need to override this method. The default +implementation processes the stripnl, stripall and tabsize +options and then yields all tokens from get_tokens_unprocessed(), +with the index dropped.

      +
      +
      def get_tokens_unprocessed(self, text):
      +

      This method should process the text and return an iterable of +(index, tokentype, value) tuples where index is the starting +position of the token within the input text.

      +

      This method must be overridden by subclasses.

      +
      +
      def analyze_text(text):
      +
      A static method which is called for lexer guessing. It should analyze +the text and return a float in the range from 0.0 to 1.0. +If it returns 0.0, the lexer will not be selected as the most +probable one, if it returns 1.0, it will be selected immediately.
      +
      +

      For a list of known tokens have a look at the Tokens page.

      +

      A lexer also can have the following attributes (in fact, they are mandatory +except alias_filenames) that are used by the builtin lookup mechanism.

      +
      +
      name
      +
      Full name for the lexer, in human-readable form.
      +
      aliases
      +
      A list of short, unique identifiers that can be used to lookup +the lexer from a list, e.g. using get_lexer_by_name().
      +
      filenames
      +
      A list of fnmatch patterns that match filenames which contain +content for this lexer. The patterns in this list should be unique among +all lexers.
      +
      alias_filenames
      +
      A list of fnmatch patterns that match filenames which may or may not +contain content for this lexer. This list is used by the +guess_lexer_for_filename() function, to determine which lexers are +then included in guessing the correct one. That means that e.g. every +lexer for HTML and a template language should include \*.html in +this list.
      +
      mimetypes
      +
      A list of MIME types for content that can be lexed with this +lexer.
      +
      +
      +
      +

      Formatters

      +

      A formatter (derived from pygments.formatter.Formatter) has the following +functions:

      +
      +
      def __init__(self, **options):
      +

      As with lexers, this constructor processes options and then must call +the base class __init__.

      +

      The Formatter class recognizes the options style, full and +title. It is up to the formatter class whether it uses them.

      +
      +
      def get_style_defs(self, arg=''):
      +

      This method must return statements or declarations suitable to define +the current style for subsequent highlighted text (e.g. CSS classes +in the HTMLFormatter).

      +

      The optional argument arg can be used to modify the generation and +is formatter dependent (it is standardized because it can be given on +the command line).

      +

      This method is called by the -S command-line option, the arg +is then given by the -a option.

      +
      +
      def format(self, tokensource, outfile):
      +

      This method must format the tokens from the tokensource iterable and +write the formatted version to the file object outfile.

      +

      Formatter options can control how exactly the tokens are converted.

      +
      +
      +

      A formatter must have the following attributes that are used by the +builtin lookup mechanism. (New in Pygments 0.7.)

      +
      +
      name
      +
      Full name for the formatter, in human-readable form.
      +
      aliases
      +
      A list of short, unique identifiers that can be used to lookup +the formatter from a list, e.g. using get_formatter_by_name().
      +
      filenames
      +
      A list of fnmatch patterns that match filenames for which this formatter +can produce output. The patterns in this list should be unique among +all formatters.
      +
      +
      +
      +

      Option processing

      +

      The pygments.util module has some utility functions usable for option +processing:

      +
      +
      class OptionError
      +
      This exception will be raised by all option processing functions if +the type or value of the argument is not correct.
      +
      def get_bool_opt(options, optname, default=None):
      +

      Interpret the key optname from the dictionary options +as a boolean and return it. Return default if optname +is not in options.

      +

      The valid string values for True are 1, yes, +true and on, the ones for False are 0, +no, false and off (matched case-insensitively).

      +
      +
      def get_int_opt(options, optname, default=None):
      +
      As get_bool_opt, but interpret the value as an integer.
      +
      def get_list_opt(options, optname, default=None):
      +
      If the key optname from the dictionary options is a string, +split it at whitespace and return it. If it is already a list +or a tuple, it is returned as a list.
      +
      def get_choice_opt(options, optname, allowed, default=None):
      +
      If the key optname from the dictionary is not in the sequence +allowed, raise an error, otherwise return it. New in Pygments 0.8.
      +
      +
      + +
      + + + \ No newline at end of file Added: external/Pygments-0.8.1/docs/build/authors.html ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/docs/build/authors.html Thu Aug 9 17:43:13 2007 @@ -0,0 +1,231 @@ + + + + Authors — Pygments + + + + +
      +

      Pygments

      +

      Authors

      + + « Back To Index + + +

      Pygments is written and maintained by Georg Brandl <g.brandl@gmx.net>.

      +

      Other contributors (as mentionend in :copyright:s) are:

      + + +
      + + + \ No newline at end of file Added: external/Pygments-0.8.1/docs/build/changelog.html ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/docs/build/changelog.html Thu Aug 9 17:43:13 2007 @@ -0,0 +1,380 @@ + + + + Changelog — Pygments + + + + +
      +

      Pygments

      +

      Changelog

      + + « Back To Index + + +
      +

      Contents

      + +
      + +
      +

      Version 0.8.1

      +

      (released Jun 27, 2007)

      +
        +
      • Fixed POD highlighting in the Ruby lexer.
        • +
      • Fixed Unicode class and namespace name highlighting in the C# lexer.
        • +
      • Fixed Unicode string prefix highlighting in the Python lexer.
        • +
      • Fixed a bug in the D and MiniD lexers.
        • +
      • Fixed the included MoinMoin parser.
        • +
      +
      +
      +

      Version 0.8

      +

      (codename Maik??fer, released May 30, 2007)

      +
        +
      • Lexers added:
          +
        • Haskell, thanks to Adam Blinkinsop
          • +
        • Redcode, thanks to Adam Blinkinsop
          • +
        • D, thanks to Kirk McDonald
          • +
        • MuPad, thanks to Christopher Creutzig
          • +
        • MiniD, thanks to Jarrett Billingsley
          • +
        • Vim Script, by Tim Hatch
          • +
        +
        • +
      • The HTML formatter now has a second line-numbers mode in which it will +just integrate the numbers in the same <pre> tag as the code.
        • +
      • The CSharpLexer now is Unicode-aware, which means that it has an +option that can be set so that it correctly lexes Unicode identifiers +allowed by the C# specs.
        • +
      • Added a RaiseOnErrorTokenFilter that raises an exception when the +lexer generates an error token, and a VisibleWhitespaceFilter that +converts whitespace (spaces, tabs, newlines) into visible characters.
        • +
      • Fixed the do_insertions() helper function to yield correct indices.
        • +
      • The ReST lexer now automatically highlights source code blocks in +".. sourcecode:: language" and ".. code:: language" directive blocks.
        • +
      • Improved the default style (thanks to Tiberius Teng). The old default +is still available as the "emacs" style (which was an alias before).
        • +
      • The get_style_defs method of HTML formatters now uses the cssclass +option as the default selector if it was given.
        • +
      • Improved the ReST and Bash lexers a bit.
        • +
      • Fixed a few bugs in the Makefile and Bash lexers, thanks to Tim Hatch.
        • +
      • Fixed a bug in the command line code that disallowed -O options +when using the -S option.
        • +
      • Fixed a bug in the RawTokenFormatter.
        • +
      +
      +
      +

      Version 0.7.1

      +

      (released Feb 15, 2007)

      +
        +
      • Fixed little highlighting bugs in the Python, Java, Scheme and Apache +Config lexers.
        • +
      • Updated the included manpage.
        • +
      • Included a built version of the documentation in the source tarball.
        • +
      +
      +
      +

      Version 0.7

      +

      (codename Faschingskrapfn, released Feb 14, 2007)

      +
        +
      • Added a MoinMoin parser that uses Pygments. With it, you get Pygments +highlighting in Moin Wiki pages.
        • +
      • Changed the exception raised if no suitable lexer, formatter etc. is +found in one of the get_*_by_* functions to a custom exception, +pygments.util.ClassNotFound. It is, however, a subclass of ValueError +in order to retain backwards compatibility.
        • +
      • Added a -H command line option which can be used to get the docstring +of a lexer, formatter or filter.
        • +
      • Made the handling of lexers and formatters more consistent. The aliases +and filename patterns of formatters are now attributes on them.
        • +
      • Added an OCaml lexer, thanks to Adam Blinkinsop.
        • +
      • Made the HTML formatter more flexible, and easily subclassable in order +to make it easy to implement custom wrappers, e.g. alternate line +number markup. See the documentation.
        • +
      • Added an outencoding option to all formatters, making it possible +to override the encoding (which is used by lexers and formatters) when +using the command line interface. Also, if using the terminal formatter +and the output file is a terminal and has an encoding attribute, use it +if no encoding is given.
        • +
      • Made it possible to just drop style modules into the styles subpackage +of the Pygments installation.
        • +
      • Added a "state" keyword argument to the using helper.
        • +
      • Added a commandprefix option to the LatexFormatter which allows to +control how the command names are constructed.
        • +
      • Added quite a few new lexers, thanks to Tim Hatch:
          +
        • Java Server Pages
          • +
        • Windows batch files
          • +
        • Trac Wiki markup
          • +
        • Python tracebacks
          • +
        • ReStructuredText
          • +
        • Dylan
          • +
        • and the Befunge esoteric programming language (yay!)
          • +
        +
        • +
      • Added Mako lexers by Ben Bangert.
        • +
      • Added "fruity" style, another dark background originally vim-based theme.
        • +
      • Added sources.list lexer by Dennis Kaarsemaker.
        • +
      • Added token stream filters, and a pygmentize option to use them.
        • +
      • Changed behavior of in Operator for tokens.
        • +
      • Added mimetypes for all lexers.
        • +
      • Fixed some problems lexing Python strings.
        • +
      • Fixed tickets: #167, #178, #179, #180, #185, #201.
        • +
      +
      +
      +

      Version 0.6

      +

      (codename Zimtstern, released Dec 20, 2006)

      +
        +
      • Added option for the HTML formatter to write the CSS to an external file +in "full document" mode.
        • +
      • Added RTF formatter.
        • +
      • Added Bash and Apache configuration lexers (thanks to Tim Hatch).
        • +
      • Improved guessing methods for various lexers.
        • +
      • Added @media support to CSS lexer (thanks to Tim Hatch).
        • +
      • Added a Groff lexer (thanks to Tim Hatch).
        • +
      • License change to BSD.
        • +
      • Added lexers for the Myghty template language.
        • +
      • Added a Scheme lexer (thanks to Marek Kubica).
        • +
      • Added some functions to iterate over existing lexers, formatters +and lexers.
        • +
      • The HtmlFormatter's get_style_defs() can now take a list as an +argument to generate CSS with multiple prefixes.
        • +
      • Support for guessing input encoding added.
        • +
      • Encoding support added: all processing is now done with Unicode +strings, input and output are converted from and optionally to +byte strings (see the encoding option of lexers and formatters).
        • +
      • Some improvements in the C(++) lexers handling comments and line +continuations.
        • +
      +
      +
      +

      Version 0.5.1

      +

      (released Oct 30, 2006)

      +
        +
      • Fixed traceback in pygmentize -L (thanks to Piotr Ozarowski).
        • +
      +
      +
      +

      Version 0.5

      +

      (codename PyKleur, released Oct 30, 2006)

      +
        +
      • Initial public release.
        • +
      +
      + +
      + + + \ No newline at end of file Added: external/Pygments-0.8.1/docs/build/cmdline.html ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/docs/build/cmdline.html Thu Aug 9 17:43:13 2007 @@ -0,0 +1,282 @@ + + + + Command Line Interface — Pygments + + + + +
      +

      Pygments

      +

      Command Line Interface

      + + « Back To Index + + + +

      You can use Pygments from the shell, provided you installed the pygmentize script:

      +
      +$ pygmentize test.py
+print "Hello World"
+
      +

      will print the file test.py to standard output, using the Python lexer +(inferred from the file name extension) and the terminal formatter (because +you didn't give an explicit formatter name).

      +

      If you want HTML output:

      +
      +$ pygmentize -f html -l python -o test.html test.py
+
      +

      As you can see, the -l option explicitly selects a lexer. As seen above, if you +give an input file name and it has an extension that Pygments recognizes, you can +omit this option.

      +

      The -o option gives an output file name. If it is not given, output is +written to stdout.

      +

      The -f option selects a formatter (as with -l, it can also be omitted +if an output file name is given and has a supported extension). +If no output file name is given and -f is omitted, the +TerminalFormatter is used.

      +

      The above command could therefore also be given as:

      +
      +$ pygmentize -o test.html test.py
+
      +

      Lexer and formatter options can be given using the -O option:

      +
      +$ pygmentize -f html -O style=colorful,linenos=1 -l python test.py
+
      +

      Be sure to enclose the option string in quotes if it contains any special shell +characters, such as spaces or expansion wildcards like *. If an option +expects a list value, separate the list entries with spaces (you'll have to +quote the option value in this case too, so that the shell doesn't split it).

      +

      Filters are added to the token stream using the -F option:

      +
      +$ pygmentize -f html -l pascal -F keywordcase:case=upper main.pas
+
      +

      As you see, options for the filter are given after a colon. As for -O, the +filter name and options must be one shell word, so there may not be any spaces +around the colon.

      +

      There's a special -S option for generating style definitions. Usage is +as follows:

      +
      +$ pygmentize -f html -S colorful -a .syntax
+
      +

      generates a CSS style sheet (because you selected the HTML formatter) for +the "colorful" style prepending a ".syntax" selector to all style rules.

      +

      For an explanation what -a means for a particular formatter, look for +the arg argument for the formatter's get_style_defs() method.

      +

      The -L option lists lexers, formatters, along with their short +names and supported file name extensions, styles and filters. If you want to see +only one category, give it as an argument:

      +
      +$ pygmentize -L filters
+
      +

      will list only all installed filters.

      +

      The -H option will give you detailed information (the same that can be found +in this documentation) about a lexer, formatter or filter. Usage is as follows:

      +
      +$ pygmentize -H formatter html
+
      +

      will print the help for the HTML formatter, while

      +
      +$ pygmentize -H lexer python
+
      +

      will print the help for the Python lexer, etc.

      + +
      + + + \ No newline at end of file Added: external/Pygments-0.8.1/docs/build/filterdevelopment.html ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/docs/build/filterdevelopment.html Thu Aug 9 17:43:13 2007 @@ -0,0 +1,280 @@ + + + + Write your own filter — Pygments + + + + +
      +

      Pygments

      +

      Write your own filter

      + + « Back To Index + + +
      +

      Contents

      + +
      + + +

      New in Pygments 0.7.

      +

      Writing own filters is very easy. All you have to do is to subclass +the Filter class and override the filter method. Additionally a +filter is instanciated with some keyword arguments you can use to +adjust the behavior of your filter.

      +
      +

      Subclassing Filters

      +

      As an example, we write a filter that converts all Name.Function tokens +to normal Name tokens to make the output less colorful.

      +
      from pygments.util import get_bool_opt
+from pygments.token import Name
+from pygments.filter import Filter
+
+class UncolorFilter(Filter):
+
+    def __init__(self, **options):
+        Filter.__init__(self, **options)
+        self.class_too = get_bool_opt(options, 'classtoo')
+
+    def filter(self, lexer, stream):
+        for ttype, value in stream:
+            if ttype is Name.Function or (self.class_too and
+                                          ttype is Name.Class):
+                ttype = Name
+            yield ttype, value
+
      +

      Some notes on the lexer argument: that can be quite confusing since it doesn't +need to be a lexer instance. If a filter was added by using the add_filter() +function of lexers, that lexer is registered for the filter. In that case +lexer will refer to the lexer that has registered the filter. It can be used +to access options passed to a lexer. Because it could be None you always have +to check for that case if you access it.

      +
      +
      +

      Using a decorator

      +

      You can also use the simplefilter decorator from the pygments.filter module:

      +
      from pygments.util import get_bool_opt
+from pygments.token import Name
+from pygments.filter import simplefilter
+
+
+@simplefilter
+def uncolor(lexer, stream, options):
+    class_too = get_bool_opt(options, 'classtoo')
+    for ttype, value in stream:
+        if ttype is Name.Function or (class_too and
+                                      ttype is Name.Class):
+            ttype = Name
+        yield ttype, value
+
      +

      The decorator automatically subclasses an internal filter class and uses the +decorated function for filtering.

      +
      + +
      + + + \ No newline at end of file Added: external/Pygments-0.8.1/docs/build/filters.html ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/docs/build/filters.html Thu Aug 9 17:43:13 2007 @@ -0,0 +1,374 @@ + + + + Filters — Pygments + + + + +
      +

      Pygments

      +

      Filters

      + + « Back To Index + + +
      +

      Contents

      + +
      + + +

      New in Pygments 0.7.

      +

      You can filter token streams coming from lexers to improve or annotate the +output. For example, you can highlight special words in comments, convert +keywords to upper or lowercase to enforce a style guide etc.

      +

      To apply a filter, you can use the add_filter() method of a lexer:

      +
      >>> from pygments.lexers import PythonLexer
+>>> l = PythonLexer()
+>>> # add a filter given by a string and options
+>>> l.add_filter('codetagify', case='lower')
+>>> l.filters
+[<pygments.filters.CodeTagFilter object at 0xb785decc>]
+>>> from pygments.filters import KeywordCaseFilter
+>>> # or give an instance
+>>> l.add_filter(KeywordCaseFilter(case='lower'))
+
      +

      The add_filter() method takes keyword arguments which are forwarded to +the constructor of the filter.

      +

      To get a list of all registered filters by name, you can use the +get_all_filters() function from the pygments.filters module that returns an +iterable for all known filters.

      +

      If you want to write your own filter, have a look at Write your own filter.

      +
      +

      Builtin Filters

      +

      NameHighlightFilter

      +
      +

      Highlight a normal Name token with a different token type.

      +

      Example:

      +
      +filter = NameHighlightFilter(
+    names=['foo', 'bar', 'baz'],
+    tokentype=Name.Function,
+)
+
      +

      This would highlight the names "foo", "bar" and "baz" +as functions. Name.Function is the default token type.

      +

      Options accepted:

      +
      +
      names : list of strings
      +
      A list of names that should be given the different token type. +There is no default.
      +
      tokentype : TokenType or string
      +
      A token type or a string containing a token type name that is +used for highlighting the strings in names. The default is +Name.Function.
      +
      +
      +++ + + + +
      Name:highlight
      + +

      CodeTagFilter

      +
      +

      Highlight special code tags in comments and docstrings.

      +

      Options accepted:

      +
      +
      codetags : list of strings
      +
      A list of strings that are flagged as code tags. The default is to +highlight XXX, TODO, BUG and NOTE.
      +
      + +++ + + + +
      Name:codetagify
      +
      +

      RaiseOnErrorTokenFilter

      +
      +

      Raise an exception when the lexer generates an error token.

      +

      Options accepted:

      +
      +
      excclass : Exception class
      +
      The exception class to raise. +The default is pygments.filters.ErrorToken.
      +
      +

      New in Pygments 0.8.

      + +++ + + + +
      Name:raiseonerror
      +
      +

      KeywordCaseFilter

      +
      +

      Convert keywords to lowercase or uppercase or capitalize them, which +means first letter uppercase, rest lowercase.

      +

      This can be useful e.g. if you highlight Pascal code and want to adapt the +code to your styleguide.

      +

      Options accepted:

      +
      +
      case : string
      +
      The casing to convert keywords to. Must be one of 'lower', +'upper' or 'capitalize'. The default is 'lower'.
      +
      + +++ + + + +
      Name:keywordcase
      +
      +

      VisibleWhitespaceFilter

      +
      +

      Convert tabs, newlines and/or spaces to visible characters.

      +

      Options accepted:

      +
      +
      spaces : string or bool
      +
      If this is a one-character string, spaces will be replaces by this string. +If it is another true value, spaces will be replaced by ?? (unicode +MIDDLE DOT). If it is a false value, spaces will not be replaced. The +default is False.
      +
      tabs : string or bool
      +
      The same as for spaces, but the default replacement character is ?? +(unicode RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK). The default value +is False. Note: this will not work if the tabsize option for the +lexer is nonzero, as tabs will already have been expanded then.
      +
      tabsize : int
      +
      If tabs are to be replaced by this filter, this is the total number of +characters that a tab should be expanded to. The default is 8.
      +
      newlines : string or bool
      +
      The same as for spaces, but the default replacement character is ?? +(unicode PILCROW SIGN). The default value is False.
      +
      wstokentype : bool
      +
      If true, give whitespace the special Whitespace token type. This allows +styling the visible whitespace differently (e.g. greyed out), but it can +disrupt background colors. The default is True.
      +
      +

      New in Pygments 0.8.

      + +++ + + + +
      Name:whitespace
      +
      + + + + + + \ No newline at end of file Added: external/Pygments-0.8.1/docs/build/formatterdevelopment.html ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/docs/build/formatterdevelopment.html Thu Aug 9 17:43:13 2007 @@ -0,0 +1,372 @@ + + + + Write your own formatter — Pygments + + + + +
      +

      Pygments

      +

      Write your own formatter

      + + « Back To Index + + +
      +

      Contents

      + +
      + + +

      As well as creating your own lexer, writing a new +formatter for Pygments is easy and straightforward.

      +

      A formatter is a class that is initialized with some keyword arguments (the +formatter options) and that must provides a format() method. +Additionally a formatter should provide a get_style_defs() method that +returns the style definitions from the style in a form usable for the +formatter's output format.

      +
      +

      Quickstart

      +

      The most basic formatter shipped with Pygments is the NullFormatter. It just +sends the value of a token to the output stream:

      +
      from pygments.formatter import Formatter
+
+class NullFormatter(Formatter):
+    def format(self, tokensource, outfile):
+        for ttype, value in tokensource:
+            outfile.write(value)
+
      +

      As you can see, the format() method is passed two parameters: tokensource +and outfile. The first is an iterable of (token_type, value) tuples, +the latter a file like object with a write() method.

      +

      Because the formatter is that basic it doesn't overwrite the get_style_defs() +method.

      +
      +
      +

      Styles

      +

      Styles aren't instantiated but their metaclass provides some class functions +so that you can access the style definitions easily.

      +

      Styles are iterable and yield tuples in the form (ttype, d) where ttype +is a token and d is a dict with the following keys:

      +
      +
      'color'
      +
      Hexadecimal color value (eg: 'ff0000' for red) or None if not +defined.
      +
      'bold'
      +
      True if the value should be bold
      +
      'italic'
      +
      True if the value should be italic
      +
      'underline'
      +
      True if the value should be underlined
      +
      'bgcolor'
      +
      Hexadecimal color value for the background (eg: 'eeeeeee' for light +gray) or None if not defined.
      +
      'border'
      +
      Hexadecimal color value for the border (eg: '0000aa' for a dark +blue) or None for no border.
      +
      +

      Additional keys might appear in the future, formatters should ignore all keys +they don't support.

      +
      +
      +

      HTML 3.2 Formatter

      +

      For an more complex example, let's implement a HTML 3.2 Formatter. We don't +use CSS but inline markup (<u>, <font>, etc). Because this isn't good +style this formatter isn't in the standard library ;-)

      +
      from pygments.formatter import Formatter
+
+class OldHtmlFormatter(Formatter):
+
+    def __init__(self, **options):
+        Formatter.__init__(self, **options)
+
+        # create a dict of (start, end) tuples that wrap the
+        # value of a token so that we can use it in the format
+        # method later
+        self.styles = {}
+
+        # we iterate over the `_styles` attribute of a style item
+        # that contains the parsed style values.
+        for token, style in self.style:
+            start = end = ''
+            # a style item is a tuple in the following form:
+            # colors are readily specified in hex: 'RRGGBB'
+            if style['color']:
+                start += '<font color="#%s">' % color
+                end += '</font>'
+            if style['bold']:
+                start += '<b>'
+                end += '</b>'
+            if style['italic']:
+                start += '<i>'
+                end += '</i>'
+            if style['underline']:
+                start += '<u>'
+                end += '</u>'
+            self.styles[token] = (start, end)
+
+    def format(self, tokensource, outfile):
+        # lastval is a string we use for caching
+        # because it's possible that an lexer yields a number
+        # of consecutive tokens with the same token type.
+        # to minimize the size of the generated html markup we
+        # try to join the values of same-type tokens here
+        lastval = ''
+        lasttype = None
+
+        # wrap the whole output with <pre>
+        outfile.write('<pre>')
+
+        for ttype, value in tokensource:
+            # if the token type doesn't exist in the stylemap
+            # we try it with the parent of the token type
+            # eg: parent of Token.Literal.String.Double is
+            # Token.Literal.String
+            while ttype not in self.styles:
+                ttype = ttype.parent
+            if ttype == lasttype:
+                # the current token type is the same of the last
+                # iteration. cache it
+                lastval += value
+            else:
+                # not the same token as last iteration, but we
+                # have some data in the buffer. wrap it with the
+                # defined style and write it to the output file
+                if lastval:
+                    stylebegin, styleend = self.styles[lasttype]
+                    outfile.write(stylebegin + lastval + styleend)
+                # set lastval/lasttype to current values
+                lastval = value
+                lasttype = ttype
+
+        # if something is left in the buffer, write it to the
+        # output file, then close the opened <pre> tag
+        if lastval:
+            stylebegin, styleend = self.styles[lasttype]
+            outfile.write(stylebegin + lastval + styleend)
+        outfile.write('</pre>\n')
+
      +

      The comments should explain it. Again, this formatter doesn't override the +get_style_defs() method. If we would have used CSS classes instead of +inline HTML markup, we would need to generate the CSS first. For that +purpose the get_style_defs() method exists:

      +
      +
      +

      Generating Style Definitions

      +

      Some formatters like the LatexFormatter and the HtmlFormatter don't +output inline markup but reference either macros or css classes. Because +the definitions of those are not part of the output, the get_style_defs() +method exists. It is passed one parameter (if it's used and how it's used +is up to the formatter) and has to return a string or None.

      +
      + +
      + + + \ No newline at end of file Added: external/Pygments-0.8.1/docs/build/formatters.html ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/docs/build/formatters.html Thu Aug 9 17:43:13 2007 @@ -0,0 +1,655 @@ + + + + Available formatters — Pygments + + + + +
      +

      Pygments

      +

      Available formatters

      + + « Back To Index + + +
      +

      Contents

      + +
      + + +

      This page lists all builtin formatters.

      +
      +

      Common options

      +

      All formatters support these options:

      +
      +
      encoding
      +

      New in Pygments 0.6.

      +

      If given, must be an encoding name (such as "utf-8"). This will +be used to convert the token strings (which are Unicode strings) +to byte strings in the output (default: None). +It will also be written in an encoding declaration suitable for the +document format if the full option is given (e.g. a meta +content-type directive in HTML or an invocation of the inputenc +package in LaTeX).

      +

      If this is "" or None, Unicode strings will be written +to the output file, which most file-like objects do not support. +For example, pygments.highlight() will return a Unicode string if +called with no outfile argument and a formatter that has encoding +set to None because it uses a StringIO.StringIO object that +supports Unicode arguments to write(). Using a regular file object +wouldn't work.

      +
      +
      outencoding
      +

      New in Pygments 0.7.

      +

      When using Pygments from the command line, any encoding option given is +passed to the lexer and the formatter. This is sometimes not desirable, +for example if you want to set the input encoding to "guess". +Therefore, outencoding has been introduced which overrides encoding +for the formatter if given.

      +
      +
      +
      +
      +

      Formatter classes

      +

      All these classes are importable from pygments.formatters.

      +
      +

      BBCodeFormatter

      +
      +

      Format tokens with BBcodes. These formatting codes are used by many +bulletin boards, so you can highlight your sourcecode with pygments before +posting it there.

      +

      This formatter has no support for background colors and borders, as there +are no common BBcode tags for that.

      +

      Some board systems (e.g. phpBB) don't support colors in their [code] tag, +so you can't use the highlighting together with that tag. +Text in a [code] tag usually is shown with a monospace font (which this +formatter can do with the monofont option) and no spaces (which you +need for indentation) are removed.

      +

      Additional options accepted:

      +
      +
      style
      +
      The style to use, can be a string or a Style subclass (default: +'default').
      +
      codetag
      +
      If set to true, put the output into [code] tags (default: +false)
      +
      monofont
      +
      If set to true, add a tag to show the code with a monospace font +(default: false).
      +
      + +++ + + + + + +
      Short names:bbcode, bb
      Filename patterns:None
      +
      +
      +
      +

      HtmlFormatter

      +
      +

      Format tokens as HTML 4 <span> tags within a <pre> tag, wrapped +in a <div> tag. The <div>'s CSS class can be set by the cssclass +option.

      +

      If the linenos option is set to "table", the <pre> is +additionally wrapped inside a <table> which has one row and two +cells: one containing the line numbers and one containing the code. +Example:

      +
      <div class="highlight" >
+<table><tr>
+  <td class="linenos" title="click to toggle"
+    onclick="with (this.firstChild.style)
+             { display = (display == '') ? 'none' : '' }">
+    <pre>1
+    2</pre>
+  </td>
+  <td class="code">
+    <pre><span class="Ke">def </span><span class="NaFu">foo</span>(bar):
+      <span class="Ke">pass</span>
+    </pre>
+  </td>
+</tr></table></div>
+
      +

      (whitespace added to improve clarity).

      +

      Wrapping can be disabled using the nowrap option.

      +

      With the full option, a complete HTML 4 document is output, including +the style definitions inside a <style> tag, or in a separate file if +the cssfile option is given.

      +

      The get_style_defs(arg='') method of a HtmlFormatter returns a string +containing CSS rules for the CSS classes used by the formatter. The +argument arg can be used to specify additional CSS selectors that +are prepended to the classes. A call fmter.get_style_defs('td .code') +would result in the following CSS classes:

      +
      td .code .kw { font-weight: bold; color: #00FF00 }
+td .code .cm { color: #999999 }
+...
+
      +

      If you have Pygments 0.6 or higher, you can also pass a list or tuple to the +get_style_defs() method to request multiple prefixes for the tokens:

      +
      formatter.get_style_defs(['div.syntax pre', 'pre.syntax'])
+
      +

      The output would then look like this:

      +
      div.syntax pre .kw,
+pre.syntax .kw { font-weight: bold; color: #00FF00 }
+div.syntax pre .cm,
+pre.syntax .cm { color: #999999 }
+...
+
      +

      Additional options accepted:

      +
      +
      nowrap
      +
      If set to True, don't wrap the tokens at all, not even inside a <pre> +tag. This disables most other options (default: False).
      +
      full
      +
      Tells the formatter to output a "full" document, i.e. a complete +self-contained document (default: False).
      +
      title
      +
      If full is true, the title that should be used to caption the +document (default: '').
      +
      style
      +
      The style to use, can be a string or a Style subclass (default: +'default').
      +
      noclasses
      +
      If set to true, token <span> tags will not use CSS classes, but +inline styles. This is not recommended for larger pieces of code since +it increases output size by quite a bit (default: False).
      +
      classprefix
      +
      Since the token types use relatively short class names, they may clash +with some of your own class names. In this case you can use the +classprefix option to give a string to prepend to all Pygments-generated +CSS class names for token types. +Note that this option also affects the output of get_style_defs().
      +
      cssclass
      +
      CSS class for the wrapping <div> tag (default: 'highlight'). +If you set this option, the default selector for get_style_defs() +will be this class.
      +
      cssstyles
      +
      Inline CSS styles for the wrapping <div> tag (default: '').
      +
      cssfile
      +
      If the full option is true and this option is given, it must be the +name of an external file. If the filename does not include an absolute +path, the file's path will be assumed to be relative to the main output +file's path, if the latter can be found. The stylesheet is then written +to this file instead of the HTML file. New in Pygments 0.6.
      +
      linenos
      +

      If set to 'table', output line numbers as a table with two cells, +one containing the line numbers, the other the whole code. This is +copy-and-paste-friendly, but may cause alignment problems with some +browsers or fonts. If set to 'inline', the line numbers will be +integrated in the <pre> tag that contains the code (that setting +is new in Pygments 0.8).

      +

      For compatibility with Pygments 0.7 and earlier, every true value +except 'inline' means the same as 'table' (in particular, that +means also True).

      +

      The default value is False, which means no line numbers at all.

      +
      +
      linenostart
      +
      The line number for the first line (default: 1).
      +
      linenostep
      +
      If set to a number n > 1, only every nth line number is printed.
      +
      linenospecial
      +
      If set to a number n > 0, every nth line number is given the CSS +class "special" (default: 0).
      +
      nobackground
      +
      If set to True, the formatter won't output the background color +for the wrapping element (this automatically defaults to False +when there is no wrapping element [eg: no argument for the +get_syntax_defs method given]) (default: False). New in +Pygments 0.6.
      +
      lineseparator
      +
      This string is output between lines of code. It defaults to "\n", +which is enough to break a line inside <pre> tags, but you can +e.g. set it to "<br>" to get HTML line breaks. New in Pygments +0.7.
      +
      +

      Subclassing the HTML formatter

      +

      New in Pygments 0.7.

      +

      The HTML formatter is now built in a way that allows easy subclassing, thus +customizing the output HTML code. The format() method calls +self._format_lines() which returns a generator that yields tuples of (1, +line), where the 1 indicates that the line is a line of the +formatted source code.

      +

      If the nowrap option is set, the generator is the iterated over and the +resulting HTML is output.

      +

      Otherwise, format() calls self.wrap(), which wraps the generator with +other generators. These may add some HTML code to the one generated by +_format_lines(), either by modifying the lines generated by the latter, +then yielding them again with (1, line), and/or by yielding other HTML +code before or after the lines, with (0, html). The distinction between +source lines and other code makes it possible to wrap the generator multiple +times.

      +

      The default wrap() implementation adds a <div> and a <pre> tag.

      +

      A custom HtmlFormatter subclass could look like this:

      +
      class CodeHtmlFormatter(HtmlFormatter):
+
+    def wrap(self, source, outfile):
+        return self._wrap_code(source)
+
+    def _wrap_code(self, source):
+        yield 0, '<code>'
+        for i, t in source:
+            if i == 1:
+                # it's a line of formatted code
+                t += '<br>'
+            yield i, t
+        yield 0, '</code>'
+
      +

      This results in wrapping the formatted lines with a <code> tag, where the +source lines are broken using <br> tags.

      +

      After calling wrap(), the format() method also adds the "line numbers" +and/or "full document" wrappers if the respective options are set. Then, all +HTML yielded by the wrapped generator is output.

      + +++ + + + + + +
      Short names:html
      Filename patterns:*.html, *.htm
      +
      +
      +
      +

      Terminal256Formatter

      +
      +

      Format tokens with ANSI color sequences, for output in a 256-color +terminal or console. Like in TerminalFormatter color sequences +are terminated at newlines, so that paging the output works correctly.

      +

      The formatter takes colors from a style defined by the style option +and converts them to nearest ANSI 256-color escape sequences. Bold and +underline attributes from the style are preserved (and displayed).

      +

      New in Pygments 0.9.

      +

      Options accepted:

      +
      +
      style
      +
      The style to use, can be a string or a Style subclass (default: +'default').
      +
      + +++ + + + + + +
      Short names:terminal256, console256, 256
      Filename patterns:None
      +
      +
      +
      +

      TerminalFormatter

      +
      +

      Format tokens with ANSI color sequences, for output in a text console. +Color sequences are terminated at newlines, so that paging the output +works correctly.

      +

      The get_style_defs() method doesn't do anything special since there is +no support for common styles.

      +

      Options accepted:

      +
      +
      bg
      +
      Set to "light" or "dark" depending on the terminal's background +(default: "light").
      +
      colorscheme
      +
      A dictionary mapping token types to (lightbg, darkbg) color names or +None (default: None = use builtin colorscheme).
      +
      + +++ + + + + + +
      Short names:terminal, console
      Filename patterns:None
      +
      +
      +
      +

      LatexFormatter

      +
      +

      Format tokens as LaTeX code. This needs the fancyvrb and color +standard packages.

      +

      Without the full option, code is formatted as one Verbatim +environment, like this:

      +
      \begin{Verbatim}[commandchars=@\[\]]
+ at Can[def ]@Cax[foo](bar):
+    @Can[pass]
+\end{Verbatim}
+
      +

      The command sequences used here (@Can etc.) are generated from the given +style and can be retrieved using the get_style_defs method.

      +

      With the full option, a complete LaTeX document is output, including +the command definitions in the preamble.

      +

      The get_style_defs(arg='') method of a LatexFormatter returns a string +containing \newcommand commands defining the commands used inside the +Verbatim environments. If the argument arg is true, +\renewcommand is used instead.

      +

      Additional options accepted:

      +
      +
      style
      +
      The style to use, can be a string or a Style subclass (default: +'default').
      +
      full
      +
      Tells the formatter to output a "full" document, i.e. a complete +self-contained document (default: False).
      +
      title
      +
      If full is true, the title that should be used to caption the +document (default: '').
      +
      docclass
      +
      If the full option is enabled, this is the document class to use +(default: 'article').
      +
      preamble
      +
      If the full option is enabled, this can be further preamble commands, +e.g. \usepackage (default: '').
      +
      linenos
      +
      If set to True, output line numbers (default: False).
      +
      linenostart
      +
      The line number for the first line (default: 1).
      +
      linenostep
      +
      If set to a number n > 1, only every nth line number is printed.
      +
      verboptions
      +
      Additional options given to the Verbatim environment (see the fancyvrb +docs for possible values) (default: '').
      +
      commandprefix
      +
      The LaTeX commands used to produce colored output are constructed +using this prefix and some letters (default: 'C'). +New in Pygments 0.7.
      +
      + +++ + + + + + +
      Short names:latex, tex
      Filename patterns:*.tex
      +
      +
      +
      +

      RtfFormatter

      +
      +

      Format tokens as RTF markup. This formatter automatically outputs full RTF +documents with color information and other useful stuff. Perfect for Copy and +Paste into Microsoft?? Word?? documents.

      +

      New in Pygments 0.6.

      +

      Additional options accepted:

      +
      +
      style
      +
      The style to use, can be a string or a Style subclass (default: +'default').
      +
      fontface
      +
      The used font famliy, for example Bitstream Vera Sans. Defaults to +some generic font which is supposed to have fixed width.
      +
      + +++ + + + + + +
      Short names:rtf
      Filename patterns:*.rtf
      +
      +
      +
      +

      NullFormatter

      +
      +

      Output the text unchanged without any formatting.

      + +++ + + + + + +
      Short names:text, null
      Filename patterns:*.txt
      +
      +
      +
      +

      RawTokenFormatter

      +
      +

      Format tokens as a raw representation for storing token streams.

      +

      The format is tokentype<TAB>repr(tokenstring)\n. The output can later +be converted to a token stream with the RawTokenLexer, described in the +lexer list.

      +

      Only one option is accepted:

      +
      +
      compress
      +
      If set to 'gz' or 'bz2', compress the output with the given +compression algorithm after encoding (default: '').
      +
      + +++ + + + + + +
      Short names:raw, tokens
      Filename patterns:*.raw
      +
      +
      +
      + +
      + + + \ No newline at end of file Added: external/Pygments-0.8.1/docs/build/index.html ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/docs/build/index.html Thu Aug 9 17:43:13 2007 @@ -0,0 +1,259 @@ + + + + Overview — Pygments + + + + +
      +

      Pygments

      +

      Overview

      + + + +

      Welcome to the Pygments documentation.

      + +
      +

      If you find bugs or have suggestions for the documentation, please +look here for info on how to contact the team.

      +

      You can download an offline version of this documentation from the +download page.

      + +
      + + + \ No newline at end of file Added: external/Pygments-0.8.1/docs/build/installation.html ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/docs/build/installation.html Thu Aug 9 17:43:13 2007 @@ -0,0 +1,278 @@ + + + + Installation — Pygments + + + + +
      +

      Pygments

      +

      Installation

      + + « Back To Index + + +
      +

      Contents

      + +
      + + +

      Pygments requires at least Python 2.3 to work correctly. Just to clarify: +there won't ever be support for Python versions below 2.3. However, there +are no other dependencies.

      +
      +

      Installing a released version

      +
      +

      As a Python egg (via easy_install)

      +

      You can install the most recent Pygments version using easy_install:

      +
      +sudo easy_install Pygments
+
      +

      This will install a Pygments egg in your Python installation's site-packages +directory.

      +
      +
      +

      From the tarball release

      +
        +
      1. Download the most recent tarball from the download page
        2. +
      2. Unpack the tarball
        3. +
      3. sudo python setup.py install
        4. +
      +

      Note that the last command will automatically download and install +setuptools if you don't already have it installed. This requires a working +internet connection.

      +

      This will install Pygments into your Python installation's site-packages directory.

      +
      +
      +
      +

      Installing the development version

      +
      +

      If you want to play around with the code

      +
        +
      1. Install Subversion
        2. +
      2. svn co http://trac.pocoo.org/repos/pygments/trunk pygments
        3. +
      3. cd pygments
        4. +
      4. ln -s pygments /usr/lib/python2.X/site-packages
        5. +
      5. ln -s pygmentize /usr/local/bin
        6. +
      +

      As an alternative to steps 4 and 5 you can also do python setup.py develop +which will install the package via setuptools in development mode.

      +
      +
      +

      If you just want the latest features and use them

      +
      +sudo easy_install Pygments==dev
+
      +

      This will install a Pygments egg containing the latest Subversion trunk code +in your Python installation's site-packages directory. Every time the command +is run, the sources are updated from Subversion.

      +
      +
      + +
      + + + \ No newline at end of file Added: external/Pygments-0.8.1/docs/build/integrate.html ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/docs/build/integrate.html Thu Aug 9 17:43:13 2007 @@ -0,0 +1,237 @@ + + + + Using Pygments in various applications — Pygments + + + + +
      +

      Pygments

      +

      Using Pygments in various applications

      + + « Back To Index + + +
      +

      Contents

      + +
      + +
      +

      PyGtk

      +

      Armin has written a piece of sample code that shows how to create a Gtk +TextBuffer object containing Pygments-highlighted text.

      +

      See the article here: http://lucumr.pocoo.org/cogitations/2007/05/30/pygments-gtk-rendering/

      +
      +
      +

      Wordpress

      +

      He also has a snippet that shows how to use Pygments in WordPress:

      +

      http://lucumr.pocoo.org/cogitations/2007/05/30/pygments-in-wordpress/

      +
      + +
      + + + \ No newline at end of file Added: external/Pygments-0.8.1/docs/build/lexerdevelopment.html ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/docs/build/lexerdevelopment.html Thu Aug 9 17:43:13 2007 @@ -0,0 +1,684 @@ + + + + Write your own lexer — Pygments + + + + +
      +

      Pygments

      +

      Write your own lexer

      + + « Back To Index + + +
      +

      Contents

      + +
      + + +

      If a lexer for your favorite language is missing in the Pygments package, you can +easily write your own and extend Pygments.

      +

      All you need can be found inside the pygments.lexer module. As you can read in +the API documentation, a lexer is a class that is initialized with +some keyword arguments (the lexer options) and that provides a +get_tokens_unprocessed() method which is given a string or unicode object with +the data to parse.

      +

      The get_tokens_unprocessed() method must return an iterator or iterable +containing tuples in the form (index, token, value). Normally you don't need +to do this since there are numerous base lexers you can subclass.

      +
      +

      RegexLexer

      +

      A very powerful (but quite easy to use) lexer is the RegexLexer. This lexer +base class allows you to define lexing rules in terms of regular expressions +for different states.

      +

      States are groups of regular expressions that are matched against the input +string at the current position. If one of these expressions matches, a +corresponding action is performed (normally yielding a token with a specific +type), the current position is set to where the last match ended and the +matching process continues with the first regex of the current state.

      +

      Lexer states are kept in a state stack: each time a new state is entered, the +new state is pushed onto the stack. The most basic lexers (like the +DiffLexer) just need one state.

      +

      Each state is defined as a list of tuples in the form (regex, action, +new_state) where the last item is optional. In the most basic form, action +is a token type (like Name.Builtin). That means: When regex matches, emit a +token with the match text and type tokentype and push new_state on the state +stack. If the new state is '#pop', the topmost state is popped from the +stack instead. (To pop more than one state, use '#pop:2' and so on.) +'#push' is a synonym for pushing the current state on the +stack.

      +

      The following example shows the DiffLexer from the builtin lexers. Note that +it contains some additional attributes name, aliases and filenames which +aren't required for a lexer. They are used by the builtin lexer lookup +functions.

      +
      from pygments.lexer import RegexLexer
+from pygments.token import *
+
+class DiffLexer(RegexLexer):
+    name = 'Diff'
+    aliases = ['diff']
+    filenames = ['*.diff']
+
+    tokens = {
+        'root': [
+            (r' .*\n', Text),
+            (r'\+.*\n', Generic.Inserted),
+            (r'-.*\n', Generic.Deleted),
+            (r'@.*\n', Generic.Subheading),
+            (r'Index.*\n', Generic.Heading),
+            (r'=.*\n', Generic.Heading),
+            (r'.*\n', Text),
+        ]
+    }
+
      +

      As you can see this lexer only uses one state. When the lexer starts scanning +the text, it first checks if the current character is a space. If this is true +it scans everything until newline and returns the parsed data as Text token.

      +

      If this rule doesn't match, it checks if the current char is a plus sign. And +so on.

      +

      If no rule matches at the current position, the current char is emitted as an +Error token that indicates a parsing error, and the position is increased by +1.

      +
      +
      +

      Regex Flags

      +

      You can either define regex flags in the regex (r'(?x)foo bar') or by adding +a flags attribute to your lexer class. If no attribute is defined, it defaults +to re.MULTILINE. For more informations about regular expression flags see the +regular expressions help page in the python documentation.

      +
      +
      +

      Scanning multiple tokens at once

      +

      Here is a more complex lexer that highlights INI files. INI files consist of +sections, comments and key = value pairs:

      +
      from pygments.lexer import RegexLexer, bygroups
+from pygments.token import *
+
+class IniLexer(RegexLexer):
+    name = 'INI'
+    aliases = ['ini', 'cfg']
+    filenames = ['*.ini', '*.cfg']
+
+    tokens = {
+        'root': [
+            (r'\s+', Text),
+            (r';.*?$', Comment),
+            (r'\[.*?\]$', Keyword),
+            (r'(.*?)(\s*)(=)(\s*)(.*?)$',
+             bygroups(Name.Attribute, Text, Operator, Text, String))
+        ]
+    }
+
      +

      The lexer first looks for whitespace, comments and section names. And later it +looks for a line that looks like a key, value pair, seperated by an '=' +sign, and optional whitespace.

      +

      The bygroups helper makes sure that each group is yielded with a different +token type. First the Name.Attribute token, then a Text token for the +optional whitespace, after that a Operator token for the equals sign. Then a +Text token for the whitespace again. The rest of the line is returned as +String.

      +

      Note that for this to work, every part of the match must be inside a capturing +group (a (...)), and there must not be any nested capturing groups. If you +nevertheless need a group, use a non-capturing group defined using this syntax: +r'(?:some|words|here)' (note the ?: after the beginning parenthesis).

      +

      If you find yourself needing a capturing group inside the regex which +shouldn't be part of the output but is used in the regular expressions for +backreferencing (eg: r'(<(foo|bar)>)(.*?)(</\2>)'), you can pass None +to the bygroups function and it will skip that group will be skipped in the +output.

      +
      +
      +

      Changing states

      +

      Many lexers need multiple states to work as expected. For example, some +languages allow multiline comments to be nested. Since this is a recursive +pattern it's impossible to lex just using regular expressions.

      +

      Here is the solution:

      +
      from pygments.lexer import RegexLexer
+from pygments.token import *
+
+class ExampleLexer(RegexLexer):
+    name = 'Example Lexer with states'
+
+    tokens = {
+        'root': [
+            (r'[^/]+', Text),
+            (r'/\*', Comment.Multiline, 'comment'),
+            (r'//.*?$', Comment.Singleline),
+            (r'/', Text)
+        ],
+        'comment': [
+            (r'[^*/]', Comment.Multiline),
+            (r'/\*', Comment.Multiline, '#push'),
+            (r'\*/', Comment.Multiline, '#pop'),
+            (r'[*/]', Comment.Multiline)
+        ]
+    }
+
      +

      This lexer starts lexing in the 'root' state. It tries to match as much as +possible until it finds a slash ('/'). If the next character after the slash +is a star ('*') the RegexLexer sends those two characters to the output +stream marked as Comment.Multiline and continues parsing with the rules +defined in the 'comment' state.

      +

      If there wasn't a star after the slash, the RegexLexer checks if it's a +singleline comment (eg: followed by a second slash). If this also wasn't the +case it must be a single slash (the separate regex for a single slash must also +be given, else the slash would be marked as an error token).

      +

      Inside the 'comment' state, we do the same thing again. Scan until the lexer +finds a star or slash. If it's the opening of a multiline comment, push the +'comment' state on the stack and continue scanning, again in the +'comment' state. Else, check if it's the end of the multiline comment. If +yes, pop one state from the stack.

      +

      Note: If you pop from an empty stack you'll get an IndexError. (There is an +easy way to prevent this from happening: don't '#pop' in the root state).

      +

      If the RegexLexer encounters a newline that is flagged as an error token, the +stack is emptied and the lexer continues scanning in the 'root' state. This +helps producing error-tolerant highlighting for erroneous input, e.g. when a +single-line string is not closed.

      +
      +
      +

      Advanced state tricks

      +

      There are a few more things you can do with states:

      +
        +

      • You can push multiple states onto the stack if you give a tuple instead of a +simple string as the third item in a rule tuple. For example, if you want to +match a comment containing a directive, something like:

        +
        +/* <processing directive>    rest of comment */
+
        +

        you can use this rule:

        +
        tokens = {
+    'root': [
+        (r'/\* <', Comment, ('comment', 'directive')),
+        ...
+    ],
+    'directive': [
+        (r'[^>]*', Comment.Directive),
+        (r'>', Comment, '#pop'),
+    ],
+    'comment': [
+        (r'[^*]+', Comment),
+        (r'\*/', Comment, '#pop'),
+        (r'\*', Comment),
+    ]
+}
+
        +

        When this encounters the above sample, first 'comment' and 'directive' +are pushed onto the stack, then the lexer continues in the directive state +until it finds the closing >, then it continues in the comment state until +the closing */. Then, both states are popped from the stack again and +lexing continues in the root state.

        +
        • +

      • You can include the rules of a state in the definition of another. This is +done by using include from pygments.lexer:

        +
        from pygments.lexer import RegexLexer, bygroups, include
+from pygments.token import *
+
+class ExampleLexer(RegexLexer):
+    tokens = {
+        'comments': [
+            (r'/\*.*?\*/', Comment),
+            (r'//.*?\n', Comment),
+        ],
+        'root': [
+            include('comments'),
+            (r'(function )(\w+)( {)',
+             bygroups(Keyword, Name, Keyword), 'function'),
+            (r'.', Text),
+        ],
+        'function': [
+            (r'[^}/]+', Text),
+            include('comments'),
+            (r'/', Text),
+            (r'}', Keyword, '#pop'),
+        ]
+    }
+
        +

        This is a hypothetical lexer for a language that consist of functions and +comments. Because comments can occur at toplevel and in functions, we need +rules for comments in both states. As you can see, the include helper saves +repeating rules that occur more than once (in this example, the state +'comment' will never be entered by the lexer, as it's only there to be +included in 'root' and 'function').

        +
        • +

      • Sometimes, you may want to "combine" a state from existing ones. This is +possible with the combine helper from pygments.lexer.

        +

        If you, instead of a new state, write combined('state1', 'state2') as the +third item of a rule tuple, a new anonymous state will be formed from state1 +and state2 and if the rule matches, the lexer will enter this state.

        +

        This is not used very often, but can be helpful in some cases, such as the +PythonLexer's string literal processing.

        +
        • +

      • If you want your lexer to start lexing in a different state you can modify +the stack by overloading the get_tokens_unprocessed() method:

        +
        from pygments.lexer import RegexLexer
+
+class MyLexer(RegexLexer):
+    tokens = {...}
+
+    def get_tokens_unprocessed(self, text):
+        stack = ['root', 'otherstate']
+        for item in RegexLexer.get_tokens_unprocessed(text, stack):
+            yield item
+
        +

        Some lexers like the PhpLexer use this to make the leading <?php +preprocessor comments optional. Note that you can crash the lexer easily +by putting values into the stack that don't exist in the token map. Also +removing 'root' from the stack can result in strange errors!

        +
        • +
      +
      +
      +

      Using multiple lexers

      +

      Using multiple lexers for the same input can be tricky. One of the easiest +combination techniques is shown here: You can replace the token type entry in a +rule tuple (the second item) with a lexer class. The matched text will then be +lexed with that lexer, and the resulting tokens will be yielded.

      +

      For example, look at this stripped-down HTML lexer:

      +
      from pygments.lexer import RegexLexer, bygroups, using
+from pygments.token import *
+from pygments.lexers.web import JavascriptLexer
+
+class HtmlLexer(RegexLexer):
+    name = 'HTML'
+    aliases = ['html']
+    filenames = ['*.html', '*.htm']
+
+    flags = re.IGNORECASE | re.DOTALL
+    tokens = {
+        'root': [
+            ('[^<&]+', Text),
+            ('&.*?;', Name.Entity),
+            (r'<\s*script\s*', Name.Tag, ('script-content', 'tag')),
+            (r'<\s*[a-zA-Z0-9:]+', Name.Tag, 'tag'),
+            (r'<\s*/\s*[a-zA-Z0-9:]+\s*>', Name.Tag),
+        ],
+        'script-content': [
+            (r'(.+?)(<\s*/\s*script\s*>)',
+             bygroups(using(JavascriptLexer), Name.Tag),
+             '#pop'),
+        ]
+    }
+
      +

      Here the content of a <script> tag is passed to a newly created instance of +a JavascriptLexer and not processed by the HtmlLexer. This is done using the +using helper that takes the other lexer class as its parameter.

      +

      Note the combination of bygroups and using. This makes sure that the content +up to the </script> end tag is processed by the JavascriptLexer, while the +end tag is yielded as a normal token with the Name.Tag type.

      +

      As an additional goodie, if the lexer class is replaced by this (imported from +pygments.lexer), the "other" lexer will be the current one (because you cannot +refer to the current class within the code that runs at class definition time).

      +

      Also note the (r'<\s*script\s*', Name.Tag, ('script-content', 'tag')) rule. +Here, two states are pushed onto the state stack, 'script-content' and +'tag'. That means that first 'tag' is processed, which will parse +attributes and the closing >, then the 'tag' state is popped and the +next state on top of the stack will be 'script-content'.

      +

      The using() helper has a special keyword argument, state, which works as +follows: if given, the lexer to use initially is not in the "root" state, +but in the state given by this argument. This only works with a RegexLexer.

      +

      Any other keywords arguments passed to using() are added to the keyword +arguments used to create the lexer.

      +
      +
      +

      Delegating Lexer

      +

      Another approach for nested lexers is the DelegatingLexer which is for +example used for the template engine lexers. It takes two lexers as +arguments on initialisation: a root_lexer and a language_lexer.

      +

      The input is processed as follows: First, the whole text is lexed with the +language_lexer. All tokens yielded with a type of Other are then +concatenated and given to the root_lexer. The language tokens of the +language_lexer are then inserted into the root_lexer's token stream +at the appropriate positions.

      +
      from pygments.lexer import DelegatingLexer
+from pygments.lexers.web import HtmlLexer, PhpLexer
+
+class HtmlPhpLexer(DelegatingLexer):
+    def __init__(self, **options):
+        super(HtmlPhpLexer, self).__init__(HtmlLexer, PhpLexer, **options)
+
      +

      This procedure ensures that e.g. HTML with template tags in it is highlighted +correctly even if the template tags are put into HTML tags or attributes.

      +

      If you want to change the needle token Other to something else, you can +give the lexer another token type as the third parameter:

      +
      DelegatingLexer.__init__(MyLexer, OtherLexer, Text, **options)
+
      +
      +
      +

      Callbacks

      +

      Sometimes the grammar of a language is so complex that a lexer would be unable +to parse it just by using regular expressions and stacks.

      +

      For this, the RegexLexer allows callbacks to be given in rule tuples, instead +of token types (bygroups and using are nothing else but preimplemented +callbacks). The callback must be a function taking two arguments:

      +
        +
      • the lexer itself
        • +
      • the match object for the last matched rule
        • +
      +

      The callback must then return an iterable of (or simply yield) (index, +tokentype, value) tuples, which are then just passed through by +get_tokens_unprocessed(). The index here is the position of the token in +the input string, tokentype is the normal token type (like Name.Builtin), +and value the associated part of the input string.

      +

      You can see an example here:

      +
      from pygments.lexer import RegexLexer
+from pygments.token import Generic
+
+class HypotheticLexer(RegexLexer):
+
+    def headline_callback(lexer, match):
+        equal_signs = match.group(1)
+        text = match.group(2)
+        yield match.start(), Generic.Headline, equal_signs + text + equal_signs
+
+    tokens = {
+        'root': [
+            (r'(=+)(.*?)(\1)', headline_callback)
+        ]
+    }
+
      +

      If the regex for the headline_callback matches, the function is called with the +match object. Note that after the callback is done, processing continues +normally, that is, after the end of the previous match. The callback has no +possibility to influence the position.

      +

      There are not really any simple examples for lexer callbacks, but you can see +them in action e.g. in the compiled.py source code in the CLexer and +JavaLexer classes.

      +
      +
      +

      The ExtendedRegexLexer class

      +

      The RegexLexer, even with callbacks, unfortunately isn't powerful enough for +the funky syntax rules of some languages that will go unnamed, such as Ruby.

      +

      But fear not; even then you don't have to abandon the regular expression +approach. For Pygments has a subclass of RegexLexer, the ExtendedRegexLexer. +All features known from RegexLexers are available here too, and the tokens are +specified in exactly the same way, except for one detail:

      +

      The get_tokens_unprocessed() method holds its internal state data not as local +variables, but in an instance of the pygments.lexer.LexerContext class, and +that instance is passed to callbacks as a third argument. This means that you +can modify the lexer state in callbacks.

      +

      The LexerContext class has the following members:

      +
        +
      • text -- the input text
        • +
      • pos -- the current starting position that is used for matching regexes
        • +
      • stack -- a list containing the state stack
        • +
      • end -- the maximum position to which regexes are matched, this defaults to +the length of text
        • +
      +

      Additionally, the get_tokens_unprocessed() method can be given a +LexerContext instead of a string and will then process this context instead of +creating a new one for the string argument.

      +

      Note that because you can set the current position to anything in the callback, +it won't be automatically be set by the caller after the callback is finished. +For example, this is how the hypothetical lexer above would be written with the +ExtendedRegexLexer:

      +
      from pygments.lexer import ExtendedRegexLexer
+from pygments.token import Generic
+
+class ExHypotheticLexer(ExtendedRegexLexer):
+
+    def headline_callback(lexer, match, ctx):
+        equal_signs = match.group(1)
+        text = match.group(2)
+        yield match.start(), Generic.Headline, equal_signs + text + equal_signs
+        ctx.pos = match.end()
+
+    tokens = {
+        'root': [
+            (r'(=+)(.*?)(\1)', headline_callback)
+        ]
+    }
+
      +

      This might sound confusing (and it can really be). But it is needed, and for an +example look at the Ruby lexer in agile.py.

      +
      +
      +

      Filtering Token Streams

      +

      Some languages ship a lot of builtin functions (for example PHP). The total +amount of those functions differs from system to system because not everybody +has every extension installed. In the case of PHP there are over 3000 builtin +functions. That's an incredible huge amount of functions, much more than you +can put into a regular expression.

      +

      But because only Name tokens can be function names it's solvable by overriding +the get_tokens_unprocessed() method. The following lexer subclasses the +PythonLexer so that it highlights some additional names as pseudo keywords:

      +
      from pygments.lexers.agile import PythonLexer
+from pygments.token import Name, Keyword
+
+class MyPythonLexer(PythonLexer):
+    EXTRA_KEYWORDS = ['foo', 'bar', 'foobar', 'barfoo', 'spam', 'eggs']
+
+    def get_tokens_unprocessed(self, text):
+        for index, token, value in PythonLexer.get_tokens_unprocessed(self, text):
+            if token is Name and value in self.EXTRA_KEYWORDS:
+                yield index, Keyword.Pseudo, value
+            else:
+                yield index, token, value
+
      +

      The PhpLexer and LuaLexer use this method to resolve builtin functions.

      +

      Note Do not confuse this with the filter system.

      +
      + +
      + + + \ No newline at end of file Added: external/Pygments-0.8.1/docs/build/lexers.html ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/docs/build/lexers.html Thu Aug 9 17:43:13 2007 @@ -0,0 +1,1829 @@ + + + + Available lexers — Pygments + + + + +
      +

      Pygments

      +

      Available lexers

      + + « Back To Index + + +
      +

      Contents

      + +
      + + +

      This page lists all available builtin lexers and the options they take.

      +

      Currently, all lexers support these options:

      +
      +
      stripnl
      +
      Strip leading and trailing newlines from the input (default: True)
      +
      stripall
      +
      Strip all leading and trailing whitespace from the input (default: +False).
      +
      tabsize
      +
      If given and greater than 0, expand tabs in the input (default: 0).
      +
      encoding
      +

      New in Pygments 0.6.

      +

      If given, must be an encoding name (such as "utf-8"). This encoding +will be used to convert the input string to Unicode (if it is not already +a Unicode string). The default is "latin1".

      +

      If this option is set to "guess", a simple UTF-8 vs. Latin-1 +detection is used, if it is set to "chardet", the +chardet library is used to +guess the encoding of the input.

      +
      +
      +

      The "Short Names" field lists the identifiers that can be used with the +get_lexer_by_name() function.

      +

      These lexers are builtin and can be imported from pygments.lexers:

      +
      +

      Lexers for agile languages

      +

      LuaLexer

      +
      +

      For Lua source code.

      +

      Additional options accepted:

      +
      +
      func_name_highlighting
      +
      If given and True, highlight builtin function names +(default: True).
      +
      disabled_modules
      +

      If given, must be a list of module names whose function names +should not be highlighted. By default all modules are highlighted.

      +

      To get a list of allowed modules have a look into the +_luabuiltins module:

      +
      >>> from pygments.lexers._luabuiltins import MODULES
+>>> MODULES.keys()
+['string', 'coroutine', 'modules', 'io', 'basic', ...]
+
      +
      +
      + +++ + + + + + + + +
      Short names:lua
      Filename patterns:*.lua
      Mimetypes:text/x-lua, application/x-lua
      +
      +

      MiniDLexer

      +
      +

      For MiniD (a D-like scripting +language) source.

      + +++ + + + + + + + +
      Short names:minid
      Filename patterns:*.md
      Mimetypes:text/x-minidsrc
      +
      +

      PerlLexer

      +
      +

      For Perl source code.

      + +++ + + + + + + + +
      Short names:perl, pl
      Filename patterns:*.pl, *.pm
      Mimetypes:text/x-perl, application/x-perl
      +
      +

      PythonConsoleLexer

      +
      +

      For Python console output or doctests, such as:

      +
      >>> a = 'foo'
+>>> print a
+foo
+>>> 1 / 0
+Traceback (most recent call last):
+  File "<stdin>", line 1, in <module>
+ZeroDivisionError: integer division or modulo by zero
+
      + +++ + + + + + + + +
      Short names:pycon
      Filename patterns:None
      Mimetypes:text/x-python-doctest
      +
      +

      PythonLexer

      +
      +

      For Python source code.

      + +++ + + + + + + + +
      Short names:python, py
      Filename patterns:*.py, *.pyw
      Mimetypes:text/x-python, application/x-python
      +
      +

      PythonTracebackLexer

      +
      +

      For Python tracebacks.

      +

      New in Pygments 0.7.

      + +++ + + + + + + + +
      Short names:pytb
      Filename patterns:*.pytb
      Mimetypes:text/x-python-traceback
      +
      +

      RubyConsoleLexer

      +
      +

      For Ruby interactive console (irb) output like:

      +
      irb(main):001:0> a = 1
+=> 1
+irb(main):002:0> puts a
+1
+=> nil
+
      + +++ + + + + + + + +
      Short names:rbcon, irb
      Filename patterns:None
      Mimetypes:text/x-ruby-shellsession
      +
      +

      RubyLexer

      +
      +

      For Ruby source code.

      + +++ + + + + + + + +
      Short names:rb, ruby
      Filename patterns:*.rb, *.rbw, Rakefile, *.rake, *.gemspec, *.rbx
      Mimetypes:text/x-ruby, application/x-ruby
      +
      +
      +
      +

      Lexers for compiled languages

      +

      CLexer

      +
      +

      For C source code with preprocessor directives.

      + +++ + + + + + + + +
      Short names:c
      Filename patterns:*.c, *.h
      Mimetypes:text/x-chdr, text/x-csrc
      +
      +

      CppLexer

      +
      +

      For C++ source code with preprocessor directives.

      + +++ + + + + + + + +
      Short names:cpp, c++
      Filename patterns:*.cpp, *.hpp, *.c++, *.h++
      Mimetypes:text/x-c++hdr, text/x-c++src
      +
      +

      DLexer

      +
      +

      For D source.

      + +++ + + + + + + + +
      Short names:d
      Filename patterns:*.d, *.di
      Mimetypes:text/x-dsrc
      +
      +

      DelphiLexer

      +
      +

      For Delphi (Borland Object Pascal), +Turbo Pascal and Free Pascal source code.

      +

      Additional options accepted:

      +
      +
      turbopascal
      +
      Highlight Turbo Pascal specific keywords (default: True).
      +
      delphi
      +
      Highlight Borland Delphi specific keywords (default: True).
      +
      freepascal
      +
      Highlight Free Pascal specific keywords (default: True).
      +
      units
      +
      A list of units that should be considered builtin, supported are +System, SysUtils, Classes and Math. +Default is to consider all of them builtin.
      +
      + +++ + + + + + + + +
      Short names:delphi, pas, pascal, objectpascal
      Filename patterns:*.pas
      Mimetypes:text/x-pascal
      +
      +

      DylanLexer

      +
      +

      For the Dylan language.

      +

      New in Pygments 0.7.

      + +++ + + + + + + + +
      Short names:dylan
      Filename patterns:*.dylan
      Mimetypes:text/x-dylan
      +
      +

      JavaLexer

      +
      +

      For Java source code.

      + +++ + + + + + + + +
      Short names:java
      Filename patterns:*.java
      Mimetypes:text/x-java
      +
      +

      ObjectiveCLexer

      +
      +

      For Objective-C source code with preprocessor directives.

      + +++ + + + + + + + +
      Short names:objective-c, objectivec, obj-c, objc
      Filename patterns:*.m
      Mimetypes:text/x-objective-c
      +
      +

      OcamlLexer

      +
      +

      For the OCaml language.

      +

      New in Pygments 0.7.

      + +++ + + + + + + + +
      Short names:ocaml
      Filename patterns:*.ml, *.mli
      Mimetypes:text/x-ocaml
      +
      +
      +
      +

      Lexers for .net languages

      +

      BooLexer

      +
      +

      For Boo source code.

      + +++ + + + + + + + +
      Short names:boo
      Filename patterns:*.boo
      Mimetypes:text/x-boo
      +
      +

      CSharpLexer

      +
      +

      For C# +source code.

      +

      Additional options accepted:

      +
      +
      unicodelevel
      +

      Determines which Unicode characters this lexer allows for identifiers. +The possible values are:

      +
        +
      • none -- only the ASCII letters and numbers are allowed. This +is the fastest selection.
        • +
      • basic -- all Unicode characters from the specification except +category Lo are allowed.
        • +
      • full -- all Unicode characters as specified in the C# specs +are allowed. Note that this means a considerable slowdown since the +Lo category has more than 40,000 characters in it!
        • +
      +

      The default value is basic.

      +

      New in Pygments 0.8.

      +
      +
      + +++ + + + + + + + +
      Short names:csharp, c#
      Filename patterns:*.cs
      Mimetypes:text/x-csharp
      +
      +

      VbNetLexer

      +
      +

      For +Visual Basic.NET +source code.

      + +++ + + + + + + + +
      Short names:vb.net, vbnet
      Filename patterns:*.vb, *.bas
      Mimetypes:text/x-vbnet, text/x-vba
      +
      +
      +
      +

      Lexers for functional languages

      +

      HaskellLexer

      +
      +

      A Haskell lexer based on the lexemes defined in the Haskell 98 Report.

      +

      New in Pygments 0.8.

      + +++ + + + + + + + +
      Short names:haskell
      Filename patterns:*.hs
      Mimetypes:None
      +
      +

      SchemeLexer

      +
      +

      A Scheme lexer, parsing a stream and outputting the tokens +needed to highlight scheme code. +This lexer could be most probably easily subclassed to parse +other LISP-Dialects like Common Lisp, Emacs Lisp or AutoLisp.

      +

      This parser is checked with pastes from the LISP pastebin +at http://paste.lisp.org/ to cover as much syntax as possible.

      +

      It supports the full Scheme syntax as defined in R5RS.

      +

      New in Pygments 0.6.

      + +++ + + + + + + + +
      Short names:scheme
      Filename patterns:*.scm
      Mimetypes:text/x-scheme, application/x-scheme
      +
      +
      +
      +

      Lexers for math languages

      +

      MuPADLexer

      +
      +

      A MuPAD lexer. +Contributed by Christopher Creutzig <christopher@creutzig.de>.

      +

      New in Pygments 0.8.

      + +++ + + + + + + + +
      Short names:mupad
      Filename patterns:*.mu
      Mimetypes:None
      +
      +
      +
      +

      Lexers for other languages

      +

      BashLexer

      +
      +

      Lexer for (ba)sh shell scripts.

      +

      New in Pygments 0.6.

      + +++ + + + + + + + +
      Short names:bash, sh
      Filename patterns:*.sh
      Mimetypes:application/x-sh, application/x-shellscript
      +
      +

      BatchLexer

      +
      +

      Lexer for the DOS/Windows Batch file format.

      +

      New in Pygments 0.7.

      + +++ + + + + + + + +
      Short names:bat
      Filename patterns:*.bat, *.cmd
      Mimetypes:application/x-dos-batch
      +
      +

      BefungeLexer

      +
      +

      Lexer for the esoteric Befunge +language.

      +

      New in Pygments 0.7.

      + +++ + + + + + + + +
      Short names:befunge
      Filename patterns:*.befunge
      Mimetypes:application/x-befunge
      +
      +

      BrainfuckLexer

      +
      +

      Lexer for the esoteric BrainFuck +language.

      + +++ + + + + + + + +
      Short names:brainfuck, bf
      Filename patterns:*.bf, *.b
      Mimetypes:application/x-brainfuck
      +
      +

      RedcodeLexer

      +
      +

      A simple Redcode lexer based on ICWS'94. +Contributed by Adam Blinkinsop <blinks@acm.org>.

      +

      New in Pygments 0.8.

      + +++ + + + + + + + +
      Short names:redcode
      Filename patterns:*.cw
      Mimetypes:None
      +
      +

      SqlLexer

      +
      +

      Lexer for Structured Query Language. Currently, this lexer does +not recognize any special syntax except ANSI SQL.

      + +++ + + + + + + + +
      Short names:sql
      Filename patterns:*.sql
      Mimetypes:text/x-sql
      +
      +
      +
      +

      Special lexers

      +

      RawTokenLexer

      +
      +

      Recreate a token stream formatted with the RawTokenFormatter.

      +

      Additional options accepted:

      +
      +
      compress
      +
      If set to "gz" or "bz2", decompress the token stream with +the given compression algorithm before lexing (default: "").
      +
      + +++ + + + + + + + +
      Short names:raw
      Filename patterns:*.raw
      Mimetypes:application/x-pygments-tokens
      +
      +

      TextLexer

      +
      +

      "Null" lexer, doesn't highlight anything.

      + +++ + + + + + + + +
      Short names:text
      Filename patterns:*.txt
      Mimetypes:text/plain
      +
      +
      +
      +

      Lexers for various template engines' markup

      +

      CssDjangoLexer

      +
      +

      Subclass of the DjangoLexer that highlights unlexed data with the +CssLexer.

      + +++ + + + + + + + +
      Short names:css+django, css+jinja
      Filename patterns:None
      Mimetypes:text/css+django, text/css+jinja
      +
      +

      CssErbLexer

      +
      +

      Subclass of ErbLexer which highlights unlexed data with the CssLexer.

      + +++ + + + + + + + +
      Short names:css+erb, css+ruby
      Filename patterns:None
      Mimetypes:text/css+ruby
      +
      +

      CssGenshiLexer

      +
      +

      A lexer that highlights CSS definitions in genshi text templates.

      + +++ + + + + + + + +
      Short names:css+genshitext, css+genshi
      Filename patterns:None
      Mimetypes:text/css+genshi
      +
      +

      CssPhpLexer

      +
      +

      Subclass of PhpLexer which highlights unmatched data with the CssLexer.

      + +++ + + + + + + + +
      Short names:css+php
      Filename patterns:None
      Mimetypes:text/css+php
      +
      +

      CssSmartyLexer

      +
      +

      Subclass of the SmartyLexer that highlights unlexed data with the +CssLexer.

      + +++ + + + + + + + +
      Short names:css+smarty
      Filename patterns:None
      Mimetypes:text/css+smarty
      +
      +

      DjangoLexer

      +
      +

      Generic django +and jinja template lexer.

      +

      It just highlights django/jinja code between the preprocessor directives, +other data is left untouched by the lexer.

      + +++ + + + + + + + +
      Short names:django, jinja
      Filename patterns:None
      Mimetypes:application/x-django-templating, application/x-jinja
      +
      +

      ErbLexer

      +
      +

      Generic ERB (Ruby Templating) +lexer.

      +

      Just highlights ruby code between the preprocessor directives, other data +is left untouched by the lexer.

      +

      All options are also forwarded to the RubyLexer.

      + +++ + + + + + + + +
      Short names:erb
      Filename patterns:None
      Mimetypes:application/x-ruby-templating
      +
      +

      GenshiLexer

      +
      +

      A lexer that highlights genshi and +kid kid XML templates.

      + +++ + + + + + + + +
      Short names:genshi, kid, xml+genshi, xml+kid
      Filename patterns:*.kid
      Mimetypes:application/x-genshi, application/x-kid
      +
      +

      GenshiTextLexer

      +
      +

      A lexer that highlights genshi text +templates.

      + +++ + + + + + + + +
      Short names:genshitext
      Filename patterns:None
      Mimetypes:application/x-genshi-text, text/x-genshi
      +
      +

      HtmlDjangoLexer

      +
      +

      Subclass of the DjangoLexer that highighlights unlexed data with the +HtmlLexer.

      +

      Nested Javascript and CSS is highlighted too.

      + +++ + + + + + + + +
      Short names:html+django, html+jinja
      Filename patterns:None
      Mimetypes:text/html+django, text/html+jinja
      +
      +

      HtmlGenshiLexer

      +
      +

      A lexer that highlights genshi and +kid kid HTML templates.

      + +++ + + + + + + + +
      Short names:html+genshi, html+kid
      Filename patterns:None
      Mimetypes:text/html+genshi
      +
      +

      HtmlPhpLexer

      +
      +

      Subclass of PhpLexer that highlights unhandled data with the HtmlLexer.

      +

      Nested Javascript and CSS is highlighted too.

      + +++ + + + + + + + +
      Short names:html+php
      Filename patterns:*.phtml
      Mimetypes:application/x-php, application/x-httpd-php, application/x-httpd-php3, application/x-httpd-php4, application/x-httpd-php5
      +
      +

      HtmlSmartyLexer

      +
      +

      Subclass of the SmartyLexer that highighlights unlexed data with the +HtmlLexer.

      +

      Nested Javascript and CSS is highlighted too.

      + +++ + + + + + + + +
      Short names:html+smarty
      Filename patterns:None
      Mimetypes:text/html+smarty
      +
      +

      JavascriptDjangoLexer

      +
      +

      Subclass of the DjangoLexer that highlights unlexed data with the +JavascriptLexer.

      + +++ + + + + + + + +
      Short names:js+django, javascript+django, js+jinja, javascript+jinja
      Filename patterns:None
      Mimetypes:application/x-javascript+django, application/x-javascript+jinja, text/x-javascript+django, text/x-javascript+jinja, text/javascript+django, text/javascript+jinja
      +
      +

      JavascriptErbLexer

      +
      +

      Subclass of ErbLexer which highlights unlexed data with the +JavascriptLexer.

      + +++ + + + + + + + +
      Short names:js+erb, javascript+erb, js+ruby, javascript+ruby
      Filename patterns:None
      Mimetypes:application/x-javascript+ruby, text/x-javascript+ruby, text/javascript+ruby
      +
      +

      JavascriptGenshiLexer

      +
      +

      A lexer that highlights javascript code in genshi text templates.

      + +++ + + + + + + + +
      Short names:js+genshitext, js+genshi, javascript+genshitext, javascript+genshi
      Filename patterns:None
      Mimetypes:application/x-javascript+genshi, text/x-javascript+genshi, text/javascript+genshi
      +
      +

      JavascriptPhpLexer

      +
      +

      Subclass of PhpLexer which highlights unmatched data with the +JavascriptLexer.

      + +++ + + + + + + + +
      Short names:js+php, javascript+php
      Filename patterns:None
      Mimetypes:application/x-javascript+php, text/x-javascript+php, text/javascript+php
      +
      +

      JavascriptSmartyLexer

      +
      +

      Subclass of the SmartyLexer that highlights unlexed data with the +JavascriptLexer.

      + +++ + + + + + + + +
      Short names:js+smarty, javascript+smarty
      Filename patterns:None
      Mimetypes:application/x-javascript+smarty, text/x-javascript+smarty, text/javascript+smarty
      +
      +

      JspLexer

      +
      +

      Lexer for Java Server Pages.

      +

      New in Pygments 0.7.

      + +++ + + + + + + + +
      Short names:jsp
      Filename patterns:*.jsp
      Mimetypes:application/x-jsp
      +
      +

      MakoCssLexer

      +
      +

      Subclass of the MakoLexer that highlights unlexer data +with the CssLexer.

      +

      New in Pygments 0.7.

      + +++ + + + + + + + +
      Short names:css+mako
      Filename patterns:None
      Mimetypes:text/css+mako
      +
      +

      MakoHtmlLexer

      +
      +

      Subclass of the MakoLexer that highlights unlexed data +with the HtmlLexer.

      +

      New in Pygments 0.7.

      + +++ + + + + + + + +
      Short names:html+mako
      Filename patterns:None
      Mimetypes:text/html+mako
      +
      +

      MakoJavascriptLexer

      +
      +

      Subclass of the MakoLexer that highlights unlexer data +with the JavascriptLexer.

      +

      New in Pygments 0.7.

      + +++ + + + + + + + +
      Short names:js+mako, javascript+mako
      Filename patterns:None
      Mimetypes:application/x-javascript+mako, text/x-javascript+mako, text/javascript+mako
      +
      +

      MakoLexer

      +
      +

      Generic mako templates lexer. Code that isn't Mako +markup is yielded as Token.Other.

      +

      New in Pygments 0.7.

      + +++ + + + + + + + +
      Short names:mako
      Filename patterns:*.mao
      Mimetypes:application/x-mako
      +
      +

      MakoXmlLexer

      +
      +

      Subclass of the MakoLexer that highlights unlexer data +with the XmlLexer.

      +

      New in Pygments 0.7.

      + +++ + + + + + + + +
      Short names:xml+mako
      Filename patterns:None
      Mimetypes:application/xml+mako
      +
      +

      MyghtyCssLexer

      +
      +

      Subclass of the MyghtyLexer that highlights unlexer data +with the CssLexer.

      +

      New in Pygments 0.6.

      + +++ + + + + + + + +
      Short names:css+myghty
      Filename patterns:None
      Mimetypes:text/css+myghty
      +
      +

      MyghtyHtmlLexer

      +
      +

      Subclass of the MyghtyLexer that highlights unlexer data +with the HtmlLexer.

      +

      New in Pygments 0.6.

      + +++ + + + + + + + +
      Short names:html+myghty
      Filename patterns:None
      Mimetypes:text/html+myghty
      +
      +

      MyghtyJavascriptLexer

      +
      +

      Subclass of the MyghtyLexer that highlights unlexer data +with the JavascriptLexer.

      +

      New in Pygments 0.6.

      + +++ + + + + + + + +
      Short names:js+myghty, javascript+myghty
      Filename patterns:None
      Mimetypes:application/x-javascript+myghty, text/x-javascript+myghty, text/javascript+mygthy
      +
      +

      MyghtyLexer

      +
      +

      Generic myghty templates lexer. Code that isn't Myghty +markup is yielded as Token.Other.

      +

      New in Pygments 0.6.

      + +++ + + + + + + + +
      Short names:myghty
      Filename patterns:*.myt, autodelegate
      Mimetypes:application/x-myghty
      +
      +

      MyghtyXmlLexer

      +
      +

      Subclass of the MyghtyLexer that highlights unlexer data +with the XmlLexer.

      +

      New in Pygments 0.6.

      + +++ + + + + + + + +
      Short names:xml+myghty
      Filename patterns:None
      Mimetypes:application/xml+myghty
      +
      +

      RhtmlLexer

      +
      +

      Subclass of the ERB lexer that highlights the unlexed data with the +html lexer.

      +

      Nested Javascript and CSS is highlighted too.

      + +++ + + + + + + + +
      Short names:rhtml, html+erb, html+ruby
      Filename patterns:*.rhtml
      Mimetypes:text/html+ruby
      +
      +

      SmartyLexer

      +
      +

      Generic Smarty template lexer.

      +

      Just highlights smarty code between the preprocessor directives, other +data is left untouched by the lexer.

      + +++ + + + + + + + +
      Short names:smarty
      Filename patterns:*.tpl
      Mimetypes:application/x-smarty
      +
      +

      XmlDjangoLexer

      +
      +

      Subclass of the DjangoLexer that highlights unlexed data with the +XmlLexer.

      + +++ + + + + + + + +
      Short names:xml+django, xml+jinja
      Filename patterns:None
      Mimetypes:application/xml+django, application/xml+jinja
      +
      +

      XmlErbLexer

      +
      +

      Subclass of ErbLexer which highlights data outside preprocessor +directives with the XmlLexer.

      + +++ + + + + + + + +
      Short names:xml+erb, xml+ruby
      Filename patterns:None
      Mimetypes:application/xml+ruby
      +
      +

      XmlPhpLexer

      +
      +

      Subclass of PhpLexer that higlights unhandled data with the XmlLexer.

      + +++ + + + + + + + +
      Short names:xml+php
      Filename patterns:None
      Mimetypes:application/xml+php
      +
      +

      XmlSmartyLexer

      +
      +

      Subclass of the SmartyLexer that highlights unlexed data with the +XmlLexer.

      + +++ + + + + + + + +
      Short names:xml+smarty
      Filename patterns:None
      Mimetypes:application/xml+smarty
      +
      +
      +
      +

      Lexers for non-source code file types

      +

      ApacheConfLexer

      +
      +

      Lexer for configuration files following the Apache config file +format.

      +

      New in Pygments 0.6.

      + +++ + + + + + + + +
      Short names:apacheconf, aconf, apache
      Filename patterns:.htaccess, apache.conf, apache2.conf
      Mimetypes:text/x-apacheconf
      +
      +

      BBCodeLexer

      +
      +

      A lexer that highlights BBCode(-like) syntax.

      +

      New in Pygments 0.6.

      + +++ + + + + + + + +
      Short names:bbcode
      Filename patterns:None
      Mimetypes:text/x-bbcode
      +
      +

      DiffLexer

      +
      +

      Lexer for unified or context-style diffs or patches.

      + +++ + + + + + + + +
      Short names:diff
      Filename patterns:*.diff, *.patch
      Mimetypes:text/x-diff, text/x-patch
      +
      +

      GroffLexer

      +
      +

      Lexer for the (g)roff typesetting language, supporting groff +extensions. Mainly useful for highlighting manpage sources.

      +

      New in Pygments 0.6.

      + +++ + + + + + + + +
      Short names:groff, nroff, man
      Filename patterns:*.[1234567], *.man
      Mimetypes:application/x-troff, text/troff
      +
      +

      IniLexer

      +
      +

      Lexer for configuration files in INI style.

      + +++ + + + + + + + +
      Short names:ini, cfg
      Filename patterns:*.ini, *.cfg
      Mimetypes:text/x-ini
      +
      +

      IrcLogsLexer

      +
      +

      Lexer for IRC logs in irssi or xchat style.

      + +++ + + + + + + + +
      Short names:irc
      Filename patterns:None
      Mimetypes:text/x-irclog
      +
      +

      MakefileLexer

      +
      +

      Lexer for Makefiles.

      + +++ + + + + + + + +
      Short names:make, makefile, mf
      Filename patterns:*.mak, Makefile, makefile
      Mimetypes:text/x-makefile
      +
      +

      MoinWikiLexer

      +
      +

      For MoinMoin (and Trac) Wiki markup.

      +

      New in Pygments 0.7.

      + +++ + + + + + + + +
      Short names:trac-wiki, moin
      Filename patterns:None
      Mimetypes:text/x-trac-wiki
      +
      +

      RstLexer

      +
      +

      For reStructuredText markup.

      +

      New in Pygments 0.7.

      +

      Additional options accepted:

      +
      +
      handlecodeblocks
      +
      Highlight the contents of .. sourcecode:: langauge and +.. code:: language directives with a lexer for the given +language (default: True). New in Pygments 0.8.
      +
      + +++ + + + + + + + +
      Short names:rst, rest, restructuredtext
      Filename patterns:*.rst, *.rest
      Mimetypes:text/x-rst
      +
      +

      SourcesListLexer

      +
      +

      Lexer that highlights debian sources.list files.

      +

      New in Pygments 0.7.

      + +++ + + + + + + + +
      Short names:sourceslist, sources.list
      Filename patterns:sources.list
      Mimetypes:None
      +
      +

      TexLexer

      +
      +

      Lexer for the TeX and LaTeX typesetting languages.

      + +++ + + + + + + + +
      Short names:tex, latex
      Filename patterns:*.tex, *.aux, *.toc
      Mimetypes:text/x-tex, text/x-latex
      +
      +

      VimLexer

      +
      +

      Lexer for VimL script files

      + +++ + + + + + + + +
      Short names:vim
      Filename patterns:*.vim, .vimrc
      Mimetypes:text/x-vim
      +
      +
      +
      +

      Lexers for web-related languages and markup

      +

      ActionScriptLexer

      +
      +

      For ActionScript source code.

      +

      New in Pygments 0.9.

      + +++ + + + + + + + +
      Short names:as, actionscript
      Filename patterns:*.as
      Mimetypes:application/x-actionscript, text/x-actionscript, text/actionscript
      +
      +

      CssLexer

      +
      +

      For CSS (Cascading Style Sheets).

      + +++ + + + + + + + +
      Short names:css
      Filename patterns:*.css
      Mimetypes:text/css
      +
      +

      HtmlLexer

      +
      +

      For HTML 4 and XHTML 1 markup. Nested JavaScript and CSS is highlighted +by the appropriate lexer.

      + +++ + + + + + + + +
      Short names:html
      Filename patterns:*.html, *.htm, *.xhtml, *.xslt
      Mimetypes:text/html, application/xhtml+xml
      +
      +

      JavascriptLexer

      +
      +

      For JavaScript source code.

      + +++ + + + + + + + +
      Short names:js, javascript
      Filename patterns:*.js
      Mimetypes:application/x-javascript, text/x-javascript, text/javascript
      +
      +

      PhpLexer

      +
      +

      For PHP source code. +For PHP embedded in HTML, use the HtmlPhpLexer.

      +

      Additional options accepted:

      +
      +
      startinline
      +
      If given and True the lexer starts highlighting with +php code (i.e.: no starting <?php required). The default +is False.
      +
      funcnamehighlighting
      +
      If given and True, highlight builtin function names +(default: True).
      +
      disabledmodules
      +

      If given, must be a list of module names whose function names +should not be highlighted. By default all modules are highlighted +except the special 'unknown' module that includes functions +that are known to php but are undocumented.

      +

      To get a list of allowed modules have a look into the +_phpbuiltins module:

      +
      >>> from pygments.lexers._phpbuiltins import MODULES
+>>> MODULES.keys()
+['PHP Options/Info', 'Zip', 'dba', ...]
+
      +

      In fact the names of those modules match the module names from +the php documentation.

      +
      +
      + +++ + + + + + + + +
      Short names:php, php3, php4, php5
      Filename patterns:*.php, *.php[345]
      Mimetypes:text/x-php
      +
      +

      XmlLexer

      +
      +

      Generic lexer for XML (eXtensible Markup Language).

      + +++ + + + + + + + +
      Short names:xml
      Filename patterns:*.xml, *.xsl, *.rss, *.xslt
      Mimetypes:text/xml, application/xml, image/svg+xml, application/rss+xml, application/atom+xml, application/xsl+xml, application/xslt+xml
      +
      +
      +
      +

      Iterating over all lexers

      +

      New in Pygments 0.6.

      +

      To get all lexers (both the builtin and the plugin ones), you can +use the get_all_lexers() function from the pygments.lexers +module:

      +
      >>> from pygments.lexers import get_all_lexers
+>>> i = get_all_lexers()
+>>> i.next()
+('Diff', ('diff',), ('*.diff', '*.patch'), ('text/x-diff', 'text/x-patch'))
+>>> i.next()
+('Delphi', ('delphi', 'objectpascal', 'pas', 'pascal'), ('*.pas',), ('text/x-pascal',))
+>>> i.next()
+('XML+Ruby', ('xml+erb', 'xml+ruby'), (), ())
+
      +

      As you can see, the return value is an iterator which yields tuples +in the form (name, aliases, filetypes, mimetypes).

      +
      + +
      + + + \ No newline at end of file Added: external/Pygments-0.8.1/docs/build/moinmoin.html ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/docs/build/moinmoin.html Thu Aug 9 17:43:13 2007 @@ -0,0 +1,243 @@ + + + + Using Pygments with MoinMoin — Pygments + + + + +
      +

      Pygments

      +

      Using Pygments with MoinMoin

      + + « Back To Index + + + +

      From Pygments 0.7, the source distribution ships a Moin parser plugin that +can be used to get Pygments highlighting in Moin wiki pages.

      +

      To use it, copy the file external/moin-parser.py from the Pygments +distribution to the data/plugin/parser subdirectory of your Moin instance. +Edit the options at the top of the file (currently ATTACHMENTS and +INLINESTYLES) and rename the file to the name that the parser directive +should have. For example, if you name the file code.py, you can get a +highlighted Python code sample with this Wiki markup:

      +
      +{{{
+#!code python
+[...]
+}}}
+
      +

      where python is the Pygments name of the lexer to use.

      +

      Additionally, if you set the ATTACHMENTS option to True, Pygments will also +be called for all attachments for whose filenames there is no other parser +registered.

      +

      You are responsible for including CSS rules that will map the Pygments CSS +classes to colors. You can output a stylesheet file with pygmentize, put it +into the htdocs directory of your Moin instance and then include it in the +stylesheets configuration option in the Moin config, e.g.:

      +
      +stylesheets = [('screen', '/htdocs/pygments.css')]
+
      +

      If you do not want to do that and are willing to accept larger HTML output, you +can set the INLINESTYLES option to True.

      + +
      + + + \ No newline at end of file Added: external/Pygments-0.8.1/docs/build/plugins.html ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/docs/build/plugins.html Thu Aug 9 17:43:13 2007 @@ -0,0 +1,292 @@ + + + + Register Plugins — Pygments + + + + +
      +

      Pygments

      +

      Register Plugins

      + + « Back To Index + + +
      +

      Contents

      + +
      + +

      If you want to extend Pygments without hacking the sources, but want to +use the lexer/formatter/style/filter lookup functions (lexers.get_lexer_by_name +et al.), you can use setuptools entrypoints to add new lexers, formatters +or styles as if they were in the Pygments core.

      +

      That means you can use your highlighter modules with the pygmentize script, +which relies on the mentioned functions.

      +
      +

      Entrypoints

      +

      Here is a list of setuptools entrypoints that Pygments understands:

      +

      pygments.lexers

      +
      +

      This entrypoint is used for adding new lexers to the Pygments core. +The name of the entrypoint values doesn't really matter, Pygments extracts +required metadata from the class definition:

      +
      [pygments.lexers]
+yourlexer = yourmodule:YourLexer
+
      +

      Note that you have to define name, aliases and filename +attributes so that you can use the highlighter from the command line:

      +
      class YourLexer(...):
+    name = 'Name Of Your Lexer'
+    aliases = ['alias']
+    filenames = ['*.ext']
+
      +
      +

      pygments.formatters

      +
      +

      You can use this entrypoint to add new formatters to Pygments. The +name of an entrypoint item is the name of the formatter. If you +prefix the name with a slash it's used as a filename pattern:

      +
      [pygments.formatters]
+yourformatter = yourmodule:YourFormatter
+/.ext = yourmodule:YourFormatter
+
      +
      +

      pygments.styles

      +
      +

      To add a new style you can use this entrypoint. The name of the entrypoint +is the name of the style:

      +
      [pygments.styles]
+yourstyle = yourmodule:YourStyle
+
      +
      +

      pygments.filters

      +
      +

      Use this entrypoint to register a new filter. The name of the +entrypoint is the name of the filter:

      +
      [pygments.filters]
+yourfilter = yourmodule:YourFilter
+
      +
      +
      +
      +

      How To Use Entrypoints

      +

      This documentation doesn't explain how to use those entrypoints because this is +covered in the setuptools documentation. That page should cover everything +you need to write a plugin. Also this blog entry might be interesting.

      +
      +
      +

      Extending The Core

      +

      If you have written a Pygments plugin that is open source, please inform us +about that. There is a high chance that we'll add it to the Pygments +distribution.

      +
      + +
      + + + \ No newline at end of file Added: external/Pygments-0.8.1/docs/build/quickstart.html ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/docs/build/quickstart.html Thu Aug 9 17:43:13 2007 @@ -0,0 +1,379 @@ + + + + Introduction and Quickstart — Pygments + + + + +
      +

      Pygments

      +

      Introduction and Quickstart

      + + « Back To Index + + +
      +

      Contents

      + +
      + + +

      Welcome to Pygments! This document explains the basic concepts and terms and +gives a few examples of how to use the library.

      +
      +

      Architecture

      +

      There are four types of components that work together highlighting a piece of +code:

      +
        +
      • A lexer splits the source into tokens, fragments of the source that +have a token type that determines what the text represents semantically +(e.g., keyword, string, or comment). There is a lexer for every language +or markup format that Pygments supports.
        • +
      • The token stream can be piped through filters, which usually modify +the token types or text fragments, e.g. uppercasing all keywords.
        • +
      • A formatter then takes the token stream and writes it to an output +file, in a format such as HTML, LaTeX or RTF.
        • +
      • While writing the output, a style determines how to highlight all the +different token types. It maps them to attributes like "red and bold".
        • +
      +
      +
      +

      Example

      +

      Here is a small example for highlighting Python code:

      +
      from pygments import highlight
+from pygments.lexers import PythonLexer
+from pygments.formatters import HtmlFormatter
+
+code = 'print "Hello World"'
+print highlight(code, PythonLexer(), HtmlFormatter())
+
      +

      which prints something like this:

      +
      <div class="highlight">
+<pre><span class="k">print</span> <span class="s">&quot;Hello World&quot;</span></pre>
+</div>
+
      +

      As you can see, Pygments uses CSS classes (by default, but you can change that) +instead of inline styles in order to avoid outputting redundant style information over +and over. A CSS stylesheet that contains all CSS classes possibly used in the output +can be produced by:

      +
      print HtmlFormatter().get_style_defs('.highlight')
+
      +

      The argument to get_style_defs is used as an additional CSS selector: the output +may look like this:

      +
      .highlight .k { color: #AA22FF; font-weight: bold }
+.highlight .s { color: #BB4444 }
+...
+
      +
      +
      +

      Options

      +

      The highlight() function supports a fourth argument called outfile, it must be +a file object if given. The formatted output will then be written to this file +instead of being returned as a string.

      +

      Lexers and formatters both support options. They are given to them as keyword +arguments either to the class or to the lookup method:

      +
      from pygments import highlight
+from pygments.lexers import get_lexer_by_name
+from pygments.formatters import HtmlFormatter
+
+lexer = get_lexer_by_name("python", stripall=True)
+formatter = HtmlFormatter(linenos=True, cssclass="source")
+result = highlight(code, lexer, formatter)
+
      +

      This makes the lexer strip all leading and trailing whitespace from the input +(stripall option), lets the formatter output line numbers (linenos option), +and sets the wrapping <div>'s class to source (instead of +highlight).

      +

      Important options include:

      +
      +
      encoding : for lexers and formatters
      +
      Since Pygments uses Unicode strings internally, this determines which +encoding will be used to convert to or from byte strings.
      +
      style : for formatters
      +
      The name of the style to use when writing the output.
      +
      +

      For an overview of builtin lexers and formatters and their options, visit the +lexer and formatters lists.

      +

      For a documentation on filters, see this page.

      +
      +
      +

      Lexer and formatter lookup

      +

      If you want to lookup a built-in lexer by its alias or a filename, you can use +one of the following methods:

      +
      >>> from pygments.lexers import (get_lexer_by_name,
+...     get_lexer_for_filename, get_lexer_for_mimetype)
+
+>>> get_lexer_by_name('python')
+<pygments.lexers.PythonLexer>
+
+>>> get_lexer_for_filename('spam.rb')
+<pygments.lexers.RubyLexer>
+
+>>> get_lexer_for_mimetype('text/x-perl')
+<pygments.lexers.PerlLexer>
+
      +

      All these functions accept keyword arguments; they will be passed to the lexer +as options.

      +

      A similar API is available for formatters: use get_formatter_by_name() and +get_formatter_for_filename() from the pygments.formatters module +for this purpose.

      +
      +
      +

      Guessing lexers

      +

      If you don't know the content of the file, or you want to highlight a file +whose extension is ambiguous, such as .html (which could contain plain HTML +or some template tags), use these functions:

      +
      >>> from pygments.lexers import guess_lexer, guess_lexer_for_filename
+
+>>> guess_lexer('#!/usr/bin/python\nprint "Hello World!"')
+<pygments.lexers.PythonLexer>
+
+>>> guess_lexer_for_filename('test.py', 'print "Hello World!"')
+<pygments.lexers.PythonLexer>
+
      +

      guess_lexer() passes the given content to the lexer classes' analyze_text() +method and returns the one for which it returns the highest number.

      +

      All lexers have two different filename pattern lists: the primary and the +secondary one. The get_lexer_for_filename() function only uses the primary +list, whose entries are supposed to be unique among all lexers. +guess_lexer_for_filename(), however, will first loop through all lexers and +look at the primary and secondary filename patterns if the filename matches. +If only one lexer matches, it is returned, else the guessing mechanism of +guess_lexer() is used with the matching lexers.

      +

      As usual, keyword arguments to these functions are given to the created lexer +as options.

      +
      +
      +

      Command line usage

      +

      You can use Pygments from the command line, using the pygmentize script:

      +
      +$ pygmentize test.py
+
      +

      will highlight the Python file test.py using ANSI escape sequences +(a.k.a. terminal colors) and print the result to standard output.

      +

      To output HTML, use the -f option:

      +
      +$ pygmentize -f html -o test.html test.py
+
      +

      to write an HTML-highlighted version of test.py to the file test.html.

      +

      The stylesheet can be created with:

      +
      +$ pygmentize -S default -f html > style.css
+
      +

      More options and tricks and be found in the command line referene.

      +
      + +
      + + + \ No newline at end of file Added: external/Pygments-0.8.1/docs/build/rstdirective.html ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/docs/build/rstdirective.html Thu Aug 9 17:43:13 2007 @@ -0,0 +1,282 @@ + + + + Using Pygments in ReST documents — Pygments + + + + +
      +

      Pygments

      +

      Using Pygments in ReST documents

      + + « Back To Index + + +

      Many Python people use ReST for documentation their sourcecode, programs, +scripts et cetera. This also means that documentation often includes sourcecode +samples or snippets.

      +

      You can easily enable Pygments support for your ReST texts using a custom +directive -- this is also how this documentation displays source code.

      +

      Add this code to the script you use for building the HTML documentation:

      +
      from docutils import nodes
+from docutils.parsers.rst import directives
+from pygments import highlight
+from pygments.lexers import get_lexer_by_name
+from pygments.formatters import HtmlFormatter
+
+pygments_formatter = HtmlFormatter()
+
+def pygments_directive(name, arguments, options, content, lineno,
+                       content_offset, block_text, state, state_machine):
+    try:
+        lexer = get_lexer_by_name(arguments[0])
+    except ValueError:
+        # no lexer found - use the text one instead of an exception
+        lexer = get_lexer_by_name('text')
+    parsed = highlight(u'\n'.join(content), lexer, pygments_formatter)
+    return [nodes.raw('', parsed, format='html')]
+pygments_directive.arguments = (1, 0, 1)
+pygments_directive.content = 1
+directives.register_directive('sourcecode', pygments_directive)
+
      +

      Now you should be able to use Pygments to highlight source code in your ReST +files using this syntax:

      +
      +.. sourcecode:: language
+
+    your code here
+
      +

      If you want to have two or more variants of the directive, you can utilize +ReST directive options, like so:

      +
      normal_fmter = HtmlFormatter()
+lineno_fmter = HtmlFormatter(linenos=True)
+
+def pygments_directive(name, arguments, options, content, lineno,
+                       content_offset, block_text, state, state_machine):
+    try:
+        lexer = get_lexer_by_name(arguments[0])
+    except ValueError:
+        # no lexer found - use the text one instead of an exception
+        lexer = get_lexer_by_name('text')
+    formatter = ('linenos' in options) and lineno_fmter or normal_fmter
+    parsed = highlight(u'\n'.join(content), lexer, formatter)
+    return [nodes.raw('', parsed, format='html')]
+pygments_directive.arguments = (1, 0, 1)
+pygments_directive.content = 1
+pygments_directive.options = {'linenos': directives.flag}
+directives.register_directive('sourcecode', pygments_directive)
+
      +

      And use it like so:

      +
      +.. sourcecode:: language
+   :linenos:
+
+   the code starts here...
+
      +

      to get line numbers (to use the normal formatter, just leave out the option +like above).

      +

      Look at the directive documentation to get all the gory details.

      +

      Loosely related note: The ReST lexer now recognizes .. sourcecode:: and +.. code:: directives and highlights the contents in the specified language +if the handlecodeblocks option is true.

      + +
      + + + \ No newline at end of file Added: external/Pygments-0.8.1/docs/build/styles.html ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/docs/build/styles.html Thu Aug 9 17:43:13 2007 @@ -0,0 +1,339 @@ + + + + Styles — Pygments + + + + +
      +

      Pygments

      +

      Styles

      + + « Back To Index + + +
      +

      Contents

      + +
      + + +

      Pygments comes with some builtin styles that work for both the HTML and +LaTeX formatter.

      +

      The builtin styles can be looked up with the get_style_by_name function:

      +
      >>> from pygments.styles import get_style_by_name
+>>> get_style_by_name('colorful')
+<class 'pygments.styles.colorful.ColorfulStyle'>
+
      +

      You can pass a instance of a Style class to a formatter as the style +option in form of a string:

      +
      >>> from pygments.styles import get_style_by_name
+>>> HtmlFormatter(style='colorful').style
+<class 'pygments.styles.colorful.ColorfulStyle'>
+
      +

      Or you can also import your own style (which must be a subclass of +pygments.style.Style) and pass it to the formatter:

      +
      >>> from yourapp.yourmodule import YourStyle
+>>> HtmlFormatter(style=YourStyle).style
+<class 'yourapp.yourmodule.YourStyle'>
+
      +
      +

      Creating Own Styles

      +

      So, how to create a style? All you have to do is to subclass Style and +define some styles:

      +
      from pygments.style import Style
+from pygments.token import Keyword, Name, Comment, String, Error, \
+     Number, Operator, Generic
+
+class YourStyle(Style):
+    default_style = ""
+    styles = {
+        Comment:                'italic #888',
+        Keyword:                'bold #005',
+        Name:                   '#f00',
+        Name.Function:          '#0f0',
+        Name.Class:             'bold #0f0',
+        String:                 'bg:#eee #111'
+    }
+
      +

      That's it. There are just a few rules. When you define a style for Name +the style automatically also affects Name.Function and so on. If you +defined 'bold' and you don't want boldface for a subtoken use 'nobold'.

      +

      (Philosophy: the styles aren't written in CSS syntax since this way +they can be used for a variety of formatters.)

      +

      default_style is the style inherited by all token types.

      +

      To make the style usable for Pygments, you must

      +
        +
      • either register it as a plugin (see the plugin docs)
        • +
      • or drop it into the styles subpackage of your Pygments distribution one style +class per style, where the file name is the style name and the class name is +StylenameClass. For example, if your style should be called +"mondrian", name the class MondrianStyle, put it into the file +mondrian.py and this file into the pygments.styles subpackage +directory.
        • +
      +
      +
      +

      Style Rules

      +

      Here a small overview of all allowed styles:

      +
      +
      bold
      +
      render text as bold
      +
      nobold
      +
      don't render text as bold (to prevent subtokens behing highlighted bold)
      +
      italic
      +
      render text italic
      +
      noitalic
      +
      don't render text as italic
      +
      underline
      +
      render text underlined
      +
      nounderline
      +
      don't render text underlined
      +
      bg:
      +
      transparent background
      +
      bg:#000000
      +
      background color (black)
      +
      border:
      +
      no border
      +
      border:#ffffff
      +
      border color (white)
      +
      #ff0000
      +
      text color (red)
      +
      noinherit
      +
      don't inherit styles from supertoken
      +
      +

      Note that there may not be a space between bg: and the color value +since the style definition string is split at whitespace. +Also, using named colors is not allowed since the supported color names +vary for different formatters.

      +

      Furthermore, not all lexers might support every style.

      +
      +
      +

      Builtin Styles

      +

      Pygments ships some builtin styles which are maintained by the Pygments team.

      +

      To get a list of known styles you can use this snippet:

      +
      >>> from pygments.styles import STYLE_MAP
+>>> STYLE_MAP.keys()
+['default', 'emacs', 'friendly', 'colorful']
+
      +
      +
      +

      Getting a list of available styles

      +

      New in Pygments 0.6.

      +

      Because it could be that a plugin registered a style, there is +a way to iterate over all styles:

      +
      >>> from pygments.styles import get_all_styles
+>>> styles = list(get_all_styles())
+
      +
      + +
      + + + \ No newline at end of file Added: external/Pygments-0.8.1/docs/build/tokens.html ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/docs/build/tokens.html Thu Aug 9 17:43:13 2007 @@ -0,0 +1,536 @@ + + + + Builtin Tokens — Pygments + + + + +
      +

      Pygments

      +

      Builtin Tokens

      + + « Back To Index + + +
      +

      Contents

      + +
      + + +

      Inside the pygments.token module, there is a special object called Token +that is used to create token types.

      +

      You can create a new token type by accessing an attribute of Token:

      +
      >>> from pygments.token import Token
+>>> Token.String
+Token.String
+>>> Token.String is Token.String
+True
+
      +

      Note that tokens are singletons so you can use the is operator for comparing +token types.

      +

      As of Pygments 0.7 you can also use the in operator to perform set tests:

      +
      >>> from pygments.token import Comment
+>>> Comment.Single in Comment
+True
+>>> Comment in Comment.Multi
+False
+
      +

      This can be useful in filters and if you write lexers on your own without +using the base lexers.

      +

      You can also split a token type into a hierarchy, and get the parent of it:

      +
      >>> String.split()
+[Token, Token.Literal, Token.Literal.String]
+>>> String.parent
+Token.Literal
+
      +

      In principle, you can create an unlimited number of token types but nobody can +guarantee that a style would define style rules for a token type. Because of +that, Pygments proposes some global token types defined in the +pygments.token.STANDARD_TYPES dict.

      +

      For some tokens aliases are already defined:

      +
      >>> from pygments.token import String
+>>> String
+Token.Literal.String
+
      +

      Inside the pygments.token module the following aliases are defined:

      + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      TextToken.Textfor any type of text data
      WhitespaceToken.Text.Whitespacefor specially highlighted whitespace
      ErrorToken.Errorrepresents lexer errors
      OtherToken.Otherspecial token for data not +matched by a parser (e.g. HTML +markup in PHP code)
      KeywordToken.Keywordany kind of keywords
      NameToken.Namevariable/function names
      LiteralToken.LiteralAny literals
      StringToken.Literal.Stringstring literals
      NumberToken.Literal.Numbernumber literals
      OperatorToken.Operatoroperators (+, not...)
      PunctuationToken.Punctuationpunctuation ([, (...)
      CommentToken.Commentany kind of comments
      GenericToken.Genericgeneric tokens (have a look at +the explanation below)
      +

      The Whitespace token type is new in Pygments 0.8. It is used only by the +VisibleWhitespaceFilter currently.

      +

      Normally you just create token types using the already defined aliases. For each +of those token aliases, a number of subtypes exists (excluding the special tokens +Token.Text, Token.Error and Token.Other)

      +

      The is_token_subtype() function in the pygments.token module can be used to +test if a token type is a subtype of another (such as Name.Tag and Name). +(This is the same as Name.Tag in Name. The overloaded in operator was newly +introduced in Pygments 0.7, the function still exists for backwards +compatiblity.)

      +

      With Pygments 0.7, it's also possible to convert strings to token types (for example +if you want to supply a token from the command line):

      +
      >>> from pygments.token import String, string_to_tokentype
+>>> string_to_tokentype("String")
+Token.Literal.String
+>>> string_to_tokentype("Token.Literal.String")
+Token.Literal.String
+>>> string_to_tokentype(String)
+Token.Literal.String
+
      +
      +

      Keyword Tokens

      +
      +
      Keyword
      +
      For any kind of keyword (especially if it doesn't match any of the +subtypes of course).
      +
      Keyword.Constant
      +
      For keywords that are constants (e.g. None in future Python versions).
      +
      Keyword.Declaration
      +
      For keywords used for variable declaration (e.g. var in some programming +languages like JavaScript).
      +
      Keyword.Pseudo
      +
      For keywords that aren't really keywords (e.g. None in old Python +versions).
      +
      Keyword.Reserved
      +
      For reserved keywords.
      +
      Keyword.Type
      +
      For builtin types that can't be used as identifiers (e.g. int, +char etc. in C).
      +
      +
      +
      +

      Name Tokens

      +
      +
      Name
      +
      For any name (variable names, function names, classes).
      +
      Name.Attribute
      +
      For all attributes (e.g. in HTML tags).
      +
      Name.Builtin
      +
      Builtin names; names that are available in the global namespace.
      +
      Name.Builtin.Pseudo
      +
      Builtin names that are implicit (e.g. self in Ruby, this in Java).
      +
      Name.Class
      +
      Class names. Because no lexer can know if a name is a class or a function +or something else this token is meant for class declarations.
      +
      Name.Constant
      +
      Token type for constants. In some languages you can recognise a token by the +way it's defined (the value after a const keyword for example). In +other languages constants are uppercase by definition (Ruby).
      +
      Name.Decorator
      +
      Token type for decorators. Decorators are synatic elements in the Python +language. Similar syntax elements exist in C# and Java.
      +
      Name.Entity
      +
      Token type for special entities. (e.g. &nbsp; in HTML).
      +
      Name.Exception
      +
      Token type for exception names (e.g. RuntimeError in Python). Some languages +define exceptions in the function signature (Java). You can highlight +the name of that exception using this token then.
      +
      Name.Function
      +
      Token type for function names.
      +
      Name.Label
      +
      Token type for label names (e.g. in languages that support goto).
      +
      Name.Namespace
      +
      Token type for namespaces. (e.g. import paths in Java/Python), names following +the module/namespace keyword in other languages.
      +
      Name.Other
      +
      Other names. Normally unused.
      +
      Name.Tag
      +
      Tag names (in HTML/XML markup or configuration files).
      +
      Name.Variable
      +
      Token type for variables. Some languages have prefixes for variable names +(PHP, Ruby, Perl). You can highlight them using this token.
      +
      Name.Variable.Class
      +
      same as Name.Variable but for class variables (also static variables).
      +
      Name.Variable.Global
      +
      same as Name.Variable but for global variables (used in Ruby, for +example).
      +
      Name.Variable.Instance
      +
      same as Name.Variable but for instance variables.
      +
      +
      +
      +

      Literals

      +
      +
      Literal
      +
      For any literal (if not further defined).
      +
      Literal.Date
      +
      for date literals (e.g. 42d in Boo).
      +
      String
      +
      For any string literal.
      +
      String.Backtick
      +
      Token type for strings enclosed in backticks.
      +
      String.Char
      +
      Token type for single characters (e.g. Java, C).
      +
      String.Doc
      +
      Token type for documentation strings (for example Python).
      +
      String.Double
      +
      Double quoted strings.
      +
      String.Escape
      +
      Token type for escape sequences in strings.
      +
      String.Heredoc
      +
      Token type for "heredoc" strings (e.g. in Ruby or Perl).
      +
      String.Interpol
      +
      Token type for interpolated parts in strings (e.g. #{foo} in Ruby).
      +
      String.Other
      +
      Token type for any other strings (for example %q{foo} string constructs +in Ruby).
      +
      String.Regex
      +
      Token type for regular expression literals (e.g. /foo/ in JavaScript).
      +
      String.Single
      +
      Token type for single quoted strings.
      +
      String.Symbol
      +
      Token type for symbols (e.g. :foo in LISP or Ruby).
      +
      Number
      +
      Token type for any number literal.
      +
      Number.Float
      +
      Token type for float literals (e.g. 42.0).
      +
      Number.Hex
      +
      Token type for hexadecimal number literals (e.g. 0xdeadbeef).
      +
      Number.Integer
      +
      Token type for integer literals (e.g. 42).
      +
      Number.Integer.Long
      +
      Token type for long integer literals (e.g. 42L in Python).
      +
      Number.Oct
      +
      Token type for octal literals.
      +
      +
      +
      +

      Operators

      +
      +
      Operator
      +
      For any punctuation operator (e.g. +, -).
      +
      Operator.Word
      +
      For any operator that is a word (e.g. not).
      +
      +
      +
      +

      Punctuation

      +

      New in Pygments 0.7.

      +
      +
      Punctuation
      +
      For any punctuation which is not an operator (e.g. [, (...)
      +
      +
      +
      +

      Comments

      +
      +
      Comment
      +
      Token type for any comment.
      +
      Comment.Multiline
      +
      Token type for multiline comments.
      +
      Comment.Preproc
      +
      Token type for preprocessor comments (also <?php/<% constructs).
      +
      Comment.Single
      +
      Token type for comments that end at the end of a line (e.g. # foo).
      +
      Comment.Special
      +
      Special data in comments. For example code tags, author and license +informations etc.
      +
      +
      +
      +

      Generic Tokens

      +

      Generic tokens are for special lexers like the DiffLexer that doesn't really +highlight a programming language but a patch file.

      +
      +
      Generic
      +
      A generic, unstyled token. Normally you don't use this token type.
      +
      Generic.Deleted
      +
      Marks the token value as deleted.
      +
      Generic.Emph
      +
      Marks the token value as emphasized.
      +
      Generic.Error
      +
      Marks the token value as an error message.
      +
      Generic.Heading
      +
      Marks the token value as headline.
      +
      Generic.Inserted
      +
      Marks the token value as inserted.
      +
      Generic.Output
      +
      Marks the token value as program output (e.g. for python cli lexer).
      +
      Generic.Prompt
      +
      Marks the token value as command prompt (e.g. bash lexer).
      +
      Generic.Strong
      +
      Marks the token value as bold (e.g. for rst lexer).
      +
      Generic.Subheading
      +
      Marks the token value as subheadline.
      +
      Generic.Traceback
      +
      Marks the token value as a part of an error traceback.
      +
      +
      + +
      + + + \ No newline at end of file Added: external/Pygments-0.8.1/docs/build/unicode.html ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/docs/build/unicode.html Thu Aug 9 17:43:13 2007 @@ -0,0 +1,246 @@ + + + + Unicode and Encodings — Pygments + + + + +
      +

      Pygments

      +

      Unicode and Encodings

      + + « Back To Index + + +

      Since Pygments 0.6, all lexers use unicode strings internally. Because of that +you might encounter the occasional UnicodeDecodeError if you pass strings with the +wrong encoding.

      +

      Per default all lexers have their input encoding set to latin1. +If you pass a lexer a string object (not unicode), it tries to decode the data +using this encoding. +You can override the encoding using the encoding lexer option. If you have the +chardet library installed and set the encoding to chardet if will ananlyse +the text and use the encoding it thinks is the right one automatically:

      +
      from pygments.lexers import PythonLexer
+lexer = PythonLexer(encoding='chardet')
+
      +

      The best way is to pass Pygments unicode objects. In that case you can't get +unexpected output.

      +

      The formatters now send Unicode objects to the stream if you don't set the +output encoding. You can do so by passing the formatters an encoding option:

      +
      from pygments.formatters import HtmlFormatter
+f = HtmlFormatter(encoding='utf-8')
+
      +

      You will have to set this option if you have non-ASCII characters in the +source and the output stream does not accept Unicode written to it! +This is the case for all regular files and for terminals.

      +

      Note: The Terminal formatter tries to be smart: if its output stream has an +encoding attribute, and you haven't set the option, +it will encode any Unicode string with this encoding +before writing it. This is the case for sys.stdout, for example. The other +formatters don't have that behavior.

      +

      New in Pygments 0.7: the formatters now also accept an outencoding option +which will override the encoding option if given. This makes it possible to +use a single options dict with lexers and formatters, and still have different +input and output encodings.

      + +
      + + + \ No newline at end of file Added: external/Pygments-0.8.1/docs/generate.py ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/docs/generate.py Thu Aug 9 17:43:13 2007 @@ -0,0 +1,465 @@ +#!/usr/bin/env python +# -*- coding: utf-8 -*- +""" + Generate Pygments Documentation + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Generates a bunch of html files containing the documentation. + + :copyright: 2006-2007 by Armin Ronacher, Georg Brandl. + :license: BSD, see LICENSE for more details. +""" + +import os +import sys +from datetime import datetime +from cgi import escape + +from docutils import nodes +from docutils.parsers.rst import directives +from docutils.core import publish_parts +from docutils.writers import html4css1 + +from jinja import from_string + +from pygments import highlight +from pygments.lexers import get_lexer_by_name +from pygments.formatters import HtmlFormatter + + +LEXERDOC = ''' +`%s` +%s + :Short names: %s + :Filename patterns: %s + :Mimetypes: %s + +''' + +def generate_lexer_docs(): + from pygments.lexers import LEXERS + + out = [] + + modules = {} + moduledocstrings = {} + for classname, data in sorted(LEXERS.iteritems(), key=lambda x: x[0]): + module = data[0] + mod = __import__(module, None, None, [classname]) + cls = getattr(mod, classname) + if not cls.__doc__: + print "Warning: %s does not have a docstring." % classname + modules.setdefault(module, []).append(( + classname, + cls.__doc__, + ', '.join(data[2]) or 'None', + ', '.join(data[3]).replace('*', '\\*') or 'None', + ', '.join(data[4]) or 'None')) + if module not in moduledocstrings: + moduledocstrings[module] = mod.__doc__ + + for module, lexers in sorted(modules.iteritems(), key=lambda x: x[0]): + heading = moduledocstrings[module].splitlines()[4].strip().rstrip('.') + out.append('\n' + heading + '\n' + '-'*len(heading) + '\n') + for data in lexers: + out.append(LEXERDOC % data) + return ''.join(out) + +def generate_formatter_docs(): + from pygments.formatters import FORMATTERS + + out = [] + for cls, data in FORMATTERS.iteritems(): + heading = cls.__name__ + out.append('`' + heading + '`\n' + '-'*(2+len(heading)) + '\n') + out.append(cls.__doc__) + out.append(''' + :Short names: %s + :Filename patterns: %s + + +''' % (', '.join(data[1]) or 'None', ', '.join(data[2]).replace('*', '\\*') or 'None')) + return ''.join(out) + +def generate_filter_docs(): + from pygments.filters import FILTERS + + out = [] + for name, cls in FILTERS.iteritems(): + out.append(''' +`%s` +%s + :Name: %s +''' % (cls.__name__, cls.__doc__, name)) + return ''.join(out) + +def generate_changelog(): + fn = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', + 'CHANGES')) + f = file(fn) + result = [] + in_header = False + header = True + for line in f: + if header: + if not in_header and line.strip(): + in_header = True + elif in_header and not line.strip(): + header = False + else: + result.append(line.rstrip()) + f.close() + return '\n'.join(result) + +def generate_authors(): + fn = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', + 'AUTHORS')) + f = file(fn) + r = f.read().rstrip() + f.close() + return r + +LEXERDOCS = generate_lexer_docs() +FORMATTERDOCS = generate_formatter_docs() +FILTERDOCS = generate_filter_docs() +CHANGELOG = generate_changelog() +AUTHORS = generate_authors() + + +PYGMENTS_FORMATTER = HtmlFormatter(style='pastie', cssclass='syntax') + +USAGE = '''\ +Usage: %s [ ...] + +Generate either python or html files out of the documentation. + +Mode can either be python or html.\ +''' % sys.argv[0] + +TEMPLATE = '''\ + + + + {{ title }} — Pygments + + + + +
      +

      Pygments

      +

      {{ title }}

      + {% if file_id != "index" %} + « Back To Index + {% endif %} + {% if toc %} +
      +

      Contents

      +
        + {% for key, value in toc %} +
      • {{ value }}
        • + {% endfor %} +
      +
      + {% endif %} + {{ body }} +
      + + +\ +''' + +STYLESHEET = '''\ +body { + background-color: #f2f2f2; + margin: 0; + padding: 0; + font-family: 'Georgia', serif; + color: #111; +} + +#content { + background-color: white; + padding: 20px; + margin: 20px auto 20px auto; + max-width: 800px; + border: 4px solid #ddd; +} + +h1 { + font-weight: normal; + font-size: 40px; + color: #09839A; +} + +h2 { + font-weight: normal; + font-size: 30px; + color: #C73F00; +} + +h1.heading { + margin: 0 0 30px 0; +} + +h2.subheading { + margin: -30px 0 0 45px; +} + +h3 { + margin-top: 30px; +} + +table.docutils { + border-collapse: collapse; + border: 2px solid #aaa; + margin: 0.5em 1.5em 0.5em 1.5em; +} + +table.docutils td { + padding: 2px; + border: 1px solid #ddd; +} + +p, li, dd, dt, blockquote { + font-size: 15px; + color: #333; +} + +p { + line-height: 150%; + margin-bottom: 0; + margin-top: 10px; +} + +hr { + border-top: 1px solid #ccc; + border-bottom: 0; + border-right: 0; + border-left: 0; + margin-bottom: 10px; + margin-top: 20px; +} + +dl { + margin-left: 10px; +} + +li, dt { + margin-top: 5px; +} + +dt { + font-weight: bold; +} + +th { + text-align: left; +} + +a { + color: #990000; +} + +a:hover { + color: #c73f00; +} + +pre { + background-color: #f9f9f9; + border-top: 1px solid #ccc; + border-bottom: 1px solid #ccc; + padding: 5px; + font-size: 13px; + font-family: Bitstream Vera Sans Mono,monospace; +} + +tt { + font-size: 13px; + font-family: Bitstream Vera Sans Mono,monospace; + color: black; + padding: 1px 2px 1px 2px; + background-color: #f0f0f0; +} + +cite { + /* abusing , it's generated by ReST for `x` */ + font-size: 13px; + font-family: Bitstream Vera Sans Mono,monospace; + font-weight: bold; + font-style: normal; +} + +#backlink { + float: right; + font-size: 11px; + color: #888; +} + +div.toc { + margin: 0 0 10px 0; +} + +div.toc h2 { + font-size: 20px; +} +''' #' + + +def pygments_directive(name, arguments, options, content, lineno, + content_offset, block_text, state, state_machine): + try: + lexer = get_lexer_by_name(arguments[0]) + except ValueError: + # no lexer found + lexer = get_lexer_by_name('text') + parsed = highlight(u'\n'.join(content), lexer, PYGMENTS_FORMATTER) + return [nodes.raw('', parsed, format="html")] +pygments_directive.arguments = (1, 0, 1) +pygments_directive.content = 1 +directives.register_directive('sourcecode', pygments_directive) + + +def create_translator(link_style): + class Translator(html4css1.HTMLTranslator): + def visit_reference(self, node): + refuri = node.get('refuri') + if refuri is not None and '/' not in refuri and refuri.endswith('.txt'): + node['refuri'] = link_style(refuri[:-4]) + html4css1.HTMLTranslator.visit_reference(self, node) + return Translator + + +class DocumentationWriter(html4css1.Writer): + + def __init__(self, link_style): + html4css1.Writer.__init__(self) + self.translator_class = create_translator(link_style) + + def translate(self): + html4css1.Writer.translate(self) + # generate table of contents + contents = self.build_contents(self.document) + contents_doc = self.document.copy() + contents_doc.children = contents + contents_visitor = self.translator_class(contents_doc) + contents_doc.walkabout(contents_visitor) + self.parts['toc'] = self._generated_toc + + def build_contents(self, node, level=0): + sections = [] + i = len(node) - 1 + while i >= 0 and isinstance(node[i], nodes.section): + sections.append(node[i]) + i -= 1 + sections.reverse() + toc = [] + for section in sections: + try: + reference = nodes.reference('', '', refid=section['ids'][0], *section[0]) + except IndexError: + continue + ref_id = reference['refid'] + text = escape(reference.astext().encode('utf-8')) + toc.append((ref_id, text)) + + self._generated_toc = [('#%s' % href, caption) for href, caption in toc] + # no further processing + return [] + + +def generate_documentation(data, link_style): + writer = DocumentationWriter(link_style) + data = data.replace('[builtin_lexer_docs]', LEXERDOCS).\ + replace('[builtin_formatter_docs]', FORMATTERDOCS).\ + replace('[builtin_filter_docs]', FILTERDOCS).\ + replace('[changelog]', CHANGELOG).\ + replace('[authors]', AUTHORS) + parts = publish_parts( + data, + writer=writer, + settings_overrides={ + 'initial_header_level': 3, + 'field_name_limit': 50, + } + ) + return { + 'title': parts['title'].encode('utf-8'), + 'body': parts['body'].encode('utf-8'), + 'toc': parts['toc'] + } + + +def handle_python(filename, fp, dst): + now = datetime.now() + title = os.path.basename(filename)[:-4] + content = fp.read() + def urlize(href): + # create links for the pygments webpage + if href == 'index.txt': + return '/docs/' + else: + return '/docs/%s/' % href + parts = generate_documentation(content, urlize) + result = file(os.path.join(dst, title + '.py'), 'w') + result.write('# -*- coding: utf-8 -*-\n') + result.write('"""\n Pygments Documentation - %s\n' % title) + result.write(' %s\n\n' % ('~' * (24 + len(title)))) + result.write(' Generated on: %s\n"""\n\n' % now) + result.write('import datetime\n') + result.write('DATE = %r\n' % now) + result.write('TITLE = %r\n' % parts['title']) + result.write('TOC = %r\n' % parts['toc']) + result.write('BODY = %r\n' % parts['body']) + result.close() + + +def handle_html(filename, fp, dst): + now = datetime.now() + title = os.path.basename(filename)[:-4] + content = fp.read() + c = generate_documentation(content, (lambda x: './%s.html' % x)) + result = file(os.path.join(dst, title + '.html'), 'w') + c['style'] = STYLESHEET + PYGMENTS_FORMATTER.get_style_defs('.syntax') + c['generation_date'] = now + c['file_id'] = title + t = from_string(TEMPLATE) + result.write(t.render(c).encode('utf-8')) + result.close() + + +def run(handle_file, dst, sources=()): + path = os.path.abspath(os.path.join(os.path.dirname(__file__), 'src')) + if not sources: + sources = [os.path.join(path, fn) for fn in os.listdir(path)] + for fn in sources: + if not os.path.isfile(fn): + continue + print 'Processing %s' % fn + f = open(fn) + try: + handle_file(fn, f, dst) + finally: + f.close() + + +def main(mode, dst='build/', *sources): + try: + handler = { + 'html': handle_html, + 'python': handle_python + }[mode] + except KeyError: + print 'Error: unknown mode "%s"' % mode + sys.exit(1) + run(handler, os.path.realpath(dst), sources) + + +if __name__ == '__main__': + if len(sys.argv) == 1: + print USAGE + else: + main(*sys.argv[1:]) Added: external/Pygments-0.8.1/docs/pygmentize.1 ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/docs/pygmentize.1 Thu Aug 9 17:43:13 2007 @@ -0,0 +1,89 @@ +.TH PYGMENTIZE 1 "February 15, 2007" + +.SH NAME +pygmentize \- highlights the input file + +.SH SYNOPSIS +.B \fBpygmentize\fP +.RI [-l\ \fI\fP]\ [-F\ \fI\fP[:\fI\fP]]\ [-f\ \fI\fP] +.RI [-O\ \fI\fP]\ [-o\ \fI\fP]\ [\fI\fP] +.br +.B \fBpygmentize\fP +.RI -S\ \fI + + +

      %(title)s

      + +''' + + +DOC_HEADER_EXTERNALCSS = '''\ + + + + + %(title)s + + + + +

      %(title)s

      + +''' + +DOC_FOOTER = '''\ + + +''' + + +CSSFILE_TEMPLATE = '''\ +td.linenos { background-color: #f0f0f0; padding-right: 10px; } +%(styledefs)s +''' + + +class HtmlFormatter(Formatter): + r""" + Format tokens as HTML 4 ```` tags within a ``
      `` tag, wrapped
+    in a ``
      `` tag. The ``
      ``'s CSS class can be set by the `cssclass`
+    option.
+
+    If the `linenos` option is set to ``"table"``, the ``
      `` is
+    additionally wrapped inside a ```` which has one row and two
+    cells: one containing the line numbers and one containing the code.
+    Example:
+
+    .. sourcecode:: html
+
+        
      
+        
      
+          
+          
+        
      
+            
      1
+            2
      
+                		
+            
      def foo(bar):
+              pass
+            
      
+          
      
+
+    (whitespace added to improve clarity).
+
+    Wrapping can be disabled using the `nowrap` option.
+
+    With the `full` option, a complete HTML 4 document is output, including
+    the style definitions inside a ``
+
+
+
      Code tags report for %s
      
+
+
+%s
+
      LineTagWhoDescription
      
+
+
+'''
+
+    TABLE = '\n
      File: %s
      %%(lno)d%%(tag)s%%(who)s%%(what)s
      + + + + + + + + + + + +
      Name:<%= text_field 'user', 'name' %>
      Passwort:<%= password_field 'user', 'password' %>
      <%= submit_tag 'Anmelden' %>
      +<%= end_form_tag %> +<% @title = 'Neuer Benutzer' -%> +<%= error_messages_for :user %> +<%= render :partial => 'form', :object => @user %> +<%= form_tag %> + + + + + + + + + + + + +
      Name:<%= text_field 'user', 'name' %>
      Passwort:<%= password_field 'user', 'password' %>
      <%= submit_tag 'Anlegen' %>
      +<%= end_form_tag %> +<% @title = 'Auftritte' %> + + + <%= render :partial => 'head' %> + <%= render :partial => 'day', :collection => @days %> +
      +<% day, auftritte = *day -%> +<% + for auftritt in auftritte +-%> + +
    + <%= colorize day.to_s(:dots) if day %> + <% if day and day.wday == 6 %>
    Samstag<% end %> +     		+ <%= colorize auftritt.time %> + + <%= colorize auftritt.program %> + <%= link_to 'E', :controller => 'admin/auftritte', :action => :edit, :id => auftritt %> + + <%= colorize(auftritt.place, 'Ort: ') + '
    ' unless auftritt.place.blank? %> +
    DatumZeitProgrammOrt
    + <%= render :partial => 'member', :collection => @members %> +
    +<% @title = 'Besetzung: %d Mitglieder' % Member.count -%> + +
    +<% if params[:action] == 'all' -%> +<%= link_to 'seitenweise', :action => :index %> +<% else -%> +<%= link_to_if @member_pages.current.previous, '<<', :page => @member_pages.current.previous %> +| <%= link_to 'alle', :action => :all %> | +<%= link_to_if @member_pages.current.next, '>>', :page => @member_pages.current.next %> +<% end -%> +| <%= link_to 'Nach Instrumenten', :action => :select_instrument %> +
    + + +<%= render :partial => 'member', :collection => @members %> +
    +<% @title = "Besetzung - Instrument w??hlen" %> + + +<% @title = "Besetzung: #{@member.name}" -%> + +
    + +
    Instrument / Aufgabe:
    +
    <%= link_to_instruments_of @member %>
    + +
    Geburtstag:
    +
    <%= h @member.birthday.to_s(:dots) %>
    + +
    Adresse:
    +
    <%= h @member.street %>
    <%= h @member.plz %>
    + +
    Telefon:
    +
    <%= h @member.phone %>
    + +
    Email:
    +
    <%= mail_to @member.email, @member.email, :encode => 'javascript' %>
    + +
    + + <%= link_to member.name, :action => :show, :id => member %>: + <%= link_to_instruments_of member %> + + +<% @title = 'Arbeitsgruppen' -%> +

    + Die Arbeitsgruppen sind verantwortlich f??r die Organisation und Durchf??hrung verschiedenster Aufgaben: +

    + + +<% @title = 'Chronik' -%> +

    + Das Jugendsinfonieorchester Marzahn-Hellersdorf wurde im Januar 2005 an der + Musikschule Marzahn-Hellersdorf gegr??ndet und gab im Mai 2005 sein erstes + umjubeltes Konzert im FEZ Wuhlheide. Das Orchester umfasst zur Zeit ca. 65 + jugendliche Musiker und soll auf die Gr????e eines ausgewachsenen + Sinfonieorchesters erweitert werden (80-100 Musiker). +

    + +

    + Als musikalischer Leiter konnte der Dirigent und Echo-Preistr??ger Jobst + Liebrecht gewonnen werden, der die Musikschule schon aus einer fr??heren + Zusammenarbeit anl??sslich der Kinderoper 'Pollicino' von Hans Werner Henze + kennt. Das Orchester probt w??chentlich. Neben den Tuttiproben finden au??erdem + ebenfalls w??chentlich Stimmsatzproben statt, die von Lehrkr??ften betreut werden. + Das gemeinsame Ziel ist der Aufbau eines leistungsstarken, lebendigen + Klangk??rpers, der die Jugendlichen und die Zuh??rer ganz neu und direkt f??r die + Orchestermusik begeistert und diese Musik in den sozialen Brennpunkt Marzahn- + Hellersdorf tr??gt. +

    + +

    + Im Jahr sind etwa 2-3 Konzertprogramme geplant, mit denen wir in Konzerts??len + auftreten. Das erste Konzert des Jugendsinfonieorchesters Marzahn-Hellersdorf + wurde von DeutschlandRadio Kultur aufgezeichnet und in einer Sendung mit dem + Titel „EINSTAND: Nicht nur auf der Strasse herumh??ngen” portr??tiert. + Wir wollen au??erdem vor Ort in Marzahn und Hellersdorf in die ??ffentlichkeit + gehen und spielen, um so f??r die Kultur zu werben und auch weitere Kinder und + Jugendliche f??r die Musik und f??rs Mitmachen zu gewinnen. Durch die Einrichtung + eines zus??tzlichen Vororchesters wird l??ngerfristig versucht, die Arbeit auf ein + breites Fundament zu stellen, eine Werkstatt, ein musikalisches Bauhaus zu + gr??nden. Wenn die Orchesterarbeit erfolgreich angelaufen ist, sollen auch + ??bergreifende Projekte (Theater, Tanz, Chor) stattfinden. +

    + +

    + Das Orchester will Musik von heute spielen in jedem Sinn, ob es sich um St??cke + aus der sinfonischen Tradition handelt oder um zeitgen??ssische Musik. Wir kennen + keine Ber??hrungs??ngste und sind neugierig auf Musik aller Art und m??chten diese + Neugierde mit unserem Publikum teilen. +

    +<% @title = 'Dirigent - Jobst Liebrecht' -%> +

    + <%= image_tag 'jobstliebrecht.jpg', :alt => 'Jobst Liebrecht', :title => 'Jobst Liebrecht', :class => 'pic_right' %> + Jobst Liebrecht studierte Dirigieren an der Musikhochschule in M??nchen und bei Peter E??tv??s. Sein spezielles Interesse + f??r neue Musik f??hrte schnell zur Zusammenarbeit mit renommierten Ensembles auf dem Gebiet wie dem Ensemble Modern, + Frankfurt, dem Klangforum-Ensemble, Wien, dem Ensemble K??ln sowie dem Ensemble United Berlin. Aufnahmen entstanden beim + WDR, beim DeutschlandRadio Berlin, beim BR und beim SFB. Er dirigierte u.a. das Rundfunk Sinfonieorchester Berlin, die + Duisburger Philharmoniker und das M??nchner Kammerorchester sowie in den Opernh??usern in Halle und Giessen. Tourneen im + Ausland f??hrten ihn nach Argentinien, Georgien, S??dkorea und in die USA. +

    + +

    + Zu den Ur- und Erstauff??hrungen, die er betreut hat, geh??ren die Opern 'Lunu' von Moritz Eggert, 'Gloria von Jaxtberg' von + HK Gruber sowie in Zusammenarbeit mit dem Regisseur Einar Schleef das Musiktheaterspiel 'Der Golem in Bayreuth' von Ulla + Berkewicz/Lesch Schmidt am Wiener Burgtheater. +

    + +

    + Jobst Liebrecht war mehrere Jahre lang Assistent von Hans Werner Henze und auch immer wieder p??dagogisch t??tig. Seine + Aufnahme von Henzes M??rchenoper 'Pollicino', die als CD bei Wergo erschienen ist, wurde mit dem ECHO-Preis 2004 in der + Sparte 'Klassik f??r Kinder' ausgezeichnet. +

    + +

    + Als Komponist ist Jobst Liebrecht mit Liedern, Kammermusik sowie B??hnenmusiken an die ??ffentlichkeit getreten. +

    +<% message, backtrace = session[:boom] -%> +<% @title = 'Fehler in Zeile %d' % [backtrace[/line\s+#(\d+)/,1]] -%> +
    +
    <%= h message %>
    +
    +<%= debug backtrace %> +<% cache :action_suffix => (action = params[:action]) do -%> +

    +Der Inhalt f??r die Aktion <%= h action.inspect %> fehlt noch. +

    +<% end -%> +<% @title = 'Schulferien Berlin' -%> +

    + Unser Orchester besteht zu einem sehr gro??en Teil aus Sch??lern und auch die + Musikschule, der die meisten von uns entstammen, hat in den Schulferien + geschlossen.
    + Deshalb finden innerhalb der Berliner Ferienzeiten keine Proben statt. +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Zeitraum200620072008
    + Winter + 30.01. - 03.02. + 05.02. - 10.02. + 04.02. - 09.02.
    + Ostern/Fr??hjahr + 10.04. - 21.04. + 02.04. - 13.04. + 17.03. - 28.03.
    + Himmelf./Pfingsten + 30.04. / 18.05. + 30.04. / 18.05. + 02.05.
    + Sommer + 06.07. - 19.08. + 12.07. - 25.08. + 17.07. - 30.08.
    + Herbst + 02.10. - 14.10. + 15.10. - 27.10. +
    + Weihnachten + 27.12. - 05.01.07 + 24.12. - 04.01.08 +
    +<% @title = 'Termine' -%> + + + + + + <%= tag 'meta', :'http-equiv' => 'content-language', :content => 'de' %> + <%= tag 'meta', :'http-equiv' => 'content-type', :content => 'text/html; charset=UTF-8' %> + + + + + + + + + + + + + JSO<%-if @title-%> - <%= h @title %><%- end -%> + <%= stylesheet_link_tag '/rcss/main' %> + <%#= stylesheet_link_tag 'main' %> + <%= javascript_include_tag 'nospam' %> + <%#= javascript_include_tag :defaults %> + + + + + + + + + + + + + + + + + +
    + <%= image_tag 'JSO-Logo.gif', :alt => 'JSO-Logo' %> + + +
    jugendsinfonieorchester
    +
    +<% if valid_user -%> +
      +
    • <%= link_to "Logout #{valid_user.name}", :controller => '/admin/admin', :action => :logout %>
      • +
    +<% end -%> +<% cache :controller => 'menu', :action => 'main_menu' do -%> + <%= render_component :controller => 'menu', :action => 'index' %> +<% end -%> +     		+<% unless @flash.keys.empty? -%> +
    + <%- for kind, msg in @flash -%> +
    <%= h msg %>
    + <%- end -%> +
    +<% end -%> +<%= content_tag 'h3', h(@title) if @title %> +<%= @content_for_layout %> +
    + +
    + powered by Ruby on Rails <%= Rails::Info.properties.value_for 'Rails version' %> [<%= h RAILS_ENV[/^./] %>] + <%= image_tag 'css.png', :alt => 'valid CSS', :title => 'valid Cascading Style Sheet', :style => 'display: inline; vertical-align: middle' %> + <%= image_tag 'xhtml11.png', :alt => 'valid XHTML 1.1', :title => 'valid eXtensible Hypertext Markup Language 1.1', :style => 'display: inline; vertical-align: middle' %> +
    +
    + + + + +<% @title = '??bersicht' -%> + +

    n??chste Probe

    + + <%= render :partial => 'proben/head' %> + <%= render :partial => 'proben/day', :object => @next_probe %> +
    +

    <%= link_to 'weitere Proben...', :controller => 'proben' %>

    + +

    n??chster Auftritt

    + + <%= render :partial => 'auftritte/head' %> + <%= render :partial => 'auftritte/day', :object => @next_auftritt %> +
    +

    <%= link_to 'mehr Auftritte...', :controller => 'auftritte' %>

    + +<% @title = 'Probenplan' %> + + + <%= render :partial => 'head' %> + <%= render :partial => 'day', :collection => @days %> +
    + +

    +Ort (wenn nicht anders angegeben): Schule am Pappelhof +

    + +<%= render_partial 'raum' %> +<% day, proben = *day -%> +<% + for probe in proben +-%> + + + + <%= colorize day.to_s(:dots) if day %> + <% if day and day.wday == 6 %>
    Samstag<% end %> + + + <%= colorize probe.time %> + + + <%= colorize(probe.place, 'Ort: ') + '
    ' unless probe.place.blank? %> + <%= colorize probe.program %> + <%= link_to 'E', :controller => 'admin/proben', :action => :edit, :id => probe %> + + + <%= h probe.instrumentation %> + + + +<% + day = nil + end +-%> + + Datum + Zeit + St??cke + Besetzung + +

    Probenr??ume

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    WerRaumAdresse
    StreicherSchule am Pappelhof
    (Raum Nr.)    		(Anschrifft Pappelhofschule)
    Blechbl??serMusikschule Marzahn
    (Raum Nr.)    		(Anschrifft Musikscule Marzahn)
    Holzbl??serSchule am Pappelhof
    (Raum Nr.)    		(Anschrifft Pappelhofschule)
    ...(Ort)
    (Raum Nr.)    		(Anschrifft)
    Added: external/Pygments-0.8.1/tests/examplefiles/example.xhtml ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/example.xhtml Thu Aug 9 17:43:13 2007 @@ -0,0 +1,376 @@ + + + + Error + + + +

    Error

    + + + +
    Path: #{path}
    +
    #{CGI.escapeHTML(error.to_s)}
    +
    + Reload this page. + Go to the referer or the home page. +
    +
    + + In file '#{error.hot_file}' #{error.hot_file =~ /\.xhtml$/ ? '(line numbering is aproximate due to template transformation)' : nil}: +

    + +
    #{line}
    + +
    #{line}
    + +
    +

    Stack Trace

    + + + +

    Request

    + + +

    Response

    + + +

    Session

    + + +

    + Powered by Nitro version #{Nitro::Version} + + + + + +

    Home > System > #{"%plural%".humanize} > Edit #{"%name%".humanize}

    + + Show editable + #{form_for @obj, :action => "#{base}/save", :cancel => "#{base}/list", :all => true} + + Show all + #{form_for @obj, :action => "#{base}/save", :cancel => "#{base}/list"} + +     +#{form_for(@%name%)} + + +

    #{"%plural%".humanize}

    +

    New #{"%name%".humanize}

    +
    + Search #{"%plural%".humanize}:   +
    + + + + + + + + + + + +
    #{obj.to_s}#{obj.update_time.stamp(:db)}editdel
    +     + + +

    Home > System > #{"%plural%".humanize}

    + New #{"%name%".humanize} +

    +

    + Search #{"%plural%".humanize}:   +
    +

    + + + + + + + + + + + +
    #(obj.to_s)#{obj.update_time.stamp(:db)}editdel
    +
    + #{@pager.navigation} +
    +     + + +

    Home > System > #{"%plural%".humanize} > New #{"%name%".humanize}

    + + Show editable + #{form_for @obj, :action => "#{base}/save", :cancel => "#{base}/list", :all => true, :enctype => "multipart/form-data"} + + Show all + #{form_for @obj, :action => "#{base}/save", :cancel => "#{base}/list", :enctype => "multipart/form-data"} + +     + + +

    Home > System > #{"%plural%".humanize} > Search for '#@query'

    +

    +

    + Search #{"%plural%".humanize}:   +
    +

    + +

    Search method is not implemented for this object

    + + + + + + + + + + + + +
    #(obj.to_s)#{obj.update_time.stamp(:db)}editdel
    +
    + #{@pager.navigation} +
    + +     + + +

    View %name%

    +

    List of %plural%

    + + #{@obj.to_yaml} + +     +Access denied + + +

    Home > System

    + +

    Og managed classes

    + + + + + + + + + + + + + + + + + +
    ClassCountCleanupProperties
    #{c.name}#{c.count}deletedestroy#{c.properties.values.join(', ')}
    + +

    System configuration

    + + + + + + + + + + + + + + + + +
    NameValueTypeDescription
    #{s.owner}.#{s.name}#{s.value.inspect}#{s.type}#{s.options[:doc]}
    +     + + + + + Test + + + + + + + +hello +Hello #{username} + +how do you feel? + +Here is your Token: #{token} + +
    + +

    Questions with Tags: #{@tags.join(" ")}

    + + 0 ?> + + Too many results for that Tag, please reduce the number by using one of the following Tags: + #{cloud_of(@qtags)} + +
    + +

    #{q.question}

    +

    + + #{excerpt} +

    +

    #{q.answers.size.to_i} answers

    + +
    +
    + #{@qpager.navigation} +
    + +
    +

    no question with this/these tag(s) found

    +

    Ask a question here.

    +
    + + + 0 ?> +

    Tips with Tags: #{@tags.join(" ")}

    + + Too many results for that Tag, please reduce the number by using one of the following Tags: + #{cloud_of(@ttags)} + +
    + +

    #{t.title}

    +

    + + #{excerpt} +

    + +
    +
    + #{@tpager.navigation} +
    + + + 0 ?> +

    Tutorials with Tags: #{@tags.join(" ")}

    + + Too many results for that Tag, please reduce the number by using one of the following Tags: + #{cloud_of(@tuttags)} + +
    + +

    #{t.title}

    +

    + + #{excerpt} +

    + +
    +
    + #{@tpager.navigation} +
    + + + + +
    + + + #{t.name} + +
    + +
    + + +     + + Added: external/Pygments-0.8.1/tests/examplefiles/example.xml ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/example.xml Thu Aug 9 17:43:13 2007 @@ -0,0 +1,1897 @@ + + + + + + abort + abs + abstract + accept + access + aliased + all + and + array + at + begin + body + constant + declare + delay + delta + digits + do + else + elsif + end + entry + exception + exit + for + function + generic + goto + in + is + limited + mod + new + not + null + of + or + others + out + package + pragma + private + procedure + protected + raise + range + rem + record + renames + requeue + return + reverse + separate + subtype + tagged + task + terminate + then + type + until + use + when + while + with + xor + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + BEGIN + END + if + else + while + do + for + in + continue + break + print + printf + getline + function + return + next + exit + + + ARGC + ARGV + CONVFMT + ENVIRON + FILENAME + FNR + FS + NF + NR + OFMT + OFS + ORS + RS + RSTART + RLENGTH + SUBSEP + + + gsub + index + length + match + split + sprintf + sub + substr + tolower + toupper + atan2 + cos + exp + int + log + rand + sin + sqrt + srand + close + fflush + system + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + break + case + else + esac + exit + export + for + function + in + return + select + then + until + while + . + done + do + elif + fi + if + + + + cp + date + echo + eval + dcop + dcopstart + dcopfind + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + break + case + continue + default + do + else + enum + extern + for + goto + if + inline + return + sizeof + struct + switch + typedef + union + while + + + auto + char + const + double + float + int + long + register + restrict + short + signed + static + unsigned + void + volatile + _Imaginary + _Complex + _Bool + + + FIXME + TODO + ### + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + aaa + access-list + address + alias + arp + async-bootp + banner + boot + bridge + buffers + busy-message + call-history-mib + cdp + chat-script + class-map + clock + cns + config-register + controller + crypto + default + default-value + dialer + dialer-list + dnsix-dmdp + dnsix-nat + downward-compatible-config + enable + end + exception + exit + file + frame-relay + help + hostname + interface + ip + isdn + isdn-mib + kerberos + key + line + logging + login-string + map-class + map-list + memory-size + menu + modemcap + multilink + netbios + no + ntp + partition + policy-map + priority-list + privilege + process-max-time + prompt + queue-list + resume-string + rlogin + rmon + route-map + router + rtr + scheduler + service + snmp-server + sntp + stackmaker + state-machine + subscriber-policy + tacacs-server + template + terminal-queue + tftp-server + time-range + username + virtual-profile + virtual-template + vpdn + vpdn-group + x25 + x29 + + + accounting + accounting-list + accounting-threshold + accounting-transits + address-pool + as-path + audit + auth-proxy + authentication + authorization + bgp-community + bootp + cef + classless + community-list + default-gateway + default-network + dhcp + dhcp-server + domain-list + domain-lookup + domain-name + dvmrp + exec-callback + extcommunity-list + finger + flow-aggregation + flow-cache + flow-export + forward-protocol + ftp + gratuitous-arps + host + host-routing + hp-host + http + icmp + inspect + local + mrm + mroute + msdp + multicast + multicast-routing + name-server + nat + new-model + ospf + password + password-encryption + pgm + pim + port-map + prefix-list + radius + rcmd + reflexive-list + route + routing + rsvp + rtcp + sap + sdr + security + source-route + subnet-zero + tacacs + tcp + tcp-small-servers + telnet + tftp + timestamps + udp-small-servers + vrf + wccp + + + accounting + accounting-list + accounting-threshold + accounting-transits + address-pool + as-path + audit + auth-proxy + authentication + authorization + bgp-community + bootp + cef + classless + community-list + default-gateway + default-network + dhcp + dhcp-server + domain-list + domain-lookup + domain-name + dvmrp + exec-callback + extcommunity-list + finger + flow-aggregation + flow-cache + flow-export + forward-protocol + ftp + gratuitous-arps + host + host-routing + hp-host + http + icmp + inspect + local + mrm + mroute + msdp + multicast + multicast-routing + name-server + nat + new-model + ospf + password + password-encryption + pgm + pim + port-map + prefix-list + radius + rcmd + reflexive-list + route + routing + rsvp + rtcp + sap + sdr + security + source-route + subnet-zero + tacacs + tcp + tcp-small-servers + telnet + tftp + timestamps + udp-small-servers + vrf + wccp + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + if + else + for + in + while + do + continue + break + with + try + catch + switch + case + new + var + function + return + this + delete + true + false + void + throw + typeof + const + default + + + + + + Anchor + Applet + Area + Array + Boolean + Button + Checkbox + Date + Document + Event + FileUpload + Form + Frame + Function + Hidden + History + Image + Layer + Linke + Location + Math + Navigator + Number + Object + Option + Password + Radio + RegExp + Reset + Screen + Select + String + Submit + Text + Textarea + Window + + + + + + abs + acos + alert + anchor + apply + asin + atan + atan2 + back + blur + call + captureEvents + ceil + charAt + charCodeAt + clearInterval + clearTimeout + click + close + compile + concat + confirm + cos + disableExternalCapture + enableExternalCapture + eval + exec + exp + find + floor + focus + forward + fromCharCode + getDate + getDay + getFullYear + getHours + getMilliseconds + getMinutes + getMonth + getSeconds + getSelection + getTime + getTimezoneOffset + getUTCDate + getUTCDay + getUTCFullYear + getUTCHours + getUTCMilliseconds + getUTCMinutes + getUTCMonth + getUTCSeconds + go + handleEvent + home + indexOf + javaEnabled + join + lastIndexOf + link + load + log + match + max + min + moveAbove + moveBelow + moveBy + moveTo + moveToAbsolute + open + parse + plugins.refresh + pop + pow + preference + print + prompt + push + random + releaseEvents + reload + replace + reset + resizeBy + resizeTo + reverse + round + routeEvent + scrollBy + scrollTo + search + select + setDate + setFullYear + setHours + setInterval + setMilliseconds + setMinutes + setMonth + setSeconds + setTime + setTimeout + setUTCDate + setUTCFullYear + setUTCHours + setUTCMilliseconds + setUTCMinutes + setUTCMonth + setUTCSeconds + shift + sin + slice + sort + splice + split + sqrt + stop + String formatting + submit + substr + substring + taintEnabled + tan + test + toLocaleString + toLowerCase + toSource + toString + toUpperCase + toUTCString + unshift + unwatch + UTC + valueOf + watch + write + writeln + + + + + + break + case + catch + continue + default + do + else + for + function + if + in + return + switch + try + var + while + + + + + + Abs + ACos + ArrayAppend + ArrayAvg + ArrayClear + ArrayDeleteAt + ArrayInsertAt + ArrayIsEmpty + ArrayLen + ArrayMax + ArrayMin + ArrayNew + ArrayPrepend + ArrayResize + ArraySet + ArraySort + ArraySum + ArraySwap + ArrayToList + Asc + ASin + Atn + BitAnd + BitMaskClear + BitMaskRead + BitMaskSet + BitNot + BitOr + BitSHLN + BitSHRN + BitXor + Ceiling + Chr + CJustify + Compare + CompareNoCase + Cos + CreateDate + CreateDateTime + CreateObject + CreateODBCDate + CreateODBCDateTime + CreateODBCTime + CreateTime + CreateTimeSpan + CreateUUID + DateAdd + DateCompare + DateConvert + DateDiff + DateFormat + DatePart + Day + DayOfWeek + DayOfWeekAsString + DayOfYear + DaysInMonth + DaysInYear + DE + DecimalFormat + DecrementValue + Decrypt + DeleteClientVariable + DirectoryExists + DollarFormat + Duplicate + Encrypt + Evaluate + Exp + ExpandPath + FileExists + Find + FindNoCase + FindOneOf + FirstDayOfMonth + Fix + FormatBaseN + GetAuthUser + GetBaseTagData + GetBaseTagList + GetBaseTemplatePath + GetClientVariablesList + GetCurrentTemplatePath + GetDirectoryFromPath + GetException + GetFileFromPath + GetFunctionList + GetHttpRequestData + GetHttpTimeString + GetK2ServerDocCount + GetK2ServerDocCountLimit + GetLocale + GetMetaData + GetMetricData + GetPageContext + GetProfileSections + GetProfileString + GetServiceSettings + GetTempDirectory + GetTempFile + GetTemplatePath + GetTickCount + GetTimeZoneInfo + GetToken + Hash + Hour + HTMLCodeFormat + HTMLEditFormat + IIf + IncrementValue + InputBaseN + Insert + Int + IsArray + IsBinary + IsBoolean + IsCustomFunction + IsDate + IsDebugMode + IsDefined + IsK2ServerABroker + IsK2ServerDocCountExceeded + IsK2ServerOnline + IsLeapYear + IsNumeric + IsNumericDate + IsObject + IsQuery + IsSimpleValue + IsStruct + IsUserInRole + IsWDDX + IsXmlDoc + IsXmlElement + IsXmlRoot + JavaCast + JSStringFormat + LCase + Left + Len + ListAppend + ListChangeDelims + ListContains + ListContainsNoCase + ListDeleteAt + ListFind + ListFindNoCase + ListFirst + ListGetAt + ListInsertAt + ListLast + ListLen + ListPrepend + ListQualify + ListRest + ListSetAt + ListSort + ListToArray + ListValueCount + ListValueCountNoCase + LJustify + Log + Log10 + LSCurrencyFormat + LSDateFormat + LSEuroCurrencyFormat + LSIsCurrency + LSIsDate + LSIsNumeric + LSNumberFormat + LSParseCurrency + LSParseDateTime + LSParseEuroCurrency + LSParseNumber + LSTimeFormat + LTrim + Max + Mid + Min + Minute + Month + MonthAsString + Now + NumberFormat + ParagraphFormat + ParameterExists + ParseDateTime + Pi + PreserveSingleQuotes + Quarter + QueryAddColumn + QueryAddRow + QueryNew + QuerySetCell + QuotedValueList + Rand + Randomize + RandRange + REFind + REFindNoCase + RemoveChars + RepeatString + Replace + ReplaceList + ReplaceNoCase + REReplace + REReplaceNoCase + Reverse + Right + RJustify + Round + RTrim + Second + SetEncoding + SetLocale + SetProfileString + SetVariable + Sgn + Sin + SpanExcluding + SpanIncluding + Sqr + StripCR + StructAppend + StructClear + StructCopy + StructCount + StructDelete + StructFind + StructFindKey + StructFindValue + StructGet + StructInsert + StructIsEmpty + StructKeyArray + StructKeyExists + StructKeyList + StructNew + StructSort + StructUpdate + Tan + TimeFormat + ToBase64 + ToBinary + ToString + Trim + UCase + URLDecode + URLEncodedFormat + URLSessionFormat + Val + ValueList + Week + WriteOutput + XmlChildPos + XmlElemNew + XmlFormat + XmlNew + XmlParse + XmlSearch + XmlTransform + Year + YesNoFormat + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + BEGIN + BY + CASE + CLOSE + CONST + DO + ELSE + ELSIF + END + FOR + IF + IMPORT + LOOP + MODULE + NEW + OF + OUT + PROCEDURE + REPEAT + THEN + TO + TYPE + UNTIL + VAR + WHILE + WITH + + + ASSERT + EXIT + HALT + RETURN + + + ANYPTR + ANYREC + ARRAY + BOOLEAN + SHORTCHAR + CHAR + BYTE + SHORTINT + INTEGER + LONGINT + POINTER + RECORD + SHORTREAL + REAL + SET + + + ABSTRACT + EMPTY + EXTENSIBLE + LIMITED + + + ABS + ASH + BITS + CAP + CHR + DEC + ENTIER + EXCL + INC + INCL + LEN + LONG + MAX + MIN + ODD + ORD + SHORT + SIZE + + + FALSE + INF + NIL + TRUE + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Added: external/Pygments-0.8.1/tests/examplefiles/format.ml ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/format.ml Thu Aug 9 17:43:13 2007 @@ -0,0 +1,1213 @@ +(***********************************************************************) +(* *) +(* Objective Caml *) +(* *) +(* Pierre Weis, projet Cristal, INRIA Rocquencourt *) +(* *) +(* Copyright 1996 Institut National de Recherche en Informatique et *) +(* en Automatique. All rights reserved. This file is distributed *) +(* under the terms of the GNU Library General Public License, with *) +(* the special exception on linking described in file ../LICENSE. *) +(* *) +(***********************************************************************) + +(* $Id: format.ml,v 1.65 2005/09/26 10:13:08 weis Exp $ *) + +(************************************************************** + + Data structures definitions. + + **************************************************************) + +type size;; + +external size_of_int : int -> size = "%identity";; +external int_of_size : size -> int = "%identity";; + +(* Tokens are one of the following : *) + +type pp_token = +| Pp_text of string (* normal text *) +| Pp_break of int * int (* complete break *) +| Pp_tbreak of int * int (* go to next tabulation *) +| Pp_stab (* set a tabulation *) +| Pp_begin of int * block_type (* beginning of a block *) +| Pp_end (* end of a block *) +| Pp_tbegin of tblock (* beginning of a tabulation block *) +| Pp_tend (* end of a tabulation block *) +| Pp_newline (* to force a newline inside a block *) +| Pp_if_newline (* to do something only if this very + line has been broken *) +| Pp_open_tag of string (* opening a tag name *) +| Pp_close_tag (* closing the most recently opened tag *) + +and tag = string + +and block_type = +| Pp_hbox (* Horizontal block no line breaking *) +| Pp_vbox (* Vertical block each break leads to a new line *) +| Pp_hvbox (* Horizontal-vertical block: same as vbox, except if this block + is small enough to fit on a single line *) +| Pp_hovbox (* Horizontal or Vertical block: breaks lead to new line + only when necessary to print the content of the block *) +| Pp_box (* Horizontal or Indent block: breaks lead to new line + only when necessary to print the content of the block, or + when it leads to a new indentation of the current line *) +| Pp_fits (* Internal usage: when a block fits on a single line *) + +and tblock = Pp_tbox of int list ref (* Tabulation box *) +;; + +(* The Queue: + contains all formatting elements. + elements are tuples (size, token, length), where + size is set when the size of the block is known + len is the declared length of the token. *) +type pp_queue_elem = { + mutable elem_size : size; token : pp_token; length : int +};; + +(* Scan stack: + each element is (left_total, queue element) where left_total + is the value of pp_left_total when the element has been enqueued. *) +type pp_scan_elem = Scan_elem of int * pp_queue_elem;; + +(* Formatting stack: + used to break the lines while printing tokens. + The formatting stack contains the description of + the currently active blocks. *) +type pp_format_elem = Format_elem of block_type * int;; + +(* General purpose queues, used in the formatter. *) +type 'a queue_elem = | Nil | Cons of 'a queue_cell +and 'a queue_cell = {mutable head : 'a; mutable tail : 'a queue_elem};; + +type 'a queue = { + mutable insert : 'a queue_elem; + mutable body : 'a queue_elem +};; + +(* The formatter specific tag handling functions. *) +type formatter_tag_functions = { + mark_open_tag : tag -> string; + mark_close_tag : tag -> string; + print_open_tag : tag -> unit; + print_close_tag : tag -> unit; + +};; + +(* A formatter with all its machinery. *) +type formatter = { + mutable pp_scan_stack : pp_scan_elem list; + mutable pp_format_stack : pp_format_elem list; + mutable pp_tbox_stack : tblock list; + mutable pp_tag_stack : tag list; + mutable pp_mark_stack : tag list; + (* Global variables: default initialization is + set_margin 78 + set_min_space_left 0. *) + (* Value of right margin. *) + mutable pp_margin : int; + (* Minimal space left before margin, when opening a block. *) + mutable pp_min_space_left : int; + (* Maximum value of indentation: + no blocks can be opened further. *) + mutable pp_max_indent : int; + (* Space remaining on the current line. *) + mutable pp_space_left : int; + (* Current value of indentation. *) + mutable pp_current_indent : int; + (* True when the line has been broken by the pretty-printer. *) + mutable pp_is_new_line : bool; + (* Total width of tokens already printed. *) + mutable pp_left_total : int; + (* Total width of tokens ever put in queue. *) + mutable pp_right_total : int; + (* Current number of opened blocks. *) + mutable pp_curr_depth : int; + (* Maximum number of blocks which can be simultaneously opened. *) + mutable pp_max_boxes : int; + (* Ellipsis string. *) + mutable pp_ellipsis : string; + (* Output function. *) + mutable pp_output_function : string -> int -> int -> unit; + (* Flushing function. *) + mutable pp_flush_function : unit -> unit; + (* Output of new lines. *) + mutable pp_output_newline : unit -> unit; + (* Output of indentation spaces. *) + mutable pp_output_spaces : int -> unit; + (* Are tags printed ? *) + mutable pp_print_tags : bool; + (* Are tags marked ? *) + mutable pp_mark_tags : bool; + (* Find opening and closing markers of tags. *) + mutable pp_mark_open_tag : tag -> string; + mutable pp_mark_close_tag : tag -> string; + mutable pp_print_open_tag : tag -> unit; + mutable pp_print_close_tag : tag -> unit; + (* The pretty-printer queue. *) + mutable pp_queue : pp_queue_elem queue +};; + +(************************************************************** + + Auxilliaries and basic functions. + + **************************************************************) + + +(* Queues auxilliaries. *) +let make_queue () = {insert = Nil; body = Nil};; + +let clear_queue q = q.insert <- Nil; q.body <- Nil;; + +let add_queue x q = + let c = Cons {head = x; tail = Nil} in + match q with + | {insert = Cons cell} -> q.insert <- c; cell.tail <- c + (* Invariant: when insert is Nil body should be Nil. *) + | _ -> q.insert <- c; q.body <- c;; + +exception Empty_queue;; + +let peek_queue = function + | {body = Cons {head = x}} -> x + | _ -> raise Empty_queue;; + +let take_queue = function + | {body = Cons {head = x; tail = tl}} as q -> + q.body <- tl; + if tl = Nil then q.insert <- Nil; (* Maintain the invariant. *) + x + | _ -> raise Empty_queue;; + +(* Enter a token in the pretty-printer queue. *) +let pp_enqueue state ({length = len} as token) = + state.pp_right_total <- state.pp_right_total + len; + add_queue token state.pp_queue;; + +let pp_clear_queue state = + state.pp_left_total <- 1; state.pp_right_total <- 1; + clear_queue state.pp_queue;; + +(* Pp_infinity: large value for default tokens size. + + Pp_infinity is documented as being greater than 1e10; to avoid + confusion about the word ``greater'', we choose pp_infinity greater + than 1e10 + 1; for correct handling of tests in the algorithm, + pp_infinity must be even one more than 1e10 + 1; let's stand on the + safe side by choosing 1.e10+10. + + Pp_infinity could probably be 1073741823 that is 2^30 - 1, that is + the minimal upper bound for integers; now that max_int is defined, + this limit could also be defined as max_int - 1. + + However, before setting pp_infinity to something around max_int, we + must carefully double-check all the integer arithmetic operations + that involve pp_infinity, since any overflow would wreck havoc the + pretty-printing algorithm's invariants. Given that this arithmetic + correctness check is difficult and error prone and given that 1e10 + + 1 is in practice large enough, there is no need to attempt to set + pp_infinity to the theoretically maximum limit. Is it not worth the + burden ! *) + +let pp_infinity = 1000000010;; + +(* Output functions for the formatter. *) +let pp_output_string state s = state.pp_output_function s 0 (String.length s) +and pp_output_newline state = state.pp_output_newline ();; + +let pp_display_blanks state n = state.pp_output_spaces n;; + +(* To format a break, indenting a new line. *) +let break_new_line state offset width = + pp_output_newline state; + state.pp_is_new_line <- true; + let indent = state.pp_margin - width + offset in + (* Don't indent more than pp_max_indent. *) + let real_indent = min state.pp_max_indent indent in + state.pp_current_indent <- real_indent; + state.pp_space_left <- state.pp_margin - state.pp_current_indent; + pp_display_blanks state state.pp_current_indent;; + +(* To force a line break inside a block: no offset is added. *) +let break_line state width = break_new_line state 0 width;; + +(* To format a break that fits on the current line. *) +let break_same_line state width = + state.pp_space_left <- state.pp_space_left - width; + pp_display_blanks state width;; + +(* To indent no more than pp_max_indent, if one tries to open a block + beyond pp_max_indent, then the block is rejected on the left + by simulating a break. *) +let pp_force_break_line state = + match state.pp_format_stack with + | Format_elem (bl_ty, width) :: _ -> + if width > state.pp_space_left then + (match bl_ty with + | Pp_fits -> () | Pp_hbox -> () | _ -> break_line state width) + | _ -> pp_output_newline state;; + +(* To skip a token, if the previous line has been broken. *) +let pp_skip_token state = + (* When calling pp_skip_token the queue cannot be empty. *) + match take_queue state.pp_queue with + {elem_size = size; length = len} -> + state.pp_left_total <- state.pp_left_total - len; + state.pp_space_left <- state.pp_space_left + int_of_size size;; + +(************************************************************** + + The main pretting printing functions. + + **************************************************************) + +(* To format a token. *) +let format_pp_token state size = function + + | Pp_text s -> + state.pp_space_left <- state.pp_space_left - size; + pp_output_string state s; + state.pp_is_new_line <- false + + | Pp_begin (off, ty) -> + let insertion_point = state.pp_margin - state.pp_space_left in + if insertion_point > state.pp_max_indent then + (* can't open a block right there. *) + begin pp_force_break_line state end; + let offset = state.pp_space_left - off in + let bl_type = + begin match ty with + | Pp_vbox -> Pp_vbox + | _ -> if size > state.pp_space_left then ty else Pp_fits + end in + state.pp_format_stack <- + Format_elem (bl_type, offset) :: state.pp_format_stack + + | Pp_end -> + begin match state.pp_format_stack with + | x :: (y :: l as ls) -> state.pp_format_stack <- ls + | _ -> () (* No more block to close. *) + end + + | Pp_tbegin (Pp_tbox _ as tbox) -> + state.pp_tbox_stack <- tbox :: state.pp_tbox_stack + + | Pp_tend -> + begin match state.pp_tbox_stack with + | x :: ls -> state.pp_tbox_stack <- ls + | _ -> () (* No more tabulation block to close. *) + end + + | Pp_stab -> + begin match state.pp_tbox_stack with + | Pp_tbox tabs :: _ -> + let rec add_tab n = function + | [] -> [n] + | x :: l as ls -> if n < x then n :: ls else x :: add_tab n l in + tabs := add_tab (state.pp_margin - state.pp_space_left) !tabs + | _ -> () (* No opened tabulation block. *) + end + + | Pp_tbreak (n, off) -> + let insertion_point = state.pp_margin - state.pp_space_left in + begin match state.pp_tbox_stack with + | Pp_tbox tabs :: _ -> + let rec find n = function + | x :: l -> if x >= n then x else find n l + | [] -> raise Not_found in + let tab = + match !tabs with + | x :: l -> + begin try find insertion_point !tabs with Not_found -> x end + | _ -> insertion_point in + let offset = tab - insertion_point in + if offset >= 0 then break_same_line state (offset + n) else + break_new_line state (tab + off) state.pp_margin + | _ -> () (* No opened tabulation block. *) + end + + | Pp_newline -> + begin match state.pp_format_stack with + | Format_elem (_, width) :: _ -> break_line state width + | _ -> pp_output_newline state + end + + | Pp_if_newline -> + if state.pp_current_indent != state.pp_margin - state.pp_space_left + then pp_skip_token state + + | Pp_break (n, off) -> + begin match state.pp_format_stack with + | Format_elem (ty, width) :: _ -> + begin match ty with + | Pp_hovbox -> + if size > state.pp_space_left + then break_new_line state off width + else break_same_line state n + | Pp_box -> + (* Have the line just been broken here ? *) + if state.pp_is_new_line then break_same_line state n else + if size > state.pp_space_left + then break_new_line state off width else + (* break the line here leads to new indentation ? *) + if state.pp_current_indent > state.pp_margin - width + off + then break_new_line state off width + else break_same_line state n + | Pp_hvbox -> break_new_line state off width + | Pp_fits -> break_same_line state n + | Pp_vbox -> break_new_line state off width + | Pp_hbox -> break_same_line state n + end + | _ -> () (* No opened block. *) + end + + | Pp_open_tag tag_name -> + let marker = state.pp_mark_open_tag tag_name in + pp_output_string state marker; + state.pp_mark_stack <- tag_name :: state.pp_mark_stack + + | Pp_close_tag -> + begin match state.pp_mark_stack with + | tag_name :: tags -> + let marker = state.pp_mark_close_tag tag_name in + pp_output_string state marker; + state.pp_mark_stack <- tags + | _ -> () (* No more tag to close. *) + end;; + +(* Print if token size is known or printing is delayed. + Size is known when not negative. + Printing is delayed when the text waiting in the queue requires + more room to format than exists on the current line. *) +let rec advance_left state = + try + match peek_queue state.pp_queue with + {elem_size = size; token = tok; length = len} -> + let size = int_of_size size in + if not + (size < 0 && + (state.pp_right_total - state.pp_left_total < state.pp_space_left)) + then begin + ignore(take_queue state.pp_queue); + format_pp_token state (if size < 0 then pp_infinity else size) tok; + state.pp_left_total <- len + state.pp_left_total; + advance_left state + end + with Empty_queue -> ();; + +let enqueue_advance state tok = pp_enqueue state tok; advance_left state;; + +(* To enqueue a string : try to advance. *) +let make_queue_elem size tok len = + {elem_size = size; token = tok; length = len};; + +let enqueue_string_as state size s = + let len = int_of_size size in + enqueue_advance state (make_queue_elem size (Pp_text s) len);; + +let enqueue_string state s = + let len = String.length s in + enqueue_string_as state (size_of_int len) s;; + +(* Routines for scan stack + determine sizes of blocks. *) + +(* The scan_stack is never empty. *) +let scan_stack_bottom = + let q_elem = make_queue_elem (size_of_int (-1)) (Pp_text "") 0 in + [Scan_elem (-1, q_elem)];; + +(* Set size of blocks on scan stack: + if ty = true then size of break is set else size of block is set; + in each case pp_scan_stack is popped. *) +let clear_scan_stack state = state.pp_scan_stack <- scan_stack_bottom;; + +(* Pattern matching on scan stack is exhaustive, + since scan_stack is never empty. + Pattern matching on token in scan stack is also exhaustive, + since scan_push is used on breaks and opening of boxes. *) +let set_size state ty = + match state.pp_scan_stack with + | Scan_elem + (left_tot, + ({elem_size = size; token = tok} as queue_elem)) :: t -> + let size = int_of_size size in + (* test if scan stack contains any data that is not obsolete. *) + if left_tot < state.pp_left_total then clear_scan_stack state else + begin match tok with + | Pp_break (_, _) | Pp_tbreak (_, _) -> + if ty then + begin + queue_elem.elem_size <- size_of_int (state.pp_right_total + size); + state.pp_scan_stack <- t + end + | Pp_begin (_, _) -> + if not ty then + begin + queue_elem.elem_size <- size_of_int (state.pp_right_total + size); + state.pp_scan_stack <- t + end + | _ -> () (* scan_push is only used for breaks and boxes. *) + end + | _ -> () (* scan_stack is never empty. *);; + +(* Push a token on scan stack. If b is true set_size is called. *) +let scan_push state b tok = + pp_enqueue state tok; + if b then set_size state true; + state.pp_scan_stack <- + Scan_elem (state.pp_right_total, tok) :: state.pp_scan_stack;; + +(* To open a new block : + the user may set the depth bound pp_max_boxes + any text nested deeper is printed as the ellipsis string. *) +let pp_open_box_gen state indent br_ty = + state.pp_curr_depth <- state.pp_curr_depth + 1; + if state.pp_curr_depth < state.pp_max_boxes then + let elem = + make_queue_elem + (size_of_int (- state.pp_right_total)) + (Pp_begin (indent, br_ty)) + 0 in + scan_push state false elem else + if state.pp_curr_depth = state.pp_max_boxes + then enqueue_string state state.pp_ellipsis;; + +(* The box which is always opened. *) +let pp_open_sys_box state = pp_open_box_gen state 0 Pp_hovbox;; + +(* Close a block, setting sizes of its subblocks. *) +let pp_close_box state () = + if state.pp_curr_depth > 1 then + begin + if state.pp_curr_depth < state.pp_max_boxes then + begin + pp_enqueue state + {elem_size = size_of_int 0; token = Pp_end; length = 0}; + set_size state true; set_size state false + end; + state.pp_curr_depth <- state.pp_curr_depth - 1; + end;; + +(* Open a tag, pushing it on the tag stack. *) +let pp_open_tag state tag_name = + if state.pp_print_tags then begin + state.pp_tag_stack <- tag_name :: state.pp_tag_stack; + state.pp_print_open_tag tag_name end; + if state.pp_mark_tags then + pp_enqueue state + {elem_size = size_of_int 0; token = Pp_open_tag tag_name; length = 0};; + +(* Close a tag, popping it from the tag stack. *) +let pp_close_tag state () = + if state.pp_mark_tags then + pp_enqueue state + {elem_size = size_of_int 0; token = Pp_close_tag; length = 0}; + if state.pp_print_tags then + begin match state.pp_tag_stack with + | tag_name :: tags -> + state.pp_print_close_tag tag_name; + state.pp_tag_stack <- tags + | _ -> () (* No more tag to close. *) + end;; + +let pp_set_print_tags state b = state.pp_print_tags <- b;; +let pp_set_mark_tags state b = state.pp_mark_tags <- b;; +let pp_get_print_tags state () = state.pp_print_tags;; +let pp_get_mark_tags state () = state.pp_mark_tags;; +let pp_set_tags state b = pp_set_print_tags state b; pp_set_mark_tags state b;; + +let pp_get_formatter_tag_functions state () = { + mark_open_tag = state.pp_mark_open_tag; + mark_close_tag = state.pp_mark_close_tag; + print_open_tag = state.pp_print_open_tag; + print_close_tag = state.pp_print_close_tag; +};; + +let pp_set_formatter_tag_functions state { + mark_open_tag = mot; + mark_close_tag = mct; + print_open_tag = pot; + print_close_tag = pct; + } = + state.pp_mark_open_tag <- mot; + state.pp_mark_close_tag <- mct; + state.pp_print_open_tag <- pot; + state.pp_print_close_tag <- pct;; + +(* Initialize pretty-printer. *) +let pp_rinit state = + pp_clear_queue state; + clear_scan_stack state; + state.pp_format_stack <- []; + state.pp_tbox_stack <- []; + state.pp_tag_stack <- []; + state.pp_mark_stack <- []; + state.pp_current_indent <- 0; + state.pp_curr_depth <- 0; + state.pp_space_left <- state.pp_margin; + pp_open_sys_box state;; + +(* Flushing pretty-printer queue. *) +let pp_flush_queue state b = + while state.pp_curr_depth > 1 do + pp_close_box state () + done; + state.pp_right_total <- pp_infinity; + advance_left state; + if b then pp_output_newline state; + pp_rinit state;; + +(************************************************************** + + Procedures to format objects, and use boxes + + **************************************************************) + +(* To format a string. *) +let pp_print_as_size state size s = + if state.pp_curr_depth < state.pp_max_boxes + then enqueue_string_as state size s;; + +let pp_print_as state isize s = + pp_print_as_size state (size_of_int isize) s;; + +let pp_print_string state s = + pp_print_as state (String.length s) s;; + +(* To format an integer. *) +let pp_print_int state i = pp_print_string state (string_of_int i);; + +(* To format a float. *) +let pp_print_float state f = pp_print_string state (string_of_float f);; + +(* To format a boolean. *) +let pp_print_bool state b = pp_print_string state (string_of_bool b);; + +(* To format a char. *) +let pp_print_char state c = + let s = String.create 1 in + s.[0] <- c; + pp_print_as state 1 s;; + +(* Opening boxes. *) +let pp_open_hbox state () = pp_open_box_gen state 0 Pp_hbox +and pp_open_vbox state indent = pp_open_box_gen state indent Pp_vbox + +and pp_open_hvbox state indent = pp_open_box_gen state indent Pp_hvbox +and pp_open_hovbox state indent = pp_open_box_gen state indent Pp_hovbox +and pp_open_box state indent = pp_open_box_gen state indent Pp_box;; + +(* Print a new line after printing all queued text + (same for print_flush but without a newline). *) +let pp_print_newline state () = + pp_flush_queue state true; state.pp_flush_function () +and pp_print_flush state () = + pp_flush_queue state false; state.pp_flush_function ();; + +(* To get a newline when one does not want to close the current block. *) +let pp_force_newline state () = + if state.pp_curr_depth < state.pp_max_boxes then + enqueue_advance state (make_queue_elem (size_of_int 0) Pp_newline 0);; + +(* To format something if the line has just been broken. *) +let pp_print_if_newline state () = + if state.pp_curr_depth < state.pp_max_boxes then + enqueue_advance state (make_queue_elem (size_of_int 0) Pp_if_newline 0);; + +(* Breaks: indicate where a block may be broken. + If line is broken then offset is added to the indentation of the current + block else (the value of) width blanks are printed. + To do (?) : add a maximum width and offset value. *) +let pp_print_break state width offset = + if state.pp_curr_depth < state.pp_max_boxes then + let elem = + make_queue_elem + (size_of_int (- state.pp_right_total)) + (Pp_break (width, offset)) + width in + scan_push state true elem;; + +let pp_print_space state () = pp_print_break state 1 0 +and pp_print_cut state () = pp_print_break state 0 0;; + +(* Tabulation boxes. *) +let pp_open_tbox state () = + state.pp_curr_depth <- state.pp_curr_depth + 1; + if state.pp_curr_depth < state.pp_max_boxes then + let elem = + make_queue_elem (size_of_int 0) (Pp_tbegin (Pp_tbox (ref []))) 0 in + enqueue_advance state elem;; + +(* Close a tabulation block. *) +let pp_close_tbox state () = + if state.pp_curr_depth > 1 then begin + if state.pp_curr_depth < state.pp_max_boxes then + let elem = make_queue_elem (size_of_int 0) Pp_tend 0 in + enqueue_advance state elem; + state.pp_curr_depth <- state.pp_curr_depth - 1 end;; + +(* Print a tabulation break. *) +let pp_print_tbreak state width offset = + if state.pp_curr_depth < state.pp_max_boxes then + let elem = + make_queue_elem + (size_of_int (- state.pp_right_total)) + (Pp_tbreak (width, offset)) + width in + scan_push state true elem;; + +let pp_print_tab state () = pp_print_tbreak state 0 0;; + +let pp_set_tab state () = + if state.pp_curr_depth < state.pp_max_boxes then + let elem = + make_queue_elem (size_of_int 0) Pp_stab 0 in + enqueue_advance state elem;; + +(************************************************************** + + Procedures to control the pretty-printers + + **************************************************************) + +(* Fit max_boxes. *) +let pp_set_max_boxes state n = if n > 1 then state.pp_max_boxes <- n;; + +(* To know the current maximum number of boxes allowed. *) +let pp_get_max_boxes state () = state.pp_max_boxes;; + +let pp_over_max_boxes state () = state.pp_curr_depth = state.pp_max_boxes;; + +(* Ellipsis. *) +let pp_set_ellipsis_text state s = state.pp_ellipsis <- s +and pp_get_ellipsis_text state () = state.pp_ellipsis;; + +(* To set the margin of pretty-printer. *) +let pp_limit n = + if n < pp_infinity then n else pred pp_infinity;; + +let pp_set_min_space_left state n = + if n >= 1 then + let n = pp_limit n in + state.pp_min_space_left <- n; + state.pp_max_indent <- state.pp_margin - state.pp_min_space_left; + pp_rinit state;; + +(* Initially, we have : + pp_max_indent = pp_margin - pp_min_space_left, and + pp_space_left = pp_margin. *) +let pp_set_max_indent state n = + pp_set_min_space_left state (state.pp_margin - n);; +let pp_get_max_indent state () = state.pp_max_indent;; + +let pp_set_margin state n = + if n >= 1 then + let n = pp_limit n in + state.pp_margin <- n; + let new_max_indent = + (* Try to maintain max_indent to its actual value. *) + if state.pp_max_indent <= state.pp_margin + then state.pp_max_indent else + (* If possible maintain pp_min_space_left to its actual value, + if this leads to a too small max_indent, take half of the + new margin, if it is greater than 1. *) + max (max (state.pp_margin - state.pp_min_space_left) + (state.pp_margin / 2)) 1 in + (* Rebuild invariants. *) + pp_set_max_indent state new_max_indent;; + +let pp_get_margin state () = state.pp_margin;; + +let pp_set_formatter_output_functions state f g = + state.pp_output_function <- f; state.pp_flush_function <- g;; +let pp_get_formatter_output_functions state () = + (state.pp_output_function, state.pp_flush_function);; + +let pp_set_all_formatter_output_functions state + ~out:f ~flush:g ~newline:h ~spaces:i = + pp_set_formatter_output_functions state f g; + state.pp_output_newline <- (function () -> h ()); + state.pp_output_spaces <- (function n -> i n);; +let pp_get_all_formatter_output_functions state () = + (state.pp_output_function, state.pp_flush_function, + state.pp_output_newline, state.pp_output_spaces);; + +let pp_set_formatter_out_channel state os = + state.pp_output_function <- output os; + state.pp_flush_function <- (fun () -> flush os);; + +(************************************************************** + + Creation of specific formatters + + **************************************************************) + +let default_pp_mark_open_tag s = "<" ^ s ^ ">";; +let default_pp_mark_close_tag s = "";; + +let default_pp_print_open_tag s = ();; +let default_pp_print_close_tag = default_pp_print_open_tag;; + +let pp_make_formatter f g h i = + (* The initial state of the formatter contains a dummy box. *) + let pp_q = make_queue () in + let sys_tok = + make_queue_elem (size_of_int (-1)) (Pp_begin (0, Pp_hovbox)) 0 in + add_queue sys_tok pp_q; + let sys_scan_stack = + (Scan_elem (1, sys_tok)) :: scan_stack_bottom in + {pp_scan_stack = sys_scan_stack; + pp_format_stack = []; + pp_tbox_stack = []; + pp_tag_stack = []; + pp_mark_stack = []; + pp_margin = 78; + pp_min_space_left = 10; + pp_max_indent = 78 - 10; + pp_space_left = 78; + pp_current_indent = 0; + pp_is_new_line = true; + pp_left_total = 1; + pp_right_total = 1; + pp_curr_depth = 1; + pp_max_boxes = max_int; + pp_ellipsis = "."; + pp_output_function = f; + pp_flush_function = g; + pp_output_newline = h; + pp_output_spaces = i; + pp_print_tags = false; + pp_mark_tags = false; + pp_mark_open_tag = default_pp_mark_open_tag; + pp_mark_close_tag = default_pp_mark_close_tag; + pp_print_open_tag = default_pp_print_open_tag; + pp_print_close_tag = default_pp_print_close_tag; + pp_queue = pp_q + };; + +(* Default function to output spaces. *) +let blank_line = String.make 80 ' ';; +let rec display_blanks state n = + if n > 0 then + if n <= 80 then state.pp_output_function blank_line 0 n else + begin + state.pp_output_function blank_line 0 80; + display_blanks state (n - 80) + end;; + +(* Default function to output new lines. *) +let display_newline state () = state.pp_output_function "\n" 0 1;; + +let make_formatter f g = + let ff = pp_make_formatter f g ignore ignore in + ff.pp_output_newline <- display_newline ff; + ff.pp_output_spaces <- display_blanks ff; + ff;; + +let formatter_of_out_channel oc = + make_formatter (output oc) (fun () -> flush oc);; + +let formatter_of_buffer b = + make_formatter (Buffer.add_substring b) ignore;; + +let stdbuf = Buffer.create 512;; + +let str_formatter = formatter_of_buffer stdbuf;; +let std_formatter = formatter_of_out_channel stdout;; +let err_formatter = formatter_of_out_channel stderr;; + +let flush_str_formatter () = + pp_flush_queue str_formatter false; + let s = Buffer.contents stdbuf in + Buffer.reset stdbuf; + s;; + +(************************************************************** + + Basic functions on the standard formatter + + **************************************************************) + +let open_hbox = pp_open_hbox std_formatter +and open_vbox = pp_open_vbox std_formatter +and open_hvbox = pp_open_hvbox std_formatter +and open_hovbox = pp_open_hovbox std_formatter +and open_box = pp_open_box std_formatter +and close_box = pp_close_box std_formatter +and open_tag = pp_open_tag std_formatter +and close_tag = pp_close_tag std_formatter +and print_as = pp_print_as std_formatter +and print_string = pp_print_string std_formatter +and print_int = pp_print_int std_formatter +and print_float = pp_print_float std_formatter +and print_char = pp_print_char std_formatter +and print_bool = pp_print_bool std_formatter +and print_break = pp_print_break std_formatter +and print_cut = pp_print_cut std_formatter +and print_space = pp_print_space std_formatter +and force_newline = pp_force_newline std_formatter +and print_flush = pp_print_flush std_formatter +and print_newline = pp_print_newline std_formatter +and print_if_newline = pp_print_if_newline std_formatter + +and open_tbox = pp_open_tbox std_formatter +and close_tbox = pp_close_tbox std_formatter +and print_tbreak = pp_print_tbreak std_formatter + +and set_tab = pp_set_tab std_formatter +and print_tab = pp_print_tab std_formatter + +and set_margin = pp_set_margin std_formatter +and get_margin = pp_get_margin std_formatter + +and set_max_indent = pp_set_max_indent std_formatter +and get_max_indent = pp_get_max_indent std_formatter + +and set_max_boxes = pp_set_max_boxes std_formatter +and get_max_boxes = pp_get_max_boxes std_formatter +and over_max_boxes = pp_over_max_boxes std_formatter + +and set_ellipsis_text = pp_set_ellipsis_text std_formatter +and get_ellipsis_text = pp_get_ellipsis_text std_formatter + +and set_formatter_out_channel = + pp_set_formatter_out_channel std_formatter + +and set_formatter_output_functions = + pp_set_formatter_output_functions std_formatter +and get_formatter_output_functions = + pp_get_formatter_output_functions std_formatter + +and set_all_formatter_output_functions = + pp_set_all_formatter_output_functions std_formatter +and get_all_formatter_output_functions = + pp_get_all_formatter_output_functions std_formatter + +and set_formatter_tag_functions = + pp_set_formatter_tag_functions std_formatter +and get_formatter_tag_functions = + pp_get_formatter_tag_functions std_formatter +and set_print_tags = + pp_set_print_tags std_formatter +and get_print_tags = + pp_get_print_tags std_formatter +and set_mark_tags = + pp_set_mark_tags std_formatter +and get_mark_tags = + pp_get_mark_tags std_formatter +and set_tags = + pp_set_tags std_formatter +;; + + +(************************************************************** + + Printf implementation. + + **************************************************************) + +(* Error messages when processing formats. *) + +(* Trailer: giving up at character number ... *) +let giving_up mess fmt i = + "fprintf: " ^ mess ^ " ``" ^ fmt ^ "'', \ + giving up at character number " ^ string_of_int i ^ + (if i < String.length fmt + then " (" ^ String.make 1 fmt.[i] ^ ")." + else String.make 1 '.');; + +(* When an invalid format deserves a special error explanation. *) +let format_invalid_arg mess fmt i = invalid_arg (giving_up mess fmt i);; + +(* Standard invalid format. *) +let invalid_format fmt i = format_invalid_arg "bad format" fmt i;; + +(* Cannot find a valid integer into that format. *) +let invalid_integer fmt i = + invalid_arg (giving_up "bad integer specification" fmt i);; + +(* Finding an integer out of a sub-string of the format. *) +let format_int_of_string fmt i s = + let sz = + try int_of_string s with + | Failure s -> invalid_integer fmt i in + size_of_int sz;; + +(* Getting strings out of buffers. *) +let get_buffer_out b = + let s = Buffer.contents b in + Buffer.reset b; + s;; + +(* [ppf] is supposed to be a pretty-printer that outputs in buffer [b]: + to extract contents of [ppf] as a string we flush [ppf] and get the string + out of [b]. *) +let string_out b ppf = + pp_flush_queue ppf false; + get_buffer_out b;; + +(* Applies [printer] to a formatter that outputs on a fresh buffer, + then returns the resulting material. *) +let exstring printer arg = + let b = Buffer.create 512 in + let ppf = formatter_of_buffer b in + printer ppf arg; + string_out b ppf;; + +(* To turn out a character accumulator into the proper string result. *) +let implode_rev s0 = function + | [] -> s0 + | l -> String.concat "" (List.rev (s0 :: l));; + +external format_to_string : ('a, 'b, 'c, 'd) format4 -> string = "%identity";; + +(* [fprintf_out] is the printf-like function generator: given the + - [str] flag that tells if we are printing into a string, + - the [out] function that has to be called at the end of formatting, + it generates a [fprintf] function that takes as arguments a [ppf] + formatter and a printing format to print the rest of arguments + according to the format. + Regular [fprintf]-like functions of this module are obtained via partial + applications of [fprintf_out]. *) +let mkprintf str get_out = + let rec kprintf k fmt = + let fmt = format_to_string fmt in + let len = String.length fmt in + + let kpr fmt v = + let ppf = get_out fmt in + let print_as = ref None in + let pp_print_as_char c = + match !print_as with + | None -> pp_print_char ppf c + | Some size -> + pp_print_as_size ppf size (String.make 1 c); + print_as := None + and pp_print_as_string s = + match !print_as with + | None -> pp_print_string ppf s + | Some size -> + pp_print_as_size ppf size s; + print_as := None in + + let rec doprn n i = + if i >= len then Obj.magic (k ppf) else + match fmt.[i] with + | '%' -> + Printf.scan_format fmt v n i cont_s cont_a cont_t cont_f cont_m + | '@' -> + let i = succ i in + if i >= len then invalid_format fmt i else + begin match fmt.[i] with + | '[' -> + do_pp_open_box ppf n (succ i) + | ']' -> + pp_close_box ppf (); + doprn n (succ i) + | '{' -> + do_pp_open_tag ppf n (succ i) + | '}' -> + pp_close_tag ppf (); + doprn n (succ i) + | ' ' -> + pp_print_space ppf (); + doprn n (succ i) + | ',' -> + pp_print_cut ppf (); + doprn n (succ i) + | '?' -> + pp_print_flush ppf (); + doprn n (succ i) + | '.' -> + pp_print_newline ppf (); + doprn n (succ i) + | '\n' -> + pp_force_newline ppf (); + doprn n (succ i) + | ';' -> + do_pp_break ppf n (succ i) + | '<' -> + let got_size size n i = + print_as := Some size; + doprn n (skip_gt i) in + get_int n (succ i) got_size + | '@' as c -> + pp_print_as_char c; + doprn n (succ i) + | c -> invalid_format fmt i + end + | c -> + pp_print_as_char c; + doprn n (succ i) + + and cont_s n s i = + pp_print_as_string s; doprn n i + and cont_a n printer arg i = + if str then + pp_print_as_string ((Obj.magic printer : unit -> _ -> string) () arg) + else + printer ppf arg; + doprn n i + and cont_t n printer i = + if str then + pp_print_as_string ((Obj.magic printer : unit -> string) ()) + else + printer ppf; + doprn n i + and cont_f n i = + pp_print_flush ppf (); doprn n i + + and cont_m n sfmt i = + kprintf (Obj.magic (fun _ -> doprn n i)) sfmt + + and get_int n i c = + if i >= len then invalid_integer fmt i else + match fmt.[i] with + | ' ' -> get_int n (succ i) c + | '%' -> + let cont_s n s i = c (format_int_of_string fmt i s) n i + and cont_a n printer arg i = invalid_integer fmt i + and cont_t n printer i = invalid_integer fmt i + and cont_f n i = invalid_integer fmt i + and cont_m n sfmt i = invalid_integer fmt i in + Printf.scan_format fmt v n i cont_s cont_a cont_t cont_f cont_m + | _ -> + let rec get j = + if j >= len then invalid_integer fmt j else + match fmt.[j] with + | '0' .. '9' | '-' -> get (succ j) + | _ -> + let size = + if j = i then size_of_int 0 else + format_int_of_string fmt j (String.sub fmt i (j - i)) in + c size n j in + get i + + and skip_gt i = + if i >= len then invalid_format fmt i else + match fmt.[i] with + | ' ' -> skip_gt (succ i) + | '>' -> succ i + | _ -> invalid_format fmt i + + and get_box_kind i = + if i >= len then Pp_box, i else + match fmt.[i] with + | 'h' -> + let i = succ i in + if i >= len then Pp_hbox, i else + begin match fmt.[i] with + | 'o' -> + let i = succ i in + if i >= len then format_invalid_arg "bad box format" fmt i else + begin match fmt.[i] with + | 'v' -> Pp_hovbox, succ i + | c -> + format_invalid_arg + ("bad box name ho" ^ String.make 1 c) fmt i end + | 'v' -> Pp_hvbox, succ i + | c -> Pp_hbox, i + end + | 'b' -> Pp_box, succ i + | 'v' -> Pp_vbox, succ i + | _ -> Pp_box, i + + and get_tag_name n i c = + let rec get accu n i j = + if j >= len + then c (implode_rev (String.sub fmt i (j - i)) accu) n j else + match fmt.[j] with + | '>' -> c (implode_rev (String.sub fmt i (j - i)) accu) n j + | '%' -> + let s0 = String.sub fmt i (j - i) in + let cont_s n s i = get (s :: s0 :: accu) n i i + and cont_a n printer arg i = + let s = + if str + then (Obj.magic printer : unit -> _ -> string) () arg + else exstring printer arg in + get (s :: s0 :: accu) n i i + and cont_t n printer i = + let s = + if str + then (Obj.magic printer : unit -> string) () + else exstring (fun ppf () -> printer ppf) () in + get (s :: s0 :: accu) n i i + and cont_f n i = + format_invalid_arg "bad tag name specification" fmt i + and cont_m n sfmt i = + format_invalid_arg "bad tag name specification" fmt i in + Printf.scan_format fmt v n j cont_s cont_a cont_t cont_f cont_m + | c -> get accu n i (succ j) in + get [] n i i + + and do_pp_break ppf n i = + if i >= len then begin pp_print_space ppf (); doprn n i end else + match fmt.[i] with + | '<' -> + let rec got_nspaces nspaces n i = + get_int n i (got_offset nspaces) + and got_offset nspaces offset n i = + pp_print_break ppf (int_of_size nspaces) (int_of_size offset); + doprn n (skip_gt i) in + get_int n (succ i) got_nspaces + | c -> pp_print_space ppf (); doprn n i + + and do_pp_open_box ppf n i = + if i >= len then begin pp_open_box_gen ppf 0 Pp_box; doprn n i end else + match fmt.[i] with + | '<' -> + let kind, i = get_box_kind (succ i) in + let got_size size n i = + pp_open_box_gen ppf (int_of_size size) kind; + doprn n (skip_gt i) in + get_int n i got_size + | c -> pp_open_box_gen ppf 0 Pp_box; doprn n i + + and do_pp_open_tag ppf n i = + if i >= len then begin pp_open_tag ppf ""; doprn n i end else + match fmt.[i] with + | '<' -> + let got_name tag_name n i = + pp_open_tag ppf tag_name; + doprn n (skip_gt i) in + get_tag_name n (succ i) got_name + | c -> pp_open_tag ppf ""; doprn n i in + + doprn (Printf.index_of_int 0) 0 in + + Printf.kapr kpr fmt in + + kprintf;; + +(************************************************************** + + Defining [fprintf] and various flavors of [fprintf]. + + **************************************************************) + +let kfprintf k ppf = mkprintf false (fun _ -> ppf) k;; + +let fprintf ppf = kfprintf ignore ppf;; +let printf fmt = fprintf std_formatter fmt;; +let eprintf fmt = fprintf err_formatter fmt;; + +let kbprintf k b = + mkprintf false (fun _ -> formatter_of_buffer b) k;; + +let bprintf b = kbprintf ignore b;; + +let ksprintf k = + let b = Buffer.create 512 in + let k ppf = k (string_out b ppf) in + mkprintf true (fun _ -> formatter_of_buffer b) k;; + +let kprintf = ksprintf;; + +let sprintf fmt = ksprintf (fun s -> s) fmt;; + +at_exit print_flush;; Added: external/Pygments-0.8.1/tests/examplefiles/fucked_up.rb ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/fucked_up.rb Thu Aug 9 17:43:13 2007 @@ -0,0 +1,77 @@ +# vim:ft=ruby + +events = Hash.new { |h, k| h[k] = [] } +DATA.read.split(/\n\n\n\s*/).each do |event| + name = event[/^.*/].sub(/http:.*/, '') + event[/\n.*/m].scan(/^([A-Z]{2}\S*)\s*(\S*)\s*(\S*)(\s*\S*)/) do |kind, day, daytime, comment| + events[ [day, daytime] ] << [kind, name + comment] + end +end + +conflicts = 0 +events.to_a.sort_by do |(day, daytime),| + [%w(Mo Di Mi Do Fr).index(day) || 0, daytime] +end.each do |(day, daytime), names| + if names.size > 1 + conflicts += 1 + print '!!! ' + end + print "#{day} #{daytime}: " + names.each { |kind, name| puts " #{kind} #{name}" } + puts +end + +puts '%d conflicts' % conflicts +puts '%d SWS' % (events.inject(0) { |sum, ((day, daytime),)| sum + (daytime[/\d+$/].to_i - daytime[/^\d+/].to_i) }) + +string = % foo # strange. huh? +print "Escape here: \n" +print 'Dont escape here: \n' + +__END__ +Informatik und Informationsgesellschaft I: Digitale Medien (32 214) +Computer lassen ihre eigentliche Bestimmung durch Multimedia und Vernetzung erkennen: Es sind digitale Medien, die alle bisherigen Massen- und Kommunikationsmedien simulieren, kopieren oder ersetzen k??nnen. Die kurze Geschichte elektronischer Medien vom Telegramm bis zum Fernsehen wird so zur Vorgeschichte des Computers als Medium. Der Prozess der Mediatisierung der Rechnernetze soll in Technik, Theorie und Praxis untersucht werden. Das PR soll die Techniken der ortsverteilten und zeitversetzten Lehre an Hand praktischer ??bungen vorf??hren und untersuchen. +VL Di 15-17 w??ch. RUD 25, 3.101 J. Koubek +VL Do 15-17 w??ch. RUD 25, 3.101 +UE/PR Do 17-19 w??ch. RUD 25, 3.101 J.-M. Loebel + + +Methoden und Modelle des Systementwurfs (32 223) +Gute Methoden zum Entwurf und zur Verifikation von Systemen sind ein Schl??ssel f??r gute Software. Dieses Seminar betrachtet moderne Entwurfsmethoden. + VL Di 09-11 w??ch. RUD 26, 0??313 W. Reisig + VL Do 09-11 w??ch. RUD 26, 0??313 + UE Di 11-13 w??ch. RUD 26, 0??313 + PR Di 13-15 w??ch. RUD 26, 0??313 D. Weinberg + + +Komplexit??tstheorie (32 229) +In dieser Vorlesung untersuchen wir eine Reihe von wichtigen algorithmischen Problemstellungen aus verschiedenen Bereichen der Informatik. Unser besonderes Interesse gilt dabei der Absch??tzung der Rechenressourcen, die zu ihrer L??sung aufzubringen sind. Die Vorlesung bildet eine wichtige Grundlage f??r weiterf??hrende Veranstaltungen in den Bereichen Algorithmen, Kryptologie, Algorithmisches Lernen und Algorithmisches Beweisen. + VL Di 09-11 w??ch. RUD 26, 1??303 J. K??bler + VL Do 09-11 w??ch. RUD 26, 1??305 + UE Do 11-13 w??ch. RUD 26, 1??305 + + +Zuverl??ssige Systeme (32 234) +Mit zunehmender Verbreitung der Computertechnologie in immer mehr Bereichen des menschlichen Lebens wird die Zuverl??ssigkeit solcher Systeme zu einer immer zentraleren Frage. +Der Halbkurs "Zuverl??ssige Systeme" konzentriert sich auf folgende Schwerpunkte: Zuverl??ssigkeit, Fehlertoleranz, Responsivit??t, Messungen, Anwendungen, Systemmodelle und Techniken, Ausfallverhalten, Fehlermodelle, Schedulingtechniken, Software/Hardware - responsives Systemdesign, Analyse und Synthese, Bewertung, Fallstudien in Forschung und Industrie. +Der Halbkurs kann mit dem Halbkurs "Eigenschaften mobiler und eingebetteter Systeme" zu einem Projektkurs kombiniert werden. Ein gemeinsames Projekt begleitet beide Halbkurse. +VL Di 09-11 w??ch. RUD 26, 1??308 M. Malek +VL Do 09-11 w??ch. RUD 26, 1??308 +PR n.V. + + +Stochastik f??r InformatikerInnen (32 239) +Grundlagen der Wahrscheinlichkeitsrechnung, Diskrete und stetige Wahrscheinlichkeitsmodelle in der Informatik, Grenzwerts??tze, Simulationsverfahren, Zufallszahlen, Statistische Sch??tz- und Testverfahren, Markoffsche Ketten, Simulated Annealing, Probabilistische Analyse von Algorithmen. +VL Mo 09-11 w??ch. RUD 25, 3.101 W. K??ssler +VL Mi 09-11 w??ch. RUD 25, 3.101 +UE Mo 11-13 w??ch. RUD 25, 3.101 + UE Mi 11-13 w??ch. RUD 25. 3.101 + + +Geschichte der Informatik ?? Ausgew??hlte Kapitel (32 243) +VL Mi 13-15 w??ch. RUD 25, 3.113 W. Coy + + +Aktuelle Themen der Theoretischen Informatik (32 260) +In diesem Seminar sollen wichtige aktuelle Ver??ffentlichungen aus der theoretischen Informatik gemeinsam erarbeitet werden. Genaueres wird erst kurz vor dem Seminar entschieden. Bei Interesse wenden Sie sich bitte m??glichst fr??hzeitig an den Veranstalter. + SE Fr 09-11 w??ch. RUD 26, 1??307 M. Grohe?? Added: external/Pygments-0.8.1/tests/examplefiles/functional.rst ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/functional.rst Thu Aug 9 17:43:13 2007 @@ -0,0 +1,1472 @@ +Functional Programming HOWTO +================================ + +**Version 0.30** + +(This is a first draft. Please send comments/error +reports/suggestions to amk at amk.ca. This URL is probably not going to +be the final location of the document, so be careful about linking to +it -- you may want to add a disclaimer.) + +In this document, we'll take a tour of Python's features suitable for +implementing programs in a functional style. After an introduction to +the concepts of functional programming, we'll look at language +features such as iterators and generators and relevant library modules +such as ``itertools`` and ``functools``. + + +.. contents:: + +Introduction +---------------------- + +This section explains the basic concept of functional programming; if +you're just interested in learning about Python language features, +skip to the next section. + +Programming languages support decomposing problems in several different +ways: + +* Most programming languages are **procedural**: + programs are lists of instructions that tell the computer what to + do with the program's input. + C, Pascal, and even Unix shells are procedural languages. + +* In **declarative** languages, you write a specification that describes + the problem to be solved, and the language implementation figures out + how to perform the computation efficiently. SQL is the declarative + language you're most likely to be familiar with; a SQL query describes + the data set you want to retrieve, and the SQL engine decides whether to + scan tables or use indexes, which subclauses should be performed first, + etc. + +* **Object-oriented** programs manipulate collections of objects. + Objects have internal state and support methods that query or modify + this internal state in some way. Smalltalk and Java are + object-oriented languages. C++ and Python are languages that + support object-oriented programming, but don't force the use + of object-oriented features. + +* **Functional** programming decomposes a problem into a set of functions. + Ideally, functions only take inputs and produce outputs, and don't have any + internal state that affects the output produced for a given input. + Well-known functional languages include the ML family (Standard ML, + OCaml, and other variants) and Haskell. + +The designers of some computer languages have chosen one approach to +programming that's emphasized. This often makes it difficult to +write programs that use a different approach. Other languages are +multi-paradigm languages that support several different approaches. Lisp, +C++, and Python are multi-paradigm; you can write programs or +libraries that are largely procedural, object-oriented, or functional +in all of these languages. In a large program, different sections +might be written using different approaches; the GUI might be object-oriented +while the processing logic is procedural or functional, for example. + +In a functional program, input flows through a set of functions. Each +function operates on its input and produces some output. Functional +style frowns upon functions with side effects that modify internal +state or make other changes that aren't visible in the function's +return value. Functions that have no side effects at all are +called **purely functional**. +Avoiding side effects means not using data structures +that get updated as a program runs; every function's output +must only depend on its input. + +Some languages are very strict about purity and don't even have +assignment statements such as ``a=3`` or ``c = a + b``, but it's +difficult to avoid all side effects. Printing to the screen or +writing to a disk file are side effects, for example. For example, in +Python a ``print`` statement or a ``time.sleep(1)`` both return no +useful value; they're only called for their side effects of sending +some text to the screen or pausing execution for a second. + +Python programs written in functional style usually won't go to the +extreme of avoiding all I/O or all assignments; instead, they'll +provide a functional-appearing interface but will use non-functional +features internally. For example, the implementation of a function +will still use assignments to local variables, but won't modify global +variables or have other side effects. + +Functional programming can be considered the opposite of +object-oriented programming. Objects are little capsules containing +some internal state along with a collection of method calls that let +you modify this state, and programs consist of making the right set of +state changes. Functional programming wants to avoid state changes as +much as possible and works with data flowing between functions. In +Python you might combine the two approaches by writing functions that +take and return instances representing objects in your application +(e-mail messages, transactions, etc.). + +Functional design may seem like an odd constraint to work under. Why +should you avoid objects and side effects? There are theoretical and +practical advantages to the functional style: + +* Formal provability. +* Modularity. +* Composability. +* Ease of debugging and testing. + +Formal provability +'''''''''''''''''''''' + +A theoretical benefit is that it's easier to construct a mathematical proof +that a functional program is correct. + +For a long time researchers have been interested in finding ways to +mathematically prove programs correct. This is different from testing +a program on numerous inputs and concluding that its output is usually +correct, or reading a program's source code and concluding that the +code looks right; the goal is instead a rigorous proof that a program +produces the right result for all possible inputs. + +The technique used to prove programs correct is to write down +**invariants**, properties of the input data and of the program's +variables that are always true. For each line of code, you then show +that if invariants X and Y are true **before** the line is executed, +the slightly different invariants X' and Y' are true **after** +the line is executed. This continues until you reach the end of the +program, at which point the invariants should match the desired +conditions on the program's output. + +Functional programming's avoidance of assignments arose because +assignments are difficult to handle with this technique; +assignments can break invariants that were true before the assignment +without producing any new invariants that can be propagated onward. + +Unfortunately, proving programs correct is largely impractical and not +relevant to Python software. Even trivial programs require proofs that +are several pages long; the proof of correctness for a moderately +complicated program would be enormous, and few or none of the programs +you use daily (the Python interpreter, your XML parser, your web +browser) could be proven correct. Even if you wrote down or generated +a proof, there would then be the question of verifying the proof; +maybe there's an error in it, and you wrongly believe you've proved +the program correct. + +Modularity +'''''''''''''''''''''' + +A more practical benefit of functional programming is that it forces +you to break apart your problem into small pieces. Programs are more +modular as a result. It's easier to specify and write a small +function that does one thing than a large function that performs a +complicated transformation. Small functions are also easier to read +and to check for errors. + + +Ease of debugging and testing +'''''''''''''''''''''''''''''''''' + +Testing and debugging a functional-style program is easier. + +Debugging is simplified because functions are generally small and +clearly specified. When a program doesn't work, each function is an +interface point where you can check that the data are correct. You +can look at the intermediate inputs and outputs to quickly isolate the +function that's responsible for a bug. + +Testing is easier because each function is a potential subject for a +unit test. Functions don't depend on system state that needs to be +replicated before running a test; instead you only have to synthesize +the right input and then check that the output matches expectations. + + + +Composability +'''''''''''''''''''''' + +As you work on a functional-style program, you'll write a number of +functions with varying inputs and outputs. Some of these functions +will be unavoidably specialized to a particular application, but +others will be useful in a wide variety of programs. For example, a +function that takes a directory path and returns all the XML files in +the directory, or a function that takes a filename and returns its +contents, can be applied to many different situations. + +Over time you'll form a personal library of utilities. Often you'll +assemble new programs by arranging existing functions in a new +configuration and writing a few functions specialized for the current +task. + + + +Iterators +----------------------- + +I'll start by looking at a Python language feature that's an important +foundation for writing functional-style programs: iterators. + +An iterator is an object representing a stream of data; this object +returns the data one element at a time. A Python iterator must +support a method called ``next()`` that takes no arguments and always +returns the next element of the stream. If there are no more elements +in the stream, ``next()`` must raise the ``StopIteration`` exception. +Iterators don't have to be finite, though; it's perfectly reasonable +to write an iterator that produces an infinite stream of data. + +The built-in ``iter()`` function takes an arbitrary object and tries +to return an iterator that will return the object's contents or +elements, raising ``TypeError`` if the object doesn't support +iteration. Several of Python's built-in data types support iteration, +the most common being lists and dictionaries. An object is called +an **iterable** object if you can get an iterator for it. + +You can experiment with the iteration interface manually:: + + >>> L = [1,2,3] + >>> it = iter(L) + >>> print it + + >>> it.next() + 1 + >>> it.next() + 2 + >>> it.next() + 3 + >>> it.next() + Traceback (most recent call last): + File "", line 1, in ? + StopIteration + >>> + +Python expects iterable objects in several different contexts, the +most important being the ``for`` statement. In the statement ``for X in Y``, +Y must be an iterator or some object for which ``iter()`` can create +an iterator. These two statements are equivalent:: + + for i in iter(obj): + print i + + for i in obj: + print i + +Iterators can be materialized as lists or tuples by using the +``list()`` or ``tuple()`` constructor functions:: + + >>> L = [1,2,3] + >>> iterator = iter(L) + >>> t = tuple(iterator) + >>> t + (1, 2, 3) + +Sequence unpacking also supports iterators: if you know an iterator +will return N elements, you can unpack them into an N-tuple:: + + >>> L = [1,2,3] + >>> iterator = iter(L) + >>> a,b,c = iterator + >>> a,b,c + (1, 2, 3) + +Built-in functions such as ``max()`` and ``min()`` can take a single +iterator argument and will return the largest or smallest element. +The ``"in"`` and ``"not in"`` operators also support iterators: ``X in +iterator`` is true if X is found in the stream returned by the +iterator. You'll run into obvious problems if the iterator is +infinite; ``max()``, ``min()``, and ``"not in"`` will never return, and +if the element X never appears in the stream, the ``"in"`` operator +won't return either. + +Note that you can only go forward in an iterator; there's no way to +get the previous element, reset the iterator, or make a copy of it. +Iterator objects can optionally provide these additional capabilities, +but the iterator protocol only specifies the ``next()`` method. +Functions may therefore consume all of the iterator's output, and if +you need to do something different with the same stream, you'll have +to create a new iterator. + + + +Data Types That Support Iterators +''''''''''''''''''''''''''''''''''' + +We've already seen how lists and tuples support iterators. In fact, +any Python sequence type, such as strings, will automatically support +creation of an iterator. + +Calling ``iter()`` on a dictionary returns an iterator that will loop +over the dictionary's keys:: + + >>> m = {'Jan': 1, 'Feb': 2, 'Mar': 3, 'Apr': 4, 'May': 5, 'Jun': 6, + ... 'Jul': 7, 'Aug': 8, 'Sep': 9, 'Oct': 10, 'Nov': 11, 'Dec': 12} + >>> for key in m: + ... print key, m[key] + Mar 3 + Feb 2 + Aug 8 + Sep 9 + May 5 + Jun 6 + Jul 7 + Jan 1 + Apr 4 + Nov 11 + Dec 12 + Oct 10 + +Note that the order is essentially random, because it's based on the +hash ordering of the objects in the dictionary. + +Applying ``iter()`` to a dictionary always loops over the keys, but +dictionaries have methods that return other iterators. If you want to +iterate over keys, values, or key/value pairs, you can explicitly call +the ``iterkeys()``, ``itervalues()``, or ``iteritems()`` methods to +get an appropriate iterator. + +The ``dict()`` constructor can accept an iterator that returns a +finite stream of ``(key, value)`` tuples:: + + >>> L = [('Italy', 'Rome'), ('France', 'Paris'), ('US', 'Washington DC')] + >>> dict(iter(L)) + {'Italy': 'Rome', 'US': 'Washington DC', 'France': 'Paris'} + +Files also support iteration by calling the ``readline()`` +method until there are no more lines in the file. This means you can +read each line of a file like this:: + + for line in file: + # do something for each line + ... + +Sets can take their contents from an iterable and let you iterate over +the set's elements:: + + S = set((2, 3, 5, 7, 11, 13)) + for i in S: + print i + + + +Generator expressions and list comprehensions +---------------------------------------------------- + +Two common operations on an iterator's output are 1) performing some +operation for every element, 2) selecting a subset of elements that +meet some condition. For example, given a list of strings, you might +want to strip off trailing whitespace from each line or extract all +the strings containing a given substring. + +List comprehensions and generator expressions (short form: "listcomps" +and "genexps") are a concise notation for such operations, borrowed +from the functional programming language Haskell +(http://www.haskell.org). You can strip all the whitespace from a +stream of strings with the following code:: + + line_list = [' line 1\n', 'line 2 \n', ...] + + # Generator expression -- returns iterator + stripped_iter = (line.strip() for line in line_list) + + # List comprehension -- returns list + stripped_list = [line.strip() for line in line_list] + +You can select only certain elements by adding an ``"if"`` condition:: + + stripped_list = [line.strip() for line in line_list + if line != ""] + +With a list comprehension, you get back a Python list; +``stripped_list`` is a list containing the resulting lines, not an +iterator. Generator expressions return an iterator that computes the +values as necessary, not needing to materialize all the values at +once. This means that list comprehensions aren't useful if you're +working with iterators that return an infinite stream or a very large +amount of data. Generator expressions are preferable in these +situations. + +Generator expressions are surrounded by parentheses ("()") and list +comprehensions are surrounded by square brackets ("[]"). Generator +expressions have the form:: + + ( expression for expr in sequence1 + if condition1 + for expr2 in sequence2 + if condition2 + for expr3 in sequence3 ... + if condition3 + for exprN in sequenceN + if conditionN ) + +Again, for a list comprehension only the outside brackets are +different (square brackets instead of parentheses). + +The elements of the generated output will be the successive values of +``expression``. The ``if`` clauses are all optional; if present, +``expression`` is only evaluated and added to the result when +``condition`` is true. + +Generator expressions always have to be written inside parentheses, +but the parentheses signalling a function call also count. If you +want to create an iterator that will be immediately passed to a +function you can write:: + + obj_total = sum(obj.count for obj in list_all_objects()) + +The ``for...in`` clauses contain the sequences to be iterated over. +The sequences do not have to be the same length, because they are +iterated over from left to right, **not** in parallel. For each +element in ``sequence1``, ``sequence2`` is looped over from the +beginning. ``sequence3`` is then looped over for each +resulting pair of elements from ``sequence1`` and ``sequence2``. + +To put it another way, a list comprehension or generator expression is +equivalent to the following Python code:: + + for expr1 in sequence1: + if not (condition1): + continue # Skip this element + for expr2 in sequence2: + if not (condition2): + continue # Skip this element + ... + for exprN in sequenceN: + if not (conditionN): + continue # Skip this element + + # Output the value of + # the expression. + +This means that when there are multiple ``for...in`` clauses but no +``if`` clauses, the length of the resulting output will be equal to +the product of the lengths of all the sequences. If you have two +lists of length 3, the output list is 9 elements long:: + + seq1 = 'abc' + seq2 = (1,2,3) + >>> [ (x,y) for x in seq1 for y in seq2] + [('a', 1), ('a', 2), ('a', 3), + ('b', 1), ('b', 2), ('b', 3), + ('c', 1), ('c', 2), ('c', 3)] + +To avoid introducing an ambiguity into Python's grammar, if +``expression`` is creating a tuple, it must be surrounded with +parentheses. The first list comprehension below is a syntax error, +while the second one is correct:: + + # Syntax error + [ x,y for x in seq1 for y in seq2] + # Correct + [ (x,y) for x in seq1 for y in seq2] + + +Generators +----------------------- + +Generators are a special class of functions that simplify the task of +writing iterators. Regular functions compute a value and return it, +but generators return an iterator that returns a stream of values. + +You're doubtless familiar with how regular function calls work in +Python or C. When you call a function, it gets a private namespace +where its local variables are created. When the function reaches a +``return`` statement, the local variables are destroyed and the +value is returned to the caller. A later call to the same function +creates a new private namespace and a fresh set of local +variables. But, what if the local variables weren't thrown away on +exiting a function? What if you could later resume the function where +it left off? This is what generators provide; they can be thought of +as resumable functions. + +Here's the simplest example of a generator function:: + + def generate_ints(N): + for i in range(N): + yield i + +Any function containing a ``yield`` keyword is a generator function; +this is detected by Python's bytecode compiler which compiles the +function specially as a result. + +When you call a generator function, it doesn't return a single value; +instead it returns a generator object that supports the iterator +protocol. On executing the ``yield`` expression, the generator +outputs the value of ``i``, similar to a ``return`` +statement. The big difference between ``yield`` and a +``return`` statement is that on reaching a ``yield`` the +generator's state of execution is suspended and local variables are +preserved. On the next call to the generator's ``.next()`` method, +the function will resume executing. + +Here's a sample usage of the ``generate_ints()`` generator:: + + >>> gen = generate_ints(3) + >>> gen + + >>> gen.next() + 0 + >>> gen.next() + 1 + >>> gen.next() + 2 + >>> gen.next() + Traceback (most recent call last): + File "stdin", line 1, in ? + File "stdin", line 2, in generate_ints + StopIteration + +You could equally write ``for i in generate_ints(5)``, or +``a,b,c = generate_ints(3)``. + +Inside a generator function, the ``return`` statement can only be used +without a value, and signals the end of the procession of values; +after executing a ``return`` the generator cannot return any further +values. ``return`` with a value, such as ``return 5``, is a syntax +error inside a generator function. The end of the generator's results +can also be indicated by raising ``StopIteration`` manually, or by +just letting the flow of execution fall off the bottom of the +function. + +You could achieve the effect of generators manually by writing your +own class and storing all the local variables of the generator as +instance variables. For example, returning a list of integers could +be done by setting ``self.count`` to 0, and having the +``next()`` method increment ``self.count`` and return it. +However, for a moderately complicated generator, writing a +corresponding class can be much messier. + +The test suite included with Python's library, ``test_generators.py``, +contains a number of more interesting examples. Here's one generator +that implements an in-order traversal of a tree using generators +recursively. + +:: + + # A recursive generator that generates Tree leaves in in-order. + def inorder(t): + if t: + for x in inorder(t.left): + yield x + + yield t.label + + for x in inorder(t.right): + yield x + +Two other examples in ``test_generators.py`` produce +solutions for the N-Queens problem (placing N queens on an NxN +chess board so that no queen threatens another) and the Knight's Tour +(finding a route that takes a knight to every square of an NxN chessboard +without visiting any square twice). + + + +Passing values into a generator +'''''''''''''''''''''''''''''''''''''''''''''' + +In Python 2.4 and earlier, generators only produced output. Once a +generator's code was invoked to create an iterator, there was no way to +pass any new information into the function when its execution is +resumed. You could hack together this ability by making the +generator look at a global variable or by passing in some mutable object +that callers then modify, but these approaches are messy. + +In Python 2.5 there's a simple way to pass values into a generator. +``yield`` became an expression, returning a value that can be assigned +to a variable or otherwise operated on:: + + val = (yield i) + +I recommend that you **always** put parentheses around a ``yield`` +expression when you're doing something with the returned value, as in +the above example. The parentheses aren't always necessary, but it's +easier to always add them instead of having to remember when they're +needed. + +(PEP 342 explains the exact rules, which are that a +``yield``-expression must always be parenthesized except when it +occurs at the top-level expression on the right-hand side of an +assignment. This means you can write ``val = yield i`` but have to +use parentheses when there's an operation, as in ``val = (yield i) ++ 12``.) + +Values are sent into a generator by calling its +``send(value)`` method. This method resumes the +generator's code and the ``yield`` expression returns the specified +value. If the regular ``next()`` method is called, the +``yield`` returns ``None``. + +Here's a simple counter that increments by 1 and allows changing the +value of the internal counter. + +:: + + def counter (maximum): + i = 0 + while i < maximum: + val = (yield i) + # If value provided, change counter + if val is not None: + i = val + else: + i += 1 + +And here's an example of changing the counter: + + >>> it = counter(10) + >>> print it.next() + 0 + >>> print it.next() + 1 + >>> print it.send(8) + 8 + >>> print it.next() + 9 + >>> print it.next() + Traceback (most recent call last): + File ``t.py'', line 15, in ? + print it.next() + StopIteration + +Because ``yield`` will often be returning ``None``, you +should always check for this case. Don't just use its value in +expressions unless you're sure that the ``send()`` method +will be the only method used resume your generator function. + +In addition to ``send()``, there are two other new methods on +generators: + +* ``throw(type, value=None, traceback=None)`` is used to raise an exception inside the + generator; the exception is raised by the ``yield`` expression + where the generator's execution is paused. + +* ``close()`` raises a ``GeneratorExit`` + exception inside the generator to terminate the iteration. + On receiving this + exception, the generator's code must either raise + ``GeneratorExit`` or ``StopIteration``; catching the + exception and doing anything else is illegal and will trigger + a ``RuntimeError``. ``close()`` will also be called by + Python's garbage collector when the generator is garbage-collected. + + If you need to run cleanup code when a ``GeneratorExit`` occurs, + I suggest using a ``try: ... finally:`` suite instead of + catching ``GeneratorExit``. + +The cumulative effect of these changes is to turn generators from +one-way producers of information into both producers and consumers. + +Generators also become **coroutines**, a more generalized form of +subroutines. Subroutines are entered at one point and exited at +another point (the top of the function, and a ``return`` +statement), but coroutines can be entered, exited, and resumed at +many different points (the ``yield`` statements). + + +Built-in functions +---------------------------------------------- + +Let's look in more detail at built-in functions often used with iterators. + +Two Python's built-in functions, ``map()`` and ``filter()``, are +somewhat obsolete; they duplicate the features of list comprehensions +but return actual lists instead of iterators. + +``map(f, iterA, iterB, ...)`` returns a list containing ``f(iterA[0], +iterB[0]), f(iterA[1], iterB[1]), f(iterA[2], iterB[2]), ...``. + +:: + + def upper(s): + return s.upper() + map(upper, ['sentence', 'fragment']) => + ['SENTENCE', 'FRAGMENT'] + + [upper(s) for s in ['sentence', 'fragment']] => + ['SENTENCE', 'FRAGMENT'] + +As shown above, you can achieve the same effect with a list +comprehension. The ``itertools.imap()`` function does the same thing +but can handle infinite iterators; it'll be discussed later, in the section on +the ``itertools`` module. + +``filter(predicate, iter)`` returns a list +that contains all the sequence elements that meet a certain condition, +and is similarly duplicated by list comprehensions. +A **predicate** is a function that returns the truth value of +some condition; for use with ``filter()``, the predicate must take a +single value. + +:: + + def is_even(x): + return (x % 2) == 0 + + filter(is_even, range(10)) => + [0, 2, 4, 6, 8] + +This can also be written as a list comprehension:: + + >>> [x for x in range(10) if is_even(x)] + [0, 2, 4, 6, 8] + +``filter()`` also has a counterpart in the ``itertools`` module, +``itertools.ifilter()``, that returns an iterator and +can therefore handle infinite sequences just as ``itertools.imap()`` can. + +``reduce(func, iter, [initial_value])`` doesn't have a counterpart in +the ``itertools`` module because it cumulatively performs an operation +on all the iterable's elements and therefore can't be applied to +infinite iterables. ``func`` must be a function that takes two elements +and returns a single value. ``reduce()`` takes the first two elements +A and B returned by the iterator and calculates ``func(A, B)``. It +then requests the third element, C, calculates ``func(func(A, B), +C)``, combines this result with the fourth element returned, and +continues until the iterable is exhausted. If the iterable returns no +values at all, a ``TypeError`` exception is raised. If the initial +value is supplied, it's used as a starting point and +``func(initial_value, A)`` is the first calculation. + +:: + + import operator + reduce(operator.concat, ['A', 'BB', 'C']) => + 'ABBC' + reduce(operator.concat, []) => + TypeError: reduce() of empty sequence with no initial value + reduce(operator.mul, [1,2,3], 1) => + 6 + reduce(operator.mul, [], 1) => + 1 + +If you use ``operator.add`` with ``reduce()``, you'll add up all the +elements of the iterable. This case is so common that there's a special +built-in called ``sum()`` to compute it:: + + reduce(operator.add, [1,2,3,4], 0) => + 10 + sum([1,2,3,4]) => + 10 + sum([]) => + 0 + +For many uses of ``reduce()``, though, it can be clearer to just write +the obvious ``for`` loop:: + + # Instead of: + product = reduce(operator.mul, [1,2,3], 1) + + # You can write: + product = 1 + for i in [1,2,3]: + product *= i + + +``enumerate(iter)`` counts off the elements in the iterable, returning +2-tuples containing the count and each element. + +:: + + enumerate(['subject', 'verb', 'object']) => + (0, 'subject'), (1, 'verb'), (2, 'object') + +``enumerate()`` is often used when looping through a list +and recording the indexes at which certain conditions are met:: + + f = open('data.txt', 'r') + for i, line in enumerate(f): + if line.strip() == '': + print 'Blank line at line #%i' % i + +``sorted(iterable, [cmp=None], [key=None], [reverse=False)`` +collects all the elements of the iterable into a list, sorts +the list, and returns the sorted result. The ``cmp``, ``key``, +and ``reverse`` arguments are passed through to the +constructed list's ``.sort()`` method. + +:: + + import random + # Generate 8 random numbers between [0, 10000) + rand_list = random.sample(range(10000), 8) + rand_list => + [769, 7953, 9828, 6431, 8442, 9878, 6213, 2207] + sorted(rand_list) => + [769, 2207, 6213, 6431, 7953, 8442, 9828, 9878] + sorted(rand_list, reverse=True) => + [9878, 9828, 8442, 7953, 6431, 6213, 2207, 769] + +(For a more detailed discussion of sorting, see the Sorting mini-HOWTO +in the Python wiki at http://wiki.python.org/moin/HowTo/Sorting.) + +The ``any(iter)`` and ``all(iter)`` built-ins look at +the truth values of an iterable's contents. ``any()`` returns +True if any element in the iterable is a true value, and ``all()`` +returns True if all of the elements are true values:: + + any([0,1,0]) => + True + any([0,0,0]) => + False + any([1,1,1]) => + True + all([0,1,0]) => + False + all([0,0,0]) => + False + all([1,1,1]) => + True + + +Small functions and the lambda statement +---------------------------------------------- + +When writing functional-style programs, you'll often need little +functions that act as predicates or that combine elements in some way. + +If there's a Python built-in or a module function that's suitable, you +don't need to define a new function at all:: + + stripped_lines = [line.strip() for line in lines] + existing_files = filter(os.path.exists, file_list) + +If the function you need doesn't exist, you need to write it. One way +to write small functions is to use the ``lambda`` statement. ``lambda`` +takes a number of parameters and an expression combining these parameters, +and creates a small function that returns the value of the expression:: + + lowercase = lambda x: x.lower() + + print_assign = lambda name, value: name + '=' + str(value) + + adder = lambda x, y: x+y + +An alternative is to just use the ``def`` statement and define a +function in the usual way:: + + def lowercase(x): + return x.lower() + + def print_assign(name, value): + return name + '=' + str(value) + + def adder(x,y): + return x + y + +Which alternative is preferable? That's a style question; my usual +course is to avoid using ``lambda``. + +One reason for my preference is that ``lambda`` is quite limited in +the functions it can define. The result has to be computable as a +single expression, which means you can't have multiway +``if... elif... else`` comparisons or ``try... except`` statements. +If you try to do too much in a ``lambda`` statement, you'll end up +with an overly complicated expression that's hard to read. Quick, +what's the following code doing? + +:: + + total = reduce(lambda a, b: (0, a[1] + b[1]), items)[1] + +You can figure it out, but it takes time to disentangle the expression +to figure out what's going on. Using a short nested +``def`` statements makes things a little bit better:: + + def combine (a, b): + return 0, a[1] + b[1] + + total = reduce(combine, items)[1] + +But it would be best of all if I had simply used a ``for`` loop:: + + total = 0 + for a, b in items: + total += b + +Or the ``sum()`` built-in and a generator expression:: + + total = sum(b for a,b in items) + +Many uses of ``reduce()`` are clearer when written as ``for`` loops. + +Fredrik Lundh once suggested the following set of rules for refactoring +uses of ``lambda``: + +1) Write a lambda function. +2) Write a comment explaining what the heck that lambda does. +3) Study the comment for a while, and think of a name that captures + the essence of the comment. +4) Convert the lambda to a def statement, using that name. +5) Remove the comment. + +I really like these rules, but you're free to disagree that this +lambda-free style is better. + + +The itertools module +----------------------- + +The ``itertools`` module contains a number of commonly-used iterators +as well as functions for combining several iterators. This section +will introduce the module's contents by showing small examples. + +The module's functions fall into a few broad classes: + +* Functions that create a new iterator based on an existing iterator. +* Functions for treating an iterator's elements as function arguments. +* Functions for selecting portions of an iterator's output. +* A function for grouping an iterator's output. + +Creating new iterators +'''''''''''''''''''''' + +``itertools.count(n)`` returns an infinite stream of +integers, increasing by 1 each time. You can optionally supply the +starting number, which defaults to 0:: + + itertools.count() => + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ... + itertools.count(10) => + 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, ... + +``itertools.cycle(iter)`` saves a copy of the contents of a provided +iterable and returns a new iterator that returns its elements from +first to last. The new iterator will repeat these elements infinitely. + +:: + + itertools.cycle([1,2,3,4,5]) => + 1, 2, 3, 4, 5, 1, 2, 3, 4, 5, ... + +``itertools.repeat(elem, [n])`` returns the provided element ``n`` +times, or returns the element endlessly if ``n`` is not provided. + +:: + + itertools.repeat('abc') => + abc, abc, abc, abc, abc, abc, abc, abc, abc, abc, ... + itertools.repeat('abc', 5) => + abc, abc, abc, abc, abc + +``itertools.chain(iterA, iterB, ...)`` takes an arbitrary number of +iterables as input, and returns all the elements of the first +iterator, then all the elements of the second, and so on, until all of +the iterables have been exhausted. + +:: + + itertools.chain(['a', 'b', 'c'], (1, 2, 3)) => + a, b, c, 1, 2, 3 + +``itertools.izip(iterA, iterB, ...)`` takes one element from each iterable +and returns them in a tuple:: + + itertools.izip(['a', 'b', 'c'], (1, 2, 3)) => + ('a', 1), ('b', 2), ('c', 3) + +It's similiar to the built-in ``zip()`` function, but doesn't +construct an in-memory list and exhaust all the input iterators before +returning; instead tuples are constructed and returned only if they're +requested. (The technical term for this behaviour is +`lazy evaluation `__.) + +This iterator is intended to be used with iterables that are all of +the same length. If the iterables are of different lengths, the +resulting stream will be the same length as the shortest iterable. + +:: + + itertools.izip(['a', 'b'], (1, 2, 3)) => + ('a', 1), ('b', 2) + +You should avoid doing this, though, because an element may be taken +from the longer iterators and discarded. This means you can't go on +to use the iterators further because you risk skipping a discarded +element. + +``itertools.islice(iter, [start], stop, [step])`` returns a stream +that's a slice of the iterator. With a single ``stop`` argument, +it will return the first ``stop`` +elements. If you supply a starting index, you'll get ``stop-start`` +elements, and if you supply a value for ``step``, elements will be +skipped accordingly. Unlike Python's string and list slicing, you +can't use negative values for ``start``, ``stop``, or ``step``. + +:: + + itertools.islice(range(10), 8) => + 0, 1, 2, 3, 4, 5, 6, 7 + itertools.islice(range(10), 2, 8) => + 2, 3, 4, 5, 6, 7 + itertools.islice(range(10), 2, 8, 2) => + 2, 4, 6 + +``itertools.tee(iter, [n])`` replicates an iterator; it returns ``n`` +independent iterators that will all return the contents of the source +iterator. If you don't supply a value for ``n``, the default is 2. +Replicating iterators requires saving some of the contents of the source +iterator, so this can consume significant memory if the iterator is large +and one of the new iterators is consumed more than the others. + +:: + + itertools.tee( itertools.count() ) => + iterA, iterB + + where iterA -> + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ... + + and iterB -> + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ... + + +Calling functions on elements +''''''''''''''''''''''''''''' + +Two functions are used for calling other functions on the contents of an +iterable. + +``itertools.imap(f, iterA, iterB, ...)`` returns +a stream containing ``f(iterA[0], iterB[0]), f(iterA[1], iterB[1]), +f(iterA[2], iterB[2]), ...``:: + + itertools.imap(operator.add, [5, 6, 5], [1, 2, 3]) => + 6, 8, 8 + +The ``operator`` module contains a set of functions +corresponding to Python's operators. Some examples are +``operator.add(a, b)`` (adds two values), +``operator.ne(a, b)`` (same as ``a!=b``), +and +``operator.attrgetter('id')`` (returns a callable that +fetches the ``"id"`` attribute). + +``itertools.starmap(func, iter)`` assumes that the iterable will +return a stream of tuples, and calls ``f()`` using these tuples as the +arguments:: + + itertools.starmap(os.path.join, + [('/usr', 'bin', 'java'), ('/bin', 'python'), + ('/usr', 'bin', 'perl'),('/usr', 'bin', 'ruby')]) + => + /usr/bin/java, /bin/python, /usr/bin/perl, /usr/bin/ruby + + +Selecting elements +'''''''''''''''''' + +Another group of functions chooses a subset of an iterator's elements +based on a predicate. + +``itertools.ifilter(predicate, iter)`` returns all the elements for +which the predicate returns true:: + + def is_even(x): + return (x % 2) == 0 + + itertools.ifilter(is_even, itertools.count()) => + 0, 2, 4, 6, 8, 10, 12, 14, ... + +``itertools.ifilterfalse(predicate, iter)`` is the opposite, +returning all elements for which the predicate returns false:: + + itertools.ifilterfalse(is_even, itertools.count()) => + 1, 3, 5, 7, 9, 11, 13, 15, ... + +``itertools.takewhile(predicate, iter)`` returns elements for as long +as the predicate returns true. Once the predicate returns false, +the iterator will signal the end of its results. + +:: + + def less_than_10(x): + return (x < 10) + + itertools.takewhile(less_than_10, itertools.count()) => + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 + + itertools.takewhile(is_even, itertools.count()) => + 0 + +``itertools.dropwhile(predicate, iter)`` discards elements while the +predicate returns true, and then returns the rest of the iterable's +results. + +:: + + itertools.dropwhile(less_than_10, itertools.count()) => + 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, ... + + itertools.dropwhile(is_even, itertools.count()) => + 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ... + + +Grouping elements +''''''''''''''''' + +The last function I'll discuss, ``itertools.groupby(iter, +key_func=None)``, is the most complicated. ``key_func(elem)`` is a +function that can compute a key value for each element returned by the +iterable. If you don't supply a key function, the key is simply each +element itself. + +``groupby()`` collects all the consecutive elements from the +underlying iterable that have the same key value, and returns a stream +of 2-tuples containing a key value and an iterator for the elements +with that key. + +:: + + city_list = [('Decatur', 'AL'), ('Huntsville', 'AL'), ('Selma', 'AL'), + ('Anchorage', 'AK'), ('Nome', 'AK'), + ('Flagstaff', 'AZ'), ('Phoenix', 'AZ'), ('Tucson', 'AZ'), + ... + ] + + def get_state ((city, state)): + return state + + itertools.groupby(city_list, get_state) => + ('AL', iterator-1), + ('AK', iterator-2), + ('AZ', iterator-3), ... + + where + iterator-1 => + ('Decatur', 'AL'), ('Huntsville', 'AL'), ('Selma', 'AL') + iterator-2 => + ('Anchorage', 'AK'), ('Nome', 'AK') + iterator-3 => + ('Flagstaff', 'AZ'), ('Phoenix', 'AZ'), ('Tucson', 'AZ') + +``groupby()`` assumes that the underlying iterable's contents will +already be sorted based on the key. Note that the returned iterators +also use the underlying iterable, so you have to consume the results +of iterator-1 before requesting iterator-2 and its corresponding key. + + +The functools module +---------------------------------------------- + +The ``functools`` module in Python 2.5 contains some higher-order +functions. A **higher-order function** takes one or more functions as +input and returns a new function. The most useful tool in this module +is the ``partial()`` function. + +For programs written in a functional style, you'll sometimes want to +construct variants of existing functions that have some of the +parameters filled in. Consider a Python function ``f(a, b, c)``; you +may wish to create a new function ``g(b, c)`` that's equivalent to +``f(1, b, c)``; you're filling in a value for one of ``f()``'s parameters. +This is called "partial function application". + +The constructor for ``partial`` takes the arguments ``(function, arg1, +arg2, ... kwarg1=value1, kwarg2=value2)``. The resulting object is +callable, so you can just call it to invoke ``function`` with the +filled-in arguments. + +Here's a small but realistic example:: + + import functools + + def log (message, subsystem): + "Write the contents of 'message' to the specified subsystem." + print '%s: %s' % (subsystem, message) + ... + + server_log = functools.partial(log, subsystem='server') + server_log('Unable to open socket') + + +The operator module +------------------- + +The ``operator`` module was mentioned earlier. It contains a set of +functions corresponding to Python's operators. These functions +are often useful in functional-style code because they save you +from writing trivial functions that perform a single operation. + +Some of the functions in this module are: + +* Math operations: ``add()``, ``sub()``, ``mul()``, ``div()``, ``floordiv()``, + ``abs()``, ... +* Logical operations: ``not_()``, ``truth()``. +* Bitwise operations: ``and_()``, ``or_()``, ``invert()``. +* Comparisons: ``eq()``, ``ne()``, ``lt()``, ``le()``, ``gt()``, and ``ge()``. +* Object identity: ``is_()``, ``is_not()``. + +Consult `the operator module's documentation `__ for a complete +list. + + + +The functional module +--------------------- + +Collin Winter's `functional module `__ +provides a number of more +advanced tools for functional programming. It also reimplements +several Python built-ins, trying to make them more intuitive to those +used to functional programming in other languages. + +This section contains an introduction to some of the most important +functions in ``functional``; full documentation can be found at `the +project's website `__. + +``compose(outer, inner, unpack=False)`` + +The ``compose()`` function implements function composition. +In other words, it returns a wrapper around the ``outer`` and ``inner`` callables, such +that the return value from ``inner`` is fed directly to ``outer``. That is, + +:: + + >>> def add(a, b): + ... return a + b + ... + >>> def double(a): + ... return 2 * a + ... + >>> compose(double, add)(5, 6) + 22 + +is equivalent to + +:: + + >>> double(add(5, 6)) + 22 + +The ``unpack`` keyword is provided to work around the fact that Python functions are not always +`fully curried `__. +By default, it is expected that the ``inner`` function will return a single object and that the ``outer`` +function will take a single argument. Setting the ``unpack`` argument causes ``compose`` to expect a +tuple from ``inner`` which will be expanded before being passed to ``outer``. Put simply, + +:: + + compose(f, g)(5, 6) + +is equivalent to:: + + f(g(5, 6)) + +while + +:: + + compose(f, g, unpack=True)(5, 6) + +is equivalent to:: + + f(*g(5, 6)) + +Even though ``compose()`` only accepts two functions, it's trivial to +build up a version that will compose any number of functions. We'll +use ``reduce()``, ``compose()`` and ``partial()`` (the last of which +is provided by both ``functional`` and ``functools``). + +:: + + from functional import compose, partial + + multi_compose = partial(reduce, compose) + + +We can also use ``map()``, ``compose()`` and ``partial()`` to craft a +version of ``"".join(...)`` that converts its arguments to string:: + + from functional import compose, partial + + join = compose("".join, partial(map, str)) + + +``flip(func)`` + +``flip()`` wraps the callable in ``func`` and +causes it to receive its non-keyword arguments in reverse order. + +:: + + >>> def triple(a, b, c): + ... return (a, b, c) + ... + >>> triple(5, 6, 7) + (5, 6, 7) + >>> + >>> flipped_triple = flip(triple) + >>> flipped_triple(5, 6, 7) + (7, 6, 5) + +``foldl(func, start, iterable)`` + +``foldl()`` takes a binary function, a starting value (usually some kind of 'zero'), and an iterable. +The function is applied to the starting value and the first element of the list, then the result of +that and the second element of the list, then the result of that and the third element of the list, +and so on. + +This means that a call such as:: + + foldl(f, 0, [1, 2, 3]) + +is equivalent to:: + + f(f(f(0, 1), 2), 3) + + +``foldl()`` is roughly equivalent to the following recursive function:: + + def foldl(func, start, seq): + if len(seq) == 0: + return start + + return foldl(func, func(start, seq[0]), seq[1:]) + +Speaking of equivalence, the above ``foldl`` call can be expressed in terms of the built-in ``reduce`` like +so:: + + reduce(f, [1, 2, 3], 0) + + +We can use ``foldl()``, ``operator.concat()`` and ``partial()`` to +write a cleaner, more aesthetically-pleasing version of Python's +``"".join(...)`` idiom:: + + from functional import foldl, partial + from operator import concat + + join = partial(foldl, concat, "") + + +Revision History and Acknowledgements +------------------------------------------------ + +The author would like to thank the following people for offering +suggestions, corrections and assistance with various drafts of this +article: Ian Bicking, Nick Coghlan, Nick Efford, Raymond Hettinger, +Jim Jewett, Mike Krell, Leandro Lameiro, Jussi Salmela, +Collin Winter, Blake Winton. + +Version 0.1: posted June 30 2006. + +Version 0.11: posted July 1 2006. Typo fixes. + +Version 0.2: posted July 10 2006. Merged genexp and listcomp +sections into one. Typo fixes. + +Version 0.21: Added more references suggested on the tutor mailing list. + +Version 0.30: Adds a section on the ``functional`` module written by +Collin Winter; adds short section on the operator module; a few other +edits. + + +References +-------------------- + +General +''''''''''''''' + +**Structure and Interpretation of Computer Programs**, by +Harold Abelson and Gerald Jay Sussman with Julie Sussman. +Full text at http://mitpress.mit.edu/sicp/. +In this classic textbook of computer science, chapters 2 and 3 discuss the +use of sequences and streams to organize the data flow inside a +program. The book uses Scheme for its examples, but many of the +design approaches described in these chapters are applicable to +functional-style Python code. + +http://www.defmacro.org/ramblings/fp.html: A general +introduction to functional programming that uses Java examples +and has a lengthy historical introduction. + +http://en.wikipedia.org/wiki/Functional_programming: +General Wikipedia entry describing functional programming. + +http://en.wikipedia.org/wiki/Coroutine: +Entry for coroutines. + +http://en.wikipedia.org/wiki/Currying: +Entry for the concept of currying. + +Python-specific +''''''''''''''''''''''''''' + +http://gnosis.cx/TPiP/: +The first chapter of David Mertz's book :title-reference:`Text Processing in Python` +discusses functional programming for text processing, in the section titled +"Utilizing Higher-Order Functions in Text Processing". + +Mertz also wrote a 3-part series of articles on functional programming +for IBM's DeveloperWorks site; see +`part 1 `__, +`part 2 `__, and +`part 3 `__, + + +Python documentation +''''''''''''''''''''''''''' + +http://docs.python.org/lib/module-itertools.html: +Documentation for the ``itertools`` module. + +http://docs.python.org/lib/module-operator.html: +Documentation for the ``operator`` module. + +http://www.python.org/dev/peps/pep-0289/: +PEP 289: "Generator Expressions" + +http://www.python.org/dev/peps/pep-0342/ +PEP 342: "Coroutines via Enhanced Generators" describes the new generator +features in Python 2.5. + +.. comment + + Topics to place + ----------------------------- + + XXX os.walk() + + XXX Need a large example. + + But will an example add much? I'll post a first draft and see + what the comments say. + +.. comment + + Original outline: + Introduction + Idea of FP + Programs built out of functions + Functions are strictly input-output, no internal state + Opposed to OO programming, where objects have state + + Why FP? + Formal provability + Assignment is difficult to reason about + Not very relevant to Python + Modularity + Small functions that do one thing + Debuggability: + Easy to test due to lack of state + Easy to verify output from intermediate steps + Composability + You assemble a toolbox of functions that can be mixed + + Tackling a problem + Need a significant example + + Iterators + Generators + The itertools module + List comprehensions + Small functions and the lambda statement + Built-in functions + map + filter + reduce + +.. comment + + Handy little function for printing part of an iterator -- used + while writing this document. + + import itertools + def print_iter(it): + slice = itertools.islice(it, 10) + for elem in slice[:-1]: + sys.stdout.write(str(elem)) + sys.stdout.write(', ') + print elem[-1] + + Added: external/Pygments-0.8.1/tests/examplefiles/genshi_example.xml+genshi ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/genshi_example.xml+genshi Thu Aug 9 17:43:13 2007 @@ -0,0 +1,193 @@ + + + + + $title + + + + + + + + (${v or 'No'} match${v != 1 and 'es' or ''}) + + +
    +

    $title ${num_matches(len(tickets))}

    + +
    +
    + Filters + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +   + + +
    +
    + +

    + + + + +

    + +

    + + +

    + +
    + + + +
    +
    +
    + + + + + +
    + Note: See TracQuery + for help on using queries. +
    + +
    + + Added: external/Pygments-0.8.1/tests/examplefiles/genshitext_example.genshitext ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/genshitext_example.genshitext Thu Aug 9 17:43:13 2007 @@ -0,0 +1,33 @@ + ## a comment + +\## not a comment + +#if foo + ${bar} +#endif + +The answer is: +#choose + #when 0 == 1 + 0 + #end + #when 1 == 1 + 1 + #end + #otherwise + 2 + #end +#end -- comment about choose + +#for item in items + * ${item} +#end + +#def greeting(name) + Hello, ${name}! +#end +${greeting('world')} + +#with y=7; z=x+10 + $x $y $z +#end Added: external/Pygments-0.8.1/tests/examplefiles/html+php_faulty.php ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/html+php_faulty.php Thu Aug 9 17:43:13 2007 @@ -0,0 +1 @@ + + + + My Webpage + + + + +

    My Webpage

    + {{ variable }} + + + +This covers the default settings. The application developer might have changed +the syntax from ``{% foo %}`` to ``<% foo %>`` or something similar. This +documentation just covers the default values. + +A variable looks like ``{{ foobar }}`` where foobar is the variable name. Inside +of statements (``{% some content here %}``) variables are just normal names +without the braces around it. In fact ``{{ foobar }}`` is just an alias for +the statement ``{% print foobar %}``. + +Variables are coming from the context provided by the application. Normally there +should be a documentation regarding the context contents but if you want to know +the content of the current context, you can add this to your template: + +.. sourcecode:: html+jinja + + 
    {{ debug()|e }}
    + +A context isn't flat which means that each variable can has subvariables, as long +as it is representable as python data structure. You can access attributes of +a variable using the dot and bracket operators. The following examples show +this: + +.. sourcecode:: jinja + + {{ user.username }} + is the same as + {{ user['username'] }} + you can also use a variable to access an attribute: + {{ users[current_user].username }} + If you have numerical indices you have to use the [] syntax: + {{ users[0].username }} + +Filters +======= + +In the examples above you might have noticed the pipe symbols. Pipe symbols tell +the engine that it has to apply a filter on the variable. Here is a small example: + +.. sourcecode:: jinja + + {{ variable|replace('foo', 'bar')|escape }} + +If you want, you can also put whitespace between the filters. + +This will look for a variable `variable`, pass it to the filter `replace` +with the arguments ``'foo'`` and ``'bar'``, and pass the result to the filter +`escape` that automatically XML-escapes the value. The `e` filter is an alias for +`escape`. Here is the complete list of supported filters: + +[[list_of_filters]] + +.. admonition:: note + + Filters have a pretty low priority. If you want to add fitered values + you have to put them into parentheses. The same applies if you want to access + attributes: + + .. sourcecode:: jinja + + correct: + {{ (foo|filter) + (bar|filter) }} + wrong: + {{ foo|filter + bar|filter }} + + correct: + {{ (foo|filter).attribute }} + wrong: + {{ foo|filter.attribute }} + +Tests +===== + +You can use the `is` operator to perform tests on a value: + +.. sourcecode:: jinja + + {{ 42 is numeric }} -> true + {{ "foobar" is numeric }} -> false + {{ 'FOO' is upper }} -> true + +These tests are especially useful when used in `if` conditions. + +[[list_of_tests]] + +Global Functions +================ + +Test functions and filter functions live in their own namespace. Global +functions not. They behave like normal objects in the context. Beside the +functions added by the application or framewhere there are two functions +available per default: + +`range` + + Works like the python `range function`_ just that it doesn't support + ranges greater than ``1000000``. + +`debug` + + Function that outputs the contents of the context. + +Loops +===== + +To iterate over a sequence, you can use the `for` loop. It basically looks like a +normal Python `for` loop and works pretty much the same: + +.. sourcecode:: html+jinja + +

    Members

    +
      + {% for user in users %} +
    • {{ loop.index }} / {{ loop.length }} - {{ user.username|escape }}
      • + {% else %} +
    • no users found
      • + {% endfor %} +
    + +*Important* Contrary to Python is the optional ``else`` block only +executed if there was no iteration because the sequence was empty. + +Inside of a `for` loop block you can access some special variables: + ++----------------------+----------------------------------------+ +| Variable | Description | ++======================+========================================+ +| `loop.index` | The current iteration of the loop. | ++----------------------+----------------------------------------+ +| `loop.index0` | The current iteration of the loop, | +| | starting counting by 0. | ++----------------------+----------------------------------------+ +| `loop.revindex` | The number of iterations from the end | +| | of the loop. | ++----------------------+----------------------------------------+ +| `loop.revindex0` | The number of iterations from the end | +| | of the loop, starting counting by 0. | ++----------------------+----------------------------------------+ +| `loop.first` | True if first iteration. | ++----------------------+----------------------------------------+ +| `loop.last` | True if last iteration. | ++----------------------+----------------------------------------+ +| `loop.even` | True if current iteration is even. | ++----------------------+----------------------------------------+ +| `loop.odd` | True if current iteration is odd. | ++----------------------+----------------------------------------+ +| `loop.length` | Total number of items in the sequence. | ++----------------------+----------------------------------------+ +| `loop.parent` | The context of the parent loop. | ++----------------------+----------------------------------------+ + +Loops also support recursion. Let's assume you have a sitemap where each item +might have a number of child items. A template for that could look like this: + +.. sourcecode:: html+jinja + +

    Sitemap +
      + {% for item in sitemap recursive %} +
    • {{ item.title|e }} + {% if item.children %}
        {{ loop(item.children) }}
      {% endif %}
      • + {% endfor %} +
    + +What happens here? Basically the first thing that is different to a normal +loop is the additional ``recursive`` modifier in the `for`-loop declaration. +It tells the template engine that we want recursion. If recursion is enabled +the special `loop` variable is callable. If you call it with a sequence it will +automatically render the loop at that position with the new sequence as argument. + +Cycling +======= + +Sometimes you might want to have different text snippets for each row in a list, +for example to have alternating row colors. You can easily do this by using the +``{% cycle %}`` tag: + +.. sourcecode:: html+jinja + +
      + {% for message in messages %} +
    • {{ message|e }}
      • + {% endfor %} +
    + +Each time Jinja encounters a `cycle` tag it will cycle through the list +of given items and return the next one. If you pass it one item jinja assumes +that this item is a sequence from the context and uses this: + +.. sourcecode:: html+jinja + +
  • ...
    • + +Conditions +========== + +Jinja supports Python-like `if` / `elif` / `else` constructs: + +.. sourcecode:: jinja + + {% if user.active %} + user {{ user.name|e }} is active. + {% elif user.deleted %} + user {{ user.name|e }} was deleted some time ago. + {% else %} + i don't know what's wrong with {{ user.username|e }} + {% endif %} + +If the user is active the first block is rendered. If not and the user was +deleted the second one, in all other cases the third one. + +You can also use comparison operators: + +.. sourcecode:: html+jinja + + {% if amount < 0 %} + {{ amount }} + {% else %} + {{ amount }} + {% endif %} + +.. admonition:: Note + + Of course you can use `or` / `and` and parentheses to create more complex + conditions, but usually the logic is already handled in the application and + you don't have to create such complex constructs in the template code. However + in some situations it might be a good thing to have the abilities to create + them. + +Operators +========= + +Inside ``{{ variable }}`` blocks, `if` conditions and many other parts you can +can use expressions. In expressions you can use any of the following operators: + + ======= =================================================================== + ``+`` add the right operand to the left one. + ``{{ 1 + 2 }}`` would return ``3``. + ``-`` subtract the right operand from the left one. + ``{{ 1 - 1 }}`` would return ``0``. + ``/`` divide the left operand by the right one. + ``{{ 1 / 2 }}`` would return ``0.5``. + ``*`` multiply the left operand with the right one. + ``{{ 2 * 2 }}`` would return ``4``. + ``**`` raise the left operand to the power of the right + operand. ``{{ 2**3 }}`` would return ``8``. + ``in`` perform sequence membership test. ``{{ 1 in [1,2,3] }}`` would + return true. + ``is`` perform a test on the value. See the section about + tests for more information. + ``|`` apply a filter on the value. See the section about + filters for more information. + ``and`` return true if the left and the right operand is true. + ``or`` return true if the left or the right operand is true. + ``not`` negate a statement (see below) + ``()`` call a callable: ``{{ user.get_username() }}``. Inside of the + parentheses you can use variables: ``{{ user.get(username) }}``. + ======= =================================================================== + +Note that there is no support for any bit operations or something similar. + +* special note regarding `not`: The `is` and `in` operators support negation + using an infix notation too: ``foo is not bar`` and ``foo not in bar`` + instead of ``not foo is bar`` and ``not foo in bar``. All other expressions + require a prefix notation: ``not (foo and bar)``. + +Boolean Values +============== + +In If-Conditions Jinja performs a boolean check. All empty values (eg: empty +lists ``[]``, empty dicts ``{}`` etc) evaluate to `false`. Numbers that are +equal to `0`/`0.00` are considered `false` too. The boolean value of other +objects depends on the behavior the application developer gave it. Usually +items are `true`. + +Here some examples that should explain it: + +.. sourcecode:: jinja + + {% if [] %} + will always be false because it's an empty list + + {% if {} %} + false too. + + {% if ['foo'] %} + this is true. Because the list is not empty. + + {% if "foobar" %} + this is also true because the string is not empty. + +Slicing +======= + +Some objects support slicing operations. For example lists: + +.. sourcecode:: jinja + + {% for item in items[:5] %} + This will only iterate over the first 5 items of the list + + {% for item in items[5:10] %} + This will only iterate from item 5 to 10. + + {% for item in items[:10:2] %} + This will only yield items from start to ten and only returing + even items. + +For more informations about slicing have a look at the `slicing chapter`_ +in the "Dive into Python" e-book. + +Macros +====== + +If you want to use a partial template in more than one place, you might want to +create a macro from it: + +.. sourcecode:: html+jinja + + {% macro show_user user %} +

    {{ user.name|e }}

    +
    + {{ user.description }} +
    + {% endmacro %} + +Now you can use it from everywhere in the code by passing it an item: + +.. sourcecode:: jinja + + {% for user in users %} + {{ show_user(user) }} + {% endfor %} + +You can also specify more than one value: + +.. sourcecode:: html+jinja + + {% macro show_dialog title, text %} +
    +

    {{ title|e }}

    +
    {{ text|e }}
    +
    + {% endmacro %} + + {{ show_dialog('Warning', 'something went wrong i guess') }} + +Inheritance +=========== + +The most powerful part of Jinja is template inheritance. Template inheritance +allows you to build a base "skeleton" template that contains all the common +elements of your site and defines **blocks** that child templates can override. + +Sounds complicated but is very basic. It's easiest to understand it by starting +with an example. + +Base Template +------------- + +This template, which we'll call ``base.html``, defines a simple HTML skeleton +document that you might use for a simple two-column page. It's the job of +"child" templates to fill the empty blocks with content: + +.. sourcecode:: html+jinja + + + + + + {% block title %}{% endblock %} - My Webpage + {% block html_head %}{% endblock %} + + +
    + {% block content %}{% endblock %} +
    + + + + +In this example, the ``{% block %}`` tags define four blocks that child templates +can fill in. All the `block` tag does is to tell the template engine that a +child template may override those portions of the template. + +Child Template +-------------- + +A child template might look like this: + +.. sourcecode:: html+jinja + + {% extends "base.html" %} + {% block title %}Index{% endblock %} + + {% block html_head %} + + {% endblock %} + + {% block content %} +

    Index

    +

    + Welcome on my awsome homepage. +

    + {% endblock %} + +The ``{% extends %}`` tag is the key here. It tells the template engine that +this template "extends" another template. When the template system evaluates +this template, first it locates the parent. + +The filename of the template depends on the template loader. For example the +``FileSystemLoader`` allows you to access other templates by giving the +filename. You can access templates in subdirectories with an slash: + +.. sourcecode:: jinja + + {% extends "layout/default.html" %} + +But this behavior can depend on the application using Jinja. + +Note that since the child template didn't define the ``footer`` block, the +value from the parent template is used instead. + +.. admonition:: Note + + You can't define multiple ``{% block %}`` tags with the same name in the + same template. This limitation exists because a block tag works in "both" + directions. That is, a block tag doesn't just provide a hole to fill - it + also defines the content that fills the hole in the *parent*. If there were + two similarly-named ``{% block %}`` tags in a template, that template's + parent wouldn't know which one of the blocks' content to use. + +Template Inclusion +================== + +You can load another template at a given position using ``{% include %}``. +Usually it's a better idea to use inheritance but if you for example want to +load macros, `include` works better than `extends`: + +.. sourcecode:: jinja + + {% include "myhelpers.html" %} + {{ my_helper("foo") }} + +If you define a macro called ``my_helper`` in ``myhelpers.html``, you can now +use it from the template as shown above. + +Filtering Blocks +================ + +Sometimes it could be a good idea to filter a complete block of text. For +example, if you want to escape some html code: + +.. sourcecode:: jinja + + {% filter escape %} + + goes here + + {% endfilter %} + +Of course you can chain filters too: + +.. sourcecode:: jinja + + {% filter lower|escape %} + SOME TEXT + {% endfilter %} + +returns ``"<b>some text</b>"``. + +Defining Variables +================== + +You can also define variables in the namespace using the ``{% set %}`` tag: + +.. sourcecode:: jinja + + {% set foo = 'foobar' %} + {{ foo }} + +This should ouput ``foobar``. + +Scopes +====== + +Jinja has multiple scopes. A scope is something like a new transparent foil on +a stack of foils. You can only write to the outermost foil but read all of them +since you can look through them. If you remove the top foil all data on that +foil disappears. Some tags in Jinja add a new layer to the stack. Currently +these are `block`, `for`, `macro` and `filter`. This means that variables and +other elements defined inside a macro, loop or some of the other tags listed +above will be only available in that block. Here an example: + +.. sourcecode:: jinja + + {% macro angryhello name %} + {% set angryname = name|upper %} + Hello {{ name }}. Hello {{ name }}! + HELLO {{ angryname }}!!!!!!111 + {% endmacro %} + +The variable ``angryname`` just exists inside the macro, not outside it. + +Defined macros appear on the context as variables. Because of this, they are +affected by the scoping too. A macro defined inside of a macro is just available +in those two macros (the macro itself and the macro it's defined in). For `set` +and `macro` two additional rules exist: If a macro is defined in an extended +template but outside of a visible block (thus outside of any block) will be +available in all blocks below. This allows you to use `include` statements to +load often used macros at once. + +Undefined Variables +=================== + +If you have already worked with python you probably know about the fact that +undefined variables raise an exception. This is different in Jinja. There is a +special value called `undefined` that represents values that do not exist. + +This special variable works complete different from any variables you maybe +know. If you print it using ``{{ variable }}`` it will not appear because it's +literally empty. If you try to iterate over it, it will work. But no items +are returned. Comparing this value to any other value results in `false`. +Even if you compare it to itself: + +.. sourcecode:: jinja + + {{ undefined == undefined }} + will return false. Not even undefined is undefined :) + Use `is defined` / `is not defined`: + + {{ undefined is not defined }} + will return true. + +There are also some additional rules regarding this special value. Any +mathematical operators (``+``, ``-``, ``*``, ``/``) return the operand +as result: + +.. sourcecode:: jinja + + {{ undefined + "foo" }} + returns "foo" + + {{ undefined - 42 }} + returns 42. Note: not -42! + +In any expression `undefined` evaluates to `false`. It has no length, all +attribute calls return undefined, calling too: + +.. sourcecode:: jinja + + {{ undefined.attribute().attribute_too[42] }} + still returns `undefined`. + +Escaping +======== + +Sometimes you might want to add Jinja syntax elements into the template +without executing them. In that case you have quite a few possibilities. + +For small parts this might be a good way: + +.. sourcecode:: jinja + + {{ "{{ foo }} is variable syntax and {% foo %} is block syntax" }} + +When you have multiple elements you can use the ``raw`` block: + +.. sourcecode:: jinja + + {% raw %} + Filtering blocks works like this in Jinja: + {% filter escape %} + + goes here + + {% endfilter %} + {% endraw %} + +Reserved Keywords +================= + +Jinja has some keywords you cannot use a variable names. This limitation +exists to make look coherent. Syntax highlighters won't mess things up and +you will don't have unexpected output. + +The following keywords exist and cannot be used as identifiers: + + `and`, `block`, `cycle`, `elif`, `else`, `endblock`, `endfilter`, + `endfor`, `endif`, `endmacro`, `endraw`, `endtrans`, `extends`, `filter`, + `for`, `if`, `in`, `include`, `is`, `macro`, `not`, `or`, `pluralize`, + `raw`, `recursive`, `set`, `trans` + +If you want to use such a name you have to prefix or suffix it or use +alternative names: + +.. sourcecode:: jinja + + {% for macro_ in macros %} + {{ macro_('foo') }} + {% endfor %} + +If future Jinja releases add new keywords those will be "light" keywords which +means that they won't raise an error for several releases but yield warnings +on the application side. But it's very unlikely that new keywords will be +added. + +Internationalization +==================== + +If the application is configured for i18n, you can define translatable blocks +for translators using the `trans` tag or the special underscore function: + +.. sourcecode:: jinja + + {% trans %} + this is a translatable block + {% endtrans %} + + {% trans "This is a translatable string" %} + + {{ _("This is a translatable string") }} + +The latter one is useful if you want translatable arguments for filters etc. + +If you want to have plural forms too, use the `pluralize` block: + +.. sourcecode:: jinja + + {% trans users=users %} + One user found. + {% pluralize %} + {{ users }} users found. + {% endtrans %} + + {% trans first=(users|first).username|escape, user=users|length %} + one user {{ first }} found. + {% pluralize users %} + {{ users }} users found, the first one is called {{ first }}. + {% endtrans %} + +If you have multiple arguments, the first one is assumed to be the indicator (the +number that is used to determine the correct singular or plural form. If you +don't have the indicator variable on position 1 you have to tell the `pluralize` +tag the correct variable name. + +Inside translatable blocks you cannot use blocks or expressions (however you can +still use the ``raw`` block which will work as expected). The variable +print syntax (``{{ variablename }}``) is the only way to insert the variables +defined in the ``trans`` header. Filters must be applied in the header. + +.. admonition:: note + + Please make sure that you always use pluralize blocks where required. + Many languages have more complex plural forms than the English language. + + Never try to workaround that issue by using something like this: + + .. sourcecode:: jinja + + {% if count != 1 %} + {{ count }} users found. + {% else %} + one user found. + {% endif %} + +.. _slicing chapter: http://diveintopython.org/native_data_types/lists.html#odbchelper.list.slice +.. _range function: http://docs.python.org/tut/node6.html#SECTION006300000000000000000 Added: external/Pygments-0.8.1/tests/examplefiles/ltmain.sh ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/ltmain.sh Thu Aug 9 17:43:13 2007 @@ -0,0 +1,2849 @@ +# ltmain.sh - Provide generalized library-building support services. +# NOTE: Changing this file will not affect anything until you rerun configure. +# +# Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2003, 2004, 2005 +# Free Software Foundation, Inc. +# Originally by Gordon Matzigkeit , 1996 +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# +# As a special exception to the GNU General Public License, if you +# distribute this file as part of a program that contains a +# configuration script generated by Autoconf, you may include it under +# the same distribution terms that you use for the rest of that program. + +basename="s,^.*/,,g" + +# Work around backward compatibility issue on IRIX 6.5. On IRIX 6.4+, sh +# is ksh but when the shell is invoked as "sh" and the current value of +# the _XPG environment variable is not equal to 1 (one), the special +# positional parameter $0, within a function call, is the name of the +# function. +progpath="$0" + +# define SED for historic ltconfig's generated by Libtool 1.3 +test -z "$SED" && SED=sed + +# The name of this program: +progname=`echo "$progpath" | $SED $basename` +modename="$progname" + +# Global variables: +EXIT_SUCCESS=0 +EXIT_FAILURE=1 + +PROGRAM=ltmain.sh +PACKAGE=libtool +VERSION=1.5.22 +TIMESTAMP=" (1.1220.2.365 2005/12/18 22:14:06)" + +# See if we are running on zsh, and set the options which allow our +# commands through without removal of \ escapes. +if test -n "${ZSH_VERSION+set}" ; then + setopt NO_GLOB_SUBST +fi +# Same for EGREP, and just to be sure, do LTCC as well +if test "X$EGREP" = X ; then + EGREP=egrep +fi +if test "X$LTCC" = X ; then + LTCC=${CC-gcc} +fi + +# Check that we have a working $echo. +if test "X$1" = X--no-reexec; then + # Discard the --no-reexec flag, and continue. + shift +elif test "X$1" = X--fallback-echo; then + # Avoid inline document here, it may be left over + : +elif test "X`($echo '\t') 2>/dev/null`" = 'X\t'; then + # Yippee, $echo works! + : +else + # Restart under the correct shell, and then maybe $echo will work. + exec $SHELL "$progpath" --no-reexec ${1+"$@"} +fi + +if test "X$1" = X--fallback-echo; then + # used as fallback echo + shift + cat <&2 + $echo "Fatal configuration error. See the $PACKAGE docs for more information." 1>&2 + exit $EXIT_FAILURE +fi + +# Global variables. +mode=$default_mode +nonopt= +prev= +prevopt= +run= +show="$echo" +show_help= +execute_dlfiles= +duplicate_deps=no +preserve_args= +lo2o="s/\\.lo\$/.${objext}/" +o2lo="s/\\.${objext}\$/.lo/" + +if test -z "$max_cmd_len"; then + i=0 + testring="ABCD" + new_result= + + # If test is not a shell built-in, we'll probably end up computing a + # maximum length that is only half of the actual maximum length, but + # we can't tell. + while (test "X"`$SHELL $0 --fallback-echo "X$testring" 2>/dev/null` \ + = "XX$testring") >/dev/null 2>&1 && + new_result=`expr "X$testring" : ".*" 2>&1` && + max_cmd_len="$new_result" && + test "$i" != 17 # 1/2 MB should be enough + do + i=`expr $i + 1` + testring="$testring$testring" + done + testring= + # Add a significant safety factor because C++ compilers can tack on massive + # amounts of additional arguments before passing them to the linker. + # It appears as though 1/2 is a usable value. + max_cmd_len=`expr $max_cmd_len \/ 2` +fi + +##################################### +# Shell function definitions: +# This seems to be the best place for them + +# func_mktempdir [string] +# Make a temporary directory that won't clash with other running +# libtool processes, and avoids race conditions if possible. If +# given, STRING is the basename for that directory. +func_mktempdir () +{ + my_template="${TMPDIR-/tmp}/${1-$progname}" + + if test "$run" = ":"; then + # Return a directory name, but don't create it in dry-run mode + my_tmpdir="${my_template}-$$" + else + + # If mktemp works, use that first and foremost + my_tmpdir=`mktemp -d "${my_template}-XXXXXXXX" 2>/dev/null` + + if test ! -d "$my_tmpdir"; then + # Failing that, at least try and use $RANDOM to avoid a race + my_tmpdir="${my_template}-${RANDOM-0}$$" + + save_mktempdir_umask=`umask` + umask 0077 + $mkdir "$my_tmpdir" + umask $save_mktempdir_umask + fi + + # If we're not in dry-run mode, bomb out on failure + test -d "$my_tmpdir" || { + $echo "cannot create temporary directory \`$my_tmpdir'" 1>&2 + exit $EXIT_FAILURE + } + fi + + $echo "X$my_tmpdir" | $Xsed +} + + +# func_win32_libid arg +# return the library type of file 'arg' +# +# Need a lot of goo to handle *both* DLLs and import libs +# Has to be a shell function in order to 'eat' the argument +# that is supplied when $file_magic_command is called. +func_win32_libid () +{ + win32_libid_type="unknown" + win32_fileres=`file -L $1 2>/dev/null` + case $win32_fileres in + *ar\ archive\ import\ library*) # definitely import + win32_libid_type="x86 archive import" + ;; + *ar\ archive*) # could be an import, or static + if eval $OBJDUMP -f $1 | $SED -e '10q' 2>/dev/null | \ + $EGREP -e 'file format pe-i386(.*architecture: i386)?' >/dev/null ; then + win32_nmres=`eval $NM -f posix -A $1 | \ + $SED -n -e '1,100{/ I /{s,.*,import,;p;q;};}'` + case $win32_nmres in + import*) win32_libid_type="x86 archive import";; + *) win32_libid_type="x86 archive static";; + esac + fi + ;; + *DLL*) + win32_libid_type="x86 DLL" + ;; + *executable*) # but shell scripts are "executable" too... + case $win32_fileres in + *MS\ Windows\ PE\ Intel*) + win32_libid_type="x86 DLL" + ;; + esac + ;; + esac + $echo $win32_libid_type +} + + +# func_infer_tag arg +# Infer tagged configuration to use if any are available and +# if one wasn't chosen via the "--tag" command line option. +# Only attempt this if the compiler in the base compile +# command doesn't match the default compiler. +# arg is usually of the form 'gcc ...' +func_infer_tag () +{ + if test -n "$available_tags" && test -z "$tagname"; then + CC_quoted= + for arg in $CC; do + case $arg in + *[\[\~\#\^\&\*\(\)\{\}\|\;\<\>\?\'\ \ ]*|*]*|"") + arg="\"$arg\"" + ;; + esac + CC_quoted="$CC_quoted $arg" + done + case $@ in + # Blanks in the command may have been stripped by the calling shell, + # but not from the CC environment variable when configure was run. + " $CC "* | "$CC "* | " `$echo $CC` "* | "`$echo $CC` "* | " $CC_quoted"* | "$CC_quoted "* | " `$echo $CC_quoted` "* | "`$echo $CC_quoted` "*) ;; + # Blanks at the start of $base_compile will cause this to fail + # if we don't check for them as well. + *) + for z in $available_tags; do + if grep "^# ### BEGIN LIBTOOL TAG CONFIG: $z$" < "$progpath" > /dev/null; then + # Evaluate the configuration. + eval "`${SED} -n -e '/^# ### BEGIN LIBTOOL TAG CONFIG: '$z'$/,/^# ### END LIBTOOL TAG CONFIG: '$z'$/p' < $progpath`" + CC_quoted= + for arg in $CC; do + # Double-quote args containing other shell metacharacters. + case $arg in + *[\[\~\#\^\&\*\(\)\{\}\|\;\<\>\?\'\ \ ]*|*]*|"") + arg="\"$arg\"" + ;; + esac + CC_quoted="$CC_quoted $arg" + done + # user sometimes does CC=-gcc so we need to match that to 'gcc' + trimedcc=`echo ${CC} | $SED -e "s/${host}-//g"` + # and sometimes libtool has CC=-gcc but user does CC=gcc + extendcc=${host}-${CC} + # and sometimes libtool has CC=-gcc but user has CC=-gcc + # (Gentoo-specific hack because we always export $CHOST) + mungedcc=${CHOST-${host}}-${trimedcc} + case "$@ " in + "cc "* | " cc "* | "${host}-cc "* | " ${host}-cc "*|\ + "gcc "* | " gcc "* | "${host}-gcc "* | " ${host}-gcc "*) + tagname=CC + break ;; + "$trimedcc "* | " $trimedcc "* | "`$echo $trimedcc` "* | " `$echo $trimedcc` "*|\ + "$extendcc "* | " $extendcc "* | "`$echo $extendcc` "* | " `$echo $extendcc` "*|\ + "$mungedcc "* | " $mungedcc "* | "`$echo $mungedcc` "* | " `$echo $mungedcc` "*|\ + " $CC "* | "$CC "* | " `$echo $CC` "* | "`$echo $CC` "* | " $CC_quoted"* | "$CC_quoted "* | " `$echo $CC_quoted` "* | "`$echo $CC_quoted` "*) + # The compiler in the base compile command matches + # the one in the tagged configuration. + # Assume this is the tagged configuration we want. + tagname=$z + break + ;; + esac + fi + done + # If $tagname still isn't set, then no tagged configuration + # was found and let the user know that the "--tag" command + # line option must be used. + if test -z "$tagname"; then + $echo "$modename: unable to infer tagged configuration" + $echo "$modename: specify a tag with \`--tag'" 1>&2 + exit $EXIT_FAILURE +# else +# $echo "$modename: using $tagname tagged configuration" + fi + ;; + esac + fi +} + + +# func_extract_an_archive dir oldlib +func_extract_an_archive () +{ + f_ex_an_ar_dir="$1"; shift + f_ex_an_ar_oldlib="$1" + + $show "(cd $f_ex_an_ar_dir && $AR x $f_ex_an_ar_oldlib)" + $run eval "(cd \$f_ex_an_ar_dir && $AR x \$f_ex_an_ar_oldlib)" || exit $? + if ($AR t "$f_ex_an_ar_oldlib" | sort | sort -uc >/dev/null 2>&1); then + : + else + $echo "$modename: ERROR: object name conflicts: $f_ex_an_ar_dir/$f_ex_an_ar_oldlib" 1>&2 + exit $EXIT_FAILURE + fi +} + +# func_extract_archives gentop oldlib ... +func_extract_archives () +{ + my_gentop="$1"; shift + my_oldlibs=${1+"$@"} + my_oldobjs="" + my_xlib="" + my_xabs="" + my_xdir="" + my_status="" + + $show "${rm}r $my_gentop" + $run ${rm}r "$my_gentop" + $show "$mkdir $my_gentop" + $run $mkdir "$my_gentop" + my_status=$? + if test "$my_status" -ne 0 && test ! -d "$my_gentop"; then + exit $my_status + fi + + for my_xlib in $my_oldlibs; do + # Extract the objects. + case $my_xlib in + [\\/]* | [A-Za-z]:[\\/]*) my_xabs="$my_xlib" ;; + *) my_xabs=`pwd`"/$my_xlib" ;; + esac + my_xlib=`$echo "X$my_xlib" | $Xsed -e 's%^.*/%%'` + my_xdir="$my_gentop/$my_xlib" + + $show "${rm}r $my_xdir" + $run ${rm}r "$my_xdir" + $show "$mkdir $my_xdir" + $run $mkdir "$my_xdir" + exit_status=$? + if test "$exit_status" -ne 0 && test ! -d "$my_xdir"; then + exit $exit_status + fi + case $host in + *-darwin*) + $show "Extracting $my_xabs" + # Do not bother doing anything if just a dry run + if test -z "$run"; then + darwin_orig_dir=`pwd` + cd $my_xdir || exit $? + darwin_archive=$my_xabs + darwin_curdir=`pwd` + darwin_base_archive=`$echo "X$darwin_archive" | $Xsed -e 's%^.*/%%'` + darwin_arches=`lipo -info "$darwin_archive" 2>/dev/null | $EGREP Architectures 2>/dev/null` + if test -n "$darwin_arches"; then + darwin_arches=`echo "$darwin_arches" | $SED -e 's/.*are://'` + darwin_arch= + $show "$darwin_base_archive has multiple architectures $darwin_arches" + for darwin_arch in $darwin_arches ; do + mkdir -p "unfat-$$/${darwin_base_archive}-${darwin_arch}" + lipo -thin $darwin_arch -output "unfat-$$/${darwin_base_archive}-${darwin_arch}/${darwin_base_archive}" "${darwin_archive}" + cd "unfat-$$/${darwin_base_archive}-${darwin_arch}" + func_extract_an_archive "`pwd`" "${darwin_base_archive}" + cd "$darwin_curdir" + $rm "unfat-$$/${darwin_base_archive}-${darwin_arch}/${darwin_base_archive}" + done # $darwin_arches + ## Okay now we have a bunch of thin objects, gotta fatten them up :) + darwin_filelist=`find unfat-$$ -type f -name \*.o -print -o -name \*.lo -print| xargs basename | sort -u | $NL2SP` + darwin_file= + darwin_files= + for darwin_file in $darwin_filelist; do + darwin_files=`find unfat-$$ -name $darwin_file -print | $NL2SP` + lipo -create -output "$darwin_file" $darwin_files + done # $darwin_filelist + ${rm}r unfat-$$ + cd "$darwin_orig_dir" + else + cd "$darwin_orig_dir" + func_extract_an_archive "$my_xdir" "$my_xabs" + fi # $darwin_arches + fi # $run + ;; + *) + func_extract_an_archive "$my_xdir" "$my_xabs" + ;; + esac + my_oldobjs="$my_oldobjs "`find $my_xdir -name \*.$objext -print -o -name \*.lo -print | $NL2SP` + done + func_extract_archives_result="$my_oldobjs" +} +# End of Shell function definitions +##################################### + +# Darwin sucks +eval std_shrext=\"$shrext_cmds\" + +disable_libs=no + +# Parse our command line options once, thoroughly. +while test "$#" -gt 0 +do + arg="$1" + shift + + case $arg in + -*=*) optarg=`$echo "X$arg" | $Xsed -e 's/[-_a-zA-Z0-9]*=//'` ;; + *) optarg= ;; + esac + + # If the previous option needs an argument, assign it. + if test -n "$prev"; then + case $prev in + execute_dlfiles) + execute_dlfiles="$execute_dlfiles $arg" + ;; + tag) + tagname="$arg" + preserve_args="${preserve_args}=$arg" + + # Check whether tagname contains only valid characters + case $tagname in + *[!-_A-Za-z0-9,/]*) + $echo "$progname: invalid tag name: $tagname" 1>&2 + exit $EXIT_FAILURE + ;; + esac + + case $tagname in + CC) + # Don't test for the "default" C tag, as we know, it's there, but + # not specially marked. + ;; + *) + if grep "^# ### BEGIN LIBTOOL TAG CONFIG: $tagname$" < "$progpath" > /dev/null; then + taglist="$taglist $tagname" + # Evaluate the configuration. + eval "`${SED} -n -e '/^# ### BEGIN LIBTOOL TAG CONFIG: '$tagname'$/,/^# ### END LIBTOOL TAG CONFIG: '$tagname'$/p' < $progpath`" + else + $echo "$progname: ignoring unknown tag $tagname" 1>&2 + fi + ;; + esac + ;; + *) + eval "$prev=\$arg" + ;; + esac + + prev= + prevopt= + continue + fi + + # Have we seen a non-optional argument yet? + case $arg in + --help) + show_help=yes + ;; + + --version) + $echo "$PROGRAM (GNU $PACKAGE) $VERSION$TIMESTAMP" + $echo + $echo "Copyright (C) 2005 Free Software Foundation, Inc." + $echo "This is free software; see the source for copying conditions. There is NO" + $echo "warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE." + exit $? + ;; + + --config) + ${SED} -e '1,/^# ### BEGIN LIBTOOL CONFIG/d' -e '/^# ### END LIBTOOL CONFIG/,$d' $progpath + # Now print the configurations for the tags. + for tagname in $taglist; do + ${SED} -n -e "/^# ### BEGIN LIBTOOL TAG CONFIG: $tagname$/,/^# ### END LIBTOOL TAG CONFIG: $tagname$/p" < "$progpath" + done + exit $? + ;; + + --debug) + $echo "$progname: enabling shell trace mode" + set -x + preserve_args="$preserve_args $arg" + ;; + + --dry-run | -n) + run=: + ;; + + --features) + $echo "host: $host" + if test "$build_libtool_libs" = yes; then + $echo "enable shared libraries" + else + $echo "disable shared libraries" + fi + if test "$build_old_libs" = yes; then + $echo "enable static libraries" + else + $echo "disable static libraries" + fi + exit $? + ;; + + --finish) mode="finish" ;; + + --mode) prevopt="--mode" prev=mode ;; + --mode=*) mode="$optarg" ;; + + --preserve-dup-deps) duplicate_deps="yes" ;; + + --quiet | --silent) + show=: + preserve_args="$preserve_args $arg" + ;; + + --tag) + prevopt="--tag" + prev=tag + preserve_args="$preserve_args --tag" + ;; + --tag=*) + set tag "$optarg" ${1+"$@"} + shift + prev=tag + preserve_args="$preserve_args --tag" + ;; + + -dlopen) + prevopt="-dlopen" + prev=execute_dlfiles + ;; + + -*) + $echo "$modename: unrecognized option \`$arg'" 1>&2 + $echo "$help" 1>&2 + exit $EXIT_FAILURE + ;; + + *) + nonopt="$arg" + break + ;; + esac +done + +if test -n "$prevopt"; then + $echo "$modename: option \`$prevopt' requires an argument" 1>&2 + $echo "$help" 1>&2 + exit $EXIT_FAILURE +fi + +case $disable_libs in +no) + ;; +shared) + build_libtool_libs=no + build_old_libs=yes + ;; +static) + build_old_libs=`case $build_libtool_libs in yes) echo no;; *) echo yes;; esac` + ;; +esac + +# If this variable is set in any of the actions, the command in it +# will be execed at the end. This prevents here-documents from being +# left over by shells. +exec_cmd= + +if test -z "$show_help"; then + + # Infer the operation mode. + if test -z "$mode"; then + $echo "*** Warning: inferring the mode of operation is deprecated." 1>&2 + $echo "*** Future versions of Libtool will require --mode=MODE be specified." 1>&2 + case $nonopt in + *cc | cc* | *++ | gcc* | *-gcc* | g++* | xlc*) + mode=link + for arg + do + case $arg in + -c) + mode=compile + break + ;; + esac + done + ;; + *db | *dbx | *strace | *truss) + mode=execute + ;; + *install*|cp|mv) + mode=install + ;; + *rm) + mode=uninstall + ;; + *) + # If we have no mode, but dlfiles were specified, then do execute mode. + test -n "$execute_dlfiles" && mode=execute + + # Just use the default operation mode. + if test -z "$mode"; then + if test -n "$nonopt"; then + $echo "$modename: warning: cannot infer operation mode from \`$nonopt'" 1>&2 + else + $echo "$modename: warning: cannot infer operation mode without MODE-ARGS" 1>&2 + fi + fi + ;; + esac + fi + + # Only execute mode is allowed to have -dlopen flags. + if test -n "$execute_dlfiles" && test "$mode" != execute; then + $echo "$modename: unrecognized option \`-dlopen'" 1>&2 + $echo "$help" 1>&2 + exit $EXIT_FAILURE + fi + + # Change the help message to a mode-specific one. + generic_help="$help" + help="Try \`$modename --help --mode=$mode' for more information." + + # These modes are in order of execution frequency so that they run quickly. + case $mode in + # libtool compile mode + compile) + modename="$modename: compile" + # Get the compilation command and the source file. + base_compile= + srcfile="$nonopt" # always keep a non-empty value in "srcfile" + suppress_opt=yes + suppress_output= + arg_mode=normal + libobj= + later= + + for arg + do + case $arg_mode in + arg ) + # do not "continue". Instead, add this to base_compile + lastarg="$arg" + arg_mode=normal + ;; + + target ) + libobj="$arg" + arg_mode=normal + continue + ;; + + normal ) + # Accept any command-line options. + case $arg in + -o) + if test -n "$libobj" ; then + $echo "$modename: you cannot specify \`-o' more than once" 1>&2 + exit $EXIT_FAILURE + fi + arg_mode=target + continue + ;; + + -static | -prefer-pic | -prefer-non-pic) + later="$later $arg" + continue + ;; + + -no-suppress) + suppress_opt=no + continue + ;; + + -Xcompiler) + arg_mode=arg # the next one goes into the "base_compile" arg list + continue # The current "srcfile" will either be retained or + ;; # replaced later. I would guess that would be a bug. + + -Wc,*) + args=`$echo "X$arg" | $Xsed -e "s/^-Wc,//"` + lastarg= + save_ifs="$IFS"; IFS=',' + for arg in $args; do + IFS="$save_ifs" + + # Double-quote args containing other shell metacharacters. + # Many Bourne shells cannot handle close brackets correctly + # in scan sets, so we specify it separately. + case $arg in + *[\[\~\#\^\&\*\(\)\{\}\|\;\<\>\?\'\ \ ]*|*]*|"") + arg="\"$arg\"" + ;; + esac + lastarg="$lastarg $arg" + done + IFS="$save_ifs" + lastarg=`$echo "X$lastarg" | $Xsed -e "s/^ //"` + + # Add the arguments to base_compile. + base_compile="$base_compile $lastarg" + continue + ;; + + * ) + # Accept the current argument as the source file. + # The previous "srcfile" becomes the current argument. + # + lastarg="$srcfile" + srcfile="$arg" + ;; + esac # case $arg + ;; + esac # case $arg_mode + + # Aesthetically quote the previous argument. + lastarg=`$echo "X$lastarg" | $Xsed -e "$sed_quote_subst"` + + case $lastarg in + # Double-quote args containing other shell metacharacters. + # Many Bourne shells cannot handle close brackets correctly + # in scan sets, and some SunOS ksh mistreat backslash-escaping + # in scan sets (worked around with variable expansion), + # and furthermore cannot handle '|' '&' '(' ')' in scan sets + # at all, so we specify them separately. + *[\[\~\#\^\&\*\(\)\{\}\|\;\<\>\?\'\ \ ]*|*]*|"") + lastarg="\"$lastarg\"" + ;; + esac + + base_compile="$base_compile $lastarg" + done # for arg + + case $arg_mode in + arg) + $echo "$modename: you must specify an argument for -Xcompile" + exit $EXIT_FAILURE + ;; + target) + $echo "$modename: you must specify a target with \`-o'" 1>&2 + exit $EXIT_FAILURE + ;; + *) + # Get the name of the library object. + [ -z "$libobj" ] && libobj=`$echo "X$srcfile" | $Xsed -e 's%^.*/%%'` + ;; + esac + + # Recognize several different file suffixes. + # If the user specifies -o file.o, it is replaced with file.lo + xform='[cCFSifmso]' + case $libobj in + *.ada) xform=ada ;; + *.adb) xform=adb ;; + *.ads) xform=ads ;; + *.asm) xform=asm ;; + *.c++) xform=c++ ;; + *.cc) xform=cc ;; + *.ii) xform=ii ;; + *.class) xform=class ;; + *.cpp) xform=cpp ;; + *.cxx) xform=cxx ;; + *.f90) xform=f90 ;; + *.for) xform=for ;; + *.java) xform=java ;; + esac + + libobj=`$echo "X$libobj" | $Xsed -e "s/\.$xform$/.lo/"` + + case $libobj in + *.lo) obj=`$echo "X$libobj" | $Xsed -e "$lo2o"` ;; + *) + $echo "$modename: cannot determine name of library object from \`$libobj'" 1>&2 + exit $EXIT_FAILURE + ;; + esac + + func_infer_tag $base_compile + + for arg in $later; do + case $arg in + -static) + build_old_libs=yes + continue + ;; + + -prefer-pic) + pic_mode=yes + continue + ;; + + -prefer-non-pic) + pic_mode=no + continue + ;; + esac + done + + qlibobj=`$echo "X$libobj" | $Xsed -e "$sed_quote_subst"` + case $qlibobj in + *[\[\~\#\^\&\*\(\)\{\}\|\;\<\>\?\'\ \ ]*|*]*|"") + qlibobj="\"$qlibobj\"" ;; + esac + test "X$libobj" != "X$qlibobj" \ + && $echo "X$libobj" | grep '[]~#^*{};<>?"'"'"' &()|`$[]' \ + && $echo "$modename: libobj name \`$libobj' may not contain shell special characters." + objname=`$echo "X$obj" | $Xsed -e 's%^.*/%%'` + xdir=`$echo "X$obj" | $Xsed -e 's%/[^/]*$%%'` + if test "X$xdir" = "X$obj"; then + xdir= + else + xdir=$xdir/ + fi + lobj=${xdir}$objdir/$objname + + if test -z "$base_compile"; then + $echo "$modename: you must specify a compilation command" 1>&2 + $echo "$help" 1>&2 + exit $EXIT_FAILURE + fi + + # Delete any leftover library objects. + if test "$build_old_libs" = yes; then + removelist="$obj $lobj $libobj ${libobj}T" + else + removelist="$lobj $libobj ${libobj}T" + fi + + $run $rm $removelist + trap "$run $rm $removelist; exit $EXIT_FAILURE" 1 2 15 + + # On Cygwin there's no "real" PIC flag so we must build both object types + case $host_os in + cygwin* | mingw* | pw32* | os2*) + pic_mode=default + ;; + esac + if test "$pic_mode" = no && test "$deplibs_check_method" != pass_all; then + # non-PIC code in shared libraries is not supported + pic_mode=default + fi + + # Calculate the filename of the output object if compiler does + # not support -o with -c + if test "$compiler_c_o" = no; then + output_obj=`$echo "X$srcfile" | $Xsed -e 's%^.*/%%' -e 's%\.[^.]*$%%'`.${objext} + lockfile="$output_obj.lock" + removelist="$removelist $output_obj $lockfile" + trap "$run $rm $removelist; exit $EXIT_FAILURE" 1 2 15 + else + output_obj= + need_locks=no + lockfile= + fi + + # Lock this critical section if it is needed + # We use this script file to make the link, it avoids creating a new file + if test "$need_locks" = yes; then + until $run ln "$srcfile" "$lockfile" 2>/dev/null; do + $show "Waiting for $lockfile to be removed" + sleep 2 + done + elif test "$need_locks" = warn; then + if test -f "$lockfile"; then + $echo "\ +*** ERROR, $lockfile exists and contains: +`cat $lockfile 2>/dev/null` + +This indicates that another process is trying to use the same +temporary object file, and libtool could not work around it because +your compiler does not support \`-c' and \`-o' together. If you +repeat this compilation, it may succeed, by chance, but you had better +avoid parallel builds (make -j) in this platform, or get a better +compiler." + + $run $rm $removelist + exit $EXIT_FAILURE + fi + $echo "$srcfile" > "$lockfile" + fi + + if test -n "$fix_srcfile_path"; then + eval srcfile=\"$fix_srcfile_path\" + fi + qsrcfile=`$echo "X$srcfile" | $Xsed -e "$sed_quote_subst"` + case $qsrcfile in + *[\[\~\#\^\&\*\(\)\{\}\|\;\<\>\?\'\ \ ]*|*]*|"") + qsrcfile="\"$qsrcfile\"" ;; + esac + + $run $rm "$libobj" "${libobj}T" + + # Create a libtool object file (analogous to a ".la" file), + # but don't create it if we're doing a dry run. + test -z "$run" && cat > ${libobj}T </dev/null`" != "X$srcfile"; then + $echo "\ +*** ERROR, $lockfile contains: +`cat $lockfile 2>/dev/null` + +but it should contain: +$srcfile + +This indicates that another process is trying to use the same +temporary object file, and libtool could not work around it because +your compiler does not support \`-c' and \`-o' together. If you +repeat this compilation, it may succeed, by chance, but you had better +avoid parallel builds (make -j) in this platform, or get a better +compiler." + + $run $rm $removelist + exit $EXIT_FAILURE + fi + + # Just move the object if needed, then go on to compile the next one + if test -n "$output_obj" && test "X$output_obj" != "X$lobj"; then + $show "$mv $output_obj $lobj" + if $run $mv $output_obj $lobj; then : + else + error=$? + $run $rm $removelist + exit $error + fi + fi + + # Append the name of the PIC object to the libtool object file. + test -z "$run" && cat >> ${libobj}T <> ${libobj}T </dev/null`" != "X$srcfile"; then + $echo "\ +*** ERROR, $lockfile contains: +`cat $lockfile 2>/dev/null` + +but it should contain: +$srcfile + +This indicates that another process is trying to use the same +temporary object file, and libtool could not work around it because +your compiler does not support \`-c' and \`-o' together. If you +repeat this compilation, it may succeed, by chance, but you had better +avoid parallel builds (make -j) in this platform, or get a better +compiler." + + $run $rm $removelist + exit $EXIT_FAILURE + fi + + # Just move the object if needed + if test -n "$output_obj" && test "X$output_obj" != "X$obj"; then + $show "$mv $output_obj $obj" + if $run $mv $output_obj $obj; then : + else + error=$? + $run $rm $removelist + exit $error + fi + fi + + # Append the name of the non-PIC object the libtool object file. + # Only append if the libtool object file exists. + test -z "$run" && cat >> ${libobj}T <> ${libobj}T <&2 + fi + if test -n "$link_static_flag"; then + dlopen_self=$dlopen_self_static + fi + prefer_static_libs=yes + else + if test -z "$pic_flag" && test -n "$link_static_flag"; then + dlopen_self=$dlopen_self_static + fi + prefer_static_libs=built + fi + build_libtool_libs=no + build_old_libs=yes + break + ;; + esac + done + + # See if our shared archives depend on static archives. + test -n "$old_archive_from_new_cmds" && build_old_libs=yes + + # Go through the arguments, transforming them on the way. + while test "$#" -gt 0; do + arg="$1" + shift + case $arg in + *[\[\~\#\^\&\*\(\)\{\}\|\;\<\>\?\'\ \ ]*|*]*|"") + qarg=\"`$echo "X$arg" | $Xsed -e "$sed_quote_subst"`\" ### testsuite: skip nested quoting test + ;; + *) qarg=$arg ;; + esac + libtool_args="$libtool_args $qarg" + + # If the previous option needs an argument, assign it. + if test -n "$prev"; then + case $prev in + output) + compile_command="$compile_command @OUTPUT@" + finalize_command="$finalize_command @OUTPUT@" + ;; + esac + + case $prev in + dlfiles|dlprefiles) + if test "$preload" = no; then + # Add the symbol object into the linking commands. + compile_command="$compile_command @SYMFILE@" + finalize_command="$finalize_command @SYMFILE@" + preload=yes + fi + case $arg in + *.la | *.lo) ;; # We handle these cases below. + force) + if test "$dlself" = no; then + dlself=needless + export_dynamic=yes + fi + prev= + continue + ;; + self) + if test "$prev" = dlprefiles; then + dlself=yes + elif test "$prev" = dlfiles && test "$dlopen_self" != yes; then + dlself=yes + else + dlself=needless + export_dynamic=yes + fi + prev= + continue + ;; + *) + if test "$prev" = dlfiles; then + dlfiles="$dlfiles $arg" + else + dlprefiles="$dlprefiles $arg" + fi + prev= + continue + ;; + esac + ;; + expsyms) + export_symbols="$arg" + if test ! -f "$arg"; then + $echo "$modename: symbol file \`$arg' does not exist" + exit $EXIT_FAILURE + fi + prev= + continue + ;; + expsyms_regex) + export_symbols_regex="$arg" + prev= + continue + ;; + inst_prefix) + inst_prefix_dir="$arg" + prev= + continue + ;; + precious_regex) + precious_files_regex="$arg" + prev= + continue + ;; + release) + release="-$arg" + prev= + continue + ;; + objectlist) + if test -f "$arg"; then + save_arg=$arg + moreargs= + for fil in `cat $save_arg` + do +# moreargs="$moreargs $fil" + arg=$fil + # A libtool-controlled object. + + # Check to see that this really is a libtool object. + if (${SED} -e '2q' $arg | grep "^# Generated by .*$PACKAGE") >/dev/null 2>&1; then + pic_object= + non_pic_object= + + # Read the .lo file + # If there is no directory component, then add one. + case $arg in + */* | *\\*) . $arg ;; + *) . ./$arg ;; + esac + + if test -z "$pic_object" || \ + test -z "$non_pic_object" || + test "$pic_object" = none && \ + test "$non_pic_object" = none; then + $echo "$modename: cannot find name of object for \`$arg'" 1>&2 + exit $EXIT_FAILURE + fi + + # Extract subdirectory from the argument. + xdir=`$echo "X$arg" | $Xsed -e 's%/[^/]*$%%'` + if test "X$xdir" = "X$arg"; then + xdir= + else + xdir="$xdir/" + fi + + if test "$pic_object" != none; then + # Prepend the subdirectory the object is found in. + pic_object="$xdir$pic_object" + + if test "$prev" = dlfiles; then + if test "$build_libtool_libs" = yes && test "$dlopen_support" = yes; then + dlfiles="$dlfiles $pic_object" + prev= + continue + else + # If libtool objects are unsupported, then we need to preload. + prev=dlprefiles + fi + fi + + # CHECK ME: I think I busted this. -Ossama + if test "$prev" = dlprefiles; then + # Preload the old-style object. + dlprefiles="$dlprefiles $pic_object" + prev= + fi + + # A PIC object. + libobjs="$libobjs $pic_object" + arg="$pic_object" + fi + + # Non-PIC object. + if test "$non_pic_object" != none; then + # Prepend the subdirectory the object is found in. + non_pic_object="$xdir$non_pic_object" + + # A standard non-PIC object + non_pic_objects="$non_pic_objects $non_pic_object" + if test -z "$pic_object" || test "$pic_object" = none ; then + arg="$non_pic_object" + fi + else + # If the PIC object exists, use it instead. + # $xdir was prepended to $pic_object above. + non_pic_object="$pic_object" + non_pic_objects="$non_pic_objects $non_pic_object" + fi + else + # Only an error if not doing a dry-run. + if test -z "$run"; then + $echo "$modename: \`$arg' is not a valid libtool object" 1>&2 + exit $EXIT_FAILURE + else + # Dry-run case. + + # Extract subdirectory from the argument. + xdir=`$echo "X$arg" | $Xsed -e 's%/[^/]*$%%'` + if test "X$xdir" = "X$arg"; then + xdir= + else + xdir="$xdir/" + fi + + pic_object=`$echo "X${xdir}${objdir}/${arg}" | $Xsed -e "$lo2o"` + non_pic_object=`$echo "X${xdir}${arg}" | $Xsed -e "$lo2o"` + libobjs="$libobjs $pic_object" + non_pic_objects="$non_pic_objects $non_pic_object" + fi + fi + done + else + $echo "$modename: link input file \`$save_arg' does not exist" + exit $EXIT_FAILURE + fi + arg=$save_arg + prev= + continue + ;; + rpath | xrpath) + # We need an absolute path. + case $arg in + [\\/]* | [A-Za-z]:[\\/]*) ;; + *) + $echo "$modename: only absolute run-paths are allowed" 1>&2 + exit $EXIT_FAILURE + ;; + esac + if test "$prev" = rpath; then + case "$rpath " in + *" $arg "*) ;; + *) rpath="$rpath $arg" ;; + esac + else + case "$xrpath " in + *" $arg "*) ;; + *) xrpath="$xrpath $arg" ;; + esac + fi + prev= + continue + ;; + xcompiler) + compiler_flags="$compiler_flags $qarg" + prev= + compile_command="$compile_command $qarg" + finalize_command="$finalize_command $qarg" + continue + ;; + xlinker) + linker_flags="$linker_flags $qarg" + compiler_flags="$compiler_flags $wl$qarg" + prev= + compile_command="$compile_command $wl$qarg" + finalize_command="$finalize_command $wl$qarg" + continue + ;; + xcclinker) + linker_flags="$linker_flags $qarg" + compiler_flags="$compiler_flags $qarg" + prev= + compile_command="$compile_command $qarg" + finalize_command="$finalize_command $qarg" + continue + ;; + shrext) + shrext_cmds="$arg" + prev= + continue + ;; + darwin_framework|darwin_framework_skip) + test "$prev" = "darwin_framework" && compiler_flags="$compiler_flags $arg" + compile_command="$compile_command $arg" + finalize_command="$finalize_command $arg" + prev= + continue + ;; + *) + eval "$prev=\"\$arg\"" + prev= + continue + ;; + esac + fi # test -n "$prev" + + prevarg="$arg" + + case $arg in + -all-static) + if test -n "$link_static_flag"; then + compile_command="$compile_command $link_static_flag" + finalize_command="$finalize_command $link_static_flag" + fi + continue + ;; + + -allow-undefined) + # FIXME: remove this flag sometime in the future. + $echo "$modename: \`-allow-undefined' is deprecated because it is the default" 1>&2 + continue + ;; + + -avoid-version) + avoid_version=yes + continue + ;; + + -dlopen) + prev=dlfiles + continue + ;; + + -dlpreopen) + prev=dlprefiles + continue + ;; + + -export-dynamic) + export_dynamic=yes + continue + ;; + + -export-symbols | -export-symbols-regex) + if test -n "$export_symbols" || test -n "$export_symbols_regex"; then + $echo "$modename: more than one -exported-symbols argument is not allowed" + exit $EXIT_FAILURE + fi + if test "X$arg" = "X-export-symbols"; then + prev=expsyms + else + prev=expsyms_regex + fi + continue + ;; + + -framework|-arch|-isysroot) + case " $CC " in + *" ${arg} ${1} "* | *" ${arg} ${1} "*) + prev=darwin_framework_skip ;; + *) compiler_flags="$compiler_flags $arg" + prev=darwin_framework ;; + esac + compile_command="$compile_command $arg" + finalize_command="$finalize_command $arg" + continue + ;; + + -inst-prefix-dir) + prev=inst_prefix + continue + ;; + + # The native IRIX linker understands -LANG:*, -LIST:* and -LNO:* + # so, if we see these flags be careful not to treat them like -L + -L[A-Z][A-Z]*:*) + case $with_gcc/$host in + no/*-*-irix* | /*-*-irix*) + compile_command="$compile_command $arg" + finalize_command="$finalize_command $arg" + ;; + esac + continue + ;; + + -L*) + dir=`$echo "X$arg" | $Xsed -e 's/^-L//'` + # We need an absolute path. + case $dir in + [\\/]* | [A-Za-z]:[\\/]*) ;; + *) + absdir=`cd "$dir" && pwd` + if test -z "$absdir"; then + $echo "$modename: cannot determine absolute directory name of \`$dir'" 1>&2 + absdir="$dir" + notinst_path="$notinst_path $dir" + fi + dir="$absdir" + ;; + esac + case "$deplibs " in + *" -L$dir "*) ;; + *) + deplibs="$deplibs -L$dir" + lib_search_path="$lib_search_path $dir" + ;; + esac + case $host in + *-*-cygwin* | *-*-mingw* | *-*-pw32* | *-*-os2*) + testbindir=`$echo "X$dir" | $Xsed -e 's*/lib$*/bin*'` + case :$dllsearchpath: in + *":$dir:"*) ;; + *) dllsearchpath="$dllsearchpath:$dir";; + esac + case :$dllsearchpath: in + *":$testbindir:"*) ;; + *) dllsearchpath="$dllsearchpath:$testbindir";; + esac + ;; + esac + continue + ;; + + -l*) + if test "X$arg" = "X-lc" || test "X$arg" = "X-lm"; then + case $host in + *-*-cygwin* | *-*-mingw* | *-*-pw32* | *-*-beos*) + # These systems don't actually have a C or math library (as such) + continue + ;; + *-*-os2*) + # These systems don't actually have a C library (as such) + test "X$arg" = "X-lc" && continue + ;; + *-*-openbsd* | *-*-freebsd* | *-*-dragonfly*) + # Do not include libc due to us having libc/libc_r. + test "X$arg" = "X-lc" && continue + ;; + *-*-rhapsody* | *-*-darwin1.[012]) + # Rhapsody C and math libraries are in the System framework + deplibs="$deplibs -framework System" + continue + ;; + *-*-sco3.2v5* | *-*-sco5v6*) + # Causes problems with __ctype + test "X$arg" = "X-lc" && continue + ;; + *-*-sysv4.2uw2* | *-*-sysv5* | *-*-unixware* | *-*-OpenUNIX*) + # Compiler inserts libc in the correct place for threads to work + test "X$arg" = "X-lc" && continue + ;; + esac + elif test "X$arg" = "X-lc_r"; then + case $host in + *-*-openbsd* | *-*-freebsd* | *-*-dragonfly*) + # Do not include libc_r directly, use -pthread flag. + continue + ;; + esac + fi + deplibs="$deplibs $arg" + continue + ;; + + # Tru64 UNIX uses -model [arg] to determine the layout of C++ + # classes, name mangling, and exception handling. + -model) + compile_command="$compile_command $arg" + compiler_flags="$compiler_flags $arg" + finalize_command="$finalize_command $arg" + prev=xcompiler + continue + ;; + + -mt|-mthreads|-kthread|-Kthread|-pthread|-pthreads|--thread-safe) + compiler_flags="$compiler_flags $arg" + compile_command="$compile_command $arg" + finalize_command="$finalize_command $arg" + continue + ;; + + -module) + module=yes + continue + ;; + + # -64, -mips[0-9] enable 64-bit mode on the SGI compiler + # -r[0-9][0-9]* specifies the processor on the SGI compiler + # -xarch=*, -xtarget=* enable 64-bit mode on the Sun compiler + # +DA*, +DD* enable 64-bit mode on the HP compiler + # -q* pass through compiler args for the IBM compiler + # -m* pass through architecture-specific compiler args for GCC + # -m*, -t[45]*, -txscale* pass through architecture-specific + # compiler args for GCC + # -pg pass through profiling flag for GCC + # @file GCC response files + -64|-mips[0-9]|-r[0-9][0-9]*|-xarch=*|-xtarget=*|+DA*|+DD*|-q*|-m*|-pg| \ + -t[45]*|-txscale*|@*) + + # Unknown arguments in both finalize_command and compile_command need + # to be aesthetically quoted because they are evaled later. + arg=`$echo "X$arg" | $Xsed -e "$sed_quote_subst"` + case $arg in + *[\[\~\#\^\&\*\(\)\{\}\|\;\<\>\?\'\ \ ]*|*]*|"") + arg="\"$arg\"" + ;; + esac + compile_command="$compile_command $arg" + finalize_command="$finalize_command $arg" + compiler_flags="$compiler_flags $arg" + continue + ;; + + -shrext) + prev=shrext + continue + ;; + + -no-fast-install) + fast_install=no + continue + ;; + + -no-install) + case $host in + *-*-cygwin* | *-*-mingw* | *-*-pw32* | *-*-os2*) + # The PATH hackery in wrapper scripts is required on Windows + # in order for the loader to find any dlls it needs. + $echo "$modename: warning: \`-no-install' is ignored for $host" 1>&2 + $echo "$modename: warning: assuming \`-no-fast-install' instead" 1>&2 + fast_install=no + ;; + *) no_install=yes ;; + esac + continue + ;; + + -no-undefined) + allow_undefined=no + continue + ;; + + -objectlist) + prev=objectlist + continue + ;; + + -o) prev=output ;; + + -precious-files-regex) + prev=precious_regex + continue + ;; + + -release) + prev=release + continue + ;; + + -rpath) + prev=rpath + continue + ;; + + -R) + prev=xrpath + continue + ;; + + -R*) + dir=`$echo "X$arg" | $Xsed -e 's/^-R//'` + # We need an absolute path. + case $dir in + [\\/]* | [A-Za-z]:[\\/]*) ;; + *) + $echo "$modename: only absolute run-paths are allowed" 1>&2 + exit $EXIT_FAILURE + ;; + esac + case "$xrpath " in + *" $dir "*) ;; + *) xrpath="$xrpath $dir" ;; + esac + continue + ;; + + -static) + # The effects of -static are defined in a previous loop. + # We used to do the same as -all-static on platforms that + # didn't have a PIC flag, but the assumption that the effects + # would be equivalent was wrong. It would break on at least + # Digital Unix and AIX. + continue + ;; + + -thread-safe) + thread_safe=yes + continue + ;; + + -version-info) + prev=vinfo + continue + ;; + -version-number) + prev=vinfo + vinfo_number=yes + continue + ;; + + -Wc,*) + args=`$echo "X$arg" | $Xsed -e "$sed_quote_subst" -e 's/^-Wc,//'` + arg= + save_ifs="$IFS"; IFS=',' + for flag in $args; do + IFS="$save_ifs" + case $flag in + *[\[\~\#\^\&\*\(\)\{\}\|\;\<\>\?\'\ \ ]*|*]*|"") + flag="\"$flag\"" + ;; + esac + arg="$arg $wl$flag" + compiler_flags="$compiler_flags $flag" + done + IFS="$save_ifs" + arg=`$echo "X$arg" | $Xsed -e "s/^ //"` + ;; + + -Wl,*) + args=`$echo "X$arg" | $Xsed -e "$sed_quote_subst" -e 's/^-Wl,//'` + arg= + save_ifs="$IFS"; IFS=',' + for flag in $args; do + IFS="$save_ifs" + case $flag in + *[\[\~\#\^\&\*\(\)\{\}\|\;\<\>\?\'\ \ ]*|*]*|"") + flag="\"$flag\"" + ;; + esac + arg="$arg $wl$flag" + compiler_flags="$compiler_flags $wl$flag" + linker_flags="$linker_flags $flag" + done + IFS="$save_ifs" + arg=`$echo "X$arg" | $Xsed -e "s/^ //"` + ;; + + -Xcompiler) + prev=xcompiler + continue + ;; + + -Xlinker) + prev=xlinker + continue + ;; + + -XCClinker) + prev=xcclinker + continue + ;; + + # Some other compiler flag. + -* | +*) + # Unknown arguments in both finalize_command and compile_command need + # to be aesthetically quoted because they are evaled later. + arg=`$echo "X$arg" | $Xsed -e "$sed_quote_subst"` + case $arg in + *[\[\~\#\^\&\*\(\)\{\}\|\;\<\>\?\'\ \ ]*|*]*|"") + arg="\"$arg\"" + ;; + esac + ;; + + *.$objext) + # A standard object. + objs="$objs $arg" + ;; + + *.lo) + # A libtool-controlled object. + + # Check to see that this really is a libtool object. + if (${SED} -e '2q' $arg | grep "^# Generated by .*$PACKAGE") >/dev/null 2>&1; then + pic_object= + non_pic_object= + + # Read the .lo file + # If there is no directory component, then add one. + case $arg in + */* | *\\*) . $arg ;; + *) . ./$arg ;; + esac + + if test -z "$pic_object" || \ + test -z "$non_pic_object" || + test "$pic_object" = none && \ + test "$non_pic_object" = none; then + $echo "$modename: cannot find name of object for \`$arg'" 1>&2 + exit $EXIT_FAILURE + fi + + # Extract subdirectory from the argument. + xdir=`$echo "X$arg" | $Xsed -e 's%/[^/]*$%%'` + if test "X$xdir" = "X$arg"; then + xdir= + else + xdir="$xdir/" + fi + + if test "$pic_object" != none; then + # Prepend the subdirectory the object is found in. + pic_object="$xdir$pic_object" + + if test "$prev" = dlfiles; then + if test "$build_libtool_libs" = yes && test "$dlopen_support" = yes; then + dlfiles="$dlfiles $pic_object" + prev= + continue + else + # If libtool objects are unsupported, then we need to preload. + prev=dlprefiles + fi + fi + + # CHECK ME: I think I busted this. -Ossama + if test "$prev" = dlprefiles; then + # Preload the old-style object. + dlprefiles="$dlprefiles $pic_object" + prev= + fi + + # A PIC object. + libobjs="$libobjs $pic_object" + arg="$pic_object" + fi + + # Non-PIC object. + if test "$non_pic_object" != none; then + # Prepend the subdirectory the object is found in. + non_pic_object="$xdir$non_pic_object" + + # A standard non-PIC object + non_pic_objects="$non_pic_objects $non_pic_object" + if test -z "$pic_object" || test "$pic_object" = none ; then + arg="$non_pic_object" + fi + else + # If the PIC object exists, use it instead. + # $xdir was prepended to $pic_object above. + non_pic_object="$pic_object" + non_pic_objects="$non_pic_objects $non_pic_object" + fi + else + # Only an error if not doing a dry-run. + if test -z "$run"; then + $echo "$modename: \`$arg' is not a valid libtool object" 1>&2 + exit $EXIT_FAILURE + else + # Dry-run case. + + # Extract subdirectory from the argument. + xdir=`$echo "X$arg" | $Xsed -e 's%/[^/]*$%%'` + if test "X$xdir" = "X$arg"; then + xdir= + else + xdir="$xdir/" + fi + + pic_object=`$echo "X${xdir}${objdir}/${arg}" | $Xsed -e "$lo2o"` + non_pic_object=`$echo "X${xdir}${arg}" | $Xsed -e "$lo2o"` + libobjs="$libobjs $pic_object" + non_pic_objects="$non_pic_objects $non_pic_object" + fi + fi + ;; + + *.$libext) + # An archive. + deplibs="$deplibs $arg" + old_deplibs="$old_deplibs $arg" + continue + ;; + + *.la) + # A libtool-controlled library. + + if test "$prev" = dlfiles; then + # This library was specified with -dlopen. + dlfiles="$dlfiles $arg" + prev= + elif test "$prev" = dlprefiles; then + # The library was specified with -dlpreopen. + dlprefiles="$dlprefiles $arg" + prev= + else + deplibs="$deplibs $arg" + fi + continue + ;; + + # Some other compiler argument. + *) + # Unknown arguments in both finalize_command and compile_command need + # to be aesthetically quoted because they are evaled later. + arg=`$echo "X$arg" | $Xsed -e "$sed_quote_subst"` + case $arg in + *[\[\~\#\^\&\*\(\)\{\}\|\;\<\>\?\'\ \ ]*|*]*|"") + arg="\"$arg\"" + ;; + esac + ;; + esac # arg + + # Now actually substitute the argument into the commands. + if test -n "$arg"; then + compile_command="$compile_command $arg" + finalize_command="$finalize_command $arg" + fi + done # argument parsing loop + + if test -n "$prev"; then + $echo "$modename: the \`$prevarg' option requires an argument" 1>&2 + $echo "$help" 1>&2 + exit $EXIT_FAILURE + fi + + if test "$export_dynamic" = yes && test -n "$export_dynamic_flag_spec"; then + eval arg=\"$export_dynamic_flag_spec\" + compile_command="$compile_command $arg" + finalize_command="$finalize_command $arg" + fi + + oldlibs= + # calculate the name of the file, without its directory + outputname=`$echo "X$output" | $Xsed -e 's%^.*/%%'` + libobjs_save="$libobjs" + + if test -n "$shlibpath_var"; then + # get the directories listed in $shlibpath_var + eval shlib_search_path=\`\$echo \"X\${$shlibpath_var}\" \| \$Xsed -e \'s/:/ /g\'\` + else + shlib_search_path= + fi + eval sys_lib_search_path=\"$sys_lib_search_path_spec\" + eval sys_lib_dlsearch_path=\"$sys_lib_dlsearch_path_spec\" + + output_objdir=`$echo "X$output" | $Xsed -e 's%/[^/]*$%%'` + if test "X$output_objdir" = "X$output"; then + output_objdir="$objdir" + else + output_objdir="$output_objdir/$objdir" + fi + # Create the object directory. + if test ! -d "$output_objdir"; then + $show "$mkdir $output_objdir" + $run $mkdir $output_objdir + exit_status=$? + if test "$exit_status" -ne 0 && test ! -d "$output_objdir"; then + exit $exit_status + fi + fi + + # Determine the type of output + case $output in + "") + $echo "$modename: you must specify an output file" 1>&2 + $echo "$help" 1>&2 + exit $EXIT_FAILURE + ;; + *.$libext) linkmode=oldlib ;; + *.lo | *.$objext) linkmode=obj ;; + *.la) linkmode=lib ;; + *) linkmode=prog ;; # Anything else should be a program. + esac + + case $host in + *cygwin* | *mingw* | *pw32*) + # don't eliminate duplications in $postdeps and $predeps + duplicate_compiler_generated_deps=yes + ;; + *) + duplicate_compiler_generated_deps=$duplicate_deps + ;; + esac + specialdeplibs= + + libs= + # Find all interdependent deplibs by searching for libraries + # that are linked more than once (e.g. -la -lb -la) + for deplib in $deplibs; do + if test "X$duplicate_deps" = "Xyes" ; then + case "$libs " in + *" $deplib "*) specialdeplibs="$specialdeplibs $deplib" ;; + esac + fi + libs="$libs $deplib" + done + + if test "$linkmode" = lib; then + libs="$predeps $libs $compiler_lib_search_path $postdeps" + + # Compute libraries that are listed more than once in $predeps + # $postdeps and mark them as special (i.e., whose duplicates are + # not to be eliminated). + pre_post_deps= + if test "X$duplicate_compiler_generated_deps" = "Xyes" ; then + for pre_post_dep in $predeps $postdeps; do + case "$pre_post_deps " in + *" $pre_post_dep "*) specialdeplibs="$specialdeplibs $pre_post_deps" ;; + esac + pre_post_deps="$pre_post_deps $pre_post_dep" + done + fi + pre_post_deps= + fi + + deplibs= + newdependency_libs= + newlib_search_path= + need_relink=no # whether we're linking any uninstalled libtool libraries + notinst_deplibs= # not-installed libtool libraries + case $linkmode in + lib) + passes="conv link" + for file in $dlfiles $dlprefiles; do + case $file in + *.la) ;; + *) + $echo "$modename: libraries can \`-dlopen' only libtool libraries: $file" 1>&2 + exit $EXIT_FAILURE + ;; + esac + done + ;; + prog) + compile_deplibs= + finalize_deplibs= + alldeplibs=no + newdlfiles= + newdlprefiles= + passes="conv scan dlopen dlpreopen link" + ;; + *) passes="conv" + ;; + esac + for pass in $passes; do + if test "$linkmode,$pass" = "lib,link" || + test "$linkmode,$pass" = "prog,scan"; then + libs="$deplibs" + deplibs= + fi + if test "$linkmode" = prog; then + case $pass in + dlopen) libs="$dlfiles" ;; + dlpreopen) libs="$dlprefiles" ;; + link) libs="$deplibs %DEPLIBS% $dependency_libs" ;; + esac + fi + if test "$pass" = dlopen; then + # Collect dlpreopened libraries + save_deplibs="$deplibs" + deplibs= + fi + for deplib in $libs; do + lib= + found=no + case $deplib in + -mt|-mthreads|-kthread|-Kthread|-pthread|-pthreads|--thread-safe) + if test "$linkmode,$pass" = "prog,link"; then + compile_deplibs="$deplib $compile_deplibs" + finalize_deplibs="$deplib $finalize_deplibs" + else + compiler_flags="$compiler_flags $deplib" + fi + continue + ;; + -l*) + if test "$linkmode" != lib && test "$linkmode" != prog; then + $echo "$modename: warning: \`-l' is ignored for archives/objects" 1>&2 + continue + fi + name=`$echo "X$deplib" | $Xsed -e 's/^-l//'` + for searchdir in $newlib_search_path $lib_search_path $sys_lib_search_path $shlib_search_path; do + for search_ext in .la $std_shrext .so .a; do + # Search the libtool library + lib="$searchdir/lib${name}${search_ext}" + if test -f "$lib"; then + if test "$search_ext" = ".la"; then + found=yes + else + found=no + fi + break 2 + fi + done + done + if test "$found" != yes; then + # deplib doesn't seem to be a libtool library + if test "$linkmode,$pass" = "prog,link"; then + compile_deplibs="$deplib $compile_deplibs" + finalize_deplibs="$deplib $finalize_deplibs" + else + deplibs="$deplib $deplibs" + test "$linkmode" = lib && newdependency_libs="$deplib $newdependency_libs" + fi + continue + else # deplib is a libtool library + # If $allow_libtool_libs_with_static_runtimes && $deplib is a stdlib, + # We need to do some special things here, and not later. + if test "X$allow_libtool_libs_with_static_runtimes" = "Xyes" ; then + case " $predeps $postdeps " in + *" $deplib "*) + if (${SED} -e '2q' $lib | + grep "^# Generated by .*$PACKAGE") >/dev/null 2>&1; then + library_names= + old_library= + case $lib in + */* | *\\*) . $lib ;; + *) . ./$lib ;; + esac + for l in $old_library $library_names; do + ll="$l" + done + if test "X$ll" = "X$old_library" ; then # only static version available + found=no + ladir=`$echo "X$lib" | $Xsed -e 's%/[^/]*$%%'` + test "X$ladir" = "X$lib" && ladir="." + lib=$ladir/$old_library + if test "$linkmode,$pass" = "prog,link"; then + compile_deplibs="$deplib $compile_deplibs" + finalize_deplibs="$deplib $finalize_deplibs" + else + deplibs="$deplib $deplibs" + test "$linkmode" = lib && newdependency_libs="$deplib $newdependency_libs" + fi + continue + fi + fi + ;; + *) ;; + esac + fi + fi + ;; # -l + -L*) + case $linkmode in + lib) + deplibs="$deplib $deplibs" + test "$pass" = conv && continue + newdependency_libs="$deplib $newdependency_libs" + newlib_search_path="$newlib_search_path "`$echo "X$deplib" | $Xsed -e 's/^-L//'` + ;; + prog) + if test "$pass" = conv; then + deplibs="$deplib $deplibs" + continue + fi + if test "$pass" = scan; then + deplibs="$deplib $deplibs" + else + compile_deplibs="$deplib $compile_deplibs" + finalize_deplibs="$deplib $finalize_deplibs" + fi + newlib_search_path="$newlib_search_path "`$echo "X$deplib" | $Xsed -e 's/^-L//'` + ;; + *) + $echo "$modename: warning: \`-L' is ignored for archives/objects" 1>&2 + ;; + esac # linkmode + continue + ;; # -L + -R*) + if test "$pass" = link; then + dir=`$echo "X$deplib" | $Xsed -e 's/^-R//'` + # Make sure the xrpath contains only unique directories. + case "$xrpath " in + *" $dir "*) ;; + *) xrpath="$xrpath $dir" ;; + esac + fi + deplibs="$deplib $deplibs" + continue + ;; + *.la) lib="$deplib" ;; + *.$libext) + if test "$pass" = conv; then + deplibs="$deplib $deplibs" + continue + fi + case $linkmode in + lib) + valid_a_lib=no + case $deplibs_check_method in + match_pattern*) + set dummy $deplibs_check_method + match_pattern_regex=`expr "$deplibs_check_method" : "$2 \(.*\)"` + if eval $echo \"$deplib\" 2>/dev/null \ + | $SED 10q \ + | $EGREP "$match_pattern_regex" > /dev/null; then + valid_a_lib=yes + fi + ;; + pass_all) + valid_a_lib=yes + ;; + esac + if test "$valid_a_lib" != yes; then + $echo + $echo "*** Warning: Trying to link with static lib archive $deplib." + $echo "*** I have the capability to make that library automatically link in when" + $echo "*** you link to this library. But I can only do this if you have a" + $echo "*** shared version of the library, which you do not appear to have" + $echo "*** because the file extensions .$libext of this argument makes me believe" + $echo "*** that it is just a static archive that I should not used here." + else + $echo + $echo "*** Warning: Linking the shared library $output against the" + $echo "*** static library $deplib is not portable!" + deplibs="$deplib $deplibs" + fi + continue + ;; + prog) + if test "$pass" != link; then + deplibs="$deplib $deplibs" + else + compile_deplibs="$deplib $compile_deplibs" + finalize_deplibs="$deplib $finalize_deplibs" + fi + continue + ;; + esac # linkmode + ;; # *.$libext + *.lo | *.$objext) + if test "$pass" = conv; then + deplibs="$deplib $deplibs" + elif test "$linkmode" = prog; then + if test "$pass" = dlpreopen || test "$dlopen_support" != yes || test "$build_libtool_libs" = no; then + # If there is no dlopen support or we're linking statically, + # we need to preload. + newdlprefiles="$newdlprefiles $deplib" + compile_deplibs="$deplib $compile_deplibs" + finalize_deplibs="$deplib $finalize_deplibs" + else + newdlfiles="$newdlfiles $deplib" + fi + fi + continue + ;; + %DEPLIBS%) + alldeplibs=yes + continue + ;; + esac # case $deplib + if test "$found" = yes || test -f "$lib"; then : + else + $echo "$modename: cannot find the library \`$lib' or unhandled argument \`$deplib'" 1>&2 + exit $EXIT_FAILURE + fi + + # Check to see that this really is a libtool archive. + if (${SED} -e '2q' $lib | grep "^# Generated by .*$PACKAGE") >/dev/null 2>&1; then : + else + $echo "$modename: \`$lib' is not a valid libtool archive" 1>&2 + exit $EXIT_FAILURE + fi + + ladir=`$echo "X$lib" | $Xsed -e 's%/[^/]*$%%'` + test "X$ladir" = "X$lib" && ladir="." + + dlname= + dlopen= + dlpreopen= + libdir= + library_names= + old_library= + # If the library was installed with an old release of libtool, + # it will not redefine variables installed, or shouldnotlink + installed=yes + shouldnotlink=no + avoidtemprpath= + + + # Read the .la file + case $lib in + */* | *\\*) . $lib ;; + *) . ./$lib ;; + esac + + if test "$linkmode,$pass" = "lib,link" || + test "$linkmode,$pass" = "prog,scan" || + { test "$linkmode" != prog && test "$linkmode" != lib; }; then + test -n "$dlopen" && dlfiles="$dlfiles $dlopen" + test -n "$dlpreopen" && dlprefiles="$dlprefiles $dlpreopen" + fi + + if test "$pass" = conv; then + # Only check for convenience libraries + deplibs="$lib $deplibs" + if test -z "$libdir"; then + if test -z "$old_library"; then + $echo "$modename: cannot find name of link library for \`$lib'" 1>&2 + exit $EXIT_FAILURE + fi + # It is a libtool convenience library, so add in its objects. + convenience="$convenience $ladir/$objdir/$old_library" + old_convenience="$old_convenience $ladir/$objdir/$old_library" + tmp_libs= + for deplib in $dependency_libs; do + deplibs="$deplib $deplibs" + if test "X$duplicate_deps" = "Xyes" ; then + case "$tmp_libs " in + *" $deplib "*) specialdeplibs="$specialdeplibs $deplib" ;; + esac + fi + tmp_libs="$tmp_libs $deplib" + done + elif test "$linkmode" != prog && test "$linkmode" != lib; then + $echo "$modename: \`$lib' is not a convenience library" 1>&2 + exit $EXIT_FAILURE + fi + continue + fi # $pass = conv + + + # Get the name of the library we link against. + linklib= + for l in $old_library $library_names; do + linklib="$l" + done + if test -z "$linklib"; then + $echo "$modename: cannot find name of link library for \`$lib'" 1>&2 + exit $EXIT_FAILURE + fi + + # This library was specified with -dlopen. + if test "$pass" = dlopen; then + if test -z "$libdir"; then + $echo "$modename: cannot -dlopen a convenience library: \`$lib'" 1>&2 + exit $EXIT_FAILURE + fi + if test -z "$dlname" || + test "$dlopen_support" != yes || + test "$build_libtool_libs" = no; then + # If there is no dlname, no dlopen support or we're linking + # statically, we need to preload. We also need to preload any + # dependent libraries so libltdl's deplib preloader doesn't + # bomb out in the load deplibs phase. + dlprefiles="$dlprefiles $lib $dependency_libs" + else + newdlfiles="$newdlfiles $lib" + fi + continue + fi # $pass = dlopen + + # We need an absolute path. + case $ladir in + [\\/]* | [A-Za-z]:[\\/]*) abs_ladir="$ladir" ;; + *) + abs_ladir=`cd "$ladir" && pwd` + if test -z "$abs_ladir"; then + $echo "$modename: warning: cannot determine absolute directory name of \`$ladir'" 1>&2 + $echo "$modename: passing it literally to the linker, although it might fail" 1>&2 + abs_ladir="$ladir" + fi + ;; + esac + laname=`$echo "X$lib" | $Xsed -e 's%^.*/%%'` + + # Find the relevant object directory and library name. + if test "X$installed" = Xyes; then + if test ! -f "$libdir/$linklib" && test -f "$abs_ladir/$linklib"; then + $echo "$modename: warning: library \`$lib' was moved." 1>&2 + dir="$ladir" + absdir="$abs_ladir" + libdir="$abs_ladir" + else + dir="$libdir" + absdir="$libdir" + fi + test "X$hardcode_automatic" = Xyes && avoidtemprpath=yes + else + if test ! -f "$ladir/$objdir/$linklib" && test -f "$abs_ladir/$linklib"; then + dir="$ladir" + absdir="$abs_ladir" + # Remove this search path later + notinst_path="$notinst_path $abs_ladir" + else + dir="$ladir/$objdir" + absdir="$abs_ladir/$objdir" + # Remove this search path later + notinst_path="$notinst_path $abs_ladir" + fi + fi # $installed = yes + name=`$echo "X$laname" | $Xsed -e 's/\.la$//' -e 's/^lib//'` + + # This library was specified with -dlpreopen. + if test "$pass" = dlpreopen; then + if test -z "$libdir"; then + $echo "$modename: cannot -dlpreopen a convenience library: \`$lib'" 1>&2 + exit $EXIT_FAILURE + fi + # Prefer using a static library (so that no silly _DYNAMIC symbols + # are required to link). + if test -n "$old_library"; then + newdlprefiles="$newdlprefiles $dir/$old_library" + # Otherwise, use the dlname, so that lt_dlopen finds it. + elif test -n "$dlname"; then + newdlprefiles="$newdlprefiles $dir/$dlname" + else + newdlprefiles="$newdlprefiles $dir/$linklib" + fi + fi # $pass = dlpreopen + + if test -z "$libdir"; then + # Link the convenience library + if test "$linkmode" = lib; then + deplibs="$dir/$old_library $deplibs" + elif test "$linkmode,$pass" = "prog,link"; then + compile_deplibs="$dir/$old_library $compile_deplibs" + finalize_deplibs="$dir/$old_library $finalize_deplibs" + else + deplibs="$lib $deplibs" # used for prog,scan pass + fi + continue + fi + + + if test "$linkmode" = prog && test "$pass" != link; then + newlib_search_path="$newlib_search_path $ladir" + deplibs="$lib $deplibs" + + linkalldeplibs=no + if test "$link_all_deplibs" != no || test -z "$library_names" || + test "$build_libtool_libs" = no; then + linkalldeplibs=yes + fi + + tmp_libs= + for deplib in $dependency_libs; do + case $deplib in + -L*) newlib_search_path="$newlib_search_path "`$echo "X$deplib" | $Xsed -e 's/^-L//'`;; ### testsuite: skip nested quoting test + esac + # Need to link against all dependency_libs? + if test "$linkalldeplibs" = yes; then + deplibs="$deplib $deplibs" + else + # Need to hardcode shared library paths + # or/and link against static libraries + newdependency_libs="$deplib $newdependency_libs" + fi + if test "X$duplicate_deps" = "Xyes" ; then + case "$tmp_libs " in + *" $deplib "*) specialdeplibs="$specialdeplibs $deplib" ;; + esac + fi + tmp_libs="$tmp_libs $deplib" + done # for deplib + continue + fi # $linkmode = prog... + + if test "$linkmode,$pass" = "prog,link"; then + if test -n "$library_names" && + { test "$prefer_static_libs" = no || test -z "$old_library"; }; then + # We need to hardcode the library path + if test -n "$shlibpath_var" && test -z "$avoidtemprpath" ; then + # Make sure the rpath contains only unique directories. + case "$temp_rpath " in + *" $dir "*) ;; + *" $absdir "*) ;; + *) temp_rpath="$temp_rpath $absdir" ;; + esac + fi + + # Hardcode the library path. + # Skip directories that are in the system default run-time + # search path. + case " $sys_lib_dlsearch_path " in + *" $absdir "*) ;; + *) + case "$compile_rpath " in + *" $absdir "*) ;; + *) compile_rpath="$compile_rpath $absdir" + esac + ;; + esac + case " $sys_lib_dlsearch_path " in + *" $libdir "*) ;; + *) + case "$finalize_rpath " in + *" $libdir "*) ;; + *) finalize_rpath="$finalize_rpath $libdir" + esac + ;; + esac + fi # $linkmode,$pass = prog,link... + + if test "$alldeplibs" = yes && + { test "$deplibs_check_method" = pass_all || + { test "$build_libtool_libs" = yes && + test -n "$library_names"; }; }; then + # We only need to search for static libraries + continue + fi + fi + + link_static=no # Whether the deplib will be linked statically + use_static_libs=$prefer_static_libs + if test "$use_static_libs" = built && test "$installed" = yes ; then + use_static_libs=no + fi + if test -n "$library_names" && + { test "$use_static_libs" = no || test -z "$old_library"; }; then + if test "$installed" = no; then + notinst_deplibs="$notinst_deplibs $lib" + need_relink=yes + fi + # This is a shared library + + # Warn about portability, can't link against -module's on + # some systems (darwin) + if test "$shouldnotlink" = yes && test "$pass" = link ; then + $echo + if test "$linkmode" = prog; then + $echo "*** Warning: Linking the executable $output against the loadable module" + else + $echo "*** Warning: Linking the shared library $output against the loadable module" + fi + $echo "*** $linklib is not portable!" + fi + if test "$linkmode" = lib && + test "$hardcode_into_libs" = yes; then + # Hardcode the library path. + # Skip directories that are in the system default run-time + # search path. + case " $sys_lib_dlsearch_path " in + *" $absdir "*) ;; + *) + case "$compile_rpath " in + *" $absdir "*) ;; + *) compile_rpath="$compile_rpath $absdir" + esac + ;; + esac + case " $sys_lib_dlsearch_path " in + *" $libdir "*) ;; + *) + case "$finalize_rpath " in + *" $libdir "*) ;; + *) finalize_rpath="$finalize_rpath $libdir" + esac + ;; + esac + fi + + if test -n "$old_archive_from_expsyms_cmds"; then + # figure out the soname + set dummy $library_names + realname="$2" + shift; shift + libname=`eval \\$echo \"$libname_spec\"` + # use dlname if we got it. it's perfectly good, no? + if test -n "$dlname"; then + soname="$dlname" + elif test -n "$soname_spec"; then + # bleh windows + case $host in + *cygwin* | mingw*) + major=`expr $current - $age` + versuffix="-$major" + ;; + esac + eval soname=\"$soname_spec\" + else + soname="$realname" + fi + + # Make a new name for the extract_expsyms_cmds to use + soroot="$soname" + soname=`$echo $soroot | ${SED} -e 's/^.*\///'` + newlib="libimp-`$echo $soname | ${SED} 's/^lib//;s/\.dll$//'`.a" + + # If the library has no export list, then create one now + if test -f "$output_objdir/$soname-def"; then : + else + $show "extracting exported symbol list from \`$soname'" + save_ifs="$IFS"; IFS='~' + cmds=$extract_expsyms_cmds + for cmd in $cmds; do + IFS="$save_ifs" + eval cmd=\"$cmd\" + $show "$cmd" + $run eval "$cmd" || exit $? + done + IFS="$save_ifs" + fi + + # Create $newlib + if test -f "$output_objdir/$newlib"; then :; else + $show "generating import library for \`$soname'" + save_ifs="$IFS"; IFS='~' + cmds=$old_archive_from_expsyms_cmds + for cmd in $cmds; do + IFS="$save_ifs" + eval cmd=\"$cmd\" + $show "$cmd" + $run eval "$cmd" || exit $? + done + IFS="$save_ifs" + fi + # make sure the library variables are pointing to the new library + dir=$output_objdir + linklib=$newlib + fi # test -n "$old_archive_from_expsyms_cmds" + + if test "$linkmode" = prog || test "$mode" != relink; then + add_shlibpath= + add_dir= + add= + lib_linked=yes + case $hardcode_action in + immediate | unsupported) + if test "$hardcode_direct" = no; then + add="$dir/$linklib" + case $host in + *-*-sco3.2v5.0.[024]*) add_dir="-L$dir" ;; + *-*-sysv4*uw2*) add_dir="-L$dir" ;; + *-*-sysv5OpenUNIX* | *-*-sysv5UnixWare7.[01].[10]* | \ + *-*-unixware7*) add_dir="-L$dir" ;; + *-*-darwin* ) + # if the lib is a module then we can not link against + # it, someone is ignoring the new warnings I added + if /usr/bin/file -L $add 2> /dev/null | + $EGREP ": [^:]* bundle" >/dev/null ; then + $echo "** Warning, lib $linklib is a module, not a shared library" + if test -z "$old_library" ; then + $echo + $echo "** And there doesn't seem to be a static archive available" + $echo "** The link will probably fail, sorry" + else + add="$dir/$old_library" + fi + fi + esac + elif test "$hardcode_minus_L" = no; then + case $host in + *-*-sunos*) add_shlibpath="$dir" ;; + esac + add_dir="-L$dir" + add="-l$name" + elif test "$hardcode_shlibpath_var" = no; then + add_shlibpath="$dir" + add="-l$name" + else + lib_linked=no + fi + ;; + relink) + if test "$hardcode_direct" = yes; then + add="$dir/$linklib" + elif test "$hardcode_minus_L" = yes; then + add_dir="-L$dir" + # Try looking first in the location we're being installed to. + if test -n "$inst_prefix_dir"; then + case $libdir in + [\\/]*) + add_dir="$add_dir -L$inst_prefix_dir$libdir" + ;; + esac + fi + add="-l$name" + elif test "$hardcode_shlibpath_var" = yes; then + add_shlibpath="$dir" + add="-l$name" + else + lib_linked=no + fi + ;; + *) lib_linked=no ;; + esac + + if test "$lib_linked" != yes; then + $echo "$modename: configuration error: unsupported hardcode properties" + exit $EXIT_FAILURE + fi + + if test -n "$add_shlibpath"; then + case :$compile_shlibpath: in + *":$add_shlibpath:"*) ;; + *) compile_shlibpath="$compile_shlibpath$add_shlibpath:" ;; + esac + fi + if test "$linkmode" = prog; then + test -n "$add_dir" && compile_deplibs="$add_dir $compile_deplibs" + test -n "$add" && compile_deplibs="$add $compile_deplibs" + else + test -n "$add_dir" && deplibs="$add_dir $deplibs" + test -n "$add" && deplibs="$add $deplibs" + if test "$hardcode_direct" != yes && \ + test "$hardcode_minus_L" != yes && \ + test "$hardcode_shlibpath_var" = yes; then + case :$finalize_shlibpath: in + *":$libdir:"*) ;; + *) finalize_shlibpath="$finalize_shlibpath$libdir:" ;; + esac + fi + fi + fi + + if test "$linkmode" = prog || test "$mode" = relink; then + add_shlibpath= + add_dir= + add= + # Finalize command for both is simple: just hardcode it. + if test "$hardcode_direct" = yes; then + add="$libdir/$linklib" + elif test "$hardcode_minus_L" = yes; then + add_dir="-L$libdir" + add="-l$name" + elif test "$hardcode_shlibpath_var" = yes; then + case :$finalize_shlibpath: in + *":$libdir:"*) ;; + *) finalize_shlibpath="$finalize_shlibpath$libdir:" ;; + esac + add="-l$name" + elif test "$hardcode_automatic" = yes; then + if test -n "$inst_prefix_dir" && + test -f "$inst_prefix_dir$libdir/$linklib" ; then + add="$inst_prefix_dir$libdir/$linklib" + else + add="$libdir/$linklib" + fi + else + # We cannot seem to hardcode it, guess we'll fake it. + add_dir="-L$libdir" + # Try looking first in the location we're being installed to. + if test -n "$inst_prefix_dir"; then + case $libdir in + [\\/]*) + add_dir="$add_dir -L$inst_prefix_dir$libdir" + ;; + esac + fi + add="-l$name" + fi + + if test "$linkmode" = prog; then + test -n "$add_dir" && finalize_deplibs="$add_dir $finalize_deplibs" + test -n "$add" && finalize_deplibs="$add $finalize_deplibs" + else + test -n "$add_dir" && deplibs="$add_dir $deplibs" + test -n "$add" && deplibs="$add $deplibs" + fi + fi + elif test "$linkmode" = prog; then + # Here we assume that one of hardcode_direct or hardcode_minus_L + # is not unsupported. This is valid on all known static and + # shared platforms. + if test "$hardcode_direct" != unsupported; then + test -n "$old_library" && linklib="$old_library" + compile_deplibs="$dir/$linklib $compile_deplibs" + finalize_deplibs="$dir/$linklib $finalize_deplibs" + else + compile_deplibs="-l$name -L$dir $compile_deplibs" + finalize_deplibs="-l$name -L$dir $finalize_deplibs" + fi + elif test "$build_libtool_libs" = yes; then + # Not a shared library + if test "$deplibs_check_method" != pass_all; then + # We're trying link a shared library against a static one + # but the system doesn't support it. + Added: external/Pygments-0.8.1/tests/examplefiles/moin_SyntaxReference.txt ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/moin_SyntaxReference.txt Thu Aug 9 17:43:13 2007 @@ -0,0 +1,340 @@ +## Please edit system and help pages ONLY in the moinmaster wiki! For more +## information, please see MoinMaster:MoinPagesEditorGroup. +##master-page:Unknown-Page +##master-date:Unknown-Date +#acl MoinPagesEditorGroup:read,write,delete,revert All:read +#format wiki +#language en + +This page aims to introduce the most important elements of MoinMoin``'s syntax at a glance, showing first the markup verbatim and then how it is rendered by the wiki engine. Additionally, you'll find links to the relative help pages. Please note that some of the features depend on your configuration. + += Table of Contents = +{{{ +'''Contents''' (up to the 2nd level) +[[TableOfContents(2)]] +}}} +'''Contents''' (up to the 2nd level) +[[TableOfContents(2)]] + += Headings = +'''''see:''' HelpOnHeadlines'' +{{{ += heading 1st level = +== heading 2nd level == +=== heading 3rd level === +==== heading 4th level ==== +===== heading 5th level ===== +}}} += heading 1st level = +== heading 2nd level == +=== heading 3rd level === +==== heading 4th level ==== +===== heading 5th level ===== + += Text Formatting = +'''''see:''' HelpOnFormatting'' +{{{ + * ''emphasized (italics)'' + * '''boldface''' + * '''''bold italics''''' + * `monospace` + * {{{source code}}} + * __underline__ + * ,,sub,,script + * ^super^script + * ~-smaller-~ + * ~+larger+~ + * --(strike through)-- +}}} + * ''emphasized (italics)'' + * '''boldface''' + * '''''bold italics''''' + * `monospace` + * {{{source code}}} + * __underline__ + * ,,sub,,script + * ^super^script + * ~-smaller-~ + * ~+larger+~ + * --(strike through)-- + += Hyperlinks = +'''''see:''' HelpOnLinking'' +== Internal Links == +{{{ + * FrontPage + * ["FrontPage"] + * HelpOnEditing/SubPages + * /SubPage + * ../SiblingPage + * [:FrontPage:named link] + * [#anchorname] + * [#anchorname description] + * [wiki:Self:PageName#anchorname] + * [wiki:Self:PageName#anchorname description] + * attachment:filename.txt +}}} + * FrontPage + * ["FrontPage"] + * HelpOnEditing/SubPages + * /SubPage + * ../SiblingPage + * [:FrontPage:named link] + * [#anchorname] + * [#anchorname description] + * [wiki:Self:PageName#anchorname] + * [wiki:Self:PageName#anchorname description] + * attachment:filename.txt + +== External Links == +{{{ + * http://moinmoin.wikiwikiweb.de/ + * [http://moinmoin.wikiwikiweb.de/] + * [http://moinmoin.wikiwikiweb.de/ MoinMoin Wiki] + * [http://moinmoin.wikiwikiweb.de/wiki/moinmoin.png] + * http://moinmoin.wikiwikiweb.de/wiki/moinmoin.png + * [http://moinmoin.wikiwikiweb.de/wiki/moinmoin.png moinmoin.png] + * MeatBall:InterWiki + * wiki:MeatBall/InterWiki + * [wiki:MeatBall/InterWiki] + * [wiki:MeatBall/InterWiki InterWiki page on MeatBall] + * [file://///servername/share/full/path/to/file/filename%20with%20spaces.txt link to file filename with spaces.txt] + * user at example.com +}}} + * http://moinmoin.wikiwikiweb.de/ + * [http://moinmoin.wikiwikiweb.de/] + * [http://moinmoin.wikiwikiweb.de/ MoinMoin Wiki] + * [http://moinmoin.wikiwikiweb.de/wiki/moinmoin.png] + * http://moinmoin.wikiwikiweb.de/wiki/moinmoin.png + * [http://moinmoin.wikiwikiweb.de/wiki/moinmoin.png moinmoin.png] + * MeatBall:InterWiki + * wiki:MeatBall/InterWiki + * [wiki:MeatBall/InterWiki] + * [wiki:MeatBall/InterWiki InterWiki page on MeatBall] + * [file://///servername/share/full/path/to/file/filename%20with%20spaces.txt link to file filename with spaces.txt] + * user at example.com + +== Avoid or Limit Automatical Linking == +{{{ + * Wiki''''''Name + * Wiki``Name + * !WikiName + * WikiName''''''s + * WikiName``s + * `http://www.example.com` +}}} + * Wiki''''''Name + * Wiki``Name + * !WikiName + * WikiName''''''s + * WikiName``s + * `http://www.example.com` + += Blockquotes and Indentions = +{{{ + indented text + text indented to the 2nd level +}}} + indented text + text indented to the 2nd level + += Lists = +'''''see:''' HelpOnLists'' +== Unordered Lists == +{{{ + * item 1 + + * item 2 (preceding white space) + * item 2.1 + * item 2.1.1 + * item 3 + . item 3.1 (bulletless) + . item 4 (bulletless) + * item 4.1 + . item 4.1.1 (bulletless) +}}} + * item 1 + + * item 2 (preceding white space) + * item 2.1 + * item 2.1.1 + * item 3 + . item 3.1 (bulletless) + . item 4 (bulletless) + * item 4.1 + . item 4.1.1 (bulletless) + +== Ordered Lists == +=== with Numbers === +{{{ + 1. item 1 + 1. item 1.1 + 1. item 1.2 + 1. item 2 +}}} + 1. item 1 + 1. item 1.1 + 1. item 1.2 + 1. item 2 + +=== with Roman Numbers === +{{{ + I. item 1 + i. item 1.1 + i. item 1.2 + I. item 2 +}}} + I. item 1 + i. item 1.1 + i. item 1.2 + I. item 2 + +=== with Letters === +{{{ + A. item A + a. item A. a) + a. item A. b) + A. item B +}}} + A. item A + a. item A. a) + a. item A. b) + A. item B + +== Definition Lists == +{{{ + term:: definition + object:: description 1 + :: description 2 + Action Items:: + :: First Item + :: Second Item +}}} + term:: definition + object:: description 1 + :: description 2 + Action Items:: + :: First Item + :: Second Item + += Horizontal Rules = +'''''see:''' HelpOnRules'' +{{{ +---- +----- +------ +------- +-------- +--------- +---------- +}}} +---- +----- +------ +------- +-------- +--------- +---------- + += Tables = +'''''see:''' HelpOnTables'' +== Tables == +{{{ +||'''A'''||'''B'''||'''C'''|| +||1 ||2 ||3 || +}}} +||'''A'''||'''B'''||'''C'''|| +||1 ||2 ||3 || + +== Cell Width == +{{{ +||minimal width ||<99%>maximal width || +}}} +||minimal width ||<99%>maximal width || + +== Spanning Rows and Columns == +{{{ +||<|2> cell spanning 2 rows ||cell in the 2nd column || +||cell in the 2nd column of the 2nd row || +||<-2> cell spanning 2 columns || +||||use empty cells as a shorthand || +}}} +||<|2> cell spanning 2 rows ||cell in the 2nd column || +||cell in the 2nd column of the 2nd row || +||<-2> cell spanning 2 columns || +||||use empty cells as a shorthand || + +== Alignment of Cell Contents == +{{{ +||<^|3> top (combined) ||<:99%> center (combined) || bottom (combined) || +||<)> right || +||<(> left || +}}} +||<^|3> top (combined) ||<:99%> center (combined) || bottom (combined) || +||<)> right || +||<(> left || + +== Coulored Table Cells == +{{{ +||<#0000FF> blue ||<#00FF00> green ||<#FF0000> red || +||<#00FFFF> cyan ||<#FF00FF> magenta ||<#FFFF00> yellow || +}}} +||<#0000FF> blue ||<#00FF00> green ||<#FF0000> red || +||<#00FFFF> cyan ||<#FF00FF> magenta ||<#FFFF00> yellow || + +== HTML-like Options for Tables == +{{{ +||A || like <|2> || +|| like <#00FF00> || +|| like <-2>|| +}}} +||A || like <|2> || +|| like <#00FF00> || +|| like <-2>|| + += Macros and Variables = +== Macros == +'''''see:''' HelpOnMacros'' + * `[[Anchor(anchorname)]]` inserts a link anchor `anchorname` + * `[[BR]]` inserts a hard line break + * `[[FootNote(Note)]]` inserts a footnote saying `Note` + * `[[Include(HelpOnMacros/Include)]]` inserts the contents of the page `HelpOnMacros/Include` inline + * `[[MailTo(user AT example DOT com)]]` obfuscates the email address `user at example.com` to users not logged in + +== Variables == +'''''see:''' HelpOnVariables'' + * `@``SIG``@` inserts your login name and timestamp of modification + * `@``TIME``@` inserts date and time of modification + += Smileys and Icons = +'''''see:''' HelpOnSmileys'' +[[ShowSmileys]] + += Source code = +'''''see:''' HelpOnParsers'' +== Verbatim Display == +{{{ +{ { { +def hello(): + print "Hello World!" +} } } +}}} +/!\ Remove spaces between "`{ { {`" and "`} } }`". +{{{ +def hello(): + print "Hello World!" +}}} + +== Syntax Highlighting == +{{{ +{ { {#!python +def hello(): + print "Hello World!" +} } } +}}} +/!\ Remove spaces between "`{ { {`" and "`} } }`". +{{{#!python +def hello(): + print "Hello World!" +}}} + Added: external/Pygments-0.8.1/tests/examplefiles/multiline_regexes.rb ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/multiline_regexes.rb Thu Aug 9 17:43:13 2007 @@ -0,0 +1,38 @@ +/ +this is a +multiline +regex +/ + +this /is a +multiline regex too/ + +foo = /is also +one/ + +also /4 +is one/ + +this(/ +too +/) + +# this not +2 /4 +asfsadf/ + +# this is also not one +0x4d /25 +foo/ + +42 and /this +is also a multiline +regex/ + + +# And here some special string cases +foo = % blah # comment here to ensure whitespace +foo(% blah ) +foo << % blah # stupid but has to work +foo = % blah + % blub # wicked +foo = %q wicked # works too Added: external/Pygments-0.8.1/tests/examplefiles/numbers.c ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/numbers.c Thu Aug 9 17:43:13 2007 @@ -0,0 +1,12 @@ +/* + * Some Number Test + */ + +int i = 24241424; +float f1 = 342423423.24234; +float f2 = 25235235.; +float f3 = .234234; +float f4 = 234243e+34343; +float f5 = 24234e-234; +int o = 0234; +int h = 0x2342; Added: external/Pygments-0.8.1/tests/examplefiles/perl5db.pl ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/perl5db.pl Thu Aug 9 17:43:13 2007 @@ -0,0 +1,998 @@ + +=head1 NAME + +perl5db.pl - the perl debugger + +=head1 SYNOPSIS + + perl -d your_Perl_script + +=head1 DESCRIPTION + +After this routine is over, we don't have user code executing in the debugger's +context, so we can use C freely. + +=cut + +############################################## Begin lexical danger zone + +# 'my' variables used here could leak into (that is, be visible in) +# the context that the code being evaluated is executing in. This means that +# the code could modify the debugger's variables. +# +# Fiddling with the debugger's context could be Bad. We insulate things as +# much as we can. + +sub eval { + + # 'my' would make it visible from user code + # but so does local! --tchrist + # Remember: this localizes @DB::res, not @main::res. + local @res; + { + + # Try to keep the user code from messing with us. Save these so that + # even if the eval'ed code changes them, we can put them back again. + # Needed because the user could refer directly to the debugger's + # package globals (and any 'my' variables in this containing scope) + # inside the eval(), and we want to try to stay safe. + local $otrace = $trace; + local $osingle = $single; + local $od = $^D; + + # Untaint the incoming eval() argument. + { ($evalarg) = $evalarg =~ /(.*)/s; } + + # $usercontext built in DB::DB near the comment + # "set up the context for DB::eval ..." + # Evaluate and save any results. + @res = eval "$usercontext $evalarg;\n"; # '\n' for nice recursive debug + + # Restore those old values. + $trace = $otrace; + $single = $osingle; + $^D = $od; + } + + # Save the current value of $@, and preserve it in the debugger's copy + # of the saved precious globals. + my $at = $@; + + # Since we're only saving $@, we only have to localize the array element + # that it will be stored in. + local $saved[0]; # Preserve the old value of $@ + eval { &DB::save }; + + # Now see whether we need to report an error back to the user. + if ($at) { + local $\ = ''; + print $OUT $at; + } + + # Display as required by the caller. $onetimeDump and $onetimedumpDepth + # are package globals. + elsif ($onetimeDump) { + if ( $onetimeDump eq 'dump' ) { + local $option{dumpDepth} = $onetimedumpDepth + if defined $onetimedumpDepth; + dumpit( $OUT, \@res ); + } + elsif ( $onetimeDump eq 'methods' ) { + methods( $res[0] ); + } + } ## end elsif ($onetimeDump) + @res; +} ## end sub eval + +############################################## End lexical danger zone + +# After this point it is safe to introduce lexicals. +# The code being debugged will be executing in its own context, and +# can't see the inside of the debugger. +# +# However, one should not overdo it: leave as much control from outside as +# possible. If you make something a lexical, it's not going to be addressable +# from outside the debugger even if you know its name. + +# This file is automatically included if you do perl -d. +# It's probably not useful to include this yourself. +# +# Before venturing further into these twisty passages, it is +# wise to read the perldebguts man page or risk the ire of dragons. +# +# (It should be noted that perldebguts will tell you a lot about +# the underlying mechanics of how the debugger interfaces into the +# Perl interpreter, but not a lot about the debugger itself. The new +# comments in this code try to address this problem.) + +# Note that no subroutine call is possible until &DB::sub is defined +# (for subroutines defined outside of the package DB). In fact the same is +# true if $deep is not defined. + +# Enhanced by ilya at math.ohio-state.edu (Ilya Zakharevich) + +# modified Perl debugger, to be run from Emacs in perldb-mode +# Ray Lischner (uunet!mntgfx!lisch) as of 5 Nov 1990 +# Johan Vromans -- upgrade to 4.0 pl 10 +# Ilya Zakharevich -- patches after 5.001 (and some before ;-) + +# (We have made efforts to clarify the comments in the change log +# in other places; some of them may seem somewhat obscure as they +# were originally written, and explaining them away from the code +# in question seems conterproductive.. -JM) + +=head1 DEBUGGER INITIALIZATION + +The debugger starts up in phases. + +=head2 BASIC SETUP + +First, it initializes the environment it wants to run in: turning off +warnings during its own compilation, defining variables which it will need +to avoid warnings later, setting itself up to not exit when the program +terminates, and defaulting to printing return values for the C command. + +=cut + +# Needed for the statement after exec(): +# +# This BEGIN block is simply used to switch off warnings during debugger +# compiliation. Probably it would be better practice to fix the warnings, +# but this is how it's done at the moment. + +BEGIN { + $ini_warn = $^W; + $^W = 0; +} # Switch compilation warnings off until another BEGIN. + +# test if assertions are supported and actived: +BEGIN { + $ini_assertion = eval "sub asserting_test : assertion {1}; 1"; + + # $ini_assertion = undef => assertions unsupported, + # " = 1 => assertions supported + # print "\$ini_assertion=$ini_assertion\n"; +} + +local ($^W) = 0; # Switch run-time warnings off during init. + +=head2 THREADS SUPPORT + +If we are running under a threaded Perl, we require threads and threads::shared +if the environment variable C is set, to enable proper +threaded debugger control. C<-dt> can also be used to set this. + +Each new thread will be announced and the debugger prompt will always inform +you of each new thread created. It will also indicate the thread id in which +we are currently running within the prompt like this: + + [tid] DB<$i> + +Where C<[tid]> is an integer thread id and C<$i> is the familiar debugger +command prompt. The prompt will show: C<[0]> when running under threads, but +not actually in a thread. C<[tid]> is consistent with C usage. + +While running under threads, when you set or delete a breakpoint (etc.), this +will apply to all threads, not just the currently running one. When you are +in a currently executing thread, you will stay there until it completes. With +the current implementation it is not currently possible to hop from one thread +to another. + +The C and C commands are currently fairly minimal - see C and C. + +Note that threading support was built into the debugger as of Perl version +C<5.8.6> and debugger version C<1.2.8>. + +=cut + +BEGIN { + # ensure we can share our non-threaded variables or no-op + if ($ENV{PERL5DB_THREADED}) { + require threads; + require threads::shared; + import threads::shared qw(share); + $DBGR; + share(\$DBGR); + lock($DBGR); + print "Threads support enabled\n"; + } else { + *lock = sub(*) {}; + *share = sub(*) {}; + } +} + +# This would probably be better done with "use vars", but that wasn't around +# when this code was originally written. (Neither was "use strict".) And on +# the principle of not fiddling with something that was working, this was +# left alone. +warn( # Do not ;-) + # These variables control the execution of 'dumpvar.pl'. + $dumpvar::hashDepth, + $dumpvar::arrayDepth, + $dumpvar::dumpDBFiles, + $dumpvar::dumpPackages, + $dumpvar::quoteHighBit, + $dumpvar::printUndef, + $dumpvar::globPrint, + $dumpvar::usageOnly, + + # used to save @ARGV and extract any debugger-related flags. + @ARGS, + + # used to control die() reporting in diesignal() + $Carp::CarpLevel, + + # used to prevent multiple entries to diesignal() + # (if for instance diesignal() itself dies) + $panic, + + # used to prevent the debugger from running nonstop + # after a restart + $second_time, + ) + if 0; + +foreach my $k (keys (%INC)) { + &share(\$main::{'_<'.$filename}); +}; + +# Command-line + PERLLIB: +# Save the contents of @INC before they are modified elsewhere. + at ini_INC = @INC; + +# This was an attempt to clear out the previous values of various +# trapped errors. Apparently it didn't help. XXX More info needed! +# $prevwarn = $prevdie = $prevbus = $prevsegv = ''; # Does not help?! + +# We set these variables to safe values. We don't want to blindly turn +# off warnings, because other packages may still want them. +$trace = $signal = $single = 0; # Uninitialized warning suppression + # (local $^W cannot help - other packages!). + +# Default to not exiting when program finishes; print the return +# value when the 'r' command is used to return from a subroutine. +$inhibit_exit = $option{PrintRet} = 1; + +=head1 OPTION PROCESSING + +The debugger's options are actually spread out over the debugger itself and +C; some of these are variables to be set, while others are +subs to be called with a value. To try to make this a little easier to +manage, the debugger uses a few data structures to define what options +are legal and how they are to be processed. + +First, the C<@options> array defines the I of all the options that +are to be accepted. + +=cut + + at options = qw( + CommandSet + hashDepth arrayDepth dumpDepth + DumpDBFiles DumpPackages DumpReused + compactDump veryCompact quote + HighBit undefPrint globPrint + PrintRet UsageOnly frame + AutoTrace TTY noTTY + ReadLine NonStop LineInfo + maxTraceLen recallCommand ShellBang + pager tkRunning ornaments + signalLevel warnLevel dieLevel + inhibit_exit ImmediateStop bareStringify + CreateTTY RemotePort windowSize + DollarCaretP OnlyAssertions WarnAssertions +); + + at RememberOnROptions = qw(DollarCaretP OnlyAssertions); + +=pod + +Second, C lists the variables that each option uses to save its +state. + +=cut + +%optionVars = ( + hashDepth => \$dumpvar::hashDepth, + arrayDepth => \$dumpvar::arrayDepth, + CommandSet => \$CommandSet, + DumpDBFiles => \$dumpvar::dumpDBFiles, + DumpPackages => \$dumpvar::dumpPackages, + DumpReused => \$dumpvar::dumpReused, + HighBit => \$dumpvar::quoteHighBit, + undefPrint => \$dumpvar::printUndef, + globPrint => \$dumpvar::globPrint, + UsageOnly => \$dumpvar::usageOnly, + CreateTTY => \$CreateTTY, + bareStringify => \$dumpvar::bareStringify, + frame => \$frame, + AutoTrace => \$trace, + inhibit_exit => \$inhibit_exit, + maxTraceLen => \$maxtrace, + ImmediateStop => \$ImmediateStop, + RemotePort => \$remoteport, + windowSize => \$window, + WarnAssertions => \$warnassertions, +); + +=pod + +Third, C<%optionAction> defines the subroutine to be called to process each +option. + +=cut + +%optionAction = ( + compactDump => \&dumpvar::compactDump, + veryCompact => \&dumpvar::veryCompact, + quote => \&dumpvar::quote, + TTY => \&TTY, + noTTY => \&noTTY, + ReadLine => \&ReadLine, + NonStop => \&NonStop, + LineInfo => \&LineInfo, + recallCommand => \&recallCommand, + ShellBang => \&shellBang, + pager => \&pager, + signalLevel => \&signalLevel, + warnLevel => \&warnLevel, + dieLevel => \&dieLevel, + tkRunning => \&tkRunning, + ornaments => \&ornaments, + RemotePort => \&RemotePort, + DollarCaretP => \&DollarCaretP, + OnlyAssertions=> \&OnlyAssertions, +); + +=pod + +Last, the C<%optionRequire> notes modules that must be Cd if an +option is used. + +=cut + +# Note that this list is not complete: several options not listed here +# actually require that dumpvar.pl be loaded for them to work, but are +# not in the table. A subsequent patch will correct this problem; for +# the moment, we're just recommenting, and we are NOT going to change +# function. +%optionRequire = ( + compactDump => 'dumpvar.pl', + veryCompact => 'dumpvar.pl', + quote => 'dumpvar.pl', +); + +=pod + +There are a number of initialization-related variables which can be set +by putting code to set them in a BEGIN block in the C environment +variable. These are: + +=over 4 + +=item C<$rl> - readline control XXX needs more explanation + +=item C<$warnLevel> - whether or not debugger takes over warning handling + +=item C<$dieLevel> - whether or not debugger takes over die handling + +=item C<$signalLevel> - whether or not debugger takes over signal handling + +=item C<$pre> - preprompt actions (array reference) + +=item C<$post> - postprompt actions (array reference) + +=item C<$pretype> + +=item C<$CreateTTY> - whether or not to create a new TTY for this debugger + +=item C<$CommandSet> - which command set to use (defaults to new, documented set) + +=back + +=cut + +# These guys may be defined in $ENV{PERL5DB} : +$rl = 1 unless defined $rl; +$warnLevel = 1 unless defined $warnLevel; +$dieLevel = 1 unless defined $dieLevel; +$signalLevel = 1 unless defined $signalLevel; +$pre = [] unless defined $pre; +$post = [] unless defined $post; +$pretype = [] unless defined $pretype; +$CreateTTY = 3 unless defined $CreateTTY; +$CommandSet = '580' unless defined $CommandSet; + +share($rl); +share($warnLevel); +share($dieLevel); +share($signalLevel); +share($pre); +share($post); +share($pretype); +share($rl); +share($CreateTTY); +share($CommandSet); + +=pod + +The default C, C, and C handlers are set up. + +=cut + +warnLevel($warnLevel); +dieLevel($dieLevel); +signalLevel($signalLevel); + +=pod + +The pager to be used is needed next. We try to get it from the +environment first. if it's not defined there, we try to find it in +the Perl C. If it's not there, we default to C. We +then call the C function to save the pager name. + +=cut + +# This routine makes sure $pager is set up so that '|' can use it. +pager( + + # If PAGER is defined in the environment, use it. + defined $ENV{PAGER} + ? $ENV{PAGER} + + # If not, see if Config.pm defines it. + : eval { require Config } + && defined $Config::Config{pager} + ? $Config::Config{pager} + + # If not, fall back to 'more'. + : 'more' + ) + unless defined $pager; + +=pod + +We set up the command to be used to access the man pages, the command +recall character (C unless otherwise defined) and the shell escape +character (C unless otherwise defined). Yes, these do conflict, and +neither works in the debugger at the moment. + +=cut + +setman(); + +# Set up defaults for command recall and shell escape (note: +# these currently don't work in linemode debugging). +&recallCommand("!") unless defined $prc; +&shellBang("!") unless defined $psh; + +=pod + +We then set up the gigantic string containing the debugger help. +We also set the limit on the number of arguments we'll display during a +trace. + +=cut + +sethelp(); + +# If we didn't get a default for the length of eval/stack trace args, +# set it here. +$maxtrace = 400 unless defined $maxtrace; + +=head2 SETTING UP THE DEBUGGER GREETING + +The debugger I helps to inform the user how many debuggers are +running, and whether the current debugger is the primary or a child. + +If we are the primary, we just hang onto our pid so we'll have it when +or if we start a child debugger. If we are a child, we'll set things up +so we'll have a unique greeting and so the parent will give us our own +TTY later. + +We save the current contents of the C environment variable +because we mess around with it. We'll also need to hang onto it because +we'll need it if we restart. + +Child debuggers make a label out of the current PID structure recorded in +PERLDB_PIDS plus the new PID. They also mark themselves as not having a TTY +yet so the parent will give them one later via C. + +=cut + +# Save the current contents of the environment; we're about to +# much with it. We'll need this if we have to restart. +$ini_pids = $ENV{PERLDB_PIDS}; + +if ( defined $ENV{PERLDB_PIDS} ) { + + # We're a child. Make us a label out of the current PID structure + # recorded in PERLDB_PIDS plus our (new) PID. Mark us as not having + # a term yet so the parent will give us one later via resetterm(). + $pids = "[$ENV{PERLDB_PIDS}]"; + $ENV{PERLDB_PIDS} .= "->$$"; + $term_pid = -1; +} ## end if (defined $ENV{PERLDB_PIDS... +else { + + # We're the parent PID. Initialize PERLDB_PID in case we end up with a + # child debugger, and mark us as the parent, so we'll know to set up + # more TTY's is we have to. + $ENV{PERLDB_PIDS} = "$$"; + $pids = "{pid=$$}"; + $term_pid = $$; +} + +$pidprompt = ''; + +# Sets up $emacs as a synonym for $slave_editor. +*emacs = $slave_editor if $slave_editor; # May be used in afterinit()... + +=head2 READING THE RC FILE + +The debugger will read a file of initialization options if supplied. If +running interactively, this is C<.perldb>; if not, it's C. + +=cut + +# As noted, this test really doesn't check accurately that the debugger +# is running at a terminal or not. + +if ( -e "/dev/tty" ) { # this is the wrong metric! + $rcfile = ".perldb"; +} +else { + $rcfile = "perldb.ini"; +} + +=pod + +The debugger does a safety test of the file to be read. It must be owned +either by the current user or root, and must only be writable by the owner. + +=cut + +# This wraps a safety test around "do" to read and evaluate the init file. +# +# This isn't really safe, because there's a race +# between checking and opening. The solution is to +# open and fstat the handle, but then you have to read and +# eval the contents. But then the silly thing gets +# your lexical scope, which is unfortunate at best. +sub safe_do { + my $file = shift; + + # Just exactly what part of the word "CORE::" don't you understand? + local $SIG{__WARN__}; + local $SIG{__DIE__}; + + unless ( is_safe_file($file) ) { + CORE::warn < command is invoked, it +tries to capture all of the state it can into environment variables, and +then sets C. When we start executing again, we check to see +if C is there; if so, we reload all the information that +the R command stuffed into the environment variables. + + PERLDB_RESTART - flag only, contains no restart data itself. + PERLDB_HIST - command history, if it's available + PERLDB_ON_LOAD - breakpoints set by the rc file + PERLDB_POSTPONE - subs that have been loaded/not executed, and have actions + PERLDB_VISITED - files that had breakpoints + PERLDB_FILE_... - breakpoints for a file + PERLDB_OPT - active options + PERLDB_INC - the original @INC + PERLDB_PRETYPE - preprompt debugger actions + PERLDB_PRE - preprompt Perl code + PERLDB_POST - post-prompt Perl code + PERLDB_TYPEAHEAD - typeahead captured by readline() + +We chug through all these variables and plug the values saved in them +back into the appropriate spots in the debugger. + +=cut + +if ( exists $ENV{PERLDB_RESTART} ) { + + # We're restarting, so we don't need the flag that says to restart anymore. + delete $ENV{PERLDB_RESTART}; + + # $restart = 1; + @hist = get_list('PERLDB_HIST'); + %break_on_load = get_list("PERLDB_ON_LOAD"); + %postponed = get_list("PERLDB_POSTPONE"); + + share(@hist); + share(@truehist); + share(%break_on_load); + share(%postponed); + + # restore breakpoints/actions + my @had_breakpoints = get_list("PERLDB_VISITED"); + for ( 0 .. $#had_breakpoints ) { + my %pf = get_list("PERLDB_FILE_$_"); + $postponed_file{ $had_breakpoints[$_] } = \%pf if %pf; + } + + # restore options + my %opt = get_list("PERLDB_OPT"); + my ( $opt, $val ); + while ( ( $opt, $val ) = each %opt ) { + $val =~ s/[\\\']/\\$1/g; + parse_options("$opt'$val'"); + } + + # restore original @INC + @INC = get_list("PERLDB_INC"); + @ini_INC = @INC; + + # return pre/postprompt actions and typeahead buffer + $pretype = [ get_list("PERLDB_PRETYPE") ]; + $pre = [ get_list("PERLDB_PRE") ]; + $post = [ get_list("PERLDB_POST") ]; + @typeahead = get_list( "PERLDB_TYPEAHEAD", @typeahead ); +} ## end if (exists $ENV{PERLDB_RESTART... + +=head2 SETTING UP THE TERMINAL + +Now, we'll decide how the debugger is going to interact with the user. +If there's no TTY, we set the debugger to run non-stop; there's not going +to be anyone there to enter commands. + +=cut + +if ($notty) { + $runnonstop = 1; + share($runnonstop); +} + +=pod + +If there is a TTY, we have to determine who it belongs to before we can +proceed. If this is a slave editor or graphical debugger (denoted by +the first command-line switch being '-emacs'), we shift this off and +set C<$rl> to 0 (XXX ostensibly to do straight reads). + +=cut + +else { + + # Is Perl being run from a slave editor or graphical debugger? + # If so, don't use readline, and set $slave_editor = 1. + $slave_editor = + ( ( defined $main::ARGV[0] ) and ( $main::ARGV[0] eq '-emacs' ) ); + $rl = 0, shift(@main::ARGV) if $slave_editor; + + #require Term::ReadLine; + +=pod + +We then determine what the console should be on various systems: + +=over 4 + +=item * Cygwin - We use C instead of a separate device. + +=cut + + if ( $^O eq 'cygwin' ) { + + # /dev/tty is binary. use stdin for textmode + undef $console; + } + +=item * Unix - use C. + +=cut + + elsif ( -e "/dev/tty" ) { + $console = "/dev/tty"; + } + +=item * Windows or MSDOS - use C. + +=cut + + elsif ( $^O eq 'dos' or -e "con" or $^O eq 'MSWin32' ) { + $console = "con"; + } + +=item * MacOS - use C if this is the MPW version; C if not. + +Note that Mac OS X returns C, not C. Also note that the debugger doesn't do anything special for C. Maybe it should. + +=cut + + elsif ( $^O eq 'MacOS' ) { + if ( $MacPerl::Version !~ /MPW/ ) { + $console = + "Dev:Console:Perl Debug"; # Separate window for application + } + else { + $console = "Dev:Console"; + } + } ## end elsif ($^O eq 'MacOS') + +=item * VMS - use C. + +=cut + + else { + + # everything else is ... + $console = "sys\$command"; + } + +=pod + +=back + +Several other systems don't use a specific console. We C +for those (Windows using a slave editor/graphical debugger, NetWare, OS/2 +with a slave editor, Epoc). + +=cut + + if ( ( $^O eq 'MSWin32' ) and ( $slave_editor or defined $ENV{EMACS} ) ) { + + # /dev/tty is binary. use stdin for textmode + $console = undef; + } + + if ( $^O eq 'NetWare' ) { + + # /dev/tty is binary. use stdin for textmode + $console = undef; + } + + # In OS/2, we need to use STDIN to get textmode too, even though + # it pretty much looks like Unix otherwise. + if ( defined $ENV{OS2_SHELL} and ( $slave_editor or $ENV{WINDOWID} ) ) + { # In OS/2 + $console = undef; + } + + # EPOC also falls into the 'got to use STDIN' camp. + if ( $^O eq 'epoc' ) { + $console = undef; + } + +=pod + +If there is a TTY hanging around from a parent, we use that as the console. + +=cut + + $console = $tty if defined $tty; + +=head2 SOCKET HANDLING + +The debugger is capable of opening a socket and carrying out a debugging +session over the socket. + +If C was defined in the options, the debugger assumes that it +should try to start a debugging session on that port. It builds the socket +and then tries to connect the input and output filehandles to it. + +=cut + + # Handle socket stuff. + + if ( defined $remoteport ) { + + # If RemotePort was defined in the options, connect input and output + # to the socket. + require IO::Socket; + $OUT = new IO::Socket::INET( + Timeout => '10', + PeerAddr => $remoteport, + Proto => 'tcp', + ); + if ( !$OUT ) { die "Unable to connect to remote host: $remoteport\n"; } + $IN = $OUT; + } ## end if (defined $remoteport) + +=pod + +If no C was defined, and we want to create a TTY on startup, +this is probably a situation where multiple debuggers are running (for example, +a backticked command that starts up another debugger). We create a new IN and +OUT filehandle, and do the necessary mojo to create a new TTY if we know how +and if we can. + +=cut + + # Non-socket. + else { + + # Two debuggers running (probably a system or a backtick that invokes + # the debugger itself under the running one). create a new IN and OUT + # filehandle, and do the necessary mojo to create a new tty if we + # know how, and we can. + create_IN_OUT(4) if $CreateTTY & 4; + if ($console) { + + # If we have a console, check to see if there are separate ins and + # outs to open. (They are assumed identiical if not.) + + my ( $i, $o ) = split /,/, $console; + $o = $i unless defined $o; + + # read/write on in, or just read, or read on STDIN. + open( IN, "+<$i" ) + || open( IN, "<$i" ) + || open( IN, "<&STDIN" ); + + # read/write/create/clobber out, or write/create/clobber out, + # or merge with STDERR, or merge with STDOUT. + open( OUT, "+>$o" ) + || open( OUT, ">$o" ) + || open( OUT, ">&STDERR" ) + || open( OUT, ">&STDOUT" ); # so we don't dongle stdout + + } ## end if ($console) + elsif ( not defined $console ) { + + # No console. Open STDIN. + open( IN, "<&STDIN" ); + + # merge with STDERR, or with STDOUT. + open( OUT, ">&STDERR" ) + || open( OUT, ">&STDOUT" ); # so we don't dongle stdout + $console = 'STDIN/OUT'; + } ## end elsif (not defined $console) + + # Keep copies of the filehandles so that when the pager runs, it + # can close standard input without clobbering ours. + $IN = \*IN, $OUT = \*OUT if $console or not defined $console; + } ## end elsif (from if(defined $remoteport)) + + # Unbuffer DB::OUT. We need to see responses right away. + my $previous = select($OUT); + $| = 1; # for DB::OUT + select($previous); + + # Line info goes to debugger output unless pointed elsewhere. + # Pointing elsewhere makes it possible for slave editors to + # keep track of file and position. We have both a filehandle + # and a I/O description to keep track of. + $LINEINFO = $OUT unless defined $LINEINFO; + $lineinfo = $console unless defined $lineinfo; + # share($LINEINFO); # <- unable to share globs + share($lineinfo); # + +=pod + +To finish initialization, we show the debugger greeting, +and then call the C subroutine if there is one. + +=cut + + # Show the debugger greeting. + $header =~ s/.Header: ([^,]+),v(\s+\S+\s+\S+).*$/$1$2/; + unless ($runnonstop) { + local $\ = ''; + local $, = ''; + if ( $term_pid eq '-1' ) { + print $OUT "\nDaughter DB session started...\n"; + } + else { + print $OUT "\nLoading DB routines from $header\n"; + print $OUT ( + "Editor support ", + $slave_editor ? "enabled" : "available", ".\n" + ); + print $OUT +"\nEnter h or `h h' for help, or `$doccmd perldebug' for more help.\n\n"; + } ## end else [ if ($term_pid eq '-1') + } ## end unless ($runnonstop) +} ## end else [ if ($notty) + +# XXX This looks like a bug to me. +# Why copy to @ARGS and then futz with @args? + at ARGS = @ARGV; +for (@args) { + # Make sure backslashes before single quotes are stripped out, and + # keep args unless they are numeric (XXX why?) + # s/\'/\\\'/g; # removed while not justified understandably + # s/(.*)/'$1'/ unless /^-?[\d.]+$/; # ditto +} + +# If there was an afterinit() sub defined, call it. It will get +# executed in our scope, so it can fiddle with debugger globals. +if ( defined &afterinit ) { # May be defined in $rcfile + &afterinit(); +} + +# Inform us about "Stack dump during die enabled ..." in dieLevel(). +$I_m_init = 1; + + Added: external/Pygments-0.8.1/tests/examplefiles/perlfunc.1 ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/perlfunc.1 Thu Aug 9 17:43:13 2007 @@ -0,0 +1,856 @@ +.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sh \" Subsection heading +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. | will give a +.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to +.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' +.\" expand to `' in nroff, nothing in troff, for use with C<>. +.tr \(*W-|\(bv\*(Tr +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.\" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.hy 0 +.if n .na +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "PERLFUNC 1" +.TH PERLFUNC 1 "2006-01-07" "perl v5.8.8" "Perl Programmers Reference Guide" +.SH "NAME" +.IX Xref "function" +perlfunc \- Perl builtin functions +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The functions in this section can serve as terms in an expression. +They fall into two major categories: list operators and named unary +operators. These differ in their precedence relationship with a +following comma. (See the precedence table in perlop.) List +operators take more than one argument, while unary operators can never +take more than one argument. Thus, a comma terminates the argument of +a unary operator, but merely separates the arguments of a list +operator. A unary operator generally provides a scalar context to its +argument, while a list operator may provide either scalar or list +contexts for its arguments. If it does both, the scalar arguments will +be first, and the list argument will follow. (Note that there can ever +be only one such list argument.) For instance, \fIsplice()\fR has three scalar +arguments followed by a list, whereas \fIgethostbyname()\fR has four scalar +arguments. +.PP +In the syntax descriptions that follow, list operators that expect a +list (and provide list context for the elements of the list) are shown +with \s-1LIST\s0 as an argument. Such a list may consist of any combination +of scalar arguments or list values; the list values will be included +in the list as if each individual element were interpolated at that +point in the list, forming a longer single-dimensional list value. +Commas should separate elements of the \s-1LIST\s0. +.PP +Any function in the list below may be used either with or without +parentheses around its arguments. (The syntax descriptions omit the +parentheses.) If you use the parentheses, the simple (but occasionally +surprising) rule is this: It \fIlooks\fR like a function, therefore it \fIis\fR a +function, and precedence doesn't matter. Otherwise it's a list +operator or unary operator, and precedence does matter. And whitespace +between the function and left parenthesis doesn't count\*(--so you need to +be careful sometimes: +.PP +.Vb 5 +\& print 1+2+4; # Prints 7. +\& print(1+2) + 4; # Prints 3. +\& print (1+2)+4; # Also prints 3! +\& print +(1+2)+4; # Prints 7. +\& print ((1+2)+4); # Prints 7. +.Ve +.PP +If you run Perl with the \fB\-w\fR switch it can warn you about this. For +example, the third line above produces: +.PP +.Vb 2 +\& print (...) interpreted as function at - line 1. +\& Useless use of integer addition in void context at - line 1. +.Ve +.PP +A few functions take no arguments at all, and therefore work as neither +unary nor list operators. These include such functions as \f(CW\*(C`time\*(C'\fR +and \f(CW\*(C`endpwent\*(C'\fR. For example, \f(CW\*(C`time+86_400\*(C'\fR always means +\&\f(CW\*(C`time() + 86_400\*(C'\fR. +.PP +For functions that can be used in either a scalar or list context, +nonabortive failure is generally indicated in a scalar context by +returning the undefined value, and in a list context by returning the +null list. +.PP +Remember the following important rule: There is \fBno rule\fR that relates +the behavior of an expression in list context to its behavior in scalar +context, or vice versa. It might do two totally different things. +Each operator and function decides which sort of value it would be most +appropriate to return in scalar context. Some operators return the +length of the list that would have been returned in list context. Some +operators return the first value in the list. Some operators return the +last value in the list. Some operators return a count of successful +operations. In general, they do what you want, unless you want +consistency. +.IX Xref "context" +.PP +A named array in scalar context is quite different from what would at +first glance appear to be a list in scalar context. You can't get a list +like \f(CW\*(C`(1,2,3)\*(C'\fR into being in scalar context, because the compiler knows +the context at compile time. It would generate the scalar comma operator +there, not the list construction version of the comma. That means it +was never a list to start with. +.PP +In general, functions in Perl that serve as wrappers for system calls +of the same name (like \fIchown\fR\|(2), \fIfork\fR\|(2), \fIclosedir\fR\|(2), etc.) all return +true when they succeed and \f(CW\*(C`undef\*(C'\fR otherwise, as is usually mentioned +in the descriptions below. This is different from the C interfaces, +which return \f(CW\*(C`\-1\*(C'\fR on failure. Exceptions to this rule are \f(CW\*(C`wait\*(C'\fR, +\&\f(CW\*(C`waitpid\*(C'\fR, and \f(CW\*(C`syscall\*(C'\fR. System calls also set the special \f(CW$!\fR +variable on failure. Other functions do not, except accidentally. +.Sh "Perl Functions by Category" +.IX Xref "function" +.IX Subsection "Perl Functions by Category" +Here are Perl's functions (including things that look like +functions, like some keywords and named operators) +arranged by category. Some functions appear in more +than one place. +.IP "Functions for SCALARs or strings" 4 +.IX Xref "scalar string character" +.IX Item "Functions for SCALARs or strings" +\&\f(CW\*(C`chomp\*(C'\fR, \f(CW\*(C`chop\*(C'\fR, \f(CW\*(C`chr\*(C'\fR, \f(CW\*(C`crypt\*(C'\fR, \f(CW\*(C`hex\*(C'\fR, \f(CW\*(C`index\*(C'\fR, \f(CW\*(C`lc\*(C'\fR, \f(CW\*(C`lcfirst\*(C'\fR, +\&\f(CW\*(C`length\*(C'\fR, \f(CW\*(C`oct\*(C'\fR, \f(CW\*(C`ord\*(C'\fR, \f(CW\*(C`pack\*(C'\fR, \f(CW\*(C`q/STRING/\*(C'\fR, \f(CW\*(C`qq/STRING/\*(C'\fR, \f(CW\*(C`reverse\*(C'\fR, +\&\f(CW\*(C`rindex\*(C'\fR, \f(CW\*(C`sprintf\*(C'\fR, \f(CW\*(C`substr\*(C'\fR, \f(CW\*(C`tr///\*(C'\fR, \f(CW\*(C`uc\*(C'\fR, \f(CW\*(C`ucfirst\*(C'\fR, \f(CW\*(C`y///\*(C'\fR +.IP "Regular expressions and pattern matching" 4 +.IX Xref "regular expression regex regexp" +.IX Item "Regular expressions and pattern matching" +\&\f(CW\*(C`m//\*(C'\fR, \f(CW\*(C`pos\*(C'\fR, \f(CW\*(C`quotemeta\*(C'\fR, \f(CW\*(C`s///\*(C'\fR, \f(CW\*(C`split\*(C'\fR, \f(CW\*(C`study\*(C'\fR, \f(CW\*(C`qr//\*(C'\fR +.IP "Numeric functions" 4 +.IX Xref "numeric number trigonometric trigonometry" +.IX Item "Numeric functions" +\&\f(CW\*(C`abs\*(C'\fR, \f(CW\*(C`atan2\*(C'\fR, \f(CW\*(C`cos\*(C'\fR, \f(CW\*(C`exp\*(C'\fR, \f(CW\*(C`hex\*(C'\fR, \f(CW\*(C`int\*(C'\fR, \f(CW\*(C`log\*(C'\fR, \f(CW\*(C`oct\*(C'\fR, \f(CW\*(C`rand\*(C'\fR, +\&\f(CW\*(C`sin\*(C'\fR, \f(CW\*(C`sqrt\*(C'\fR, \f(CW\*(C`srand\*(C'\fR +.ie n .IP "Functions for real @ARRAYs" 4 +.el .IP "Functions for real \f(CW at ARRAYs\fR" 4 +.IX Xref "array" +.IX Item "Functions for real @ARRAYs" +\&\f(CW\*(C`pop\*(C'\fR, \f(CW\*(C`push\*(C'\fR, \f(CW\*(C`shift\*(C'\fR, \f(CW\*(C`splice\*(C'\fR, \f(CW\*(C`unshift\*(C'\fR +.IP "Functions for list data" 4 +.IX Xref "list" +.IX Item "Functions for list data" +\&\f(CW\*(C`grep\*(C'\fR, \f(CW\*(C`join\*(C'\fR, \f(CW\*(C`map\*(C'\fR, \f(CW\*(C`qw/STRING/\*(C'\fR, \f(CW\*(C`reverse\*(C'\fR, \f(CW\*(C`sort\*(C'\fR, \f(CW\*(C`unpack\*(C'\fR +.ie n .IP "Functions for real %HASHes" 4 +.el .IP "Functions for real \f(CW%HASHes\fR" 4 +.IX Xref "hash" +.IX Item "Functions for real %HASHes" +\&\f(CW\*(C`delete\*(C'\fR, \f(CW\*(C`each\*(C'\fR, \f(CW\*(C`exists\*(C'\fR, \f(CW\*(C`keys\*(C'\fR, \f(CW\*(C`values\*(C'\fR +.IP "Input and output functions" 4 +.IX Xref "I O input output dbm" +.IX Item "Input and output functions" +\&\f(CW\*(C`binmode\*(C'\fR, \f(CW\*(C`close\*(C'\fR, \f(CW\*(C`closedir\*(C'\fR, \f(CW\*(C`dbmclose\*(C'\fR, \f(CW\*(C`dbmopen\*(C'\fR, \f(CW\*(C`die\*(C'\fR, \f(CW\*(C`eof\*(C'\fR, +\&\f(CW\*(C`fileno\*(C'\fR, \f(CW\*(C`flock\*(C'\fR, \f(CW\*(C`format\*(C'\fR, \f(CW\*(C`getc\*(C'\fR, \f(CW\*(C`print\*(C'\fR, \f(CW\*(C`printf\*(C'\fR, \f(CW\*(C`read\*(C'\fR, +\&\f(CW\*(C`readdir\*(C'\fR, \f(CW\*(C`rewinddir\*(C'\fR, \f(CW\*(C`seek\*(C'\fR, \f(CW\*(C`seekdir\*(C'\fR, \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`syscall\*(C'\fR, +\&\f(CW\*(C`sysread\*(C'\fR, \f(CW\*(C`sysseek\*(C'\fR, \f(CW\*(C`syswrite\*(C'\fR, \f(CW\*(C`tell\*(C'\fR, \f(CW\*(C`telldir\*(C'\fR, \f(CW\*(C`truncate\*(C'\fR, +\&\f(CW\*(C`warn\*(C'\fR, \f(CW\*(C`write\*(C'\fR +.IP "Functions for fixed length data or records" 4 +.IX Item "Functions for fixed length data or records" +\&\f(CW\*(C`pack\*(C'\fR, \f(CW\*(C`read\*(C'\fR, \f(CW\*(C`syscall\*(C'\fR, \f(CW\*(C`sysread\*(C'\fR, \f(CW\*(C`syswrite\*(C'\fR, \f(CW\*(C`unpack\*(C'\fR, \f(CW\*(C`vec\*(C'\fR +.IP "Functions for filehandles, files, or directories" 4 +.IX Xref "file filehandle directory pipe link symlink" +.IX Item "Functions for filehandles, files, or directories" +\&\f(CW\*(C`\-\f(CIX\f(CW\*(C'\fR, \f(CW\*(C`chdir\*(C'\fR, \f(CW\*(C`chmod\*(C'\fR, \f(CW\*(C`chown\*(C'\fR, \f(CW\*(C`chroot\*(C'\fR, \f(CW\*(C`fcntl\*(C'\fR, \f(CW\*(C`glob\*(C'\fR, +\&\f(CW\*(C`ioctl\*(C'\fR, \f(CW\*(C`link\*(C'\fR, \f(CW\*(C`lstat\*(C'\fR, \f(CW\*(C`mkdir\*(C'\fR, \f(CW\*(C`open\*(C'\fR, \f(CW\*(C`opendir\*(C'\fR, +\&\f(CW\*(C`readlink\*(C'\fR, \f(CW\*(C`rename\*(C'\fR, \f(CW\*(C`rmdir\*(C'\fR, \f(CW\*(C`stat\*(C'\fR, \f(CW\*(C`symlink\*(C'\fR, \f(CW\*(C`sysopen\*(C'\fR, +\&\f(CW\*(C`umask\*(C'\fR, \f(CW\*(C`unlink\*(C'\fR, \f(CW\*(C`utime\*(C'\fR +.IP "Keywords related to the control flow of your Perl program" 4 +.IX Xref "control flow" +.IX Item "Keywords related to the control flow of your Perl program" +\&\f(CW\*(C`caller\*(C'\fR, \f(CW\*(C`continue\*(C'\fR, \f(CW\*(C`die\*(C'\fR, \f(CW\*(C`do\*(C'\fR, \f(CW\*(C`dump\*(C'\fR, \f(CW\*(C`eval\*(C'\fR, \f(CW\*(C`exit\*(C'\fR, +\&\f(CW\*(C`goto\*(C'\fR, \f(CW\*(C`last\*(C'\fR, \f(CW\*(C`next\*(C'\fR, \f(CW\*(C`redo\*(C'\fR, \f(CW\*(C`return\*(C'\fR, \f(CW\*(C`sub\*(C'\fR, \f(CW\*(C`wantarray\*(C'\fR +.IP "Keywords related to scoping" 4 +.IX Item "Keywords related to scoping" +\&\f(CW\*(C`caller\*(C'\fR, \f(CW\*(C`import\*(C'\fR, \f(CW\*(C`local\*(C'\fR, \f(CW\*(C`my\*(C'\fR, \f(CW\*(C`our\*(C'\fR, \f(CW\*(C`package\*(C'\fR, \f(CW\*(C`use\*(C'\fR +.IP "Miscellaneous functions" 4 +.IX Item "Miscellaneous functions" +\&\f(CW\*(C`defined\*(C'\fR, \f(CW\*(C`dump\*(C'\fR, \f(CW\*(C`eval\*(C'\fR, \f(CW\*(C`formline\*(C'\fR, \f(CW\*(C`local\*(C'\fR, \f(CW\*(C`my\*(C'\fR, \f(CW\*(C`our\*(C'\fR, \f(CW\*(C`reset\*(C'\fR, +\&\f(CW\*(C`scalar\*(C'\fR, \f(CW\*(C`undef\*(C'\fR, \f(CW\*(C`wantarray\*(C'\fR +.IP "Functions for processes and process groups" 4 +.IX Xref "process pid process id" +.IX Item "Functions for processes and process groups" +\&\f(CW\*(C`alarm\*(C'\fR, \f(CW\*(C`exec\*(C'\fR, \f(CW\*(C`fork\*(C'\fR, \f(CW\*(C`getpgrp\*(C'\fR, \f(CW\*(C`getppid\*(C'\fR, \f(CW\*(C`getpriority\*(C'\fR, \f(CW\*(C`kill\*(C'\fR, +\&\f(CW\*(C`pipe\*(C'\fR, \f(CW\*(C`qx/STRING/\*(C'\fR, \f(CW\*(C`setpgrp\*(C'\fR, \f(CW\*(C`setpriority\*(C'\fR, \f(CW\*(C`sleep\*(C'\fR, \f(CW\*(C`system\*(C'\fR, +\&\f(CW\*(C`times\*(C'\fR, \f(CW\*(C`wait\*(C'\fR, \f(CW\*(C`waitpid\*(C'\fR +.IP "Keywords related to perl modules" 4 +.IX Xref "module" +.IX Item "Keywords related to perl modules" +\&\f(CW\*(C`do\*(C'\fR, \f(CW\*(C`import\*(C'\fR, \f(CW\*(C`no\*(C'\fR, \f(CW\*(C`package\*(C'\fR, \f(CW\*(C`require\*(C'\fR, \f(CW\*(C`use\*(C'\fR +.IP "Keywords related to classes and object-orientedness" 4 +.IX Xref "object class package" +.IX Item "Keywords related to classes and object-orientedness" +\&\f(CW\*(C`bless\*(C'\fR, \f(CW\*(C`dbmclose\*(C'\fR, \f(CW\*(C`dbmopen\*(C'\fR, \f(CW\*(C`package\*(C'\fR, \f(CW\*(C`ref\*(C'\fR, \f(CW\*(C`tie\*(C'\fR, \f(CW\*(C`tied\*(C'\fR, +\&\f(CW\*(C`untie\*(C'\fR, \f(CW\*(C`use\*(C'\fR +.IP "Low-level socket functions" 4 +.IX Xref "socket sock" +.IX Item "Low-level socket functions" +\&\f(CW\*(C`accept\*(C'\fR, \f(CW\*(C`bind\*(C'\fR, \f(CW\*(C`connect\*(C'\fR, \f(CW\*(C`getpeername\*(C'\fR, \f(CW\*(C`getsockname\*(C'\fR, +\&\f(CW\*(C`getsockopt\*(C'\fR, \f(CW\*(C`listen\*(C'\fR, \f(CW\*(C`recv\*(C'\fR, \f(CW\*(C`send\*(C'\fR, \f(CW\*(C`setsockopt\*(C'\fR, \f(CW\*(C`shutdown\*(C'\fR, +\&\f(CW\*(C`socket\*(C'\fR, \f(CW\*(C`socketpair\*(C'\fR +.IP "System V interprocess communication functions" 4 +.IX Xref "IPC System V semaphore shared memory memory message" +.IX Item "System V interprocess communication functions" +\&\f(CW\*(C`msgctl\*(C'\fR, \f(CW\*(C`msgget\*(C'\fR, \f(CW\*(C`msgrcv\*(C'\fR, \f(CW\*(C`msgsnd\*(C'\fR, \f(CW\*(C`semctl\*(C'\fR, \f(CW\*(C`semget\*(C'\fR, \f(CW\*(C`semop\*(C'\fR, +\&\f(CW\*(C`shmctl\*(C'\fR, \f(CW\*(C`shmget\*(C'\fR, \f(CW\*(C`shmread\*(C'\fR, \f(CW\*(C`shmwrite\*(C'\fR +.IP "Fetching user and group info" 4 +.IX Xref "user group password uid gid passwd etc passwd" +.IX Item "Fetching user and group info" +\&\f(CW\*(C`endgrent\*(C'\fR, \f(CW\*(C`endhostent\*(C'\fR, \f(CW\*(C`endnetent\*(C'\fR, \f(CW\*(C`endpwent\*(C'\fR, \f(CW\*(C`getgrent\*(C'\fR, +\&\f(CW\*(C`getgrgid\*(C'\fR, \f(CW\*(C`getgrnam\*(C'\fR, \f(CW\*(C`getlogin\*(C'\fR, \f(CW\*(C`getpwent\*(C'\fR, \f(CW\*(C`getpwnam\*(C'\fR, +\&\f(CW\*(C`getpwuid\*(C'\fR, \f(CW\*(C`setgrent\*(C'\fR, \f(CW\*(C`setpwent\*(C'\fR +.IP "Fetching network info" 4 +.IX Xref "network protocol host hostname IP address service" +.IX Item "Fetching network info" +\&\f(CW\*(C`endprotoent\*(C'\fR, \f(CW\*(C`endservent\*(C'\fR, \f(CW\*(C`gethostbyaddr\*(C'\fR, \f(CW\*(C`gethostbyname\*(C'\fR, +\&\f(CW\*(C`gethostent\*(C'\fR, \f(CW\*(C`getnetbyaddr\*(C'\fR, \f(CW\*(C`getnetbyname\*(C'\fR, \f(CW\*(C`getnetent\*(C'\fR, +\&\f(CW\*(C`getprotobyname\*(C'\fR, \f(CW\*(C`getprotobynumber\*(C'\fR, \f(CW\*(C`getprotoent\*(C'\fR, +\&\f(CW\*(C`getservbyname\*(C'\fR, \f(CW\*(C`getservbyport\*(C'\fR, \f(CW\*(C`getservent\*(C'\fR, \f(CW\*(C`sethostent\*(C'\fR, +\&\f(CW\*(C`setnetent\*(C'\fR, \f(CW\*(C`setprotoent\*(C'\fR, \f(CW\*(C`setservent\*(C'\fR +.IP "Time-related functions" 4 +.IX Xref "time date" +.IX Item "Time-related functions" +\&\f(CW\*(C`gmtime\*(C'\fR, \f(CW\*(C`localtime\*(C'\fR, \f(CW\*(C`time\*(C'\fR, \f(CW\*(C`times\*(C'\fR +.IP "Functions new in perl5" 4 +.IX Xref "perl5" +.IX Item "Functions new in perl5" +\&\f(CW\*(C`abs\*(C'\fR, \f(CW\*(C`bless\*(C'\fR, \f(CW\*(C`chomp\*(C'\fR, \f(CW\*(C`chr\*(C'\fR, \f(CW\*(C`exists\*(C'\fR, \f(CW\*(C`formline\*(C'\fR, \f(CW\*(C`glob\*(C'\fR, +\&\f(CW\*(C`import\*(C'\fR, \f(CW\*(C`lc\*(C'\fR, \f(CW\*(C`lcfirst\*(C'\fR, \f(CW\*(C`map\*(C'\fR, \f(CW\*(C`my\*(C'\fR, \f(CW\*(C`no\*(C'\fR, \f(CW\*(C`our\*(C'\fR, \f(CW\*(C`prototype\*(C'\fR, +\&\f(CW\*(C`qx\*(C'\fR, \f(CW\*(C`qw\*(C'\fR, \f(CW\*(C`readline\*(C'\fR, \f(CW\*(C`readpipe\*(C'\fR, \f(CW\*(C`ref\*(C'\fR, \f(CW\*(C`sub*\*(C'\fR, \f(CW\*(C`sysopen\*(C'\fR, \f(CW\*(C`tie\*(C'\fR, +\&\f(CW\*(C`tied\*(C'\fR, \f(CW\*(C`uc\*(C'\fR, \f(CW\*(C`ucfirst\*(C'\fR, \f(CW\*(C`untie\*(C'\fR, \f(CW\*(C`use\*(C'\fR +.Sp +* \- \f(CW\*(C`sub\*(C'\fR was a keyword in perl4, but in perl5 it is an +operator, which can be used in expressions. +.IP "Functions obsoleted in perl5" 4 +.IX Item "Functions obsoleted in perl5" +\&\f(CW\*(C`dbmclose\*(C'\fR, \f(CW\*(C`dbmopen\*(C'\fR +.Sh "Portability" +.IX Xref "portability Unix portable" +.IX Subsection "Portability" +Perl was born in Unix and can therefore access all common Unix +system calls. In non-Unix environments, the functionality of some +Unix system calls may not be available, or details of the available +functionality may differ slightly. The Perl functions affected +by this are: +.PP +\&\f(CW\*(C`\-X\*(C'\fR, \f(CW\*(C`binmode\*(C'\fR, \f(CW\*(C`chmod\*(C'\fR, \f(CW\*(C`chown\*(C'\fR, \f(CW\*(C`chroot\*(C'\fR, \f(CW\*(C`crypt\*(C'\fR, +\&\f(CW\*(C`dbmclose\*(C'\fR, \f(CW\*(C`dbmopen\*(C'\fR, \f(CW\*(C`dump\*(C'\fR, \f(CW\*(C`endgrent\*(C'\fR, \f(CW\*(C`endhostent\*(C'\fR, +\&\f(CW\*(C`endnetent\*(C'\fR, \f(CW\*(C`endprotoent\*(C'\fR, \f(CW\*(C`endpwent\*(C'\fR, \f(CW\*(C`endservent\*(C'\fR, \f(CW\*(C`exec\*(C'\fR, +\&\f(CW\*(C`fcntl\*(C'\fR, \f(CW\*(C`flock\*(C'\fR, \f(CW\*(C`fork\*(C'\fR, \f(CW\*(C`getgrent\*(C'\fR, \f(CW\*(C`getgrgid\*(C'\fR, \f(CW\*(C`gethostbyname\*(C'\fR, +\&\f(CW\*(C`gethostent\*(C'\fR, \f(CW\*(C`getlogin\*(C'\fR, \f(CW\*(C`getnetbyaddr\*(C'\fR, \f(CW\*(C`getnetbyname\*(C'\fR, \f(CW\*(C`getnetent\*(C'\fR, +\&\f(CW\*(C`getppid\*(C'\fR, \f(CW\*(C`getpgrp\*(C'\fR, \f(CW\*(C`getpriority\*(C'\fR, \f(CW\*(C`getprotobynumber\*(C'\fR, +\&\f(CW\*(C`getprotoent\*(C'\fR, \f(CW\*(C`getpwent\*(C'\fR, \f(CW\*(C`getpwnam\*(C'\fR, \f(CW\*(C`getpwuid\*(C'\fR, +\&\f(CW\*(C`getservbyport\*(C'\fR, \f(CW\*(C`getservent\*(C'\fR, \f(CW\*(C`getsockopt\*(C'\fR, \f(CW\*(C`glob\*(C'\fR, \f(CW\*(C`ioctl\*(C'\fR, +\&\f(CW\*(C`kill\*(C'\fR, \f(CW\*(C`link\*(C'\fR, \f(CW\*(C`lstat\*(C'\fR, \f(CW\*(C`msgctl\*(C'\fR, \f(CW\*(C`msgget\*(C'\fR, \f(CW\*(C`msgrcv\*(C'\fR, +\&\f(CW\*(C`msgsnd\*(C'\fR, \f(CW\*(C`open\*(C'\fR, \f(CW\*(C`pipe\*(C'\fR, \f(CW\*(C`readlink\*(C'\fR, \f(CW\*(C`rename\*(C'\fR, \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`semctl\*(C'\fR, +\&\f(CW\*(C`semget\*(C'\fR, \f(CW\*(C`semop\*(C'\fR, \f(CW\*(C`setgrent\*(C'\fR, \f(CW\*(C`sethostent\*(C'\fR, \f(CW\*(C`setnetent\*(C'\fR, +\&\f(CW\*(C`setpgrp\*(C'\fR, \f(CW\*(C`setpriority\*(C'\fR, \f(CW\*(C`setprotoent\*(C'\fR, \f(CW\*(C`setpwent\*(C'\fR, +\&\f(CW\*(C`setservent\*(C'\fR, \f(CW\*(C`setsockopt\*(C'\fR, \f(CW\*(C`shmctl\*(C'\fR, \f(CW\*(C`shmget\*(C'\fR, \f(CW\*(C`shmread\*(C'\fR, +\&\f(CW\*(C`shmwrite\*(C'\fR, \f(CW\*(C`socket\*(C'\fR, \f(CW\*(C`socketpair\*(C'\fR, +\&\f(CW\*(C`stat\*(C'\fR, \f(CW\*(C`symlink\*(C'\fR, \f(CW\*(C`syscall\*(C'\fR, \f(CW\*(C`sysopen\*(C'\fR, \f(CW\*(C`system\*(C'\fR, +\&\f(CW\*(C`times\*(C'\fR, \f(CW\*(C`truncate\*(C'\fR, \f(CW\*(C`umask\*(C'\fR, \f(CW\*(C`unlink\*(C'\fR, +\&\f(CW\*(C`utime\*(C'\fR, \f(CW\*(C`wait\*(C'\fR, \f(CW\*(C`waitpid\*(C'\fR +.PP +For more information about the portability of these functions, see +perlport and other available platform-specific documentation. +.Sh "Alphabetical Listing of Perl Functions" +.IX Subsection "Alphabetical Listing of Perl Functions" +.IP "\-X \s-1FILEHANDLE\s0" 8 +.IX Xref "-r -w -x -o -R -W -X -O -e -z -s -f -d -l -p -S -b -c -t -u -g -k -T -B -M -A -C" +.IX Item "-X FILEHANDLE" +.PD 0 +.IP "\-X \s-1EXPR\s0" 8 +.IX Item "-X EXPR" +.IP "\-X" 8 +.IX Item "-X" +.PD +A file test, where X is one of the letters listed below. This unary +operator takes one argument, either a filename or a filehandle, and +tests the associated file to see if something is true about it. If the +argument is omitted, tests \f(CW$_\fR, except for \f(CW\*(C`\-t\*(C'\fR, which tests \s-1STDIN\s0. +Unless otherwise documented, it returns \f(CW1\fR for true and \f(CW''\fR for false, or +the undefined value if the file doesn't exist. Despite the funny +names, precedence is the same as any other named unary operator, and +the argument may be parenthesized like any other unary operator. The +operator may be any of: +.Sp +.Vb 4 +\& -r File is readable by effective uid/gid. +\& -w File is writable by effective uid/gid. +\& -x File is executable by effective uid/gid. +\& -o File is owned by effective uid. +.Ve +.Sp +.Vb 4 +\& -R File is readable by real uid/gid. +\& -W File is writable by real uid/gid. +\& -X File is executable by real uid/gid. +\& -O File is owned by real uid. +.Ve +.Sp +.Vb 3 +\& -e File exists. +\& -z File has zero size (is empty). +\& -s File has nonzero size (returns size in bytes). +.Ve +.Sp +.Vb 8 +\& -f File is a plain file. +\& -d File is a directory. +\& -l File is a symbolic link. +\& -p File is a named pipe (FIFO), or Filehandle is a pipe. +\& -S File is a socket. +\& -b File is a block special file. +\& -c File is a character special file. +\& -t Filehandle is opened to a tty. +.Ve +.Sp +.Vb 3 +\& -u File has setuid bit set. +\& -g File has setgid bit set. +\& -k File has sticky bit set. +.Ve +.Sp +.Vb 2 +\& -T File is an ASCII text file (heuristic guess). +\& -B File is a "binary" file (opposite of -T). +.Ve +.Sp +.Vb 3 +\& -M Script start time minus file modification time, in days. +\& -A Same for access time. +\& -C Same for inode change time (Unix, may differ for other platforms) +.Ve +.Sp +Example: +.Sp +.Vb 5 +\& while (<>) { +\& chomp; +\& next unless -f $_; # ignore specials +\& #... +\& } +.Ve +.Sp +The interpretation of the file permission operators \f(CW\*(C`\-r\*(C'\fR, \f(CW\*(C`\-R\*(C'\fR, +\&\f(CW\*(C`\-w\*(C'\fR, \f(CW\*(C`\-W\*(C'\fR, \f(CW\*(C`\-x\*(C'\fR, and \f(CW\*(C`\-X\*(C'\fR is by default based solely on the mode +of the file and the uids and gids of the user. There may be other +reasons you can't actually read, write, or execute the file. Such +reasons may be for example network filesystem access controls, ACLs +(access control lists), read-only filesystems, and unrecognized +executable formats. +.Sp +Also note that, for the superuser on the local filesystems, the \f(CW\*(C`\-r\*(C'\fR, +\&\f(CW\*(C`\-R\*(C'\fR, \f(CW\*(C`\-w\*(C'\fR, and \f(CW\*(C`\-W\*(C'\fR tests always return 1, and \f(CW\*(C`\-x\*(C'\fR and \f(CW\*(C`\-X\*(C'\fR return 1 +if any execute bit is set in the mode. Scripts run by the superuser +may thus need to do a \fIstat()\fR to determine the actual mode of the file, +or temporarily set their effective uid to something else. +.Sp +If you are using ACLs, there is a pragma called \f(CW\*(C`filetest\*(C'\fR that may +produce more accurate results than the bare \fIstat()\fR mode bits. +When under the \f(CW\*(C`use filetest 'access'\*(C'\fR the above-mentioned filetests +will test whether the permission can (not) be granted using the +\&\fIaccess()\fR family of system calls. Also note that the \f(CW\*(C`\-x\*(C'\fR and \f(CW\*(C`\-X\*(C'\fR may +under this pragma return true even if there are no execute permission +bits set (nor any extra execute permission ACLs). This strangeness is +due to the underlying system calls' definitions. Read the +documentation for the \f(CW\*(C`filetest\*(C'\fR pragma for more information. +.Sp +Note that \f(CW\*(C`\-s/a/b/\*(C'\fR does not do a negated substitution. Saying +\&\f(CW\*(C`\-exp($foo)\*(C'\fR still works as expected, however\*(--only single letters +following a minus are interpreted as file tests. +.Sp +The \f(CW\*(C`\-T\*(C'\fR and \f(CW\*(C`\-B\*(C'\fR switches work as follows. The first block or so of the +file is examined for odd characters such as strange control codes or +characters with the high bit set. If too many strange characters (>30%) +are found, it's a \f(CW\*(C`\-B\*(C'\fR file; otherwise it's a \f(CW\*(C`\-T\*(C'\fR file. Also, any file +containing null in the first block is considered a binary file. If \f(CW\*(C`\-T\*(C'\fR +or \f(CW\*(C`\-B\*(C'\fR is used on a filehandle, the current \s-1IO\s0 buffer is examined +rather than the first block. Both \f(CW\*(C`\-T\*(C'\fR and \f(CW\*(C`\-B\*(C'\fR return true on a null +file, or a file at \s-1EOF\s0 when testing a filehandle. Because you have to +read a file to do the \f(CW\*(C`\-T\*(C'\fR test, on most occasions you want to use a \f(CW\*(C`\-f\*(C'\fR +against the file first, as in \f(CW\*(C`next unless \-f $file && \-T $file\*(C'\fR. +.Sp +If any of the file tests (or either the \f(CW\*(C`stat\*(C'\fR or \f(CW\*(C`lstat\*(C'\fR operators) are given +the special filehandle consisting of a solitary underline, then the stat +structure of the previous file test (or stat operator) is used, saving +a system call. (This doesn't work with \f(CW\*(C`\-t\*(C'\fR, and you need to remember +that \fIlstat()\fR and \f(CW\*(C`\-l\*(C'\fR will leave values in the stat structure for the +symbolic link, not the real file.) (Also, if the stat buffer was filled by +an \f(CW\*(C`lstat\*(C'\fR call, \f(CW\*(C`\-T\*(C'\fR and \f(CW\*(C`\-B\*(C'\fR will reset it with the results of \f(CW\*(C`stat _\*(C'\fR). +Example: +.Sp +.Vb 1 +\& print "Can do.\en" if -r $a || -w _ || -x _; +.Ve +.Sp +.Vb 9 +\& stat($filename); +\& print "Readable\en" if -r _; +\& print "Writable\en" if -w _; +\& print "Executable\en" if -x _; +\& print "Setuid\en" if -u _; +\& print "Setgid\en" if -g _; +\& print "Sticky\en" if -k _; +\& print "Text\en" if -T _; +\& print "Binary\en" if -B _; +.Ve +.IP "abs \s-1VALUE\s0" 8 +.IX Xref "abs absolute" +.IX Item "abs VALUE" +.PD 0 +.IP "abs" 8 +.IX Item "abs" +.PD +Returns the absolute value of its argument. +If \s-1VALUE\s0 is omitted, uses \f(CW$_\fR. +.IP "accept \s-1NEWSOCKET\s0,GENERICSOCKET" 8 +.IX Xref "accept" +.IX Item "accept NEWSOCKET,GENERICSOCKET" +Accepts an incoming socket connect, just as the \fIaccept\fR\|(2) system call +does. Returns the packed address if it succeeded, false otherwise. +See the example in \*(L"Sockets: Client/Server Communication\*(R" in perlipc. +.Sp +On systems that support a close-on-exec flag on files, the flag will +be set for the newly opened file descriptor, as determined by the +value of $^F. See \*(L"$^F\*(R" in perlvar. +.IP "alarm \s-1SECONDS\s0" 8 +.IX Xref "alarm SIGALRM timer" +.IX Item "alarm SECONDS" +.PD 0 +.IP "alarm" 8 +.IX Item "alarm" +.PD +Arranges to have a \s-1SIGALRM\s0 delivered to this process after the +specified number of wallclock seconds has elapsed. If \s-1SECONDS\s0 is not +specified, the value stored in \f(CW$_\fR is used. (On some machines, +unfortunately, the elapsed time may be up to one second less or more +than you specified because of how seconds are counted, and process +scheduling may delay the delivery of the signal even further.) +.Sp +Only one timer may be counting at once. Each call disables the +previous timer, and an argument of \f(CW0\fR may be supplied to cancel the +previous timer without starting a new one. The returned value is the +amount of time remaining on the previous timer. +.Sp +For delays of finer granularity than one second, you may use Perl's +four-argument version of \fIselect()\fR leaving the first three arguments +undefined, or you might be able to use the \f(CW\*(C`syscall\*(C'\fR interface to +access \fIsetitimer\fR\|(2) if your system supports it. The Time::HiRes +module (from \s-1CPAN\s0, and starting from Perl 5.8 part of the standard +distribution) may also prove useful. +.Sp +It is usually a mistake to intermix \f(CW\*(C`alarm\*(C'\fR and \f(CW\*(C`sleep\*(C'\fR calls. +(\f(CW\*(C`sleep\*(C'\fR may be internally implemented in your system with \f(CW\*(C`alarm\*(C'\fR) +.Sp +If you want to use \f(CW\*(C`alarm\*(C'\fR to time out a system call you need to use an +\&\f(CW\*(C`eval\*(C'\fR/\f(CW\*(C`die\*(C'\fR pair. You can't rely on the alarm causing the system call to +fail with \f(CW$!\fR set to \f(CW\*(C`EINTR\*(C'\fR because Perl sets up signal handlers to +restart system calls on some systems. Using \f(CW\*(C`eval\*(C'\fR/\f(CW\*(C`die\*(C'\fR always works, +modulo the caveats given in \*(L"Signals\*(R" in perlipc. +.Sp +.Vb 13 +\& eval { +\& local $SIG{ALRM} = sub { die "alarm\en" }; # NB: \en required +\& alarm $timeout; +\& $nread = sysread SOCKET, $buffer, $size; +\& alarm 0; +\& }; +\& if ($@) { +\& die unless $@ eq "alarm\en"; # propagate unexpected errors +\& # timed out +\& } +\& else { +\& # didn't +\& } +.Ve +.Sp +For more information see perlipc. +.IP "atan2 Y,X" 8 +.IX Xref "atan2 arctangent tan tangent" +.IX Item "atan2 Y,X" +Returns the arctangent of Y/X in the range \-PI to \s-1PI\s0. +.Sp +For the tangent operation, you may use the \f(CW\*(C`Math::Trig::tan\*(C'\fR +function, or use the familiar relation: +.Sp +.Vb 1 +\& sub tan { sin($_[0]) / cos($_[0]) } +.Ve +.Sp +Note that atan2(0, 0) is not well\-defined. +.IP "bind \s-1SOCKET\s0,NAME" 8 +.IX Xref "bind" +.IX Item "bind SOCKET,NAME" +Binds a network address to a socket, just as the bind system call +does. Returns true if it succeeded, false otherwise. \s-1NAME\s0 should be a +packed address of the appropriate type for the socket. See the examples in +\&\*(L"Sockets: Client/Server Communication\*(R" in perlipc. +.IP "binmode \s-1FILEHANDLE\s0, \s-1LAYER\s0" 8 +.IX Xref "binmode binary text DOS Windows" +.IX Item "binmode FILEHANDLE, LAYER" +.PD 0 +.IP "binmode \s-1FILEHANDLE\s0" 8 +.IX Item "binmode FILEHANDLE" +.PD +Arranges for \s-1FILEHANDLE\s0 to be read or written in \*(L"binary\*(R" or \*(L"text\*(R" +mode on systems where the run-time libraries distinguish between +binary and text files. If \s-1FILEHANDLE\s0 is an expression, the value is +taken as the name of the filehandle. Returns true on success, +otherwise it returns \f(CW\*(C`undef\*(C'\fR and sets \f(CW$!\fR (errno). +.Sp +On some systems (in general, \s-1DOS\s0 and Windows-based systems) \fIbinmode()\fR +is necessary when you're not working with a text file. For the sake +of portability it is a good idea to always use it when appropriate, +and to never use it when it isn't appropriate. Also, people can +set their I/O to be by default \s-1UTF\-8\s0 encoded Unicode, not bytes. +.Sp +In other words: regardless of platform, use \fIbinmode()\fR on binary data, +like for example images. +.Sp +If \s-1LAYER\s0 is present it is a single string, but may contain multiple +directives. The directives alter the behaviour of the file handle. +When \s-1LAYER\s0 is present using binmode on text file makes sense. +.Sp +If \s-1LAYER\s0 is omitted or specified as \f(CW\*(C`:raw\*(C'\fR the filehandle is made +suitable for passing binary data. This includes turning off possible \s-1CRLF\s0 +translation and marking it as bytes (as opposed to Unicode characters). +Note that, despite what may be implied in \fI\*(L"Programming Perl\*(R"\fR (the +Camel) or elsewhere, \f(CW\*(C`:raw\*(C'\fR is \fInot\fR the simply inverse of \f(CW\*(C`:crlf\*(C'\fR +\&\*(-- other layers which would affect binary nature of the stream are +\&\fIalso\fR disabled. See PerlIO, perlrun and the discussion about the +\&\s-1PERLIO\s0 environment variable. +.Sp +The \f(CW\*(C`:bytes\*(C'\fR, \f(CW\*(C`:crlf\*(C'\fR, and \f(CW\*(C`:utf8\*(C'\fR, and any other directives of the +form \f(CW\*(C`:...\*(C'\fR, are called I/O \fIlayers\fR. The \f(CW\*(C`open\*(C'\fR pragma can be used to +establish default I/O layers. See open. +.Sp +\&\fIThe \s-1LAYER\s0 parameter of the \fIbinmode()\fI function is described as \*(L"\s-1DISCIPLINE\s0\*(R" +in \*(L"Programming Perl, 3rd Edition\*(R". However, since the publishing of this +book, by many known as \*(L"Camel \s-1III\s0\*(R", the consensus of the naming of this +functionality has moved from \*(L"discipline\*(R" to \*(L"layer\*(R". All documentation +of this version of Perl therefore refers to \*(L"layers\*(R" rather than to +\&\*(L"disciplines\*(R". Now back to the regularly scheduled documentation...\fR +.Sp +To mark \s-1FILEHANDLE\s0 as \s-1UTF\-8\s0, use \f(CW\*(C`:utf8\*(C'\fR. +.Sp +In general, \fIbinmode()\fR should be called after \fIopen()\fR but before any I/O +is done on the filehandle. Calling \fIbinmode()\fR will normally flush any +pending buffered output data (and perhaps pending input data) on the +handle. An exception to this is the \f(CW\*(C`:encoding\*(C'\fR layer that +changes the default character encoding of the handle, see open. +The \f(CW\*(C`:encoding\*(C'\fR layer sometimes needs to be called in +mid\-stream, and it doesn't flush the stream. The \f(CW\*(C`:encoding\*(C'\fR +also implicitly pushes on top of itself the \f(CW\*(C`:utf8\*(C'\fR layer because +internally Perl will operate on \s-1UTF\-8\s0 encoded Unicode characters. +.Sp +The operating system, device drivers, C libraries, and Perl run-time +system all work together to let the programmer treat a single +character (\f(CW\*(C`\en\*(C'\fR) as the line terminator, irrespective of the external +representation. On many operating systems, the native text file +representation matches the internal representation, but on some +platforms the external representation of \f(CW\*(C`\en\*(C'\fR is made up of more than +one character. +.Sp +Mac \s-1OS\s0, all variants of Unix, and Stream_LF files on \s-1VMS\s0 use a single +character to end each line in the external representation of text (even +though that single character is \s-1CARRIAGE\s0 \s-1RETURN\s0 on Mac \s-1OS\s0 and \s-1LINE\s0 \s-1FEED\s0 +on Unix and most \s-1VMS\s0 files). In other systems like \s-1OS/2\s0, \s-1DOS\s0 and the +various flavors of MS-Windows your program sees a \f(CW\*(C`\en\*(C'\fR as a simple \f(CW\*(C`\ecJ\*(C'\fR, +but what's stored in text files are the two characters \f(CW\*(C`\ecM\ecJ\*(C'\fR. That +means that, if you don't use \fIbinmode()\fR on these systems, \f(CW\*(C`\ecM\ecJ\*(C'\fR +sequences on disk will be converted to \f(CW\*(C`\en\*(C'\fR on input, and any \f(CW\*(C`\en\*(C'\fR in +your program will be converted back to \f(CW\*(C`\ecM\ecJ\*(C'\fR on output. This is what +you want for text files, but it can be disastrous for binary files. +.Sp +Another consequence of using \fIbinmode()\fR (on some systems) is that +special end-of-file markers will be seen as part of the data stream. +For systems from the Microsoft family this means that if your binary +data contains \f(CW\*(C`\ecZ\*(C'\fR, the I/O subsystem will regard it as the end of +the file, unless you use \fIbinmode()\fR. +.Sp +\&\fIbinmode()\fR is not only important for \fIreadline()\fR and \fIprint()\fR operations, +but also when using \fIread()\fR, \fIseek()\fR, \fIsysread()\fR, \fIsyswrite()\fR and \fItell()\fR +(see perlport for more details). See the \f(CW$/\fR and \f(CW\*(C`$\e\*(C'\fR variables +in perlvar for how to manually set your input and output +line-termination sequences. +.IP "bless \s-1REF\s0,CLASSNAME" 8 +.IX Xref "bless" +.IX Item "bless REF,CLASSNAME" +.PD 0 +.IP "bless \s-1REF\s0" 8 +.IX Item "bless REF" +.PD +This function tells the thingy referenced by \s-1REF\s0 that it is now an object +in the \s-1CLASSNAME\s0 package. If \s-1CLASSNAME\s0 is omitted, the current package +is used. Because a \f(CW\*(C`bless\*(C'\fR is often the last thing in a constructor, +it returns the reference for convenience. Always use the two-argument +version if a derived class might inherit the function doing the blessing. +See perltoot and perlobj for more about the blessing (and blessings) +of objects. +.Sp +Consider always blessing objects in CLASSNAMEs that are mixed case. +Namespaces with all lowercase names are considered reserved for +Perl pragmata. Builtin types have all uppercase names. To prevent +confusion, you may wish to avoid such package names as well. Make sure +that \s-1CLASSNAME\s0 is a true value. +.Sp +See \*(L"Perl Modules\*(R" in perlmod. +.IP "caller \s-1EXPR\s0" 8 +.IX Xref "caller call stack stack stack trace" +.IX Item "caller EXPR" +.PD 0 +.IP "caller" 8 +.IX Item "caller" +.PD +Returns the context of the current subroutine call. In scalar context, +returns the caller's package name if there is a caller, that is, if +we're in a subroutine or \f(CW\*(C`eval\*(C'\fR or \f(CW\*(C`require\*(C'\fR, and the undefined value +otherwise. In list context, returns +.Sp +.Vb 1 +\& ($package, $filename, $line) = caller; +.Ve +.Sp +With \s-1EXPR\s0, it returns some extra information that the debugger uses to +print a stack trace. The value of \s-1EXPR\s0 indicates how many call frames +to go back before the current one. +.Sp +.Vb 2 +\& ($package, $filename, $line, $subroutine, $hasargs, +\& $wantarray, $evaltext, $is_require, $hints, $bitmask) = caller($i); +.Ve +.Sp +Here \f(CW$subroutine\fR may be \f(CW\*(C`(eval)\*(C'\fR if the frame is not a subroutine +call, but an \f(CW\*(C`eval\*(C'\fR. In such a case additional elements \f(CW$evaltext\fR and +\&\f(CW$is_require\fR are set: \f(CW$is_require\fR is true if the frame is created by a +\&\f(CW\*(C`require\*(C'\fR or \f(CW\*(C`use\*(C'\fR statement, \f(CW$evaltext\fR contains the text of the +\&\f(CW\*(C`eval EXPR\*(C'\fR statement. In particular, for an \f(CW\*(C`eval BLOCK\*(C'\fR statement, +\&\f(CW$filename\fR is \f(CW\*(C`(eval)\*(C'\fR, but \f(CW$evaltext\fR is undefined. (Note also that +each \f(CW\*(C`use\*(C'\fR statement creates a \f(CW\*(C`require\*(C'\fR frame inside an \f(CW\*(C`eval EXPR\*(C'\fR +frame.) \f(CW$subroutine\fR may also be \f(CW\*(C`(unknown)\*(C'\fR if this particular +subroutine happens to have been deleted from the symbol table. +\&\f(CW$hasargs\fR is true if a new instance of \f(CW at _\fR was set up for the frame. +\&\f(CW$hints\fR and \f(CW$bitmask\fR contain pragmatic hints that the caller was +compiled with. The \f(CW$hints\fR and \f(CW$bitmask\fR values are subject to change +between versions of Perl, and are not meant for external use. +.Sp +Furthermore, when called from within the \s-1DB\s0 package, caller returns more +detailed information: it sets the list variable \f(CW at DB::args\fR to be the +arguments with which the subroutine was invoked. +.Sp +Be aware that the optimizer might have optimized call frames away before +\&\f(CW\*(C`caller\*(C'\fR had a chance to get the information. That means that \f(CWcaller(N)\fR +might not return information about the call frame you expect it do, for +\&\f(CW\*(C`N > 1\*(C'\fR. In particular, \f(CW at DB::args\fR might have information from the +previous time \f(CW\*(C`caller\*(C'\fR was called. +.IP "chdir \s-1EXPR\s0" 8 +.IX Xref "chdir cd" +.IX Item "chdir EXPR" +.PD 0 +.IP "chdir \s-1FILEHANDLE\s0" 8 +.IX Item "chdir FILEHANDLE" +.IP "chdir \s-1DIRHANDLE\s0" 8 +.IX Item "chdir DIRHANDLE" +.IP "chdir" 8 +.IX Item "chdir" +.PD +Changes the working directory to \s-1EXPR\s0, if possible. If \s-1EXPR\s0 is omitted, +changes to the directory specified by \f(CW$ENV{HOME}\fR, if set; if not, +changes to the directory specified by \f(CW$ENV{LOGDIR}\fR. (Under \s-1VMS\s0, the +variable \f(CW$ENV{SYS$LOGIN}\fR is also checked, and used if it is set.) If +neither is set, \f(CW\*(C`chdir\*(C'\fR does nothing. It returns true upon success, +false otherwise. See the example under \f(CW\*(C`die\*(C'\fR. +.Sp +On systems that support fchdir, you might pass a file handle or +directory handle as argument. On systems that don't support fchdir, +passing handles produces a fatal error at run time. +.IP "chmod \s-1LIST\s0" 8 +.IX Xref "chmod permission mode" +.IX Item "chmod LIST" +Changes the permissions of a list of files. The first element of the +list must be the numerical mode, which should probably be an octal +number, and which definitely should \fInot\fR be a string of octal digits: +\&\f(CW0644\fR is okay, \f(CW'0644'\fR is not. Returns the number of files +successfully changed. See also \*(L"oct\*(R", if all you have is a string. +.Sp +.Vb 6 +\& $cnt = chmod 0755, 'foo', 'bar'; +\& chmod 0755, @executables; +\& $mode = '0644'; chmod $mode, 'foo'; # !!! sets mode to +\& # --w----r-T +\& $mode = '0644'; chmod oct($mode), 'foo'; # this is better +\& $mode = 0644; chmod $mode, 'foo'; # this is best +.Ve +.Sp +On systems that support fchmod, you might pass file handles among the +files. On systems that don't support fchmod, passing file handles +produces a fatal error at run time. +.Sp +.Vb 3 +\& open(my $fh, "<", "foo"); +\& my $perm = (stat $fh)[2] & 07777; +\& chmod($perm | 0600, $fh); +.Ve +.Sp +You can also import the symbolic \f(CW\*(C`S_I*\*(C'\fR constants from the Fcntl +module: +.Sp +.Vb 1 +\& use Fcntl ':mode'; +.Ve +.Sp +.Vb 2 +\& chmod S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH|S_IXOTH, @executables; +\& # This is identical to the chmod 0755 of the above example. +.Ve +.IP "chomp \s-1VARIABLE\s0" 8 +.IX Xref "chomp INPUT_RECORD_SEPARATOR $ newline eol" +.IX Item "chomp VARIABLE" +.PD 0 +.IP "chomp( \s-1LIST\s0 )" 8 +.IX Item "chomp( LIST )" +.IP "chomp" 8 +.IX Item "chomp" +.PD +This safer version of \*(L"chop\*(R" removes any trailing string +that corresponds to the current value of \f(CW$/\fR (also known as +\&\f(CW$INPUT_RECORD_SEPARATOR\fR in the \f(CW\*(C`English\*(C'\fR module). It returns the total +number of characters removed from all its arguments. It's often used to +remove the newline from the end of an input record when you're worried +that the final record may be missing its newline. When in paragraph +mode (\f(CW\*(C`$/ = ""\*(C'\fR), it removes all trailing newlines from the string. +When in slurp mode (\f(CW\*(C`$/ = undef\*(C'\fR) or fixed-length record mode (\f(CW$/\fR is +a reference to an integer or the like, see perlvar) \fIchomp()\fR won't +remove anything. +If \s-1VARIABLE\s0 is omitted, it chomps \f(CW$_\fR. Example: +.Sp +.Vb 5 +\& while (<>) { +\& chomp; # avoid \en on last field +\& @array = split(/:/); +\& # ... +\& } +.Ve +.Sp +If \s-1VARIABLE\s0 is a hash, it chomps the hash's values, but not its keys. +.Sp + Added: external/Pygments-0.8.1/tests/examplefiles/phpcomplete.vim ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/phpcomplete.vim Thu Aug 9 17:43:13 2007 @@ -0,0 +1,567 @@ +" Vim completion script +" Language: PHP +" Maintainer: Mikolaj Machowski ( mikmach AT wp DOT pl ) +" Last Change: 2006 May 9 +" +" TODO: +" - Class aware completion: +" a) caching? +" - Switching to HTML (XML?) completion (SQL) inside of phpStrings +" - allow also for XML completion <- better do html_flavor for HTML +" completion +" - outside of getting parent tag may cause problems. Heh, even in +" perfect conditions GetLastOpenTag doesn't cooperate... Inside of +" phpStrings this can be even a bonus but outside of it is not the +" best situation + +function! phpcomplete#CompletePHP(findstart, base) + if a:findstart + unlet! b:php_menu + " Check if we are inside of PHP markup + let pos = getpos('.') + let phpbegin = searchpairpos('', 'bWn', + \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string\|comment"') + let phpend = searchpairpos('', 'Wn', + \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string\|comment"') + + if phpbegin == [0,0] && phpend == [0,0] + " We are outside of any PHP markup. Complete HTML + let htmlbegin = htmlcomplete#CompleteTags(1, '') + let cursor_col = pos[2] + let base = getline('.')[htmlbegin : cursor_col] + let b:php_menu = htmlcomplete#CompleteTags(0, base) + return htmlbegin + else + " locate the start of the word + let line = getline('.') + let start = col('.') - 1 + let curline = line('.') + let compl_begin = col('.') - 2 + while start >= 0 && line[start - 1] =~ '[a-zA-Z_0-9\x7f-\xff$]' + let start -= 1 + endwhile + let b:compl_context = getline('.')[0:compl_begin] + return start + + " We can be also inside of phpString with HTML tags. Deal with + " it later (time, not lines). + endif + + endif + " If exists b:php_menu it means completion was already constructed we + " don't need to do anything more + if exists("b:php_menu") + return b:php_menu + endif + " Initialize base return lists + let res = [] + let res2 = [] + " a:base is very short - we need context + if exists("b:compl_context") + let context = b:compl_context + unlet! b:compl_context + endif + + if !exists('g:php_builtin_functions') + call phpcomplete#LoadData() + endif + + let scontext = substitute(context, '\$\?[a-zA-Z_\x7f-\xff][a-zA-Z_0-9\x7f-\xff]*$', '', '') + + if scontext =~ '\(=\s*new\|extends\)\s\+$' + " Complete class name + " Internal solution for finding classes in current file. + let file = getline(1, '$') + call filter(file, + \ 'v:val =~ "class\\s\\+[a-zA-Z_\\x7f-\\xff][a-zA-Z_0-9\\x7f-\\xff]*\\s*("') + let fnames = join(map(tagfiles(), 'escape(v:val, " \\#%")')) + let jfile = join(file, ' ') + let int_values = split(jfile, 'class\s\+') + let int_classes = {} + for i in int_values + let c_name = matchstr(i, '^[a-zA-Z_\x7f-\xff][a-zA-Z_0-9\x7f-\xff]*') + if c_name != '' + let int_classes[c_name] = '' + endif + endfor + + " Prepare list of classes from tags file + let ext_classes = {} + let fnames = join(map(tagfiles(), 'escape(v:val, " \\#%")')) + if fnames != '' + exe 'silent! vimgrep /^'.a:base.'.*\tc\(\t\|$\)/j '.fnames + let qflist = getqflist() + if len(qflist) > 0 + for field in qflist + " [:space:] thing: we don't have to be so strict when + " dealing with tags files - entries there were already + " checked by ctags. + let item = matchstr(field['text'], '^[^[:space:]]\+') + let ext_classes[item] = '' + endfor + endif + endif + + " Prepare list of built in classes from g:php_builtin_functions + if !exists("g:php_omni_bi_classes") + let g:php_omni_bi_classes = {} + for i in keys(g:php_builtin_object_functions) + let g:php_omni_bi_classes[substitute(i, '::.*$', '', '')] = '' + endfor + endif + + let classes = sort(keys(int_classes)) + let classes += sort(keys(ext_classes)) + let classes += sort(keys(g:php_omni_bi_classes)) + + for m in classes + if m =~ '^'.a:base + call add(res, m) + endif + endfor + + let final_menu = [] + for i in res + let final_menu += [{'word':i, 'kind':'c'}] + endfor + + return final_menu + + elseif scontext =~ '\(->\|::\)$' + " Complete user functions and variables + " Internal solution for current file. + " That seems as unnecessary repeating of functions but there are + " few not so subtle differences as not appending of $ and addition + " of 'kind' tag (not necessary in regular completion) + + if scontext =~ '->$' && scontext !~ '\$this->$' + + " Get name of the class + let classname = phpcomplete#GetClassName(scontext) + + " Get location of class definition, we have to iterate through all + " tags files separately because we need relative path from current + " file to the exact file (tags file can be in different dir) + if classname != '' + let classlocation = phpcomplete#GetClassLocation(classname) + else + let classlocation = '' + endif + + if classlocation == 'VIMPHP_BUILTINOBJECT' + + for object in keys(g:php_builtin_object_functions) + if object =~ '^'.classname + let res += [{'word':substitute(object, '.*::', '', ''), + \ 'info': g:php_builtin_object_functions[object]}] + endif + endfor + + return res + + endif + + if filereadable(classlocation) + let classfile = readfile(classlocation) + let classcontent = '' + let classcontent .= "\n".phpcomplete#GetClassContents(classfile, classname) + let sccontent = split(classcontent, "\n") + + " YES, YES, YES! - we have whole content including extends! + " Now we need to get two elements: public functions and public + " vars + " NO, NO, NO! - third separate filtering looking for content + " :(, but all of them have differences. To squeeze them into + " one implementation would require many additional arguments + " and ifs. No good solution + " Functions declared with public keyword or without any + " keyword are public + let functions = filter(deepcopy(sccontent), + \ 'v:val =~ "^\\s*\\(static\\s\\+\\|public\\s\\+\\)*function"') + let jfuncs = join(functions, ' ') + let sfuncs = split(jfuncs, 'function\s\+') + let c_functions = {} + for i in sfuncs + let f_name = matchstr(i, + \ '^&\?\zs[a-zA-Z_\x7f-\xff][a-zA-Z_0-9\x7f-\xff]*\ze') + let f_args = matchstr(i, + \ '^&\?[a-zA-Z_\x7f-\xff][a-zA-Z_0-9\x7f-\xff]*\s*(\zs.\{-}\ze)\_s*{') + if f_name != '' + let c_functions[f_name.'('] = f_args + endif + endfor + " Variables declared with var or with public keyword are + " public + let variables = filter(deepcopy(sccontent), + \ 'v:val =~ "^\\s*\\(public\\|var\\)\\s\\+\\$"') + let jvars = join(variables, ' ') + let svars = split(jvars, '\$') + let c_variables = {} + for i in svars + let c_var = matchstr(i, + \ '^\zs[a-zA-Z_\x7f-\xff][a-zA-Z_0-9\x7f-\xff]*\ze') + if c_var != '' + let c_variables[c_var] = '' + endif + endfor + + let all_values = {} + call extend(all_values, c_functions) + call extend(all_values, c_variables) + + for m in sort(keys(all_values)) + if m =~ '^'.a:base && m !~ '::' + call add(res, m) + elseif m =~ '::'.a:base + call add(res2, m) + endif + endfor + + let start_list = res + res2 + + let final_list = [] + for i in start_list + if has_key(c_variables, i) + let class = ' ' + if all_values[i] != '' + let class = i.' class ' + endif + let final_list += + \ [{'word':i, + \ 'info':class.all_values[i], + \ 'kind':'v'}] + else + let final_list += + \ [{'word':substitute(i, '.*::', '', ''), + \ 'info':i.all_values[i].')', + \ 'kind':'f'}] + endif + endfor + + return final_list + + endif + + endif + + if a:base =~ '^\$' + let adddollar = '$' + else + let adddollar = '' + endif + let file = getline(1, '$') + let jfile = join(file, ' ') + let sfile = split(jfile, '\$') + let int_vars = {} + for i in sfile + if i =~ '^\$[a-zA-Z_\x7f-\xff][a-zA-Z_0-9\x7f-\xff]*\s*=\s*new' + let val = matchstr(i, '^[a-zA-Z_\x7f-\xff][a-zA-Z_0-9\x7f-\xff]*').'->' + else + let val = matchstr(i, '^[a-zA-Z_\x7f-\xff][a-zA-Z_0-9\x7f-\xff]*') + endif + if val !~ '' + let int_vars[adddollar.val] = '' + endif + endfor + + " ctags has good support for PHP, use tags file for external + " variables + let fnames = join(map(tagfiles(), 'escape(v:val, " \\#%")')) + let ext_vars = {} + if fnames != '' + let sbase = substitute(a:base, '^\$', '', '') + exe 'silent! vimgrep /^'.sbase.'.*\tv\(\t\|$\)/j '.fnames + let qflist = getqflist() + if len(qflist) > 0 + for field in qflist + let item = matchstr(field['text'], '^[^[:space:]]\+') + " Add -> if it is possible object declaration + let classname = '' + if field['text'] =~ item.'\s*=\s*new\s\+' + let item = item.'->' + let classname = matchstr(field['text'], + \ '=\s*new\s\+\zs[a-zA-Z_0-9\x7f-\xff]\+\ze') + endif + let ext_vars[adddollar.item] = classname + endfor + endif + endif + + " Now we have all variables in int_vars dictionary + call extend(int_vars, ext_vars) + + " Internal solution for finding functions in current file. + let file = getline(1, '$') + call filter(file, + \ 'v:val =~ "function\\s\\+&\\?[a-zA-Z_\\x7f-\\xff][a-zA-Z_0-9\\x7f-\\xff]*\\s*("') + let fnames = join(map(tagfiles(), 'escape(v:val, " \\#%")')) + let jfile = join(file, ' ') + let int_values = split(jfile, 'function\s\+') + let int_functions = {} + for i in int_values + let f_name = matchstr(i, + \ '^&\?\zs[a-zA-Z_\x7f-\xff][a-zA-Z_0-9\x7f-\xff]*\ze') + let f_args = matchstr(i, + \ '^&\?[a-zA-Z_\x7f-\xff][a-zA-Z_0-9\x7f-\xff]*\s*(\zs.\{-}\ze)\_s*{') + let int_functions[f_name.'('] = f_args.')' + endfor + + " Prepare list of functions from tags file + let ext_functions = {} + if fnames != '' + exe 'silent! vimgrep /^'.a:base.'.*\tf\(\t\|$\)/j '.fnames + let qflist = getqflist() + if len(qflist) > 0 + for field in qflist + " File name + let item = matchstr(field['text'], '^[^[:space:]]\+') + let fname = matchstr(field['text'], '\t\zs\f\+\ze') + let prototype = matchstr(field['text'], + \ 'function\s\+&\?[^[:space:]]\+\s*(\s*\zs.\{-}\ze\s*)\s*{\?') + let ext_functions[item.'('] = prototype.') - '.fname + endfor + endif + endif + + let all_values = {} + call extend(all_values, int_functions) + call extend(all_values, ext_functions) + call extend(all_values, int_vars) " external variables are already in + call extend(all_values, g:php_builtin_object_functions) + + for m in sort(keys(all_values)) + if m =~ '\(^\|::\)'.a:base + call add(res, m) + endif + endfor + + let start_list = res + + let final_list = [] + for i in start_list + if has_key(int_vars, i) + let class = ' ' + if all_values[i] != '' + let class = i.' class ' + endif + let final_list += [{'word':i, 'info':class.all_values[i], 'kind':'v'}] + else + let final_list += + \ [{'word':substitute(i, '.*::', '', ''), + \ 'info':i.all_values[i], + \ 'kind':'f'}] + endif + endfor + + return final_list + endif + + if a:base =~ '^\$' + " Complete variables + " Built-in variables {{{ + let g:php_builtin_vars = {'$GLOBALS':'', + \ '$_SERVER':'', + \ '$_GET':'', + \ '$_POST':'', + \ '$_COOKIE':'', + \ '$_FILES':'', + \ '$_ENV':'', + \ '$_REQUEST':'', + \ '$_SESSION':'', + \ '$HTTP_SERVER_VARS':'', + \ '$HTTP_ENV_VARS':'', + \ '$HTTP_COOKIE_VARS':'', + \ '$HTTP_GET_VARS':'', + \ '$HTTP_POST_VARS':'', + \ '$HTTP_POST_FILES':'', + \ '$HTTP_SESSION_VARS':'', + \ '$php_errormsg':'', + \ '$this':'' + \ } + " }}} + + " Internal solution for current file. + let file = getline(1, '$') + let jfile = join(file, ' ') + let int_vals = split(jfile, '\ze\$') + let int_vars = {} + for i in int_vals + if i =~ '^\$[a-zA-Z_\x7f-\xff][a-zA-Z_0-9\x7f-\xff]*\s*=\s*new' + let val = matchstr(i, + \ '^\$[a-zA-Z_\x7f-\xff][a-zA-Z_0-9\x7f-\xff]*').'->' + else + let val = matchstr(i, + \ '^\$[a-zA-Z_\x7f-\xff][a-zA-Z_0-9\x7f-\xff]*') + endif + if val != '' + let int_vars[val] = '' + endif + endfor + + call extend(int_vars,g:php_builtin_vars) + + " ctags has support for PHP, use tags file for external variables + let fnames = join(map(tagfiles(), 'escape(v:val, " \\#%")')) + let ext_vars = {} + if fnames != '' + let sbase = substitute(a:base, '^\$', '', '') + exe 'silent! vimgrep /^'.sbase.'.*\tv\(\t\|$\)/j '.fnames + let qflist = getqflist() + if len(qflist) > 0 + for field in qflist + let item = '$'.matchstr(field['text'], '^[^[:space:]]\+') + let m_menu = '' + " Add -> if it is possible object declaration + if field['text'] =~ item.'\s*=\s*new\s\+' + let item = item.'->' + let m_menu = matchstr(field['text'], + \ '=\s*new\s\+\zs[a-zA-Z_0-9\x7f-\xff]\+\ze') + endif + let ext_vars[item] = m_menu + endfor + endif + endif + + call extend(int_vars, ext_vars) + let g:a0 = keys(int_vars) + + for m in sort(keys(int_vars)) + if m =~ '^\'.a:base + call add(res, m) + endif + endfor + + let int_list = res + + let int_dict = [] + for i in int_list + if int_vars[i] != '' + let class = ' ' + if int_vars[i] != '' + let class = i.' class ' + endif + let int_dict += [{'word':i, 'info':class.int_vars[i], 'kind':'v'}] + else + let int_dict += [{'word':i, 'kind':'v'}] + endif + endfor + + return int_dict + + else + " Complete everything else - + " + functions, DONE + " + keywords of language DONE + " + defines (constant definitions), DONE + " + extend keywords for predefined constants, DONE + " + classes (after new), DONE + " + limit choice after -> and :: to funcs and vars DONE + + " Internal solution for finding functions in current file. + let file = getline(1, '$') + call filter(file, + \ 'v:val =~ "function\\s\\+&\\?[a-zA-Z_\\x7f-\\xff][a-zA-Z_0-9\\x7f-\\xff]*\\s*("') + let fnames = join(map(tagfiles(), 'escape(v:val, " \\#%")')) + let jfile = join(file, ' ') + let int_values = split(jfile, 'function\s\+') + let int_functions = {} + for i in int_values + let f_name = matchstr(i, + \ '^&\?\zs[a-zA-Z_\x7f-\xff][a-zA-Z_0-9\x7f-\xff]*\ze') + let f_args = matchstr(i, + \ '^&\?[a-zA-Z_\x7f-\xff][a-zA-Z_0-9\x7f-\xff]*\s*(\s*\zs.\{-}\ze\s*)\_s*{') + let int_functions[f_name.'('] = f_args.')' + endfor + + " Prepare list of functions from tags file + let ext_functions = {} + if fnames != '' + exe 'silent! vimgrep /^'.a:base.'.*\tf\(\t\|$\)/j '.fnames + let qflist = getqflist() + if len(qflist) > 0 + for field in qflist + " File name + let item = matchstr(field['text'], '^[^[:space:]]\+') + let fname = matchstr(field['text'], '\t\zs\f\+\ze') + let prototype = matchstr(field['text'], + \ 'function\s\+&\?[^[:space:]]\+\s*(\s*\zs.\{-}\ze\s*)\s*{\?') + let ext_functions[item.'('] = prototype.') - '.fname + endfor + endif + endif + + " All functions + call extend(int_functions, ext_functions) + call extend(int_functions, g:php_builtin_functions) + + " Internal solution for finding constants in current file + let file = getline(1, '$') + call filter(file, 'v:val =~ "define\\s*("') + let jfile = join(file, ' ') + let int_values = split(jfile, 'define\s*(\s*') + let int_constants = {} + for i in int_values + let c_name = matchstr(i, '\(["'']\)\zs[a-zA-Z_\x7f-\xff][a-zA-Z_0-9\x7f-\xff]*\ze\1') + " let c_value = matchstr(i, + " \ '\(["'']\)[a-zA-Z_\x7f-\xff][a-zA-Z_0-9\x7f-\xff]*\1\s*,\s*\zs.\{-}\ze\s*)') + if c_name != '' + let int_constants[c_name] = '' " c_value + endif + endfor + + " Prepare list of constants from tags file + let fnames = join(map(tagfiles(), 'escape(v:val, " \\#%")')) + let ext_constants = {} + if fnames != '' + exe 'silent! vimgrep /^'.a:base.'.*\td\(\t\|$\)/j '.fnames + let qflist = getqflist() + if len(qflist) > 0 + for field in qflist + let item = matchstr(field['text'], '^[^[:space:]]\+') + let ext_constants[item] = '' + endfor + endif + endif + + " All constants + call extend(int_constants, ext_constants) + " Treat keywords as constants + + let all_values = {} + + " One big dictionary of functions + call extend(all_values, int_functions) + + " Add constants + call extend(all_values, int_constants) + " Add keywords + call extend(all_values, g:php_keywords) + + for m in sort(keys(all_values)) + if m =~ '^'.a:base + call add(res, m) + endif + endfor + + let int_list = res + + let final_list = [] + for i in int_list + if has_key(int_functions, i) + let final_list += + \ [{'word':i, + \ 'info':i.int_functions[i], + \ 'kind':'f'}] + elseif has_key(int_constants, i) + let final_list += [{'word':i, 'kind':'d'}] + else + let final_list += [{'word':i}] + endif + endfor + + return final_list + + endif + +endfunction +" vim:set foldmethod=marker: Added: external/Pygments-0.8.1/tests/examplefiles/pleac.in.rb ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/pleac.in.rb Thu Aug 9 17:43:13 2007 @@ -0,0 +1,1223 @@ +# -*- ruby -*- + +# Local variables: +# indent-tabs-mode: nil +# ruby-indent-level: 4 +# End: + +# @@PLEAC@@_NAME +# @@SKIP@@ Ruby + +# @@PLEAC@@_WEB +# @@SKIP@@ http://www.ruby-lang.org + + +# @@PLEAC@@_1.0 +string = '\n' # two characters, \ and an n +string = 'Jon \'Maddog\' Orwant' # literal single quotes + +string = "\n" # a "newline" character +string = "Jon \"Maddog\" Orwant" # literal double quotes + +string = %q/Jon 'Maddog' Orwant/ # literal single quotes + +string = %q[Jon 'Maddog' Orwant] # literal single quotes +string = %q{Jon 'Maddog' Orwant} # literal single quotes +string = %q(Jon 'Maddog' Orwant) # literal single quotes +string = %q # literal single quotes + +a = <<"EOF" +This is a multiline here document +terminated by EOF on a line by itself +EOF + + +# @@PLEAC@@_1.1 +value = string[offset,count] +value = string[offset..-1] + +string[offset,count] = newstring +string[offset..-1] = newtail + +# in Ruby we can also specify intervals by their two offsets +value = string[offset..offs2] +string[offset..offs2] = newstring + +leading, s1, s2, trailing = data.unpack("A5 x3 A8 A8 A*") + +fivers = string.unpack("A5" * (string.length/5)) + +chars = string.unpack("A1" * string.length) + +string = "This is what you have" +# +012345678901234567890 Indexing forwards (left to right) +# 109876543210987654321- Indexing backwards (right to left) +# note that 0 means 10 or 20, etc. above + +first = string[0, 1] # "T" +start = string[5, 2] # "is" +rest = string[13..-1] # "you have" +last = string[-1, 1] # "e" +end_ = string[-4..-1] # "have" +piece = string[-8, 3] # "you" + +string[5, 2] = "wasn't" # change "is" to "wasn't" +string[-12..-1] = "ondrous" # "This wasn't wondrous" +string[0, 1] = "" # delete first character +string[-10..-1] = "" # delete last 10 characters + +if string[-10..-1] =~ /pattern/ + puts "Pattern matches in last 10 characters" +end + +string[0, 5].gsub!(/is/, 'at') + +a = "make a hat" +a[0, 1], a[-1, 1] = a[-1, 1], a[0, 1] + +a = "To be or not to be" +b = a.unpack("x6 A6") + +b, c = a.unpack("x6 A2 X5 A2") +puts "#{b}\n#{c}\n" + +def cut2fmt(*args) + template = '' + lastpos = 1 + for place in args + template += "A" + (place - lastpos).to_s + " " + lastpos = place + end + template += "A*" + return template +end + +fmt = cut2fmt(8, 14, 20, 26, 30) + + +# @@PLEAC@@_1.2 +# careful! "b is true" doesn't mean "b != 0" (0 is true in Ruby) +# thus no problem of "defined" later since only nil is false +# the following sets to `c' if `b' is nil or false +a = b || c + +# if you need Perl's behaviour (setting to `c' if `b' is 0) the most +# effective way is to use Numeric#nonzero? (thanks to Dave Thomas!) +a = b.nonzero? || c + +# you will still want to use defined? in order to test +# for scope existence of a given object +a = defined?(b) ? b : c + +dir = ARGV.shift || "/tmp" + + +# @@PLEAC@@_1.3 +v1, v2 = v2, v1 + +alpha, beta, production = %w(January March August) +alpha, beta, production = beta, production, alpha + + +# @@PLEAC@@_1.4 +num = char[0] +char = num.chr + +# Ruby also supports having a char from character constant +num = ?r + +char = sprintf("%c", num) +printf("Number %d is character %c\n", num, num) + +ascii = string.unpack("C*") +string = ascii.pack("C*") + +hal = "HAL" +ascii = hal.unpack("C*") +# We can't use Array#each since we can't mutate a Fixnum +ascii.collect! { |i| + i + 1 # add one to each ASCII value +} +ibm = ascii.pack("C*") +puts ibm + + +# @@PLEAC@@_1.5 +array = string.split('') + +array = string.unpack("C*") + +string.scan(/./) { |b| + # do something with b +} + +string = "an apple a day" +print "unique chars are: ", string.split('').uniq.sort, "\n" + +sum = 0 +for ascval in string.unpack("C*") # or use Array#each for a pure OO style :) + sum += ascval +end +puts "sum is #{sum & 0xffffffff}" # since Ruby will go Bignum if necessary + +# @@INCLUDE@@ include/ruby/slowcat.rb + + +# @@PLEAC@@_1.6 +revbytes = string.reverse + +revwords = string.split(" ").reverse.join(" ") + +revwords = string.split(/(\s+)/).reverse.join + +# using the fact that IO is Enumerable, you can directly "select" it +long_palindromes = File.open("/usr/share/dict/words"). + select { |w| w.chomp!; w.reverse == w && w.length > 5 } + + +# @@PLEAC@@_1.7 +while string.sub!("\t+") { ' ' * ($&.length * 8 - $`.length % 8) } +end + + +# @@PLEAC@@_1.8 +'You owe #{debt} to me'.gsub(/\#{(\w+)}/) { eval($1) } + +rows, cols = 24, 80 +text = %q(I am #{rows} high and #{cols} long) +text.gsub!(/\#{(\w+)}/) { eval("#{$1}") } +puts text + +'I am 17 years old'.gsub(/\d+/) { 2 * $&.to_i } + + +# @@PLEAC@@_1.9 +e = "bo peep".upcase +e.downcase! +e.capitalize! + +"thIS is a loNG liNE".gsub!(/\w+/) { $&.capitalize } + + +# @@PLEAC@@_1.10 +"I have #{n+1} guanacos." +print "I have ", n+1, " guanacos." + + +# @@PLEAC@@_1.11 +var = <<'EOF'.gsub(/^\s+/, '') + your text + goes here +EOF + + +# @@PLEAC@@_1.12 +string = "Folding and splicing is the work of an editor,\n"+ + "not a mere collection of silicon\n"+ + "and\n"+ + "mobile electrons!" + +def wrap(str, max_size) + all = [] + line = '' + for l in str.split + if (line+l).length >= max_size + all.push(line) + line = '' + end + line += line == '' ? l : ' ' + l + end + all.push(line).join("\n") +end + +print wrap(string, 20) +#=> Folding and +#=> splicing is the +#=> work of an editor, +#=> not a mere +#=> collection of +#=> silicon and mobile +#=> electrons! + + +# @@PLEAC@@_1.13 +string = %q(Mom said, "Don't do that.") +string.gsub(/['"]/) { '\\'+$& } +string.gsub(/['"]/, '\&\&') +string.gsub(/[^A-Z]/) { '\\'+$& } +"is a test!".gsub(/\W/) { '\\'+$& } # no function like quotemeta? + + +# @@PLEAC@@_1.14 +string.strip! + + +# @@PLEAC@@_1.15 +def parse_csv(text) + new = text.scan(/"([^\"\\]*(?:\\.[^\"\\]*)*)",?|([^,]+),?|,/) + new << nil if text[-1] == ?, + new.flatten.compact +end + +line = %q +fields = parse_csv(line) +fields.each_with_index { |v,i| + print "#{i} : #{v}\n"; +} + + +# @@PLEAC@@_1.16 +# Use the soundex.rb Library from Michael Neumann. +# http://www.s-direktnet.de/homepages/neumann/rb_prgs/Soundex.rb +require 'Soundex' + +code = Text::Soundex.soundex(string) +codes = Text::Soundex.soundex(array) + +# substitution function for getpwent(): +# returns an array of user entries, +# each entry contains the username and the full name +def login_names + result = [] + File.open("/etc/passwd") { |file| + file.each_line { |line| + next if line.match(/^#/) + cols = line.split(":") + result.push([cols[0], cols[4]]) + } + } + result +end + +puts "Lookup user: " +user = STDIN.gets +user.chomp! +exit unless user +name_code = Text::Soundex.soundex(user) + +splitter = Regexp.new('(\w+)[^,]*\b(\w+)') +for username, fullname in login_names do + firstname, lastname = splitter.match(fullname)[1,2] + if name_code == Text::Soundex.soundex(username) + || name_code == Text::Soundex.soundex(firstname) + || name_code == Text::Soundex.soundex(lastname) + then + puts "#{username}: #{firstname} #{lastname}" + end +end + + +# @@PLEAC@@_1.17 +# @@INCLUDE@@ include/ruby/fixstyle.rb + + +# @@PLEAC@@_1.18 +# @@INCLUDE@@ include/ruby/psgrep.rb + + +# @@PLEAC@@_2.1 +# Matz tells that you can use Integer() for strict checked conversion. +Integer("abc") +#=> `Integer': invalid value for Integer: "abc" (ArgumentError) +Integer("567") +#=> 567 + +# You may use Float() for floating point stuff +Integer("56.7") +#=> `Integer': invalid value for Integer: "56.7" (ArgumentError) +Float("56.7") +#=> 56.7 + +# You may also use a regexp for that +if string =~ /^[+-]?\d+$/ + p 'is an integer' +else + p 'is not' +end + +if string =~ /^-?(?:\d+(?:\.\d*)?|\.\d+)$/ + p 'is a decimal number' +else + p 'is not' +end + + +# @@PLEAC@@_2.2 +# equal(num1, num2, accuracy) : returns true if num1 and num2 are +# equal to accuracy number of decimal places +def equal(i, j, a) + sprintf("%.#{a}g", i) == sprintf("%.#{a}g", j) +end + +wage = 536 # $5.36/hour +week = 40 * wage # $214.40 +printf("One week's wage is: \$%.2f\n", week/100.0) + + +# @@PLEAC@@_2.3 +num.round # rounds to integer + +a = 0.255 +b = sprintf("%.2f", a) +print "Unrounded: #{a}\nRounded: #{b}\n" +printf "Unrounded: #{a}\nRounded: %.2f\n", a + +print "number\tint\tfloor\tceil\n" +a = [ 3.3 , 3.5 , 3.7, -3.3 ] +for n in a + printf("% .1f\t% .1f\t% .1f\t% .1f\n", # at least I don't fake my output :) + n, n.to_i, n.floor, n.ceil) +end + + +# @@PLEAC@@_2.4 +def dec2bin(n) + [n].pack("N").unpack("B32")[0].sub(/^0+(?=\d)/, '') +end + +def bin2dec(n) + [("0"*32+n.to_s)[-32..-1]].pack("B32").unpack("N")[0] +end + + +# @@PLEAC@@_2.5 +for i in x .. y + # i is set to every integer from x to y, inclusive +end + +x.step(y,7) { |i| + # i is set to every integer from x to y, stepsize = 7 +} + +print "Infancy is: " +(0..2).each { |i| + print i, " " +} +print "\n" + + +# @@PLEAC@@_2.6 +# We can add conversion methods to the Integer class, +# this makes a roman number just a representation for normal numbers. +class Integer + + @@romanlist = [["M", 1000], + ["CM", 900], + ["D", 500], + ["CD", 400], + ["C", 100], + ["XC", 90], + ["L", 50], + ["XL", 40], + ["X", 10], + ["IX", 9], + ["V", 5], + ["IV", 4], + ["I", 1]] + + def to_roman + remains = self + roman = "" + for sym, num in @@romanlist + while remains >= num + remains -= num + roman << sym + end + end + roman + end + + def Integer.from_roman(roman) + ustr = roman.upcase + sum = 0 + for entry in @@romanlist + sym, num = entry[0], entry[1] + while sym == ustr[0, sym.length] + sum += num + ustr.slice!(0, sym.length) + end + end + sum + end + +end + + +roman_fifteen = 15.to_roman +puts "Roman for fifteen is #{roman_fifteen}" +i = Integer.from_roman(roman_fifteen) +puts "Converted back, #{roman_fifteen} is #{i}" + +# check +for i in (1..3900) + r = i.to_roman + j = Integer.from_roman(r) + if i != j + puts "error: #{i} : #{r} - #{j}" + end +end + + +# @@PLEAC@@_2.7 +random = rand(y-x+1)+x + +chars = ["A".."Z","a".."z","0".."9"].collect { |r| r.to_a }.join + %q(!@$%^&*) +password = (1..8).collect { chars[rand(chars.size)] }.pack("C*") + + +# @@PLEAC@@_2.8 +srand # uses a combination of the time, the process id, and a sequence number +srand(val) # for repeatable behaviour + + +# @@PLEAC@@_2.9 +# from the randomr lib: +# http://raa.ruby-lang.org/project/randomr/ +----> http://raa.ruby-lang.org/project/randomr/ + +require 'random/mersenne_twister' +mers = Random::MersenneTwister.new 123456789 +puts mers.rand(0) # 0.550321932544541 +puts mers.rand(10) # 2 + +# using online sources of random data via the realrand package: +# http://raa.ruby-lang.org/project/realrand/ +# **Note** +# The following online services are used in this package: +# http://www.random.org - source: atmospheric noise +# http://www.fourmilab.ch/hotbits - source: radioactive decay timings +# http://random.hd.org - source: entropy from local and network noise +# Please visit the sites and respect the rules of each service. + +require 'random/online' + +generator1 = Random::RandomOrg.new +puts generator1.randbyte(5).join(",") +puts generator1.randnum(10, 1, 6).join(",") # Roll dice 10 times. + +generator2 = Random::FourmiLab.new +puts generator2.randbyte(5).join(",") +# randnum is not supported. + +generator3 = Random::EntropyPool.new +puts generator3.randbyte(5).join(",") +# randnum is not supported. + + +# @@PLEAC@@_2.10 +def gaussian_rand + begin + u1 = 2 * rand() - 1 + u2 = 2 * rand() - 1 + w = u1*u1 + u2*u2 + end while (w >= 1) + w = Math.sqrt((-2*Math.log(w))/w) + [ u2*w, u1*w ] +end + +mean = 25 +sdev = 2 +salary = gaussian_rand[0] * sdev + mean +printf("You have been hired at \$%.2f\n", salary) + + +# @@PLEAC@@_2.11 +def deg2rad(d) + (d/180.0)*Math::PI +end + +def rad2deg(r) + (r/Math::PI)*180 +end + + +# @@PLEAC@@_2.12 +sin_val = Math.sin(angle) +cos_val = Math.cos(angle) +tan_val = Math.tan(angle) + +# AFAIK Ruby's Math module doesn't provide acos/asin +# While we're at it, let's also define missing hyperbolic functions +module Math + def Math.asin(x) + atan2(x, sqrt(1 - x**2)) + end + def Math.acos(x) + atan2(sqrt(1 - x**2), x) + end + def Math.atan(x) + atan2(x, 1) + end + def Math.sinh(x) + (exp(x) - exp(-x)) / 2 + end + def Math.cosh(x) + (exp(x) + exp(-x)) / 2 + end + def Math.tanh(x) + sinh(x) / cosh(x) + end +end + +# The support for Complex numbers is not built-in +y = Math.acos(3.7) +#=> in `sqrt': square root for negative number (ArgumentError) + +# There is an implementation of Complex numbers in 'complex.rb' in current +# Ruby distro, but it doesn't support atan2 with complex args, so it doesn't +# solve this problem. + + +# @@PLEAC@@_2.13 +log_e = Math.log(val) +log_10 = Math.log10(val) + +def log_base(base, val) + Math.log(val)/Math.log(base) +end + +answer = log_base(10, 10_000) +puts "log10(10,000) = #{answer}" + + +# @@PLEAC@@_2.14 +require 'matrix.rb' + +a = Matrix[[3, 2, 3], [5, 9, 8]] +b = Matrix[[4, 7], [9, 3], [8, 1]] +c = a * b + +a.row_size +a.column_size + +c.det +a.transpose + + +# @@PLEAC@@_2.15 +require 'complex.rb' +require 'rational.rb' + +a = Complex(3, 5) # 3 + 5i +b = Complex(2, -2) # 2 - 2i +puts "c = #{a*b}" + +c = a * b +d = 3 + 4*Complex::I + +printf "sqrt(#{d}) = %s\n", Math.sqrt(d) + + +# @@PLEAC@@_2.16 +number = hexadecimal.hex +number = octal.oct + +print "Gimme a number in decimal, octal, or hex: " +num = gets.chomp +exit unless defined?(num) +num = num.oct if num =~ /^0/ # does both oct and hex +printf "%d %x %o\n", num, num, num + +print "Enter file permission in octal: " +permissions = gets.chomp +raise "Exiting ...\n" unless defined?(permissions) +puts "The decimal value is #{permissions.oct}" + + +# @@PLEAC@@_2.17 +def commify(n) + n.to_s =~ /([^\.]*)(\..*)?/ + int, dec = $1.reverse, $2 ? $2 : "" + while int.gsub!(/(,|\.|^)(\d{3})(\d)/, '\1\2,\3') + end + int.reverse + dec +end + + +# @@PLEAC@@_2.18 +printf "It took %d hour%s\n", time, time == 1 ? "" : "s" + +# dunno if an equivalent to Lingua::EN::Inflect exists... + + +# @@PLEAC@@_2.19 +#----------------------------- +#!/usr/bin/ruby +# bigfact - calculating prime factors +def factorize(orig) + factors = {} + factors.default = 0 # return 0 instead nil if key not found in hash + n = orig + i = 2 + sqi = 4 # square of i + while sqi <= n do + while n.modulo(i) == 0 do + n /= i + factors[i] += 1 + # puts "Found factor #{i}" + end + # we take advantage of the fact that (i +1)**2 = i**2 + 2*i +1 + sqi += 2 * i + 1 + i += 1 + end + + if (n != 1) && (n != orig) + factors[n] += 1 + end + factors +end + +def printfactorhash(orig, factorcount) + print format("%-10d ", orig) + if factorcount.length == 0 + print "PRIME" + else + # sorts after number, because the hash keys are numbers + factorcount.sort.each { |factor,exponent| + print factor + if exponent > 1 + print "**", exponent + end + print " " + } + end + puts +end + +for arg in ARGV + n = arg.to_i + mfactors = factorize(n) + printfactorhash(n, mfactors) +end +#----------------------------- + + +# @@PLEAC@@_3.0 +puts Time.now + +print "Today is day ", Time.now.yday, " of the current year.\n" +print "Today is day ", Time.now.day, " of the current month.\n" + + +# @@PLEAC@@_3.1 +day, month, year = Time.now.day, Time.now.month, Time.now.year +# or +day, month, year = Time.now.to_a[3..5] + +tl = Time.now.localtime +printf("The current date is %04d %02d %02d\n", tl.year, tl.month, tl.day) + +Time.now.localtime.strftime("%Y-%m-%d") + + +# @@PLEAC@@_3.2 +Time.local(year, month, day, hour, minute, second).tv_sec +Time.gm(year, month, day, hour, minute, second).tv_sec + + +# @@PLEAC@@_3.3 +sec, min, hour, day, month, year, wday, yday, isdst, zone = Time.at(epoch_secs).to_a + + +# @@PLEAC@@_3.4 +when_ = now + difference # now -> Time ; difference -> Numeric (delta in seconds) +then_ = now - difference + + +# @@PLEAC@@_3.5 +bree = 361535725 +nat = 96201950 + +difference = bree - nat +puts "There were #{difference} seconds between Nat and Bree" + +seconds = difference % 60 +difference = (difference - seconds) / 60 +minutes = difference % 60 +difference = (difference - minutes) / 60 +hours = difference % 24 +difference = (difference - hours) / 24 +days = difference % 7 +weeks = (difference - days) / 7 + +puts "(#{weeks} weeks, #{days} days, #{hours}:#{minutes}:#{seconds})" + + +# @@PLEAC@@_3.6 +monthday, weekday, yearday = date.mday, date.wday, date.yday + +# AFAIK the week number is not just a division since week boundaries are on sundays +weeknum = d.strftime("%U").to_i + 1 + +year = 1981 +month = "jun" # or `6' if you want to emulate a broken language +day = 16 +t = Time.mktime(year, month, day) +print "#{month}/#{day}/#{year} was a ", t.strftime("%A"), "\n" + + +# @@PLEAC@@_3.7 +yyyy, mm, dd = $1, $2, $3 if "1998-06-25" =~ /(\d+)-(\d+)-(\d+)/ + +epoch_seconds = Time.mktime(yyyy, mm, dd).tv_sec + +# dunno an equivalent to Date::Manip#ParseDate + + +# @@PLEAC@@_3.8 +string = Time.at(epoch_secs) +Time.at(1234567890).gmtime # gives: Fri Feb 13 23:31:30 UTC 2009 + +time = Time.mktime(1973, "jan", 18, 3, 45, 50) +print "In localtime it gives: ", time.localtime, "\n" + + +# @@PLEAC@@_3.9 +# Ruby provides micro-seconds in Time object +Time.now.usec + +# Ruby gives the seconds in floating format when substracting two Time objects +before = Time.now +line = gets +elapsed = Time.now - before +puts "You took #{elapsed} seconds." + +# On my Celeron-400 with Linux-2.2.19-14mdk, average for three execs are: +# This Ruby version: average 0.00321 sec +# Cookbook's Perl version: average 0.00981 sec +size = 500 +number_of_times = 100 +total_time = 0 +number_of_times.times { + # populate array + array = [] + size.times { array << rand } + # sort it + begin_ = Time.now + array.sort! + time = Time.now - begin_ + total_time += time +} +printf "On average, sorting %d random numbers takes %.5f seconds\n", + size, (total_time/Float(number_of_times)) + + +# @@PLEAC@@_3.10 +sleep(0.005) # Ruby is definitely not as broken as Perl :) +# (may be interrupted by sending the process a SIGALRM) + + +# @@PLEAC@@_3.11 +#!/usr/bin/ruby -w +# hopdelta - feed mail header, produce lines +# showing delay at each hop. +require 'time' +class MailHopDelta + + def initialize(mail) + @head = mail.gsub(/\n\s+/,' ') + @topline = %w-Sender Recipient Time Delta- + @start_from = mail.match(/^From.*\@([^\s>]*)/)[1] + @date = Time.parse(mail.match(/^Date:\s+(.*)/)[1]) + end + + def out(line) + "%-20.20s %-20.20s %-20.20s %s" % line + end + + def hop_date(day) + day.strftime("%I:%M:%S %Y/%m/%d") + end + + def puts_hops + puts out(@topline) + puts out(['Start', @start_from, hop_date(@date),'']) + @head.split(/\n/).reverse.grep(/^Received:/).each do |hop| + hop.gsub!(/\bon (.*?) (id.*)/,'; \1') + whence = hop.match(/;\s+(.*)$/)[1] + unless whence + warn "Bad received line: #{hop}" + next + end + from = $+ if hop =~ /from\s+(\S+)|\((.*?)\)/ + by = $1 if hop =~ /by\s+(\S+\.\S+)/ + next unless now = Time.parse(whence).localtime + delta = now - @date + puts out([from, by, hop_date(now), hop_time(delta)]) + @date = now + end + end + + def hop_time(secs) + sign = secs < 0 ? -1 : 1 + days, secs = secs.abs.divmod(60 * 60 * 24) + hours,secs = secs.abs.divmod(60 * 60) + mins, secs = secs.abs.divmod(60) + rtn = "%3ds" % [secs * sign] + rtn << "%3dm" % [mins * sign] if mins != 0 + rtn << "%3dh" % [hours * sign] if hours != 0 + rtn << "%3dd" % [days * sign] if days != 0 + rtn + end +end + +$/ = "" +mail = MailHopDelta.new(ARGF.gets).puts_hops + + +# @@PLEAC@@_4.0 +single_level = [ "this", "that", "the", "other" ] + +# Ruby directly supports nested arrays +double_level = [ "this", "that", [ "the", "other" ] ] +still_single_level = [ "this", "that", [ "the", "other" ] ].flatten + + +# @@PLEAC@@_4.1 +a = [ "quick", "brown", "fox" ] +a = %w(Why are you teasing me?) + +lines = <<"END_OF_HERE_DOC".gsub(/^\s*(.+)/, '\1') + The boy stood on the burning deck, + It was as hot as glass. +END_OF_HERE_DOC + +bigarray = IO.readlines("mydatafile").collect { |l| l.chomp } + +name = "Gandalf" +banner = %Q(Speak, #{name}, and welcome!) + +host_info = `host #{his_host}` + +%x(ps #{$$}) + +banner = 'Costs only $4.95'.split(' ') + +rax = %w! ( ) < > { } [ ] ! + + +# @@PLEAC@@_4.2 +def commify_series(arr) + return '' if not arr + case arr.size + when 0 then '' + when 1 then arr[0] + when 2 then arr.join(' and ') + else arr[0..-2].join(', ') + ', and ' + arr[-1] + end +end + +array = [ "red", "yellow", "green" ] + +print "I have ", array, " marbles\n" +# -> I have redyellowgreen marbles + +# But unlike Perl: +print "I have #{array} marbles\n" +# -> I have redyellowgreen marbles +# So, needs: +print "I have #{array.join(' ')} marbles\n" +# -> I have red yellow green marbles + +#!/usr/bin/ruby +# communify_series - show proper comma insertion in list output + +def commify_series(arr) + return '' if not arr + sepchar = arr.find { |p| p =~ /,/ } ? '; ' : ', ' + case arr.size + when 0 then '' + when 1 then arr[0] + when 2 then arr.join(' and ') + else arr[0..-2].join(sepchar) + sepchar + 'and ' + arr[-1] + end +end + +lists = [ + [ 'just one thing' ], + %w(Mutt Jeff), + %w(Peter Paul Mary), + [ 'To our parents', 'Mother Theresa', 'God' ], + [ 'pastrami', 'ham and cheese', 'peanut butter and jelly', 'tuna' ], + [ 'recycle tired, old phrases', 'ponder big, happy thoughts' ], + [ 'recycle tired, old phrases', + 'ponder big, happy thoughts', + 'sleep and dream peacefully' ], +] + +for list in lists do + puts "The list is: #{commify_series(list)}." +end + + +# @@PLEAC@@_4.3 +# (note: AFAIK Ruby doesn't allow gory change of Array length) +# grow the array by assigning nil to past the end of array +ary[new_size-1] = nil +# shrink the array by slicing it down +ary.slice!(new_size..-1) +# init the array with given size +Array.new(number_of_elems) +# assign to an element past the original end enlarges the array +ary[index_new_last_elem] = value + +def what_about_that_array(a) + print "The array now has ", a.size, " elements.\n" + # Index of last element is not really interesting in Ruby + print "Element #3 is `#{a[3]}'.\n" +end +people = %w(Crosby Stills Nash Young) +what_about_that_array(people) + + +# @@PLEAC@@_4.4 +# OO style +bad_users.each { |user| + complain(user) +} +# or, functional style +for user in bad_users + complain(user) +end + +for var in ENV.keys.sort + puts "#{var}=#{ENV[var]}" +end + +for user in all_users + disk_space = get_usage(user) + if (disk_space > MAX_QUOTA) + complain(user) + end +end + +for l in IO.popen("who").readlines + print l if l =~ /^gc/ +end + +# we can mimic the obfuscated Perl way +while fh.gets # $_ is set to the line just read + chomp # $_ has a trailing \n removed, if it had one + split.each { |w| # $_ is split on whitespace + # but $_ is not set to each chunk as in Perl + print w.reverse + } +end +# ...or use a cleaner way +for l in fh.readlines + l.chomp.split.each { |w| print w.reverse } +end + +# same drawback as in problem 1.4, we can't mutate a Numeric... +array.collect! { |v| v - 1 } + +a = [ .5, 3 ]; b = [ 0, 1 ] +for ary in [ a, b ] + ary.collect! { |v| v * 7 } +end +puts "#{a.join(' ')} #{b.join(' ')}" + +# we can mutate Strings, cool; we need a trick for the scalar +for ary in [ [ scalar ], array, hash.values ] + ary.each { |v| v.strip! } # String#strip rules :) +end + + +# @@PLEAC@@_4.5 +# not relevant in Ruby since we have always references +for item in array + # do somethingh with item +end + + +# @@PLEAC@@_4.6 +unique = list.uniq + +# generate a list of users logged in, removing duplicates +users = `who`.collect { |l| l =~ /(\w+)/; $1 }.sort.uniq +puts("users logged in: #{commify_series(users)}") # see 4.2 for commify_series + + +# @@PLEAC@@_4.7 +a - b +# [ 1, 1, 2, 2, 3, 3, 3, 4, 5 ] - [ 1, 2, 4 ] -> [3, 5] + + +# @@PLEAC@@_4.8 +union = a | b +intersection = a & b +difference = a - b + + +# @@PLEAC@@_4.9 +array1.concat(array2) +# if you will assign to another object, better use: +new_ary = array1 + array2 + +members = [ "Time", "Flies" ] +initiates = [ "An", "Arrow" ] +members += initiates + +members = [ "Time", "Flies" ] +initiates = [ "An", "Arrow" ] +members[2,0] = [ "Like", initiates ].flatten + +members[0] = "Fruit" +members[3,2] = "A", "Banana" + + +# @@PLEAC@@_4.10 +reversed = ary.reverse + +ary.reverse_each { |e| + # do something with e +} + +descending = ary.sort.reverse +descending = ary.sort { |a,b| b <=> a } + + +# @@PLEAC@@_4.11 +# remove n elements from front of ary (shift n) +front = ary.slice!(0, n) + +# remove n elements from the end of ary (pop n) +end_ = ary.slice!(-n .. -1) + +# let's extend the Array class, to make that useful +class Array + def shift2() + slice!(0 .. 1) # more symetric with pop2... + end + def pop2() + slice!(-2 .. -1) + end +end + +friends = %w(Peter Paul Mary Jim Tim) +this, that = friends.shift2 + +beverages = %w(Dew Jolt Cola Sprite Fresca) +pair = beverages.pop2 + + +# @@PLEAC@@_4.12 +# use Enumerable#detect (or the synonym Enumerable#find) +highest_eng = employees.detect { |emp| emp.category == 'engineer' } + + +# @@PLEAC@@_4.13 +# use Enumerable#select (or the synonym Enumerable#find_all) +bigs = nums.select { |i| i > 1_000_000 } +pigs = users.keys.select { |k| users[k] > 1e7 } + +matching = `who`.select { |u| u =~ /^gnat / } + +engineers = employees.select { |e| e.position == 'Engineer' } + +secondary_assistance = applicants.select { |a| + a.income >= 26_000 && a.income < 30_000 +} + + +# @@PLEAC@@_4.14 +# normally you would have an array of Numeric (Float or +# Fixnum or Bignum), so you would use: +sorted = unsorted.sort +# if you have strings representing Integers or Floats +# you may specify another sort method: +sorted = unsorted.sort { |a,b| a.to_f <=> b.to_f } + +# let's use the list of my own PID's +`ps ux`.split("\n")[1..-1]. + select { |i| i =~ /^#{ENV['USER']}/ }. + collect { |i| i.split[1] }. + sort { |a,b| a.to_i <=> b.to_i }.each { |i| puts i } +puts "Select a process ID to kill:" +pid = gets.chomp +raise "Exiting ... \n" unless pid && pid =~ /^\d+$/ +Process.kill('TERM', pid.to_i) +sleep 2 +Process.kill('KILL', pid.to_i) + +descending = unsorted.sort { |a,b| b.to_f <=> a.to_f } + + +# @@PLEAC@@_4.15 +ordered = unordered.sort { |a,b| compare(a,b) } + +precomputed = unordered.collect { |e| [compute, e] } +ordered_precomputed = precomputed.sort { |a,b| a[0] <=> b[0] } +ordered = ordered_precomputed.collect { |e| e[1] } + +ordered = unordered.collect { |e| [compute, e] }. + sort { |a,b| a[0] <=> b[0] }. + collect { |e| e[1] } + +for employee in employees.sort { |a,b| a.name <=> b.name } + print employee.name, " earns \$ ", employee.salary, "\n" +end + +# Beware! `0' is true in Ruby. +# For chaining comparisons, you may use Numeric#nonzero?, which +# returns num if num is not zero, nil otherwise +sorted = employees.sort { |a,b| (a.name <=> b.name).nonzero? || b.age <=> a.age } + +users = [] +# getpwent is not wrapped in Ruby... let's fallback +IO.readlines('/etc/passwd').each { |u| users << u.split(':') } +users.sort! { |a,b| a[0] <=> b[0] } +for user in users + puts user[0] +end + +sorted = names.sort { |a,b| a[1, 1] <=> b[1, 1] } +sorted = strings.sort { |a,b| a.length <=> b.length } + +# let's show only the compact version +ordered = strings.collect { |e| [e.length, e] }. + sort { |a,b| a[0] <=> b[0] }. + collect { |e| e[1] } + +ordered = strings.collect { |e| [/\d+/.match(e)[0].to_i, e] }. + sort { |a,b| a[0] <=> b[0] }. + collect { |e| e[1] } + +print `cat /etc/passwd`.collect { |e| [e, e.split(':').indexes(3,2,0)].flatten }. + sort { |a,b| (a[1] <=> b[1]).nonzero? || (a[2] <=> b[2]).nonzero? || a[3] <=> b[3] }. + collect { |e| e[0] } + + +# @@PLEAC@@_4.16 +circular.unshift(circular.pop) # the last shall be first +circular.push(circular.shift) # and vice versa + +def grab_and_rotate(l) + l.push(ret = l.shift) + ret +end + +processes = [1, 2, 3, 4, 5] +while (1) + process = grab_and_rotate(processes) + puts "Handling process #{process}" + sleep 1 +end + + +# @@PLEAC@@_4.17 +def fisher_yates_shuffle(a) + (a.size-1).downto(1) { |i| + j = rand(i+1) + a[i], a[j] = a[j], a[i] if i != j + } +end + +def naive_shuffle(a) + for i in 0...a.size + j = rand(a.size) + a[i], a[j] = a[j], a[i] + end +end + + Added: external/Pygments-0.8.1/tests/examplefiles/simple.md ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/simple.md Thu Aug 9 17:43:13 2007 @@ -0,0 +1,747 @@ +module simple; + +// Importing stuff. +{ + function loadMod(name, ns) + { + assert(name == "mod"); + + ns.x = "I'm x"; + + ns.foo = function foo() + { + writefln("foo"); + }; + + ns.bar = function bar(x) + { + return x[0]; + }; + + ns.baz = function baz() + { + writefln(x); + }; + + foreach(k, v; ns) + if(isFunction(v)) + v.environment(ns); + } + + setModuleLoader("mod", loadMod); + + import mod : foo, bar; + foo(); + writefln(bar([5])); + mod.baz(); + + writefln(); +} + +// Super calls. +{ + class Base + { + function fork() + { + writefln("Base fork."); + } + } + + class Derived : Base + { + function fork() + { + writefln("Derived fork!"); + super.fork(); + } + } + + local d = Derived(); + d.fork(); + + writefln(); +} + +// Coroutines and coroutine iteration. +{ + local countDown = coroutine function countDown(x) + { + yield(); + + while(x > 0) + { + yield(x); + x--; + } + }; + + foreach(v; countDown, 5) + writefln(v); + + writefln(); + + local forEach = coroutine function forEach(t) + { + yield(); + + foreach(k, v; t) + yield(k, v); + }; + + foreach(_, k, v; forEach, {hi = 1, bye = 2}) + writefln("key: ", k, ", value: ", v); + + writefln(); +} + +// Testing tailcalls. +{ + function recurse(x) + { + writefln("recurse: ", x); + + if(x == 0) + return toString(x); + else + return recurse(x - 1); + } + + writefln(recurse(5)); + writefln(); + + class A + { + function f(x) + { + writefln("A.f: ", x); + + if(x == 0) + return toString(x); + else + return this.f(x - 1); // call it as this.f to force a 'method' instruction to be generated + } + } + + local a = A(); + writefln(a.f(5)); + writefln(); +} + +{ + // A function which lets us define properties for a class. + // The varargs should be a bunch of tables, each with a 'name' field, and 'getter' and/or 'setter' fields. + function mixinProperties(classType, vararg) + { + classType.mProps = { }; + + classType.opIndex = function opIndex(key) + { + local prop = mProps[key]; + + if(prop is null) + throw format(classType, ".opIndex() - Property '%s' does not exist", key); + + local getter = prop.getter; + + if(getter is null) + throw format(classType, ".opIndex() - Property '%s' has no getter", key); + + return getter(with this); + }; + + classType.opIndexAssign = function opIndexAssign(key, value) + { + local prop = mProps[key]; + + if(prop is null) + throw format(classType, ".opIndexAssign() - Property '%s' does not exist", key); + + local setter = prop.setter; + + if(setter is null) + throw format(classType, ".opIndexAssign() - Property '%s' has no setter", key); + + setter(with this, value); + }; + + foreach(i, prop; [vararg]) + { + if(!isTable(prop)) + throw format("mixinProperties() - property ", i, " is not a table"); + + if(prop.name is null) + throw format("mixinProperties() - property ", i, " has no name"); + + if(prop.setter is null && prop.getter is null) + throw format("mixinProperties() - property '%s' has no getter or setter", prop.name); + + classType.mProps[prop.name] = prop; + } + } + + // Create a class to test out. + class PropTest + { + mX = 0; + mY = 0; + mName = ""; + + function constructor(name) + { + mName = name; + } + + function toString() + { + return format("name = '", mName, "' x = ", mX, " y = ", mY); + } + } + + // Mix in the properties. + mixinProperties + ( + PropTest, + + { + name = "x", + + function setter(value) + { + mX = value; + } + + function getter() + { + return mX; + } + }, + + { + name = "y", + + function setter(value) + { + mY = value; + } + + function getter() + { + return mY; + } + }, + + { + name = "name", + + function getter() + { + return mName; + } + } + ); + + // Create an instance and try it out. + local p = PropTest("hello"); + + writefln(p); + p.x = 46; + p.y = 123; + p.x = p.x + p.y; + writefln(p); + + // Try to access a nonexistent property. + try + p.name = "crap"; + catch(e) + { + writefln("caught: ", e); + writefln(getTraceback()); + } + + writefln(); +} + +// Some container classes. +{ + class PQ + { + mData; + mLength = 0; + + function constructor() + { + mData = array.new(15); + } + + function insert(data) + { + resizeArray(); + mData[mLength] = data; + + local index = mLength; + local parentIndex = (index - 1) / 2; + + while(index > 0 && mData[parentIndex] > mData[index]) + { + local temp = mData[parentIndex]; + mData[parentIndex] = mData[index]; + mData[index] = temp; + + index = parentIndex; + parentIndex = (index - 1) / 2; + } + + mLength += 1; + } + + function remove() + { + if(mLength == 0) + throw "PQ.remove() - No items to remove"; + + local data = mData[0]; + mLength -= 1; + mData[0] = mData[mLength]; + + local index = 0; + local left = 1; + local right = 2; + + while(index < mLength) + { + local smaller; + + if(left >= mLength) + { + if(right >= mLength) + break; + else + smaller = right; + } + else + { + if(right >= mLength) + smaller = left; + else + { + if(mData[left] < mData[right]) + smaller = left; + else + smaller = right; + } + } + + if(mData[index] > mData[smaller]) + { + local temp = mData[index]; + mData[index] = mData[smaller]; + mData[smaller] = temp; + + index = smaller; + left = (index * 2) + 1; + right = left + 1; + } + else + break; + } + + return data; + } + + function resizeArray() + { + if(mLength >= #mData) + mData.length((#mData + 1) * 2 - 1); + } + + function hasData() + { + return mLength != 0; + } + } + + class Stack + { + mHead = null; + + function push(data) + { + local t = { data = data, next = mHead }; + mHead = t; + } + + function pop() + { + if(mHead is null) + throw "Stack.pop() - No items to pop"; + + local item = mHead; + mHead = mHead.next; + + return item.data; + } + + function hasData() + { + return mHead !is null; + } + } + + class Queue + { + mHead = null; + mTail = null; + + function push(data) + { + local t = { data = data, next = null }; + + if(mTail is null) + { + mHead = t; + mTail = t; + } + else + { + mTail.next = t; + mTail = t; + } + } + + function pop() + { + if(mTail is null) + throw "Queue.pop() - No items to pop"; + + local item = mHead; + mHead = mHead.next; + + if(mHead is null) + mTail = null; + + return item.data; + } + + function hasData() + { + return mHead !is null; + } + } + + writefln("Priority queue (heap)"); + + local prioQ = PQ(); + + for(i : 0 .. 10) + prioQ.insert(math.rand(0, 20)); + + while(prioQ.hasData()) + writefln(prioQ.remove()); + + writefln(); + writefln("Stack"); + + local stack = Stack(); + + for(i : 0 .. 5) + stack.push(i + 1); + + while(stack.hasData()) + writefln(stack.pop()); + + writefln(); + writefln("Queue"); + + local queue = Queue(); + + for(i : 0 .. 5) + queue.push(i + 1); + + while(queue.hasData()) + writefln(queue.pop()); + + writefln(); +} + +// opApply tests. +{ + class Test + { + mData = [4, 5, 6]; + + function opApply(extra) + { + if(isString(extra) && extra == "reverse") + { + local function iterator_reverse(index) + { + index--; + + if(index < 0) + return; + + return index, mData[index]; + } + + return iterator_reverse, this, #mData; + } + else + { + local function iterator(index) + { + index++; + + if(index >= #mData) + return; + + return index, mData[index]; + } + + return iterator, this, -1; + } + } + } + + local test = Test(); + + foreach(k, v; test) + writefln("test[", k, "] = ", v); + + writefln(); + + foreach(k, v; test, "reverse") + writefln("test[", k, "] = ", v); + + writefln(); + + test = + { + fork = 5, + knife = 10, + spoon = "hi" + }; + + foreach(k, v; test) + writefln("test[", k, "] = ", v); + + test = [5, 10, "hi"]; + + writefln(); + + foreach(k, v; test) + writefln("test[", k, "] = ", v); + + writefln(); + + foreach(k, v; test, "reverse") + writefln("test[", k, "] = ", v); + + writefln(); + + foreach(k, v; "hello") + writefln("str[", k, "] = ", v); + + writefln(); + + foreach(k, v; "hello", "reverse") + writefln("str[", k, "] = ", v); + + writefln(); +} + +// Testing upvalues in for loops. +{ + local arr = array.new(10); + + for(i : 0 .. 10) + arr[i] = function() { return i; }; + + writefln("This should be the values 0 through 9:"); + + foreach(func; arr) + writefln(func()); + + writefln(); +} + +// Testing nested functions. +{ + function outer() + { + local x = 3; + + function inner() + { + x++; + writefln("inner x: ", x); + } + + writefln("outer x: ", x); + inner(); + writefln("outer x: ", x); + + return inner; + } + + local func = outer(); + func(); + + writefln(); +} + +// Testing Exceptions. +{ + function thrower(x) + { + if(x >= 3) + throw "Sorry, x is too big for me!"; + } + + function tryCatch(iterations) + { + try + { + for(i : 0 .. iterations) + { + writefln("tryCatch: ", i); + thrower(i); + } + } + catch(e) + { + writefln("tryCatch caught: ", e); + throw e; + } + finally + writefln("tryCatch finally"); + } + + try + { + tryCatch(2); + tryCatch(5); + } + catch(e) + writefln("caught: ", e); + + writefln(); +} + +// Testing arrays. +{ + local array = [7, 9, 2, 3, 6]; + + array.sort(); + + foreach(i, v; array) + writefln("arr[", i, "] = ", v); + + array ~= ["foo", "far"]; + + writefln(); + + foreach(i, v; array) + writefln("arr[", i, "] = ", v); + + writefln(); +} + +// Testing vararg functions. +{ + function vargs(vararg) + { + local args = [vararg]; + + writefln("num varargs: ", #args); + + foreach(i, v; args) + writefln("args[", i, "] = ", v); + } + + vargs(); + + writefln(); + + vargs(2, 3, 5, "foo", "bar"); + + writefln(); +} + +// Testing switches. +{ + foreach(v; ["hi", "bye", "foo"]) + { + switch(v) + { + case "hi": + writefln("switched to hi"); + break; + + case "bye": + writefln("switched to bye"); + break; + + default: + writefln("switched to something else"); + break; + } + } + + writefln(); + + foreach(v; [null, false, 1, 2.3, 'x', "hi"]) + { + switch(v) + { + case null: writefln("null"); break; + case false: writefln("false"); break; + case 1: writefln("1"); break; + case 2.3: writefln("2.3"); break; + case 'x': writefln("x"); break; + case "hi": writefln("hi"); break; + } + } + + writefln(); + + class A + { + mValue; + + this(value) + { + mValue = value; + } + + function opCmp(other) + { + assert(other as A); + return mValue <=> other.mValue; + } + } + + local a1 = A(1); + local a2 = A(2); + local a3 = A(3); + + for(s : 1 .. 4) + { + local ss = A(s); + + switch(ss) + { + case a1: + writefln(1); + break; + + case a2: + writefln(2); + break; + + case a3: + writefln(3); + break; + } + } +} \ No newline at end of file Added: external/Pygments-0.8.1/tests/examplefiles/smarty_example.html ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/smarty_example.html Thu Aug 9 17:43:13 2007 @@ -0,0 +1,209 @@ +{php} + include "some/php/file.php"; + + foreach ($rows as $row) { + echo $row; + } +{/php} + +{* smarty comment *} + + {serendipity_hookPlugin hook="entries_header" addData="$entry_id"} + + {foreach from=$entries item="dategroup"} +
    + {if $dategroup.is_sticky} +

    {$CONST.STICKY_POSTINGS}

    + {else} +

    {$dategroup.date|@formatTime:DATE_FORMAT_BARSINISTER}

    + {/if} + + {foreach from=$dategroup.entries item="entry"} +

    {$entry.title}

    + +
    + {if $entry.categories} + + {foreach from=$entry.categories item="category"} + {if $category.category_icon} + {$category.category_name|@escape} + {/if} + {/foreach} + + {/if} + +
    + {$entry.body} +
    + + {if $entry.is_extended} +
    {$entry.extended}
    + {/if} + + {if $entry.has_extended and not $is_single_entry and not $entry.is_extended}
    +

    {$CONST.VIEW_EXTENDED_ENTRY|@sprintf:$entry.title}


    + {/if} + +
    + {$CONST.POSTED_BY} {$entry.author} + {if $entry.categories} + {$CONST.IN} {foreach from=$entry.categories item="category" name="categories"}{$category.category_name|@escape}{if not $smarty.foreach.categories.last}, {/if}{/foreach} + {/if} + + {if $entry.has_comments} + {if $use_popups} + | {$entry.label_comments} ({$entry.comments}) + {else} + | {$entry.label_comments} ({$entry.comments}) + {/if} + {/if} + + {if $entry.has_trackbacks} + {if $use_popups} + | {$entry.label_trackbacks} ({$entry.trackbacks}) + {else} + | {$entry.label_trackbacks} ({$entry.trackbacks}) + {/if} + {/if} + + {if $entry.is_entry_owner and not $is_preview} + | {$CONST.EDIT_ENTRY} + {/if} + + {$entry.add_footer} +
    +
    + + {$entry.plugin_display_dat} + + {if $is_single_entry and not $use_popups and not $is_preview} + {if $CONST.DATA_UNSUBSCRIBED} +
    {$CONST.DATA_UNSUBSCRIBED|@sprintf:$CONST.UNSUBSCRIBE_OK}

    + {/if} + + {if $CONST.DATA_TRACKBACK_DELETED} +
    {$CONST.DATA_TRACKBACK_DELETED|@sprintf:$CONST.TRACKBACK_DELETED}

    + {/if} + + {if $CONST.DATA_TRACKBACK_APPROVED} +
    {$CONST.DATA_TRACKBACK_APPROVED|@sprintf:$CONST.TRACKBACK_APPROVED}

    + {/if} + + {if $CONST.DATA_COMMENT_DELETED} +
    {$CONST.DATA_COMMENT_DELETED|@sprintf:$CONST.COMMENT_DELETED}

    + {/if} + + {if $CONST.DATA_COMMENT_APPROVED} +
    {$CONST.DATA_COMMENT_APPROVED|@sprintf:$CONST.COMMENT_APPROVED}

    + {/if} + + {/if} + + {if $is_single_entry and not $is_preview} +
    +
    + +
    {$CONST.TRACKBACKS}
    +
    + {$CONST.TRACKBACK_SPECIFIC} +
    +
    + {serendipity_printTrackbacks entry=$entry.id} +
    +
    +
    + +
    {$CONST.COMMENTS}
    +
    {$CONST.DISPLAY_COMMENTS_AS} + {if $entry.viewmode eq $CONST.VIEWMODE_LINEAR} + ({$CONST.COMMENTS_VIEWMODE_LINEAR} | {$CONST.COMMENTS_VIEWMODE_THREADED}) + {else} + ({$CONST.COMMENTS_VIEWMODE_LINEAR} | {$CONST.COMMENTS_VIEWMODE_THREADED}) + {/if} +
    +
    + {serendipity_printComments entry=$entry.id mode=$entry.viewmode} + + {if $entry.is_entry_owner} + {if $entry.allow_comments} +
    ({$CONST.COMMENTS_DISABLE})
    + {else} +
    ({$CONST.COMMENTS_ENABLE})
    + {/if} + {/if} + + + {foreach from=$comments_messagestack item="message"} +
    {$message}
    + {/foreach} + + {if $is_comment_added} + +
    +
    {$CONST.COMMENT_ADDED}
    + + {elseif $is_comment_moderate} + +
    +
    {$CONST.COMMENT_ADDED}
    {$CONST.THIS_COMMENT_NEEDS_REVIEW}
    + + {elseif not $entry.allow_comments} + +
    +
    {$CONST.COMMENTS_CLOSED}
    + + {else} + +
    +
    {$CONST.ADD_COMMENT}
    + {$COMMENTFORM} + + {/if} +
    + {/if} + + {$entry.backend_preview} + {/foreach} +
    + {foreachelse} + {if not $plugin_clean_page} + {$CONST.NO_ENTRIES_TO_PRINT} + {/if} + {/foreach} + +{if $footer_info} +
    + {if $footer_info} + {if $footer_prev_page} + « {$CONST.PREVIOUS_PAGE} + {else} +   + {/if} + {else} + {/if} + + {if $footer_info} + ({$footer_info}) + {/if} + + {if $footer_info} + {if $footer_next_page} + {$CONST.NEXT_PAGE} » + {else} +   + {/if} + {else} + {/if} +
    {/if} + {serendipity_hookPlugin hook="entries_footer"} + Added: external/Pygments-0.8.1/tests/examplefiles/sources.list ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/sources.list Thu Aug 9 17:43:13 2007 @@ -0,0 +1,62 @@ +## CD ROM +deb cdrom:[Xubuntu 6.06.1 _Dapper Drake_ - Release i386 (20060807)]/ dapper main restricted + +deb http://archive.ubuntu.com/ubuntu/ dapper main restricted +deb-src http://archive.ubuntu.com/ubuntu/ dapper main restricted + +deb http://foo.com/$(ARCH)/ main foo + +## Major bug fix updates produced after the final release of the +## distribution. +deb http://archive.ubuntu.com/ubuntu/ dapper-updates main restricted +deb-src http://archive.ubuntu.com/ubuntu/ dapper-updates main restricted + +## Uncomment the following two lines to add software from the 'universe' +## repository. +## N.B. software from this repository is ENTIRELY UNSUPPORTED by the Ubuntu +## team, and may not be under a free licence. Please satisfy yourself as to +## your rights to use the software. Also, please note that software in +## universe WILL NOT receive any review or updates from the Ubuntu security +## team. +deb http://archive.ubuntu.com/ubuntu/ dapper universe multiverse +deb-src http://archive.ubuntu.com/ubuntu/ dapper universe multiverse + +## Uncomment the following two lines to add software from the 'backports' +## repository. +## N.B. software from this repository may not have been tested as +## extensively as that contained in the main release, although it includes +## newer versions of some applications which may provide useful features. +## Also, please note that software in backports WILL NOT receive any review +## or updates from the Ubuntu security team. +deb http://archive.ubuntu.com/ubuntu/ dapper-backports main restricted universe multiverse +deb-src http://archive.ubuntu.com/ubuntu/ dapper-backports main restricted universe multiverse + +deb http://security.ubuntu.com/ubuntu dapper-security main restricted +deb-src http://security.ubuntu.com/ubuntu dapper-security main restricted +deb http://security.ubuntu.com/ubuntu dapper-security universe multiverse +deb-src http://security.ubuntu.com/ubuntu dapper-security universe multiverse + +## dapper-commercial by canonical +## currently has realplay (realplayer 10) and opera (opera 9) +deb http://archive.canonical.com/ubuntu dapper-commercial main + +## Bleeding edge wine repository for Dapper +## only uncomment it if you need it +## deb http://wine.budgetdedicated.com/apt dapper main +## deb-src http://wine.budgetdedicated.com/apt dapper main + +## skype +## only uncomment it if you need it +## deb http://download.skype.com/linux/repos/debian/ stable non-free + +deb http://de.archive.ubuntu.com/ubuntu/ edgy main restricted multiverse universe + +deb http://de.archive.ubuntu.com/ubuntu/ edgy-updates main restricted multiverse universe + +deb http://de.archive.ubuntu.com/ubuntu/ edgy-backports main restricted universe multiverse + +deb http://security.ubuntu.com/ubuntu edgy-security main restricted universe multiverse + +deb http://wine.budgetdedicated.com/apt edgy main + +deb http://archive.czessi.net/ubuntu edgy main restricted universe multiverse i18n-de Added: external/Pygments-0.8.1/tests/examplefiles/test.bas ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/test.bas Thu Aug 9 17:43:13 2007 @@ -0,0 +1,29 @@ +Public Class Form1 + Inherits System.Windows.Forms.Form + + Private t As New System.Timers.Timer(2000) + + Private Sub Form1_Load(ByVal sender As Object, _ + ByVal e As System.EventArgs) Handles MyBase.Load + + AddHandler t.Elapsed, AddressOf TimerFired + End Sub + + Private Sub btnStart_Click(ByVal sender As System.Object, _ + ByVal e As System.EventArgs) Handles btnStart.Click + + t.Enabled = True + End Sub + + Private Sub btnStop_Click(ByVal sender As System.Object, _ + ByVal e As System.EventArgs) Handles btnStop.Click + + t.Enabled = False + End Sub + + Public Sub TimerFired(ByVal sender As Object, _ + ByVal e As System.Timers.ElapsedEventArgs) + + Label1.Text = "Signal Time = " & e.SignalTime.ToString + End Sub +End Class Added: external/Pygments-0.8.1/tests/examplefiles/test.boo ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/test.boo Thu Aug 9 17:43:13 2007 @@ -0,0 +1,39 @@ +import System +import Boo.Lang.Interpreter from Boo.Lang.Interpreter + +class ObjectInterpreter(AbstractInterpreter): + + _context as object + + [getter(Value)] + _value as object + + def constructor(context): + _context = context + self.RememberLastValue = true + + override def Lookup(name as string): + property = _context.GetType().GetProperty(name) + return property.PropertyType if property is not null + + override def GetValue(name as string): + return _context.GetType().GetProperty(name).GetValue( + _context, null) + + override def SetLastValue(value): + _value = value + + override def SetValue(name as string, value): + raise InvalidOperationException() + + override def Declare(name as string, type as Type): + raise InvalidOperationException() + +class Person: + [property(FirstName)] + _fname as string = "" + +p = Person(FirstName: "Homer") +i = ObjectInterpreter(p) +i.Eval('"Hello, ${FirstName.ToUpper()}!"') +print i.Value Added: external/Pygments-0.8.1/tests/examplefiles/test.cs ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/test.cs Thu Aug 9 17:43:13 2007 @@ -0,0 +1,351 @@ +//////////////////////////////////////////////////////////////////////////////// +// // +// MIT X11 license, Copyright (c) 2005-2006 by: // +// // +// Authors: // +// Michael Dominic K. // +// // +// Permission is hereby granted, free of charge, to any person obtaining a // +// copy of this software and associated documentation files (the "Software"), // +// to deal in the Software without restriction, including without limitation // +// the rights to use, copy, modify, merge, publish, distribute, sublicense, // +// and/or sell copies of the Software, and to permit persons to whom the // +// Software is furnished to do so, subject to the following conditions: // +// // +// The above copyright notice and this permission notice shall be included // +// in all copies or substantial portions of the Software. // +// // +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS // +// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF // +// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN // +// NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, // +// DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR // +// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE // +// USE OR OTHER DEALINGS IN THE SOFTWARE. // +// // +//////////////////////////////////////////////////////////////////////////////// + +namespace Diva.Core { + + using System; + using Widgets; + using System.Xml; + using Util; + using System.Collections.Generic; + using System.Collections; + using Basics; + + public class OpenerTask : Task, IBoilProvider { + + // Private structs //////////////////////////////////////////// + + struct ObjectInfo { + + public ObjectContainer Container; + public int[] Depends; + public string SystemType; + public int RefId; + + /* CONSTRUCTOR */ + public ObjectInfo (ObjectContainer container) + { + Container = container; + Depends = container.Depends.ToArray (); + SystemType = container.SystemType; + RefId = container.RefId; + } + + public override string ToString () + { + return String.Format ("Type: {0} Deps count: {1} Id: {2}", + SystemType, Depends.Length, RefId); + } + + public bool IsUnBoilable (IBoilProvider provider) + { + if (Depends.Length == 0) + return true; + + foreach (int id in Depends) + if (! (provider.Contains (id))) + return false; + + return true; + } + + } + + // Enums ////////////////////////////////////////////////////// + + enum OpenerTaskStep { Init, Header, ProjectInfoRead, ObjectListRead, + ObjectListParse, ObjectListUnBoil, FindRoots, + Finished }; + + // Fields ///////////////////////////////////////////////////// + + string fileName; // Filename we're reading + XmlDocument xmlDocument; // Our document + //XmlNode projectInfoNode; // node + IEnumerator objectsEnumerator; // Enumerator + List objectsList; // Objects list + ObjectListContainer objectListContainer; + OpenerTaskStep currentStep; // Our current step + + Dictionary idToObject; // Id -> object + Dictionary objectToId; // Object -> Id + + string projectName = String.Empty; + string projectDirectory = String.Empty; + TagList projectTagList; + StuffList projectStuffList; + TrackList projectTrackList; + ClipList projectClipList; + MediaItemList projectMediaItemList; + Commander projectCommander; + Gdv.Pipeline projectPipeline; + Gdv.ProjectFormat projectFormat; + + // Properties ///////////////////////////////////////////////// + + public string ProjectName { + get { return projectName; } + } + + public string ProjectDirectory { + get { return projectDirectory; } + } + + public TagList ProjectTagList { + get { return projectTagList; } + } + + public StuffList ProjectStuffList { + get { return projectStuffList; } + } + + public TrackList ProjectTrackList { + get { return projectTrackList; } + } + + public ClipList ProjectClipList { + get { return projectClipList; } + } + + public MediaItemList ProjectMediaItemList { + get { return projectMediaItemList; } + } + + public Commander ProjectCommander { + get { return projectCommander; } + } + + public Gdv.Pipeline ProjectPipeline { + get { return projectPipeline; } + } + + public Gdv.ProjectFormat ProjectFormat { + get { return projectFormat; } + } + + // Public methods ///////////////////////////////////////////// + + /* CONSTRUCTOR */ + public OpenerTask (string fileName) + { + this.fileName = fileName; + } + + public override void Reset () + { + objectToId = new Dictionary (); + idToObject = new Dictionary (); + + xmlDocument = null; + //projectInfoNode = null; + + currentStep = OpenerTaskStep.Init; + + base.Reset (); + } + + public int GetIdForObject (object o) + { + return objectToId [o]; + } + + public object GetObjectForId (int id) + { + return idToObject [id]; + } + + public bool Contains (int id) + { + return idToObject.ContainsKey (id); + } + + // Private methods //////////////////////////////////////////// + + protected override TaskStatus ExecuteStep (int s) + { + bool cont = true; + + // Main + switch (currentStep) { + + case OpenerTaskStep.Init: + objectsList = new List (); + xmlDocument = new XmlDocument (); + xmlDocument.Load (fileName); + currentStep = OpenerTaskStep.Header; + break; + + case OpenerTaskStep.Header: + //ReadHeader (); + currentStep = OpenerTaskStep.ProjectInfoRead; + break; + + case OpenerTaskStep.ProjectInfoRead: + foreach (XmlNode node in xmlDocument.DocumentElement.ChildNodes) + if (node.Name == "projectinfo") + ResolveProjectInfoNode (node); + + // FIXME: Fail if not found/not resolved + currentStep = OpenerTaskStep.ObjectListRead; + break; + + case OpenerTaskStep.ObjectListRead: + foreach (XmlNode node in xmlDocument.DocumentElement.ChildNodes) + if (node.Name == "objectlist") + objectListContainer = (ObjectListContainer) + DataFactory.MakeDataElement (node as XmlElement); + + if (objectListContainer == null) + throw new Exception ("ObjectListContainer not found!"); + + currentStep = OpenerTaskStep.ObjectListParse; + break; + + case OpenerTaskStep.ObjectListParse: + bool flush = EnumerateSomeObjects (); + if (flush) + currentStep = OpenerTaskStep.ObjectListUnBoil; + break; + + case OpenerTaskStep.ObjectListUnBoil: + bool done = UnBoilSomeObjects (); + if (done) + currentStep = OpenerTaskStep.FindRoots; + break; + + + case OpenerTaskStep.FindRoots: + projectTrackList = (TrackList) FindRoot ("tracklist"); + projectTagList = (TagList) FindRoot ("taglist"); + projectStuffList = (StuffList) FindRoot ("stufflist"); + projectClipList = (ClipList) FindRoot ("cliplist"); + projectMediaItemList = (MediaItemList) FindRoot ("mediaitemlist"); + projectPipeline = (Gdv.Pipeline) FindRoot ("pipeline"); + projectCommander = (Commander) FindRoot ("commander"); + projectFormat = (Gdv.ProjectFormat) FindRoot ("projectformat"); + + currentStep = OpenerTaskStep.Finished; + break; + + case OpenerTaskStep.Finished: + cont = false; + break; + + default: + break; + } + + // Post + if (cont) + return TaskStatus.Running; + else + return TaskStatus.Done; + } + + /* + void ReadHeader () + { + // FIXME: Read all the attributes from the element + }*/ + + void ResolveProjectInfoNode (XmlNode node) + { + foreach (XmlNode childNode in node) { + + switch (childNode.Name) { + + case "name": + projectName = childNode.FirstChild.Value; + break; + + case "directory": + projectDirectory = childNode.FirstChild.Value; + break; + + // FIXME: Duration etc. + } + } + } + + bool EnumerateSomeObjects () + { + if (objectsEnumerator == null) + objectsEnumerator = objectListContainer.FindAllObjects ().GetEnumerator (); + + for (int i = 0; i < 10; i++) { + if (objectsEnumerator.MoveNext () == false) + return true; + + ObjectContainer container = (ObjectContainer) + objectsEnumerator.Current; + + ObjectInfo newInfo = new ObjectInfo (container); + objectsList.Add (newInfo); + } + + return false; + } + + ObjectInfo GetNextCandidate () + { + foreach (ObjectInfo objInfo in objectsList) + if (objInfo.IsUnBoilable (this)) + return objInfo; + + throw new Exception ("FIXME: No more unboilable objects found. Recursive?"); + } + + bool UnBoilSomeObjects () + { + for (int i = 0; i < 5; i++) { + // All unboiled + if (objectsList.Count == 0) + return true; + + ObjectInfo objInfo = GetNextCandidate (); + + object o = BoilFactory.UnBoil (objInfo.Container, this); + objectsList.Remove (objInfo); + + // Add + idToObject [objInfo.RefId] = o; + objectToId [o] = objInfo.RefId; + + } + + return false; + } + + object FindRoot (string rootString) + { + ObjectContainer container = objectListContainer.FindObjectContainer (rootString); + return idToObject [container.RefId]; + } + + } + +} Added: external/Pygments-0.8.1/tests/examplefiles/test.css ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/test.css Thu Aug 9 17:43:13 2007 @@ -0,0 +1,30 @@ +body { + font-size: 12pt; + background: #fff url(temp.png) top left no-repeat; +} + +* html body { + font-size: 14pt; +} + +#nav .new { + display: block; +} + +ul#nav li.new { + font-weight: bold; +} + +:link { + color: #f00; +} + +:link:hover { + color: #0f0; +} + + at media screen { + body { + background: #ccc; + } +} Added: external/Pygments-0.8.1/tests/examplefiles/test.d ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/test.d Thu Aug 9 17:43:13 2007 @@ -0,0 +1,135 @@ +// Created by Lionello Lunesu and placed in the public domain. +// This file has been modified from its original version. +// It has been formatted to fit your screen. +module phoneno; // optional +import std.stdio; // writefln +import std.ctype; // isdigit +import std.stream; // BufferedFile + +// Just for readability (imagine char[][][char[]]) +alias char[] string; +alias string[] stringarray; + +/// Strips non-digit characters from the string (COW) +string stripNonDigit( in string line ) +{ + string ret; + foreach(uint i, c; line) { + // Error: std.ctype.isdigit at C:\dmd\src\phobos\std\ctype.d(37) + // conflicts with std.stream.isdigit at C:\dmd\src\phobos\std\stream.d(2924) + if (!std.ctype.isdigit(c)) { + if (!ret) + ret = line[0..i]; + } + else if (ret) + ret ~= c; + } + return ret?ret:line; +} + +unittest { + assert( stripNonDigit("asdf") == "" ); + assert( stripNonDigit("\'13-=2 4kop") == "1324" ); +} + +/// Converts a word into a number, ignoring all non alpha characters +string wordToNum( in string word ) +{ +// translation table for the task at hand +const char[256] TRANSLATE = + " " // 0 + " 0123456789 " // 32 + " 57630499617851881234762239 " // 64 + " 57630499617851881234762239 " + " " + " " + " " + " "; + string ret; + foreach(c; cast(ubyte[])word) + if (TRANSLATE[c] != ' ') + ret ~= TRANSLATE[c]; + return ret; +} + +unittest { + // Test wordToNum using the table from the task description. + assert( "01112223334455666777888999" == + wordToNum("E | J N Q | R W X | D S Y | F T | A M | C I V | B K U | L O P | G H Z")); + assert( "01112223334455666777888999" == + wordToNum("e | j n q | r w x | d s y | f t | a m | c i v | b k u | l o p | g h z")); + assert( "0123456789" == + wordToNum("0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9")); +} + +void main( string[] args ) +{ + // This associative array maps a number to an array of words. + stringarray[string] num2words; + + foreach(string word; new BufferedFile("dictionary.txt" ) ) + num2words[ wordToNum(word) ] ~= word.dup; // must dup + + /// Finds all alternatives for the given number + /// (should have been stripped from non-digit characters) + stringarray _FindWords( string numbers, bool digitok ) + in { + assert(numbers.length > 0); + } + out(result) { + foreach (a; result) + assert( wordToNum(a) == numbers ); + } + body { + stringarray ret; + bool foundword = false; + for (uint t=1; t<=numbers.length; ++t) { + auto alternatives = numbers[0..t] in num2words; + if (!alternatives) + continue; + foundword = true; + if (numbers.length > t) { + // Combine all current alternatives with all alternatives + // of the rest (next piece can start with a digit) + foreach (a2; _FindWords( numbers[t..$], true ) ) + foreach(a1; *alternatives) + ret ~= a1 ~ " " ~ a2; + } + else + ret ~= *alternatives; // append these alternatives + } + // Try to keep 1 digit, only if we're allowed and no other + // alternatives were found + // Testing "ret.length" makes more sense than testing "foundword", + // but the other implementations seem to do just this. + if (digitok && !foundword) { //ret.length == 0 + if(numbers.length > 1) { + // Combine 1 digit with all altenatives from the rest + // (next piece can not start with a digit) + foreach (a; _FindWords( numbers[1..$], false ) ) + ret ~= numbers[0..1] ~ " " ~ a; + } + else + ret ~= numbers[0..1]; // just append this digit + } + return ret; + } + + /// (This function was inlined in the original program) + /// Finds all alternatives for the given phone number + /// Returns: array of strings + stringarray FindWords( string phone_number ) + { + if (!phone_number.length) + return null; + // Strip the non-digit characters from the phone number, and + // pass it to the recursive function (leading digit is allowed) + return _FindWords( stripNonDigit(phone_number), true ); + } + + // Read the phone numbers + foreach(string phone; new BufferedFile("input.txt" ) ) + foreach(alternative; FindWords( phone ) ) + writefln(phone, ": ", alternative ); +} + Added: external/Pygments-0.8.1/tests/examplefiles/test.html ============================================================================== --- (empty file) +++ external/Pygments-0.8.1/tests/examplefiles/test.html Thu Aug 9 17:43:13 2007 @@ -0,0 +1,351 @@ + + + + + + +
    # -*- coding: utf-8 -*-
+"""
+    pocoo.pkg.core.acl
+    ~~~~~~~~~~~~~~~~~~
+
+    Pocoo ACL System.
+
+    :copyright: 2006-2007 by Armin Ronacher.
+    :license: GNU GPL, see LICENSE for more details.
+"""
+
+from pocoo.db import meta
+
+from pocoo.pkg.core.forum import Site, Forum, Thread
+from pocoo.pkg.core.user import User, Group
+
+from pocoo.pkg.core.db import users, groups, group_members, privileges, \
+     forums, posts, acl_mapping, acl_subjects, acl_objects
+
+
+class AclManager(object):
+    """
+    Manager object to manage ALCs.
+    """
+    STRONG_NO = -1
+
+    WEAK_NO = 0
+    WEAK_YES = 1
+    STRONG_YES = 2
+
+    def __init__(self, ctx, subject):
+        self.ctx = ctx
+
+        self.subject = subject
+        if isinstance(subject, User):
+            self._type = 'user'
+
+        elif isinstance(subject, Group):
+            self._type = 'group'
+
+        else:
+            raise ValueError('neither user or group specified')
+
+    def allow(self, privilege, obj, force=False):
+        """Allows the subject privilege on obj."""
+
+        return self._set(privilege, obj, 1 + bool(force))
+
+    def default(self, privilege, obj):
+        """Sets the state for privilege on obj back to weak yes."""
+
+        return self._set(privilege, obj, 0)
+
+    def deny(self, privilege, obj, force=False):
+        """Denies the subject privilege on obj."""
+
+        return self._set(privilege, obj, -1 - bool(force))
+
+    def can_access(self, privilege, obj):
+        """Checks if the current subject with the required privilege
+        somehow. Either directly or when the subject is a user and
+        one of its groups can access it."""
+
+        #XXX: maybe this could be one big query instead of 4
+        #XXX: this currently does not work correctly, therefore return True
+        return True
+
+        if not isinstance(obj, (Forum, Thread, Site.__class__)):
+            raise TypeError('obj must be a forum, thread or site')
+        privilege = privilege.upper()
+        s = self._get_subject_join().alias('s').c
+
+        def do_check(obj, tendency):
+            db = self.ctx.engine
+
+            o = self._get_object_join(obj).alias('o').c
+
+            # self check
+            r = db.execute(meta.select([acl_mapping.c.state],
+                (acl_mapping.c.priv_id == privileges.c.priv_id) &
+
+                (acl_mapping.c.subject_id == s.subject_id) &
+                (acl_mapping.c.object_id == o.object_id) &
+
+                (privileges.c.name == privilege)
+            ))
+            row = r.fetchone()
+            if row is not None:
+                if row['state'] in (self.STRONG_NO, self.STRONG_YES):
+                    return row['state'] == self.STRONG_YES
+
+                tendency = row['state']
+
+            # if the controlled subject is a user check all groups
+            if isinstance(self.subject, User):
+                r = db.execute(meta.select([acl_mapping.c.state],
+                    (acl_mapping.c.object_id == o.object_id) &
+
+                    (acl_mapping.c.subject_id == groups.c.subject_id) &
+
+                    (groups.c.group_id == group_members.c.group_id) &
+
+                    (group_members.c.user_id == self.subject.user_id)
+                ))
+                while True:
+                    row = r.fetchone()
+                    if row is None:
+                        break
+
+                    state = row[0]
+                    if state in (self.STRONG_YES, self.STRONG_NO):
+                        return state == self.STRONG_YES
+
+                    if tendency is None:
+                        tendency = state
+                    elif tendency == self.WEAK_NO and state == self.WEAK_YES:
+                        tendency = self.WEAK_YES
+
+            # check related objects
+            if isinstance(obj, Thread):
+                return do_check(obj.forum, tendency)
+            elif isinstance(obj, Forum):
+                return do_check(Site, tendency)
+            else:
+                return tendency
+
+        return do_check(obj, None) in (self.WEAK_YES, self.STRONG_YES)
+
+    def _set(self, privilege, obj, state):
+        """Helper functions for settings privileges."""
+
+        privilege = privilege.upper()
+        if self.subject.subject_id is None:
+            self._bootstrap()
+        if obj.object_id is None:
+            self._bootstrap_object(obj)
+        # special state "0" which means delete
+
+        if not state:
+            p = meta.select([privileges.c.priv_id], privileges.c.name == privilege)
+            self.ctx.engine.execute(acl_mapping.delete(
+                (acl_mapping.c.priv_id == p.c.priv_id) &
+
+                (acl_mapping.c.subject_id == self.subject.subject_id) &
+
+                (acl_mapping.c.object_id == obj.object_id)
+            ))
+            return
+        # touch privilege and check existing mapping
+
+        priv_id = self._fetch_privilege(privilege)
+        r = self.ctx.engine.execute(meta.select([acl_mapping.c.state],
+            (acl_mapping.c.priv_id == priv_id) &
+
+            (acl_mapping.c.subject_id == self.subject.subject_id) &
+
+            (acl_mapping.c.object_id == obj.object_id)
+        ))
+        row = r.fetchone()
+        if row is not None:
+            # this rule exists already
+
+            if row['state'] == state:
+                return
+            # goddamn, same rule - different state, delete old first
+            self._set(privilege, obj, 0)
+        # insert new rule
+
+        self.ctx.engine.execute(acl_mapping.insert(),
+            priv_id = priv_id,
+            subject_id = self.subject.subject_id,
+            object_id = obj.object_id,
+            state = state
+
+        )
+
+    def _bootstrap(self):
+        """This method is automatically called when subject_id is
+        None and an subject_id is required."""
+        r = self.ctx.engine.execute(acl_subjects.insert(),
+            subject_type = self._type
+
+        )
+        self.subject.subject_id = r.last_inserted_ids()[0]
+        self.subject.save()
+
+    def _bootstrap_object(self, obj):
+        """Like _bootstrap but works for objects."""
+
+        objtype = self._get_object_type(obj)
+        r = self.ctx.engine.execute(acl_objects.insert(),
+            object_type = objtype
+
+        )
+        obj.object_id = r.last_inserted_ids()[0]
+        obj.save()
+
+    def _get_object_type(self, obj):
+        if isinstance(obj, Forum):
+            return 'forum'
+
+        elif isinstance(obj, Thread):
+            return 'thread'
+        elif obj is Site:
+            return 'site'
+
+        raise TypeError('obj isn\'t a forum or thread')
+
+    def _get_object_join(self, obj):
+        """Returns a subjoin for the object id."""
+
+        t = self._get_object_type(obj)
+        if t == 'forum':
+            return meta.select([forums.c.object_id],
+                forums.c.forum_id == obj.forum_id
+
+            )
+        elif t == 'thread':
+            return meta.select([posts.c.object_id],
+                posts.c.post_id == obj.post_id
+
+            )
+        else:
+            # XXX: it works ^^
+            # i really want something like meta.select('0 as group_id')
+            class Fake(object):
+                def alias(self, n):
+                    class _C(object):
+                        class c(object):
+                            object_id = 0
+
+                    return _C
+            return Fake()
+
+    def _get_subject_join(self):
+        """Returns a subjoin for the subject id."""
+
+        if self._type == 'user':
+            return meta.select([users.c.subject_id],
+                users.c.user_id == self.subject.user_id
+
+            )
+        return meta.select([groups.c.subject_id],
+            groups.c.group_id == self.subject.group_id
+
+        )
+
+    def _fetch_privilege(self, name):
+        """Returns the priv_id for the given privilege. If it
+        doesn\'t exist by now the system will create a new
+        privilege."""
+        r = self.ctx.engine.execute(meta.select([privileges.c.priv_id],
+            privileges.c.name == name
+
+        ))
+        row = r.fetchone()
+        if row is not None:
+            return row[0]
+        r = self.ctx.engine.execute(privileges.insert(),
+            name = name
+
+        )
+        return r.last_inserted_ids()[0]
+
+    def __repr__(self):
+        if self._type == 'user':
+            id_ = self.subject.user_id
+
+        else:
+            id_ = self.subject.group_id
+        if self.subject.subject_id is None:
+            return '<%s %s:%d inactive>' % (
+                self.__class__.__name__,
+                self._type,
+                id_
+
+            )
+        return '<%s %s:%d active as %d>' % (
+            self.__class__.__name__,
+            self._type,
+            id_,
+            self.subject.subject_id
+
+        )
+

Added: external/Pygments-0.8.1/tests/examplefiles/test.java
==============================================================================
--- (empty file)
+++ external/Pygments-0.8.1/tests/examplefiles/test.java	Thu Aug  9 17:43:13 2007
@@ -0,0 +1,653 @@
+/*
+ * Created on 13-Mar-2004
+ * Created by James Yeh
+ * Copyright (C) 2004, 2005, 2006 Aelitis, All Rights Reserved.
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+ * 
+ * AELITIS, SAS au capital de 46,603.30 euros
+ * 8 Allee Lenotre, La Grille Royale, 78600 Le Mesnil le Roi, France.
+ *
+ */
+
+package org.gudy.azureus2.platform.macosx;
+
+import org.gudy.azureus2.core3.logging.*;
+import org.gudy.azureus2.core3.util.AEMonitor;
+import org.gudy.azureus2.core3.util.Debug;
+import org.gudy.azureus2.core3.util.SystemProperties;
+import org.gudy.azureus2.platform.PlatformManager;
+import org.gudy.azureus2.platform.PlatformManagerCapabilities;
+import org.gudy.azureus2.platform.PlatformManagerListener;
+import org.gudy.azureus2.platform.macosx.access.jnilib.OSXAccess;
+
+import org.gudy.azureus2.plugins.platform.PlatformManagerException;
+
+import java.io.BufferedReader;
+import java.io.File;
+import java.io.IOException;
+import java.io.InputStreamReader;
+import java.text.MessageFormat;
+import java.util.HashSet;
+
+
+/**
+ * Performs platform-specific operations with Mac OS X
+ *
+ * @author James Yeh
+ * @version 1.0 Initial Version
+ * @see PlatformManager
+ */
+public class PlatformManagerImpl implements PlatformManager
+{
+    private static final LogIDs LOGID = LogIDs.CORE;
+
+    protected static PlatformManagerImpl singleton;
+    protected static AEMonitor class_mon = new AEMonitor("PlatformManager");
+
+    private static final String USERDATA_PATH = new File(System.getProperty("user.home") + "/Library/Application Support/").getPath();
+
+    //T: PlatformManagerCapabilities
+    private final HashSet capabilitySet = new HashSet();
+
+    /**
+     * Gets the platform manager singleton, which was already initialized
+     */
+    public static PlatformManagerImpl getSingleton()
+    {
+        return singleton;
+    }
+
+    /**
+     * Tries to enable cocoa-java access and instantiates the singleton
+     */
+    static
+    {
+        initializeSingleton();
+    }
+
+    /**
+     * Instantiates the singleton
+     */
+    private static void initializeSingleton()
+    {
+        try
+        {
+            class_mon.enter();
+            singleton = new PlatformManagerImpl();
+        }
+        catch (Throwable e)
+        {
+        	Logger.log(new LogEvent(LOGID, "Failed to initialize platform manager"
+					+ " for Mac OS X", e));
+        }
+        finally
+        {
+            class_mon.exit();
+        }
+    }
+
+    /**
+     * Creates a new PlatformManager and initializes its capabilities
+     */
+    public PlatformManagerImpl()
+    {
+        capabilitySet.add(PlatformManagerCapabilities.RecoverableFileDelete);
+        capabilitySet.add(PlatformManagerCapabilities.ShowFileInBrowser);
+        capabilitySet.add(PlatformManagerCapabilities.ShowPathInCommandLine);
+        capabilitySet.add(PlatformManagerCapabilities.CreateCommandLineProcess);
+        capabilitySet.add(PlatformManagerCapabilities.GetUserDataDirectory);
+        capabilitySet.add(PlatformManagerCapabilities.UseNativeScripting);
+        capabilitySet.add(PlatformManagerCapabilities.PlaySystemAlert);
+        
+        if (OSXAccess.isLoaded()) {
+	        capabilitySet.add(PlatformManagerCapabilities.GetVersion);
+        }
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public int getPlatformType()
+    {
+        return PT_MACOSX;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public String getVersion() throws PlatformManagerException
+    {
+    	if (!OSXAccess.isLoaded()) {
+        throw new PlatformManagerException("Unsupported capability called on platform manager");
+    	}
+    	
+    	return OSXAccess.getVersion();
+    }
+
+    /**
+     * {@inheritDoc}
+     * @see org.gudy.azureus2.core3.util.SystemProperties#getUserPath()
+     */
+    public String getUserDataDirectory() throws PlatformManagerException
+    {
+        return USERDATA_PATH;
+    }
+
+	public File
+	getLocation(
+		long	location_id )
+	
+		throws PlatformManagerException
+	{
+		if ( location_id == LOC_USER_DATA ){
+			
+			return( new File( USERDATA_PATH ));
+		}
+		
+		return( null );
+	}
+    /**
+     * Not implemented; returns True
+     */
+    public boolean isApplicationRegistered() throws PlatformManagerException
+    {
+        return true;
+    }
+
+    
+	public String
+	getApplicationCommandLine()
+		throws PlatformManagerException
+	{
+		try{	    
+			String	bundle_path = System.getProperty("user.dir") +SystemProperties.SEP+ SystemProperties.getApplicationName() + ".app";
+
+			File osx_app_bundle = new File( bundle_path ).getAbsoluteFile();
+			
+			if( !osx_app_bundle.exists() ) {
+				String msg = "OSX app bundle not found: [" +osx_app_bundle.toString()+ "]";
+				System.out.println( msg );
+				if (Logger.isEnabled())
+					Logger.log(new LogEvent(LOGID, msg));		
+				throw new PlatformManagerException( msg );
+			}
+			
+			return "open -a \"" +osx_app_bundle.toString()+ "\"";
+			//return osx_app_bundle.toString() +"/Contents/MacOS/JavaApplicationStub";
+			
+		}
+		catch( Throwable t ){	
+			t.printStackTrace();
+			return null;
+		}
+	}
+	
+	
+	public boolean
+	isAdditionalFileTypeRegistered(
+		String		name,				// e.g. "BitTorrent"
+		String		type )				// e.g. ".torrent"
+	
+		throws PlatformManagerException
+	{
+	    throw new PlatformManagerException("Unsupported capability called on platform manager");
+	}
+	
+	public void
+	unregisterAdditionalFileType(
+		String		name,				// e.g. "BitTorrent"
+		String		type )				// e.g. ".torrent"
+		
+		throws PlatformManagerException
+	{
+		throw new PlatformManagerException("Unsupported capability called on platform manager");
+	}
+	
+	public void
+	registerAdditionalFileType(
+		String		name,				// e.g. "BitTorrent"
+		String		description,		// e.g. "BitTorrent File"
+		String		type,				// e.g. ".torrent"
+		String		content_type )		// e.g. "application/x-bittorrent"
+	
+		throws PlatformManagerException
+	{
+	   throw new PlatformManagerException("Unsupported capability called on platform manager");
+	}
+	
+    /**
+     * Not implemented; does nothing
+     */
+    public void registerApplication() throws PlatformManagerException
+    {
+        // handled by LaunchServices and/0r user interaction
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public void createProcess(String cmd, boolean inheritsHandles) throws PlatformManagerException
+    {
+        try
+        {
+            performRuntimeExec(cmd.split(" "));
+        }
+        catch (Throwable e)
+        {
+            throw new PlatformManagerException("Failed to create process", e);
+        }
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public void performRecoverableFileDelete(String path) throws PlatformManagerException
+    {
+        File file = new File(path);
+        if(!file.exists())
+        {
+	        	if (Logger.isEnabled())
+							Logger.log(new LogEvent(LOGID, LogEvent.LT_WARNING, "Cannot find "
+									+ file.getName()));
+            return;
+        }
+
+        boolean useOSA = !NativeInvocationBridge.sharedInstance().isEnabled() || !NativeInvocationBridge.sharedInstance().performRecoverableFileDelete(file);
+
+        if(useOSA)
+        {
+            try
+            {
+                StringBuffer sb = new StringBuffer();
+                sb.append("tell application \"");
+                sb.append("Finder");
+                sb.append("\" to move (posix file \"");
+                sb.append(path);
+                sb.append("\" as alias) to the trash");
+
+                performOSAScript(sb);
+            }
+            catch (Throwable e)
+            {
+                throw new PlatformManagerException("Failed to move file", e);
+            }
+        }
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public boolean hasCapability(PlatformManagerCapabilities capability)
+    {
+        return capabilitySet.contains(capability);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public void dispose()
+    {
+        NativeInvocationBridge.sharedInstance().dispose();
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public void setTCPTOSEnabled(boolean enabled) throws PlatformManagerException
+    {
+        throw new PlatformManagerException("Unsupported capability called on platform manager");
+    }
+
+	public void
+    copyFilePermissions(
+		String	from_file_name,
+		String	to_file_name )
+	
+		throws PlatformManagerException
+	{
+	    throw new PlatformManagerException("Unsupported capability called on platform manager");		
+	}
+	
+    /**
+     * {@inheritDoc}
+     */
+    public void showFile(String path) throws PlatformManagerException
+    {
+        File file = new File(path);
+        if(!file.exists())
+        {
+        	if (Logger.isEnabled())
+        		Logger.log(new LogEvent(LOGID, LogEvent.LT_WARNING, "Cannot find "
+        				+ file.getName()));
+            throw new PlatformManagerException("File not found");
+        }
+
+        showInFinder(file);
+    }
+
+    // Public utility methods not shared across the interface
+
+    /**
+     * Plays the system alert (the jingle is specified by the user in System Preferences)
+     */
+    public void playSystemAlert()
+    {
+        try
+        {
+            performRuntimeExec(new String[]{"beep"});
+        }
+        catch (IOException e)
+        {
+        	if (Logger.isEnabled())
+        		Logger.log(new LogEvent(LOGID, LogEvent.LT_WARNING,
+						"Cannot play system alert"));
+        	Logger.log(new LogEvent(LOGID, "", e));
+        }
+    }
+
+    /**
+     * 
    Shows the given file or directory in Finder
    
+     * @param path Absolute path to the file or directory
+     */
+    public void showInFinder(File path)
+    {
+        boolean useOSA = !NativeInvocationBridge.sharedInstance().isEnabled() || !NativeInvocationBridge.sharedInstance().showInFinder(path);
+
+        if(useOSA)
+        {
+            StringBuffer sb = new StringBuffer();
+            sb.append("tell application \"");
+            sb.append(getFileBrowserName());
+            sb.append("\" to reveal (posix file \"");
+            sb.append(path);
+            sb.append("\" as alias)");
+
+            try
+            {
+                performOSAScript(sb);
+            }
+            catch (IOException e)
+            {
+                Logger.log(new LogAlert(LogAlert.UNREPEATABLE, LogAlert.AT_ERROR, e
+						.getMessage()));
+            }
+        }
+    }
+
+    /**
+     * 
    Shows the given file or directory in Terminal by executing cd /absolute/path/to
    
+     * @param path Absolute path to the file or directory
+     */
+    public void showInTerminal(String path)
+    {
+        showInTerminal(new File(path));
+    }
+
+    /**
+     * 
    Shows the given file or directory in Terminal by executing cd /absolute/path/to
    
+     * @param path Absolute path to the file or directory
+     */
+    public void showInTerminal(File path)
+    {
+        if (path.isFile())
+        {
+            path = path.getParentFile();
+        }
+
+        if (path != null && path.isDirectory())
+        {
+            StringBuffer sb = new StringBuffer();
+            sb.append("tell application \"");
+            sb.append("Terminal");
+            sb.append("\" to do script \"cd ");
+            sb.append(path.getAbsolutePath().replaceAll(" ", "\\ "));
+            sb.append("\"");
+
+            try
+            {
+                performOSAScript(sb);
+            }
+            catch (IOException e)
+            {
+                Logger.log(new LogAlert(LogAlert.UNREPEATABLE, LogAlert.AT_ERROR, e
+						.getMessage()));
+            }
+        }
+        else
+        {
+        	if (Logger.isEnabled())
+        		Logger.log(new LogEvent(LOGID, LogEvent.LT_WARNING, "Cannot find "
+        				+ path.getName()));
+        }
+    }
+
+    // Internal utility methods
+
+    /**
+     * Compiles a new AppleScript instance and runs it
+     * @param cmd AppleScript command to execute; do not surround command with extra quotation marks
+     * @return Output of the script
+     * @throws IOException If the script failed to execute
+     */
+    protected static String performOSAScript(CharSequence cmd) throws IOException
+    {
+        return performOSAScript(new CharSequence[]{cmd});
+    }
+
+    /**
+     * Compiles a new AppleScript instance and runs it
+     * @param cmds AppleScript Sequence of commands to execute; do not surround command with extra quotation marks
+     * @return Output of the script
+     * @throws IOException If the script failed to execute
+     */
+    protected static String performOSAScript(CharSequence[] cmds) throws IOException
+    {
+        long start = System.currentTimeMillis();
+        Debug.outNoStack("Executing OSAScript: ");
+        for (int i = 0; i < cmds.length; i++)
+        {
+            Debug.outNoStack("\t" + cmds[i]);
+        }
+
+        String[] cmdargs = new String[2 * cmds.length + 1];
+        cmdargs[0] = "osascript";
+        for (int i = 0; i < cmds.length; i++)
+        {
+            cmdargs[i * 2 + 1] = "-e";
+            cmdargs[i * 2 + 2] = String.valueOf(cmds[i]);
+        }
+
+        Process osaProcess = performRuntimeExec(cmdargs);
+        BufferedReader reader = new BufferedReader(new InputStreamReader(osaProcess.getInputStream()));
+        String line = reader.readLine();
+        reader.close();
+        Debug.outNoStack("OSAScript Output: " + line);
+
+        reader = new BufferedReader(new InputStreamReader(osaProcess.getErrorStream()));
+        String errorMsg = reader.readLine();
+        reader.close();
+
+        Debug.outNoStack("OSAScript Error (if any): " + errorMsg);
+
+        Debug.outNoStack(MessageFormat.format("OSAScript execution ended ({0}ms)", new Object[]{String.valueOf(System.currentTimeMillis() - start)}));
+
+        if (errorMsg != null)
+        {
+            throw new IOException(errorMsg);
+        }
+
+        return line;
+    }
+
+    /**
+     * Compiles a new AppleScript instance and runs it
+     * @param script AppleScript file (.scpt) to execute
+     * @return Output of the script
+     * @throws IOException If the script failed to execute
+     */
+    protected static String performOSAScript(File script) throws IOException
+    {
+        long start = System.currentTimeMillis();
+        Debug.outNoStack("Executing OSAScript from file: " + script.getPath());
+
+        Process osaProcess = performRuntimeExec(new String[]{"osascript", script.getPath()});
+        BufferedReader reader = new BufferedReader(new InputStreamReader(osaProcess.getInputStream()));
+        String line = reader.readLine();
+        reader.close();
+        Debug.outNoStack("OSAScript Output: " + line);
+
+        reader = new BufferedReader(new InputStreamReader(osaProcess.getErrorStream()));
+        String errorMsg = reader.readLine();
+        reader.close();
+
+        Debug.outNoStack("OSAScript Error (if any): " + errorMsg);
+
+        Debug.outNoStack(MessageFormat.format("OSAScript execution ended ({0}ms)", new Object[]{String.valueOf(System.currentTimeMillis() - start)}));
+
+        if (errorMsg != null)
+        {
+            throw new IOException(errorMsg);
+        }
+
+        return line;
+    }
+
+    /**
+     * Compiles a new AppleScript instance to the specified location
+     * @param cmd         Command to compile; do not surround command with extra quotation marks
+     * @param destination Destination location of the AppleScript file
+     * @return True if compiled successfully
+     */
+    protected static boolean compileOSAScript(CharSequence cmd, File destination)
+    {
+        return compileOSAScript(new CharSequence[]{cmd}, destination);
+    }
+
+    /**
+     * Compiles a new AppleScript instance to the specified location
+     * @param cmds Sequence of commands to compile; do not surround command with extra quotation marks
+     * @param destination Destination location of the AppleScript file
+     * @return True if compiled successfully
+     */
+    protected static boolean compileOSAScript(CharSequence[] cmds, File destination)
+    {
+        long start = System.currentTimeMillis();
+        Debug.outNoStack("Compiling OSAScript: " + destination.getPath());
+        for (int i = 0; i < cmds.length; i++)
+        {
+            Debug.outNoStack("\t" + cmds[i]);
+        }
+
+        String[] cmdargs = new String[2 * cmds.length + 3];
+        cmdargs[0] = "osacompile";
+        for (int i = 0; i < cmds.length; i++)
+        {
+            cmdargs[i * 2 + 1] = "-e";
+            cmdargs[i * 2 + 2] = String.valueOf(cmds[i]);
+        }
+
+        cmdargs[cmdargs.length - 2] = "-o";
+        cmdargs[cmdargs.length - 1] = destination.getPath();
+
+        String errorMsg;
+        try
+        {
+            Process osaProcess = performRuntimeExec(cmdargs);
+
+            BufferedReader reader = new BufferedReader(new InputStreamReader(osaProcess.getErrorStream()));
+            errorMsg = reader.readLine();
+            reader.close();
+        }
+        catch (IOException e)
+        {
+            Debug.outNoStack("OSACompile Execution Failed: " + e.getMessage());
+            Debug.printStackTrace(e);
+            return false;
+        }
+
+        Debug.outNoStack("OSACompile Error (if any): " + errorMsg);
+
+        Debug.outNoStack(MessageFormat.format("OSACompile execution ended ({0}ms)", new Object[]{String.valueOf(System.currentTimeMillis() - start)}));
+
+        return (errorMsg == null);
+    }
+
+    /**
+     * @see Runtime#exec(String[])
+     */
+    protected static Process performRuntimeExec(String[] cmdargs) throws IOException
+    {
+        try
+        {
+            return Runtime.getRuntime().exec(cmdargs);
+        }
+        catch (IOException e)
+        {
+            Logger.log(new LogAlert(LogAlert.UNREPEATABLE, e.getMessage(), e));
+            throw e;
+        }
+    }
+
+    /**
+     * 
    Gets the preferred file browser name
    
+     * 
    Currently supported browsers are Path Finder and Finder. If Path Finder is currently running
+     * (not just installed), then "Path Finder is returned; else, "Finder" is returned.
    
+     * @return "Path Finder" if it is currently running; else "Finder"
+     */
+    private static String getFileBrowserName()
+    {
+        try
+        {
+            // slowwwwwwww
+            if ("true".equalsIgnoreCase(performOSAScript("tell application \"System Events\" to exists process \"Path Finder\"")))
+            {
+                Debug.outNoStack("Path Finder is running");
+
+                return "Path Finder";
+            }
+            else
+            {
+                return "Finder";
+            }
+        }
+        catch (IOException e)
+        {
+            Debug.printStackTrace(e);
+            Logger.log(new LogEvent(LOGID, e.getMessage(), e));
+
+            return "Finder";
+        }
+    }
+    
+	public boolean
+	testNativeAvailability(
+		String	name )
+	
+		throws PlatformManagerException
+	{
+	    throw new PlatformManagerException("Unsupported capability called on platform manager");		
+	}
+    
+    public void
+    addListener(
+    	PlatformManagerListener		listener )
+    {
+    }
+    
+    public void
+    removeListener(
+    	PlatformManagerListener		listener )
+    {
+    }
+}

Added: external/Pygments-0.8.1/tests/examplefiles/test.jsp
==============================================================================
--- (empty file)
+++ external/Pygments-0.8.1/tests/examplefiles/test.jsp	Thu Aug  9 17:43:13 2007
@@ -0,0 +1,24 @@
+
+<%= var x = 1;
+%>
+<%! int i = 0; %>
+<%! int a, b, c; %>
+<%! Circle a = new Circle(2.0); %>
+
+<%
+      String name = null;
+      if (request.getParameter("name") == null) {
+%>
+<%@ include file="error.html" %>
+<%
+      } else {
+      foo.setName(request.getParameter("name"));
+      if (foo.getName().equalsIgnoreCase("integra"))
+      name = "acura";
+      if (name.equalsIgnoreCase( "acura" )) {
+%>
+
+
+
    
+Calendar of 
+
    

Added: external/Pygments-0.8.1/tests/examplefiles/test.myt
==============================================================================
--- (empty file)
+++ external/Pygments-0.8.1/tests/examplefiles/test.myt	Thu Aug  9 17:43:13 2007
@@ -0,0 +1,166 @@
+<%doc>formatting.myt - Provides section formatting elements, syntax-highlighted code blocks, and other special filters.
+
+<%global>
+    import string, re
+    import highlight
+
+
+<%method section>
+<%doc>Main section formatting element.
+<%args>
+    toc
+    path
+    description=None
+    onepage=False
+
+<%init>
+    item = toc.get_by_path(path)
+    if item is None:
+        raise "path: " + path
+
+
+
+
+
    
+
+<%python>
+    content = m.content()
+    re2 = re.compile(r"'''PYESC(.+?)PYESC'''", re.S)
+    content = re2.sub(lambda m: m.group(1), content)
+
+
+% if item.depth > 1:
+
    <% description or item.description %>
    
+%
+
+    
    
+    <% content %>
+    
    
+
+% if onepage or item.depth > 1:
+%   if (item.next and item.next.depth >= item.depth):
+    back to section top
+%
+% else:
+    back to section top
+    <& nav.myt:pagenav, item=item, onepage=onepage &>
+% 
+
    
+
+
+
+
+<%method formatplain>
+    <%filter>
+        import re
+        f = re.sub(r'\n[\s\t]*\n[\s\t]*', '
    \n
    ', f)
+        f = "
    " + f + "
    "
+        return f
+    
+<% m.content() | h%>
+
+
+
+
+
+<%method codeline trim="both">
+<% m.content() %>
+
+
+<%method code autoflush=False>
+<%args>
+    title = None
+    syntaxtype = 'python'
+    html_escape = False
+    use_sliders = False
+
+
+<%init>
+    def fix_indent(f):
+        f =string.expandtabs(f, 4)
+        g = ''
+        lines = string.split(f, "\n")
+        whitespace = None
+        for line in lines:
+            if whitespace is None:
+                match = re.match(r"^([ ]*).+", line)
+                if match is not None:
+                    whitespace = match.group(1)
+
+            if whitespace is not None:
+                line = re.sub(r"^%s" % whitespace, "", line)
+
+            if whitespace is not None or re.search(r"\w", line) is not None:
+                g += (line + "\n")
+
+
+        return g.rstrip()
+
+    p = re.compile(r'
    (.*?)
    ', re.S)
+    def hlight(match):
+        return "
    " + highlight.highlight(fix_indent(match.group(1)), html_escape = html_escape, syntaxtype = syntaxtype) + "
    "
+    content = p.sub(hlight, "
    " + m.content() + "
    ")
+
+
    ">
+% if title is not None:
+    
    <% title %>
    
+%
+<% content %>
    
+
+
+
+
+
+<%method popboxlink trim="both"> 
+    <%args>
+        name=None
+        show='show'
+        hide='hide'
+    
+    <%init>
+        if name is None:
+            name = m.attributes.setdefault('popbox_name', 0)
+        name += 1
+        m.attributes['popbox_name'] = name
+        name = "popbox_" + repr(name)
+    
+javascript:togglePopbox('<% name %>', '<% show %>', '<% hide %>')
+
+
+<%method popbox trim="both">
+<%args>
+    name = None
+    class_ = None
+
+<%init>
+    if name is None:
+        name = 'popbox_' + repr(m.attributes['popbox_name'])
+
+
+
+
+<%method poplink trim="both">
+    <%args>
+        link='sql'
+    
+    <%init>
+        href = m.scomp('SELF:popboxlink')
+    
+    '''PYESC<& nav.myt:link, href=href, text=link, class_="codepoplink" &>PYESC'''
+
+
+<%method codepopper trim="both">
+	<%init>
+		c = m.content()
+		c = re.sub(r'\n', '
    \n', c.strip())
+	
+
    <&|SELF:popbox, class_="codepop" &><% c %>
    +
+
+<%method poppedcode trim="both">
+	<%init>
+		c = m.content()
+		c = re.sub(r'\n', '
    \n', c.strip())
+	
+
    <% c %>
    +

Added: external/Pygments-0.8.1/tests/examplefiles/test.pas
==============================================================================
--- (empty file)
+++ external/Pygments-0.8.1/tests/examplefiles/test.pas	Thu Aug  9 17:43:13 2007
@@ -0,0 +1,743 @@
+//
+// Sourcecode from http://www.delphi-library.de/topic_47880.html
+//
+uses Windows, Messages;
+
+const
+  FFM_INIT               = WM_USER + 1976;
+  FFM_ONFILEFOUND        = WM_USER + 1974; // wParam: not used, lParam: Filename
+  FFM_ONDIRFOUND         = WM_USER + 1975; // wParam: NumFolder, lParam: Directory
+var
+  CntFolders             : Cardinal = 0;
+  NumFolder              : Cardinal = 0;
+
+
+////////////////////////////////////////////////////////////////////////////////
+//
+//  FindAllFilesInit
+//
+//
+procedure FindAllFilesInit; external;
+label foo;
+begin
+  CntFolders := 0;
+  NumFolder := 0;
+foo:
+  Blub;
+  goto foo;
+end;
+
+////////////////////////////////////////////////////////////////////////////////
+//
+//  CountFolders
+//
+//
+procedure CountFolders(Handle: THandle; RootFolder: string; Recurse: Boolean = True);
+var
+  hFindFile              : THandle;
+  wfd                    : TWin32FindData;
+begin
+  SendMessage(Handle, FFM_INIT, 0, 0);
+  if RootFolder[length(RootFolder)] <> '\' then
+    RootFolder := RootFolder + '\';
+  ZeroMemory(@wfd, sizeof(wfd));
+  wfd.dwFileAttributes := FILE_ATTRIBUTE_NORMAL;
+  if Recurse then
+  begin
+    hFindFile := FindFirstFile(pointer(RootFolder + '*.*'), wfd);
+    if hFindFile <> 0 then
+    try
+      repeat
+        if wfd.dwFileAttributes and FILE_ATTRIBUTE_DIRECTORY = FILE_ATTRIBUTE_DIRECTORY then
+        begin
+          if (string(wfd.cFileName) <> '.') and (string(wfd.cFileName) <> '..') then
+          begin
+            CountFolders(Handle, RootFolder + wfd.cFileName, Recurse);
+          end;
+        end;
+      until FindNextFile(hFindFile, wfd) = False;
+      Inc(CntFolders);
+    finally
+      Windows.FindClose(hFindFile);
+    end;
+  end;
+end;
+
+////////////////////////////////////////////////////////////////////////////////
+//
+//  FindAllFiles
+//
+procedure FindAllFiles(Handle: THandle; RootFolder: string; Mask: string; Recurse: Boolean = True);
+var
+  hFindFile              : THandle;
+  wfd                    : TWin32FindData;
+begin
+  if RootFolder[length(RootFolder)] <> '\' then
+    RootFolder := RootFolder + '\';
+  ZeroMemory(@wfd, sizeof(wfd));
+  wfd.dwFileAttributes := FILE_ATTRIBUTE_NORMAL;
+  if Recurse then
+  begin
+    hFindFile := FindFirstFile(pointer(RootFolder + '*.*'), wfd);
+    if hFindFile <> 0 then
+    try
+      repeat
+        if wfd.dwFileAttributes and FILE_ATTRIBUTE_DIRECTORY = FILE_ATTRIBUTE_DIRECTORY then
+        begin
+          if (string(wfd.cFileName) <> '.') and (string(wfd.cFileName) <> '..') then
+          begin
+            FindAllFiles(Handle, RootFolder + wfd.cFileName, Mask, Recurse);
+          end;
+        end;
+      until FindNextFile(hFindFile, wfd) = False;
+      Inc(NumFolder);
+      SendMessage(Handle, FFM_ONDIRFOUND, NumFolder, lParam(string(RootFolder)));
+    finally
+      Windows.FindClose(hFindFile);
+    end;
+  end;
+  hFindFile := FindFirstFile(pointer(RootFolder + Mask), wfd);
+  if hFindFile <> INVALID_HANDLE_VALUE then
+  try
+    repeat
+      if (wfd.dwFileAttributes and FILE_ATTRIBUTE_DIRECTORY <> FILE_ATTRIBUTE_DIRECTORY) then
+      begin
+        SendMessage(Handle, FFM_ONFILEFOUND, 0, lParam(string(RootFolder + wfd.cFileName)));
+      end;
+    until FindNextFile(hFindFile, wfd) = False;
+  finally
+    Windows.FindClose(hFindFile);
+  end;
+end;
+
+
+property test: boolean read ftest write ftest;
+procedure test: boolean read ftest write ftest;
+
+//
+// This sourcecode is part of omorphia
+//
+
+Function IsValidHandle(Const Handle: THandle): Boolean; {$IFDEF OMORPHIA_FEATURES_USEASM} Assembler;
+Asm
+    TEST    EAX, EAX
+    JZ      @@Finish
+    NOT     EAX
+    TEST    EAX, EAX
+    SETNZ   AL
+
+    {$IFDEF WINDOWS}
+    JZ      @@Finish
+
+    //Save the handle against modifications or loss
+    PUSH    EAX
+
+    //reserve some space for a later duplicate
+    PUSH    EAX
+
+    //Check if we are working on NT-Platform
+    CALL    IsWindowsNTSystem
+    TEST    EAX, EAX
+    JZ      @@NoNTSystem
+
+    PUSH    DWORD PTR [ESP]
+    LEA     EAX, DWORD PTR [ESP+$04]
+    PUSH    EAX
+    CALL    GetHandleInformation
+    TEST    EAX, EAX
+    JNZ     @@Finish2
+
+@@NoNTSystem:
+    //Result := DuplicateHandle(GetCurrentProcess, Handle, GetCurrentProcess,
+    //  @Duplicate, 0, False, DUPLICATE_SAME_ACCESS);
+    PUSH    DUPLICATE_SAME_ACCESS
+    PUSH    $00000000
+    PUSH    $00000000
+    LEA     EAX, DWORD PTR [ESP+$0C]
+    PUSH    EAX
+    CALL    GetCurrentProcess
+    PUSH    EAX
+    PUSH    DWORD PTR [ESP+$18]
+    PUSH    EAX
+    CALL    DuplicateHandle
+
+    TEST    EAX, EAX
+    JZ      @@Finish2
+
+    //  Result := CloseHandle(Duplicate);
+    PUSH    DWORD PTR [ESP]
+    CALL    CloseHandle
+
+@@Finish2:
+    POP     EDX
+    POP     EDX
+
+    PUSH    EAX
+    PUSH    $00000000
+    CALL    SetLastError
+    POP     EAX
+    {$ENDIF}
+
+@@Finish:
+End;
+{$ELSE}
+Var
+    Duplicate: THandle;
+    Flags: DWORD;
+Begin
+    If IsWinNT Then
+        Result := GetHandleInformation(Handle, Flags)
+    Else
+        Result := False;
+    If Not Result Then
+    Begin
+        // DuplicateHandle is used as an additional check for those object types not
+        // supported by GetHandleInformation (e.g. according to the documentation,
+        // GetHandleInformation doesn't support window stations and desktop although
+        // tests show that it does). GetHandleInformation is tried first because its
+        // much faster. Additionally GetHandleInformation is only supported on NT...
+        Result := DuplicateHandle(GetCurrentProcess, Handle, GetCurrentProcess,
+            @Duplicate, 0, False, DUPLICATE_SAME_ACCESS);
+        If Result Then
+            Result := CloseHandle(Duplicate);
+    End;
+End;
+{$ENDIF}
+
+
+    	
+
+{*******************************************************}
+{                                                       }
+{       Delphi Supplemental Components                  }
+{       ZLIB Data Compression Interface Unit            }
+{                                                       }
+{       Copyright (c) 1997 Borland International        }
+{                                                       }
+{*******************************************************}
+
+{ Modified for zlib 1.1.3 by Davide Moretti  Z_STREAM_END do
+      begin
+        P := OutBuf;
+        Inc(OutBytes, 256);
+        ReallocMem(OutBuf, OutBytes);
+        strm.next_out := PChar(Integer(OutBuf) + (Integer(strm.next_out) - Integer(P)));
+        strm.avail_out := 256;
+      end;
+    finally
+      CCheck(deflateEnd(strm));
+    end;
+    ReallocMem(OutBuf, strm.total_out);
+    OutBytes := strm.total_out;
+  except
+    FreeMem(OutBuf);
+    raise
+  end;
+end;
+
+
+procedure DecompressBuf(const InBuf: Pointer; InBytes: Integer;
+  OutEstimate: Integer; out OutBuf: Pointer; out OutBytes: Integer);
+var
+  strm: TZStreamRec;
+  P: Pointer;
+  BufInc: Integer;
+begin
+  FillChar(strm, sizeof(strm), 0);
+  BufInc := (InBytes + 255) and not 255;
+  if OutEstimate = 0 then
+    OutBytes := BufInc
+  else
+    OutBytes := OutEstimate;
+  GetMem(OutBuf, OutBytes);
+  try
+    strm.next_in := InBuf;
+    strm.avail_in := InBytes;
+    strm.next_out := OutBuf;
+    strm.avail_out := OutBytes;
+    DCheck(inflateInit_(strm, zlib_version, sizeof(strm)));
+    try
+      while DCheck(inflate(strm, Z_FINISH)) <> Z_STREAM_END do
+      begin
+        P := OutBuf;
+        Inc(OutBytes, BufInc);
+        ReallocMem(OutBuf, OutBytes);
+        strm.next_out := PChar(Integer(OutBuf) + (Integer(strm.next_out) - Integer(P)));
+        strm.avail_out := BufInc;
+      end;
+    finally
+      DCheck(inflateEnd(strm));
+    end;
+    ReallocMem(OutBuf, strm.total_out);
+    OutBytes := strm.total_out;
+  except
+    FreeMem(OutBuf);
+    raise
+  end;
+end;
+
+
+// TCustomZlibStream
+
+constructor TCustomZLibStream.Create(Strm: TStream);
+begin
+  inherited Create;
+  FStrm := Strm;
+  FStrmPos := Strm.Position;
+end;
+
+procedure TCustomZLibStream.Progress(Sender: TObject);
+begin
+  if Assigned(FOnProgress) then FOnProgress(Sender);
+end;
+
+
+// TCompressionStream
+
+constructor TCompressionStream.Create(CompressionLevel: TCompressionLevel;
+  Dest: TStream);
+const
+  Levels: array [TCompressionLevel] of ShortInt =
+    (Z_NO_COMPRESSION, Z_BEST_SPEED, Z_DEFAULT_COMPRESSION, Z_BEST_COMPRESSION);
+begin
+  inherited Create(Dest);
+  FZRec.next_out := FBuffer;
+  FZRec.avail_out := sizeof(FBuffer);
+  CCheck(deflateInit_(FZRec, Levels[CompressionLevel], zlib_version, sizeof(FZRec)));
+end;
+
+destructor TCompressionStream.Destroy;
+begin
+  FZRec.next_in := nil;
+  FZRec.avail_in := 0;
+  try
+    if FStrm.Position <> FStrmPos then FStrm.Position := FStrmPos;
+    while (CCheck(deflate(FZRec, Z_FINISH)) <> Z_STREAM_END)
+      and (FZRec.avail_out = 0) do
+    begin
+      FStrm.WriteBuffer(FBuffer, sizeof(FBuffer));
+      FZRec.next_out := FBuffer;
+      FZRec.avail_out := sizeof(FBuffer);
+    end;
+    if FZRec.avail_out < sizeof(FBuffer) then
+      FStrm.WriteBuffer(FBuffer, sizeof(FBuffer) - FZRec.avail_out);
+  finally
+    deflateEnd(FZRec);
+  end;
+  inherited Destroy;
+end;
+
+function TCompressionStream.Read(var Buffer; Count: Longint): Longint;
+begin
+  raise ECompressionError.Create('Invalid stream operation');
+end;
+
+function TCompressionStream.Write(const Buffer; Count: Longint): Longint;
+begin
+  FZRec.next_in := @Buffer;
+  FZRec.avail_in := Count;
+  if FStrm.Position <> FStrmPos then FStrm.Position := FStrmPos;
+  while (FZRec.avail_in > 0) do
+  begin
+    CCheck(deflate(FZRec, 0));
+    if FZRec.avail_out = 0 then
+    begin
+      FStrm.WriteBuffer(FBuffer, sizeof(FBuffer));
+      FZRec.next_out := FBuffer;
+      FZRec.avail_out := sizeof(FBuffer);
+      FStrmPos := FStrm.Position;
+      Progress(Self);
+    end;
+  end;
+  Result := Count;
+end;
+
+function TCompressionStream.Seek(Offset: Longint; Origin: Word): Longint;
+begin
+  if (Offset = 0) and (Origin = soFromCurrent) then
+    Result := FZRec.total_in
+  else
+    raise ECompressionError.Create('Invalid stream operation');
+end;
+
+function TCompressionStream.GetCompressionRate: Single;
+begin
+  if FZRec.total_in = 0 then
+    Result := 0
+  else
+    Result := (1.0 - (FZRec.total_out / FZRec.total_in)) * 100.0;
+end;
+
+
+// TDecompressionStream
+
+constructor TDecompressionStream.Create(Source: TStream);
+begin
+  inherited Create(Source);
+  FZRec.next_in := FBuffer;
+  FZRec.avail_in := 0;
+  DCheck(inflateInit_(FZRec, zlib_version, sizeof(FZRec)));
+end;
+
+destructor TDecompressionStream.Destroy;
+begin
+  inflateEnd(FZRec);
+  inherited Destroy;
+end;
+
+function TDecompressionStream.Read(var Buffer; Count: Longint): Longint;
+begin
+  FZRec.next_out := @Buffer;
+  FZRec.avail_out := Count;
+  if FStrm.Position <> FStrmPos then FStrm.Position := FStrmPos;
+  while (FZRec.avail_out > 0) do
+  begin
+    if FZRec.avail_in = 0 then
+    begin
+      FZRec.avail_in := FStrm.Read(FBuffer, sizeof(FBuffer));
+      if FZRec.avail_in = 0 then
+        begin
+          Result := Count - FZRec.avail_out;
+          Exit;
+        end;
+      FZRec.next_in := FBuffer;
+      FStrmPos := FStrm.Position;
+      Progress(Self);
+    end;
+    DCheck(inflate(FZRec, 0));
+  end;
+  Result := Count;
+end;
+
+function TDecompressionStream.Write(const Buffer; Count: Longint): Longint;
+begin
+  raise EDecompressionError.Create('Invalid stream operation');
+end;
+
+function TDecompressionStream.Seek(Offset: Longint; Origin: Word): Longint;
+var
+  I: Integer;
+  Buf: array [0..4095] of Char;
+begin
+  if (Offset = 0) and (Origin = soFromBeginning) then
+  begin
+    DCheck(inflateReset(FZRec));
+    FZRec.next_in := FBuffer;
+    FZRec.avail_in := 0;
+    FStrm.Position := 0;
+    FStrmPos := 0;
+  end
+  else if ( (Offset >= 0) and (Origin = soFromCurrent)) or
+          ( ((Offset - FZRec.total_out) > 0) and (Origin = soFromBeginning)) then
+  begin
+    if Origin = soFromBeginning then Dec(Offset, FZRec.total_out);
+    if Offset > 0 then
+    begin
+      for I := 1 to Offset div sizeof(Buf) do
+        ReadBuffer(Buf, sizeof(Buf));
+      ReadBuffer(Buf, Offset mod sizeof(Buf));
+    end;
+  end
+  else
+    raise EDecompressionError.Create('Invalid stream operation');
+  Result := FZRec.total_out;
+end;
+
+end.

Added: external/Pygments-0.8.1/tests/examplefiles/test.php
==============================================================================
--- (empty file)
+++ external/Pygments-0.8.1/tests/examplefiles/test.php	Thu Aug  9 17:43:13 2007
@@ -0,0 +1,498 @@
+
+ *  @copyright   Copyright (c) 2006, Manni
+ *  @version     1.0
+ *  @link        http://www.pkware.com/business_and_developers/developer/popups/appnote.txt
+ *  @link        http://mannithedark.is-a-geek.net/
+ *  @since       1.0
+ *  @package     fnord.bb
+ *  @subpackage  archive
+ */
+class Zip extends Archive {
+ /**
+  *  Outputs the zip file
+  *
+  *  This function creates the zip file with the dirs and files given.
+  *  If the optional parameter $file is given, the zip file is will be
+  *  saved at that location. Otherwise the function returns the zip file's content.
+  *
+  *  @access                   public
+  *
+  *  @link                     http://www.pkware.com/business_and_developers/developer/popups/appnote.txt
+  *  @param  string $filename  The path where the zip file will be saved
+  *
+  *  @return bool|string       Returns either true if the fil is sucessfully created or the content of the zip file
+  */
+  function out($filename = false) {
+    // Empty output
+    $file_data = array(); // Data of the file part
+    $cd_data   = array(); // Data of the central directory
+
+    // Sort dirs and files by path length
+    uksort($this->dirs,  'sort_by_length');
+    uksort($this->files, 'sort_by_length');
+
+    // Handle dirs
+    foreach($this->dirs as $dir) {
+      $dir .= '/';
+      // File part
+
+      // Reset dir data
+      $dir_data = '';
+
+      // Local file header
+      $dir_data .= "\x50\x4b\x03\x04";      // Local file header signature
+      $dir_data .= pack("v", 10);           // Version needed to extract
+      $dir_data .= pack("v", 0);            // General purpose bit flag
+      $dir_data .= pack("v", 0);            // Compression method
+      $dir_data .= pack("v", 0);            // Last mod file time
+      $dir_data .= pack("v", 0);            // Last mod file date
+      $dir_data .= pack("V", 0);            // crc-32
+      $dir_data .= pack("V", 0);            // Compressed size
+      $dir_data .= pack("V", 0);            // Uncompressed size
+      $dir_data .= pack("v", strlen($dir)); // File name length
+      $dir_data .= pack("v", 0);            // Extra field length
+
+      $dir_data .= $dir;                    // File name
+      $dir_data .= '';                      // Extra field (is empty)
+
+      // File data
+      $dir_data .= '';                      // Dirs have no file data
+
+      // Data descriptor
+      $dir_data .= pack("V", 0);            // crc-32
+      $dir_data .= pack("V", 0);            // Compressed size
+      $dir_data .= pack("V", 0);            // Uncompressed size
+
+      // Save current offset
+      $offset = strlen(implode('', $file_data));
+
+      // Append dir data to the file part
+      $file_data[] = $dir_data;
+
+      // Central directory
+
+      // Reset dir data
+      $dir_data = '';
+
+      // File header
+      $dir_data .= "\x50\x4b\x01\x02";      // Local file header signature
+      $dir_data .= pack("v", 0);            // Version made by
+      $dir_data .= pack("v", 10);           // Version needed to extract
+      $dir_data .= pack("v", 0);            // General purpose bit flag
+      $dir_data .= pack("v", 0);            // Compression method
+      $dir_data .= pack("v", 0);            // Last mod file time
+      $dir_data .= pack("v", 0);            // Last mod file date
+      $dir_data .= pack("V", 0);            // crc-32
+      $dir_data .= pack("V", 0);            // Compressed size
+      $dir_data .= pack("V", 0);            // Uncompressed size
+      $dir_data .= pack("v", strlen($dir)); // File name length
+      $dir_data .= pack("v", 0);            // Extra field length
+      $dir_data .= pack("v", 0);            // File comment length
+      $dir_data .= pack("v", 0);            // Disk number start
+      $dir_data .= pack("v", 0);            // Internal file attributes
+      $dir_data .= pack("V", 16);           // External file attributes
+      $dir_data .= pack("V", $offset);      // Relative offset of local header
+
+      $dir_data .= $dir;                    // File name
+      $dir_data .= '';                      // Extra field (is empty)
+      $dir_data .= '';                      // File comment (is empty)
+
+      /*
+      // Data descriptor
+      $dir_data .= pack("V", 0);            // crc-32
+      $dir_data .= pack("V", 0);            // Compressed size
+      $dir_data .= pack("V", 0);            // Uncompressed size
+      */
+      
+      // Append dir data to the central directory data
+      $cd_data[] = $dir_data;
+    }
+
+    // Handle files
+    foreach($this->files as $name => $file) {
+      // Get values
+      $content = $file[0];
+    
+      // File part
+
+      // Reset file data
+      $fd = '';
+      
+      // Detect possible compressions
+      // Use deflate
+      if(function_exists('gzdeflate')) {
+        $method = 8;
+
+        // Compress file content
+        $compressed_data = gzdeflate($content);
+
+      // Use bzip2
+      } elseif(function_exists('bzcompress')) {
+        $method = 12;
+
+        // Compress file content
+        $compressed_data = bzcompress($content);
+
+      // No compression
+      } else {
+        $method = 0;
+
+        // Do not compress the content :P
+        $compressed_data = $content;
+      }
+
+      // Local file header
+      $fd .= "\x50\x4b\x03\x04";                  // Local file header signature
+      $fd .= pack("v", 20);                       // Version needed to extract
+      $fd .= pack("v", 0);                        // General purpose bit flag
+      $fd .= pack("v", $method);                  // Compression method
+      $fd .= pack("v", 0);                        // Last mod file time
+      $fd .= pack("v", 0);                        // Last mod file date
+      $fd .= pack("V", crc32($content));          // crc-32
+      $fd .= pack("V", strlen($compressed_data)); // Compressed size
+      $fd .= pack("V", strlen($content));         // Uncompressed size
+      $fd .= pack("v", strlen($name));            // File name length
+      $fd .= pack("v", 0);                        // Extra field length
+
+      $fd .= $name;                               // File name
+      $fd .= '';                                  // Extra field (is empty)
+
+      // File data
+      $fd .= $compressed_data;
+      
+      // Data descriptor
+      $fd .= pack("V", crc32($content));          // crc-32
+      $fd .= pack("V", strlen($compressed_data)); // Compressed size
+      $fd .= pack("V", strlen($content));         // Uncompressed size
+
+      // Save current offset
+      $offset = strlen(implode('', $file_data));
+
+      // Append file data to the file part
+      $file_data[] = $fd;
+
+      // Central directory
+
+      // Reset file data
+      $fd = '';
+
+      // File header
+      $fd .= "\x50\x4b\x01\x02";                  // Local file header signature
+      $fd .= pack("v", 0);                        // Version made by
+      $fd .= pack("v", 20);                       // Version needed to extract
+      $fd .= pack("v", 0);                        // General purpose bit flag
+      $fd .= pack("v", $method);                  // Compression method
+      $fd .= pack("v", 0);                        // Last mod file time
+      $fd .= pack("v", 0);                        // Last mod file date
+      $fd .= pack("V", crc32($content));          // crc-32
+      $fd .= pack("V", strlen($compressed_data)); // Compressed size
+      $fd .= pack("V", strlen($content));         // Uncompressed size
+      $fd .= pack("v", strlen($name));            // File name length
+      $fd .= pack("v", 0);                        // Extra field length
+      $fd .= pack("v", 0);                        // File comment length
+      $fd .= pack("v", 0);                        // Disk number start
+      $fd .= pack("v", 0);                        // Internal file attributes
+      $fd .= pack("V", 32);                       // External file attributes
+      $fd .= pack("V", $offset);                  // Relative offset of local header
+
+      $fd .= $name;                               // File name
+      $fd .= '';                                  // Extra field (is empty)
+      $fd .= '';                                  // File comment (is empty)
+
+      /*
+      // Data descriptor
+      $fd .= pack("V", crc32($content));          // crc-32
+      $fd .= pack("V", strlen($compressed_data)); // Compressed size
+      $fd .= pack("V", strlen($content));         // Uncompressed size
+      */
+
+      // Append file data to the central directory data
+      $cd_data[] = $fd;
+    }
+
+    // Digital signature
+    $digital_signature = '';
+    $digital_signature .= "\x50\x4b\x05\x05";  // Header signature
+    $digital_signature .= pack("v", 0);        // Size of data
+    $digital_signature .= '';                  // Signature data (is empty)
+
+    $tmp_file_data = implode('', $file_data);  // File data
+    $tmp_cd_data   = implode('', $cd_data).    // Central directory
+                     $digital_signature;       // Digital signature
+
+    // End of central directory
+    $eof_cd = '';
+    $eof_cd .= "\x50\x4b\x05\x06";                // End of central dir signature
+    $eof_cd .= pack("v", 0);                      // Number of this disk
+    $eof_cd .= pack("v", 0);                      // Number of the disk with the start of the central directory
+    $eof_cd .= pack("v", count($cd_data));        // Total number of entries in the central directory on this disk
+    $eof_cd .= pack("v", count($cd_data));        // Total number of entries in the central directory
+    $eof_cd .= pack("V", strlen($tmp_cd_data));   // Size of the central directory
+    $eof_cd .= pack("V", strlen($tmp_file_data)); // Offset of start of central directory with respect to the starting disk number
+    $eof_cd .= pack("v", 0);                      // .ZIP file comment length
+    $eof_cd .= '';                                // .ZIP file comment (is empty)
+
+    // Content of the zip file
+    $data = $tmp_file_data.
+            // $extra_data_record.
+            $tmp_cd_data.
+            $eof_cd;
+
+    // Return content?
+    if(!$filename)
+      return $data;
+      
+    // Write to file
+    return file_put_contents($filename, $data);
+  }
+  
+ /**
+  *  Load a zip file
+  *
+  *  This function loads the files and dirs from a zip file from the harddrive.
+  *
+  *  @access                public
+  *
+  *  @param  string $file   The path to the zip file
+  *  @param  bool   $reset  Reset the files and dirs before adding the zip file's content?
+  *
+  *  @return bool           Returns true if the file was loaded sucessfully
+  */
+  function load_file($file, $reset = true) {
+    // Check whether the file exists
+    if(!file_exists($file))
+      return false;
+
+    // Load the files content
+    $content = @file_get_contents($file);
+
+    // Return false if the file cannot be opened
+    if(!$content)
+      return false;
+
+    // Read the zip
+    return $this->load_string($content, $reset);
+  }
+  
+ /**
+  *  Load a zip string
+  *
+  *  This function loads the files and dirs from a string
+  *
+  *  @access                 public
+  *
+  *  @param  string $string  The string the zip is generated from
+  *  @param  bool   $reset   Reset the files and dirs before adding the zip file's content?
+  *
+  *  @return bool            Returns true if the string was loaded sucessfully
+  */
+  function load_string($string, $reset = true) {
+    // Reset the zip?
+    if($reset) {
+      $this->dirs  = array();
+      $this->files = array();
+    }
+
+    // Get the starting position of the end of central directory record
+    $start = strpos($string, "\x50\x4b\x05\x06");
+
+    // Error
+    if($start === false)
+      die('Could not find the end of central directory record');
+
+    // Get the ecdr
+    $eof_cd = substr($string, $start+4, 18);
+
+    // Unpack the ecdr infos
+    $eof_cd = unpack('vdisc1/'.
+                     'vdisc2/'.
+                     'ventries1/'.
+                     'ventries2/'.
+                     'Vsize/'.
+                     'Voffset/'.
+                     'vcomment_lenght', $eof_cd);
+
+    // Do not allow multi disc zips
+    if($eof_cd['disc1'] != 0)
+      die('multi disk stuff is not yet implemented :/');
+
+    // Save the interesting values
+    $cd_entries = $eof_cd['entries1'];
+    $cd_size    = $eof_cd['size'];
+    $cd_offset  = $eof_cd['offset'];
+
+    // Get the central directory record
+    $cdr = substr($string, $cd_offset, $cd_size);
+
+    // Reset the position and the list of the entries
+    $pos     = 0;
+    $entries = array();
+
+    // Handle cdr
+    while($pos < strlen($cdr)) {
+      // Check header signature
+      // Digital signature
+      if(substr($cdr, $pos, 4) == "\x50\x4b\x05\x05") {
+        // Get digital signature size
+        $tmp_info = unpack('vsize', substr($cdr, $pos + 4, 2));
+
+        // Read out the digital signature
+        $digital_sig = substr($header, $pos + 6, $tmp_info['size']);
+
+        break;
+      }
+
+      // Get file header
+      $header = substr($cdr, $pos, 46);
+
+      // Unpack the header information
+      $header_info = @unpack('Vheader/'.
+                             'vversion_made_by/'.
+                             'vversion_needed/'.
+                             'vgeneral_purpose/'.
+                             'vcompression_method/'.
+                             'vlast_mod_time/'.
+                             'vlast_mod_date/'.
+                             'Vcrc32/'.
+                             'Vcompressed_size/'.
+                             'Vuncompressed_size/'.
+                             'vname_length/'.
+                             'vextra_length/'.
+                             'vcomment_length/'.
+                             'vdisk_number/'.
+                             'vinternal_attributes/'.
+                             'Vexternal_attributes/'.
+                             'Voffset',
+                             $header);
+
+      // Valid header?
+      if($header_info['header'] != 33639248)
+        return false;
+
+      // New position
+      $pos += 46;
+
+      // Read out the file name
+      $header_info['name'] = substr($cdr, $pos, $header_info['name_length']);
+
+      // New position
+      $pos += $header_info['name_length'];
+
+      // Read out the extra stuff
+      $header_info['extra'] = substr($cdr, $pos, $header_info['extra_length']);
+
+      // New position
+      $pos += $header_info['extra_length'];
+
+      // Read out the comment
+      $header_info['comment'] = substr($cdr, $pos, $header_info['comment_length']);
+
+      // New position
+      $pos += $header_info['comment_length'];
+
+      // Append this file/dir to the entry list
+      $entries[] = $header_info;
+    }
+
+    // Check whether all entries where read sucessfully
+    if(count($entries) != $cd_entries)
+      return false;
+
+    // Handle files/dirs
+    foreach($entries as $entry) {
+      // Is a dir?
+      if($entry['external_attributes'] & 16) {
+        $this->add_dir($entry['name']);
+        continue;
+      }
+
+      // Get local file header
+      $header = substr($string, $entry['offset'], 30);
+
+      // Unpack the header information
+      $header_info = @unpack('Vheader/'.
+                             'vversion_needed/'.
+                             'vgeneral_purpose/'.
+                             'vcompression_method/'.
+                             'vlast_mod_time/'.
+                             'vlast_mod_date/'.
+                             'Vcrc32/'.
+                             'Vcompressed_size/'.
+                             'Vuncompressed_size/'.
+                             'vname_length/'.
+                             'vextra_length',
+                             $header);
+
+      // Valid header?
+      if($header_info['header'] != 67324752)
+        return false;
+
+      // Get content start position
+      $start = $entry['offset'] + 30 + $header_info['name_length'] + $header_info['extra_length'];
+
+      // Get the compressed data
+      $data = substr($string, $start, $header_info['compressed_size']);
+
+      // Detect compression type
+      switch($header_info['compression_method']) {
+        // No compression
+        case 0:
+          // Ne decompression needed
+          $content = $data;
+          break;
+
+        // Gzip
+        case 8:
+          if(!function_exists('gzinflate'))
+            return false;
+
+          // Uncompress data
+          $content = gzinflate($data);
+          break;
+
+        // Bzip2
+        case 12:
+          if(!function_exists('bzdecompress'))
+            return false;
+
+          // Decompress data
+          $content = bzdecompress($data);
+          break;
+
+        // Compression not supported -> error
+        default:
+          return false;
+      }
+
+      // Try to add file
+      if(!$this->add_file($entry['name'], $content))
+        return false;
+    }
+
+    return true;
+  }
+}
+
+function &byref() {
+    $x = array();
+    return $x;
+}
+?>

Added: external/Pygments-0.8.1/tests/examplefiles/test.rb
==============================================================================
--- (empty file)
+++ external/Pygments-0.8.1/tests/examplefiles/test.rb	Thu Aug  9 17:43:13 2007
@@ -0,0 +1,174 @@
+a.each{|el|anz[el]=anz[el]?anz[el]+1:1}
+while x<10000
+#a bis f dienen dazu die Nachbarschaft festzulegen. Man stelle sich die #Zahl von 1 bis 64 im Bin??rcode vor 1 bedeutet an 0 aus
+  b=(p[x]%32)/16<1 ? 0 : 1
+
+  (x-102>=0? n[x-102].to_i : 0)*a+(x-101>=0?n[x-101].to_i : 0)*e+n[x-100].to_i+(x-99>=0? n[x-99].to_i : 0)*f+(x-98>=0? n[x-98].to_i : 0)*a+
+  n[x+199].to_i*b+n[x+200].to_i*d+n[x+201].to_i*b
+
+#und die Ausgabe folgt
+g=%w{}
+x=0
+
+while x<100
+ puts"#{g[x]}"
+ x+=1
+end
+
+puts""
+sleep(10)
+
+1E1E1
+puts 30.send(:/, 5) # prints 6
+
+# fun with class attributes
+class Foo
+  def self.blub x
+    if not x.nil?
+      self.new
+    end
+  end
+  def another_way_to_get_class
+    self.class
+  end
+end
+
+# ruby 1.9 "call operator"
+a = Proc.new { 42 }
+a.()
+
+"instance variables can be #@included, #@@class_variables\n and #$globals as well."
+`instance variables can be #@included, #@@class_variables\n and #$globals as well.`
+'instance variables can be #@included, #@@class_variables\n and #$globals as well.'
+/instance variables can be #@included, #@@class_variables\n and #$globals as well./mousenix
+:"instance variables can be #@included, #@@class_variables\n and #$globals as well."
+:'instance variables can be #@included, #@@class_variables\n and #$globals as well.'
+%'instance variables can be #@included, #@@class_variables\n and #$globals as well.'
+%q'instance variables can be #@included, #@@class_variables\n and #$globals as well.'
+%Q'instance variables can be #@included, #@@class_variables\n and #$globals as well.'
+%w'instance variables can be #@included, #@@class_variables\n and #$globals as well.'
+%W'instance variables can be #@included, #@@class_variables\n and #$globals as well.'
+%s'instance variables can be #@included, #@@class_variables\n and #$globals as well.'
+%r'instance variables can be #@included, #@@class_variables\n and #$globals as well.'
+%x'instance variables can be #@included, #@@class_variables\n and #$globals as well.'
+
+#%W[ but #@0illegal_values look strange.]
+
+%s#ruby allows strange#{constructs}
+%s#ruby allows strange#$constructs
+%s#ruby allows strange#@@constructs
+
+##################################################################
+# HEREDOCS
+foo(<<-A, <<-B)
+this is the text of a
+A
+and this is the text of b
+B
+
+a = <<"EOF"
+This is a multiline #$here document
+terminated by EOF on a line by itself
+EOF
+
+a = <<'EOF'
+This is a multiline #$here document
+terminated by EOF on a line by itself
+EOF
+
+b=(p[x] %32)/16<1 ? 0 : 1
+
+<<""
+#{test}
+#@bla
+#die suppe!!!
+\xfffff
+
+
+super <<-EOE % [
+    foo
+EOE
+
+< [1, 2, 3, 4, 5, 6]
+p [1,2,3].`(:concat, [4,5,6]) # => [1, 2, 3, 4, 5, 6]
+p "Hurra! ".`(:*, 3) # => "Hurra! Hurra! Hurra! "
+p "Hurra! ".`('*', 3) # => "Hurra! Hurra! Hurra! "
+# Leider geht nicht die Wunschform
+# [1,2,3] `concat` [4,5,6]
+
+class Object
+  @@infixops = []
+  alias :xeq :`
+  def addinfix(operator)
+    @@infixops << operator
+  end
+  def `(expression)
+    @@infixops.each{|op|break if expression.match(/^(.*?) (#{op}) (.*)$/)}
+    raise "unknown infix operator in expression: #{expression}" if $2 == nil
+    eval($1).method($2.to_sym).call(eval($3))
+  end
+end
+addinfix("concat")
+p `[1,2,3] concat [4,5,6]` # => [1, 2, 3, 4, 5, 6]
+
+
+# HEREDOC FUN!!!!!!!1111
+foo(<
+ <% rows.each do |row| %>
+  
+   <%= item.title %>
+   <%= item.description %>
+  
+ <% end %>
+
+
+
+
    Pages
    
+
+
+  
+    
+      
+      
+      
+    
+  
+  
+<% if @homepage -%>
+<%= render_node @homepage -%>
+<% else -%>
+  
+    
+  
+<% end -%>
+  
+
    PageStatusModify
    No Pages
    
+
+
    
+  
    
+<% unless @homepage -%>
+    <%= link_to image_tag('new-homepage', :alt => 'New Homepage'), homepage_new_url %>
+<% end -%>
+    <%= image_submit_tag 'clear-page-cache' %>
+  
    
+
    

Added: external/Pygments-0.8.1/tests/run.py
==============================================================================
--- (empty file)
+++ external/Pygments-0.8.1/tests/run.py	Thu Aug  9 17:43:13 2007
@@ -0,0 +1,140 @@
+# -*- coding: utf-8 -*-
+"""
+    Pygments unit tests
+    ~~~~~~~~~~~~~~~~~~
+
+    Usage::
+
+        python run.py [testfile ...]
+
+
+    :copyright: 2006-2007 by Georg Brandl.
+    :license: GNU GPL, see LICENSE for more details.
+"""
+
+import sys, os, new
+import unittest
+import __builtin__
+
+from os.path import dirname, basename, join, abspath
+
+try:
+    import coverage
+except ImportError:
+    coverage = None
+
+testdir = abspath(dirname(__file__))
+
+# useful for all tests
+__builtin__.testdir = testdir
+
+failed = []
+total_test_count = 0
+error_test_count = 0
+
+
+def err(file, what, exc):
+    print >>sys.stderr, file, 'failed %s:' % what,
+    print >>sys.stderr, exc
+    failed.append(file[:-3])
+
+
+class QuietTestRunner(object):
+    """Customized test runner for relatively quiet output"""
+
+    def __init__(self, testname, stream=sys.stderr):
+        self.testname = testname
+        self.stream = unittest._WritelnDecorator(stream)
+
+    def run(self, test):
+        global total_test_count
+        global error_test_count
+        result = unittest._TextTestResult(self.stream, True, 1)
+        test(result)
+        if not result.wasSuccessful():
+            self.stream.write(' FAIL:')
+            result.printErrors()
+            failed.append(self.testname)
+        else:
+            self.stream.write(' ok\n')
+        total_test_count += result.testsRun
+        error_test_count += len(result.errors) + len(result.failures)
+        return result
+
+
+def run_tests(with_coverage=False):
+    # needed to avoid confusion involving atexit handlers
+    import logging
+
+    if sys.argv[1:]:
+        # test only files given on cmdline
+        files = [entry + '.py' for entry in sys.argv[1:] if entry.startswith('test_')]
+    else:
+        files = [entry for entry in os.listdir(testdir)
+                 if (entry.startswith('test_') and entry.endswith('.py'))]
+        files.sort()
+
+    WIDTH = 80
+
+    print >>sys.stderr, \
+        ('Pygments Test Suite running%s, stand by...' %
+         (with_coverage and " with coverage analysis" or "")).center(WIDTH)
+    print >>sys.stderr, ('(using Python %s)' % sys.version.split()[0]).center(WIDTH)
+    print >>sys.stderr, '='*WIDTH
+
+    if with_coverage:
+        coverage.erase()
+        coverage.start()
+
+    for testfile in files:
+        globs = {}
+        try:
+            __builtin__.testfile = testfile
+            execfile(join(testdir, testfile), globs)
+        except Exception, exc:
+            raise
+            err(testfile, 'execfile', exc)
+            continue
+        sys.stderr.write(testfile[:-3] + ': ')
+        try:
+            runner = QuietTestRunner(testfile[:-3])
+            # make a test suite of all TestCases in the file
+            tests = []
+            for name, thing in globs.iteritems():
+                if name.endswith('Test'):
+                    tests.append((name, unittest.makeSuite(thing)))
+            tests.sort()
+            suite = unittest.TestSuite()
+            suite.addTests([x[1] for x in tests])
+            runner.run(suite)
+        except Exception, exc:
+            err(testfile, 'running test', exc)
+
+    print >>sys.stderr, '='*WIDTH
+    if failed:
+        print >>sys.stderr, '%d of %d tests failed.' % \
+              (error_test_count, total_test_count)
+        print >>sys.stderr, 'Tests failed in:', ', '.join(failed)
+        ret = 1
+    else:
+        if total_test_count == 1:
+            print >>sys.stderr, '1 test happy.'
+        else:
+            print >>sys.stderr, 'All %d tests happy.' % total_test_count
+        ret = 0
+
+    if with_coverage:
+        coverage.stop()
+        modules = [mod for name, mod in sys.modules.iteritems()
+                   if name.startswith('pygments.') and mod]
+        coverage.report(modules)
+
+    return ret
+
+
+if __name__ == '__main__':
+    with_coverage = False
+    if sys.argv[1:2] == ['-C']:
+        with_coverage = bool(coverage)
+        del sys.argv[1]
+    sys.exit(run_tests(with_coverage))

Added: external/Pygments-0.8.1/tests/test_basic_api.py
==============================================================================
--- (empty file)
+++ external/Pygments-0.8.1/tests/test_basic_api.py	Thu Aug  9 17:43:13 2007
@@ -0,0 +1,187 @@
+# -*- coding: utf-8 -*-
+"""
+    Pygments basic API tests
+    ~~~~~~~~~~~~~~~~~~~~~~~~
+
+    :copyright: 2006-2007 by Georg Brandl.
+    :license: BSD, see LICENSE for more details.
+"""
+
+import os
+import unittest
+import StringIO
+import random
+
+from pygments import lexers, formatters, filters, format
+from pygments.token import _TokenType, Text
+from pygments.lexer import RegexLexer
+
+test_content = [chr(i) for i in xrange(33, 128)] * 5
+random.shuffle(test_content)
+test_content = ''.join(test_content) + '\n'
+
+class LexersTest(unittest.TestCase):
+
+    def test_import_all(self):
+        # instantiate every lexer, to see if the token type defs are correct
+        for x in lexers.LEXERS.keys():
+            c = getattr(lexers, x)()
+
+    def test_lexer_classes(self):
+        a = self.assert_
+        ae = self.assertEquals
+        # test that every lexer class has the correct public API
+        for lexer in lexers._iter_lexerclasses():
+            a(type(lexer.name) is str)
+            for attr in 'aliases', 'filenames', 'alias_filenames', 'mimetypes':
+                a(hasattr(lexer, attr))
+                a(type(getattr(lexer, attr)) is list, "%s: %s attribute wrong" %
+                                                      (lexer, attr))
+            result = lexer.analyse_text("abc")
+            a(isinstance(result, float) and 0.0 <= result <= 1.0)
+
+            if issubclass(lexer, RegexLexer):
+                if not hasattr(lexer, '_tokens'):
+                    # if there's no "_tokens", the lexer has to be one with
+                    # multiple tokendef variants
+                    a(lexer.token_variants)
+                    for variant in lexer.tokens:
+                        a('root' in lexer.tokens[variant])
+                else:
+                    a('root' in lexer._tokens, '%s has no root state' % lexer)
+
+            inst = lexer(opt1="val1", opt2="val2")
+            tokens = list(inst.get_tokens(test_content))
+            txt = ""
+            for token in tokens:
+                a(isinstance(token, tuple))
+                a(isinstance(token[0], _TokenType))
+                if isinstance(token[1], str):
+                    print repr(token[1])
+                a(isinstance(token[1], unicode))
+                txt += token[1]
+            ae(txt, test_content, "%s lexer roundtrip failed: %r != %r" %
+                    (lexer.name, test_content, txt))
+
+    def test_get_lexers(self):
+        a = self.assert_
+        ae = self.assertEquals
+        # test that the lexers functions work
+
+        for func, args in [(lexers.get_lexer_by_name, ("python",)),
+                           (lexers.get_lexer_for_filename, ("test.py",)),
+                           (lexers.get_lexer_for_mimetype, ("text/x-python",)),
+                           (lexers.guess_lexer, ("#!/usr/bin/python -O\nprint",)),
+                           (lexers.guess_lexer_for_filename, ("a.py", "<%= @foo %>"))
+                           ]:
+            x = func(opt="val", *args)
+            a(isinstance(x, lexers.PythonLexer))
+            ae(x.options["opt"], "val")
+
+
+class FiltersTest(unittest.TestCase):
+
+    def test_basic(self):
+        filter_args = {
+            'whitespace': {'spaces': True, 'tabs': True, 'newlines': True},
+            'highlight': {'names': ['isinstance', 'lexers', 'x']},
+        }
+        for x in filters.FILTERS.keys():
+            lx = lexers.PythonLexer()
+            lx.add_filter(x, **filter_args.get(x, {}))
+            text = file(os.path.join(testdir, testfile)).read().decode('utf-8')
+            tokens = list(lx.get_tokens(text))
+            roundtext = ''.join([t[1] for t in tokens])
+            if x not in ('whitespace', 'keywordcase'):
+                # these filters change the text
+                self.assertEquals(roundtext, text,
+                                  "lexer roundtrip with %s filter failed" % x)
+
+    def test_raiseonerror(self):
+        lx = lexers.PythonLexer()
+        lx.add_filter('raiseonerror', excclass=RuntimeError)
+        self.assertRaises(RuntimeError, list, lx.get_tokens('$'))
+
+    def test_whitespace(self):
+        lx = lexers.PythonLexer()
+        lx.add_filter('whitespace', spaces='%')
+        text = file(os.path.join(testdir, testfile)).read().decode('utf-8')
+        lxtext = ''.join([t[1] for t in list(lx.get_tokens(text))])
+        self.failIf(' ' in lxtext)
+
+    def test_keywordcase(self):
+        lx = lexers.PythonLexer()
+        lx.add_filter('keywordcase', case='capitalize')
+        text = file(os.path.join(testdir, testfile)).read().decode('utf-8')
+        lxtext = ''.join([t[1] for t in list(lx.get_tokens(text))])
+        self.assert_('Def' in lxtext and 'Class' in lxtext)
+
+
+class FormattersTest(unittest.TestCase):
+
+    def test_public_api(self):
+        a = self.assert_
+        ae = self.assertEquals
+        ts = list(lexers.PythonLexer().get_tokens("def f(): pass"))
+        out = StringIO.StringIO()
+        # test that every formatter class has the correct public API
+        for formatter, info in formatters.FORMATTERS.iteritems():
+            a(len(info) == 4)
+            a(info[0], "missing formatter name") # name
+            a(info[1], "missing formatter aliases") # aliases
+            a(info[3], "missing formatter docstring") # doc
+
+            inst = formatter(opt1="val1")
+            inst.get_style_defs()
+            inst.format(ts, out)
+
+    def test_encodings(self):
+        from pygments.formatters import HtmlFormatter
+
+        # unicode output
+        fmt = HtmlFormatter()
+        tokens = [(Text, u"??")]
+        out = format(tokens, fmt)
+        self.assert_(type(out) is unicode)
+        self.assert_(u"??" in out)
+
+        # encoding option
+        fmt = HtmlFormatter(encoding="latin1")
+        tokens = [(Text, u"??")]
+        self.assert_(u"??".encode("latin1") in format(tokens, fmt))
+
+        # encoding and outencoding option
+        fmt = HtmlFormatter(encoding="latin1", outencoding="utf8")
+        tokens = [(Text, u"??")]
+        self.assert_(u"??".encode("utf8") in format(tokens, fmt))
+
+    def test_styles(self):
+        from pygments.formatters import HtmlFormatter
+        fmt = HtmlFormatter(style="pastie")
+
+    def test_unicode_handling(self):
+        # test that the formatter supports encoding and Unicode
+        tokens = list(lexers.PythonLexer(encoding='utf-8').get_tokens("def f(): '??'"))
+        for formatter, info in formatters.FORMATTERS.iteritems():
+            inst = formatter(encoding=None)
+            out = format(tokens, inst)
+            if formatter.unicodeoutput:
+                self.assert_(type(out) is unicode)
+
+            inst = formatter(encoding='utf-8')
+            out = format(tokens, inst)
+            self.assert_(type(out) is str)
+            # Cannot test for encoding, since formatters may have to escape
+            # non-ASCII characters.
+
+    def test_get_formatters(self):
+        a = self.assert_
+        ae = self.assertEquals
+        # test that the formatters functions work
+        x = formatters.get_formatter_by_name("html", opt="val")
+        a(isinstance(x, formatters.HtmlFormatter))
+        ae(x.options["opt"], "val")
+
+        x = formatters.get_formatter_for_filename("a.html", opt="val")
+        a(isinstance(x, formatters.HtmlFormatter))
+        ae(x.options["opt"], "val")

Added: external/Pygments-0.8.1/tests/test_clexer.py
==============================================================================
--- (empty file)
+++ external/Pygments-0.8.1/tests/test_clexer.py	Thu Aug  9 17:43:13 2007
@@ -0,0 +1,35 @@
+# -*- coding: utf-8 -*-
+"""
+    Basic CLexer Test
+    ~~~~~~~~~~~~~~~~~
+
+    :copyright: 2006-2007 by Armin Ronacher.
+    :license: BSD, see LICENSE for more details.
+"""
+
+import unittest
+import os
+
+from pygments.token import Text, Number
+from pygments.lexers import CLexer
+
+
+class CLexerTest(unittest.TestCase):
+
+    def setUp(self):
+        self.lexer = CLexer()
+
+    def testNumbers(self):
+        code = '42 23.42 23. .42 023 0xdeadbeef 23e+42 42e-23'
+        wanted = []
+        for item in zip([Number.Integer, Number.Float, Number.Float,
+                         Number.Float, Number.Oct, Number.Hex,
+                         Number.Float, Number.Float], code.split()):
+            wanted.append(item)
+            wanted.append((Text, ' '))
+        wanted = [(Text, '')] + wanted[:-1] + [(Text, '\n')]
+        self.assertEqual(list(self.lexer.get_tokens(code)), wanted)
+
+
+if __name__ == '__main__':
+    unittest.main()

Added: external/Pygments-0.8.1/tests/test_cmdline.py
==============================================================================
--- (empty file)
+++ external/Pygments-0.8.1/tests/test_cmdline.py	Thu Aug  9 17:43:13 2007
@@ -0,0 +1,92 @@
+# -*- coding: utf-8 -*-
+"""
+    Command line test
+    ~~~~~~~~~~~~~~~~~
+
+    :copyright: 2006-2007 by Georg Brandl.
+    :license: BSD, see LICENSE for more details.
+"""
+
+# Test the command line interface
+
+import sys, os
+import unittest
+import StringIO
+
+from pygments import highlight
+from pygments.cmdline import main as cmdline_main
+
+
+def run_cmdline(*args):
+    saved_stdout = sys.stdout
+    saved_stderr = sys.stderr
+    new_stdout = sys.stdout = StringIO.StringIO()
+    new_stderr = sys.stderr = StringIO.StringIO()
+    try:
+        ret = cmdline_main(["pygmentize"] + list(args))
+    finally:
+        sys.stdout = saved_stdout
+        sys.stderr = saved_stderr
+    return (ret, new_stdout.getvalue(), new_stderr.getvalue())
+
+
+class CmdLineTest(unittest.TestCase):
+
+    def test_L_opt(self):
+        c, o, e = run_cmdline("-L")
+        self.assertEquals(c, 0)
+        self.assert_("Lexers" in o and "Formatters" in o and
+                     "Filters" in o and "Styles" in o)
+        c, o, e = run_cmdline("-L", "lexer")
+        self.assertEquals(c, 0)
+        self.assert_("Lexers" in o and "Formatters" not in o)
+        c, o, e = run_cmdline("-L", "lexers")
+        self.assertEquals(c, 0)
+
+    def test_O_opt(self):
+        filename = os.path.join(testdir, testfile)
+        c, o, e = run_cmdline("-Ofull=1,linenos=true,foo=bar", "-fhtml", filename)
+        self.assertEquals(c, 0)
+        self.assert_("', '', houtfile.getvalue())
+        escaped_text = escape_html(noutfile.getvalue())
+        self.assertEquals(stripped_html, escaped_text)
+
+    def test_external_css(self):
+        # test correct behavior
+        # CSS should be in /tmp directory
+        fmt1 = HtmlFormatter(full=True, cssfile='fmt1.css')
+        # CSS should be in testdir (testdir is absolute)
+        fmt2 = HtmlFormatter(full=True, cssfile=join(testdir, 'fmt2.css'))
+        tfile = tempfile.NamedTemporaryFile(suffix='.html')
+        fmt1.format(tokensource, tfile)
+        try:
+            fmt2.format(tokensource, tfile)
+            self.assert_(isfile(join(testdir, 'fmt2.css')))
+        except IOError:
+            # test directory not writable
+            pass
+        tfile.close()
+
+        self.assert_(isfile(join(dirname(tfile.name), 'fmt1.css')))
+        os.unlink(join(dirname(tfile.name), 'fmt1.css'))
+        try:
+            os.unlink(join(testdir, 'fmt2.css'))
+        except OSError:
+            pass
+
+    def test_all_options(self):
+        for optdict in [dict(nowrap=True),
+                        dict(linenos=True),
+                        dict(linenos=True, full=True),
+                        dict(linenos=True, full=True, noclasses=True)]:
+
+            outfile = StringIO.StringIO()
+            fmt = HtmlFormatter(**optdict)
+            fmt.format(tokensource, outfile)
+
+    def test_valid_output(self):
+        # test all available wrappers
+        fmt = HtmlFormatter(full=True, linenos=True, noclasses=True)
+
+        handle, pathname = tempfile.mkstemp('.html')
+        tfile = os.fdopen(handle, 'w+b')
+        fmt.format(tokensource, tfile)
+        tfile.close()
+        catname = os.path.join(testdir, 'dtds', 'HTML4.soc')
+        try:
+            try:
+                import subprocess
+                ret = subprocess.Popen(['nsgmls', '-s', '-c', catname, pathname],
+                                       stdout=subprocess.PIPE).wait()
+            except ImportError:
+                # Python 2.3 - no subprocess module
+                ret = os.popen('nsgmls -s -c "%s" "%s"' % (catname, pathname)).close()
+                if ret == 32512: raise OSError  # not found
+        except OSError:
+            # latex not available
+            pass
+        else:
+            self.failIf(ret, 'nsgmls run reported errors')
+
+        os.unlink(pathname)
+
+    def test_get_style_defs(self):
+        fmt = HtmlFormatter()
+        sd = fmt.get_style_defs()
+        self.assert_(sd.startswith('.'))
+
+        fmt = HtmlFormatter(cssclass='foo')
+        sd = fmt.get_style_defs()
+        self.assert_(sd.startswith('.foo'))
+        sd = fmt.get_style_defs('.bar')
+        self.assert_(sd.startswith('.bar'))
+        sd = fmt.get_style_defs(['.bar', '.baz'])
+        fl = sd.splitlines()[0]
+        self.assert_('.bar' in fl and '.baz' in fl)

Added: external/Pygments-0.8.1/tests/test_latex_formatter.py
==============================================================================
--- (empty file)
+++ external/Pygments-0.8.1/tests/test_latex_formatter.py	Thu Aug  9 17:43:13 2007
@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+"""
+    Pygments LaTeX formatter tests
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    :copyright: 2006-2007 by Georg Brandl.
+    :license: BSD, see LICENSE for more details.
+"""
+
+import os
+import unittest
+import tempfile
+
+from pygments.formatters import LatexFormatter
+from pygments.lexers import PythonLexer
+
+
+class LatexFormatterTest(unittest.TestCase):
+
+    def test_valid_output(self):
+        tokensource = list(PythonLexer().get_tokens(file(
+            os.path.join(testdir, testfile)).read()))
+        fmt = LatexFormatter(full=True)
+
+        handle, pathname = tempfile.mkstemp('.tex')
+        # place all output files in /tmp too
+        old_wd = os.getcwd()
+        os.chdir(os.path.dirname(pathname))
+        tfile = os.fdopen(handle, 'w+b')
+        fmt.format(tokensource, tfile)
+        tfile.close()
+        try:
+            try:
+                import subprocess
+                ret = subprocess.Popen(['latex', '-interaction=nonstopmode', pathname],
+                                       stdout=subprocess.PIPE).wait()
+            except ImportError:
+                # Python 2.3 - no subprocess module
+                ret = os.popen('latex -interaction=nonstopmode "%s"' % pathname).close()
+                if ret == 32512: raise OSError  # not found
+        except OSError:
+            # latex not available
+            pass
+        else:
+            self.failIf(ret, 'latex run reported errors')
+
+        os.unlink(pathname)
+        os.chdir(old_wd)

Added: external/Pygments-0.8.1/tests/test_token.py
==============================================================================
--- (empty file)
+++ external/Pygments-0.8.1/tests/test_token.py	Thu Aug  9 17:43:13 2007
@@ -0,0 +1,51 @@
+# -*- coding: utf-8 -*-
+"""
+    Test suite for the token module
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    :copyright: 2006-2007 by Georg Brandl.
+    :license: BSD, see LICENSE for more details.
+"""
+
+import unittest
+import StringIO
+import sys
+
+from pygments import token
+
+
+class TokenTest(unittest.TestCase):
+
+    def test_tokentype(self):
+        e = self.assertEquals
+        r = self.assertRaises
+
+        t = token.String
+
+        e(t.split(), [token.Token, token.Literal, token.String])
+
+        e(t.__class__, token._TokenType)
+
+    def test_functions(self):
+        self.assert_(token.is_token_subtype(token.String, token.String))
+        self.assert_(token.is_token_subtype(token.String, token.Literal))
+        self.failIf(token.is_token_subtype(token.Literal, token.String))
+
+        self.assert_(token.string_to_tokentype(token.String) is token.String)
+        self.assert_(token.string_to_tokentype('') is token.Token)
+        self.assert_(token.string_to_tokentype('String') is token.String)
+
+    def test_sanity_check(self):
+        try:
+            try:
+                old_stdout = sys.stdout
+                sys.stdout = StringIO.StringIO()
+                execfile(token.__file__.rstrip('c'), {'__name__': '__main__'})
+            finally:
+                sys.stdout = old_stdout
+        except SystemExit:
+            pass
+
+
+if __name__ == '__main__':
+    unittest.main()

Added: external/Pygments-0.8.1/tests/test_using_api.py
==============================================================================
--- (empty file)
+++ external/Pygments-0.8.1/tests/test_using_api.py	Thu Aug  9 17:43:13 2007
@@ -0,0 +1,31 @@
+import unittest
+from pygments.lexer import using, bygroups, this, RegexLexer
+from pygments.token import String, Text, Keyword
+
+class TestLexer(RegexLexer):
+    tokens = {
+        'root': [
+            (r'#.*', using(this, state='invalid')),
+            (r'(")(.+?)(")', bygroups(String, using(this, state='string'), String)),
+            (r'[^"]+', Text),
+        ],
+        'string': [
+            (r'.+', Keyword),
+        ],
+    }
+
+class UsingStateTest(unittest.TestCase):
+    def test_basic(self):
+        expected = [(Text, 'a'), (String, '"'), (Keyword, 'bcd'),
+                    (String, '"'), (Text, 'e\n')]
+        t = list(TestLexer().get_tokens('a"bcd"e'))
+        self.assertEquals(t, expected)
+    def test_error(self):
+        def gen():
+            x = list(TestLexer().get_tokens('#a'))
+        #XXX: should probably raise a more specific exception if the state
+        #     doesn't exist.
+        self.assertRaises(Exception, gen)
+
+if __name__ == "__main__":
+    unittest.main()

Added: external/Pygments-0.8.1/tests/test_util.py
==============================================================================
--- (empty file)
+++ external/Pygments-0.8.1/tests/test_util.py	Thu Aug  9 17:43:13 2007
@@ -0,0 +1,90 @@
+# -*- coding: utf-8 -*-
+"""
+    Test suite for the util module
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    :copyright: 2006-2007 by Georg Brandl.
+    :license: BSD, see LICENSE for more details.
+"""
+
+import unittest
+import os
+
+from pygments import util
+
+
+class UtilTest(unittest.TestCase):
+
+    def test_getoptions(self):
+        raises = self.assertRaises
+        equals = self.assertEquals
+
+        equals(util.get_bool_opt({}, 'a', True), True)
+        equals(util.get_bool_opt({}, 'a', 1), True)
+        equals(util.get_bool_opt({}, 'a', 'true'), True)
+        equals(util.get_bool_opt({}, 'a', 'no'), False)
+        raises(util.OptionError, util.get_bool_opt, {}, 'a', [])
+        raises(util.OptionError, util.get_bool_opt, {}, 'a', 'foo')
+
+        equals(util.get_int_opt({}, 'a', 1), 1)
+        raises(util.OptionError, util.get_int_opt, {}, 'a', [])
+        raises(util.OptionError, util.get_int_opt, {}, 'a', 'bar')
+
+        equals(util.get_list_opt({}, 'a', [1]), [1])
+        equals(util.get_list_opt({}, 'a', '1 2'), ['1', '2'])
+        raises(util.OptionError, util.get_list_opt, {}, 'a', 1)
+
+
+    def test_docstring_headline(self):
+        def f1():
+            """
+            docstring headline
+
+            other text
+            """
+        def f2():
+            """
+            docstring
+            headline
+
+            other text
+            """
+
+        self.assertEquals(util.docstring_headline(f1), "docstring headline")
+        self.assertEquals(util.docstring_headline(f2), "docstring headline")
+
+    def test_analysator(self):
+        class X(object):
+            def analyse(text):
+                return 0.5
+            analyse = util.make_analysator(analyse)
+        self.assertEquals(X.analyse(''), 0.5)
+
+    def test_shebang_matches(self):
+        self.assert_(util.shebang_matches('#!/usr/bin/env python', r'python(2\.\d)?'))
+        self.assert_(util.shebang_matches('#!/usr/bin/python2.4', r'python(2\.\d)?'))
+        self.assert_(util.shebang_matches('#!/usr/bin/startsomethingwith python',
+                                          r'python(2\.\d)?'))
+        self.assert_(util.shebang_matches('#!C:\\Python2.4\\Python.exe',
+                                          r'python(2\.\d)?'))
+
+        self.failIf(util.shebang_matches('#!/usr/bin/python-ruby', r'python(2\.\d)?'))
+        self.failIf(util.shebang_matches('#!/usr/bin/python/ruby', r'python(2\.\d)?'))
+        self.failIf(util.shebang_matches('#!', r'python'))
+
+    def test_doctype_matches(self):
+        self.assert_(util.doctype_matches(' ',
+                                          'html.*'))
+        self.failIf(util.doctype_matches('  ',
+                                         'html.*'))
+        self.assert_(util.html_doctype_matches(
+            ''))
+
+    def test_xml(self):
+        self.assert_(util.looks_like_xml(
+            ''))
+        self.assert_(util.looks_like_xml('abc'))
+        self.failIf(util.looks_like_xml(''))
+
+if __name__ == '__main__':
+    unittest.main()

From python-checkins at python.org  Thu Aug  9 17:46:07 2007
From: python-checkins at python.org (georg.brandl)
Date: Thu,  9 Aug 2007 17:46:07 +0200 (CEST)
Subject: [Python-checkins] r56856 - in doctools/trunk: Doc-26
	Doc-26/Makefile Doc-26/tools Doc-26/tools/sphinx-build.py
	Doc-26/tools/sphinx-web.py Doc-26/tutorial/modules.rst Doc-3k
	Doc-3k/Makefile Doc-3k/tools Doc-3k/tools/sphinx-build.py
	Doc-3k/tools/sphinx-web.py Doc-3k/tutorial/modules.rst
Message-ID: <20070809154607.D33861E400D@bag.python.org>

Author: georg.brandl
Date: Thu Aug  9 17:46:06 2007
New Revision: 56856

Added:
   doctools/trunk/Doc-26/Makefile
   doctools/trunk/Doc-26/tools/sphinx-build.py
   doctools/trunk/Doc-26/tools/sphinx-web.py
   doctools/trunk/Doc-3k/Makefile
   doctools/trunk/Doc-3k/tools/sphinx-build.py
   doctools/trunk/Doc-3k/tools/sphinx-web.py
Modified:
   doctools/trunk/Doc-26/   (props changed)
   doctools/trunk/Doc-26/tools/   (props changed)
   doctools/trunk/Doc-26/tutorial/modules.rst
   doctools/trunk/Doc-3k/   (props changed)
   doctools/trunk/Doc-3k/tools/   (props changed)
   doctools/trunk/Doc-3k/tutorial/modules.rst
Log:
Add a Makefile to the Doc trees.


Added: doctools/trunk/Doc-26/Makefile
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-26/Makefile	Thu Aug  9 17:46:06 2007
@@ -0,0 +1,55 @@
+#
+# Makefile for Python documentation
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+
+PYTHON  = python
+SVNROOT = http://svn.python.org/projects
+
+.PHONY: default checkout html web htmlhelp clean
+
+default:
+	@echo "Please use \`make ' where  is one of"
+	@echo "  html  to make standalone HTML files"
+	@echo "  web   to make file usable by Sphinx.web"
+	@echo "  htmlhelp to make HTML files and a HTML help project"
+
+checkout:
+	@if [ ! -d tools/sphinx ]; then \
+	  echo "Checking out Sphinx..."; \
+	  svn checkout $(SVNROOT)/doctools/trunk/sphinx tools/sphinx; \
+	  echo "Checking out Pygments..."; \
+	  svn checkout $(SVNROOT)/external/Pygments-0.8.1/pygments tools/pygments; \
+	else \
+	  echo "Sphinx already checked out, run \`make update' to update" \
+	       "the toolchain."; \
+	fi
+
+update:
+	svn update tools/sphinx
+	svn update tools/pygments
+
+html: checkout
+	mkdir -p build/html build/doctrees
+	$(PYTHON) tools/sphinx-build.py -bhtml -dbuild/doctrees . build/html
+	@echo
+	@echo "Build finished. The HTML pages are in build/html."
+
+web: checkout
+	mkdir -p build/web build/doctrees
+	$(PYTHON) tools/sphinx-build.py -bweb -dbuild/doctrees . build/web
+	@echo
+	@echo "Build finished; now you can run"
+	@echo "  PYTHONPATH=tools $(PYTHON) -m sphinx.web build/web"
+	@echo "to start the server."
+
+htmlhelp: checkout
+	mkdir -p build/hhp build/doctrees
+	$(PYTHON) tools/sphinx-build.py -bhtmlhelp -dbuild/doctrees . build/hhp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      "build/hhp/pydoc.hhp project file."
+
+clean:
+	-rm -rf build/*
+	-rm -rf tools/sphinx

Added: doctools/trunk/Doc-26/tools/sphinx-build.py
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-26/tools/sphinx-build.py	Thu Aug  9 17:46:06 2007
@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+"""
+    Sphinx - Python documentation toolchain
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    :copyright: 2007 by Georg Brandl.
+    :license: Python license.
+"""
+
+import sys
+
+if __name__ == '__main__':
+    from sphinx import main
+    sys.exit(main(sys.argv))

Added: doctools/trunk/Doc-26/tools/sphinx-web.py
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-26/tools/sphinx-web.py	Thu Aug  9 17:46:06 2007
@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+"""
+    Sphinx - Python documentation webserver
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    :copyright: 2007 by Georg Brandl.
+    :license: Python license.
+"""
+
+import sys
+
+if __name__ == '__main__':
+    from sphinx.web import main
+    sys.exit(main(sys.argv))

Modified: doctools/trunk/Doc-26/tutorial/modules.rst
==============================================================================
--- doctools/trunk/Doc-26/tutorial/modules.rst	(original)
+++ doctools/trunk/Doc-26/tutorial/modules.rst	Thu Aug  9 17:46:06 2007
@@ -510,10 +510,10 @@
 statement looks for a top-level module with the given name.
 
 When packages are structured into subpackages (as with the :mod:`sound` package
-in the example), there's no shortcut to refer to submodules of sibling packages
-- the full name of the subpackage must be used.  For example, if the module
-:mod:`sound.filters.vocoder` needs to use the :mod:`echo` module in the
-:mod:`sound.effects` package, it can use ``from sound.effects import echo``.
+in the example), you can use absolute imports to refer to submodules of siblings
+packages.  For example, if the module :mod:`sound.filters.vocoder` needs to use
+the :mod:`echo` module in the :mod:`sound.effects` package, it can use ``from
+sound.effects import echo``.
 
 Starting with Python 2.5, in addition to the implicit relative imports described
 above, you can write explicit relative imports with the ``from module import

Added: doctools/trunk/Doc-3k/Makefile
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-3k/Makefile	Thu Aug  9 17:46:06 2007
@@ -0,0 +1,55 @@
+#
+# Makefile for Python documentation
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+
+PYTHON  = python
+SVNROOT = http://svn.python.org/projects
+
+.PHONY: default checkout html web htmlhelp clean
+
+default:
+	@echo "Please use \`make ' where  is one of"
+	@echo "  html  to make standalone HTML files"
+	@echo "  web   to make file usable by Sphinx.web"
+	@echo "  htmlhelp to make HTML files and a HTML help project"
+
+checkout:
+	@if [ ! -d tools/sphinx ]; then \
+	  echo "Checking out Sphinx..."; \
+	  svn checkout $(SVNROOT)/doctools/trunk/sphinx tools/sphinx; \
+	  echo "Checking out Pygments..."; \
+	  svn checkout $(SVNROOT)/external/Pygments-0.8.1/pygments tools/pygments; \
+	else \
+	  echo "Sphinx already checked out, run \`make update' to update" \
+	       "the toolchain."; \
+	fi
+
+update:
+	svn update tools/sphinx
+	svn update tools/pygments
+
+html: checkout
+	mkdir -p build/html build/doctrees
+	$(PYTHON) tools/sphinx-build.py -bhtml -dbuild/doctrees . build/html
+	@echo
+	@echo "Build finished. The HTML pages are in build/html."
+
+web: checkout
+	mkdir -p build/web build/doctrees
+	$(PYTHON) tools/sphinx-build.py -bweb -dbuild/doctrees . build/web
+	@echo
+	@echo "Build finished; now you can run"
+	@echo "  PYTHONPATH=tools $(PYTHON) -m sphinx.web build/web"
+	@echo "to start the server."
+
+htmlhelp: checkout
+	mkdir -p build/hhp build/doctrees
+	$(PYTHON) tools/sphinx-build.py -bhtmlhelp -dbuild/doctrees . build/hhp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      "build/hhp/pydoc.hhp project file."
+
+clean:
+	-rm -rf build/*
+	-rm -rf tools/sphinx

Added: doctools/trunk/Doc-3k/tools/sphinx-build.py
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-3k/tools/sphinx-build.py	Thu Aug  9 17:46:06 2007
@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+"""
+    Sphinx - Python documentation toolchain
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    :copyright: 2007 by Georg Brandl.
+    :license: Python license.
+"""
+
+import sys
+
+if __name__ == '__main__':
+    from sphinx import main
+    sys.exit(main(sys.argv))

Added: doctools/trunk/Doc-3k/tools/sphinx-web.py
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-3k/tools/sphinx-web.py	Thu Aug  9 17:46:06 2007
@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+"""
+    Sphinx - Python documentation webserver
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    :copyright: 2007 by Georg Brandl.
+    :license: Python license.
+"""
+
+import sys
+
+if __name__ == '__main__':
+    from sphinx.web import main
+    sys.exit(main(sys.argv))

Modified: doctools/trunk/Doc-3k/tutorial/modules.rst
==============================================================================
--- doctools/trunk/Doc-3k/tutorial/modules.rst	(original)
+++ doctools/trunk/Doc-3k/tutorial/modules.rst	Thu Aug  9 17:46:06 2007
@@ -510,10 +510,10 @@
 statement looks for a top-level module with the given name.
 
 When packages are structured into subpackages (as with the :mod:`sound` package
-in the example), there's no shortcut to refer to submodules of sibling packages
-- the full name of the subpackage must be used.  For example, if the module
-:mod:`sound.filters.vocoder` needs to use the :mod:`echo` module in the
-:mod:`sound.effects` package, it can use ``from sound.effects import echo``.
+in the example), you can use absolute imports to refer to submodules of siblings
+packages.  For example, if the module :mod:`sound.filters.vocoder` needs to use
+the :mod:`echo` module in the :mod:`sound.effects` package, it can use ``from
+sound.effects import echo``.
 
 Starting with Python 2.5, in addition to the implicit relative imports described
 above, you can write explicit relative imports with the ``from module import

From python-checkins at python.org  Thu Aug  9 17:52:19 2007
From: python-checkins at python.org (georg.brandl)
Date: Thu,  9 Aug 2007 17:52:19 +0200 (CEST)
Subject: [Python-checkins] r56857 - in external/docutils-0.4: BUGS.txt
	COPYING.txt FAQ.txt HISTORY.txt PKG-INFO README.txt
	RELEASE-NOTES.txt THANKS.txt docs docs/api
	docs/api/cmdline-tool.txt docs/api/publisher.txt
	docs/api/runtime-settings.txt docs/dev
	docs/dev/distributing.txt docs/dev/enthought-plan.txt
	docs/dev/enthought-rfp.txt docs/dev/hacking.txt
	docs/dev/policies.txt docs/dev/pysource.dtd
	docs/dev/pysource.txt docs/dev/release.txt
	docs/dev/repository.txt docs/dev/rst
	docs/dev/rst/alternatives.txt docs/dev/rst/problems.txt
	docs/dev/semantics.txt docs/dev/testing.txt docs/dev/todo.txt
	docs/dev/website.txt docs/howto
	docs/howto/html-stylesheets.txt docs/howto/i18n.txt
	docs/howto/rst-directives.txt docs/howto/rst-roles.txt
	docs/index.txt docs/peps docs/peps/pep-0256.txt
	docs/peps/pep-0257.txt docs/peps/pep-0258.txt
	docs/peps/pep-0287.txt docs/ref docs/ref/doctree.txt
	docs/ref/docutils.dtd docs/ref/rst
	docs/ref/rst/definitions.txt docs/ref/rst/directives.txt
	docs/ref/rst/introduction.txt
	docs/ref/rst/restructuredtext.txt docs/ref/rst/roles.txt
	docs/ref/soextblx.dtd docs/ref/transforms.txt docs/user
	docs/user/Makefile.docutils-update docs/user/config.txt
	docs/user/emacs.txt docs/user/images
	docs/user/images/big-black.png docs/user/images/big-white.png
	docs/user/images/default.png docs/user/images/happy_monkey.png
	docs/user/images/medium-black.png docs/user/images/medium-white.png
	docs/user/images/rsp-all.png docs/user/images/rsp-breaks.png
	docs/user/images/rsp-covers.png docs/user/images/rsp-cuts.png
	docs/user/images/rsp-empty.png
	docs/user/images/rsp-objects.png docs/user/images/rsp.svg
	docs/user/images/s5-files.png docs/user/images/s5-files.svg
	docs/user/images/small-black.png
	docs/user/images/small-white.png docs/user/latex.txt
	docs/user/links.txt docs/user/mailing-lists.txt docs/user/rst
	docs/user/rst/cheatsheet.txt docs/user/rst/demo.txt
	docs/user/rst/images docs/user/rst/images/ball1.gif
	docs/user/rst/images/biohazard.png
	docs/user/rst/images/title.png docs/user/rst/quickref.html
	docs/user/rst/quickstart.txt docs/user/slide-shows.txt
	docs/user/tools.txt docutils docutils/__init__.py
	docutils/core.py docutils/docutils.conf docutils/examples.py
	docutils/frontend.py docutils/io.py docutils/languages
	docutils/languages/__init__.py docutils/languages/af.py
	docutils/languages/ca.py docutils/languages/cs.py
	docutils/languages/de.py docutils/languages/en.py
	docutils/languages/eo.py docutils/languages/es.py
	docutils/languages/fi.py docutils/languages/fr.py
	docutils/languages/it.py docutils/languages/ja.py
	docutils/languages/nl.py docutils/languages/pt_br.py
	docutils/languages/ru.py docutils/languages/sk.py
	docutils/languages/sv.py docutils/languages/zh_cn.py
	docutils/languages/zh_tw.py docutils/nodes.py
	docutils/parsers docutils/parsers/__init__.py
	docutils/parsers/null.py docutils/parsers/rst
	docutils/parsers/rst/__init__.py docutils/parsers/rst/directives
	docutils/parsers/rst/directives/__init__.py
	docutils/parsers/rst/directives/admonitions.py
	docutils/parsers/rst/directives/body.py
	docutils/parsers/rst/directives/html.py
	docutils/parsers/rst/directives/images.py
	docutils/parsers/rst/directives/misc.py
	docutils/parsers/rst/directives/parts.py
	docutils/parsers/rst/directives/references.py
	docutils/parsers/rst/directives/tables.py
	docutils/parsers/rst/include docutils/parsers/rst/include/README.txt
	docutils/parsers/rst/include/isoamsa.txt
	docutils/parsers/rst/include/isoamsb.txt
	docutils/parsers/rst/include/isoamsc.txt
	docutils/parsers/rst/include/isoamsn.txt
	docutils/parsers/rst/include/isoamso.txt
	docutils/parsers/rst/include/isoamsr.txt
	docutils/parsers/rst/include/isobox.txt
	docutils/parsers/rst/include/isocyr1.txt
	docutils/parsers/rst/include/isocyr2.txt
	docutils/parsers/rst/include/isodia.txt
	docutils/parsers/rst/include/isogrk1.txt
	docutils/parsers/rst/include/isogrk2.txt
	docutils/parsers/rst/include/isogrk3.txt
	docutils/parsers/rst/include/isogrk4-wide.txt
	docutils/parsers/rst/include/isogrk4.txt
	docutils/parsers/rst/include/isolat1.txt
	docutils/parsers/rst/include/isolat2.txt
	docutils/parsers/rst/include/isomfrk-wide.txt
	docutils/parsers/rst/include/isomfrk.txt
	docutils/parsers/rst/include/isomopf-wide.txt
	docutils/parsers/rst/include/isomopf.txt
	docutils/parsers/rst/include/isomscr-wide.txt
	docutils/parsers/rst/include/isomscr.txt
	docutils/parsers/rst/include/isonum.txt
	docutils/parsers/rst/include/isopub.txt
	docutils/parsers/rst/include/isotech.txt
	docutils/parsers/rst/include/mmlalias.txt
	docutils/parsers/rst/include/mmlextra-wide.txt
	docutils/parsers/rst/include/mmlextra.txt
	docutils/parsers/rst/include/s5defs.txt
	docutils/parsers/rst/include/xhtml1-lat1.txt
	docutils/parsers/rst/include/xhtml1-special.txt
	docutils/parsers/rst/include/xhtml1-symbol.txt
	docutils/parsers/rst/languages
	docutils/parsers/rst/languages/__init__.py
	docutils/parsers/rst/languages/af.py
	docutils/parsers/rst/languages/ca.py
	docutils/parsers/rst/languages/cs.py
	docutils/parsers/rst/languages/de.py
	docutils/parsers/rst/languages/en.py
	docutils/parsers/rst/languages/eo.py
	docutils/parsers/rst/languages/es.py
	docutils/parsers/rst/languages/fi.py
	docutils/parsers/rst/languages/fr.py
	docutils/parsers/rst/languages/it.py
	docutils/parsers/rst/languages/ja.py
	docutils/parsers/rst/languages/nl.py
	docutils/parsers/rst/languages/pt_br.py
	docutils/parsers/rst/languages/ru.py
	docutils/parsers/rst/languages/sk.py
	docutils/parsers/rst/languages/sv.py
	docutils/parsers/rst/languages/zh_cn.py
	docutils/parsers/rst/languages/zh_tw.py
	docutils/parsers/rst/roles.py docutils/parsers/rst/states.py
	docutils/parsers/rst/tableparser.py docutils/readers
	docutils/readers/__init__.py docutils/readers/doctree.py
	docutils/readers/pep.py docutils/readers/python
	docutils/readers/python/__init__.py
	docutils/readers/python/moduleparser.py
	docutils/readers/python/pynodes.py
	docutils/readers/standalone.py docutils/statemachine.py
	docutils/transforms docutils/transforms/__init__.py
	docutils/transforms/components.py docutils/transforms/frontmatter.py
	docutils/transforms/misc.py docutils/transforms/parts.py
	docutils/transforms/peps.py docutils/transforms/references.py
	docutils/transforms/universal.py
	docutils/transforms/writer_aux.py docutils/urischemes.py
	docutils/utils.py docutils/writers
	docutils/writers/__init__.py docutils/writers/docutils_xml.py
	docutils/writers/html4css1 docutils/writers/html4css1/__init__.py
	docutils/writers/html4css1/html4css1.css
	docutils/writers/latex2e docutils/writers/latex2e/__init__.py
	docutils/writers/latex2e/latex2e.tex docutils/writers/newlatex2e
	docutils/writers/newlatex2e/__init__.py
	docutils/writers/newlatex2e/base.tex
	docutils/writers/newlatex2e/unicode_map.py
	docutils/writers/null.py docutils/writers/pep_html
	docutils/writers/pep_html/__init__.py
	docutils/writers/pep_html/pep.css
	docutils/writers/pep_html/template.txt
	docutils/writers/pseudoxml.py docutils/writers/s5_html
	docutils/writers/s5_html/__init__.py docutils/writers/s5_html/themes
	docutils/writers/s5_html/themes/README.txt
	docutils/writers/s5_html/themes/big-black
	docutils/writers/s5_html/themes/big-black/__base__
	docutils/writers/s5_html/themes/big-black/framing.css
	docutils/writers/s5_html/themes/big-black/pretty.css
	docutils/writers/s5_html/themes/big-white
	docutils/writers/s5_html/themes/big-white/framing.css
	docutils/writers/s5_html/themes/big-white/pretty.css
	docutils/writers/s5_html/themes/default
	docutils/writers/s5_html/themes/default/blank.gif
	docutils/writers/s5_html/themes/default/framing.css
	docutils/writers/s5_html/themes/default/iepngfix.htc
	docutils/writers/s5_html/themes/default/opera.css
	docutils/writers/s5_html/themes/default/outline.css
	docutils/writers/s5_html/themes/default/pretty.css
	docutils/writers/s5_html/themes/default/print.css
	docutils/writers/s5_html/themes/default/s5-core.css
	docutils/writers/s5_html/themes/default/slides.css
	docutils/writers/s5_html/themes/default/slides.js
	docutils/writers/s5_html/themes/medium-black
	docutils/writers/s5_html/themes/medium-black/__base__
	docutils/writers/s5_html/themes/medium-black/pretty.css
	docutils/writers/s5_html/themes/medium-white
	docutils/writers/s5_html/themes/medium-white/framing.css
	docutils/writers/s5_html/themes/medium-white/pretty.css
	docutils/writers/s5_html/themes/small-black
	docutils/writers/s5_html/themes/small-black/__base__
	docutils/writers/s5_html/themes/small-black/pretty.css
	docutils/writers/s5_html/themes/small-white
	docutils/writers/s5_html/themes/small-white/framing.css
	docutils/writers/s5_html/themes/small-white/pretty.css extras
	extras/optparse.py extras/roman.py extras/textwrap.py
	install.py licenses licenses/docutils.conf licenses/gpl.txt
	licenses/python-2-1-1.txt licenses/python-2-2.txt
	licenses/python-2-3.txt setup.py test
	test/DocutilsTestSupport.py test/alltests.py test/coverage.sh
	test/data test/data/config_1.txt test/data/config_2.txt
	test/data/config_error_handler.txt test/data/config_list.txt
	test/data/config_list_2.txt test/data/config_old.txt
	test/data/csv_data.txt test/data/csv_dep.txt
	test/data/dependencies.txt test/data/include.txt
	test/data/raw.txt test/data/stylesheet.txt test/docutils.conf
	test/docutils_difflib.py test/functional
	test/functional/README.txt test/functional/expected
	test/functional/expected/compact_lists.html
	test/functional/expected/dangerous.html
	test/functional/expected/field_name_limit.html
	test/functional/expected/latex_docinfo.tex
	test/functional/expected/misc_rst_html4css1.html
	test/functional/expected/pep_html.html
	test/functional/expected/standalone_rst_html4css1.html
	test/functional/expected/standalone_rst_latex.tex
	test/functional/expected/standalone_rst_pseudoxml.txt
	test/functional/expected/standalone_rst_s5_html_1.html
	test/functional/expected/standalone_rst_s5_html_2.html
	test/functional/expected/ui test/functional/expected/ui/default
	test/functional/expected/ui/default/blank.gif
	test/functional/expected/ui/default/framing.css
	test/functional/expected/ui/default/iepngfix.htc
	test/functional/expected/ui/default/opera.css
	test/functional/expected/ui/default/outline.css
	test/functional/expected/ui/default/pretty.css
	test/functional/expected/ui/default/print.css
	test/functional/expected/ui/default/s5-core.css
	test/functional/expected/ui/default/slides.css
	test/functional/expected/ui/default/slides.js
	test/functional/expected/ui/small-black
	test/functional/expected/ui/small-black/blank.gif
	test/functional/expected/ui/small-black/framing.css
	test/functional/expected/ui/small-black/iepngfix.htc
	test/functional/expected/ui/small-black/opera.css
	test/functional/expected/ui/small-black/outline.css
	test/functional/expected/ui/small-black/pretty.css
	test/functional/expected/ui/small-black/print.css
	test/functional/expected/ui/small-black/s5-core.css
	test/functional/expected/ui/small-black/slides.css
	test/functional/expected/ui/small-black/slides.js
	test/functional/input test/functional/input/compact_lists.txt
	test/functional/input/dangerous.txt test/functional/input/data
	test/functional/input/data/custom_roles.txt
	test/functional/input/data/errors.txt
	test/functional/input/data/header_footer.txt
	test/functional/input/data/latex.txt
	test/functional/input/data/list_table.txt
	test/functional/input/data/nonalphanumeric.txt
	test/functional/input/data/standard.txt
	test/functional/input/data/table_colspan.txt
	test/functional/input/data/table_complex.txt
	test/functional/input/data/table_rowspan.txt
	test/functional/input/data/unicode.txt
	test/functional/input/field_list.txt
	test/functional/input/latex_docinfo.txt
	test/functional/input/pep_html.txt test/functional/input/simple.txt
	test/functional/input/standalone_rst_html4css1.txt
	test/functional/input/standalone_rst_latex.txt
	test/functional/input/standalone_rst_newlatex.txt
	test/functional/input/standalone_rst_pseudoxml.txt
	test/functional/input/standalone_rst_s5_html.txt
	test/functional/output test/functional/output/README.txt
	test/functional/tests test/functional/tests/_default.py
	test/functional/tests/_standalone_rst_defaults.py
	test/functional/tests/compact_lists.py
	test/functional/tests/dangerous.py
	test/functional/tests/field_name_limit.py
	test/functional/tests/latex_docinfo.py
	test/functional/tests/misc_rst_html4css1.py
	test/functional/tests/pep_html.py
	test/functional/tests/standalone_rst_html4css1.py
	test/functional/tests/standalone_rst_latex.py
	test/functional/tests/standalone_rst_pseudoxml.py
	test/functional/tests/standalone_rst_s5_html_1.py
	test/functional/tests/standalone_rst_s5_html_2.py
	test/package_unittest.py test/test_dependencies.py
	test/test_functional.py test/test_io.py test/test_language.py
	test/test_nodes.py test/test_parsers
	test/test_parsers/__init__.py test/test_parsers/test_rst
	test/test_parsers/test_rst/__init__.py
	test/test_parsers/test_rst/includes
	test/test_parsers/test_rst/includes/include9.txt
	test/test_parsers/test_rst/test_SimpleTableParser.py
	test/test_parsers/test_rst/test_TableParser.py
	test/test_parsers/test_rst/test_block_quotes.py
	test/test_parsers/test_rst/test_bullet_lists.py
	test/test_parsers/test_rst/test_citations.py
	test/test_parsers/test_rst/test_comments.py
	test/test_parsers/test_rst/test_definition_lists.py
	test/test_parsers/test_rst/test_directives
	test/test_parsers/test_rst/test_directives/__init__.py
	test/test_parsers/test_rst/test_directives/empty.txt
	test/test_parsers/test_rst/test_directives/include 11.txt
	test/test_parsers/test_rst/test_directives/include1.txt
	test/test_parsers/test_rst/test_directives/include10.txt
	test/test_parsers/test_rst/test_directives/include2.txt
	test/test_parsers/test_rst/test_directives/include3.txt
	test/test_parsers/test_rst/test_directives/include8.txt
	test/test_parsers/test_rst/test_directives/includes
	test/test_parsers/test_rst/test_directives/includes/include4.txt
	test/test_parsers/test_rst/test_directives/includes/include5.txt
	test/test_parsers/test_rst/test_directives/includes/more
	test/test_parsers/test_rst/test_directives/includes/more/include6.txt
	test/test_parsers/test_rst/test_directives/includes/sibling
	test/test_parsers/test_rst/test_directives/includes/sibling/include7.txt
	test/test_parsers/test_rst/test_directives/raw1.txt
	test/test_parsers/test_rst/test_directives/test_admonitions.py
	test/test_parsers/test_rst/test_directives/test_compound.py
	test/test_parsers/test_rst/test_directives/test_container.py
	test/test_parsers/test_rst/test_directives/test_contents.py
	test/test_parsers/test_rst/test_directives/test_date.py
	test/test_parsers/test_rst/test_directives/test_decorations.py
	test/test_parsers/test_rst/test_directives/test_default_role.py
	test/test_parsers/test_rst/test_directives/test_figures.py
	test/test_parsers/test_rst/test_directives/test_images.py
	test/test_parsers/test_rst/test_directives/test_include.py
	test/test_parsers/test_rst/test_directives/test_line_blocks.py
	test/test_parsers/test_rst/test_directives/test_meta.py
	test/test_parsers/test_rst/test_directives/test_raw.py
	test/test_parsers/test_rst/test_directives/test_replace.py
	test/test_parsers/test_rst/test_directives/test_role.py
	test/test_parsers/test_rst/test_directives/test_rubrics.py
	test/test_parsers/test_rst/test_directives/test_sidebars.py
	test/test_parsers/test_rst/test_directives/test_tables.py
	test/test_parsers/test_rst/test_directives/test_target_notes.py
	test/test_parsers/test_rst/test_directives/test_test_directives.py
	test/test_parsers/test_rst/test_directives/test_topics.py
	test/test_parsers/test_rst/test_directives/test_unicode.py
	test/test_parsers/test_rst/test_directives/test_unknown.py
	test/test_parsers/test_rst/test_directives/utf-16.csv
	test/test_parsers/test_rst/test_doctest_blocks.py
	test/test_parsers/test_rst/test_east_asian_text.py
	test/test_parsers/test_rst/test_enumerated_lists.py
	test/test_parsers/test_rst/test_field_lists.py
	test/test_parsers/test_rst/test_footnotes.py
	test/test_parsers/test_rst/test_functions.py
	test/test_parsers/test_rst/test_inline_markup.py
	test/test_parsers/test_rst/test_interpreted.py
	test/test_parsers/test_rst/test_line_blocks.py
	test/test_parsers/test_rst/test_literal_blocks.py
	test/test_parsers/test_rst/test_option_lists.py
	test/test_parsers/test_rst/test_outdenting.py
	test/test_parsers/test_rst/test_paragraphs.py
	test/test_parsers/test_rst/test_section_headers.py
	test/test_parsers/test_rst/test_substitutions.py
	test/test_parsers/test_rst/test_tables.py
	test/test_parsers/test_rst/test_targets.py
	test/test_parsers/test_rst/test_transitions.py
	test/test_publisher.py test/test_readers
	test/test_readers/__init__.py test/test_readers/test_pep
	test/test_readers/test_pep/__init__.py
	test/test_readers/test_pep/test_inline_markup.py
	test/test_readers/test_pep/test_rfc2822.py
	test/test_readers/test_python
	test/test_readers/test_python/__init__.py
	test/test_readers/test_python/showast
	test/test_readers/test_python/showdoc
	test/test_readers/test_python/showparse
	test/test_readers/test_python/showtok
	test/test_readers/test_python/test_functions.py
	test/test_readers/test_python/test_parser.py
	test/test_readers/test_python/test_token_parser.py
	test/test_settings.py test/test_statemachine.py
	test/test_transforms test/test_transforms/__init__.py
	test/test_transforms/test___init__.py
	test/test_transforms/test_class.py
	test/test_transforms/test_contents.py
	test/test_transforms/test_docinfo.py
	test/test_transforms/test_doctitle.py
	test/test_transforms/test_expose_internals.py
	test/test_transforms/test_filter.py
	test/test_transforms/test_footnotes.py
	test/test_transforms/test_hyperlinks.py
	test/test_transforms/test_messages.py
	test/test_transforms/test_peps.py
	test/test_transforms/test_sectnum.py
	test/test_transforms/test_strip_comments.py
	test/test_transforms/test_substitutions.py
	test/test_transforms/test_target_notes.py
	test/test_transforms/test_transitions.py
	test/test_transforms/test_writer_aux.py test/test_utils.py
	test/test_viewlist.py test/test_writers
	test/test_writers/__init__.py test/test_writers/test_docutils_xml.py
	test/test_writers/test_html4css1.py
	test/test_writers/test_html4css1_misc.py
	test/test_writers/test_latex2e.py test/test_writers/test_null.py
	test/test_writers/test_pseudoxml.py tools tools/buildhtml.py
	tools/dev tools/dev/README.txt tools/dev/create_unimap.py
	tools/dev/profile_docutils.py tools/dev/unicode2rstsubs.py
	tools/docutils.conf tools/editors tools/editors/README.txt
	tools/editors/emacs tools/editors/emacs/README.txt
	tools/editors/emacs/docutils.conf tools/editors/emacs/rst.el
	tools/editors/emacs/tests tools/editors/emacs/tests/Makefile
	tools/editors/emacs/tests/README
	tools/editors/emacs/tests/tests-adjust-section.el
	tools/editors/emacs/tests/tests-basic.el
	tools/editors/emacs/tests/tests-runner.el tools/quicktest.py
	tools/rst2html.py tools/rst2latex.py tools/rst2newlatex.py
	tools/rst2pseudoxml.py tools/rst2s5.py tools/rst2xml.py
	tools/rstpep2html.py
Message-ID: <20070809155219.76B401E4009@bag.python.org>

Author: georg.brandl
Date: Thu Aug  9 17:52:00 2007
New Revision: 56857

Added:
   external/docutils-0.4/
   external/docutils-0.4/BUGS.txt
   external/docutils-0.4/COPYING.txt
   external/docutils-0.4/FAQ.txt
   external/docutils-0.4/HISTORY.txt
   external/docutils-0.4/PKG-INFO
   external/docutils-0.4/README.txt
   external/docutils-0.4/RELEASE-NOTES.txt
   external/docutils-0.4/THANKS.txt
   external/docutils-0.4/docs/
   external/docutils-0.4/docs/api/
   external/docutils-0.4/docs/api/cmdline-tool.txt
   external/docutils-0.4/docs/api/publisher.txt
   external/docutils-0.4/docs/api/runtime-settings.txt
   external/docutils-0.4/docs/dev/
   external/docutils-0.4/docs/dev/distributing.txt
   external/docutils-0.4/docs/dev/enthought-plan.txt
   external/docutils-0.4/docs/dev/enthought-rfp.txt
   external/docutils-0.4/docs/dev/hacking.txt
   external/docutils-0.4/docs/dev/policies.txt
   external/docutils-0.4/docs/dev/pysource.dtd
   external/docutils-0.4/docs/dev/pysource.txt
   external/docutils-0.4/docs/dev/release.txt
   external/docutils-0.4/docs/dev/repository.txt
   external/docutils-0.4/docs/dev/rst/
   external/docutils-0.4/docs/dev/rst/alternatives.txt
   external/docutils-0.4/docs/dev/rst/problems.txt
   external/docutils-0.4/docs/dev/semantics.txt
   external/docutils-0.4/docs/dev/testing.txt
   external/docutils-0.4/docs/dev/todo.txt
   external/docutils-0.4/docs/dev/website.txt
   external/docutils-0.4/docs/howto/
   external/docutils-0.4/docs/howto/html-stylesheets.txt
   external/docutils-0.4/docs/howto/i18n.txt
   external/docutils-0.4/docs/howto/rst-directives.txt
   external/docutils-0.4/docs/howto/rst-roles.txt
   external/docutils-0.4/docs/index.txt
   external/docutils-0.4/docs/peps/
   external/docutils-0.4/docs/peps/pep-0256.txt
   external/docutils-0.4/docs/peps/pep-0257.txt
   external/docutils-0.4/docs/peps/pep-0258.txt
   external/docutils-0.4/docs/peps/pep-0287.txt
   external/docutils-0.4/docs/ref/
   external/docutils-0.4/docs/ref/doctree.txt
   external/docutils-0.4/docs/ref/docutils.dtd
   external/docutils-0.4/docs/ref/rst/
   external/docutils-0.4/docs/ref/rst/definitions.txt
   external/docutils-0.4/docs/ref/rst/directives.txt
   external/docutils-0.4/docs/ref/rst/introduction.txt
   external/docutils-0.4/docs/ref/rst/restructuredtext.txt
   external/docutils-0.4/docs/ref/rst/roles.txt
   external/docutils-0.4/docs/ref/soextblx.dtd
   external/docutils-0.4/docs/ref/transforms.txt
   external/docutils-0.4/docs/user/
   external/docutils-0.4/docs/user/Makefile.docutils-update
   external/docutils-0.4/docs/user/config.txt
   external/docutils-0.4/docs/user/emacs.txt
   external/docutils-0.4/docs/user/images/
   external/docutils-0.4/docs/user/images/big-black.png   (contents, props changed)
   external/docutils-0.4/docs/user/images/big-white.png   (contents, props changed)
   external/docutils-0.4/docs/user/images/default.png   (contents, props changed)
   external/docutils-0.4/docs/user/images/happy_monkey.png   (contents, props changed)
   external/docutils-0.4/docs/user/images/medium-black.png   (contents, props changed)
   external/docutils-0.4/docs/user/images/medium-white.png   (contents, props changed)
   external/docutils-0.4/docs/user/images/rsp-all.png   (contents, props changed)
   external/docutils-0.4/docs/user/images/rsp-breaks.png   (contents, props changed)
   external/docutils-0.4/docs/user/images/rsp-covers.png   (contents, props changed)
   external/docutils-0.4/docs/user/images/rsp-cuts.png   (contents, props changed)
   external/docutils-0.4/docs/user/images/rsp-empty.png   (contents, props changed)
   external/docutils-0.4/docs/user/images/rsp-objects.png   (contents, props changed)
   external/docutils-0.4/docs/user/images/rsp.svg
   external/docutils-0.4/docs/user/images/s5-files.png   (contents, props changed)
   external/docutils-0.4/docs/user/images/s5-files.svg
   external/docutils-0.4/docs/user/images/small-black.png   (contents, props changed)
   external/docutils-0.4/docs/user/images/small-white.png   (contents, props changed)
   external/docutils-0.4/docs/user/latex.txt
   external/docutils-0.4/docs/user/links.txt
   external/docutils-0.4/docs/user/mailing-lists.txt
   external/docutils-0.4/docs/user/rst/
   external/docutils-0.4/docs/user/rst/cheatsheet.txt
   external/docutils-0.4/docs/user/rst/demo.txt
   external/docutils-0.4/docs/user/rst/images/
   external/docutils-0.4/docs/user/rst/images/ball1.gif   (contents, props changed)
   external/docutils-0.4/docs/user/rst/images/biohazard.png   (contents, props changed)
   external/docutils-0.4/docs/user/rst/images/title.png   (contents, props changed)
   external/docutils-0.4/docs/user/rst/quickref.html
   external/docutils-0.4/docs/user/rst/quickstart.txt
   external/docutils-0.4/docs/user/slide-shows.txt
   external/docutils-0.4/docs/user/tools.txt
   external/docutils-0.4/docutils/
   external/docutils-0.4/docutils/__init__.py
   external/docutils-0.4/docutils/core.py
   external/docutils-0.4/docutils/docutils.conf
   external/docutils-0.4/docutils/examples.py
   external/docutils-0.4/docutils/frontend.py
   external/docutils-0.4/docutils/io.py
   external/docutils-0.4/docutils/languages/
   external/docutils-0.4/docutils/languages/__init__.py
   external/docutils-0.4/docutils/languages/af.py
   external/docutils-0.4/docutils/languages/ca.py
   external/docutils-0.4/docutils/languages/cs.py
   external/docutils-0.4/docutils/languages/de.py
   external/docutils-0.4/docutils/languages/en.py
   external/docutils-0.4/docutils/languages/eo.py
   external/docutils-0.4/docutils/languages/es.py
   external/docutils-0.4/docutils/languages/fi.py
   external/docutils-0.4/docutils/languages/fr.py
   external/docutils-0.4/docutils/languages/it.py
   external/docutils-0.4/docutils/languages/ja.py
   external/docutils-0.4/docutils/languages/nl.py
   external/docutils-0.4/docutils/languages/pt_br.py
   external/docutils-0.4/docutils/languages/ru.py
   external/docutils-0.4/docutils/languages/sk.py
   external/docutils-0.4/docutils/languages/sv.py
   external/docutils-0.4/docutils/languages/zh_cn.py
   external/docutils-0.4/docutils/languages/zh_tw.py
   external/docutils-0.4/docutils/nodes.py
   external/docutils-0.4/docutils/parsers/
   external/docutils-0.4/docutils/parsers/__init__.py
   external/docutils-0.4/docutils/parsers/null.py
   external/docutils-0.4/docutils/parsers/rst/
   external/docutils-0.4/docutils/parsers/rst/__init__.py
   external/docutils-0.4/docutils/parsers/rst/directives/
   external/docutils-0.4/docutils/parsers/rst/directives/__init__.py
   external/docutils-0.4/docutils/parsers/rst/directives/admonitions.py
   external/docutils-0.4/docutils/parsers/rst/directives/body.py
   external/docutils-0.4/docutils/parsers/rst/directives/html.py
   external/docutils-0.4/docutils/parsers/rst/directives/images.py
   external/docutils-0.4/docutils/parsers/rst/directives/misc.py
   external/docutils-0.4/docutils/parsers/rst/directives/parts.py
   external/docutils-0.4/docutils/parsers/rst/directives/references.py
   external/docutils-0.4/docutils/parsers/rst/directives/tables.py
   external/docutils-0.4/docutils/parsers/rst/include/
   external/docutils-0.4/docutils/parsers/rst/include/README.txt
   external/docutils-0.4/docutils/parsers/rst/include/isoamsa.txt
   external/docutils-0.4/docutils/parsers/rst/include/isoamsb.txt
   external/docutils-0.4/docutils/parsers/rst/include/isoamsc.txt
   external/docutils-0.4/docutils/parsers/rst/include/isoamsn.txt
   external/docutils-0.4/docutils/parsers/rst/include/isoamso.txt
   external/docutils-0.4/docutils/parsers/rst/include/isoamsr.txt
   external/docutils-0.4/docutils/parsers/rst/include/isobox.txt
   external/docutils-0.4/docutils/parsers/rst/include/isocyr1.txt
   external/docutils-0.4/docutils/parsers/rst/include/isocyr2.txt
   external/docutils-0.4/docutils/parsers/rst/include/isodia.txt
   external/docutils-0.4/docutils/parsers/rst/include/isogrk1.txt
   external/docutils-0.4/docutils/parsers/rst/include/isogrk2.txt
   external/docutils-0.4/docutils/parsers/rst/include/isogrk3.txt
   external/docutils-0.4/docutils/parsers/rst/include/isogrk4-wide.txt
   external/docutils-0.4/docutils/parsers/rst/include/isogrk4.txt
   external/docutils-0.4/docutils/parsers/rst/include/isolat1.txt
   external/docutils-0.4/docutils/parsers/rst/include/isolat2.txt
   external/docutils-0.4/docutils/parsers/rst/include/isomfrk-wide.txt
   external/docutils-0.4/docutils/parsers/rst/include/isomfrk.txt
   external/docutils-0.4/docutils/parsers/rst/include/isomopf-wide.txt
   external/docutils-0.4/docutils/parsers/rst/include/isomopf.txt
   external/docutils-0.4/docutils/parsers/rst/include/isomscr-wide.txt
   external/docutils-0.4/docutils/parsers/rst/include/isomscr.txt
   external/docutils-0.4/docutils/parsers/rst/include/isonum.txt
   external/docutils-0.4/docutils/parsers/rst/include/isopub.txt
   external/docutils-0.4/docutils/parsers/rst/include/isotech.txt
   external/docutils-0.4/docutils/parsers/rst/include/mmlalias.txt
   external/docutils-0.4/docutils/parsers/rst/include/mmlextra-wide.txt
   external/docutils-0.4/docutils/parsers/rst/include/mmlextra.txt
   external/docutils-0.4/docutils/parsers/rst/include/s5defs.txt
   external/docutils-0.4/docutils/parsers/rst/include/xhtml1-lat1.txt
   external/docutils-0.4/docutils/parsers/rst/include/xhtml1-special.txt
   external/docutils-0.4/docutils/parsers/rst/include/xhtml1-symbol.txt
   external/docutils-0.4/docutils/parsers/rst/languages/
   external/docutils-0.4/docutils/parsers/rst/languages/__init__.py
   external/docutils-0.4/docutils/parsers/rst/languages/af.py
   external/docutils-0.4/docutils/parsers/rst/languages/ca.py
   external/docutils-0.4/docutils/parsers/rst/languages/cs.py
   external/docutils-0.4/docutils/parsers/rst/languages/de.py
   external/docutils-0.4/docutils/parsers/rst/languages/en.py
   external/docutils-0.4/docutils/parsers/rst/languages/eo.py
   external/docutils-0.4/docutils/parsers/rst/languages/es.py
   external/docutils-0.4/docutils/parsers/rst/languages/fi.py
   external/docutils-0.4/docutils/parsers/rst/languages/fr.py
   external/docutils-0.4/docutils/parsers/rst/languages/it.py
   external/docutils-0.4/docutils/parsers/rst/languages/ja.py
   external/docutils-0.4/docutils/parsers/rst/languages/nl.py
   external/docutils-0.4/docutils/parsers/rst/languages/pt_br.py
   external/docutils-0.4/docutils/parsers/rst/languages/ru.py
   external/docutils-0.4/docutils/parsers/rst/languages/sk.py
   external/docutils-0.4/docutils/parsers/rst/languages/sv.py
   external/docutils-0.4/docutils/parsers/rst/languages/zh_cn.py
   external/docutils-0.4/docutils/parsers/rst/languages/zh_tw.py
   external/docutils-0.4/docutils/parsers/rst/roles.py
   external/docutils-0.4/docutils/parsers/rst/states.py
   external/docutils-0.4/docutils/parsers/rst/tableparser.py
   external/docutils-0.4/docutils/readers/
   external/docutils-0.4/docutils/readers/__init__.py
   external/docutils-0.4/docutils/readers/doctree.py
   external/docutils-0.4/docutils/readers/pep.py
   external/docutils-0.4/docutils/readers/python/
   external/docutils-0.4/docutils/readers/python/__init__.py
   external/docutils-0.4/docutils/readers/python/moduleparser.py
   external/docutils-0.4/docutils/readers/python/pynodes.py
   external/docutils-0.4/docutils/readers/standalone.py
   external/docutils-0.4/docutils/statemachine.py
   external/docutils-0.4/docutils/transforms/
   external/docutils-0.4/docutils/transforms/__init__.py
   external/docutils-0.4/docutils/transforms/components.py
   external/docutils-0.4/docutils/transforms/frontmatter.py
   external/docutils-0.4/docutils/transforms/misc.py
   external/docutils-0.4/docutils/transforms/parts.py
   external/docutils-0.4/docutils/transforms/peps.py
   external/docutils-0.4/docutils/transforms/references.py
   external/docutils-0.4/docutils/transforms/universal.py
   external/docutils-0.4/docutils/transforms/writer_aux.py
   external/docutils-0.4/docutils/urischemes.py
   external/docutils-0.4/docutils/utils.py
   external/docutils-0.4/docutils/writers/
   external/docutils-0.4/docutils/writers/__init__.py
   external/docutils-0.4/docutils/writers/docutils_xml.py
   external/docutils-0.4/docutils/writers/html4css1/
   external/docutils-0.4/docutils/writers/html4css1/__init__.py
   external/docutils-0.4/docutils/writers/html4css1/html4css1.css
   external/docutils-0.4/docutils/writers/latex2e/
   external/docutils-0.4/docutils/writers/latex2e/__init__.py
   external/docutils-0.4/docutils/writers/latex2e/latex2e.tex
   external/docutils-0.4/docutils/writers/newlatex2e/
   external/docutils-0.4/docutils/writers/newlatex2e/__init__.py
   external/docutils-0.4/docutils/writers/newlatex2e/base.tex
   external/docutils-0.4/docutils/writers/newlatex2e/unicode_map.py
   external/docutils-0.4/docutils/writers/null.py
   external/docutils-0.4/docutils/writers/pep_html/
   external/docutils-0.4/docutils/writers/pep_html/__init__.py
   external/docutils-0.4/docutils/writers/pep_html/pep.css
   external/docutils-0.4/docutils/writers/pep_html/template.txt
   external/docutils-0.4/docutils/writers/pseudoxml.py
   external/docutils-0.4/docutils/writers/s5_html/
   external/docutils-0.4/docutils/writers/s5_html/__init__.py
   external/docutils-0.4/docutils/writers/s5_html/themes/
   external/docutils-0.4/docutils/writers/s5_html/themes/README.txt
   external/docutils-0.4/docutils/writers/s5_html/themes/big-black/
   external/docutils-0.4/docutils/writers/s5_html/themes/big-black/__base__
   external/docutils-0.4/docutils/writers/s5_html/themes/big-black/framing.css
   external/docutils-0.4/docutils/writers/s5_html/themes/big-black/pretty.css
   external/docutils-0.4/docutils/writers/s5_html/themes/big-white/
   external/docutils-0.4/docutils/writers/s5_html/themes/big-white/framing.css
   external/docutils-0.4/docutils/writers/s5_html/themes/big-white/pretty.css
   external/docutils-0.4/docutils/writers/s5_html/themes/default/
   external/docutils-0.4/docutils/writers/s5_html/themes/default/blank.gif   (contents, props changed)
   external/docutils-0.4/docutils/writers/s5_html/themes/default/framing.css
   external/docutils-0.4/docutils/writers/s5_html/themes/default/iepngfix.htc
   external/docutils-0.4/docutils/writers/s5_html/themes/default/opera.css
   external/docutils-0.4/docutils/writers/s5_html/themes/default/outline.css
   external/docutils-0.4/docutils/writers/s5_html/themes/default/pretty.css
   external/docutils-0.4/docutils/writers/s5_html/themes/default/print.css
   external/docutils-0.4/docutils/writers/s5_html/themes/default/s5-core.css
   external/docutils-0.4/docutils/writers/s5_html/themes/default/slides.css
   external/docutils-0.4/docutils/writers/s5_html/themes/default/slides.js
   external/docutils-0.4/docutils/writers/s5_html/themes/medium-black/
   external/docutils-0.4/docutils/writers/s5_html/themes/medium-black/__base__
   external/docutils-0.4/docutils/writers/s5_html/themes/medium-black/pretty.css
   external/docutils-0.4/docutils/writers/s5_html/themes/medium-white/
   external/docutils-0.4/docutils/writers/s5_html/themes/medium-white/framing.css
   external/docutils-0.4/docutils/writers/s5_html/themes/medium-white/pretty.css
   external/docutils-0.4/docutils/writers/s5_html/themes/small-black/
   external/docutils-0.4/docutils/writers/s5_html/themes/small-black/__base__
   external/docutils-0.4/docutils/writers/s5_html/themes/small-black/pretty.css
   external/docutils-0.4/docutils/writers/s5_html/themes/small-white/
   external/docutils-0.4/docutils/writers/s5_html/themes/small-white/framing.css
   external/docutils-0.4/docutils/writers/s5_html/themes/small-white/pretty.css
   external/docutils-0.4/extras/
   external/docutils-0.4/extras/optparse.py
   external/docutils-0.4/extras/roman.py
   external/docutils-0.4/extras/textwrap.py
   external/docutils-0.4/install.py   (contents, props changed)
   external/docutils-0.4/licenses/
   external/docutils-0.4/licenses/docutils.conf
   external/docutils-0.4/licenses/gpl.txt
   external/docutils-0.4/licenses/python-2-1-1.txt
   external/docutils-0.4/licenses/python-2-2.txt
   external/docutils-0.4/licenses/python-2-3.txt
   external/docutils-0.4/setup.py   (contents, props changed)
   external/docutils-0.4/test/
   external/docutils-0.4/test/DocutilsTestSupport.py
   external/docutils-0.4/test/alltests.py   (contents, props changed)
   external/docutils-0.4/test/coverage.sh   (contents, props changed)
   external/docutils-0.4/test/data/
   external/docutils-0.4/test/data/config_1.txt
   external/docutils-0.4/test/data/config_2.txt
   external/docutils-0.4/test/data/config_error_handler.txt
   external/docutils-0.4/test/data/config_list.txt
   external/docutils-0.4/test/data/config_list_2.txt
   external/docutils-0.4/test/data/config_old.txt
   external/docutils-0.4/test/data/csv_data.txt
   external/docutils-0.4/test/data/csv_dep.txt
   external/docutils-0.4/test/data/dependencies.txt
   external/docutils-0.4/test/data/include.txt
   external/docutils-0.4/test/data/raw.txt
   external/docutils-0.4/test/data/stylesheet.txt
   external/docutils-0.4/test/docutils.conf
   external/docutils-0.4/test/docutils_difflib.py
   external/docutils-0.4/test/functional/
   external/docutils-0.4/test/functional/README.txt
   external/docutils-0.4/test/functional/expected/
   external/docutils-0.4/test/functional/expected/compact_lists.html
   external/docutils-0.4/test/functional/expected/dangerous.html
   external/docutils-0.4/test/functional/expected/field_name_limit.html
   external/docutils-0.4/test/functional/expected/latex_docinfo.tex
   external/docutils-0.4/test/functional/expected/misc_rst_html4css1.html
   external/docutils-0.4/test/functional/expected/pep_html.html
   external/docutils-0.4/test/functional/expected/standalone_rst_html4css1.html
   external/docutils-0.4/test/functional/expected/standalone_rst_latex.tex
   external/docutils-0.4/test/functional/expected/standalone_rst_pseudoxml.txt
   external/docutils-0.4/test/functional/expected/standalone_rst_s5_html_1.html
   external/docutils-0.4/test/functional/expected/standalone_rst_s5_html_2.html
   external/docutils-0.4/test/functional/expected/ui/
   external/docutils-0.4/test/functional/expected/ui/default/
   external/docutils-0.4/test/functional/expected/ui/default/blank.gif   (contents, props changed)
   external/docutils-0.4/test/functional/expected/ui/default/framing.css
   external/docutils-0.4/test/functional/expected/ui/default/iepngfix.htc
   external/docutils-0.4/test/functional/expected/ui/default/opera.css
   external/docutils-0.4/test/functional/expected/ui/default/outline.css
   external/docutils-0.4/test/functional/expected/ui/default/pretty.css
   external/docutils-0.4/test/functional/expected/ui/default/print.css
   external/docutils-0.4/test/functional/expected/ui/default/s5-core.css
   external/docutils-0.4/test/functional/expected/ui/default/slides.css
   external/docutils-0.4/test/functional/expected/ui/default/slides.js
   external/docutils-0.4/test/functional/expected/ui/small-black/
   external/docutils-0.4/test/functional/expected/ui/small-black/blank.gif   (contents, props changed)
   external/docutils-0.4/test/functional/expected/ui/small-black/framing.css
   external/docutils-0.4/test/functional/expected/ui/small-black/iepngfix.htc
   external/docutils-0.4/test/functional/expected/ui/small-black/opera.css
   external/docutils-0.4/test/functional/expected/ui/small-black/outline.css
   external/docutils-0.4/test/functional/expected/ui/small-black/pretty.css
   external/docutils-0.4/test/functional/expected/ui/small-black/print.css
   external/docutils-0.4/test/functional/expected/ui/small-black/s5-core.css
   external/docutils-0.4/test/functional/expected/ui/small-black/slides.css
   external/docutils-0.4/test/functional/expected/ui/small-black/slides.js
   external/docutils-0.4/test/functional/input/
   external/docutils-0.4/test/functional/input/compact_lists.txt
   external/docutils-0.4/test/functional/input/dangerous.txt
   external/docutils-0.4/test/functional/input/data/
   external/docutils-0.4/test/functional/input/data/custom_roles.txt
   external/docutils-0.4/test/functional/input/data/errors.txt
   external/docutils-0.4/test/functional/input/data/header_footer.txt
   external/docutils-0.4/test/functional/input/data/latex.txt
   external/docutils-0.4/test/functional/input/data/list_table.txt
   external/docutils-0.4/test/functional/input/data/nonalphanumeric.txt
   external/docutils-0.4/test/functional/input/data/standard.txt
   external/docutils-0.4/test/functional/input/data/table_colspan.txt
   external/docutils-0.4/test/functional/input/data/table_complex.txt
   external/docutils-0.4/test/functional/input/data/table_rowspan.txt
   external/docutils-0.4/test/functional/input/data/unicode.txt
   external/docutils-0.4/test/functional/input/field_list.txt
   external/docutils-0.4/test/functional/input/latex_docinfo.txt
   external/docutils-0.4/test/functional/input/pep_html.txt
   external/docutils-0.4/test/functional/input/simple.txt
   external/docutils-0.4/test/functional/input/standalone_rst_html4css1.txt
   external/docutils-0.4/test/functional/input/standalone_rst_latex.txt
   external/docutils-0.4/test/functional/input/standalone_rst_newlatex.txt
   external/docutils-0.4/test/functional/input/standalone_rst_pseudoxml.txt
   external/docutils-0.4/test/functional/input/standalone_rst_s5_html.txt
   external/docutils-0.4/test/functional/output/
   external/docutils-0.4/test/functional/output/README.txt
   external/docutils-0.4/test/functional/tests/
   external/docutils-0.4/test/functional/tests/_default.py
   external/docutils-0.4/test/functional/tests/_standalone_rst_defaults.py
   external/docutils-0.4/test/functional/tests/compact_lists.py
   external/docutils-0.4/test/functional/tests/dangerous.py
   external/docutils-0.4/test/functional/tests/field_name_limit.py
   external/docutils-0.4/test/functional/tests/latex_docinfo.py
   external/docutils-0.4/test/functional/tests/misc_rst_html4css1.py
   external/docutils-0.4/test/functional/tests/pep_html.py
   external/docutils-0.4/test/functional/tests/standalone_rst_html4css1.py
   external/docutils-0.4/test/functional/tests/standalone_rst_latex.py
   external/docutils-0.4/test/functional/tests/standalone_rst_pseudoxml.py
   external/docutils-0.4/test/functional/tests/standalone_rst_s5_html_1.py   (contents, props changed)
   external/docutils-0.4/test/functional/tests/standalone_rst_s5_html_2.py   (contents, props changed)
   external/docutils-0.4/test/package_unittest.py
   external/docutils-0.4/test/test_dependencies.py   (contents, props changed)
   external/docutils-0.4/test/test_functional.py   (contents, props changed)
   external/docutils-0.4/test/test_io.py   (contents, props changed)
   external/docutils-0.4/test/test_language.py   (contents, props changed)
   external/docutils-0.4/test/test_nodes.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/
   external/docutils-0.4/test/test_parsers/__init__.py
   external/docutils-0.4/test/test_parsers/test_rst/
   external/docutils-0.4/test/test_parsers/test_rst/__init__.py
   external/docutils-0.4/test/test_parsers/test_rst/includes/
   external/docutils-0.4/test/test_parsers/test_rst/includes/include9.txt
   external/docutils-0.4/test/test_parsers/test_rst/test_SimpleTableParser.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_TableParser.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_block_quotes.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_bullet_lists.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_citations.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_comments.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_definition_lists.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/__init__.py
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/empty.txt
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/include 11.txt
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/include1.txt
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/include10.txt
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/include2.txt
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/include3.txt
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/include8.txt
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/includes/
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/includes/include4.txt
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/includes/include5.txt
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/includes/more/
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/includes/more/include6.txt
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/includes/sibling/
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/includes/sibling/include7.txt
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/raw1.txt
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/test_admonitions.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/test_compound.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/test_container.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/test_contents.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/test_date.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/test_decorations.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/test_default_role.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/test_figures.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/test_images.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/test_include.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/test_line_blocks.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/test_meta.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/test_raw.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/test_replace.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/test_role.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/test_rubrics.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/test_sidebars.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/test_tables.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/test_target_notes.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/test_test_directives.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/test_topics.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/test_unicode.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/test_unknown.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_directives/utf-16.csv   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_doctest_blocks.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_east_asian_text.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_enumerated_lists.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_field_lists.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_footnotes.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_functions.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_inline_markup.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_interpreted.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_line_blocks.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_literal_blocks.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_option_lists.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_outdenting.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_paragraphs.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_section_headers.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_substitutions.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_tables.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_targets.py   (contents, props changed)
   external/docutils-0.4/test/test_parsers/test_rst/test_transitions.py   (contents, props changed)
   external/docutils-0.4/test/test_publisher.py   (contents, props changed)
   external/docutils-0.4/test/test_readers/
   external/docutils-0.4/test/test_readers/__init__.py
   external/docutils-0.4/test/test_readers/test_pep/
   external/docutils-0.4/test/test_readers/test_pep/__init__.py
   external/docutils-0.4/test/test_readers/test_pep/test_inline_markup.py   (contents, props changed)
   external/docutils-0.4/test/test_readers/test_pep/test_rfc2822.py   (contents, props changed)
   external/docutils-0.4/test/test_readers/test_python/
   external/docutils-0.4/test/test_readers/test_python/__init__.py
   external/docutils-0.4/test/test_readers/test_python/showast   (contents, props changed)
   external/docutils-0.4/test/test_readers/test_python/showdoc   (contents, props changed)
   external/docutils-0.4/test/test_readers/test_python/showparse   (contents, props changed)
   external/docutils-0.4/test/test_readers/test_python/showtok   (contents, props changed)
   external/docutils-0.4/test/test_readers/test_python/test_functions.py   (contents, props changed)
   external/docutils-0.4/test/test_readers/test_python/test_parser.py   (contents, props changed)
   external/docutils-0.4/test/test_readers/test_python/test_token_parser.py   (contents, props changed)
   external/docutils-0.4/test/test_settings.py   (contents, props changed)
   external/docutils-0.4/test/test_statemachine.py   (contents, props changed)
   external/docutils-0.4/test/test_transforms/
   external/docutils-0.4/test/test_transforms/__init__.py
   external/docutils-0.4/test/test_transforms/test___init__.py   (contents, props changed)
   external/docutils-0.4/test/test_transforms/test_class.py   (contents, props changed)
   external/docutils-0.4/test/test_transforms/test_contents.py   (contents, props changed)
   external/docutils-0.4/test/test_transforms/test_docinfo.py   (contents, props changed)
   external/docutils-0.4/test/test_transforms/test_doctitle.py   (contents, props changed)
   external/docutils-0.4/test/test_transforms/test_expose_internals.py   (contents, props changed)
   external/docutils-0.4/test/test_transforms/test_filter.py   (contents, props changed)
   external/docutils-0.4/test/test_transforms/test_footnotes.py   (contents, props changed)
   external/docutils-0.4/test/test_transforms/test_hyperlinks.py   (contents, props changed)
   external/docutils-0.4/test/test_transforms/test_messages.py   (contents, props changed)
   external/docutils-0.4/test/test_transforms/test_peps.py   (contents, props changed)
   external/docutils-0.4/test/test_transforms/test_sectnum.py   (contents, props changed)
   external/docutils-0.4/test/test_transforms/test_strip_comments.py   (contents, props changed)
   external/docutils-0.4/test/test_transforms/test_substitutions.py   (contents, props changed)
   external/docutils-0.4/test/test_transforms/test_target_notes.py   (contents, props changed)
   external/docutils-0.4/test/test_transforms/test_transitions.py   (contents, props changed)
   external/docutils-0.4/test/test_transforms/test_writer_aux.py   (contents, props changed)
   external/docutils-0.4/test/test_utils.py   (contents, props changed)
   external/docutils-0.4/test/test_viewlist.py   (contents, props changed)
   external/docutils-0.4/test/test_writers/
   external/docutils-0.4/test/test_writers/__init__.py
   external/docutils-0.4/test/test_writers/test_docutils_xml.py   (contents, props changed)
   external/docutils-0.4/test/test_writers/test_html4css1.py   (contents, props changed)
   external/docutils-0.4/test/test_writers/test_html4css1_misc.py   (contents, props changed)
   external/docutils-0.4/test/test_writers/test_latex2e.py   (contents, props changed)
   external/docutils-0.4/test/test_writers/test_null.py   (contents, props changed)
   external/docutils-0.4/test/test_writers/test_pseudoxml.py   (contents, props changed)
   external/docutils-0.4/tools/
   external/docutils-0.4/tools/buildhtml.py   (contents, props changed)
   external/docutils-0.4/tools/dev/
   external/docutils-0.4/tools/dev/README.txt
   external/docutils-0.4/tools/dev/create_unimap.py   (contents, props changed)
   external/docutils-0.4/tools/dev/profile_docutils.py   (contents, props changed)
   external/docutils-0.4/tools/dev/unicode2rstsubs.py   (contents, props changed)
   external/docutils-0.4/tools/docutils.conf
   external/docutils-0.4/tools/editors/
   external/docutils-0.4/tools/editors/README.txt
   external/docutils-0.4/tools/editors/emacs/
   external/docutils-0.4/tools/editors/emacs/README.txt
   external/docutils-0.4/tools/editors/emacs/docutils.conf
   external/docutils-0.4/tools/editors/emacs/rst.el
   external/docutils-0.4/tools/editors/emacs/tests/
   external/docutils-0.4/tools/editors/emacs/tests/Makefile
   external/docutils-0.4/tools/editors/emacs/tests/README
   external/docutils-0.4/tools/editors/emacs/tests/tests-adjust-section.el
   external/docutils-0.4/tools/editors/emacs/tests/tests-basic.el
   external/docutils-0.4/tools/editors/emacs/tests/tests-runner.el
   external/docutils-0.4/tools/quicktest.py   (contents, props changed)
   external/docutils-0.4/tools/rst2html.py   (contents, props changed)
   external/docutils-0.4/tools/rst2latex.py   (contents, props changed)
   external/docutils-0.4/tools/rst2newlatex.py   (contents, props changed)
   external/docutils-0.4/tools/rst2pseudoxml.py   (contents, props changed)
   external/docutils-0.4/tools/rst2s5.py   (contents, props changed)
   external/docutils-0.4/tools/rst2xml.py   (contents, props changed)
   external/docutils-0.4/tools/rstpep2html.py   (contents, props changed)
Log:
Add Docutils 0.4 as an external.


Added: external/docutils-0.4/BUGS.txt
==============================================================================
--- (empty file)
+++ external/docutils-0.4/BUGS.txt	Thu Aug  9 17:52:00 2007
@@ -0,0 +1,280 @@
+================
+ Docutils_ Bugs
+================
+
+:Author: David Goodger; open to all Docutils developers
+:Contact: goodger at python.org
+:Date: $Date: 2005-12-29 00:48:48 +0100 (Thu, 29 Dec 2005) $
+:Revision: $Revision: 4233 $
+:Copyright: This document has been placed in the public domain.
+
+.. _Docutils: http://docutils.sourceforge.net/
+
+
+Bugs in Docutils?!?  Yes, we do have a few.  Some are old-timers that
+tend to stay in the shadows and don't bother anybody.  Once in a while
+new bugs are born.  From time to time some bugs (new and old) crawl
+out into the light and must be dealt with.  Icky.
+
+This document describes how to report a bug, and lists known bugs.
+
+.. contents::
+
+
+How To Report A Bug
+===================
+
+If you think you've discovered a bug, please read through these
+guidelines before reporting it.
+
+First, make sure it's a new bug:
+
+* Please check the list of `known bugs`_ below and the `SourceForge
+  Bug Tracker`_ to see if it has already been reported.
+
+* Are you using the very latest version of Docutils?  The bug may have
+  already been fixed.  Please get the latest version of Docutils from
+  the repository_ or from the current snapshot_ and check again.  Even
+  if your bug has not been fixed, others probably have, and you're
+  better off with the most up-to-date code.
+
+  If you don't have time to check the latest snapshot, please report
+  the bug anyway.  We'd rather tell you that it's already fixed than
+  miss reports of unfixed bugs.
+
+* If Docutils does not behave the way you expect, look in the
+  documentation_ (don't forget the FAQ_!) and `mailing list archives`_
+  for evidence that it should behave the way you expect.
+
+If you're not sure, please ask on the Docutils-users_ mailing list
+first.
+
+If it's a new bug, the most important thing you can do is to write a
+simple description and a recipe that reproduces the bug.  Try to
+create a minimal document that demonstrates the bug.  The easier you
+make it to understand and track down the bug, the more likely a fix
+will be.
+
+Now you're ready to write the bug report.  Please include:
+
+* A clear description of the bug.  Describe how you expected Docutils
+  to behave, and contrast that with how it actually behaved.  While
+  the bug may seem obvious to you, it may not be so obvious to someone
+  else, so it's best to avoid a guessing game.
+
+* A complete description of the environment in which you reproduced
+  the bug:
+
+  - Your operating system & version.
+  - The version of Python (``python -V``).
+  - The version of Docutils (use the "-V" option to most Docutils
+    front-end tools).
+  - Any private modifications you made to Docutils.
+  - Anything else that could possibly be relevant.  Err on the side
+    of too much information, rather than too little.
+
+* A literal transcript of the *exact* command you ran, and the *exact*
+  output.  Use the "--traceback" option to get a complete picture.
+
+* The exact input and output files.  Better to attach complete files
+  to your bug report than to include just a summary or excerpt.
+
+* If you also want to include speculation as to the cause, and even a
+  patch to fix the bug, that would be great!
+
+The best place to send your bug report is to the `SourceForge Bug
+Tracker`_.  That way, it won't be misplaced or forgotten.  In fact, an
+open bug report on SourceForge is a constant irritant that begs to be
+squashed.
+
+Thank you!
+
+(This section was inspired by the `Subversion project's`__ BUGS__
+file.)
+
+__ http://subversion.tigris.org/
+__ http://svn.collab.net/viewcvs/svn/trunk/BUGS?view=markup
+
+.. _CVS: http://sourceforge.net/cvs/?group_id=38414
+.. _repository: docs/dev/repository.html
+.. _snapshot: http://docutils.sourceforge.net/#download
+.. _documentation: docs/
+.. _FAQ: FAQ.html
+.. _mailing list archives: http://docutils.sf.net/#mailing-lists
+.. _Docutils-users: docs/user/mailing-lists.html#docutils-users
+.. _SourceForge Bug Tracker:
+   http://sourceforge.net/tracker/?group_id=38414&atid=422030
+
+
+Known Bugs
+==========
+
+Also see the `SourceForge Bug Tracker`_.
+
+* The "stylesheet" setting (a URL, to be used verbatim) should be
+  allowed to be combined with "embed_stylesheet".  The stylesheet data
+  should be read in using urllib.  There was an assumption that a
+  stylesheet to be embedded should exist as a file on the local
+  system, and only the "stylesheet_path" setting should be used.
+
+* ``utils.relative_path()`` sometimes returns absolute _`paths on
+  Windows` (like ``C:/test/foo.css``) where it could have chosen a
+  relative path.
+
+  Furthermore, absolute pathnames are inserted verbatim, like
+  ``href="C:/test/foo.css"`` instead of
+  ``href="file:///C:/test/foo.css"``.
+
+  For details, see `this posting by Alan G. Isaac
+  `_.
+
+* _`Line numbers` in system messages are inconsistent in the parser.
+
+  - In text inserted by the "include" directive, errors are often not
+    reported with the correct "source" or "line" numbers.  Perhaps all
+    Reporter calls need "source" and "line" keyword arguments.
+    Elements' .line assignments should be checked.  (Assign to .source
+    too?  Add a set_info method?  To what?)  There's a test in
+    test/test_parsers/test_rst/test_directives/test_include.py.
+
+  - Some line numbers in elements are not being set properly
+    (explicitly), just implicitly/automatically.  See rev. 1.74 of
+    docutils/parsers/rst/states.py for an example of how to set.
+
+* .. _none source:
+
+  Quite a few nodes are getting a "None" source attribute as well.  In
+  particular, see the bodies of definition lists.
+
+* Footnote label "5" should be "4" when processing the following
+  input::
+
+      ref [#abc]_ [#]_ [1]_ [#4]_
+
+      .. [#abc] footnote
+      .. [#] two
+      .. [1] one
+      .. [#4] four
+
+  Output::
+
+      
+          
+              ref
+              
+                  2
+
+              
+                  3
+
+              
+                  1
+
+              
+                  5
+          
+