pytimeparse

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.

Package Information

• Package Name: pytimeparse
• Language: Python
• Installation: pip install pytimeparse
• Version: 1.1.8
• License: MIT
• Python Compatibility: 2.7, 3.2-3.6+

Core Imports

import pytimeparse

Common usage pattern:

from pytimeparse import parse

Alternative direct import:

from pytimeparse.timeparse import timeparse

Basic Usage

from pytimeparse import parse

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

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

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

# Parse signed expressions
seconds = parse('+32m')       # 1920
seconds = parse('-32m')       # -1920

# Handle unparseable strings
result = parse('invalid')     # None

Capabilities

Time Expression Parsing

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

def parse(sval, granularity='seconds'):
    """
    Parse a time expression, returning it as a number of seconds.
    
    Parameters:
    - sval (str): The string value to parse
    - granularity (str, optional): Either 'seconds' (default) or 'minutes'.
                                   Affects interpretation of ambiguous colon-separated times.
                                   When 'minutes', formats like '1:30' are interpreted as 
                                   1 hour 30 minutes instead of 1 minute 30 seconds.
    
    Returns:
    - int or float: Number of seconds, or None if parsing fails
    
    Raises:
    - No exceptions raised for invalid input
    """

Granularity Control

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

from pytimeparse import parse

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

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

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

Supported Time Expression Formats

Abbreviated Unit Formats

• 32m - 32 minutes
• 2h32m - 2 hours 32 minutes
• 3d2h32m - 3 days 2 hours 32 minutes
• 1w3d2h32m - 1 week 3 days 2 hours 32 minutes

Spaced Formats

• 1w 3d 2h 32m - With spaces between units
• 1 w 3 d 2 h 32 m - With spaces around units

Clock Formats

• 4:13 - 4 minutes 13 seconds (or 4 hours 13 minutes with granularity='minutes')
• 4:13:02 - 4 hours 13 minutes 2 seconds
• 4:13:02.266 - With fractional seconds
• 2:04:13:02.266 - 2 days 4 hours 13 minutes 2.266 seconds
• :22 - 22 seconds (bare seconds)

Uptime Formats

• 2 days, 4:13:02 - Combined day count with clock format
• 2 days, 4:13:02.266 - With fractional seconds

Natural Language Formats

• 5hr34m56s - Abbreviated mixed format
• 5 hours, 34 minutes, 56 seconds - Full words
• 5 hrs, 34 mins, 56 secs - Abbreviated words
• 2 days, 5 hours, 34 minutes, 56 seconds - Multi-unit natural language

Decimal Formats

• 1.2 m / 1.2 min / 1.2 mins / 1.2 minute / 1.2 minutes - Decimal minutes
• 172 hours / 172 hr / 172 h / 172 hrs / 172 hour - Various hour formats
• 1.24 days / 5 d / 5 day / 5 days - Day formats
• 5.6 wk / 5.6 week / 5.6 weeks - Week formats
• 1.75 s / 1.75 sec / 1.75 secs / 1.75 second / 1.75 seconds - Second formats

Signed Expressions

• +32m - Positive 32 minutes (explicit positive sign)
• -32m - Negative 32 minutes
• + 32m / - 32m - With spaces after sign

Unit Conversion Values

The library uses these conversion factors:

• Seconds: 1
• Minutes: 60
• Hours: 3600 (60 × 60)
• Days: 86400 (24 × 60 × 60)
• Weeks: 604800 (7 × 24 × 60 × 60)

Error Handling

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

Return Types

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

Alternative Import Patterns

# Direct access to main function
from pytimeparse.timeparse import timeparse
result = timeparse('1h30m')

# Access to version information  
import pytimeparse
version = pytimeparse.__version__  # '1.1.8'

# Both parse and timeparse refer to the same function
from pytimeparse import parse
from pytimeparse.timeparse import timeparse
assert parse is timeparse  # True