Home | History | Annotate | Download | only in tutorial
      1 .. _tut-informal:
      2 
      3 **********************************
      4 An Informal Introduction to Python
      5 **********************************
      6 
      7 In the following examples, input and output are distinguished by the presence or
      8 absence of prompts (:term:`>>>` and :term:`...`): to repeat the example, you must type
      9 everything after the prompt, when the prompt appears; lines that do not begin
     10 with a prompt are output from the interpreter. Note that a secondary prompt on a
     11 line by itself in an example means you must type a blank line; this is used to
     12 end a multi-line command.
     13 
     14 Many of the examples in this manual, even those entered at the interactive
     15 prompt, include comments.  Comments in Python start with the hash character,
     16 ``#``, and extend to the end of the physical line.  A comment may appear at the
     17 start of a line or following whitespace or code, but not within a string
     18 literal.  A hash character within a string literal is just a hash character.
     19 Since comments are to clarify code and are not interpreted by Python, they may
     20 be omitted when typing in examples.
     21 
     22 Some examples::
     23 
     24    # this is the first comment
     25    spam = 1  # and this is the second comment
     26              # ... and now a third!
     27    text = "# This is not a comment because it's inside quotes."
     28 
     29 
     30 .. _tut-calculator:
     31 
     32 Using Python as a Calculator
     33 ============================
     34 
     35 Let's try some simple Python commands.  Start the interpreter and wait for the
     36 primary prompt, ``>>>``.  (It shouldn't take long.)
     37 
     38 
     39 .. _tut-numbers:
     40 
     41 Numbers
     42 -------
     43 
     44 The interpreter acts as a simple calculator: you can type an expression at it
     45 and it will write the value.  Expression syntax is straightforward: the
     46 operators ``+``, ``-``, ``*`` and ``/`` work just like in most other languages
     47 (for example, Pascal or C); parentheses (``()``) can be used for grouping.
     48 For example::
     49 
     50    >>> 2 + 2
     51    4
     52    >>> 50 - 5*6
     53    20
     54    >>> (50 - 5*6) / 4
     55    5.0
     56    >>> 8 / 5  # division always returns a floating point number
     57    1.6
     58 
     59 The integer numbers (e.g. ``2``, ``4``, ``20``) have type :class:`int`,
     60 the ones with a fractional part (e.g. ``5.0``, ``1.6``) have type
     61 :class:`float`.  We will see more about numeric types later in the tutorial.
     62 
     63 Division (``/``) always returns a float.  To do :term:`floor division` and
     64 get an integer result (discarding any fractional result) you can use the ``//``
     65 operator; to calculate the remainder you can use ``%``::
     66 
     67    >>> 17 / 3  # classic division returns a float
     68    5.666666666666667
     69    >>>
     70    >>> 17 // 3  # floor division discards the fractional part
     71    5
     72    >>> 17 % 3  # the % operator returns the remainder of the division
     73    2
     74    >>> 5 * 3 + 2  # result * divisor + remainder
     75    17
     76 
     77 With Python, it is possible to use the ``**`` operator to calculate powers [#]_::
     78 
     79    >>> 5 ** 2  # 5 squared
     80    25
     81    >>> 2 ** 7  # 2 to the power of 7
     82    128
     83 
     84 The equal sign (``=``) is used to assign a value to a variable. Afterwards, no
     85 result is displayed before the next interactive prompt::
     86 
     87    >>> width = 20
     88    >>> height = 5 * 9
     89    >>> width * height
     90    900
     91 
     92 If a variable is not "defined" (assigned a value), trying to use it will
     93 give you an error::
     94 
     95    >>> n  # try to access an undefined variable
     96    Traceback (most recent call last):
     97      File "<stdin>", line 1, in <module>
     98    NameError: name 'n' is not defined
     99 
    100 There is full support for floating point; operators with mixed type operands
    101 convert the integer operand to floating point::
    102 
    103    >>> 3 * 3.75 / 1.5
    104    7.5
    105    >>> 7.0 / 2
    106    3.5
    107 
    108 In interactive mode, the last printed expression is assigned to the variable
    109 ``_``.  This means that when you are using Python as a desk calculator, it is
    110 somewhat easier to continue calculations, for example::
    111 
    112    >>> tax = 12.5 / 100
    113    >>> price = 100.50
    114    >>> price * tax
    115    12.5625
    116    >>> price + _
    117    113.0625
    118    >>> round(_, 2)
    119    113.06
    120 
    121 This variable should be treated as read-only by the user.  Don't explicitly
    122 assign a value to it --- you would create an independent local variable with the
    123 same name masking the built-in variable with its magic behavior.
    124 
    125 In addition to :class:`int` and :class:`float`, Python supports other types of
    126 numbers, such as :class:`~decimal.Decimal` and :class:`~fractions.Fraction`.
    127 Python also has built-in support for :ref:`complex numbers <typesnumeric>`,
    128 and uses the ``j`` or ``J`` suffix to indicate the imaginary part
    129 (e.g. ``3+5j``).
    130 
    131 
    132 .. _tut-strings:
    133 
    134 Strings
    135 -------
    136 
    137 Besides numbers, Python can also manipulate strings, which can be expressed
    138 in several ways.  They can be enclosed in single quotes (``'...'``) or
    139 double quotes (``"..."``) with the same result [#]_.  ``\`` can be used
    140 to escape quotes::
    141 
    142    >>> 'spam eggs'  # single quotes
    143    'spam eggs'
    144    >>> 'doesn\'t'  # use \' to escape the single quote...
    145    "doesn't"
    146    >>> "doesn't"  # ...or use double quotes instead
    147    "doesn't"
    148    >>> '"Yes," he said.'
    149    '"Yes," he said.'
    150    >>> "\"Yes,\" he said."
    151    '"Yes," he said.'
    152    >>> '"Isn\'t," she said.'
    153    '"Isn\'t," she said.'
    154 
    155 In the interactive interpreter, the output string is enclosed in quotes and
    156 special characters are escaped with backslashes.  While this might sometimes
    157 look different from the input (the enclosing quotes could change), the two
    158 strings are equivalent.  The string is enclosed in double quotes if
    159 the string contains a single quote and no double quotes, otherwise it is
    160 enclosed in single quotes.  The :func:`print` function produces a more
    161 readable output, by omitting the enclosing quotes and by printing escaped
    162 and special characters::
    163 
    164    >>> '"Isn\'t," she said.'
    165    '"Isn\'t," she said.'
    166    >>> print('"Isn\'t," she said.')
    167    "Isn't," she said.
    168    >>> s = 'First line.\nSecond line.'  # \n means newline
    169    >>> s  # without print(), \n is included in the output
    170    'First line.\nSecond line.'
    171    >>> print(s)  # with print(), \n produces a new line
    172    First line.
    173    Second line.
    174 
    175 If you don't want characters prefaced by ``\`` to be interpreted as
    176 special characters, you can use *raw strings* by adding an ``r`` before
    177 the first quote::
    178 
    179    >>> print('C:\some\name')  # here \n means newline!
    180    C:\some
    181    ame
    182    >>> print(r'C:\some\name')  # note the r before the quote
    183    C:\some\name
    184 
    185 String literals can span multiple lines.  One way is using triple-quotes:
    186 ``"""..."""`` or ``'''...'''``.  End of lines are automatically
    187 included in the string, but it's possible to prevent this by adding a ``\`` at
    188 the end of the line.  The following example::
    189 
    190    print("""\
    191    Usage: thingy [OPTIONS]
    192         -h                        Display this usage message
    193         -H hostname               Hostname to connect to
    194    """)
    195 
    196 produces the following output (note that the initial newline is not included):
    197 
    198 .. code-block:: text
    199 
    200    Usage: thingy [OPTIONS]
    201         -h                        Display this usage message
    202         -H hostname               Hostname to connect to
    203 
    204 Strings can be concatenated (glued together) with the ``+`` operator, and
    205 repeated with ``*``::
    206 
    207    >>> # 3 times 'un', followed by 'ium'
    208    >>> 3 * 'un' + 'ium'
    209    'unununium'
    210 
    211 Two or more *string literals* (i.e. the ones enclosed between quotes) next
    212 to each other are automatically concatenated. ::
    213 
    214    >>> 'Py' 'thon'
    215    'Python'
    216 
    217 This only works with two literals though, not with variables or expressions::
    218 
    219    >>> prefix = 'Py'
    220    >>> prefix 'thon'  # can't concatenate a variable and a string literal
    221      ...
    222    SyntaxError: invalid syntax
    223    >>> ('un' * 3) 'ium'
    224      ...
    225    SyntaxError: invalid syntax
    226 
    227 If you want to concatenate variables or a variable and a literal, use ``+``::
    228 
    229    >>> prefix + 'thon'
    230    'Python'
    231 
    232 This feature is particularly useful when you want to break long strings::
    233 
    234    >>> text = ('Put several strings within parentheses '
    235    ...         'to have them joined together.')
    236    >>> text
    237    'Put several strings within parentheses to have them joined together.'
    238 
    239 Strings can be *indexed* (subscripted), with the first character having index 0.
    240 There is no separate character type; a character is simply a string of size
    241 one::
    242 
    243    >>> word = 'Python'
    244    >>> word[0]  # character in position 0
    245    'P'
    246    >>> word[5]  # character in position 5
    247    'n'
    248 
    249 Indices may also be negative numbers, to start counting from the right::
    250 
    251    >>> word[-1]  # last character
    252    'n'
    253    >>> word[-2]  # second-last character
    254    'o'
    255    >>> word[-6]
    256    'P'
    257 
    258 Note that since -0 is the same as 0, negative indices start from -1.
    259 
    260 In addition to indexing, *slicing* is also supported.  While indexing is used
    261 to obtain individual characters, *slicing* allows you to obtain substring::
    262 
    263    >>> word[0:2]  # characters from position 0 (included) to 2 (excluded)
    264    'Py'
    265    >>> word[2:5]  # characters from position 2 (included) to 5 (excluded)
    266    'tho'
    267 
    268 Note how the start is always included, and the end always excluded.  This
    269 makes sure that ``s[:i] + s[i:]`` is always equal to ``s``::
    270 
    271    >>> word[:2] + word[2:]
    272    'Python'
    273    >>> word[:4] + word[4:]
    274    'Python'
    275 
    276 Slice indices have useful defaults; an omitted first index defaults to zero, an
    277 omitted second index defaults to the size of the string being sliced. ::
    278 
    279    >>> word[:2]   # character from the beginning to position 2 (excluded)
    280    'Py'
    281    >>> word[4:]   # characters from position 4 (included) to the end
    282    'on'
    283    >>> word[-2:]  # characters from the second-last (included) to the end
    284    'on'
    285 
    286 One way to remember how slices work is to think of the indices as pointing
    287 *between* characters, with the left edge of the first character numbered 0.
    288 Then the right edge of the last character of a string of *n* characters has
    289 index *n*, for example::
    290 
    291     +---+---+---+---+---+---+
    292     | P | y | t | h | o | n |
    293     +---+---+---+---+---+---+
    294     0   1   2   3   4   5   6
    295    -6  -5  -4  -3  -2  -1
    296 
    297 The first row of numbers gives the position of the indices 0...6 in the string;
    298 the second row gives the corresponding negative indices. The slice from *i* to
    299 *j* consists of all characters between the edges labeled *i* and *j*,
    300 respectively.
    301 
    302 For non-negative indices, the length of a slice is the difference of the
    303 indices, if both are within bounds.  For example, the length of ``word[1:3]`` is
    304 2.
    305 
    306 Attempting to use an index that is too large will result in an error::
    307 
    308    >>> word[42]  # the word only has 6 characters
    309    Traceback (most recent call last):
    310      File "<stdin>", line 1, in <module>
    311    IndexError: string index out of range
    312 
    313 However, out of range slice indexes are handled gracefully when used for
    314 slicing::
    315 
    316    >>> word[4:42]
    317    'on'
    318    >>> word[42:]
    319    ''
    320 
    321 Python strings cannot be changed --- they are :term:`immutable`.
    322 Therefore, assigning to an indexed position in the string results in an error::
    323 
    324    >>> word[0] = 'J'
    325      ...
    326    TypeError: 'str' object does not support item assignment
    327    >>> word[2:] = 'py'
    328      ...
    329    TypeError: 'str' object does not support item assignment
    330 
    331 If you need a different string, you should create a new one::
    332 
    333    >>> 'J' + word[1:]
    334    'Jython'
    335    >>> word[:2] + 'py'
    336    'Pypy'
    337 
    338 The built-in function :func:`len` returns the length of a string::
    339 
    340    >>> s = 'supercalifragilisticexpialidocious'
    341    >>> len(s)
    342    34
    343 
    344 
    345 .. seealso::
    346 
    347    :ref:`textseq`
    348       Strings are examples of *sequence types*, and support the common
    349       operations supported by such types.
    350 
    351    :ref:`string-methods`
    352       Strings support a large number of methods for
    353       basic transformations and searching.
    354 
    355    :ref:`f-strings`
    356       String literals that have embedded expressions.
    357 
    358    :ref:`formatstrings`
    359       Information about string formatting with :meth:`str.format`.
    360 
    361    :ref:`old-string-formatting`
    362       The old formatting operations invoked when strings are
    363       the left operand of the ``%`` operator are described in more detail here.
    364 
    365 
    366 .. _tut-lists:
    367 
    368 Lists
    369 -----
    370 
    371 Python knows a number of *compound* data types, used to group together other
    372 values.  The most versatile is the *list*, which can be written as a list of
    373 comma-separated values (items) between square brackets.  Lists might contain
    374 items of different types, but usually the items all have the same type. ::
    375 
    376    >>> squares = [1, 4, 9, 16, 25]
    377    >>> squares
    378    [1, 4, 9, 16, 25]
    379 
    380 Like strings (and all other built-in :term:`sequence` type), lists can be
    381 indexed and sliced::
    382 
    383    >>> squares[0]  # indexing returns the item
    384    1
    385    >>> squares[-1]
    386    25
    387    >>> squares[-3:]  # slicing returns a new list
    388    [9, 16, 25]
    389 
    390 All slice operations return a new list containing the requested elements.  This
    391 means that the following slice returns a new (shallow) copy of the list::
    392 
    393    >>> squares[:]
    394    [1, 4, 9, 16, 25]
    395 
    396 Lists also support operations like concatenation::
    397 
    398    >>> squares + [36, 49, 64, 81, 100]
    399    [1, 4, 9, 16, 25, 36, 49, 64, 81, 100]
    400 
    401 Unlike strings, which are :term:`immutable`, lists are a :term:`mutable`
    402 type, i.e. it is possible to change their content::
    403 
    404     >>> cubes = [1, 8, 27, 65, 125]  # something's wrong here
    405     >>> 4 ** 3  # the cube of 4 is 64, not 65!
    406     64
    407     >>> cubes[3] = 64  # replace the wrong value
    408     >>> cubes
    409     [1, 8, 27, 64, 125]
    410 
    411 You can also add new items at the end of the list, by using
    412 the :meth:`~list.append` *method* (we will see more about methods later)::
    413 
    414    >>> cubes.append(216)  # add the cube of 6
    415    >>> cubes.append(7 ** 3)  # and the cube of 7
    416    >>> cubes
    417    [1, 8, 27, 64, 125, 216, 343]
    418 
    419 Assignment to slices is also possible, and this can even change the size of the
    420 list or clear it entirely::
    421 
    422    >>> letters = ['a', 'b', 'c', 'd', 'e', 'f', 'g']
    423    >>> letters
    424    ['a', 'b', 'c', 'd', 'e', 'f', 'g']
    425    >>> # replace some values
    426    >>> letters[2:5] = ['C', 'D', 'E']
    427    >>> letters
    428    ['a', 'b', 'C', 'D', 'E', 'f', 'g']
    429    >>> # now remove them
    430    >>> letters[2:5] = []
    431    >>> letters
    432    ['a', 'b', 'f', 'g']
    433    >>> # clear the list by replacing all the elements with an empty list
    434    >>> letters[:] = []
    435    >>> letters
    436    []
    437 
    438 The built-in function :func:`len` also applies to lists::
    439 
    440    >>> letters = ['a', 'b', 'c', 'd']
    441    >>> len(letters)
    442    4
    443 
    444 It is possible to nest lists (create lists containing other lists), for
    445 example::
    446 
    447    >>> a = ['a', 'b', 'c']
    448    >>> n = [1, 2, 3]
    449    >>> x = [a, n]
    450    >>> x
    451    [['a', 'b', 'c'], [1, 2, 3]]
    452    >>> x[0]
    453    ['a', 'b', 'c']
    454    >>> x[0][1]
    455    'b'
    456 
    457 .. _tut-firststeps:
    458 
    459 First Steps Towards Programming
    460 ===============================
    461 
    462 Of course, we can use Python for more complicated tasks than adding two and two
    463 together.  For instance, we can write an initial sub-sequence of the *Fibonacci*
    464 series as follows::
    465 
    466    >>> # Fibonacci series:
    467    ... # the sum of two elements defines the next
    468    ... a, b = 0, 1
    469    >>> while b < 10:
    470    ...     print(b)
    471    ...     a, b = b, a+b
    472    ...
    473    1
    474    1
    475    2
    476    3
    477    5
    478    8
    479 
    480 This example introduces several new features.
    481 
    482 * The first line contains a *multiple assignment*: the variables ``a`` and ``b``
    483   simultaneously get the new values 0 and 1.  On the last line this is used again,
    484   demonstrating that the expressions on the right-hand side are all evaluated
    485   first before any of the assignments take place.  The right-hand side expressions
    486   are evaluated  from the left to the right.
    487 
    488 * The :keyword:`while` loop executes as long as the condition (here: ``b < 10``)
    489   remains true.  In Python, like in C, any non-zero integer value is true; zero is
    490   false.  The condition may also be a string or list value, in fact any sequence;
    491   anything with a non-zero length is true, empty sequences are false.  The test
    492   used in the example is a simple comparison.  The standard comparison operators
    493   are written the same as in C: ``<`` (less than), ``>`` (greater than), ``==``
    494   (equal to), ``<=`` (less than or equal to), ``>=`` (greater than or equal to)
    495   and ``!=`` (not equal to).
    496 
    497 * The *body* of the loop is *indented*: indentation is Python's way of grouping
    498   statements.  At the interactive prompt, you have to type a tab or space(s) for
    499   each indented line.  In practice you will prepare more complicated input
    500   for Python with a text editor; all decent text editors have an auto-indent
    501   facility.  When a compound statement is entered interactively, it must be
    502   followed by a blank line to indicate completion (since the parser cannot
    503   guess when you have typed the last line).  Note that each line within a basic
    504   block must be indented by the same amount.
    505 
    506 * The :func:`print` function writes the value of the argument(s) it is given.
    507   It differs from just writing the expression you want to write (as we did
    508   earlier in the calculator examples) in the way it handles multiple arguments,
    509   floating point quantities, and strings.  Strings are printed without quotes,
    510   and a space is inserted between items, so you can format things nicely, like
    511   this::
    512 
    513      >>> i = 256*256
    514      >>> print('The value of i is', i)
    515      The value of i is 65536
    516 
    517   The keyword argument *end* can be used to avoid the newline after the output,
    518   or end the output with a different string::
    519 
    520      >>> a, b = 0, 1
    521      >>> while b < 1000:
    522      ...     print(b, end=',')
    523      ...     a, b = b, a+b
    524      ...
    525      1,1,2,3,5,8,13,21,34,55,89,144,233,377,610,987,
    526 
    527 
    528 .. rubric:: Footnotes
    529 
    530 .. [#] Since ``**`` has higher precedence than ``-``, ``-3**2`` will be
    531    interpreted as ``-(3**2)`` and thus result in ``-9``.  To avoid this
    532    and get ``9``, you can use ``(-3)**2``.
    533 
    534 .. [#] Unlike other languages, special characters such as ``\n`` have the
    535    same meaning with both single (``'...'``) and double (``"..."``) quotes.
    536    The only difference between the two is that within single quotes you don't
    537    need to escape ``"`` (but you have to escape ``\'``) and vice versa.
    538