What is the correct form for string.replace?

Question

Following the Python documentation for string.replace ( http://docs.python.org/library/string.html ):

string.replace(str, old, new[, maxreplace])

Return a copy of string str with all occurrences of substring old replaced by new. If the optional argument maxreplace is given, the first maxreplace occurrences are replaced.

Using the format as given generates the following error:

>>> a = 'grateful'
>>> a.replace(a,'t','c')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: an integer is required

It seems odd that you'd need the "str" repeated and from the error I guessed that my third argument was being taken for maxreplace.

The format:

string.replace(old, new)

does seem to function as expected.

I'm wondering if I am misunderstanding something, and the form given in the Python documentation is, in fact, correct in some way.

Answer 1

I think your confusion here (and that of most of the answers) is the different between the string module and the str built-in class. They're entirely separate things, even if there is a lot of overlap in functionality.

string.replace(s, old, new) is a free function, not a method. There's no way you can call it as s.replace(old, new), because s cannot be an instance of the string module.

str.replace(self, old, new) is a method. As with any other method (other than classmethod and staticmethod methods), you can—and usually do—call it through a str instance, as s.replace(old, new), where s becomes the self parameter automatically.

You can also call a method through the class, so str.replace(s, old, new) turns out to be exactly the same as s.replace(old, new). And it just so happens that, if s is a str, this does the exact same thing as string.replace(old, new). But that's really a coincidence that's true for historical reasons.

As a side note, you almost never want to call functions in the string module. They're mostly a holdover from very early versions of Python. In fact, string.replace is listed under the "Deprecated string functions" section in the documentation, as are most of the other functions you'd probably go looking for there. The reason the whole module hasn't been deprecated is that it has some things that don't belong in the str (or bytes or unicode) class, such as constants like string.digits.

Answer 2

Yes, that doc is correct, since it is referring to using string.replace() as a stand alone function. So you can do this:

>>> import string
>>> string.replace("a","a","b")
'b'

This is different from calling replace() as a method of a given string, like this:

>>> 'a'.replace('a','b')
'b'

They are two different things that have different syntax but are designed to have the same results. So calling one with the other's syntax will result in an error. For example:

>>> 'a'.replace('a','a','b')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: an integer is required