From 3ce0dee9a3a5bce536ddab38bf233deaaded00e0 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 13 Sep 2008 17:18:11 +0000 Subject: [PATCH] Incorporate some suggestions by Tait Stevens. --- Doc/tutorial/classes.rst | 2 +- Doc/tutorial/controlflow.rst | 49 +++++++++++++++++---------------- Doc/tutorial/datastructures.rst | 1 + Doc/tutorial/introduction.rst | 17 ++++++++++-- 4 files changed, 42 insertions(+), 27 deletions(-) diff --git a/Doc/tutorial/classes.rst b/Doc/tutorial/classes.rst index bca91080056..43f2c6da798 100644 --- a/Doc/tutorial/classes.rst +++ b/Doc/tutorial/classes.rst @@ -208,7 +208,7 @@ the class's namespace when the class object was created. So, if the class definition looked like this:: class MyClass: - "A simple example class" + """A simple example class""" i = 12345 def f(self): return 'hello world' diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst index 4fa9858765d..a77618fce08 100644 --- a/Doc/tutorial/controlflow.rst +++ b/Doc/tutorial/controlflow.rst @@ -17,6 +17,7 @@ Perhaps the most well-known statement type is the :keyword:`if` statement. For example:: >>> x = int(raw_input("Please enter an integer: ")) + Please enter an integer: 42 >>> if x < 0: ... x = 0 ... print 'Negative changed to zero' @@ -26,7 +27,8 @@ example:: ... 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 @@ -161,7 +163,7 @@ The :keyword:`pass` statement does nothing. It can be used when a statement is required syntactically but the program requires no action. For example:: >>> while True: - ... pass # Busy-wait for keyboard interrupt + ... pass # Busy-wait for keyboard interrupt (Ctrl+C) ... @@ -192,14 +194,14 @@ boundary:: 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 @@ -228,12 +230,12 @@ mechanism:: >>> 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 :keyword:`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. +You can see it if you really want to using :keyword:`print`:: >>> fib(0) >>> print fib(0) @@ -259,7 +261,7 @@ This example, as usual, demonstrates some new Python features: * 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 @@ -400,21 +402,21 @@ 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, '?' + 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 = keywords.keys() keys.sort() - 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') + client="John Cleese", + sketch="Cheese Shop Sketch") and of course it would print:: @@ -442,8 +444,8 @@ Arbitrary Argument Lists 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)) @@ -600,7 +602,8 @@ extracted for you: * 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. diff --git a/Doc/tutorial/datastructures.rst b/Doc/tutorial/datastructures.rst index fa718702496..931f506ef7e 100644 --- a/Doc/tutorial/datastructures.rst +++ b/Doc/tutorial/datastructures.rst @@ -345,6 +345,7 @@ of an empty list to the slice). For example:: Referencing the name ``a`` hereafter is an error (at least until another value is assigned to it). We'll find other uses for :keyword:`del` later. +.. _tut-tuples: .. _tut-tuples: diff --git a/Doc/tutorial/introduction.rst b/Doc/tutorial/introduction.rst index c138ce69eb3..797e531270f 100644 --- a/Doc/tutorial/introduction.rst +++ b/Doc/tutorial/introduction.rst @@ -13,9 +13,11 @@ end a multi-line command. 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:: @@ -77,6 +79,15 @@ A value can be assigned to several variables simultaneously:: >>> 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 "", line 1, in + 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:: @@ -269,7 +280,7 @@ omitted second index defaults to the size of the string being sliced. :: >>> 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 position in the string results in an error:: >>> word[0] = 'x'