Python - Regex findall and finditer

Python's re module provides two very important functions for finding all occurrences of a Regular Expression pattern:

findall()
finditer()
        

Both functions search the complete target string from left to right.

However, there is an important difference:

findall()
   │
   └── Returns matched values

finditer()
   │
   └── Returns Match Objects
        

Simple Definition:

findall() returns all matched values, whereas finditer() provides Match Objects for all matches.

The findall() function is used to find all occurrences of the specified Regular Expression in the target string.

Syntax:

re.findall(pattern, string)
        

It searches the complete target string and normally returns the matched values in a list.

Example:

re.findall("[0-9]", "a7b9c5")
        

The matching characters are:

7
9
5
        

Therefore, the result is:

['7', '9', '5']
        

Return Value of findall()

For the simple patterns used in this tutorial, findall() returns a list containing all matched strings.

Condition	Result
Matches are available	List containing matched values
No match is available	Empty list []

Another example:

re.findall("\\d", "a1b2c3")
        

returns:

['1', '2', '3']
        

The following program uses findall() to find every digit in the target string a7b9c5kz:

['7', '9', '5']

Step 1: Import the re module.

import re
        

Step 2: Call findall().

l = re.findall("[0-9]", "a7b9c5kz")
        

The Regular Expression is:

[0-9]
        

It means:

Find any digit from 0 to 9.

The target string is:

a7b9c5kz
        

Python checks the complete target:

Character : a 7 b 9 c 5 k z
Index     : 0 1 2 3 4 5 6 7
              ↑   ↑   ↑
            Match Match Match
        

The matching values are:

7
9
5
        

Therefore:

l = ['7', '9', '5']
        

findall() first creates the result containing all matched values:

['7', '9', '5']
        

The for loop then processes one value at a time:

First iteration  → 7
Second iteration → 9
Third iteration  → 5
        

Hence the values are printed on separate lines.

7
9
5

The target:

abcdefgh
        

does not contain any digit.

Therefore:

[0-9]
        

cannot find any occurrence.

findall() does not return None in this case.

It returns an empty list:

[]
        

[]

The execution of a findall() program can be followed through this flow:

Program Starts
      │
      ▼
import re
      │
      ▼
Define Pattern
[0-9]
      │
      ▼
Target String
"a7b9c5kz"
      │
      ▼
re.findall()
      │
      ▼
Search Complete
Target String
      │
      ▼
Check Character
from Left to Right
      │
   ┌──┴───────┐
   │          │
 Match      No Match
   │          │
   ▼          ▼
Add Value    Continue
to Result    Searching
   │
   └────┬─────┘
        ▼
Search Until
End of String
        │
        ▼
Return List
['7','9','5']
        │
        ▼
Print Result
        │
        ▼
       End
        

When to Use findall()

• findall() is convenient when only matched values are required.
• For simple patterns, findall() returns all matched strings directly in a list.

The finditer() function is also used to find all occurrences of a Regular Expression in the target string.

But instead of directly giving only the matched values, it provides Match Objects.

Syntax:

re.finditer(pattern, string)
        

Simple Definition:

finditer() returns an iterator that provides a Match Object for every successful match.

From each Match Object, we can obtain:

start()
end()
group()
        

What Does finditer() Return?

Consider:

matcher = re.finditer("[0-9]", "a7b9c5kz")
        

Conceptually, Python finds:

7 → Match Object
9 → Match Object
5 → Match Object
        

Each Match Object contains information about that particular occurrence.

Match Object
    │
    ├── start() → Starting index
    │
    ├── end()   → Ending position
    │
    └── group() → Matched text
        

The following program uses finditer() on the same target string and prints the starting position and matched value of every digit:

1 ... 7
3 ... 9
5 ... 5

Step 1:

import re
        

imports the Regular Expression module.

Step 2:

matcher = re.finditer("[0-9]", "a7b9c5kz")
        

searches for all digits.

The target is:

Character : a 7 b 9 c 5 k z
Index     : 0 1 2 3 4 5 6 7
        

Matches occur at:

Index 1 → 7
Index 3 → 9
Index 5 → 5
        

Step 3:

for match in matcher:
        

retrieves each Match Object one by one.

Step 4:

match.start()
        

returns the starting position.

Step 5:

match.group()
        

returns the actual matched value.

Hence:

1 ... 7
3 ... 9
5 ... 5
        

The program below prints the starting position, the ending position, and the matched value for every digit in the target string:

Understanding the Match Objects

For the first match:

a 7 b 9 c 5 k z
0 1 2 3 4 5 6 7
  ↑
        

The matched value is 7.

start() → 1
end()   → 2
group() → 7
        

For the second match:

start() → 3
end()   → 4
group() → 9
        

For the third match:

start() → 5
end()   → 6
group() → 5
        

Remember that end() gives the position immediately after the matched substring.

The Match Object

A Match Object stores information about a successful Regular Expression match.

Important methods include:

Method	Purpose
start()	Returns starting index of the match
end()	Returns the position immediately after the match
group()	Returns the matched text

Example:

Target = "a7b9c5kz"

Match = 9
        

For this Match Object:

start() = 3
end()   = 4
group() = "9"
        

Start: 1
End: 2
Group: 7

Start: 3
End: 4
Group: 9

Start: 5
End: 6
Group: 5

The pattern a+ means one or more consecutive a characters.

The target is:

a b a a b a a a b
0 1 2 3 4 5 6 7 8
        

Therefore the Match Objects represent:

Match	start()	end()	group()
1	0	1	a
2	2	4	aa
3	5	8	aaa

This makes finditer() very useful when we need both the matched value and its location.

Start: 0 End: 1 Group: a
Start: 2 End: 4 Group: aa
Start: 5 End: 8 Group: aaa

The execution of a finditer() program can be followed through this flow:

Program Starts
      │
      ▼
import re
      │
      ▼
Pattern = [0-9]
      │
      ▼
Target =
"a7b9c5kz"
      │
      ▼
re.finditer()
      │
      ▼
Search from
Left to Right
      │
      ▼
Pattern Found?
      │
   ┌──┴─────────┐
   │            │
  Yes           No
   │            │
   ▼            ▼
Create         Continue
Match Object   Search
   │
   ▼
Provide Match
Object through
Iterator
   │
   ▼
for Loop Gets
Match Object
   │
   ▼
start()
end()
group()
   │
   ▼
Print Information
   │
   ▼
Continue Until
End of String
   │
   ▼
Program Ends
        

When to Use finditer()

• finditer() is useful when both matched values and their positions are required.
• finditer() is especially useful when the position of every match is important.

Both functions find all matches, but the form of the result is different.

                Regular Expression
                        │
                        ▼
                   Target String
                        │
              ┌─────────┴─────────┐
              │                   │
              ▼                   ▼
          findall()           finditer()
              │                   │
              ▼                   ▼
        Matched Values        Match Objects
              │                   │
              ▼                   ▼
       ['7','9','5']       start(), end(),
                              group()
        

Complete Comparison Table

Feature	findall()	finditer()
Finds all occurrences	Yes	Yes
Searches complete target	Yes	Yes
Simple result	Matched values	Match Objects through an iterator
Can directly get start index from each result	No	Yes
Can directly get end index from each result	No	Yes
Can use group() on each result	No	Yes
No matches	Empty list	Iterator produces no Match Objects
Best when	Only matched values are needed	Detailed information about each match is needed

The same Regular Expression is used:

[0-9]
        

and the same target:

a7b9c5kz
        

findall() directly provides:

['7', '9', '5']
        

It is convenient when we mainly need the matched values.

finditer() provides Match Objects.

Therefore we can obtain:

Match 1:
start = 1
end   = 2
group = 7

Match 2:
start = 3
end   = 4
group = 9

Match 3:
start = 5
end   = 6
group = 5
        

Using findall():
['7', '9', '5']

Using finditer():
1 2 7
3 4 9
5 6 5

Function	Number of Matches	Main Result
search()	First occurrence only	One Match Object or None
findall()	All occurrences	List of matched results for simple patterns
finditer()	All occurrences	Iterator of Match Objects

Easy memory rule:

search()
    ↓
First Match


findall()
    ↓
All Matched Values


finditer()
    ↓
All Match Objects
        

For simple patterns such as:

[0-9]
\d
a+
        

findall() returns a list of matched strings.

However, if the Regular Expression contains capturing groups, the exact shape of the findall() result can change.

Capturing groups are an advanced Regular Expression concept.

For the current examples, remember:

findall()
    ↓
List of matched values
        

Complete Execution Flow

                   Start
                     │
                     ▼
                  import re
                     │
                     ▼
               Define Pattern
                     │
                     ▼
                Target String
                     │
          ┌──────────┴──────────┐
          │                     │
          ▼                     ▼
      findall()             finditer()
          │                     │
          ▼                     ▼
   Search All Matches     Search All Matches
          │                     │
          ▼                     ▼
   Collect Matched        Create Match Object
       Results             for Each Match
          │                     │
          ▼                     ▼
    Return Result         Return Iterator
       List                    │
          │                     ▼
          │                for Loop
          │                     │
          │                     ▼
          │              Match Object
          │                     │
          │             ┌───────┼───────┐
          │             │       │       │
          │             ▼       ▼       ▼
          │          start()  end()  group()
          │             │       │       │
          └─────────────┴───────┴───────┘
                        │
                        ▼
                      Output
                        │
                        ▼
                       End
        

Quick Revision

findall(pattern, string)
        │
        ▼
Find ALL occurrences
        │
        ▼
Return matched results
as a list for simple patterns


finditer(pattern, string)
        │
        ▼
Find ALL occurrences
        │
        ▼
Return an iterator
        │
        ▼
Each item is a
Match Object
        │
   ┌────┼─────┐
   ▼    ▼     ▼
start  end   group
        

Summary

• findall() and finditer() are important functions of Python's re module.
• Both functions are used to find all occurrences of a Regular Expression.
• findall() searches the complete target string.
• For simple patterns, findall() returns all matched strings in a list.
• If no match exists, findall() returns an empty list.
• finditer() also searches for all occurrences.
• finditer() returns an iterator that provides Match Objects.
• Each Match Object contains information about one successful match.
• start() returns the starting index.
• end() returns the position immediately after the matched substring.
• group() returns the actual matched value.
• findall() is convenient when only matched values are required.
• finditer() is useful when both matched values and their positions are required.
• search() returns only the first occurrence, whereas findall() and finditer() process all occurrences.

Important Notes

1. findall() and finditer() should not be confused with search().
2. search() returns only the first successful Match Object.
3. findall() searches for all matches.
4. finditer() also searches for all matches.
5. For simple Regular Expressions, findall() gives the matched values directly.
6. finditer() gives Match Objects instead of only matched values.
7. Use start() when you need the starting position of a match.
8. Use end() when you need the position immediately after the match.
9. Use group() when you need the actual matched text.
10. For a one-character match at index 3, start() is 3 and end() is 4.
11. If findall() finds no match, it returns [].
12. If finditer() finds no matches, its iterator simply produces no Match Objects.
13. finditer() is especially useful when the position of every match is important.
14. For simple patterns, remember: findall() = values and finditer() = Match Objects.
15. When capturing groups are introduced, the exact result returned by findall() can differ from the simple string-list behaviour.