Notice that in the prior examples, we were not changing the original string with any of the operations we ran on it. Every string operation is defined to produce a new string as its result, because strings are immutable in Python—they cannot be changed in-place after they are created. For example, you can’t change a string by assigning to one of its positions, but you can always build a new one and assign it to the same name. Because Python cleans up old objects as you go (as you’ll see later), this isn’t as inefficient as it may sound:

  >>> S
  'Spam'
  >>> S[0] = 'z'             # Immutable objects cannot be change d
  ...error text omittted...
  TypeError: 'str' object does not support item assignment

  >>> S = 'z' + S[1:]        # But we can run expressions to make new objects
  >>> S
  'zpam'

Every object in Python is classified as immutable (unchangeable) or not. In terms of the core types, numbers, strings, and tuples are immutable; lists and dictionaries are not (they can be changed in-place freely). Among other things, immutability can be used to guarantee that an object remains constant throughout your program.

Type-Specific Methods

Every string operation we’ve studied so far is really a sequence operation—that is, these operations will work on other sequences in Python as well, including lists and tuples. In addition to generic sequence operations, though, strings also have operations all their own, available as methods (functions attached to the object, which are triggered with a call expression).

For example, the string find method is the basic substring search operation (it returns the offset of the passed-in substring, or -1 if it is not present), and the string replace method performs global searches and replacements:

  >>> S.find('pa')             # Find the offset of a substring 
  1
  >>> S
  'Spam'
  >>> S.replace('pa', 'XYZ')   # Replace occurrences of a substring with anothe r
  'SXYZm '
  >>> S
  'Spam'

Again, despite the names of these string methods, we are not changing the original strings here, but creating new strings as the results—because strings are immutable, we have to do it this way. String methods are the first line of text-processing tools in Python; other methods split a string into substrings on a delimiter (handy as a sim ple form of parsing), perform case conversions, test the content of the string (digits, letters, and so on), and strip whitespace characters off the ends of the string:

  >>> line = 'aaa,bbb,ccccc,dd'
  >>> line.split(',')                # Split on a delimiter into a list of substrings
  ['aaa', 'bbb', 'ccccc', 'dd' ]

  >>> S = 'spam'
  >>> S.upper()                    # Upper- and lowercase conversions
  'SPAM '

  >>> S.isalpha()                  # Content tests: isalpha, isdigit, etc .
  Tru e

  >>> line = 'aaa,bbb,ccccc,dd\n'
  >>> line = line.rstrip()         # Remove whitespace characters on the right side
  >>> line
  'aaa,bbb,ccccc,dd'

One note here: although sequence operations are generic, methods are not—string method operations work only on strings, and nothing else. As a rule of thumb, Python’s toolset is layered: generic operations that span multiple types show up as built-in functions or expressions (e.g., len(X) , X[0] ), but type-specific operations are method calls (e.g., aString.upper() ). Finding the tools you need among all these cat egories will become more natural as you use Python more, but the next section gives a few tips you can use right now.

Getting Help

The methods introduced in the prior section are a representative, but small, sample of what is available for string objects. In general, this book is not exhaustive in its look at object methods. For more details, you can always call the built-in dir function, which returns a list of all the attributes available in a given object. Because methods are function attributes, they will show up in this list:

  >>> dir(S)
  ['__add__', '__class__', '__contains__', '__delattr__', '__doc__', '__eq__',
  '__ge__', '__getattribute__', '__getitem__',
'__getnewargs__', '__getslice__', 
  '__gt_ _', '__hash__', '__init__', '__le__', '__len__', '__lt_ _', '__mod__',
  '__mul__', '__ne__', '__new__',  '__reduce__', '__reduce_ex__', '__repr__',
  '__rmod__', '__rmul__', '__setattr__', '_
_str__', 'capitalize', 'center',
  'count', 'decode', 'encode', 'endswith', 'expandtabs', 'find', 'index',
  'isalnum', 'isalpha', 'isdigit', 'islower', 'isspace', 'istitle', 'isupper',
  'join', 'ljust', 'lower', 'lstrip', 'partition', 'replace', 'rfind', 'rindex',
  'rjust', 'rpartition', 'rsplit', 'rstrip',
'split', 'splitlines', 'startswith',
  'strip', 'swapcase', 'title', 'translate', 'upper', 'zfill']

You probably won’t care about the names with underscores in this list until later in the book, when we study operator overloading in classes—they represent the imple mentation of the string object, and are available to support customization. In general, leading and trailing double underscores is the naming pattern Python uses for implementation details. The names without the underscores in this list are the callable methods on string objects.

The dir function simply gives the methods’ names. To ask what they do, you can pass them to the help function:

  >>> help(S.index)
  Help on built-in function index:

  index(... )
      S.index(sub [,start [,end]]) -> int

      Like S.find() but raise ValueError when the substring is not found.

help is one of a handful of interfaces to a system of code that ships with Python known as PyDoc—a tool for extracting documentation from objects. Later in the book, you’ll see that PyDoc can also render its reports in HTML format.

You can also ask for help on an entire string (e.g., help(S) ), but you may get more help than you want to see—i.e., information about every string method. It’s gener ally better to ask about a specific method, as we did above.

For more details, you can also consult Python’s standard library reference manual, or commercially published reference books, but dir and help are the first line of documentation in Python.