strcoerce

Safe string-to-type coercion for Python. Zero dependencies.

The problem

import os
DEBUG = bool(os.environ.get("DEBUG", "false"))  # Always True — "false" is a non-empty string

bool("false") is True in Python. This catches experienced developers off guard and is a documented trap with no stdlib fix.

Install

pip install strcoerce

Usage

from strcoerce import parse_bool, parse_int, parse_float, parse_list, parse_duration

# Environment variables
DEBUG  = parse_bool(os.environ.get("DEBUG", "false"))   # False
PORT   = parse_int(os.environ.get("PORT", "8080"))      # 8080
HOSTS  = parse_list(os.environ.get("ALLOWED_HOSTS", ""))  # []

# With defaults
parse_bool("maybe", default=False)  # False — no exception
parse_int("oops",   default=0)      # 0

# Durations
from datetime import timedelta
parse_duration("2h30m")   # timedelta(hours=2, minutes=30)
parse_duration("1w2d")    # timedelta(weeks=1, days=2)

API

parse_bool(s, *, default=<raise>)

Case-insensitive. Strips surrounding whitespace.

parse_int(s, *, default=<raise>, base=10)

parse_int("42")              # 42
parse_int("0xff", base=16)   # 255
parse_int("bad", default=0)  # 0

parse_float(s, *, default=<raise>)

parse_float("3.14")           # 3.14
parse_float("1e-3")           # 0.001
parse_float("bad", default=0) # 0

parse_list(s, sep=",", *, strip=True)

parse_list("a, b, c")          # ["a", "b", "c"]
parse_list("a|b|c", sep="|")   # ["a", "b", "c"]
parse_list("")                 # []

parse_duration(s)

Parses combinations of Nw Nd Nh Nm Ns (weeks/days/hours/minutes/seconds).

parse_duration("30s")        # timedelta(seconds=30)
parse_duration("5m")         # timedelta(minutes=5)
parse_duration("2h30m")      # timedelta(hours=2, minutes=30)
parse_duration("1w2d3h4m5s") # timedelta(weeks=1, days=2, hours=3, minutes=4, seconds=5)

Error handling

All functions raise ParseError (subclass of ValueError) when input is invalid and no default is given.

from strcoerce import ParseError

try:
    val = parse_bool(user_input)
except ParseError as e:
    print(f"Invalid boolean: {e}")

License

MIT