Skip to content

🔧 Type System

Advanced type handling and conversion utilities.

🎯 Overview

Type system provides low-level type detection, conversion, and handling utilities.

📦 Functions

Type Utilities

datason.safe_float(value: Any, default: float = 0.0) -> float

Convert value to float, handling NaN, None, and Inf values safely.

This function is particularly useful when working with pandas DataFrames that may contain NaN values or when processing data from external sources that may have None values.

Parameters:

Name Type Description Default
value Any

Value to convert to float

 required
default float

Default value to return if conversion fails or value is NaN/None/Inf

 0.0

Returns:

Type Description
float

Float value or default if conversion fails

Examples:

>>> safe_float(42.5)
42.5
>>> safe_float(None)
0.0
>>> safe_float(float('nan'))
0.0
>>> safe_float(float('inf'))
0.0
>>> safe_float("invalid", 10.0)
10.0
Source code in datason/converters.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
def safe_float(value: Any, default: float = 0.0) -> float:
    """Convert value to float, handling NaN, None, and Inf values safely.

    This function is particularly useful when working with pandas DataFrames
    that may contain NaN values or when processing data from external sources
    that may have None values.

    Args:
        value: Value to convert to float
        default: Default value to return if conversion fails or value is NaN/None/Inf

    Returns:
        Float value or default if conversion fails

    Examples:
        >>> safe_float(42.5)
        42.5
        >>> safe_float(None)
        0.0
        >>> safe_float(float('nan'))
        0.0
        >>> safe_float(float('inf'))
        0.0
        >>> safe_float("invalid", 10.0)
        10.0
    """
    if value is None:
        return default
    try:
        float_val = float(value)
        return default if (math.isnan(float_val) or math.isinf(float_val)) else float_val
    except (ValueError, TypeError):
        return default

datason.safe_int(value: Any, default: int = 0) -> int

Convert value to int, handling NaN and None values safely.

This function is particularly useful when working with pandas DataFrames that may contain NaN values or when processing data from external sources that may have None values.

Parameters:

Name Type Description Default
value Any

Value to convert to int

 required
default int

Default value to return if conversion fails or value is NaN/None

 0

Returns:

Type Description
int

Integer value or default if conversion fails

Examples:

>>> safe_int(42)
42
>>> safe_int(42.7)
42
>>> safe_int(None)
0
>>> safe_int(float('nan'))
0
>>> safe_int("invalid", 10)
10
Source code in datason/converters.py 
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
def safe_int(value: Any, default: int = 0) -> int:
    """Convert value to int, handling NaN and None values safely.

    This function is particularly useful when working with pandas DataFrames
    that may contain NaN values or when processing data from external sources
    that may have None values.

    Args:
        value: Value to convert to int
        default: Default value to return if conversion fails or value is NaN/None

    Returns:
        Integer value or default if conversion fails

    Examples:
        >>> safe_int(42)
        42
        >>> safe_int(42.7)
        42
        >>> safe_int(None)
        0
        >>> safe_int(float('nan'))
        0
        >>> safe_int("invalid", 10)
        10
    """
    if value is None:
        return default
    try:
        if isinstance(value, float) and (math.isnan(value) or math.isinf(value)):
            return default
        # Handle string representations of floats
        if isinstance(value, str):
            try:
                float_val = float(value)
                if math.isnan(float_val) or math.isinf(float_val):
                    return default
                return int(float_val)
            except (ValueError, TypeError):
                return default
        return int(value)
    except (ValueError, TypeError, OverflowError):
        return default

datason.ensure_timestamp(val: Any) -> Any

Ensure a scalar date value is a pandas Timestamp. Use this for group-level date fields.

Parameters:

Name Type Description Default
val Any

A date value (can be pd.Timestamp, datetime, or string)

 required

Returns:

Type Description
Any

pd.Timestamp or pd.NaT

Raises: TypeError: If input is a list, dict, or other non-date-like object

Source code in datason/datetime_utils.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
def ensure_timestamp(val: Any) -> Any:
    """Ensure a scalar date value is a pandas Timestamp. Use this for group-level date fields.

    Args:
        val: A date value (can be pd.Timestamp, datetime, or string)

    Returns:
        pd.Timestamp or pd.NaT
    Raises:
        TypeError: If input is a list, dict, or other non-date-like object
    """
    if pd is None:
        raise ImportError("pandas is required for ensure_timestamp function")

    if val is None or (isinstance(val, float) and pd.isna(val)):
        return pd.NaT
    if isinstance(val, pd.Timestamp):
        return val
    if isinstance(val, (list, dict, set)):
        logger.error(f"ensure_timestamp: Invalid type {type(val)} for value {val}")
        raise TypeError(f"Cannot convert type {type(val)} to Timestamp")
    try:
        return pd.to_datetime(val)
    except Exception as e:
        logger.warning(f"ensure_timestamp: Could not convert {val!r} to Timestamp: {e}")
        return pd.NaT