0
# first
1

2
A simple Python utility function that returns the first truthy value from an iterable. The `first` package provides a clean, Pythonic solution for finding the first element that evaluates to True, with optional support for custom key functions and default values when no truthy element is found.
3

4
## Package Information
5

6
- **Package Name**: first
7
- **Language**: Python
8
- **Installation**: `pip install first`
9

10
## Core Imports
11

12
```python
13
from first import first
14
```
15

16
Access to package metadata:
17

18
```python
19
import first
20
print(first.__version__)  # '2.0.2'
21
print(first.__author__)   # 'Hynek Schlawack'
22
```
23

24
## Basic Usage
25

26
```python
27
from first import first
28

29
# Simple usage - returns first truthy value
30
result = first([0, False, None, [], (), 42])
31
print(result)  # 42
32

33
# Returns None if no truthy values found
34
result = first([0, False, None, [], ()])
35
print(result)  # None
36

37
# Use default value when no truthy element exists
38
result = first([0, False, None, [], ()], default='not found')
39
print(result)  # 'not found'
40

41
# Use key function to customize truthiness evaluation
42
result = first([1, 1, 3, 4, 5], key=lambda x: x % 2 == 0)
43
print(result)  # 4 (first even number)
44
```
45

46
## Capabilities
47

48
### First Element Selection
49

50
Returns the first element from an iterable that evaluates to true, or a default value if none found.
51

52
```python { .api }
53
def first(iterable, default=None, key=None):
54
    """
55
    Return first element of `iterable` that evaluates true, else return None
56
    (or an optional default value).
57

58
    Parameters:
59
    - iterable: Any iterable object (list, tuple, generator, etc.)
60
    - default: Optional default value to return if no truthy element is found (defaults to None)
61
    - key: Optional one-argument predicate function like that used for filter(). Must be in keyword form.
62

63
    Returns:
64
    First truthy element from the iterable, or `default` if none found
65

66
    Examples:
67
    >>> first([0, False, None, [], (), 42])
68
    42
69
    
70
    >>> first([0, False, None, [], ()]) is None
71
    True
72
    
73
    >>> first([0, False, None, [], ()], default='ohai')
74
    'ohai'
75
    
76
    >>> first([1, 1, 3, 4, 5], key=lambda x: x % 2 == 0)
77
    4
78
    """
79
```
80

81
### Package Metadata
82

83
Access to package version and author information.
84

85
```python { .api }
86
__version__ = "2.0.2"
87
__author__ = "Hynek Schlawack"
88
__license__ = "MIT"
89
__copyright__ = "Copyright 2012 Hynek Schlawack"
90
__title__ = "first"
91
```
92

93
## Usage Examples
94

95
### Regular Expression Matching
96

97
Common pattern for handling multiple regex attempts:
98

99
```python
100
import re
101
from first import first
102

103
# Define regex patterns
104
re1 = re.compile('b(.*)')
105
re2 = re.compile('a(.*)')
106

107
# Find first matching pattern
108
m = first(regexp.match('abc') for regexp in [re1, re2])
109
if not m:
110
    print('no match!')
111
elif m.re is re1:
112
    print('re1', m.group(1))
113
elif m.re is re2:
114
    print('re2', m.group(1))
115
```
116

117
### Filtering with Custom Keys
118

119
Use key functions to find first element matching specific criteria:
120

121
```python
122
from first import first
123

124
# Find first even number
125
numbers = [1, 1, 3, 4, 5]
126
result = first(numbers, key=lambda x: x % 2 == 0)
127
print(result)  # 4
128

129
# Find first boolean value
130
mixed_values = [(), 0, False, 3, []]
131
result = first(mixed_values, key=lambda x: isinstance(x, bool))
132
print(result)  # False
133

134
# Find first integer value
135
result = first(mixed_values, key=lambda x: isinstance(x, int))
136
print(result)  # 0
137
```
138

139
### Providing Default Values
140

141
Handle cases where no truthy element exists:
142

143
```python
144
from first import first
145

146
# Empty iterables
147
result = first([], default=42)
148
print(result)  # 42
149

150
# All falsy values
151
result = first([0, False, []], default=3.14)
152
print(result)  # 3.14
153

154
# No match with key function
155
result = first([1, 3, 5], key=lambda x: x % 2 == 0, default='no even numbers')
156
print(result)  # 'no even numbers'
157
```