0
# pytimeparse
1

2
A Python library for parsing various kinds of time expressions into numeric values representing seconds. It handles diverse time formats including abbreviated units, colon-separated time formats, natural language expressions, and mixed formats with decimal values. The library exposes a single main function that converts time strings into integer or floating-point seconds, making it highly reusable for applications requiring time duration parsing, scheduling systems, configuration parsers, and any tool that needs to interpret human-readable time expressions in a consistent programmatic format.
3

4
## Package Information
5

6
- **Package Name**: pytimeparse
7
- **Language**: Python
8
- **Installation**: `pip install pytimeparse`
9
- **Version**: 1.1.8
10
- **License**: MIT
11
- **Python Compatibility**: 2.7, 3.2-3.6+
12

13
## Core Imports
14

15
```python
16
import pytimeparse
17
```
18

19
Common usage pattern:
20

21
```python
22
from pytimeparse import parse
23
```
24

25
Alternative direct import:
26

27
```python
28
from pytimeparse.timeparse import timeparse
29
```
30

31
## Basic Usage
32

33
```python
34
from pytimeparse import parse
35

36
# Parse abbreviated time formats
37
seconds = parse('32m')        # 1920 (32 minutes)
38
seconds = parse('2h32m')      # 9120 (2 hours 32 minutes)
39
seconds = parse('1w3d2h32m')  # 873120 (1 week 3 days 2 hours 32 minutes)
40

41
# Parse clock formats
42
seconds = parse('4:13')       # 253 (4 minutes 13 seconds)
43
seconds = parse('4:13:02')    # 15182 (4 hours 13 minutes 2 seconds)
44
seconds = parse(':22')        # 22 (22 seconds)
45

46
# Parse natural language
47
seconds = parse('1 minute, 24 secs')          # 84
48
seconds = parse('5 hours, 34 minutes, 56 seconds')  # 20096
49
seconds = parse('1.2 minutes')                # 72.0
50

51
# Parse signed expressions
52
seconds = parse('+32m')       # 1920
53
seconds = parse('-32m')       # -1920
54

55
# Handle unparseable strings
56
result = parse('invalid')     # None
57
```
58

59
## Capabilities
60

61
### Time Expression Parsing
62

63
Parses time expressions and returns the equivalent number of seconds as an integer or float. Returns None if the expression cannot be parsed.
64

65
```python { .api }
66
def parse(sval, granularity='seconds'):
67
    """
68
    Parse a time expression, returning it as a number of seconds.
69
    
70
    Parameters:
71
    - sval (str): The string value to parse
72
    - granularity (str, optional): Either 'seconds' (default) or 'minutes'.
73
                                   Affects interpretation of ambiguous colon-separated times.
74
                                   When 'minutes', formats like '1:30' are interpreted as 
75
                                   1 hour 30 minutes instead of 1 minute 30 seconds.
76
    
77
    Returns:
78
    - int or float: Number of seconds, or None if parsing fails
79
    
80
    Raises:
81
    - No exceptions raised for invalid input
82
    """
83
```
84

85
### Granularity Control
86

87
The `granularity` parameter controls how ambiguous colon-separated time formats are interpreted:
88

89
```python
90
from pytimeparse import parse
91

92
# Default behavior: interpret as minutes:seconds
93
parse('1:30')                    # 90 (1 minute 30 seconds)
94

95
# Minutes granularity: interpret as hours:minutes  
96
parse('1:30', granularity='minutes')  # 5400 (1 hour 30 minutes)
97

98
# Granularity only affects ambiguous formats (single colon, no decimals)
99
parse('1:30:45')                 # 5445 (same regardless of granularity)
100
parse('1:30:45', granularity='minutes')  # 5445 (same result)
101
```
102

103
## Supported Time Expression Formats
104

105
### Abbreviated Unit Formats
106
- `32m` - 32 minutes
107
- `2h32m` - 2 hours 32 minutes  
108
- `3d2h32m` - 3 days 2 hours 32 minutes
109
- `1w3d2h32m` - 1 week 3 days 2 hours 32 minutes
110

111
### Spaced Formats
112
- `1w 3d 2h 32m` - With spaces between units
113
- `1 w 3 d 2 h 32 m` - With spaces around units
114

115
### Clock Formats
116
- `4:13` - 4 minutes 13 seconds (or 4 hours 13 minutes with `granularity='minutes'`)
117
- `4:13:02` - 4 hours 13 minutes 2 seconds
118
- `4:13:02.266` - With fractional seconds
119
- `2:04:13:02.266` - 2 days 4 hours 13 minutes 2.266 seconds
120
- `:22` - 22 seconds (bare seconds)
121

122
### Uptime Formats
123
- `2 days, 4:13:02` - Combined day count with clock format
124
- `2 days, 4:13:02.266` - With fractional seconds
125

126
### Natural Language Formats
127
- `5hr34m56s` - Abbreviated mixed format
128
- `5 hours, 34 minutes, 56 seconds` - Full words
129
- `5 hrs, 34 mins, 56 secs` - Abbreviated words
130
- `2 days, 5 hours, 34 minutes, 56 seconds` - Multi-unit natural language
131

132
### Decimal Formats
133
- `1.2 m` / `1.2 min` / `1.2 mins` / `1.2 minute` / `1.2 minutes` - Decimal minutes
134
- `172 hours` / `172 hr` / `172 h` / `172 hrs` / `172 hour` - Various hour formats
135
- `1.24 days` / `5 d` / `5 day` / `5 days` - Day formats
136
- `5.6 wk` / `5.6 week` / `5.6 weeks` - Week formats
137
- `1.75 s` / `1.75 sec` / `1.75 secs` / `1.75 second` / `1.75 seconds` - Second formats
138

139
### Signed Expressions
140
- `+32m` - Positive 32 minutes (explicit positive sign)
141
- `-32m` - Negative 32 minutes
142
- `+ 32m` / `- 32m` - With spaces after sign
143

144
## Unit Conversion Values
145

146
The library uses these conversion factors:
147

148
- **Seconds**: 1
149
- **Minutes**: 60
150
- **Hours**: 3600 (60 × 60)
151
- **Days**: 86400 (24 × 60 × 60)
152
- **Weeks**: 604800 (7 × 24 × 60 × 60)
153

154
## Error Handling
155

156
- Returns `None` for unparseable time expressions
157
- No exceptions are thrown for invalid input
158
- Invalid characters or malformed expressions result in `None`
159
- Mixed signs within expression (e.g., `'32m - 1s'`) return `None`
160

161
## Return Types
162

163
- **Integer**: Returned when all time components are whole numbers and seconds component (if present) is an integer
164
- **Float**: Returned when any component contains decimal values or when seconds component is fractional
165
- **None**: Returned for unparseable input
166

167
## Alternative Import Patterns
168

169
```python
170
# Direct access to main function
171
from pytimeparse.timeparse import timeparse
172
result = timeparse('1h30m')
173

174
# Access to version information  
175
import pytimeparse
176
version = pytimeparse.__version__  # '1.1.8'
177

178
# Both parse and timeparse refer to the same function
179
from pytimeparse import parse
180
from pytimeparse.timeparse import timeparse
181
assert parse is timeparse  # True
182
```