diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/Makefile | 16 | ||||
| -rw-r--r-- | Doc/README.txt | 4 | ||||
| -rw-r--r-- | Doc/conf.py | 24 | ||||
| -rw-r--r-- | Doc/includes/email-alternative.py | 48 | ||||
| -rw-r--r-- | Doc/library/email-examples.rst | 11 | ||||
| -rw-r--r-- | Doc/library/queue.rst | 2 | ||||
| -rw-r--r-- | Doc/library/socket.rst | 2 | ||||
| -rw-r--r-- | Doc/library/urllib2.rst | 39 | ||||
| -rw-r--r-- | Doc/make.bat (renamed from Doc/builddoc.bat) | 0 | ||||
| -rw-r--r-- | Doc/reference/datamodel.rst | 2 |
10 files changed, 116 insertions, 32 deletions
diff --git a/Doc/Makefile b/Doc/Makefile index 189a2f7..95718d7 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -16,11 +16,12 @@ ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees -D latex_paper_size=$(PAPER) \ help: @echo "Please use \`make <target>' where <target> 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" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " changes to make an overview over all changed/added/deprecated items" + @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" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " changes to make an overview over all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" checkout: @if [ ! -d tools/sphinx ]; then \ @@ -71,6 +72,11 @@ changes: BUILDER = changes changes: build @echo "The overview file is in build/changes." +linkcheck: BUILDER = linkcheck +linkcheck: build + @echo "Link check complete; look for any errors in the above output "\ + "or in build/$(BUILDER)/output.txt" + clean: -rm -rf build/* -rm -rf tools/sphinx diff --git a/Doc/README.txt b/Doc/README.txt index c6f685c..a93542f 100644 --- a/Doc/README.txt +++ b/Doc/README.txt @@ -55,6 +55,10 @@ Available make targets are: * "latex", which builds LaTeX source files that can be run with "pdflatex" to produce PDF documents. + + * "linkcheck", which checks all external references to see whether they are + broken, redirected or malformed, and outputs this information to stdout + as well as a plain-text (.txt) file. * "changes", which builds an overview over all versionadded/versionchanged/ deprecated items in the current version. This is meant as a help for the diff --git a/Doc/conf.py b/Doc/conf.py index 3c33f98..273c76c 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -103,29 +103,29 @@ latex_font_size = '10pt' # (source start file, target name, title, author, document class [howto/manual]). _stdauthor = r'Guido van Rossum\\Fred L. Drake, Jr., editor' latex_documents = [ - ('c-api/index.rst', 'c-api.tex', + ('c-api/index', 'c-api.tex', 'The Python/C API', _stdauthor, 'manual'), - ('distutils/index.rst', 'distutils.tex', + ('distutils/index', 'distutils.tex', 'Distributing Python Modules', _stdauthor, 'manual'), - ('documenting/index.rst', 'documenting.tex', + ('documenting/index', 'documenting.tex', 'Documenting Python', 'Georg Brandl', 'manual'), - ('extending/index.rst', 'extending.tex', + ('extending/index', 'extending.tex', 'Extending and Embedding Python', _stdauthor, 'manual'), - ('install/index.rst', 'install.tex', + ('install/index', 'install.tex', 'Installing Python Modules', _stdauthor, 'manual'), - ('library/index.rst', 'library.tex', + ('library/index', 'library.tex', 'The Python Library Reference', _stdauthor, 'manual'), - ('reference/index.rst', 'reference.tex', + ('reference/index', 'reference.tex', 'The Python Language Reference', _stdauthor, 'manual'), - ('tutorial/index.rst', 'tutorial.tex', + ('tutorial/index', 'tutorial.tex', 'Python Tutorial', _stdauthor, 'manual'), - ('using/index.rst', 'using.tex', + ('using/index', 'using.tex', 'Using Python', _stdauthor, 'manual'), - ('whatsnew/' + version + '.rst', 'whatsnew.tex', + ('whatsnew/' + version, 'whatsnew.tex', 'What\'s New in Python', 'A. M. Kuchling', 'howto'), ] # Collect all HOWTOs individually -latex_documents.extend(('howto/' + fn, 'howto-' + fn[:-4] + '.tex', +latex_documents.extend(('howto/' + fn[:-4], 'howto-' + fn[:-4] + '.tex', 'HOWTO', _stdauthor, 'howto') for fn in os.listdir('howto') if fn.endswith('.rst') and fn != 'index.rst') @@ -139,4 +139,4 @@ latex_preamble = r''' ''' # Documents to append as an appendix to all manuals. -latex_appendices = ['glossary.rst', 'about.rst', 'license.rst', 'copyright.rst'] +latex_appendices = ['glossary', 'about', 'license', 'copyright'] diff --git a/Doc/includes/email-alternative.py b/Doc/includes/email-alternative.py new file mode 100644 index 0000000..d941323 --- /dev/null +++ b/Doc/includes/email-alternative.py @@ -0,0 +1,48 @@ +#! /usr/bin/python + +import smtplib + +from email.mime.multipart import MIMEMultipart +from email.mime.text import MIMEText + +# me == my email address +# you == recipient's email address +me = "my@email.com" +you = "your@email.com" + +# Create message container - the correct MIME type is multipart/alternative. +msg = MIMEMultipart('alternative') +msg['Subject'] = "Link" +msg['From'] = me +msg['To'] = you + +# Create the body of the message (a plain-text and an HTML version). +text = "Hi!\nHow are you?\nHere is the link you wanted:\nhttp://www.python.org" +html = """\ +<html> + <head></head> + <body> + <p>Hi!<br> + How are you?<br> + Here is the <a href="http://www.python.org">link</a> you wanted. + </p> + </body> +</html> +""" + +# Record the MIME types of both parts - text/plain and text/html. +part1 = MIMEText(text, 'plain') +part2 = MIMEText(html, 'html') + +# Attach parts into message container. +# According to RFC 2046, the last part of a multipart message, in this case +# the HTML message, is best and preferred. +msg.attach(part1) +msg.attach(part2) + +# Send the message via local SMTP server. +s = smtplib.SMTP('localhost') +# sendmail function takes 3 arguments: sender's address, recipient's address +# and message to send - here it is sent as one string. +s.sendmail(me, you, msg.as_string()) +s.close() diff --git a/Doc/library/email-examples.rst b/Doc/library/email-examples.rst index 64a9944..f606f9b 100644 --- a/Doc/library/email-examples.rst +++ b/Doc/library/email-examples.rst @@ -16,18 +16,23 @@ pictures that may be residing in a directory: Here's an example of how to send the entire contents of a directory as an email -message: [1]_ +message: [1]_ .. literalinclude:: ../includes/email-dir.py -And finally, here's an example of how to unpack a MIME message like the one +Here's an example of how to unpack a MIME message like the one above, into a directory of files: .. literalinclude:: ../includes/email-unpack.py +Here's an example of how to create an HTML message with an alternative plain +text version: [2]_ + +.. literalinclude:: ../includes/email-alternative.py + .. rubric:: Footnotes .. [1] Thanks to Matthew Dixon Cowles for the original inspiration and examples. - +.. [2] Contributed by Martin Matejek. diff --git a/Doc/library/queue.rst b/Doc/library/queue.rst index 582f2cd..b5ba24d 100644 --- a/Doc/library/queue.rst +++ b/Doc/library/queue.rst @@ -71,7 +71,7 @@ The :mod:`Queue` module defines the following classes and exceptions: Queue Objects ------------- -Queue objects (:class:``Queue``, :class:``LifoQueue``, or :class:``PriorityQueue`` +Queue objects (:class:`Queue`, :class:`LifoQueue`, or :class:`PriorityQueue`) provide the public methods described below. diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index 7d2dea0..cb1b87c 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -23,7 +23,7 @@ PS1:7 and PS1:8). The platform-specific reference material for the various socket-related system calls are also a valuable source of information on the details of socket semantics. For Unix, refer to the manual pages; for Windows, see the WinSock (or Winsock 2) specification. For IPv6-ready APIs, readers may -want to refer to :rfc:`2553` titled Basic Socket Interface Extensions for IPv6. +want to refer to :rfc:`3493` titled Basic Socket Interface Extensions for IPv6. .. index:: object: socket diff --git a/Doc/library/urllib2.rst b/Doc/library/urllib2.rst index b3e5485..d77712f 100644 --- a/Doc/library/urllib2.rst +++ b/Doc/library/urllib2.rst @@ -33,10 +33,12 @@ The :mod:`urllib2` module defines the following functions: 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, commonly used to + determine if a redirect was followed - * :meth:`info` --- return the meta-information of the page, as a dictionary-like - object + * :meth:`info` --- return the meta-information of the page, such as headers, in + the form of an ``httplib.HTTPMessage`` instance + (see `Quick Reference to HTTP Headers <http://www.cs.tut.fi/~jkorpela/http.html>`_) Raises :exc:`URLError` on errors. @@ -81,18 +83,32 @@ The following exceptions are raised as appropriate: The handlers raise this exception (or derived exceptions) when they run into a problem. It is a subclass of :exc:`IOError`. + .. attribute:: reason + + The reason for this error. It can be a message string or another exception + instance (:exc:`socket.error` for remote URLs, :exc:`OSError` for local + URLs). + .. 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. + Though being an exception (a subclass of :exc:`URLError`), an :exc:`HTTPError` + 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. + + .. attribute:: code + + An HTTP status code as defined in `RFC 2616 <http://www.faqs.org/rfcs/rfc2616.html>`_. + This numeric value corresponds to a value found in the dictionary of + codes as found in :attr:`BaseHTTPServer.BaseHTTPRequestHandler.responses`. + + The following classes are provided: -.. class:: Request(url[, data][, headers] [, origin_req_host][, unverifiable]) +.. class:: Request(url[, data][, headers][, origin_req_host][, unverifiable]) This class is an abstraction of a URL request. @@ -107,7 +123,12 @@ The following classes are provided: returns a string in this format. *headers* should be a dictionary, and will be treated as if :meth:`add_header` - was called with each key and value as arguments. + was called with each key and value as arguments. This is often used to "spoof" + the ``User-Agent`` header, which is used by a browser to identify itself -- + some HTTP servers only allow requests coming from common browsers as opposed + to scripts. For example, Mozilla Firefox may identify itself as ``"Mozilla/5.0 + (X11; U; Linux i686) Gecko/20071127 Firefox/2.0.0.11"``, while :mod:`urllib2`'s + default user agent string is ``"Python-urllib/2.6"`` (on Python 2.6). The final two arguments are only of interest for correct handling of third-party HTTP cookies: diff --git a/Doc/builddoc.bat b/Doc/make.bat index a26851f..a26851f 100644 --- a/Doc/builddoc.bat +++ b/Doc/make.bat diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 3a6b527..0ab5f11 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -991,7 +991,7 @@ that all old-style instances, independently of their class, are implemented with a single built-in type, called ``instance``. New-style classes were introduced in Python 2.2 to unify classes and types. A -new-style class neither more nor less than a user-defined type. If *x* is an +new-style class is neither more nor less than a user-defined type. If *x* is an instance of a new-style class, then ``type(x)`` is the same as ``x.__class__``. The major motivation for introducing new-style classes is to provide a unified |