Documentation additions/fixes.

Author: Liam3851

doc/source/text.rst

@@ -118,8 +118,8 @@ i.e., from the end of the string to the beginning of the string:
 
    s2.str.rsplit('_', expand=True, n=1)
 
-Methods like ``replace`` and ``findall`` take `regular expressions
-<https://docs.python.org/3/library/re.html>`__, too:
+``replace`` by default replaces `regular expressions
+<https://docs.python.org/3/library/re.html>`__:
 
 .. ipython:: python
 
@@ -146,12 +146,25 @@ following code will cause trouble because of the regular expression meaning of
    # We need to escape the special character (for >1 len patterns)
    dollars.str.replace(r'-\$', '-')
 
+.. versionadded:: 0.23.0
+
+If you do want literal replacement of a string (equivalent to
+:meth:`str.replace`), you can set the optional ``regex`` parameter to
+``False``, rather than escaping each character. In this case both ``pat``
+and ``repl`` must be strings:
+
+.. ipython:: python
+
+    # These lines are equivalent
+    dollars.str.replace(r'-\$', '-')
+    dollars.str.replace('-$', '-', regex=False)  
+
+.. versionadded:: 0.20.0
+
 The ``replace`` method can also take a callable as replacement. It is called
 on every ``pat`` using :func:`re.sub`. The callable should expect one
 positional argument (a regex object) and return a string.
 
-.. versionadded:: 0.20.0
-
 .. ipython:: python
 
    # Reverse every lowercase alphabetic word
@@ -164,12 +177,12 @@ positional argument (a regex object) and return a string.
    repl = lambda m: m.group('two').swapcase()
    pd.Series(['Foo Bar Baz', np.nan]).str.replace(pat, repl)
 
+.. versionadded:: 0.20.0
+
 The ``replace`` method also accepts a compiled regular expression object
 from :func:`re.compile` as a pattern. All flags should be included in the
 compiled regular expression object.
 
-.. versionadded:: 0.20.0
-
 .. ipython:: python
 
    import re
@@ -186,6 +199,7 @@ regular expression object will raise a ``ValueError``.
     ---------------------------------------------------------------------------
     ValueError: case and flags cannot be set when pat is a compiled regex
 
+
 Indexing with ``.str``
 ----------------------
 
@@ -432,7 +446,7 @@ Method Summary
     :meth:`~Series.str.join`;Join strings in each element of the Series with passed separator
     :meth:`~Series.str.get_dummies`;Split strings on the delimiter returning DataFrame of dummy variables
     :meth:`~Series.str.contains`;Return boolean array if each string contains pattern/regex
-    :meth:`~Series.str.replace`;Replace occurrences of pattern/regex with some other string or the return value of a callable given the occurrence
+    :meth:`~Series.str.replace`;Replace occurrences of pattern/regex/string with some other string or the return value of a callable given the occurrence
     :meth:`~Series.str.repeat`;Duplicate values (``s.str.repeat(3)`` equivalent to ``x * 3``)
     :meth:`~Series.str.pad`;"Add whitespace to left, right, or both sides of strings"
     :meth:`~Series.str.center`;Equivalent to ``str.center``

doc/source/whatsnew/v0.23.0.txt

@@ -620,6 +620,7 @@ Other API Changes
 - Set operations (union, difference...) on :class:`IntervalIndex` with incompatible index types will now raise a ``TypeError`` rather than a ``ValueError`` (:issue:`19329`)
 - :class:`DateOffset` objects render more simply, e.g. ``<DateOffset: days=1>`` instead of ``<DateOffset: kwds={'days': 1}>`` (:issue:`19403`)
 - ``Categorical.fillna`` now validates its ``value`` and ``method`` keyword arguments. It now raises when both or none are specified, matching the behavior of :meth:`Series.fillna` (:issue:`19682`)
+- :func:`Series.str.replace` now takes an optional `regex` keyword which, when set to ``False``, uses literal string replacement rather than regex replacement (:issue:`16808`) 
 
 .. _whatsnew_0230.deprecations:
 

pandas/core/strings.py

@@ -368,7 +368,8 @@ def str_replace(arr, pat, repl, n=-1, case=None, flags=0, regex=True):
 
     When `pat` is a string and `regex` is True, the given `pat` is compiled
     as a regex. When `repl` is a string, it replaces matching regex patterns
-    literally as with :meth:`re.sub`:
+    as with :meth:`re.sub`:
+
     >>> pd.Series(['foo', 'fuz', np.nan]).str.replace('f.', 'ba', regex=True)
     0    bao
     1    baz