{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "\n", "\n", "*This notebook contains an excerpt from the [Whirlwind Tour of Python](http://www.oreilly.com/programming/free/a-whirlwind-tour-of-python.csp) by Jake VanderPlas; the content is available [on GitHub](https://github.com/jakevdp/WhirlwindTourOfPython).*\n", "\n", "*The text and code are released under the [CC0](https://github.com/jakevdp/WhirlwindTourOfPython/blob/master/LICENSE) license; see also the companion project, the [Python Data Science Handbook](https://github.com/jakevdp/PythonDataScienceHandbook).*\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "\n", "< [Modules and Packages](13-Modules-and-Packages.ipynb) | [Contents](Index.ipynb) | [A Preview of Data Science Tools](15-Preview-of-Data-Science-Tools.ipynb) >" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "# String Manipulation and Regular Expressions" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "One place where the Python language really shines is in the manipulation of strings.\n", "This section will cover some of Python's built-in string methods and formatting operations, before moving on to a quick guide to the extremely useful subject of *regular expressions*.\n", "Such string manipulation patterns come up often in the context of data science work, and is one big perk of Python in this context.\n", "\n", "Strings in Python can be defined using either single or double quotations (they are functionally equivalent):" ] }, { "cell_type": "code", "execution_count": 1, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "True" ] }, "execution_count": 1, "metadata": {}, "output_type": "execute_result" } ], "source": [ "x = 'a string'\n", "y = \"a string\"\n", "x == y" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "In addition, it is possible to define multi-line strings using a triple-quote syntax:" ] }, { "cell_type": "code", "execution_count": 2, "metadata": { "collapsed": true }, "outputs": [], "source": [ "multiline = \"\"\"\n", "one\n", "two\n", "three\n", "\"\"\"" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "With this, let's take a quick tour of some of Python's string manipulation tools." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Simple String Manipulation in Python\n", "\n", "For basic manipulation of strings, Python's built-in string methods can be extremely convenient.\n", "If you have a background working in C or another low-level language, you will likely find the simplicity of Python's methods extremely refreshing.\n", "We introduced Python's string type and a few of these methods earlier; here we'll dive a bit deeper" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Formatting strings: Adjusting case\n", "\n", "Python makes it quite easy to adjust the case of a string.\n", "Here we'll look at the ``upper()``, ``lower()``, ``capitalize()``, ``title()``, and ``swapcase()`` methods, using the following messy string as an example:" ] }, { "cell_type": "code", "execution_count": 3, "metadata": { "collapsed": true }, "outputs": [], "source": [ "fox = \"tHe qUICk bROWn fOx.\"" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "To convert the entire string into upper-case or lower-case, you can use the ``upper()`` or ``lower()`` methods respectively:" ] }, { "cell_type": "code", "execution_count": 4, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "'THE QUICK BROWN FOX.'" ] }, "execution_count": 4, "metadata": {}, "output_type": "execute_result" } ], "source": [ "fox.upper()" ] }, { "cell_type": "code", "execution_count": 5, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "'the quick brown fox.'" ] }, "execution_count": 5, "metadata": {}, "output_type": "execute_result" } ], "source": [ "fox.lower()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "A common formatting need is to capitalize just the first letter of each word, or perhaps the first letter of each sentence.\n", "This can be done with the ``title()`` and ``capitalize()`` methods:" ] }, { "cell_type": "code", "execution_count": 6, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "'The Quick Brown Fox.'" ] }, "execution_count": 6, "metadata": {}, "output_type": "execute_result" } ], "source": [ "fox.title()" ] }, { "cell_type": "code", "execution_count": 7, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "'The quick brown fox.'" ] }, "execution_count": 7, "metadata": {}, "output_type": "execute_result" } ], "source": [ "fox.capitalize()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The cases can be swapped using the ``swapcase()`` method:" ] }, { "cell_type": "code", "execution_count": 8, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "'ThE QuicK BrowN FoX.'" ] }, "execution_count": 8, "metadata": {}, "output_type": "execute_result" } ], "source": [ "fox.swapcase()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Formatting strings: Adding and removing spaces\n", "\n", "Another common need is to remove spaces (or other characters) from the beginning or end of the string.\n", "The basic method of removing characters is the ``strip()`` method, which strips whitespace from the beginning and end of the line:" ] }, { "cell_type": "code", "execution_count": 9, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "'this is the content'" ] }, "execution_count": 9, "metadata": {}, "output_type": "execute_result" } ], "source": [ "line = ' this is the content '\n", "line.strip()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "To remove just space to the right or left, use ``rstrip()`` or ``lstrip()`` respectively:" ] }, { "cell_type": "code", "execution_count": 10, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "' this is the content'" ] }, "execution_count": 10, "metadata": {}, "output_type": "execute_result" } ], "source": [ "line.rstrip()" ] }, { "cell_type": "code", "execution_count": 11, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "'this is the content '" ] }, "execution_count": 11, "metadata": {}, "output_type": "execute_result" } ], "source": [ "line.lstrip()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "To remove characters other than spaces, you can pass the desired character to the ``strip()`` method:" ] }, { "cell_type": "code", "execution_count": 12, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "'435'" ] }, "execution_count": 12, "metadata": {}, "output_type": "execute_result" } ], "source": [ "num = \"000000000000435\"\n", "num.strip('0')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The opposite of this operation, adding spaces or other characters, can be accomplished using the ``center()``, ``ljust()``, and ``rjust()`` methods.\n", "\n", "For example, we can use the ``center()`` method to center a given string within a given number of spaces:" ] }, { "cell_type": "code", "execution_count": 13, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "' this is the content '" ] }, "execution_count": 13, "metadata": {}, "output_type": "execute_result" } ], "source": [ "line = \"this is the content\"\n", "line.center(30)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Similarly, ``ljust()`` and ``rjust()`` will left-justify or right-justify the string within spaces of a given length:" ] }, { "cell_type": "code", "execution_count": 14, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "'this is the content '" ] }, "execution_count": 14, "metadata": {}, "output_type": "execute_result" } ], "source": [ "line.ljust(30)" ] }, { "cell_type": "code", "execution_count": 15, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "' this is the content'" ] }, "execution_count": 15, "metadata": {}, "output_type": "execute_result" } ], "source": [ "line.rjust(30)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "All these methods additionally accept any character which will be used to fill the space.\n", "For example:" ] }, { "cell_type": "code", "execution_count": 16, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "'0000000435'" ] }, "execution_count": 16, "metadata": {}, "output_type": "execute_result" } ], "source": [ "'435'.rjust(10, '0')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Because zero-filling is such a common need, Python also provides ``zfill()``, which is a special method to right-pad a string with zeros:" ] }, { "cell_type": "code", "execution_count": 17, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "'0000000435'" ] }, "execution_count": 17, "metadata": {}, "output_type": "execute_result" } ], "source": [ "'435'.zfill(10)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Finding and replacing substrings\n", "\n", "If you want to find occurrences of a certain character in a string, the ``find()``/``rfind()``, ``index()``/``rindex()``, and ``replace()`` methods are the best built-in methods.\n", "\n", "``find()`` and ``index()`` are very similar, in that they search for the first occurrence of a character or substring within a string, and return the index of the substring:" ] }, { "cell_type": "code", "execution_count": 18, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "16" ] }, "execution_count": 18, "metadata": {}, "output_type": "execute_result" } ], "source": [ "line = 'the quick brown fox jumped over a lazy dog'\n", "line.find('fox')" ] }, { "cell_type": "code", "execution_count": 19, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "16" ] }, "execution_count": 19, "metadata": {}, "output_type": "execute_result" } ], "source": [ "line.index('fox')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The only difference between ``find()`` and ``index()`` is their behavior when the search string is not found; ``find()`` returns ``-1``, while ``index()`` raises a ``ValueError``:" ] }, { "cell_type": "code", "execution_count": 20, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "-1" ] }, "execution_count": 20, "metadata": {}, "output_type": "execute_result" } ], "source": [ "line.find('bear')" ] }, { "cell_type": "code", "execution_count": 21, "metadata": { "collapsed": false }, "outputs": [ { "ename": "ValueError", "evalue": "substring not found", "output_type": "error", "traceback": [ "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m", "\u001b[0;31mValueError\u001b[0m Traceback (most recent call last)", "\u001b[0;32m\u001b[0m in \u001b[0;36m\u001b[0;34m()\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0mline\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mindex\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m'bear'\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m", "\u001b[0;31mValueError\u001b[0m: substring not found" ] } ], "source": [ "line.index('bear')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The related ``rfind()`` and ``rindex()`` work similarly, except they search for the first occurrence from the end rather than the beginning of the string:" ] }, { "cell_type": "code", "execution_count": 22, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "35" ] }, "execution_count": 22, "metadata": {}, "output_type": "execute_result" } ], "source": [ "line.rfind('a')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "For the special case of checking for a substring at the beginning or end of a string, Python provides the ``startswith()`` and ``endswith()`` methods:" ] }, { "cell_type": "code", "execution_count": 23, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "True" ] }, "execution_count": 23, "metadata": {}, "output_type": "execute_result" } ], "source": [ "line.endswith('dog')" ] }, { "cell_type": "code", "execution_count": 24, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "False" ] }, "execution_count": 24, "metadata": {}, "output_type": "execute_result" } ], "source": [ "line.startswith('fox')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "To go one step further and replace a given substring with a new string, you can use the ``replace()`` method.\n", "Here, let's replace ``'brown'`` with ``'red'``:" ] }, { "cell_type": "code", "execution_count": 25, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "'the quick red fox jumped over a lazy dog'" ] }, "execution_count": 25, "metadata": {}, "output_type": "execute_result" } ], "source": [ "line.replace('brown', 'red')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The ``replace()`` function returns a new string, and will replace all occurrences of the input:" ] }, { "cell_type": "code", "execution_count": 26, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "'the quick br--wn f--x jumped --ver a lazy d--g'" ] }, "execution_count": 26, "metadata": {}, "output_type": "execute_result" } ], "source": [ "line.replace('o', '--')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "For a more flexible approach to this ``replace()`` functionality, see the discussion of regular expressions in [Flexible Pattern Matching with Regular Expressions](#Flexible-Pattern-Matching-with-Regular-Expressions)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Splitting and partitioning strings\n", "\n", "If you would like to find a substring *and then* split the string based on its location, the ``partition()`` and/or ``split()`` methods are what you're looking for.\n", "Both will return a sequence of substrings.\n", "\n", "The ``partition()`` method returns a tuple with three elements: the substring before the first instance of the split-point, the split-point itself, and the substring after:" ] }, { "cell_type": "code", "execution_count": 27, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "('the quick brown ', 'fox', ' jumped over a lazy dog')" ] }, "execution_count": 27, "metadata": {}, "output_type": "execute_result" } ], "source": [ "line.partition('fox')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The ``rpartition()`` method is similar, but searches from the right of the string.\n", "\n", "The ``split()`` method is perhaps more useful; it finds *all* instances of the split-point and returns the substrings in between.\n", "The default is to split on any whitespace, returning a list of the individual words in a string:" ] }, { "cell_type": "code", "execution_count": 28, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "['the', 'quick', 'brown', 'fox', 'jumped', 'over', 'a', 'lazy', 'dog']" ] }, "execution_count": 28, "metadata": {}, "output_type": "execute_result" } ], "source": [ "line.split()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "A related method is ``splitlines()``, which splits on newline characters.\n", "Let's do this with a Haiku, popularly attributed to the 17th-century poet Matsuo Bashō:" ] }, { "cell_type": "code", "execution_count": 29, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "['matsushima-ya', 'aah matsushima-ya', 'matsushima-ya']" ] }, "execution_count": 29, "metadata": {}, "output_type": "execute_result" } ], "source": [ "haiku = \"\"\"matsushima-ya\n", "aah matsushima-ya\n", "matsushima-ya\"\"\"\n", "\n", "haiku.splitlines()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Note that if you would like to undo a ``split()``, you can use the ``join()`` method, which returns a string built from a splitpoint and an iterable:" ] }, { "cell_type": "code", "execution_count": 30, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "'1--2--3'" ] }, "execution_count": 30, "metadata": {}, "output_type": "execute_result" } ], "source": [ "'--'.join(['1', '2', '3'])" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "A common pattern is to use the special character ``\"\\n\"`` (newline) to join together lines that have been previously split, and recover the input:" ] }, { "cell_type": "code", "execution_count": 31, "metadata": { "collapsed": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "matsushima-ya\n", "aah matsushima-ya\n", "matsushima-ya\n" ] } ], "source": [ "print(\"\\n\".join(['matsushima-ya', 'aah matsushima-ya', 'matsushima-ya']))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Format Strings\n", "\n", "In the preceding methods, we have learned how to extract values from strings, and to manipulate strings themselves into desired formats.\n", "Another use of string methods is to manipulate string *representations* of values of other types.\n", "Of course, string representations can always be found using the ``str()`` function; for example:" ] }, { "cell_type": "code", "execution_count": 32, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "'3.14159'" ] }, "execution_count": 32, "metadata": {}, "output_type": "execute_result" } ], "source": [ "pi = 3.14159\n", "str(pi)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "For more complicated formats, you might be tempted to use string arithmetic as outlined in [Basic Python Semantics: Operators](04-Semantics-Operators.ipynb):" ] }, { "cell_type": "code", "execution_count": 33, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "'The value of pi is 3.14159'" ] }, "execution_count": 33, "metadata": {}, "output_type": "execute_result" } ], "source": [ "\"The value of pi is \" + str(pi)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "A more flexible way to do this is to use *format strings*, which are strings with special markers (noted by curly braces) into which string-formatted values will be inserted.\n", "Here is a basic example:" ] }, { "cell_type": "code", "execution_count": 34, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "'The value of pi is 3.14159'" ] }, "execution_count": 34, "metadata": {}, "output_type": "execute_result" } ], "source": [ "\"The value of pi is {}\".format(pi)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Inside the ``{}`` marker you can also include information on exactly *what* you would like to appear there.\n", "If you include a number, it will refer to the index of the argument to insert:" ] }, { "cell_type": "code", "execution_count": 35, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "'First letter: A. Last letter: Z.'" ] }, "execution_count": 35, "metadata": {}, "output_type": "execute_result" } ], "source": [ "\"\"\"First letter: {0}. Last letter: {1}.\"\"\".format('A', 'Z')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "If you include a string, it will refer to the key of any keyword argument:" ] }, { "cell_type": "code", "execution_count": 36, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "'First letter: A. Last letter: Z.'" ] }, "execution_count": 36, "metadata": {}, "output_type": "execute_result" } ], "source": [ "\"\"\"First letter: {first}. Last letter: {last}.\"\"\".format(last='Z', first='A')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Finally, for numerical inputs, you can include format codes which control how the value is converted to a string.\n", "For example, to print a number as a floating point with three digits after the decimal point, you can use the following:" ] }, { "cell_type": "code", "execution_count": 37, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "'pi = 3.142'" ] }, "execution_count": 37, "metadata": {}, "output_type": "execute_result" } ], "source": [ "\"pi = {0:.3f}\".format(pi)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "As before, here the \"``0``\" refers to the index of the value to be inserted.\n", "The \"``:``\" marks that format codes will follow.\n", "The \"``.3f``\" encodes the desired precision: three digits beyond the decimal point, floating-point format.\n", "\n", "This style of format specification is very flexible, and the examples here barely scratch the surface of the formatting options available.\n", "For more information on the syntax of these format strings, see the [Format Specification](https://docs.python.org/3/library/string.html#formatspec) section of Python's online documentation." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Flexible Pattern Matching with Regular Expressions\n", "\n", "The methods of Python's ``str`` type give you a powerful set of tools for formatting, splitting, and manipulating string data.\n", "But even more powerful tools are available in Python's built-in *regular expression* module.\n", "Regular expressions are a huge topic; there are there are entire books written on the topic (including Jeffrey E.F. Friedl’s [*Mastering Regular Expressions, 3rd Edition*](http://shop.oreilly.com/product/9780596528126.do)), so it will be hard to do justice within just a single subsection.\n", "\n", "My goal here is to give you an idea of the types of problems that might be addressed using regular expressions, as well as a basic idea of how to use them in Python.\n", "I'll suggest some references for learning more in [Further Resources on Regular Expressions](#Further-Resources-on-Regular-Expressions).\n", "\n", "Fundamentally, regular expressions are a means of *flexible pattern matching* in strings.\n", "If you frequently use the command-line, you are probably familiar with this type of flexible matching with the \"``*``\" character, which acts as a wildcard.\n", "For example, we can list all the IPython notebooks (i.e., files with extension *.ipynb*) with \"Python\" in their filename by using the \"``*``\" wildcard to match any characters in between:" ] }, { "cell_type": "code", "execution_count": 38, "metadata": { "collapsed": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "01-How-to-Run-Python-Code.ipynb 02-Basic-Python-Syntax.ipynb\r\n" ] } ], "source": [ "!ls *Python*.ipynb" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Regular expressions generalize this \"wildcard\" idea to a wide range of flexible string-matching sytaxes.\n", "The Python interface to regular expressions is contained in the built-in ``re`` module; as a simple example, let's use it to duplicate the functionality of the string ``split()`` method:" ] }, { "cell_type": "code", "execution_count": 39, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "['the', 'quick', 'brown', 'fox', 'jumped', 'over', 'a', 'lazy', 'dog']" ] }, "execution_count": 39, "metadata": {}, "output_type": "execute_result" } ], "source": [ "import re\n", "regex = re.compile('\\s+')\n", "regex.split(line)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Here we've first *compiled* a regular expression, then used it to *split* a string.\n", "Just as Python's ``split()`` method returns a list of all substrings between whitespace, the regular expression ``split()`` method returns a list of all substrings between matches to the input pattern.\n", "\n", "In this case, the input is ``\"\\s+\"``: \"``\\s``\" is a special character that matches any whitespace (space, tab, newline, etc.), and the \"``+``\" is a character that indicates *one or more* of the entity preceding it.\n", "Thus, the regular expression matches any substring consisting of one or more spaces.\n", "\n", "The ``split()`` method here is basically a convenience routine built upon this *pattern matching* behavior; more fundamental is the ``match()`` method, which will tell you whether the beginning of a string matches the pattern:" ] }, { "cell_type": "code", "execution_count": 40, "metadata": { "collapsed": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "' ' matches\n", "'abc ' does not match\n", "' abc' matches\n" ] } ], "source": [ "for s in [\" \", \"abc \", \" abc\"]:\n", " if regex.match(s):\n", " print(repr(s), \"matches\")\n", " else:\n", " print(repr(s), \"does not match\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Like ``split()``, there are similar convenience routines to find the first match (like ``str.index()`` or ``str.find()``) or to find and replace (like ``str.replace()``).\n", "We'll again use the line from before:" ] }, { "cell_type": "code", "execution_count": 41, "metadata": { "collapsed": true }, "outputs": [], "source": [ "line = 'the quick brown fox jumped over a lazy dog'" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "With this, we can see that the ``regex.search()`` method operates a lot like ``str.index()`` or ``str.find()``:" ] }, { "cell_type": "code", "execution_count": 42, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "16" ] }, "execution_count": 42, "metadata": {}, "output_type": "execute_result" } ], "source": [ "line.index('fox')" ] }, { "cell_type": "code", "execution_count": 43, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "16" ] }, "execution_count": 43, "metadata": {}, "output_type": "execute_result" } ], "source": [ "regex = re.compile('fox')\n", "match = regex.search(line)\n", "match.start()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Similarly, the ``regex.sub()`` method operates much like ``str.replace()``:" ] }, { "cell_type": "code", "execution_count": 44, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "'the quick brown BEAR jumped over a lazy dog'" ] }, "execution_count": 44, "metadata": {}, "output_type": "execute_result" } ], "source": [ "line.replace('fox', 'BEAR')" ] }, { "cell_type": "code", "execution_count": 45, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "'the quick brown BEAR jumped over a lazy dog'" ] }, "execution_count": 45, "metadata": {}, "output_type": "execute_result" } ], "source": [ "regex.sub('BEAR', line)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "With a bit of thought, other native string operations can also be cast as regular expressions." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### A more sophisticated example\n", "\n", "But, you might ask, why would you want to use the more complicated and verbose syntax of regular expressions rather than the more intuitive and simple string methods?\n", "The advantage is that regular expressions offer *far* more flexibility.\n", "\n", "Here we'll consider a more complicated example: the common task of matching email addresses.\n", "I'll start by simply writing a (somewhat indecipherable) regular expression, and then walk through what is going on.\n", "Here it goes:" ] }, { "cell_type": "code", "execution_count": 46, "metadata": { "collapsed": true }, "outputs": [], "source": [ "email = re.compile('\\w+@\\w+\\.[a-z]{3}')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Using this, if we're given a line from a document, we can quickly extract things that look like email addresses" ] }, { "cell_type": "code", "execution_count": 47, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "['guido@python.org', 'guido@google.com']" ] }, "execution_count": 47, "metadata": {}, "output_type": "execute_result" } ], "source": [ "text = \"To email Guido, try guido@python.org or the older address guido@google.com.\"\n", "email.findall(text)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "(Note that these addresses are entirely made up; there are probably better ways to get in touch with Guido).\n", "\n", "We can do further operations, like replacing these email addresses with another string, perhaps to hide addresses in the output:" ] }, { "cell_type": "code", "execution_count": 48, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "'To email Guido, try --@--.-- or the older address --@--.--.'" ] }, "execution_count": 48, "metadata": {}, "output_type": "execute_result" } ], "source": [ "email.sub('--@--.--', text)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Finally, note that if you really want to match *any* email address, the preceding regular expression is far too simple.\n", "For example, it only allows addresses made of alphanumeric characters that end in one of several common domain suffixes.\n", "So, for example, the period used here means that we only find part of the address:" ] }, { "cell_type": "code", "execution_count": 49, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "['obama@whitehouse.gov']" ] }, "execution_count": 49, "metadata": {}, "output_type": "execute_result" } ], "source": [ "email.findall('barack.obama@whitehouse.gov')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "This goes to show how unforgiving regular expressions can be if you're not careful!\n", "If you search around online, you can find some suggestions for regular expressions that will match *all* valid emails, but beware: they are much more involved than the simple expression used here!" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Basics of regular expression syntax\n", "\n", "The syntax of regular expressions is much too large a topic for this short section.\n", "Still, a bit of familiarity can go a long way: I will walk through some of the basic constructs here, and then list some more complete resources from which you can learn more.\n", "My hope is that the following quick primer will enable you to use these resources effectively." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Simple strings are matched directly\n", "\n", "If you build a regular expression on a simple string of characters or digits, it will match that exact string:" ] }, { "cell_type": "code", "execution_count": 50, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "['ion']" ] }, "execution_count": 50, "metadata": {}, "output_type": "execute_result" } ], "source": [ "regex = re.compile('ion')\n", "regex.findall('Great Expectations')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Some characters have special meanings\n", "\n", "While simple letters or numbers are direct matches, there are a handful of characters that have special meanings within regular expressions. They are:\n", "```\n", ". ^ $ * + ? { } [ ] \\ | ( )\n", "```\n", "We will discuss the meaning of some of these momentarily.\n", "In the meantime, you should know that if you'd like to match any of these characters directly, you can *escape* them with a back-slash:" ] }, { "cell_type": "code", "execution_count": 51, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "['$']" ] }, "execution_count": 51, "metadata": {}, "output_type": "execute_result" } ], "source": [ "regex = re.compile(r'\\$')\n", "regex.findall(\"the cost is $20\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The ``r`` preface in ``r'\\$'`` indicates a *raw string*; in standard Python strings, the backslash is used to indicate special characters.\n", "For example, a tab is indicated by ``\"\\t\"``:" ] }, { "cell_type": "code", "execution_count": 52, "metadata": { "collapsed": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "a\tb\tc\n" ] } ], "source": [ "print('a\\tb\\tc')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Such substitutions are not made in a raw string:" ] }, { "cell_type": "code", "execution_count": 53, "metadata": { "collapsed": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "a\\tb\\tc\n" ] } ], "source": [ "print(r'a\\tb\\tc')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "For this reason, whenever you use backslashes in a regular expression, it is good practice to use a raw string." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Special characters can match character groups\n", "\n", "Just as the ``\"\\\"`` character within regular expressions can escape special characters, turning them into normal characters, it can also be used to give normal characters special meaning.\n", "These special characters match specified groups of characters, and we've seen them before.\n", "In the email address regexp from before, we used the character ``\"\\w\"``, which is a special marker matching *any alphanumeric character*. Similarly, in the simple ``split()`` example, we also saw ``\"\\s\"``, a special marker indicating *any whitespace character*.\n", "\n", "Putting these together, we can create a regular expression that will match *any two letters/digits with whitespace between them*:" ] }, { "cell_type": "code", "execution_count": 54, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "['e f', 'x i', 's 9', 's o']" ] }, "execution_count": 54, "metadata": {}, "output_type": "execute_result" } ], "source": [ "regex = re.compile(r'\\w\\s\\w')\n", "regex.findall('the fox is 9 years old')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "This example begins to hint at the power and flexibility of regular expressions." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The following table lists a few of these characters that are commonly useful:\n", "\n", "| Character | Description || Character | Description |\n", "|-----------|-----------------------------||-----------|---------------------------------|\n", "| ``\"\\d\"`` | Match any digit || ``\"\\D\"`` | Match any non-digit |\n", "| ``\"\\s\"`` | Match any whitespace || ``\"\\S\"`` | Match any non-whitespace |\n", "| ``\"\\w\"`` | Match any alphanumeric char || ``\"\\W\"`` | Match any non-alphanumeric char |\n", "\n", "This is *not* a comprehensive list or description; for more details, see Python's [regular expression syntax documentation](https://docs.python.org/3/library/re.html#re-syntax)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Square brackets match custom character groups\n", "\n", "If the built-in character groups aren't specific enough for you, you can use square brackets to specify any set of characters you're interested in.\n", "For example, the following will match any lower-case vowel:" ] }, { "cell_type": "code", "execution_count": 55, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "['c', 'ns', 'q', '', 'nt', '', 'l']" ] }, "execution_count": 55, "metadata": {}, "output_type": "execute_result" } ], "source": [ "regex = re.compile('[aeiou]')\n", "regex.split('consequential')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Similarly, you can use a dash to specify a range: for example, ``\"[a-z]\"`` will match any lower-case letter, and ``\"[1-3]\"`` will match any of ``\"1\"``, ``\"2\"``, or ``\"3\"``.\n", "For instance, you may need to extract from a document specific numerical codes that consist of a capital letter followed by a digit. You could do this as follows:" ] }, { "cell_type": "code", "execution_count": 56, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "['G2', 'H6']" ] }, "execution_count": 56, "metadata": {}, "output_type": "execute_result" } ], "source": [ "regex = re.compile('[A-Z][0-9]')\n", "regex.findall('1043879, G2, H6')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Wildcards match repeated characters\n", "\n", "If you would like to match a string with, say, three alphanumeric characters in a row, it is possible to write, for example, ``\"\\w\\w\\w\"``.\n", "Because this is such a common need, there is a specific syntax to match repetitions – curly braces with a number:" ] }, { "cell_type": "code", "execution_count": 57, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "['The', 'qui', 'bro', 'fox']" ] }, "execution_count": 57, "metadata": {}, "output_type": "execute_result" } ], "source": [ "regex = re.compile(r'\\w{3}')\n", "regex.findall('The quick brown fox')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "There are also markers available to match any number of repetitions – for example, the ``\"+\"`` character will match *one or more* repetitions of what precedes it:" ] }, { "cell_type": "code", "execution_count": 58, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "['The', 'quick', 'brown', 'fox']" ] }, "execution_count": 58, "metadata": {}, "output_type": "execute_result" } ], "source": [ "regex = re.compile(r'\\w+')\n", "regex.findall('The quick brown fox')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The following is a table of the repetition markers available for use in regular expressions:\n", "\n", "| Character | Description | Example |\n", "|-----------|-------------|---------|\n", "| ``?`` | Match zero or one repetitions of preceding | ``\"ab?\"`` matches ``\"a\"`` or ``\"ab\"`` |\n", "| ``*`` | Match zero or more repetitions of preceding | ``\"ab*\"`` matches ``\"a\"``, ``\"ab\"``, ``\"abb\"``, ``\"abbb\"``... |\n", "| ``+`` | Match one or more repetitions of preceding | ``\"ab+\"`` matches ``\"ab\"``, ``\"abb\"``, ``\"abbb\"``... but not ``\"a\"`` |\n", "| ``{n}`` | Match ``n`` repetitions of preeeding | ``\"ab{2}\"`` matches ``\"abb\"`` |\n", "| ``{m,n}`` | Match between ``m`` and ``n`` repetitions of preceding | ``\"ab{2,3}\"`` matches ``\"abb\"`` or ``\"abbb\"`` |" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "With these basics in mind, let's return to our email address matcher:" ] }, { "cell_type": "code", "execution_count": 59, "metadata": { "collapsed": true }, "outputs": [], "source": [ "email = re.compile(r'\\w+@\\w+\\.[a-z]{3}')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We can now understand what this means: we want one or more alphanumeric character (``\"\\w+\"``) followed by the *at sign* (``\"@\"``), followed by one or more alphanumeric character (``\"\\w+\"``), followed by a period (``\"\\.\"`` – note the need for a backslash escape), followed by exactly three lower-case letters.\n", "\n", "If we want to now modify this so that the Obama email address matches, we can do so using the square-bracket notation:" ] }, { "cell_type": "code", "execution_count": 60, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "['barack.obama@whitehouse.gov']" ] }, "execution_count": 60, "metadata": {}, "output_type": "execute_result" } ], "source": [ "email2 = re.compile(r'[\\w.]+@\\w+\\.[a-z]{3}')\n", "email2.findall('barack.obama@whitehouse.gov')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We have changed ``\"\\w+\"`` to ``\"[\\w.]+\"``, so we will match any alphanumeric character *or* a period.\n", "With this more flexible expression, we can match a wider range of email addresses (though still not all – can you identify other shortcomings of this expression?)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Parentheses indicate *groups* to extract\n", "\n", "For compound regular expressions like our email matcher, we often want to extract their components rather than the full match. This can be done using parentheses to *group* the results:" ] }, { "cell_type": "code", "execution_count": 61, "metadata": { "collapsed": true }, "outputs": [], "source": [ "email3 = re.compile(r'([\\w.]+)@(\\w+)\\.([a-z]{3})')" ] }, { "cell_type": "code", "execution_count": 62, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "[('guido', 'python', 'org'), ('guido', 'google', 'com')]" ] }, "execution_count": 62, "metadata": {}, "output_type": "execute_result" } ], "source": [ "text = \"To email Guido, try guido@python.org or the older address guido@google.com.\"\n", "email3.findall(text)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "As we see, this grouping actually extracts a list of the sub-components of the email address.\n", "\n", "We can go a bit further and *name* the extracted components using the ``\"(?P )\"`` syntax, in which case the groups can be extracted as a Python dictionary:" ] }, { "cell_type": "code", "execution_count": 63, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "{'domain': 'python', 'suffix': 'org', 'user': 'guido'}" ] }, "execution_count": 63, "metadata": {}, "output_type": "execute_result" } ], "source": [ "email4 = re.compile(r'(?P[\\w.]+)@(?P\\w+)\\.(?P[a-z]{3})')\n", "match = email4.match('guido@python.org')\n", "match.groupdict()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Combining these ideas (as well as some of the powerful regexp syntax that we have not covered here) allows you to flexibly and quickly extract information from strings in Python." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Further Resources on Regular Expressions\n", "\n", "The above discussion is just a quick (and far from complete) treatment of this large topic.\n", "If you'd like to learn more, I recommend the following resources:\n", "\n", "- [Python's ``re`` package Documentation](https://docs.python.org/3/library/re.html): I find that I promptly forget how to use regular expressions just about every time I use them. Now that I have the basics down, I have found this page to be an incredibly valuable resource to recall what each specific character or sequence means within a regular expression.\n", "- [Python's official regular expression HOWTO](https://docs.python.org/3/howto/regex.html): a more narrative approach to regular expressions in Python.\n", "- [Mastering Regular Expressions (OReilly, 2006)](http://shop.oreilly.com/product/9780596528126.do) is a 500+ page book on the subject. If you want a really complete treatment of this topic, this is the resource for you.\n", "\n", "For some examples of string manipulation and regular expressions in action at a larger scale, see [Pandas: Labeled Column-oriented Data](15-Preview-of-Data-Science-Tools.ipynb#Pandas:-Labeled-Column-oriented-Data), where we look at applying these sorts of expressions across *tables* of string data within the Pandas package." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "\n", "< [Modules and Packages](13-Modules-and-Packages.ipynb) | [Contents](Index.ipynb) | [A Preview of Data Science Tools](15-Preview-of-Data-Science-Tools.ipynb) >" ] } ], "metadata": { "anaconda-cloud": {}, "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.5.1" } }, "nbformat": 4, "nbformat_minor": 0 }