~dkuhlman/python-training-materials/Materials

<h1>7.2. <a class="reference internal" href="#module-re" title="re: Regular expression operations."><code class="xref py py-mod docutils literal">re</code></a> — Regular expression operations<a class="headerlink" href="#module-re" title="Permalink to this headline">¶</a></h1>

This module provides regular expression matching operations similar to

those found in Perl. Both patterns and strings to be searched can be

Unicode strings as well as 8-bit strings.

Regular expressions use the backslash character (<code class="docutils literal">'\'</code>) to indicate

special forms or to allow special characters to be used without invoking

their special meaning. This collides with Python’s usage of the same

character for the same purpose in string literals; for example, to match

a literal backslash, one might have to write <code class="docutils literal">'\\\\'</code> as the pattern

string, because the regular expression must be <code class="docutils literal">\\</code>, and each

backslash must be expressed as <code class="docutils literal">\\</code> inside a regular Python string

literal.

The solution is to use Python’s raw string notation for regular expression

patterns; backslashes are not handled in any special way in a string literal

prefixed with <code class="docutils literal">'r'</code>. So <code class="docutils literal">r"\n"</code> is a two-character string containing

<code class="docutils literal">'\'</code> and <code class="docutils literal">'n'</code>, while <code class="docutils literal">"\n"</code> is a one-character string containing a

newline. Usually patterns will be expressed in Python code using this raw

string notation.

It is important to note that most regular expression operations are available as

module-level functions and <a class="reference internal" href="#re.RegexObject" title="re.RegexObject"><code class="xref py py-class docutils literal">RegexObject</code></a> methods. The functions are

shortcuts that don’t require you to compile a regex object first, but miss some

fine-tuning parameters.

100

101

<h2>7.2.1. Regular Expression Syntax<a class="headerlink" href="#regular-expression-syntax" title="Permalink to this headline">¶</a></h2>

102

A regular expression (or RE) specifies a set of strings that matches it; the

103

functions in this module let you check if a particular string matches a given

104

regular expression (or if a given regular expression matches a particular

105

string, which comes down to the same thing).

106

Regular expressions can be concatenated to form new regular expressions; if A

107

and B are both regular expressions, then AB is also a regular expression.

108

In general, if a string p matches A and another string q matches B, the

109

string pq will match AB. This holds unless A or B contain low precedence

110

operations; boundary conditions between A and B; or have numbered group

111

references. Thus, complex expressions can easily be constructed from simpler

112

primitive expressions like the ones described here. For details of the theory

113

and implementation of regular expressions, consult the Friedl book referenced

114

above, or almost any textbook about compiler construction.

115

A brief explanation of the format of regular expressions follows. For further

116

information and a gentler presentation, consult the <a class="reference internal" href="../howto/regex.html#regex-howto">Regular Expression HOWTO</a>.

117

Regular expressions can contain both special and ordinary characters. Most

118

ordinary characters, like <code class="docutils literal">'A'</code>, <code class="docutils literal">'a'</code>, or <code class="docutils literal">'0'</code>, are the simplest regular

119

expressions; they simply match themselves. You can concatenate ordinary

120

characters, so <code class="docutils literal">last</code> matches the string <code class="docutils literal">'last'</code>. (In the rest of this

121

section, we’ll write RE’s in <code class="docutils literal">this special style</code>, usually without quotes, and

122

strings to be matched <code class="docutils literal">'in single quotes'</code>.)

123

Some characters, like <code class="docutils literal">'|'</code> or <code class="docutils literal">'('</code>, are special. Special

124

characters either stand for classes of ordinary characters, or affect

125

how the regular expressions around them are interpreted. Regular

126

expression pattern strings may not contain null bytes, but can specify

127

the null byte using the <code class="docutils literal">\number</code> notation, e.g., <code class="docutils literal">'\x00'</code>.

128

The special characters are:

129

130

131

<dd>(Dot.) In the default mode, this matches any character except a newline. If

132

the <a class="reference internal" href="#re.DOTALL" title="re.DOTALL"><code class="xref py py-const docutils literal">DOTALL</code></a> flag has been specified, this matches any character

133

including a newline.</dd>

134

135

<dd>(Caret.) Matches the start of the string, and in <a class="reference internal" href="#re.MULTILINE" title="re.MULTILINE"><code class="xref py py-const docutils literal">MULTILINE</code></a> mode also

136

matches immediately after each newline.</dd>

137

138

<dd>Matches the end of the string or just before the newline at the end of the

139

string, and in <a class="reference internal" href="#re.MULTILINE" title="re.MULTILINE"><code class="xref py py-const docutils literal">MULTILINE</code></a> mode also matches before a newline. <code class="docutils literal">foo</code>

140

matches both ‘foo’ and ‘foobar’, while the regular expression <code class="docutils literal">foo$</code> matches

141

only ‘foo’. More interestingly, searching for <code class="docutils literal">foo.$</code> in <code class="docutils literal">'foo1\nfoo2\n'</code>

142

matches ‘foo2’ normally, but ‘foo1’ in <a class="reference internal" href="#re.MULTILINE" title="re.MULTILINE"><code class="xref py py-const docutils literal">MULTILINE</code></a> mode; searching for

143

a single <code class="docutils literal">$</code> in <code class="docutils literal">'foo\n'</code> will find two (empty) matches: one just before

144

the newline, and one at the end of the string.</dd>

145

146

<dd>Causes the resulting RE to match 0 or more repetitions of the preceding RE, as

147

many repetitions as are possible. <code class="docutils literal">ab*</code> will match ‘a’, ‘ab’, or ‘a’ followed

148

by any number of ‘b’s.</dd>

149

150

<dd>Causes the resulting RE to match 1 or more repetitions of the preceding RE.

151

<code class="docutils literal">ab+</code> will match ‘a’ followed by any non-zero number of ‘b’s; it will not

152

match just ‘a’.</dd>

153

154

<dd>Causes the resulting RE to match 0 or 1 repetitions of the preceding RE.

155

<code class="docutils literal">ab?</code> will match either ‘a’ or ‘ab’.</dd>

156

157

<dd>The <code class="docutils literal">'*'</code>, <code class="docutils literal">'+'</code>, and <code class="docutils literal">'?'</code> qualifiers are all greedy; they match

158

as much text as possible. Sometimes this behaviour isn’t desired; if the RE

159

<code class="docutils literal"><.*></code> is matched against <code class="docutils literal">'<H1>title</H1>'</code>, it will match the entire

160

string, and not just <code class="docutils literal">'<H1>'</code>. Adding <code class="docutils literal">'?'</code> after the qualifier makes it

161

perform the match in non-greedy or minimal fashion; as few

162

characters as possible will be matched. Using <code class="docutils literal">.*?</code> in the previous

163

expression will match only <code class="docutils literal">'<H1>'</code>.</dd>

164

165

<dd>Specifies that exactly m copies of the previous RE should be matched; fewer

166

matches cause the entire RE not to match. For example, <code class="docutils literal">a{6}</code> will match

167

exactly six <code class="docutils literal">'a'</code> characters, but not five.</dd>

168

169

<dd>Causes the resulting RE to match from m to n repetitions of the preceding

170

RE, attempting to match as many repetitions as possible. For example,

171

<code class="docutils literal">a{3,5}</code> will match from 3 to 5 <code class="docutils literal">'a'</code> characters. Omitting m specifies a

172

lower bound of zero, and omitting n specifies an infinite upper bound. As an

173

example, <code class="docutils literal">a{4,}b</code> will match <code class="docutils literal">aaaab</code> or a thousand <code class="docutils literal">'a'</code> characters

174

followed by a <code class="docutils literal">b</code>, but not <code class="docutils literal">aaab</code>. The comma may not be omitted or the

175

modifier would be confused with the previously described form.</dd>

176

177

<dd>Causes the resulting RE to match from m to n repetitions of the preceding

178

RE, attempting to match as few repetitions as possible. This is the

179

non-greedy version of the previous qualifier. For example, on the

180

6-character string <code class="docutils literal">'aaaaaa'</code>, <code class="docutils literal">a{3,5}</code> will match 5 <code class="docutils literal">'a'</code> characters,

181

while <code class="docutils literal">a{3,5}?</code> will only match 3 characters.</dd>

182

183

<dd>Either escapes special characters (permitting you to match characters like

184

<code class="docutils literal">'*'</code>, <code class="docutils literal">'?'</code>, and so forth), or signals a special sequence; special

185

sequences are discussed below.

186

If you’re not using a raw string to express the pattern, remember that Python

187

also uses the backslash as an escape sequence in string literals; if the escape

188

sequence isn’t recognized by Python’s parser, the backslash and subsequent

189

character are included in the resulting string. However, if Python would

190

recognize the resulting sequence, the backslash should be repeated twice. This

191

is complicated and hard to understand, so it’s highly recommended that you use

192

raw strings for all but the simplest expressions.

193

</dd>

194

195

<dd>Used to indicate a set of characters. In a set:

196

197

<li>Characters can be listed individually, e.g. <code class="docutils literal">[amk]</code> will match <code class="docutils literal">'a'</code>,

198

199

<li>Ranges of characters can be indicated by giving two characters and separating

200

them by a <code class="docutils literal">'-'</code>, for example <code class="docutils literal">[a-z]</code> will match any lowercase ASCII letter,

201

<code class="docutils literal">[0-5][0-9]</code> will match all the two-digits numbers from <code class="docutils literal">00</code> to <code class="docutils literal">59</code>, and

202

<code class="docutils literal">[0-9A-Fa-f]</code> will match any hexadecimal digit. If <code class="docutils literal">-</code> is escaped (e.g.

203

<code class="docutils literal">[a\-z]</code>) or if it’s placed as the first or last character (e.g. <code class="docutils literal">[a-]</code>),

204

it will match a literal <code class="docutils literal">'-'</code>.</li>

205

<li>Special characters lose their special meaning inside sets. For example,

206

<code class="docutils literal">[(+*)]</code> will match any of the literal characters <code class="docutils literal">'('</code>, <code class="docutils literal">'+'</code>,

207

208

<li>Character classes such as <code class="docutils literal">\w</code> or <code class="docutils literal">\S</code> (defined below) are also accepted

209

inside a set, although the characters they match depends on whether

210

<a class="reference internal" href="#re.LOCALE" title="re.LOCALE"><code class="xref py py-const docutils literal">LOCALE</code></a> or <a class="reference internal" href="#re.UNICODE" title="re.UNICODE"><code class="xref py py-const docutils literal">UNICODE</code></a> mode is in force.</li>

211

<li>Characters that are not within a range can be matched by complementing

212

the set. If the first character of the set is <code class="docutils literal">'^'</code>, all the characters

213

that are not in the set will be matched. For example, <code class="docutils literal">[^5]</code> will match

214

any character except <code class="docutils literal">'5'</code>, and <code class="docutils literal">[^^]</code> will match any character except

215

<code class="docutils literal">'^'</code>. <code class="docutils literal">^</code> has no special meaning if it’s not the first character in

216

the set.</li>

217

<li>To match a literal <code class="docutils literal">']'</code> inside a set, precede it with a backslash, or

218

place it at the beginning of the set. For example, both <code class="docutils literal">[()[\]{}]</code> and

219

<code class="docutils literal">[]()[{}]</code> will both match a parenthesis.</li>

220

</ul>

221

</dd>

222

223

<dd><code class="docutils literal">A|B</code>, where A and B can be arbitrary REs, creates a regular expression that

224

will match either A or B. An arbitrary number of REs can be separated by the

225

<code class="docutils literal">'|'</code> in this way. This can be used inside groups (see below) as well. As

226

the target string is scanned, REs separated by <code class="docutils literal">'|'</code> are tried from left to

227

right. When one pattern completely matches, that branch is accepted. This means

228

that once <code class="docutils literal">A</code> matches, <code class="docutils literal">B</code> will not be tested further, even if it would

229

produce a longer overall match. In other words, the <code class="docutils literal">'|'</code> operator is never

230

greedy. To match a literal <code class="docutils literal">'|'</code>, use <code class="docutils literal">\|</code>, or enclose it inside a

231

character class, as in <code class="docutils literal">[|]</code>.</dd>

232

233

<dd>Matches whatever regular expression is inside the parentheses, and indicates the

234

start and end of a group; the contents of a group can be retrieved after a match

235

has been performed, and can be matched later in the string with the <code class="docutils literal">\number</code>

236

special sequence, described below. To match the literals <code class="docutils literal">'('</code> or <code class="docutils literal">')'</code>,

237

use <code class="docutils literal">$</code> or <code class="docutils literal">$</code>, or enclose them inside a character class: <code class="docutils literal">[(] [)]</code>.</dd>

238

239

<dd>This is an extension notation (a <code class="docutils literal">'?'</code> following a <code class="docutils literal">'('</code> is not meaningful

240

otherwise). The first character after the <code class="docutils literal">'?'</code> determines what the meaning

241

and further syntax of the construct is. Extensions usually do not create a new

242

group; <code class="docutils literal">(?P<name>...)</code> is the only exception to this rule. Following are the

243

currently supported extensions.</dd>

244

<dt><code class="docutils literal">(?iLmsux)</code></dt>

245

<dd>(One or more letters from the set <code class="docutils literal">'i'</code>, <code class="docutils literal">'L'</code>, <code class="docutils literal">'m'</code>, <code class="docutils literal">'s'</code>,

246

<code class="docutils literal">'u'</code>, <code class="docutils literal">'x'</code>.) The group matches the empty string; the letters

247

set the corresponding flags: <a class="reference internal" href="#re.I" title="re.I"><code class="xref py py-const docutils literal">re.I</code></a> (ignore case),

248

<a class="reference internal" href="#re.L" title="re.L"><code class="xref py py-const docutils literal">re.L</code></a> (locale dependent), <a class="reference internal" href="#re.M" title="re.M"><code class="xref py py-const docutils literal">re.M</code></a> (multi-line),

249

<a class="reference internal" href="#re.S" title="re.S"><code class="xref py py-const docutils literal">re.S</code></a> (dot matches all), <a class="reference internal" href="#re.U" title="re.U"><code class="xref py py-const docutils literal">re.U</code></a> (Unicode dependent),

250

and <a class="reference internal" href="#re.X" title="re.X"><code class="xref py py-const docutils literal">re.X</code></a> (verbose), for the entire regular expression. (The

251

flags are described in <a class="reference internal" href="#contents-of-module-re">Module Contents</a>.) This

252

is useful if you wish to include the flags as part of the regular

253

expression, instead of passing a flag argument to the

254

<a class="reference internal" href="#re.compile" title="re.compile"><code class="xref py py-func docutils literal">re.compile()</code></a> function.

255

Note that the <code class="docutils literal">(?x)</code> flag changes how the expression is parsed. It should be

256

used first in the expression string, or after one or more whitespace characters.

257

If there are non-whitespace characters before the flag, the results are

258

undefined.

259

</dd>

260

261

<dd>A non-capturing version of regular parentheses. Matches whatever regular

262

expression is inside the parentheses, but the substring matched by the group

263

cannot be retrieved after performing a match or referenced later in the

264

pattern.</dd>

265

266

<dd>Similar to regular parentheses, but the substring matched by the group is

267

accessible via the symbolic group name name. Group names must be valid

268

Python identifiers, and each group name must be defined only once within a

269

regular expression. A symbolic group is also a numbered group, just as if

270

the group were not named.

271

Named groups can be referenced in three contexts. If the pattern is

272

<code class="docutils literal">(?P<quote>['"]).*?(?P=quote)</code> (i.e. matching a string quoted with either

273

single or double quotes):

274

275

276

277

278

</colgroup>

279

280

<tr class="row-odd"><th class="head">Context of reference to group “quote”</th>

281

<th class="head">Ways to reference it</th>

282

</tr>

283

</thead>

284

285

<tr class="row-even"><td>in the same pattern itself</td>

286

287

<li><code class="docutils literal">(?P=quote)</code> (as shown)</li>

288

289

</ul>

290

</td>

291

</tr>

292

<tr class="row-odd"><td>when processing match object <code class="docutils literal">m</code></td>

293

294

<li><code class="docutils literal">m.group('quote')</code></li>

295

<li><code class="docutils literal">m.end('quote')</code> (etc.)</li>

296

</ul>

297

</td>

298

</tr>

299

<tr class="row-even"><td>in a string passed to the <code class="docutils literal">repl</code>

300

argument of <code class="docutils literal">re.sub()</code></td>

301

302

303

304

305

</ul>

306

</td>

307

</tr>

308

</tbody>

309

</table>

310

</dd>

311

312

<dd>A backreference to a named group; it matches whatever text was matched by the

313

earlier group named name.</dd>

314

315

<dd>A comment; the contents of the parentheses are simply ignored.</dd>

316

317

<dd>Matches if <code class="docutils literal">...</code> matches next, but doesn’t consume any of the string. This is

318

called a lookahead assertion. For example, <code class="docutils literal">Isaac (?=Asimov)</code> will match

319

<code class="docutils literal">'Isaac '</code> only if it’s followed by <code class="docutils literal">'Asimov'</code>.</dd>

320

321

<dd>Matches if <code class="docutils literal">...</code> doesn’t match next. This is a negative lookahead assertion.

322

For example, <code class="docutils literal">Isaac (?!Asimov)</code> will match <code class="docutils literal">'Isaac '</code> only if it’s not

323

followed by <code class="docutils literal">'Asimov'</code>.</dd>

324

325

<dd>Matches if the current position in the string is preceded by a match for <code class="docutils literal">...</code>

326

that ends at the current position. This is called a positive lookbehind

327

assertion. <code class="docutils literal">(?<=abc)def</code> will find a match in <code class="docutils literal">abcdef</code>, since the

328

lookbehind will back up 3 characters and check if the contained pattern matches.

329

The contained pattern must only match strings of some fixed length, meaning that

330

<code class="docutils literal">abc</code> or <code class="docutils literal">a|b</code> are allowed, but <code class="docutils literal">a*</code> and <code class="docutils literal">a{3,4}</code> are not. Group

331

references are not supported even if they match strings of some fixed length.

332

Note that

333

patterns which start with positive lookbehind assertions will not match at the

334

beginning of the string being searched; you will most likely want to use the

335

<a class="reference internal" href="#re.search" title="re.search"><code class="xref py py-func docutils literal">search()</code></a> function rather than the <a class="reference internal" href="#re.match" title="re.match"><code class="xref py py-func docutils literal">match()</code></a> function:

336

<div class="highlight-python"><div class="highlight"><pre>>>> import re

337

>>> m = re.search('(?<=abc)def', 'abcdef')

338

>>> m.group(0)

339

'def'

340

</pre></div>

341

</div>

342

This example looks for a word following a hyphen:

343

<div class="last highlight-python"><div class="highlight"><pre>>>> m = re.search('(?<=-)\w+', 'spam-egg')

344

>>> m.group(0)

345

'egg'

346

</pre></div>

347

</div>

348

</dd>

349

350

<dd>Matches if the current position in the string is not preceded by a match for

351

<code class="docutils literal">...</code>. This is called a negative lookbehind assertion. Similar to

352

positive lookbehind assertions, the contained pattern must only match strings of

353

some fixed length and shouldn’t contain group references.

354

Patterns which start with negative lookbehind assertions may

355

match at the beginning of the string being searched.</dd>

356

<dt><code class="docutils literal">(?(id/name)yes-pattern|no-pattern)</code></dt>

357

<dd>Will try to match with <code class="docutils literal">yes-pattern</code> if the group with given id or name

358

exists, and with <code class="docutils literal">no-pattern</code> if it doesn’t. <code class="docutils literal">no-pattern</code> is optional and

359

can be omitted. For example, <code class="docutils literal">(<)?(\w+@\w+(?:\.\w+)+)(?(1)>)</code> is a poor email

360

matching pattern, which will match with <code class="docutils literal">'<user@host.com>'</code> as well as

361

<code class="docutils literal">'user@host.com'</code>, but not with <code class="docutils literal">'<user@host.com'</code>.

362

363

New in version 2.4.

364

</div>

365

</dd>

366

</dl>

367

The special sequences consist of <code class="docutils literal">'\'</code> and a character from the list below.

368

If the ordinary character is not on the list, then the resulting RE will match

369

the second character. For example, <code class="docutils literal">\$</code> matches the character <code class="docutils literal">'$'</code>.

370

371

<dt><code class="docutils literal">\number</code></dt>

372

<dd>Matches the contents of the group of the same number. Groups are numbered

373

starting from 1. For example, <code class="docutils literal">(.+) \1</code> matches <code class="docutils literal">'the the'</code> or <code class="docutils literal">'55 55'</code>,

374

but not <code class="docutils literal">'thethe'</code> (note the space after the group). This special sequence

375

can only be used to match one of the first 99 groups. If the first digit of

376

number is 0, or number is 3 octal digits long, it will not be interpreted as

377

a group match, but as the character with octal value number. Inside the

378

<code class="docutils literal">'['</code> and <code class="docutils literal">']'</code> of a character class, all numeric escapes are treated as

379

characters.</dd>

380

381

<dd>Matches only at the start of the string.</dd>

382

383

<dd>Matches the empty string, but only at the beginning or end of a word. A word is

384

defined as a sequence of alphanumeric or underscore characters, so the end of a

385

word is indicated by whitespace or a non-alphanumeric, non-underscore character.

386

Note that formally, <code class="docutils literal">\b</code> is defined as the boundary between a <code class="docutils literal">\w</code> and

387

a <code class="docutils literal">\W</code> character (or vice versa), or between <code class="docutils literal">\w</code> and the beginning/end

388

of the string, so the precise set of characters deemed to be alphanumeric

389

depends on the values of the <code class="docutils literal">UNICODE</code> and <code class="docutils literal">LOCALE</code> flags.

390

For example, <code class="docutils literal">r'\bfoo\b'</code> matches <code class="docutils literal">'foo'</code>, <code class="docutils literal">'foo.'</code>, <code class="docutils literal">'(foo)'</code>,

391

<code class="docutils literal">'bar foo baz'</code> but not <code class="docutils literal">'foobar'</code> or <code class="docutils literal">'foo3'</code>.

392

Inside a character range, <code class="docutils literal">\b</code> represents the backspace character, for

393

compatibility with Python’s string literals.</dd>

394

395

<dd>Matches the empty string, but only when it is not at the beginning or end of a

396

word. This means that <code class="docutils literal">r'py\B'</code> matches <code class="docutils literal">'python'</code>, <code class="docutils literal">'py3'</code>, <code class="docutils literal">'py2'</code>,

397

but not <code class="docutils literal">'py'</code>, <code class="docutils literal">'py.'</code>, or <code class="docutils literal">'py!'</code>.

398

<code class="docutils literal">\B</code> is just the opposite of <code class="docutils literal">\b</code>, so is also subject to the settings

399

of <code class="docutils literal">LOCALE</code> and <code class="docutils literal">UNICODE</code>.</dd>

400

401

<dd>When the <a class="reference internal" href="#re.UNICODE" title="re.UNICODE"><code class="xref py py-const docutils literal">UNICODE</code></a> flag is not specified, matches any decimal digit; this

402

is equivalent to the set <code class="docutils literal">[0-9]</code>. With <a class="reference internal" href="#re.UNICODE" title="re.UNICODE"><code class="xref py py-const docutils literal">UNICODE</code></a>, it will match

403

whatever is classified as a decimal digit in the Unicode character properties

404

database.</dd>

405

406

407

character; this is equivalent to the set <code class="docutils literal">[^0-9]</code>. With <a class="reference internal" href="#re.UNICODE" title="re.UNICODE"><code class="xref py py-const docutils literal">UNICODE</code></a>, it

408

will match anything other than character marked as digits in the Unicode

409

character properties database.</dd>

410

411

412

character, this is equivalent to the set <code class="docutils literal">[ \t\n\r\f\v]</code>. The

413

<a class="reference internal" href="#re.LOCALE" title="re.LOCALE"><code class="xref py py-const docutils literal">LOCALE</code></a> flag has no extra effect on matching of the space.

414

If <a class="reference internal" href="#re.UNICODE" title="re.UNICODE"><code class="xref py py-const docutils literal">UNICODE</code></a> is set, this will match the characters <code class="docutils literal">[ \t\n\r\f\v]</code>

415

plus whatever is classified as space in the Unicode character properties

416

database.</dd>

417

418

419

character; this is equivalent to the set <code class="docutils literal">[^ \t\n\r\f\v]</code> The

420

421

<a class="reference internal" href="#re.UNICODE" title="re.UNICODE"><code class="xref py py-const docutils literal">UNICODE</code></a> is set, then any character not marked as space in the

422

Unicode character properties database is matched.</dd>

423

424

<dd>When the <a class="reference internal" href="#re.LOCALE" title="re.LOCALE"><code class="xref py py-const docutils literal">LOCALE</code></a> and <a class="reference internal" href="#re.UNICODE" title="re.UNICODE"><code class="xref py py-const docutils literal">UNICODE</code></a> flags are not specified, matches

425

any alphanumeric character and the underscore; this is equivalent to the set

426

<code class="docutils literal">[a-zA-Z0-9_]</code>. With <a class="reference internal" href="#re.LOCALE" title="re.LOCALE"><code class="xref py py-const docutils literal">LOCALE</code></a>, it will match the set <code class="docutils literal">[0-9_]</code> plus

427

whatever characters are defined as alphanumeric for the current locale. If

428

429

is classified as alphanumeric in the Unicode character properties database.</dd>

430

431

432

any non-alphanumeric character; this is equivalent to the set <code class="docutils literal">[^a-zA-Z0-9_]</code>.

433

With <a class="reference internal" href="#re.LOCALE" title="re.LOCALE"><code class="xref py py-const docutils literal">LOCALE</code></a>, it will match any character not in the set <code class="docutils literal">[0-9_]</code>, and

434

not defined as alphanumeric for the current locale. If <a class="reference internal" href="#re.UNICODE" title="re.UNICODE"><code class="xref py py-const docutils literal">UNICODE</code></a> is set,

435

this will match anything other than <code class="docutils literal">[0-9_]</code> plus characters classified as

436

not alphanumeric in the Unicode character properties database.</dd>

437

438

<dd>Matches only at the end of the string.</dd>

439

</dl>

440

If both <a class="reference internal" href="#re.LOCALE" title="re.LOCALE"><code class="xref py py-const docutils literal">LOCALE</code></a> and <a class="reference internal" href="#re.UNICODE" title="re.UNICODE"><code class="xref py py-const docutils literal">UNICODE</code></a> flags are included for a

441

particular sequence, then <a class="reference internal" href="#re.LOCALE" title="re.LOCALE"><code class="xref py py-const docutils literal">LOCALE</code></a> flag takes effect first followed by

442

the <a class="reference internal" href="#re.UNICODE" title="re.UNICODE"><code class="xref py py-const docutils literal">UNICODE</code></a>.

443

Most of the standard escapes supported by Python string literals are also

444

accepted by the regular expression parser:

445

<div class="highlight-python"><div class="highlight"><pre>\a \b \f \n

446

\r \t \v \x

447

448

</pre></div>

449

</div>

450

(Note that <code class="docutils literal">\b</code> is used to represent word boundaries, and means “backspace”

451

only inside character classes.)

452

Octal escapes are included in a limited form: If the first digit is a 0, or if

453

there are three octal digits, it is considered an octal escape. Otherwise, it is

454

a group reference. As for string literals, octal escapes are always at most

455

three digits in length.

456

457

See also

458

459

<dt>Mastering Regular Expressions</dt>

460

<dd>Book on regular expressions by Jeffrey Friedl, published by O’Reilly. The

461

second edition of the book no longer covers Python at all, but the first

462

edition covered writing good regular expression patterns in great detail.</dd>

463

</dl>

464

</div>

465

</div>

466

467

<h2>7.2.2. Module Contents<a class="headerlink" href="#module-contents" title="Permalink to this headline">¶</a></h2>

468

The module defines several functions, constants, and an exception. Some of the

469

functions are simplified versions of the full featured methods for compiled

470

regular expressions. Most non-trivial applications always use the compiled

471

form.

472

473

474

<code class="descclassname">re.</code><code class="descname">compile</code>(pattern, flags=0)<a class="headerlink" href="#re.compile" title="Permalink to this definition">¶</a></dt>

475

<dd>Compile a regular expression pattern into a regular expression object, which

476

can be used for matching using its <a class="reference internal" href="#re.RegexObject.match" title="re.RegexObject.match"><code class="xref py py-func docutils literal">match()</code></a> and

477

<a class="reference internal" href="#re.RegexObject.search" title="re.RegexObject.search"><code class="xref py py-func docutils literal">search()</code></a> methods, described below.

478

The expression’s behaviour can be modified by specifying a flags value.

479

Values can be any of the following variables, combined using bitwise OR (the

480

<code class="docutils literal">|</code> operator).

481

The sequence

482

<div class="highlight-python"><div class="highlight"><pre>prog = re.compile(pattern)

483

result = prog.match(string)

484

</pre></div>

485

</div>

486

is equivalent to

487

<div class="highlight-python"><div class="highlight"><pre>result = re.match(pattern, string)

488

</pre></div>

489

</div>

490

but using <a class="reference internal" href="#re.compile" title="re.compile"><code class="xref py py-func docutils literal">re.compile()</code></a> and saving the resulting regular expression

491

object for reuse is more efficient when the expression will be used several

492

times in a single program.

493

494

Note

495

The compiled versions of the most recent patterns passed to

496

<a class="reference internal" href="#re.match" title="re.match"><code class="xref py py-func docutils literal">re.match()</code></a>, <a class="reference internal" href="#re.search" title="re.search"><code class="xref py py-func docutils literal">re.search()</code></a> or <a class="reference internal" href="#re.compile" title="re.compile"><code class="xref py py-func docutils literal">re.compile()</code></a> are cached, so

497

programs that use only a few regular expressions at a time needn’t worry

498

about compiling regular expressions.

499

</div>

500

</dd></dl>

501

502

503

504

<code class="descclassname">re.</code><code class="descname">DEBUG</code><a class="headerlink" href="#re.DEBUG" title="Permalink to this definition">¶</a></dt>

505

<dd>Display debug information about compiled expression.

506

</dd></dl>

507

508

509

510

511

512

<code class="descclassname">re.</code><code class="descname">IGNORECASE</code><a class="headerlink" href="#re.IGNORECASE" title="Permalink to this definition">¶</a></dt>

513

<dd>Perform case-insensitive matching; expressions like <code class="docutils literal">[A-Z]</code> will match

514

lowercase letters, too. This is not affected by the current locale.

515

</dd></dl>

516

517

518

519

520

521

<code class="descclassname">re.</code><code class="descname">LOCALE</code><a class="headerlink" href="#re.LOCALE" title="Permalink to this definition">¶</a></dt>

522

<dd>Make <code class="docutils literal">\w</code>, <code class="docutils literal">\W</code>, <code class="docutils literal">\b</code>, <code class="docutils literal">\B</code>, <code class="docutils literal">\s</code> and <code class="docutils literal">\S</code> dependent on the

523

current locale.

524

</dd></dl>

525

526

527

528

529

530

<code class="descclassname">re.</code><code class="descname">MULTILINE</code><a class="headerlink" href="#re.MULTILINE" title="Permalink to this definition">¶</a></dt>

531

<dd>When specified, the pattern character <code class="docutils literal">'^'</code> matches at the beginning of the

532

string and at the beginning of each line (immediately following each newline);

533

and the pattern character <code class="docutils literal">'$'</code> matches at the end of the string and at the

534

end of each line (immediately preceding each newline). By default, <code class="docutils literal">'^'</code>

535

matches only at the beginning of the string, and <code class="docutils literal">'$'</code> only at the end of the

536

string and immediately before the newline (if any) at the end of the string.

537

</dd></dl>

538

539

540

541

542

543

<code class="descclassname">re.</code><code class="descname">DOTALL</code><a class="headerlink" href="#re.DOTALL" title="Permalink to this definition">¶</a></dt>

544

<dd>Make the <code class="docutils literal">'.'</code> special character match any character at all, including a

545

newline; without this flag, <code class="docutils literal">'.'</code> will match anything except a newline.

546

</dd></dl>

547

548

549

550

551

552

<code class="descclassname">re.</code><code class="descname">UNICODE</code><a class="headerlink" href="#re.UNICODE" title="Permalink to this definition">¶</a></dt>

553

<dd>Make <code class="docutils literal">\w</code>, <code class="docutils literal">\W</code>, <code class="docutils literal">\b</code>, <code class="docutils literal">\B</code>, <code class="docutils literal">\d</code>, <code class="docutils literal">\D</code>, <code class="docutils literal">\s</code> and <code class="docutils literal">\S</code> dependent

554

on the Unicode character properties database.

555

556

New in version 2.0.

557

</div>

558

</dd></dl>

559

560

561

562

563

564

<code class="descclassname">re.</code><code class="descname">VERBOSE</code><a class="headerlink" href="#re.VERBOSE" title="Permalink to this definition">¶</a></dt>

565

<dd>This flag allows you to write regular expressions that look nicer and are

566

more readable by allowing you to visually separate logical sections of the

567

pattern and add comments. Whitespace within the pattern is ignored, except

568

when in a character class or when preceded by an unescaped backslash.

569

When a line contains a <code class="docutils literal">#</code> that is not in a character class and is not

570

preceded by an unescaped backslash, all characters from the leftmost such

571

<code class="docutils literal">#</code> through the end of the line are ignored.

572

This means that the two following regular expression objects that match a

573

decimal number are functionally equal:

574

<div class="highlight-python"><div class="highlight"><pre>a = re.compile(r"""\d + # the integral part

575

\. # the decimal point

576

\d * # some fractional digits""", re.X)

577

b = re.compile(r"\d+\.\d*")

578

</pre></div>

579

</div>

580

</dd></dl>

581

582

583

584

<code class="descclassname">re.</code><code class="descname">search</code>(pattern, string, flags=0)<a class="headerlink" href="#re.search" title="Permalink to this definition">¶</a></dt>

585

<dd>Scan through string looking for the first location where the regular expression

586

pattern produces a match, and return a corresponding <a class="reference internal" href="#re.MatchObject" title="re.MatchObject"><code class="xref py py-class docutils literal">MatchObject</code></a>

587

instance. Return <code class="docutils literal">None</code> if no position in the string matches the pattern; note

588

that this is different from finding a zero-length match at some point in the

589

string.

590

</dd></dl>

591

592

593

594

<code class="descclassname">re.</code><code class="descname">match</code>(pattern, string, flags=0)<a class="headerlink" href="#re.match" title="Permalink to this definition">¶</a></dt>

595

<dd>If zero or more characters at the beginning of string match the regular

596

expression pattern, return a corresponding <a class="reference internal" href="#re.MatchObject" title="re.MatchObject"><code class="xref py py-class docutils literal">MatchObject</code></a> instance.

597

Return <code class="docutils literal">None</code> if the string does not match the pattern; note that this is

598

different from a zero-length match.

599

Note that even in <a class="reference internal" href="#re.MULTILINE" title="re.MULTILINE"><code class="xref py py-const docutils literal">MULTILINE</code></a> mode, <a class="reference internal" href="#re.match" title="re.match"><code class="xref py py-func docutils literal">re.match()</code></a> will only match

600

at the beginning of the string and not at the beginning of each line.

601

If you want to locate a match anywhere in string, use <a class="reference internal" href="#re.search" title="re.search"><code class="xref py py-func docutils literal">search()</code></a>

602

instead (see also <a class="reference internal" href="#search-vs-match">search() vs. match()</a>).

603

</dd></dl>

604

605

606

607

<code class="descclassname">re.</code><code class="descname">split</code>(pattern, string, maxsplit=0, flags=0)<a class="headerlink" href="#re.split" title="Permalink to this definition">¶</a></dt>

608

<dd>Split string by the occurrences of pattern. If capturing parentheses are

609

used in pattern, then the text of all groups in the pattern are also returned

610

as part of the resulting list. If maxsplit is nonzero, at most maxsplit

611

splits occur, and the remainder of the string is returned as the final element

612

of the list. (Incompatibility note: in the original Python 1.5 release,

613

maxsplit was ignored. This has been fixed in later releases.)

614

<div class="highlight-python"><div class="highlight"><pre>>>> re.split('\W+', 'Words, words, words.')

615

['Words', 'words', 'words', '']

616

>>> re.split('(\W+)', 'Words, words, words.')

617

['Words', ', ', 'words', ', ', 'words', '.', '']

618

>>> re.split('\W+', 'Words, words, words.', 1)

619

['Words', 'words, words.']

620

>>> re.split('[a-f]+', '0a3B9', flags=re.IGNORECASE)

621

['0', '3', '9']

622

</pre></div>

623

</div>

624

If there are capturing groups in the separator and it matches at the start of

625

the string, the result will start with an empty string. The same holds for

626

the end of the string:

627

<div class="highlight-python"><div class="highlight"><pre>>>> re.split('(\W+)', '...words, words...')

628

['', '...', 'words', ', ', 'words', '...', '']

629

</pre></div>

630

</div>

631

That way, separator components are always found at the same relative

632

indices within the result list (e.g., if there’s one capturing group

633

in the separator, the 0th, the 2nd and so forth).

634

Note that split will never split a string on an empty pattern match.

635

For example:

636

<div class="highlight-python"><div class="highlight"><pre>>>> re.split('x*', 'foo')

637

['foo']

638

>>> re.split("(?m)^$", "foo\n\nbar\n")

639

['foo\n\nbar\n']

640

</pre></div>

641

</div>

642

643

Changed in version 2.7: Added the optional flags argument.

644

</div>

645

</dd></dl>

646

647

648

649

<code class="descclassname">re.</code><code class="descname">findall</code>(pattern, string, flags=0)<a class="headerlink" href="#re.findall" title="Permalink to this definition">¶</a></dt>

650

<dd>Return all non-overlapping matches of pattern in string, as a list of

651

strings. The string is scanned left-to-right, and matches are returned in

652

the order found. If one or more groups are present in the pattern, return a

653

list of groups; this will be a list of tuples if the pattern has more than

654

one group. Empty matches are included in the result unless they touch the

655

beginning of another match.

656

657

New in version 1.5.2.

658

</div>

659

660

Changed in version 2.4: Added the optional flags argument.

661

</div>

662

</dd></dl>

663

664

665

666

<code class="descclassname">re.</code><code class="descname">finditer</code>(pattern, string, flags=0)<a class="headerlink" href="#re.finditer" title="Permalink to this definition">¶</a></dt>

667

<dd>Return an <a class="reference internal" href="../glossary.html#term-iterator">iterator</a> yielding <a class="reference internal" href="#re.MatchObject" title="re.MatchObject"><code class="xref py py-class docutils literal">MatchObject</code></a> instances over all

668

non-overlapping matches for the RE pattern in string. The string is

669

scanned left-to-right, and matches are returned in the order found. Empty

670

matches are included in the result unless they touch the beginning of another

671

match.

672

673

New in version 2.2.

674

</div>

675

676

Changed in version 2.4: Added the optional flags argument.

677

</div>

678

</dd></dl>

679

680

681

682

<code class="descclassname">re.</code><code class="descname">sub</code>(pattern, repl, string, count=0, flags=0)<a class="headerlink" href="#re.sub" title="Permalink to this definition">¶</a></dt>

683

<dd>Return the string obtained by replacing the leftmost non-overlapping occurrences

684

of pattern in string by the replacement repl. If the pattern isn’t found,

685

string is returned unchanged. repl can be a string or a function; if it is

686

a string, any backslash escapes in it are processed. That is, <code class="docutils literal">\n</code> is

687

converted to a single newline character, <code class="docutils literal">\r</code> is converted to a carriage return, and

688

so forth. Unknown escapes such as <code class="docutils literal">\j</code> are left alone. Backreferences, such

689

as <code class="docutils literal">\6</code>, are replaced with the substring matched by group 6 in the pattern.

690

For example:

691

<div class="highlight-python"><div class="highlight"><pre>>>> re.sub(r'def\s+([a-zA-Z_][a-zA-Z_0-9]*)\s*$\s*$:',

692

... r'static PyObject*\npy_\1(void)\n{',

693

... 'def myfunc():')

694

'static PyObject*\npy_myfunc(void)\n{'

695

</pre></div>

696

</div>

697

If repl is a function, it is called for every non-overlapping occurrence of

698

pattern. The function takes a single match object argument, and returns the

699

replacement string. For example:

700

<div class="highlight-python"><div class="highlight"><pre>>>> def dashrepl(matchobj):

701

... if matchobj.group(0) == '-': return ' '

702

... else: return '-'

703

>>> re.sub('-{1,2}', dashrepl, 'pro----gram-files')

704

'pro--gram files'

705

>>> re.sub(r'\sAND\s', ' & ', 'Baked Beans And Spam', flags=re.IGNORECASE)

706

'Baked Beans & Spam'

707

</pre></div>

708

</div>

709

The pattern may be a string or an RE object.

710

The optional argument count is the maximum number of pattern occurrences to be

711

replaced; count must be a non-negative integer. If omitted or zero, all

712

occurrences will be replaced. Empty matches for the pattern are replaced only

713

when not adjacent to a previous match, so <code class="docutils literal">sub('x*', '-', 'abc')</code> returns

714

<code class="docutils literal">'-a-b-c-'</code>.

715

In string-type repl arguments, in addition to the character escapes and

716

backreferences described above,

717

<code class="docutils literal">\g<name></code> will use the substring matched by the group named <code class="docutils literal">name</code>, as

718

defined by the <code class="docutils literal">(?P<name>...)</code> syntax. <code class="docutils literal">\g<number></code> uses the corresponding

719

group number; <code class="docutils literal">\g<2></code> is therefore equivalent to <code class="docutils literal">\2</code>, but isn’t ambiguous

720

in a replacement such as <code class="docutils literal">\g<2>0</code>. <code class="docutils literal">\20</code> would be interpreted as a

721

reference to group 20, not a reference to group 2 followed by the literal

722

character <code class="docutils literal">'0'</code>. The backreference <code class="docutils literal">\g<0></code> substitutes in the entire

723

substring matched by the RE.

724

725

Changed in version 2.7: Added the optional flags argument.

726

</div>

727

</dd></dl>

728

729

730

731

<code class="descclassname">re.</code><code class="descname">subn</code>(pattern, repl, string, count=0, flags=0)<a class="headerlink" href="#re.subn" title="Permalink to this definition">¶</a></dt>

732

<dd>Perform the same operation as <a class="reference internal" href="#re.sub" title="re.sub"><code class="xref py py-func docutils literal">sub()</code></a>, but return a tuple <code class="docutils literal">(new_string,

733

number_of_subs_made)</code>.

734

735

Changed in version 2.7: Added the optional flags argument.

736

</div>

737

</dd></dl>

738

739

740

741

<code class="descclassname">re.</code><code class="descname">escape</code>(string)<a class="headerlink" href="#re.escape" title="Permalink to this definition">¶</a></dt>

742

<dd>Return string with all non-alphanumerics backslashed; this is useful if you

743

want to match an arbitrary literal string that may have regular expression

744

metacharacters in it.

745

</dd></dl>

746

747

748

749

<code class="descclassname">re.</code><code class="descname">purge</code>()<a class="headerlink" href="#re.purge" title="Permalink to this definition">¶</a></dt>

750

<dd>Clear the regular expression cache.

751

</dd></dl>

752

753

754

755

exception <code class="descclassname">re.</code><code class="descname">error</code><a class="headerlink" href="#re.error" title="Permalink to this definition">¶</a></dt>

756

<dd>Exception raised when a string passed to one of the functions here is not a

757

valid regular expression (for example, it might contain unmatched parentheses)

758

or when some other error occurs during compilation or matching. It is never an

759

error if a string contains no match for a pattern.

760

</dd></dl>

761

762

</div>

763

764

<h2>7.2.3. Regular Expression Objects<a class="headerlink" href="#regular-expression-objects" title="Permalink to this headline">¶</a></h2>

765

766

767

class <code class="descclassname">re.</code><code class="descname">RegexObject</code><a class="headerlink" href="#re.RegexObject" title="Permalink to this definition">¶</a></dt>

768

<dd>The <a class="reference internal" href="#re.RegexObject" title="re.RegexObject"><code class="xref py py-class docutils literal">RegexObject</code></a> class supports the following methods and attributes:

769

770

771

<code class="descname">search</code>(string[, pos[, endpos]])<a class="headerlink" href="#re.RegexObject.search" title="Permalink to this definition">¶</a></dt>

772

<dd>Scan through string looking for a location where this regular expression

773

produces a match, and return a corresponding <a class="reference internal" href="#re.MatchObject" title="re.MatchObject"><code class="xref py py-class docutils literal">MatchObject</code></a> instance.

774

Return <code class="docutils literal">None</code> if no position in the string matches the pattern; note that this

775

is different from finding a zero-length match at some point in the string.

776

The optional second parameter pos gives an index in the string where the

777

search is to start; it defaults to <code class="docutils literal">0</code>. This is not completely equivalent to

778

slicing the string; the <code class="docutils literal">'^'</code> pattern character matches at the real beginning

779

of the string and at positions just after a newline, but not necessarily at the

780

index where the search is to start.

781

The optional parameter endpos limits how far the string will be searched; it

782

will be as if the string is endpos characters long, so only the characters

783

from pos to <code class="docutils literal">endpos - 1</code> will be searched for a match. If endpos is less

784

than pos, no match will be found, otherwise, if rx is a compiled regular

785

expression object, <code class="docutils literal">rx.search(string, 0, 50)</code> is equivalent to

786

<code class="docutils literal">rx.search(string[:50], 0)</code>.

787

<div class="highlight-python"><div class="highlight"><pre>>>> pattern = re.compile("d")

788

>>> pattern.search("dog") # Match at index 0

789

<_sre.SRE_Match object at ...>

790

>>> pattern.search("dog", 1) # No match; search doesn't include the "d"

791

</pre></div>

792

</div>

793

</dd></dl>

794

795

796

797

<code class="descname">match</code>(string[, pos[, endpos]])<a class="headerlink" href="#re.RegexObject.match" title="Permalink to this definition">¶</a></dt>

798

<dd>If zero or more characters at the beginning of string match this regular

799

expression, return a corresponding <a class="reference internal" href="#re.MatchObject" title="re.MatchObject"><code class="xref py py-class docutils literal">MatchObject</code></a> instance. Return

800

<code class="docutils literal">None</code> if the string does not match the pattern; note that this is different

801

from a zero-length match.

802

The optional pos and endpos parameters have the same meaning as for the

803

<a class="reference internal" href="#re.RegexObject.search" title="re.RegexObject.search"><code class="xref py py-meth docutils literal">search()</code></a> method.

804

805

>>> pattern.match("dog") # No match as "o" is not at the start of "dog".

806

>>> pattern.match("dog", 1) # Match as "o" is the 2nd character of "dog".

807

<_sre.SRE_Match object at ...>

808

</pre></div>

809

</div>

810

If you want to locate a match anywhere in string, use

811

<a class="reference internal" href="#re.RegexObject.search" title="re.RegexObject.search"><code class="xref py py-meth docutils literal">search()</code></a> instead (see also <a class="reference internal" href="#search-vs-match">search() vs. match()</a>).

812

</dd></dl>

813

814

815

816

<code class="descname">split</code>(string, maxsplit=0)<a class="headerlink" href="#re.RegexObject.split" title="Permalink to this definition">¶</a></dt>

817

<dd>Identical to the <a class="reference internal" href="#re.split" title="re.split"><code class="xref py py-func docutils literal">split()</code></a> function, using the compiled pattern.

818

</dd></dl>

819

820

821

822

<code class="descname">findall</code>(string[, pos[, endpos]])<a class="headerlink" href="#re.RegexObject.findall" title="Permalink to this definition">¶</a></dt>

823

<dd>Similar to the <a class="reference internal" href="#re.findall" title="re.findall"><code class="xref py py-func docutils literal">findall()</code></a> function, using the compiled pattern, but

824

also accepts optional pos and endpos parameters that limit the search

825

region like for <a class="reference internal" href="#re.match" title="re.match"><code class="xref py py-meth docutils literal">match()</code></a>.

826

</dd></dl>

827

828

829

830

<code class="descname">finditer</code>(string[, pos[, endpos]])<a class="headerlink" href="#re.RegexObject.finditer" title="Permalink to this definition">¶</a></dt>

831

<dd>Similar to the <a class="reference internal" href="#re.finditer" title="re.finditer"><code class="xref py py-func docutils literal">finditer()</code></a> function, using the compiled pattern, but

832

also accepts optional pos and endpos parameters that limit the search

833

region like for <a class="reference internal" href="#re.match" title="re.match"><code class="xref py py-meth docutils literal">match()</code></a>.

834

</dd></dl>

835

836

837

838

<code class="descname">sub</code>(repl, string, count=0)<a class="headerlink" href="#re.RegexObject.sub" title="Permalink to this definition">¶</a></dt>

839

<dd>Identical to the <a class="reference internal" href="#re.sub" title="re.sub"><code class="xref py py-func docutils literal">sub()</code></a> function, using the compiled pattern.

840

</dd></dl>

841

842

843

844

<code class="descname">subn</code>(repl, string, count=0)<a class="headerlink" href="#re.RegexObject.subn" title="Permalink to this definition">¶</a></dt>

845

<dd>Identical to the <a class="reference internal" href="#re.subn" title="re.subn"><code class="xref py py-func docutils literal">subn()</code></a> function, using the compiled pattern.

846

</dd></dl>

847

848

849

850

<code class="descname">flags</code><a class="headerlink" href="#re.RegexObject.flags" title="Permalink to this definition">¶</a></dt>

851

<dd>The regex matching flags. This is a combination of the flags given to

852

<a class="reference internal" href="#re.compile" title="re.compile"><code class="xref py py-func docutils literal">compile()</code></a> and any <code class="docutils literal">(?...)</code> inline flags in the pattern.

853

</dd></dl>

854

855

856

857

<code class="descname">groups</code><a class="headerlink" href="#re.RegexObject.groups" title="Permalink to this definition">¶</a></dt>

858

<dd>The number of capturing groups in the pattern.

859

</dd></dl>

860

861

862

863

<code class="descname">groupindex</code><a class="headerlink" href="#re.RegexObject.groupindex" title="Permalink to this definition">¶</a></dt>

864

<dd>A dictionary mapping any symbolic group names defined by <code class="docutils literal">(?P<id>)</code> to group

865

numbers. The dictionary is empty if no symbolic groups were used in the

866

pattern.

867

</dd></dl>

868

869

870

871

<code class="descname">pattern</code><a class="headerlink" href="#re.RegexObject.pattern" title="Permalink to this definition">¶</a></dt>

872

<dd>The pattern string from which the RE object was compiled.

873

</dd></dl>

874

875

</dd></dl>

876

877

</div>

878

879

<h2>7.2.4. Match Objects<a class="headerlink" href="#match-objects" title="Permalink to this headline">¶</a></h2>

880

881

882

class <code class="descclassname">re.</code><code class="descname">MatchObject</code><a class="headerlink" href="#re.MatchObject" title="Permalink to this definition">¶</a></dt>

883

<dd>Match objects always have a boolean value of <code class="docutils literal">True</code>.

884

Since <code class="xref py py-meth docutils literal">match()</code> and <code class="xref py py-meth docutils literal">search()</code> return <code class="docutils literal">None</code>

885

when there is no match, you can test whether there was a match with a simple

886

<code class="docutils literal">if</code> statement:

887

<div class="highlight-python"><div class="highlight"><pre>match = re.search(pattern, string)

888

if match:

889

process(match)

890

</pre></div>

891

</div>

892

Match objects support the following methods and attributes:

893

894

895

<code class="descname">expand</code>(template)<a class="headerlink" href="#re.MatchObject.expand" title="Permalink to this definition">¶</a></dt>

896

<dd>Return the string obtained by doing backslash substitution on the template

897

string template, as done by the <a class="reference internal" href="#re.RegexObject.sub" title="re.RegexObject.sub"><code class="xref py py-meth docutils literal">sub()</code></a> method. Escapes

898

such as <code class="docutils literal">\n</code> are converted to the appropriate characters, and numeric

899

backreferences (<code class="docutils literal">\1</code>, <code class="docutils literal">\2</code>) and named backreferences (<code class="docutils literal">\g<1></code>,

900

<code class="docutils literal">\g<name></code>) are replaced by the contents of the corresponding group.

901

</dd></dl>

902

903

904

905

<code class="descname">group</code>([group1, ...])<a class="headerlink" href="#re.MatchObject.group" title="Permalink to this definition">¶</a></dt>

906

<dd>Returns one or more subgroups of the match. If there is a single argument, the

907

result is a single string; if there are multiple arguments, the result is a

908

tuple with one item per argument. Without arguments, group1 defaults to zero

909

(the whole match is returned). If a groupN argument is zero, the corresponding

910

return value is the entire matching string; if it is in the inclusive range

911

[1..99], it is the string matching the corresponding parenthesized group. If a

912

group number is negative or larger than the number of groups defined in the

913

pattern, an <a class="reference internal" href="exceptions.html#exceptions.IndexError" title="exceptions.IndexError"><code class="xref py py-exc docutils literal">IndexError</code></a> exception is raised. If a group is contained in a

914

part of the pattern that did not match, the corresponding result is <code class="docutils literal">None</code>.

915

If a group is contained in a part of the pattern that matched multiple times,

916

the last match is returned.

917

<div class="highlight-python"><div class="highlight"><pre>>>> m = re.match(r"(\w+) (\w+)", "Isaac Newton, physicist")

918

>>> m.group(0) # The entire match

919

'Isaac Newton'

920

>>> m.group(1) # The first parenthesized subgroup.

921

'Isaac'

922

>>> m.group(2) # The second parenthesized subgroup.

923

'Newton'

924

>>> m.group(1, 2) # Multiple arguments give us a tuple.

925

('Isaac', 'Newton')

926

</pre></div>

927

</div>

928

If the regular expression uses the <code class="docutils literal">(?P<name>...)</code> syntax, the groupN

929

arguments may also be strings identifying groups by their group name. If a

930

string argument is not used as a group name in the pattern, an <a class="reference internal" href="exceptions.html#exceptions.IndexError" title="exceptions.IndexError"><code class="xref py py-exc docutils literal">IndexError</code></a>

931

exception is raised.

932

A moderately complicated example:

933

<div class="highlight-python"><div class="highlight"><pre>>>> m = re.match(r"(?P<first_name>\w+) (?P<last_name>\w+)", "Malcolm Reynolds")

934

>>> m.group('first_name')

935

'Malcolm'

936

>>> m.group('last_name')

937

'Reynolds'

938

</pre></div>

939

</div>

940

Named groups can also be referred to by their index:

941

<div class="highlight-python"><div class="highlight"><pre>>>> m.group(1)

942

'Malcolm'

943

>>> m.group(2)

944

'Reynolds'

945

</pre></div>

946

</div>

947

If a group matches multiple times, only the last match is accessible:

948

<div class="highlight-python"><div class="highlight"><pre>>>> m = re.match(r"(..)+", "a1b2c3") # Matches 3 times.

949

950

'c3'

951

</pre></div>

952

</div>

953

</dd></dl>

954

955

956

957

<code class="descname">groups</code>([default])<a class="headerlink" href="#re.MatchObject.groups" title="Permalink to this definition">¶</a></dt>

958

<dd>Return a tuple containing all the subgroups of the match, from 1 up to however

959

many groups are in the pattern. The default argument is used for groups that

960

did not participate in the match; it defaults to <code class="docutils literal">None</code>. (Incompatibility

961

note: in the original Python 1.5 release, if the tuple was one element long, a

962

string would be returned instead. In later versions (from 1.5.1 on), a

963

singleton tuple is returned in such cases.)

964

For example:

965

<div class="highlight-python"><div class="highlight"><pre>>>> m = re.match(r"(\d+)\.(\d+)", "24.1632")

966

>>> m.groups()

967

('24', '1632')

968

</pre></div>

969

</div>

970

If we make the decimal place and everything after it optional, not all groups

971

might participate in the match. These groups will default to <code class="docutils literal">None</code> unless

972

the default argument is given:

973

<div class="highlight-python"><div class="highlight"><pre>>>> m = re.match(r"(\d+)\.?(\d+)?", "24")

974

>>> m.groups() # Second group defaults to None.

975

('24', None)

976

>>> m.groups('0') # Now, the second group defaults to '0'.

977

('24', '0')

978

</pre></div>

979

</div>

980

</dd></dl>

981

982

983

984

<code class="descname">groupdict</code>([default])<a class="headerlink" href="#re.MatchObject.groupdict" title="Permalink to this definition">¶</a></dt>

985

<dd>Return a dictionary containing all the named subgroups of the match, keyed by

986

the subgroup name. The default argument is used for groups that did not

987

participate in the match; it defaults to <code class="docutils literal">None</code>. For example:

988

<div class="highlight-python"><div class="highlight"><pre>>>> m = re.match(r"(?P<first_name>\w+) (?P<last_name>\w+)", "Malcolm Reynolds")

989

>>> m.groupdict()

990

{'first_name': 'Malcolm', 'last_name': 'Reynolds'}

991

</pre></div>

992

</div>

993

</dd></dl>

994

995

996

997

<code class="descname">start</code>([group])<a class="headerlink" href="#re.MatchObject.start" title="Permalink to this definition">¶</a></dt>

998

999

<code class="descname">end</code>([group])<a class="headerlink" href="#re.MatchObject.end" title="Permalink to this definition">¶</a></dt>

1000

<dd>Return the indices of the start and end of the substring matched by group;

1001

group defaults to zero (meaning the whole matched substring). Return <code class="docutils literal">-1</code> if

1002

group exists but did not contribute to the match. For a match object m, and

1003

a group g that did contribute to the match, the substring matched by group g

1004

(equivalent to <code class="docutils literal">m.group(g)</code>) is

1005

<div class="highlight-python"><div class="highlight"><pre>m.string[m.start(g):m.end(g)]

1006

</pre></div>

1007

</div>

1008

Note that <code class="docutils literal">m.start(group)</code> will equal <code class="docutils literal">m.end(group)</code> if group matched a

1009

null string. For example, after <code class="docutils literal">m = re.search('b(c?)', 'cba')</code>,

1010

<code class="docutils literal">m.start(0)</code> is 1, <code class="docutils literal">m.end(0)</code> is 2, <code class="docutils literal">m.start(1)</code> and <code class="docutils literal">m.end(1)</code> are both

1011

2, and <code class="docutils literal">m.start(2)</code> raises an <a class="reference internal" href="exceptions.html#exceptions.IndexError" title="exceptions.IndexError"><code class="xref py py-exc docutils literal">IndexError</code></a> exception.

1012

An example that will remove remove_this from email addresses:

1013

<div class="highlight-python"><div class="highlight"><pre>>>> email = "tony@tiremove_thisger.net"

1014

>>> m = re.search("remove_this", email)

1015

>>> email[:m.start()] + email[m.end():]

1016

'tony@tiger.net'

1017

</pre></div>

1018

</div>

1019

</dd></dl>

1020

1021

1022

1023

<code class="descname">span</code>([group])<a class="headerlink" href="#re.MatchObject.span" title="Permalink to this definition">¶</a></dt>

1024

<dd>For <a class="reference internal" href="#re.MatchObject" title="re.MatchObject"><code class="xref py py-class docutils literal">MatchObject</code></a> m, return the 2-tuple <code class="docutils literal">(m.start(group),

1025

m.end(group))</code>. Note that if group did not contribute to the match, this is

1026

<code class="docutils literal">(-1, -1)</code>. group defaults to zero, the entire match.

1027

</dd></dl>

1028

1029

1030

1031

1032

<dd>The value of pos which was passed to the <a class="reference internal" href="#re.RegexObject.search" title="re.RegexObject.search"><code class="xref py py-meth docutils literal">search()</code></a> or

1033

<a class="reference internal" href="#re.RegexObject.match" title="re.RegexObject.match"><code class="xref py py-meth docutils literal">match()</code></a> method of the <a class="reference internal" href="#re.RegexObject" title="re.RegexObject"><code class="xref py py-class docutils literal">RegexObject</code></a>. This is the

1034

index into the string at which the RE engine started looking for a match.

1035

</dd></dl>

1036

1037

1038

1039

<code class="descname">endpos</code><a class="headerlink" href="#re.MatchObject.endpos" title="Permalink to this definition">¶</a></dt>

1040

<dd>The value of endpos which was passed to the <a class="reference internal" href="#re.RegexObject.search" title="re.RegexObject.search"><code class="xref py py-meth docutils literal">search()</code></a> or

1041

1042

index into the string beyond which the RE engine will not go.

1043

</dd></dl>

1044

1045

1046

1047

<code class="descname">lastindex</code><a class="headerlink" href="#re.MatchObject.lastindex" title="Permalink to this definition">¶</a></dt>

1048

<dd>The integer index of the last matched capturing group, or <code class="docutils literal">None</code> if no group

1049

was matched at all. For example, the expressions <code class="docutils literal">(a)b</code>, <code class="docutils literal">((a)(b))</code>, and

1050

<code class="docutils literal">((ab))</code> will have <code class="docutils literal">lastindex == 1</code> if applied to the string <code class="docutils literal">'ab'</code>, while

1051

the expression <code class="docutils literal">(a)(b)</code> will have <code class="docutils literal">lastindex == 2</code>, if applied to the same

1052

string.

1053

</dd></dl>

1054

1055

1056

1057

<code class="descname">lastgroup</code><a class="headerlink" href="#re.MatchObject.lastgroup" title="Permalink to this definition">¶</a></dt>

1058

<dd>The name of the last matched capturing group, or <code class="docutils literal">None</code> if the group didn’t

1059

have a name, or if no group was matched at all.

1060

</dd></dl>

1061

1062

1063

1064

1065

<dd>The regular expression object whose <a class="reference internal" href="#re.RegexObject.match" title="re.RegexObject.match"><code class="xref py py-meth docutils literal">match()</code></a> or

1066

<a class="reference internal" href="#re.RegexObject.search" title="re.RegexObject.search"><code class="xref py py-meth docutils literal">search()</code></a> method produced this <a class="reference internal" href="#re.MatchObject" title="re.MatchObject"><code class="xref py py-class docutils literal">MatchObject</code></a>

1067

instance.

1068

</dd></dl>

1069

1070

1071

1072

<code class="descname">string</code><a class="headerlink" href="#re.MatchObject.string" title="Permalink to this definition">¶</a></dt>

1073

<dd>The string passed to <a class="reference internal" href="#re.RegexObject.match" title="re.RegexObject.match"><code class="xref py py-meth docutils literal">match()</code></a> or

1074

<a class="reference internal" href="#re.RegexObject.search" title="re.RegexObject.search"><code class="xref py py-meth docutils literal">search()</code></a>.

1075

</dd></dl>

1076

1077

</dd></dl>

1078

1079

</div>

1080

1081

<h2>7.2.5. Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>

1082

1083

<h3>7.2.5.1. Checking For a Pair<a class="headerlink" href="#checking-for-a-pair" title="Permalink to this headline">¶</a></h3>

1084

In this example, we’ll use the following helper function to display match

1085

objects a little more gracefully:

1086

<div class="highlight-python"><div class="highlight"><pre>def displaymatch(match):

1087

if match is None:

1088

return None

1089

return '<Match: %r, groups=%r>' % (match.group(), match.groups())

1090

</pre></div>

1091

</div>

1092

Suppose you are writing a poker program where a player’s hand is represented as

1093

a 5-character string with each character representing a card, “a” for ace, “k”

1094

for king, “q” for queen, “j” for jack, “t” for 10, and “2” through “9”

1095

representing the card with that value.

1096

To see if a given string is a valid hand, one could do the following:

1097

<div class="highlight-python"><div class="highlight"><pre>>>> valid = re.compile(r"^[a2-9tjqk]{5}$")

1098

>>> displaymatch(valid.match("akt5q")) # Valid.

1099

"<Match: 'akt5q', groups=()>"

1100

>>> displaymatch(valid.match("akt5e")) # Invalid.

1101

>>> displaymatch(valid.match("akt")) # Invalid.

1102

>>> displaymatch(valid.match("727ak")) # Valid.

1103

"<Match: '727ak', groups=()>"

1104

</pre></div>

1105

</div>

1106

That last hand, <code class="docutils literal">"727ak"</code>, contained a pair, or two of the same valued cards.

1107

To match this with a regular expression, one could use backreferences as such:

1108

<div class="highlight-python"><div class="highlight"><pre>>>> pair = re.compile(r".*(.).*\1")

1109

>>> displaymatch(pair.match("717ak")) # Pair of 7s.

1110

"<Match: '717', groups=('7',)>"

1111

>>> displaymatch(pair.match("718ak")) # No pairs.

1112

>>> displaymatch(pair.match("354aa")) # Pair of aces.

1113

"<Match: '354aa', groups=('a',)>"

1114

</pre></div>

1115

</div>

1116

To find out what card the pair consists of, one could use the

1117

<a class="reference internal" href="#re.MatchObject.group" title="re.MatchObject.group"><code class="xref py py-meth docutils literal">group()</code></a> method of <a class="reference internal" href="#re.MatchObject" title="re.MatchObject"><code class="xref py py-class docutils literal">MatchObject</code></a> in the following

1118

manner:

1119

<div class="highlight-python"><div class="highlight"><pre>>>> pair.match("717ak").group(1)

1120

'7'

1121

1122

# Error because re.match() returns None, which doesn't have a group() method:

1123

>>> pair.match("718ak").group(1)

1124

Traceback (most recent call last):

1125

File "<pyshell#23>", line 1, in <module>

1126

re.match(r".*(.).*\1", "718ak").group(1)

1127

AttributeError: 'NoneType' object has no attribute 'group'

1128

1129

>>> pair.match("354aa").group(1)

1130

'a'

1131

</pre></div>

1132

</div>

1133

</div>

1134

1135

<h3>7.2.5.2. Simulating scanf()<a class="headerlink" href="#simulating-scanf" title="Permalink to this headline">¶</a></h3>

1136

Python does not currently have an equivalent to <code class="xref c c-func docutils literal">scanf()</code>. Regular

1137

expressions are generally more powerful, though also more verbose, than

1138

<code class="xref c c-func docutils literal">scanf()</code> format strings. The table below offers some more-or-less

1139

equivalent mappings between <code class="xref c c-func docutils literal">scanf()</code> format tokens and regular

1140

expressions.

1141

1142

1143

1144

1145

</colgroup>

1146

1147

<tr class="row-odd"><th class="head"><code class="xref c c-func docutils literal">scanf()</code> Token</th>

1148

<th class="head">Regular Expression</th>

1149

</tr>

1150

</thead>

1151

1152

1153

1154

</tr>

1155

1156

1157

</tr>

1158

1159

1160

</tr>

1161

1162

1163

</tr>

1164

1165

1166

</tr>

1167

1168

1169

</tr>

1170

1171

1172

</tr>

1173

1174

1175

</tr>

1176

1177

1178

</tr>

1179

</tbody>

1180

</table>

1181

To extract the filename and numbers from a string like

1182

<div class="highlight-python"><div class="highlight"><pre>/usr/sbin/sendmail - 0 errors, 4 warnings

1183

</pre></div>

1184

</div>

1185

you would use a <code class="xref c c-func docutils literal">scanf()</code> format like

1186

<div class="highlight-python"><div class="highlight"><pre>%s - %d errors, %d warnings

1187

</pre></div>

1188

</div>

1189

The equivalent regular expression would be

1190

<div class="highlight-python"><div class="highlight"><pre>(\S+) - (\d+) errors, (\d+) warnings

1191

</pre></div>

1192

</div>

1193

</div>

1194

1195

<h3>7.2.5.3. search() vs. match()<a class="headerlink" href="#search-vs-match" title="Permalink to this headline">¶</a></h3>

1196

Python offers two different primitive operations based on regular expressions:

1197

<a class="reference internal" href="#re.match" title="re.match"><code class="xref py py-func docutils literal">re.match()</code></a> checks for a match only at the beginning of the string, while

1198

<a class="reference internal" href="#re.search" title="re.search"><code class="xref py py-func docutils literal">re.search()</code></a> checks for a match anywhere in the string (this is what Perl

1199

does by default).

1200

For example:

1201

1202

>>> re.search("c", "abcdef") # Match

1203

<_sre.SRE_Match object at ...>

1204

</pre></div>

1205

</div>

1206

Regular expressions beginning with <code class="docutils literal">'^'</code> can be used with <a class="reference internal" href="#re.search" title="re.search"><code class="xref py py-func docutils literal">search()</code></a> to

1207

restrict the match at the beginning of the string:

1208

1209

>>> re.search("^c", "abcdef") # No match

1210

>>> re.search("^a", "abcdef") # Match

1211

<_sre.SRE_Match object at ...>

1212

</pre></div>

1213

</div>

1214

Note however that in <a class="reference internal" href="#re.MULTILINE" title="re.MULTILINE"><code class="xref py py-const docutils literal">MULTILINE</code></a> mode <a class="reference internal" href="#re.match" title="re.match"><code class="xref py py-func docutils literal">match()</code></a> only matches at the

1215

beginning of the string, whereas using <a class="reference internal" href="#re.search" title="re.search"><code class="xref py py-func docutils literal">search()</code></a> with a regular expression

1216

beginning with <code class="docutils literal">'^'</code> will match at the beginning of each line.

1217

<div class="highlight-python"><div class="highlight"><pre>>>> re.match('X', 'A\nB\nX', re.MULTILINE) # No match

1218

>>> re.search('^X', 'A\nB\nX', re.MULTILINE) # Match

1219

<_sre.SRE_Match object at ...>

1220

</pre></div>

1221

</div>

1222

</div>

1223

1224

<h3>7.2.5.4. Making a Phonebook<a class="headerlink" href="#making-a-phonebook" title="Permalink to this headline">¶</a></h3>

1225

<a class="reference internal" href="#re.split" title="re.split"><code class="xref py py-func docutils literal">split()</code></a> splits a string into a list delimited by the passed pattern. The

1226

method is invaluable for converting textual data into data structures that can be

1227

easily read and modified by Python as demonstrated in the following example that

1228

creates a phonebook.

1229

First, here is the input. Normally it may come from a file, here we are using

1230

triple-quoted string syntax:

1231

<div class="highlight-python"><div class="highlight"><pre>>>> text = """Ross McFluff: 834.345.1254 155 Elm Street

1232

...

1233

... Ronald Heathmore: 892.345.3428 436 Finley Avenue

1234

... Frank Burger: 925.541.7625 662 South Dogwood Way

1235

...

1236

...

1237

... Heather Albrecht: 548.326.4584 919 Park Place"""

1238

</pre></div>

1239

</div>

1240

The entries are separated by one or more newlines. Now we convert the string

1241

into a list with each nonempty line having its own entry:

1242

<div class="highlight-python"><div class="highlight"><pre>>>> entries = re.split("\n+", text)

1243

>>> entries

1244

['Ross McFluff: 834.345.1254 155 Elm Street',

1245

'Ronald Heathmore: 892.345.3428 436 Finley Avenue',

1246

'Frank Burger: 925.541.7625 662 South Dogwood Way',

1247

'Heather Albrecht: 548.326.4584 919 Park Place']

1248

</pre></div>

1249

</div>

1250

Finally, split each entry into a list with first name, last name, telephone

1251

number, and address. We use the <code class="docutils literal">maxsplit</code> parameter of <a class="reference internal" href="#re.split" title="re.split"><code class="xref py py-func docutils literal">split()</code></a>

1252

because the address has spaces, our splitting pattern, in it:

1253

<div class="highlight-python"><div class="highlight"><pre>>>> [re.split(":? ", entry, 3) for entry in entries]

1254

[['Ross', 'McFluff', '834.345.1254', '155 Elm Street'],

1255

['Ronald', 'Heathmore', '892.345.3428', '436 Finley Avenue'],

1256

['Frank', 'Burger', '925.541.7625', '662 South Dogwood Way'],

1257

['Heather', 'Albrecht', '548.326.4584', '919 Park Place']]

1258

</pre></div>

1259

</div>

1260

The <code class="docutils literal">:?</code> pattern matches the colon after the last name, so that it does not

1261

occur in the result list. With a <code class="docutils literal">maxsplit</code> of <code class="docutils literal">4</code>, we could separate the

1262

house number from the street name:

1263

<div class="highlight-python"><div class="highlight"><pre>>>> [re.split(":? ", entry, 4) for entry in entries]

1264

[['Ross', 'McFluff', '834.345.1254', '155', 'Elm Street'],

1265

['Ronald', 'Heathmore', '892.345.3428', '436', 'Finley Avenue'],

1266

['Frank', 'Burger', '925.541.7625', '662', 'South Dogwood Way'],

1267

['Heather', 'Albrecht', '548.326.4584', '919', 'Park Place']]

1268

</pre></div>

1269

</div>

1270

</div>

1271

1272

<h3>7.2.5.5. Text Munging<a class="headerlink" href="#text-munging" title="Permalink to this headline">¶</a></h3>

1273

<a class="reference internal" href="#re.sub" title="re.sub"><code class="xref py py-func docutils literal">sub()</code></a> replaces every occurrence of a pattern with a string or the

1274

result of a function. This example demonstrates using <a class="reference internal" href="#re.sub" title="re.sub"><code class="xref py py-func docutils literal">sub()</code></a> with

1275

a function to “munge” text, or randomize the order of all the characters

1276

in each word of a sentence except for the first and last characters:

1277

<div class="highlight-python"><div class="highlight"><pre>>>> def repl(m):

1278

... inner_word = list(m.group(2))

1279

... random.shuffle(inner_word)

1280

... return m.group(1) + "".join(inner_word) + m.group(3)

1281

>>> text = "Professor Abdolmalek, please report your absences promptly."

1282

>>> re.sub(r"(\w)(\w+)(\w)", repl, text)

1283

'Poefsrosr Aealmlobdk, pslaee reorpt your abnseces plmrptoy.'

1284

1285

'Pofsroser Aodlambelk, plasee reoprt yuor asnebces potlmrpy.'

1286

</pre></div>

1287

</div>

1288

</div>

1289

1290

<h3>7.2.5.6. Finding all Adverbs<a class="headerlink" href="#finding-all-adverbs" title="Permalink to this headline">¶</a></h3>

1291

<a class="reference internal" href="#re.findall" title="re.findall"><code class="xref py py-func docutils literal">findall()</code></a> matches all occurrences of a pattern, not just the first

1292

one as <a class="reference internal" href="#re.search" title="re.search"><code class="xref py py-func docutils literal">search()</code></a> does. For example, if one was a writer and wanted to

1293

find all of the adverbs in some text, he or she might use <a class="reference internal" href="#re.findall" title="re.findall"><code class="xref py py-func docutils literal">findall()</code></a> in

1294

the following manner:

1295

<div class="highlight-python"><div class="highlight"><pre>>>> text = "He was carefully disguised but captured quickly by police."

1296

>>> re.findall(r"\w+ly", text)

1297

['carefully', 'quickly']

1298

</pre></div>

1299

</div>

1300

</div>

1301

1302

<h3>7.2.5.7. Finding all Adverbs and their Positions<a class="headerlink" href="#finding-all-adverbs-and-their-positions" title="Permalink to this headline">¶</a></h3>

1303

If one wants more information about all matches of a pattern than the matched

1304

text, <a class="reference internal" href="#re.finditer" title="re.finditer"><code class="xref py py-func docutils literal">finditer()</code></a> is useful as it provides instances of

1305

<a class="reference internal" href="#re.MatchObject" title="re.MatchObject"><code class="xref py py-class docutils literal">MatchObject</code></a> instead of strings. Continuing with the previous example,

1306

if one was a writer who wanted to find all of the adverbs and their positions

1307

in some text, he or she would use <a class="reference internal" href="#re.finditer" title="re.finditer"><code class="xref py py-func docutils literal">finditer()</code></a> in the following manner:

1308

1309

>>> for m in re.finditer(r"\w+ly", text):

1310

... print '%02d-%02d: %s' % (m.start(), m.end(), m.group(0))

1311

07-16: carefully

1312

40-47: quickly

1313

</pre></div>

1314

</div>

1315

</div>

1316

1317

<h3>7.2.5.8. Raw String Notation<a class="headerlink" href="#raw-string-notation" title="Permalink to this headline">¶</a></h3>

1318

Raw string notation (<code class="docutils literal">r"text"</code>) keeps regular expressions sane. Without it,

1319

every backslash (<code class="docutils literal">'\'</code>) in a regular expression would have to be prefixed with

1320

another one to escape it. For example, the two following lines of code are

1321

functionally identical:

1322

1323

<_sre.SRE_Match object at ...>

1324

>>> re.match("\\W(.)\\1\\W", " ff ")

1325

<_sre.SRE_Match object at ...>

1326

</pre></div>

1327

</div>

1328

When one wants to match a literal backslash, it must be escaped in the regular

1329

expression. With raw string notation, this means <code class="docutils literal">r"\\"</code>. Without raw string

1330

notation, one must use <code class="docutils literal">"\\\\"</code>, making the following lines of code

1331

functionally identical:

1332

<div class="highlight-python"><div class="highlight"><pre>>>> re.match(r"\\", r"\\")

1333

<_sre.SRE_Match object at ...>

1334

>>> re.match("\\\\", r"\\")

1335

<_sre.SRE_Match object at ...>

1336

</pre></div>

1337

</div>

1338

</div>

1339

</div>

1340

</div>

1341

1342

1343

</div>

1344

</div>

1345

</div>

1346

1347

1348

<h3><a href="../contents.html">Table Of Contents</a></h3>

1349

<ul>

1350

<li><a class="reference internal" href="#">7.2. <code class="docutils literal">re</code> — Regular expression operations</a><ul>

1351

<li><a class="reference internal" href="#regular-expression-syntax">7.2.1. Regular Expression Syntax</a></li>

1352

<li><a class="reference internal" href="#module-contents">7.2.2. Module Contents</a></li>

1353

<li><a class="reference internal" href="#regular-expression-objects">7.2.3. Regular Expression Objects</a></li>

1354

<li><a class="reference internal" href="#match-objects">7.2.4. Match Objects</a></li>

1355

<li><a class="reference internal" href="#examples">7.2.5. Examples</a><ul>

1356

<li><a class="reference internal" href="#checking-for-a-pair">7.2.5.1. Checking For a Pair</a></li>

1357

<li><a class="reference internal" href="#simulating-scanf">7.2.5.2. Simulating scanf()</a></li>

1358

<li><a class="reference internal" href="#search-vs-match">7.2.5.3. search() vs. match()</a></li>

1359

<li><a class="reference internal" href="#making-a-phonebook">7.2.5.4. Making a Phonebook</a></li>

1360

<li><a class="reference internal" href="#text-munging">7.2.5.5. Text Munging</a></li>

1361

<li><a class="reference internal" href="#finding-all-adverbs">7.2.5.6. Finding all Adverbs</a></li>

1362

<li><a class="reference internal" href="#finding-all-adverbs-and-their-positions">7.2.5.7. Finding all Adverbs and their Positions</a></li>

1363

<li><a class="reference internal" href="#raw-string-notation">7.2.5.8. Raw String Notation</a></li>

1364

</ul>

1365

</li>

1366

</ul>

1367

</li>

1368

</ul>

1369

1370

<h4>Previous topic</h4>

1371

<a href="string.html"

1372

title="previous chapter">7.1. <code class="docutils literal">string</code> — Common string operations</a>

1373

<h4>Next topic</h4>

1374

<a href="struct.html"

1375

title="next chapter">7.3. <code class="docutils literal">struct</code> — Interpret strings as packed binary data</a>

1376

1377

1378

<li><a href="../bugs.html">Report a Bug</a></li>

1379

<li><a href="../_sources/library/re.txt"

1380

rel="nofollow">Show Source</a></li>

1381

</ul>

1382

1383

1384

<h3>Quick search</h3>

1385

1386

1387

1388

1389

1390

</form>

1391

1392

Enter search terms or a module, class or function name.

1393

1394

</div>

1395

1396

</div>

1397

</div>

1398

1399

</div>

1400

1401

<h3>Navigation</h3>

1402

<ul>

1403

1404

<a href="../genindex.html" title="General Index"

1405

>index</a></li>

1406

1407

<a href="../py-modindex.html" title="Python Module Index"

1408

>modules</a> |</li>

1409

1410

<a href="struct.html" title="7.3. struct — Interpret strings as packed binary data"

1411

>next</a> |</li>

1412

1413

<a href="string.html" title="7.1. string — Common string operations"

1414

>previous</a> |</li>

1415

<li><img src="../_static/py.png" alt=""

1416

style="vertical-align: middle; margin-top: -1px"/></li>

1417

<li><a href="https://www.python.org/">Python</a> »</li>

1418

<li>

1419

2.7.11

1420

<a href="../index.html">Documentation</a> »

1421

</li>

1422

1423

<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>

1424

<li class="nav-item nav-item-2"><a href="strings.html" >7. String Services</a> »</li>

1425

</ul>

1426

</div>

1427

1428

1429

1430

The Python Software Foundation is a non-profit corporation.

1431

<a href="https://www.python.org/psf/donations/">Please donate.</a>

1432

1433

Last updated on Jan 23, 2016.

1434

<a href="../bugs.html">Found a bug</a>?

1435

1436

Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.3.3.

1437

</div>

1438

1439

</body>

1440

</html>

b'\\ No newline at end of file'

Older »