diff -r ffa851df0825 -r 2fb8b9db1c86 symbian-qemu-0.9.1-12/python-2.6.1/Doc/tutorial/introduction.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/symbian-qemu-0.9.1-12/python-2.6.1/Doc/tutorial/introduction.rst Fri Jul 31 15:01:17 2009 +0100 @@ -0,0 +1,652 @@ +.. _tut-informal: + +********************************** +An Informal Introduction to Python +********************************** + +In the following examples, input and output are distinguished by the presence or +absence of prompts (``>>>`` and ``...``): to repeat the example, you must type +everything after the prompt, when the prompt appears; lines that do not begin +with a prompt are output from the interpreter. Note that a secondary prompt on a +line by itself in an example means you must type a blank line; this is used to +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 +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:: + + # this is the first comment + SPAM = 1 # and this is the second comment + # ... and now a third! + STRING = "# This is not a comment." + + +.. _tut-calculator: + +Using Python as a Calculator +============================ + +Let's try some simple Python commands. Start the interpreter and wait for the +primary prompt, ``>>>``. (It shouldn't take long.) + + +.. _tut-numbers: + +Numbers +------- + +The interpreter acts as a simple calculator: you can type an expression at it +and it will write the value. Expression syntax is straightforward: the +operators ``+``, ``-``, ``*`` and ``/`` work just like in most other languages +(for example, Pascal or C); parentheses can be used for grouping. For example:: + + >>> 2+2 + 4 + >>> # This is a comment + ... 2+2 + 4 + >>> 2+2 # and a comment on the same line as code + 4 + >>> (50-5*6)/4 + 5 + >>> # Integer division returns the floor: + ... 7/3 + 2 + >>> 7/-3 + -3 + +The equal sign (``'='``) is used to assign a value to a variable. Afterwards, no +result is displayed before the next interactive prompt:: + + >>> width = 20 + >>> height = 5*9 + >>> width * height + 900 + +A value can be assigned to several variables simultaneously:: + + >>> x = y = z = 0 # Zero x, y and z + >>> x + 0 + >>> y + 0 + >>> 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:: + + >>> 3 * 3.75 / 1.5 + 7.5 + >>> 7.0 / 2 + 3.5 + +Complex numbers are also supported; imaginary numbers are written with a suffix +of ``j`` or ``J``. Complex numbers with a nonzero real component are written as +``(real+imagj)``, or can be created with the ``complex(real, imag)`` function. +:: + + >>> 1j * 1J + (-1+0j) + >>> 1j * complex(0,1) + (-1+0j) + >>> 3+1j*3 + (3+3j) + >>> (3+1j)*3 + (9+3j) + >>> (1+2j)/(1+1j) + (1.5+0.5j) + +Complex numbers are always represented as two floating point numbers, the real +and imaginary part. To extract these parts from a complex number *z*, use +``z.real`` and ``z.imag``. :: + + >>> a=1.5+0.5j + >>> a.real + 1.5 + >>> a.imag + 0.5 + +The conversion functions to floating point and integer (:func:`float`, +:func:`int` and :func:`long`) don't work for complex numbers --- there is no one +correct way to convert a complex number to a real number. Use ``abs(z)`` to get +its magnitude (as a float) or ``z.real`` to get its real part. :: + + >>> a=3.0+4.0j + >>> float(a) + Traceback (most recent call last): + File "", line 1, in ? + TypeError: can't convert complex to float; use abs(z) + >>> a.real + 3.0 + >>> a.imag + 4.0 + >>> abs(a) # sqrt(a.real**2 + a.imag**2) + 5.0 + >>> + +In interactive mode, the last printed expression is assigned to the variable +``_``. This means that when you are using Python as a desk calculator, it is +somewhat easier to continue calculations, for example:: + + >>> tax = 12.5 / 100 + >>> price = 100.50 + >>> price * tax + 12.5625 + >>> price + _ + 113.0625 + >>> round(_, 2) + 113.06 + >>> + +This variable should be treated as read-only by the user. Don't explicitly +assign a value to it --- you would create an independent local variable with the +same name masking the built-in variable with its magic behavior. + + +.. _tut-strings: + +Strings +------- + +Besides numbers, Python can also manipulate strings, which can be expressed in +several ways. They can be enclosed in single quotes or double quotes:: + + >>> 'spam eggs' + 'spam eggs' + >>> 'doesn\'t' + "doesn't" + >>> "doesn't" + "doesn't" + >>> '"Yes," he said.' + '"Yes," he said.' + >>> "\"Yes,\" he said." + '"Yes," he said.' + >>> '"Isn\'t," she said.' + '"Isn\'t," she said.' + +String literals can span multiple lines in several ways. Continuation lines can +be used, with a backslash as the last character on the line indicating that the +next line is a logical continuation of the line:: + + hello = "This is a rather long string containing\n\ + several lines of text just as you would do in C.\n\ + Note that whitespace at the beginning of the line is\ + significant." + + print hello + +Note that newlines still need to be embedded in the string using ``\n``; the +newline following the trailing backslash is discarded. This example would print +the following:: + + This is a rather long string containing + several lines of text just as you would do in C. + Note that whitespace at the beginning of the line is significant. + +If we make the string literal a "raw" string, however, the ``\n`` sequences are +not converted to newlines, but the backslash at the end of the line, and the +newline character in the source, are both included in the string as data. Thus, +the example:: + + hello = r"This is a rather long string containing\n\ + several lines of text much as you would do in C." + + print hello + +would print:: + + This is a rather long string containing\n\ + several lines of text much as you would do in C. + +Or, strings can be surrounded in a pair of matching triple-quotes: ``"""`` or +``'''``. End of lines do not need to be escaped when using triple-quotes, but +they will be included in the string. :: + + print """ + Usage: thingy [OPTIONS] + -h Display this usage message + -H hostname Hostname to connect to + """ + +produces the following output:: + + Usage: thingy [OPTIONS] + -h Display this usage message + -H hostname Hostname to connect to + +The interpreter prints the result of string operations in the same way as they +are typed for input: inside quotes, and with quotes and other funny characters +escaped by backslashes, to show the precise value. The string is enclosed in +double quotes if the string contains a single quote and no double quotes, else +it's enclosed in single quotes. (The :keyword:`print` statement, described +later, can be used to write strings without quotes or escapes.) + +Strings can be concatenated (glued together) with the ``+`` operator, and +repeated with ``*``:: + + >>> word = 'Help' + 'A' + >>> word + 'HelpA' + >>> '<' + word*5 + '>' + '' + +Two string literals next to each other are automatically concatenated; the first +line above could also have been written ``word = 'Help' 'A'``; this only works +with two literals, not with arbitrary string expressions:: + + >>> 'str' 'ing' # <- This is ok + 'string' + >>> 'str'.strip() + 'ing' # <- This is ok + 'string' + >>> 'str'.strip() 'ing' # <- This is invalid + File "", line 1, in ? + 'str'.strip() 'ing' + ^ + SyntaxError: invalid syntax + +Strings can be subscripted (indexed); like in C, the first character of a string +has subscript (index) 0. There is no separate character type; a character is +simply a string of size one. Like in Icon, substrings can be specified with the +*slice notation*: two indices separated by a colon. :: + + >>> word[4] + 'A' + >>> word[0:2] + 'He' + >>> word[2:4] + 'lp' + +Slice indices have useful defaults; an omitted first index defaults to zero, an +omitted second index defaults to the size of the string being sliced. :: + + >>> word[:2] # The first two characters + 'He' + >>> word[2:] # Everything except the first two characters + 'lpA' + +Unlike a C string, Python strings cannot be changed. Assigning to an indexed +position in the string results in an error:: + + >>> word[0] = 'x' + Traceback (most recent call last): + File "", line 1, in ? + TypeError: object doesn't support item assignment + >>> word[:1] = 'Splat' + Traceback (most recent call last): + File "", line 1, in ? + TypeError: object doesn't support slice assignment + +However, creating a new string with the combined content is easy and efficient:: + + >>> 'x' + word[1:] + 'xelpA' + >>> 'Splat' + word[4] + 'SplatA' + +Here's a useful invariant of slice operations: ``s[:i] + s[i:]`` equals ``s``. +:: + + >>> word[:2] + word[2:] + 'HelpA' + >>> word[:3] + word[3:] + 'HelpA' + +Degenerate slice indices are handled gracefully: an index that is too large is +replaced by the string size, an upper bound smaller than the lower bound returns +an empty string. :: + + >>> word[1:100] + 'elpA' + >>> word[10:] + '' + >>> word[2:1] + '' + +Indices may be negative numbers, to start counting from the right. For example:: + + >>> word[-1] # The last character + 'A' + >>> word[-2] # The last-but-one character + 'p' + >>> word[-2:] # The last two characters + 'pA' + >>> word[:-2] # Everything except the last two characters + 'Hel' + +But note that -0 is really the same as 0, so it does not count from the right! +:: + + >>> word[-0] # (since -0 equals 0) + 'H' + +Out-of-range negative slice indices are truncated, but don't try this for +single-element (non-slice) indices:: + + >>> word[-100:] + 'HelpA' + >>> word[-10] # error + Traceback (most recent call last): + File "", line 1, in ? + IndexError: string index out of range + +One way to remember how slices work is to think of the indices as pointing +*between* characters, with the left edge of the first character numbered 0. +Then the right edge of the last character of a string of *n* characters has +index *n*, for example:: + + +---+---+---+---+---+ + | H | e | l | p | A | + +---+---+---+---+---+ + 0 1 2 3 4 5 + -5 -4 -3 -2 -1 + +The first row of numbers gives the position of the indices 0...5 in the string; +the second row gives the corresponding negative indices. The slice from *i* to +*j* consists of all characters between the edges labeled *i* and *j*, +respectively. + +For non-negative indices, the length of a slice is the difference of the +indices, if both are within bounds. For example, the length of ``word[1:3]`` is +2. + +The built-in function :func:`len` returns the length of a string:: + + >>> s = 'supercalifragilisticexpialidocious' + >>> len(s) + 34 + + +.. seealso:: + + :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:`new-string-formatting` + Information about string formatting with :meth:`str.format` is described + here. + + :ref:`string-formatting` + The old formatting operations invoked when strings and Unicode strings are + the left operand of the ``%`` operator are described in more detail here. + + +.. _tut-unicodestrings: + +Unicode Strings +--------------- + +.. sectionauthor:: Marc-Andre Lemburg + + +Starting with Python 2.0 a new data type for storing text data is available to +the programmer: the Unicode object. It can be used to store and manipulate +Unicode data (see http://www.unicode.org/) and integrates well with the existing +string objects, providing auto-conversions where necessary. + +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 +possible ordinals for script characters. Texts were typically bound to a code +page which mapped the ordinals to script characters. This lead to very much +confusion especially with respect to internationalization (usually written as +``i18n`` --- ``'i'`` + 18 characters + ``'n'``) of software. Unicode solves +these problems by defining one code page for all scripts. + +Creating Unicode strings in Python is just as simple as creating normal +strings:: + + >>> u'Hello World !' + u'Hello World !' + +The small ``'u'`` in front of the quote indicates that a Unicode string is +supposed to be created. If you want to include special characters in the string, +you can do so by using the Python *Unicode-Escape* encoding. The following +example shows how:: + + >>> u'Hello\u0020World !' + u'Hello World !' + +The escape sequence ``\u0020`` indicates to insert the Unicode character with +the ordinal value 0x0020 (the space character) at the given position. + +Other characters are interpreted by using their respective ordinal values +directly as Unicode ordinals. If you have literal strings in the standard +Latin-1 encoding that is used in many Western countries, you will find it +convenient that the lower 256 characters of Unicode are the same as the 256 +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'. :: + + >>> ur'Hello\u0020World !' + u'Hello World !' + >>> ur'Hello\\u0020World !' + u'Hello\\\\u0020World !' + +The raw mode is most useful when you have to enter lots of backslashes, as can +be necessary in regular expressions. + +Apart from these standard encodings, Python provides a whole set of other ways +of creating Unicode strings on the basis of a known encoding. + +.. index:: builtin: unicode + +The built-in function :func:`unicode` provides access to all registered Unicode +codecs (COders and DECoders). Some of the more well known encodings which these +codecs can convert are *Latin-1*, *ASCII*, *UTF-8*, and *UTF-16*. The latter two +are variable-length encodings that store each Unicode character in one or more +bytes. The default encoding is normally set to ASCII, which passes through +characters in the range 0 to 127 and rejects any other characters with an error. +When a Unicode string is printed, written to a file, or converted with +:func:`str`, conversion takes place using this default encoding. :: + + >>> u"abc" + u'abc' + >>> str(u"abc") + 'abc' + >>> u"äöü" + u'\xe4\xf6\xfc' + >>> str(u"äöü") + Traceback (most recent call last): + File "", line 1, in ? + UnicodeEncodeError: 'ascii' codec can't encode characters in position 0-2: ordinal not in range(128) + +To convert a Unicode string into an 8-bit string using a specific encoding, +Unicode objects provide an :func:`encode` method that takes one argument, the +name of the encoding. Lowercase names for encodings are preferred. :: + + >>> u"äöü".encode('utf-8') + '\xc3\xa4\xc3\xb6\xc3\xbc' + +If you have data in a specific encoding and want to produce a corresponding +Unicode string from it, you can use the :func:`unicode` function with the +encoding name as the second argument. :: + + >>> unicode('\xc3\xa4\xc3\xb6\xc3\xbc', 'utf-8') + u'\xe4\xf6\xfc' + + +.. _tut-lists: + +Lists +----- + +Python knows a number of *compound* data types, used to group together other +values. The most versatile is the *list*, which can be written as a list of +comma-separated values (items) between square brackets. List items need not all +have the same type. :: + + >>> a = ['spam', 'eggs', 100, 1234] + >>> a + ['spam', 'eggs', 100, 1234] + +Like string indices, list indices start at 0, and lists can be sliced, +concatenated and so on:: + + >>> a[0] + 'spam' + >>> a[3] + 1234 + >>> a[-2] + 100 + >>> a[1:-1] + ['eggs', 100] + >>> a[:2] + ['bacon', 2*2] + ['spam', 'eggs', 'bacon', 4] + >>> 3*a[:3] + ['Boo!'] + ['spam', 'eggs', 100, 'spam', 'eggs', 100, 'spam', 'eggs', 100, 'Boo!'] + +Unlike strings, which are *immutable*, it is possible to change individual +elements of a list:: + + >>> a + ['spam', 'eggs', 100, 1234] + >>> a[2] = a[2] + 23 + >>> a + ['spam', 'eggs', 123, 1234] + +Assignment to slices is also possible, and this can even change the size of the +list or clear it entirely:: + + >>> # Replace some items: + ... a[0:2] = [1, 12] + >>> a + [1, 12, 123, 1234] + >>> # Remove some: + ... a[0:2] = [] + >>> a + [123, 1234] + >>> # Insert some: + ... a[1:1] = ['bletch', 'xyzzy'] + >>> a + [123, 'bletch', 'xyzzy', 1234] + >>> # Insert (a copy of) itself at the beginning + >>> a[:0] = a + >>> a + [123, 'bletch', 'xyzzy', 1234, 123, 'bletch', 'xyzzy', 1234] + >>> # Clear the list: replace all items with an empty list + >>> a[:] = [] + >>> a + [] + +The built-in function :func:`len` also applies to lists:: + + >>> a = ['a', 'b', 'c', 'd'] + >>> len(a) + 4 + +It is possible to nest lists (create lists containing other lists), for +example:: + + >>> q = [2, 3] + >>> p = [1, q, 4] + >>> len(p) + 3 + >>> p[1] + [2, 3] + >>> p[1][0] + 2 + >>> p[1].append('xtra') # See section 5.1 + >>> p + [1, [2, 3, 'xtra'], 4] + >>> q + [2, 3, 'xtra'] + +Note that in the last example, ``p[1]`` and ``q`` really refer to the same +object! We'll come back to *object semantics* later. + + +.. _tut-firststeps: + +First Steps Towards Programming +=============================== + +Of course, we can use Python for more complicated tasks than adding two and two +together. For instance, we can write an initial sub-sequence of the *Fibonacci* +series as follows:: + + >>> # Fibonacci series: + ... # the sum of two elements defines the next + ... a, b = 0, 1 + >>> while b < 10: + ... print b + ... a, b = b, a+b + ... + 1 + 1 + 2 + 3 + 5 + 8 + +This example introduces several new features. + +* The first line contains a *multiple assignment*: the variables ``a`` and ``b`` + simultaneously get the new values 0 and 1. On the last line this is used again, + demonstrating that the expressions on the right-hand side are all evaluated + first before any of the assignments take place. The right-hand side expressions + are evaluated from the left to the right. + +* The :keyword:`while` loop executes as long as the condition (here: ``b < 10``) + remains true. In Python, like in C, any non-zero integer value is true; zero is + false. The condition may also be a string or list value, in fact any sequence; + anything with a non-zero length is true, empty sequences are false. The test + used in the example is a simple comparison. The standard comparison operators + are written the same as in C: ``<`` (less than), ``>`` (greater than), ``==`` + (equal to), ``<=`` (less than or equal to), ``>=`` (greater than or equal to) + and ``!=`` (not equal to). + +* The *body* of the loop is *indented*: indentation is Python's way of grouping + statements. Python does not (yet!) provide an intelligent input line editing + facility, so you have to type a tab or space(s) for each indented line. In + practice you will prepare more complicated input for Python with a text editor; + most text editors have an auto-indent facility. When a compound statement is + entered interactively, it must be followed by a blank line to indicate + completion (since the parser cannot guess when you have typed the last line). + Note that each line within a basic block must be indented by the same amount. + +* The :keyword:`print` statement writes the value of the expression(s) it is + given. It differs from just writing the expression you want to write (as we did + earlier in the calculator examples) in the way it handles multiple expressions + and strings. Strings are printed without quotes, and a space is inserted + between items, so you can format things nicely, like this:: + + >>> i = 256*256 + >>> print 'The value of i is', i + The value of i is 65536 + + A trailing comma avoids the newline after the output:: + + >>> a, b = 0, 1 + >>> while b < 1000: + ... print b, + ... a, b = b, a+b + ... + 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 + + Note that the interpreter inserts a newline before it prints the next prompt if + the last line was not completed.