diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -1772,10 +1772,11 @@ .. attribute:: buffer - If set to true, ``sys.stdout`` and ``sys.stderr`` will be buffered in between - :meth:`startTest` and :meth:`stopTest` being called. Collected output will - only be echoed onto the real ``sys.stdout`` and ``sys.stderr`` if the test - fails or errors. Any output is also attached to the failure / error message. + If set to true, :func:`sys.stdout` and :func:`sys.stderr` will be buffered + in between :meth:`startTest` and :meth:`stopTest` being called. Collected + output will only be echoed onto the real :func:`sys.stdout` and :func:`sys.stderr` + if the test fails or errors. Any output is also attached to the + failure / error message. .. versionadded:: 3.2 diff --git a/Doc/library/wsgiref.rst b/Doc/library/wsgiref.rst --- a/Doc/library/wsgiref.rst +++ b/Doc/library/wsgiref.rst @@ -352,7 +352,7 @@ .. method:: WSGIRequestHandler.get_stderr() Return the object that should be used as the ``wsgi.errors`` stream. The default - implementation just returns ``sys.stderr``. + implementation just returns :func:`sys.stderr`. .. method:: WSGIRequestHandler.handle() @@ -397,13 +397,13 @@ example, :mod:`wsgiref.simple_server` and other servers based on :mod:`wsgiref.handlers` (that don't override the error handling methods to do something else) will simply output a message that an error has occurred, and - dump the traceback to ``sys.stderr`` or some other error stream. + dump the traceback to :func:`sys.stderr` or some other error stream. This wrapper may also generate output using the :mod:`warnings` module to indicate behaviors that are questionable but which may not actually be prohibited by :pep:`3333`. Unless they are suppressed using Python command-line options or the :mod:`warnings` API, any such warnings will be written to - ``sys.stderr`` (*not* ``wsgi.errors``, unless they happen to be the same + :func:`sys.stderr` (*not* ``wsgi.errors``, unless they happen to be the same object). Example usage:: @@ -445,10 +445,10 @@ .. class:: CGIHandler() - CGI-based invocation via ``sys.stdin``, ``sys.stdout``, ``sys.stderr`` and - ``os.environ``. This is useful when you have a WSGI application and want to run - it as a CGI script. Simply invoke ``CGIHandler().run(app)``, where ``app`` is - the WSGI application object you wish to invoke. + CGI-based invocation via :func:`sys.stdin`, :func:`sys.stdout`, :func:`sys.stderr` + and ``os.environ``. This is useful when you have a WSGI application and want + to run it as a CGI script. Simply invoke ``CGIHandler().run(app)``, where + ``app`` is the WSGI application object you wish to invoke. This class is a subclass of :class:`BaseCGIHandler` that sets ``wsgi.run_once`` to true, ``wsgi.multithread`` to false, and ``wsgi.multiprocess`` to true, and @@ -650,7 +650,7 @@ This method is a WSGI application to generate an error page for the user. It is only invoked if an error occurs before headers are sent to the client. - This method can access the current error information using ``sys.exc_info()``, + This method can access the current error information using :func:`sys.exc_info()`, and should pass that information to *start_response* when calling it (as described in the "Error Handling" section of :pep:`3333`). diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst --- a/Doc/library/zipfile.rst +++ b/Doc/library/zipfile.rst @@ -230,7 +230,7 @@ .. method:: ZipFile.printdir() - Print a table of contents for the archive to ``sys.stdout``. + Print a table of contents for the archive to :meth:`sys.stdout`. .. method:: ZipFile.setpassword(pwd) @@ -314,7 +314,7 @@ The level of debug output to use. This may be set from ``0`` (the default, no output) to ``3`` (the most output). Debugging information is written to - ``sys.stdout``. + :meth:`sys.stdout`. .. attribute:: ZipFile.comment diff --git a/Doc/library/zipimport.rst b/Doc/library/zipimport.rst --- a/Doc/library/zipimport.rst +++ b/Doc/library/zipimport.rst @@ -9,11 +9,11 @@ This module adds the ability to import Python modules (:file:`\*.py`, :file:`\*.py[co]`) and packages from ZIP-format archives. It is usually not needed to use the :mod:`zipimport` module explicitly; it is automatically used -by the built-in :keyword:`import` mechanism for ``sys.path`` items that are paths +by the built-in :keyword:`import` mechanism for :func:`sys.path` items that are paths to ZIP archives. -Typically, ``sys.path`` is a list of directory names as strings. This module -also allows an item of ``sys.path`` to be a string naming a ZIP file archive. +Typically, :func:`sys.path` is a list of directory names as strings. This module +also allows an item of :func:`sys.path` to be a string naming a ZIP file archive. The ZIP archive can contain a subdirectory structure to support package imports, and a path within the archive can be specified to only import from a subdirectory. For example, the path :file:`/tmp/example.zip/lib/` would only diff --git a/Doc/library/zlib.rst b/Doc/library/zlib.rst --- a/Doc/library/zlib.rst +++ b/Doc/library/zlib.rst @@ -18,7 +18,7 @@ consult the zlib manual at http://www.zlib.net/manual.html for authoritative information. -For reading and writing ``.gz`` files see the :mod:`gzip` module. For +For reading and writing :file:`.gz` files see the :mod:`gzip` module. For other archive formats, see the :mod:`bz2`, :mod:`zipfile`, and :mod:`tarfile` modules. diff --git a/Doc/tutorial/classes.rst b/Doc/tutorial/classes.rst --- a/Doc/tutorial/classes.rst +++ b/Doc/tutorial/classes.rst @@ -440,10 +440,10 @@ return 'hello world' h = g -Now ``f``, ``g`` and ``h`` are all attributes of class :class:`C` that refer to -function objects, and consequently they are all methods of instances of -:class:`C` --- ``h`` being exactly equivalent to ``g``. Note that this practice -usually only serves to confuse the reader of a program. +Now :attr:`f`, :attr:`g` and :attr:`h` are all attributes of class :class:`C` +that refer to function objects, and consequently they are all methods of +instances of :class:`C` --- :attr:`h` being exactly equivalent to :attr:`g`. +Note that this practice usually only serves to confuse the reader of a program. Methods may call other methods by using method attributes of the ``self`` argument:: @@ -501,7 +501,7 @@ applied recursively if the base class itself is derived from some other class. There's nothing special about instantiation of derived classes: -``DerivedClassName()`` creates a new instance of the class. Method references +:class:`DerivedClassName` creates a new instance of the class. Method references are resolved as follows: the corresponding class attribute is searched, descending down the chain of base classes if necessary, and the method reference is valid if this yields a function object. @@ -516,8 +516,8 @@ simply replace the base class method of the same name. There is a simple way to call the base class method directly: just call ``BaseClassName.methodname(self, arguments)``. This is occasionally useful to clients as well. (Note that this -only works if the base class is accessible as ``BaseClassName`` in the global -scope.) +only works if the base class is accessible as :class:`BaseClassName` in the +global scope.) Python has two built-in functions that work with inheritance: @@ -599,11 +599,11 @@ possible to access or modify a variable that is considered private. This can even be useful in special circumstances, such as in the debugger. -Notice that code passed to ``exec()`` or ``eval()`` does not consider the +Notice that code passed to :func:`exec` or :func:`eval` does not consider the classname of the invoking class to be the current class; this is similar to the -effect of the ``global`` statement, the effect of which is likewise restricted +effect of the :keyword:`global` statement, the effect of which is likewise restricted to code that is byte-compiled together. The same restriction applies to -``getattr()``, ``setattr()`` and ``delattr()``, as well as when referencing +:func:`getattr`, :func:`setattr` and :func:`delattr`, as well as when referencing ``__dict__`` directly. diff --git a/Doc/tutorial/interpreter.rst b/Doc/tutorial/interpreter.rst --- a/Doc/tutorial/interpreter.rst +++ b/Doc/tutorial/interpreter.rst @@ -71,7 +71,7 @@ When known to the interpreter, the script name and additional arguments thereafter are turned into a list of strings and assigned to the ``argv`` -variable in the ``sys`` module. You can access this list by executing ``import +variable in the :mod:`sys` module. You can access this list by executing ``import sys``. The length of the list is at least one; when no script and no arguments are given, ``sys.argv[0]`` is an empty string. When the script name is given as ``'-'`` (meaning standard input), ``sys.argv[0]`` is set to ``'-'``. When @@ -163,9 +163,9 @@ $ chmod +x myscript.py On Windows systems, there is no notion of an "executable mode". The Python -installer automatically associates ``.py`` files with ``python.exe`` so that +installer automatically associates :file:`.py` files with ``python.exe`` so that a double-click on a Python file will run it as a script. The extension can -also be ``.pyw``, in that case, the console window that normally appears is +also be :file:`.pyw`, in that case, the console window that normally appears is suppressed. @@ -221,8 +221,8 @@ commands (which otherwise behaves like an interactive session). It is executed in the same namespace where interactive commands are executed, so that objects that it defines or imports can be used without qualification in the interactive -session. You can also change the prompts ``sys.ps1`` and ``sys.ps2`` in this -file. +session. You can also change the prompts :func:`sys.ps1` and :func:`sys.ps2` in +this file. If you want to read an additional start-up file from the current directory, you can program this in the global start-up file using code like ``if diff --git a/Doc/tutorial/modules.rst b/Doc/tutorial/modules.rst --- a/Doc/tutorial/modules.rst +++ b/Doc/tutorial/modules.rst @@ -169,7 +169,7 @@ :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 +:func:`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 @@ -204,8 +204,8 @@ * When the Python interpreter is invoked with the :option:`-O` flag, optimized code is generated and stored in :file:`.pyo` files. The optimizer currently doesn't help much; it only removes :keyword:`assert` statements. When - :option:`-O` is used, *all* :term:`bytecode` is optimized; ``.pyc`` files are - ignored and ``.py`` files are compiled to optimized bytecode. + :option:`-O` is used, *all* :term:`bytecode` is optimized; :file:`.pyc` files are + ignored and :file:`.py` files are compiled to optimized bytecode. * Passing two :option:`-O` flags to the Python interpreter (:option:`-OO`) will cause the bytecode compiler to perform optimizations that could in some rare @@ -253,7 +253,7 @@ 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 +:func:`sys.ps1` and :func:`sys.ps2` define the strings used as primary and secondary prompts:: >>> import sys @@ -269,7 +269,7 @@ These two variables are only defined if the interpreter is in interactive mode. -The variable ``sys.path`` is a list of strings that determines the interpreter's +The variable :func:`sys.path` is a list of strings that determines the interpreter's search path for modules. It is initialized to a default path taken from the environment variable :envvar:`PYTHONPATH`, or from a built-in default if :envvar:`PYTHONPATH` is not set. You can modify it using standard list @@ -391,7 +391,7 @@ ... When importing the package, Python searches through the directories on -``sys.path`` looking for the package subdirectory. +:func:`sys.path` looking for the package subdirectory. The :file:`__init__.py` files are required to make Python treat the directories as containing packages; this is done to prevent directories with a common name, @@ -430,7 +430,7 @@ Note that when using ``from package import item``, the item can be either a submodule (or subpackage) of the package, or some other name defined in the -package, like a function, class or variable. The ``import`` statement first +package, like a function, class or variable. The :keyword:`import` statement first tests whether the item is defined in the package; if not, it assumes it is a module and attempts to load it. If it fails to find it, an :exc:`ImportError` exception is raised. diff --git a/Doc/tutorial/stdlib.rst b/Doc/tutorial/stdlib.rst --- a/Doc/tutorial/stdlib.rst +++ b/Doc/tutorial/stdlib.rst @@ -87,7 +87,7 @@ >>> sys.stderr.write('Warning, log file not found starting a new one\n') Warning, log file not found starting a new one -The most direct way to terminate a script is to use ``sys.exit()``. +The most direct way to terminate a script is to use :func:`sys.exit`. .. _tut-string-pattern-matching: diff --git a/Doc/tutorial/stdlib2.rst b/Doc/tutorial/stdlib2.rst --- a/Doc/tutorial/stdlib2.rst +++ b/Doc/tutorial/stdlib2.rst @@ -211,7 +211,7 @@ ======= 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``:: +At its simplest, log messages are sent to a file or to :func:`sys.stderr`:: import logging logging.debug('Debugging information')