georg.brandl
2008-09-13 17:18:21 UTC
Author: georg.brandl
Date: Sat Sep 13 19:18:21 2008
New Revision: 66448
Log:
Forward-port of r66447.
Modified:
python/branches/py3k/Doc/tutorial/classes.rst
python/branches/py3k/Doc/tutorial/controlflow.rst
python/branches/py3k/Doc/tutorial/datastructures.rst
python/branches/py3k/Doc/tutorial/introduction.rst
Modified: python/branches/py3k/Doc/tutorial/classes.rst
==============================================================================
--- python/branches/py3k/Doc/tutorial/classes.rst (original)
+++ python/branches/py3k/Doc/tutorial/classes.rst Sat Sep 13 19:18:21 2008
@@ -261,7 +261,7 @@
definition looked like this::
class MyClass:
- "A simple example class"
+ """A simple example class"""
i = 12345
def f(self):
return 'hello world'
Modified: python/branches/py3k/Doc/tutorial/controlflow.rst
==============================================================================
--- python/branches/py3k/Doc/tutorial/controlflow.rst (original)
+++ python/branches/py3k/Doc/tutorial/controlflow.rst Sat Sep 13 19:18:21 2008
@@ -17,6 +17,7 @@
... x = 0
... print('Negative changed to zero')
@@ -26,7 +27,8 @@
... print('Single')
... else:
... print('More')
- ...
+ ...
+ More
There can be zero or more :keyword:`elif` parts, and the :keyword:`else` part is
optional. The keyword ':keyword:`elif`' is short for 'else if', and is useful
@@ -191,7 +193,7 @@
- ... pass # Busy-wait for keyboard interrupt
+ ... pass # Busy-wait for keyboard interrupt (Ctrl+C)
...
@@ -223,14 +225,14 @@
The keyword :keyword:`def` introduces a function *definition*. It must be
followed by the function name and the parenthesized list of formal parameters.
The statements that form the body of the function start at the next line, and
-must be indented. The first statement of the function body can optionally be a
-string literal; this string literal is the function's documentation string, or
-:dfn:`docstring`.
+must be indented.
+The first statement of the function body can optionally be a string literal;
+this string literal is the function's documentation string, or :dfn:`docstring`.
+(More about docstrings can be found in the section :ref:`tut-docstrings`.)
There are tools which use docstrings to automatically produce online or printed
documentation, or to let the user interactively browse through code; it's good
-practice to include docstrings in code that you write, so try to make a habit of
-it.
+practice to include docstrings in code that you write, so make a habit of it.
The *execution* of a function introduces a new symbol table used for the local
variables of the function. More precisely, all variable assignments in a
@@ -259,12 +261,12 @@
-You might object that ``fib`` is not a function but a procedure. In Python,
-like in C, procedures are just functions that don't return a value. In fact,
-technically speaking, procedures do return a value, albeit a rather boring one.
-This value is called ``None`` (it's a built-in name). Writing the value
-``None`` is normally suppressed by the interpreter if it would be the only value
-written. You can see it if you really want to using :func:`print`::
+Coming from other languages, you might object that ``fib`` is not a function but
+a procedure since it doesn't return a value. In fact, even functions without a
+:keyword:`return` statement do return a value, albeit a rather boring one. This
+value is called ``None`` (it's a built-in name). Writing the value ``None`` is
+normally suppressed by the interpreter if it would be the only value written.
* The :keyword:`return` statement returns with a value from a function.
:keyword:`return` without an expression argument returns ``None``. Falling off
- the end of a procedure also returns ``None``.
+ the end of a function also returns ``None``.
* The statement ``result.append(b)`` calls a *method* of the list object
``result``. A method is a function that 'belongs' to an object and is named
@@ -432,20 +434,20 @@
function like this::
def cheeseshop(kind, *arguments, **keywords):
- print("-- Do you have any", kind, '?')
+ print("-- Do you have any", kind, "?")
print("-- I'm sorry, we're all out of", kind)
for arg in arguments: print(arg)
- print('-'*40)
+ print("-" * 40)
keys = sorted(keywords.keys())
- for kw in keys: print(kw, ':', keywords[kw])
+ for kw in keys: print(kw, ":", keywords[kw])
It could be called like this::
- cheeseshop('Limburger', "It's very runny, sir.",
+ cheeseshop("Limburger", "It's very runny, sir.",
"It's really very, VERY runny, sir.",
- client='John Cleese',
- shopkeeper='Michael Palin',
- sketch='Cheese Shop Sketch')
+ shopkeeper="Michael Palin",
+ client="John Cleese",
+ sketch="Cheese Shop Sketch")
and of course it would print::
@@ -472,8 +474,8 @@
Finally, the least frequently used option is to specify that a function can be
called with an arbitrary number of arguments. These arguments will be wrapped
-up in a tuple. Before the variable number of arguments, zero or more normal
-arguments may occur. ::
+up in a tuple (see :ref:`tut-tuples`). Before the variable number of arguments,
+zero or more normal arguments may occur. ::
def write_multiple_items(file, separator, *args):
file.write(separator.join(args))
@@ -644,7 +646,8 @@
* Name your classes and functions consistently; the convention is to use
``CamelCase`` for classes and ``lower_case_with_underscores`` for functions
- and methods. Always use ``self`` as the name for the first method argument.
+ and methods. Always use ``self`` as the name for the first method argument
+ (see :ref:`tut-firstclasses` for more on classes and methods).
* Don't use fancy encodings if your code is meant to be used in international
environments. Plain ASCII works best in any case.
Modified: python/branches/py3k/Doc/tutorial/datastructures.rst
==============================================================================
--- python/branches/py3k/Doc/tutorial/datastructures.rst (original)
+++ python/branches/py3k/Doc/tutorial/datastructures.rst Sat Sep 13 19:18:21 2008
@@ -292,6 +292,7 @@
is assigned to it). We'll find other uses for :keyword:`del` later.
+.. _tut-tuples:
Tuples and Sequences
====================
Modified: python/branches/py3k/Doc/tutorial/introduction.rst
==============================================================================
--- python/branches/py3k/Doc/tutorial/introduction.rst (original)
+++ python/branches/py3k/Doc/tutorial/introduction.rst Sat Sep 13 19:18:21 2008
@@ -13,9 +13,11 @@
Many of the examples in this manual, even those entered at the interactive
prompt, include comments. Comments in Python start with the hash character,
-``#``, and extend to the end of the physical line. A comment may appear at
-the start of a line or following whitespace or code, but not within a string
+``#``, and extend to the end of the physical line. A comment may appear at the
+start of a line or following whitespace or code, but not within a string
literal. A hash character within a string literal is just a hash character.
+Since comments are to clarify code and are not interpreted by Python, they may
+be omitted when typing in examples.
Some examples::
@@ -96,6 +98,15 @@
+Variables must be "defined" (assigned a value) before they can be used, or an
+error will occur::
+
+ >>> # try to access an undefined variable
+ ... n
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in <module>
+ NameError: name 'n' is not defined
+
There is full support for floating point; operators with mixed type operands
convert the integer operand to floating point::
@@ -290,7 +301,7 @@
-Unlike a C string, Python strings cannot be changed. Assigning to an indexed
+Unlike a C string, Python strings cannot be changed. Assigning to an indexed
.. sectionauthor:: Marc-Andre Lemburg <mal at lemburg.com>
-Starting with Python 3.0 all strings support Unicode.
-(See http://www.unicode.org/)
+Starting with Python 3.0 all strings support Unicode (see
+http://www.unicode.org/).
Unicode has the advantage of providing one ordinal for every character in every
script used in modern and ancient texts. Previously, there were only 256
Date: Sat Sep 13 19:18:21 2008
New Revision: 66448
Log:
Forward-port of r66447.
Modified:
python/branches/py3k/Doc/tutorial/classes.rst
python/branches/py3k/Doc/tutorial/controlflow.rst
python/branches/py3k/Doc/tutorial/datastructures.rst
python/branches/py3k/Doc/tutorial/introduction.rst
Modified: python/branches/py3k/Doc/tutorial/classes.rst
==============================================================================
--- python/branches/py3k/Doc/tutorial/classes.rst (original)
+++ python/branches/py3k/Doc/tutorial/classes.rst Sat Sep 13 19:18:21 2008
@@ -261,7 +261,7 @@
definition looked like this::
class MyClass:
- "A simple example class"
+ """A simple example class"""
i = 12345
def f(self):
return 'hello world'
Modified: python/branches/py3k/Doc/tutorial/controlflow.rst
==============================================================================
--- python/branches/py3k/Doc/tutorial/controlflow.rst (original)
+++ python/branches/py3k/Doc/tutorial/controlflow.rst Sat Sep 13 19:18:21 2008
@@ -17,6 +17,7 @@
x = int(input("Please enter an integer: "))
+ Please enter an integer: 42... x = 0
... print('Negative changed to zero')
@@ -26,7 +27,8 @@
... print('Single')
... else:
... print('More')
- ...
+ ...
+ More
There can be zero or more :keyword:`elif` parts, and the :keyword:`else` part is
optional. The keyword ':keyword:`elif`' is short for 'else if', and is useful
@@ -191,7 +193,7 @@
- ... pass # Busy-wait for keyboard interrupt
+ ... pass # Busy-wait for keyboard interrupt (Ctrl+C)
...
@@ -223,14 +225,14 @@
The keyword :keyword:`def` introduces a function *definition*. It must be
followed by the function name and the parenthesized list of formal parameters.
The statements that form the body of the function start at the next line, and
-must be indented. The first statement of the function body can optionally be a
-string literal; this string literal is the function's documentation string, or
-:dfn:`docstring`.
+must be indented.
+The first statement of the function body can optionally be a string literal;
+this string literal is the function's documentation string, or :dfn:`docstring`.
+(More about docstrings can be found in the section :ref:`tut-docstrings`.)
There are tools which use docstrings to automatically produce online or printed
documentation, or to let the user interactively browse through code; it's good
-practice to include docstrings in code that you write, so try to make a habit of
-it.
+practice to include docstrings in code that you write, so make a habit of it.
The *execution* of a function introduces a new symbol table used for the local
variables of the function. More precisely, all variable assignments in a
@@ -259,12 +261,12 @@
f(100)
1 1 2 3 5 8 13 21 34 55 89-You might object that ``fib`` is not a function but a procedure. In Python,
-like in C, procedures are just functions that don't return a value. In fact,
-technically speaking, procedures do return a value, albeit a rather boring one.
-This value is called ``None`` (it's a built-in name). Writing the value
-``None`` is normally suppressed by the interpreter if it would be the only value
-written. You can see it if you really want to using :func:`print`::
+Coming from other languages, you might object that ``fib`` is not a function but
+a procedure since it doesn't return a value. In fact, even functions without a
+:keyword:`return` statement do return a value, albeit a rather boring one. This
+value is called ``None`` (it's a built-in name). Writing the value ``None`` is
+normally suppressed by the interpreter if it would be the only value written.
fib(0)
print(fib(0))
@@ -290,7 +292,7 @@print(fib(0))
* The :keyword:`return` statement returns with a value from a function.
:keyword:`return` without an expression argument returns ``None``. Falling off
- the end of a procedure also returns ``None``.
+ the end of a function also returns ``None``.
* The statement ``result.append(b)`` calls a *method* of the list object
``result``. A method is a function that 'belongs' to an object and is named
@@ -432,20 +434,20 @@
function like this::
def cheeseshop(kind, *arguments, **keywords):
- print("-- Do you have any", kind, '?')
+ print("-- Do you have any", kind, "?")
print("-- I'm sorry, we're all out of", kind)
for arg in arguments: print(arg)
- print('-'*40)
+ print("-" * 40)
keys = sorted(keywords.keys())
- for kw in keys: print(kw, ':', keywords[kw])
+ for kw in keys: print(kw, ":", keywords[kw])
It could be called like this::
- cheeseshop('Limburger', "It's very runny, sir.",
+ cheeseshop("Limburger", "It's very runny, sir.",
"It's really very, VERY runny, sir.",
- client='John Cleese',
- shopkeeper='Michael Palin',
- sketch='Cheese Shop Sketch')
+ shopkeeper="Michael Palin",
+ client="John Cleese",
+ sketch="Cheese Shop Sketch")
and of course it would print::
@@ -472,8 +474,8 @@
Finally, the least frequently used option is to specify that a function can be
called with an arbitrary number of arguments. These arguments will be wrapped
-up in a tuple. Before the variable number of arguments, zero or more normal
-arguments may occur. ::
+up in a tuple (see :ref:`tut-tuples`). Before the variable number of arguments,
+zero or more normal arguments may occur. ::
def write_multiple_items(file, separator, *args):
file.write(separator.join(args))
@@ -644,7 +646,8 @@
* Name your classes and functions consistently; the convention is to use
``CamelCase`` for classes and ``lower_case_with_underscores`` for functions
- and methods. Always use ``self`` as the name for the first method argument.
+ and methods. Always use ``self`` as the name for the first method argument
+ (see :ref:`tut-firstclasses` for more on classes and methods).
* Don't use fancy encodings if your code is meant to be used in international
environments. Plain ASCII works best in any case.
Modified: python/branches/py3k/Doc/tutorial/datastructures.rst
==============================================================================
--- python/branches/py3k/Doc/tutorial/datastructures.rst (original)
+++ python/branches/py3k/Doc/tutorial/datastructures.rst Sat Sep 13 19:18:21 2008
@@ -292,6 +292,7 @@
is assigned to it). We'll find other uses for :keyword:`del` later.
+.. _tut-tuples:
Tuples and Sequences
====================
Modified: python/branches/py3k/Doc/tutorial/introduction.rst
==============================================================================
--- python/branches/py3k/Doc/tutorial/introduction.rst (original)
+++ python/branches/py3k/Doc/tutorial/introduction.rst Sat Sep 13 19:18:21 2008
@@ -13,9 +13,11 @@
Many of the examples in this manual, even those entered at the interactive
prompt, include comments. Comments in Python start with the hash character,
-``#``, and extend to the end of the physical line. A comment may appear at
-the start of a line or following whitespace or code, but not within a string
+``#``, and extend to the end of the physical line. A comment may appear at the
+start of a line or following whitespace or code, but not within a string
literal. A hash character within a string literal is just a hash character.
+Since comments are to clarify code and are not interpreted by Python, they may
+be omitted when typing in examples.
Some examples::
@@ -96,6 +98,15 @@
z
0+Variables must be "defined" (assigned a value) before they can be used, or an
+error will occur::
+
+ >>> # try to access an undefined variable
+ ... n
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in <module>
+ NameError: name 'n' is not defined
+
There is full support for floating point; operators with mixed type operands
convert the integer operand to floating point::
@@ -290,7 +301,7 @@
word[2:] # Everything except the first two characters
'lpA'-Unlike a C string, Python strings cannot be changed. Assigning to an indexed
+Unlike a C string, Python strings cannot be changed. Assigning to an indexed
word[0] = 'x'
@@ -409,8 +420,8 @@.. sectionauthor:: Marc-Andre Lemburg <mal at lemburg.com>
-Starting with Python 3.0 all strings support Unicode.
-(See http://www.unicode.org/)
+Starting with Python 3.0 all strings support Unicode (see
+http://www.unicode.org/).
Unicode has the advantage of providing one ordinal for every character in every
script used in modern and ancient texts. Previously, there were only 256