Skip to content

Utils

conversions

Functions:

  • date_to_int –

    Converts a date object to an integer representation.

  • int_to_date –

    Converts an int or str object to the datetime.date representation.

  • date_to_datetime –

    Converts one object from date to the datetime object.

  • day_to_ordinal –

    Converts an integer day to an ordinal number, i.e., 1 -> 1st, 32 -> 32nd

  • next_month –

    Returns the next month after the provided month. Original source.

  • month_range –

    Range of the provided month as a tuple [start, end).

  • current_timestamp –

    Returns the current timestamp in milliseconds, using UTC time.

  • cents_to_decimal –

    Converts the number of cents to a decimal.Decimal object.

  • decimal_to_cents –

    Converts the decimal amount (decimal.Decimal or int or float) to an integer value.

date_to_int 

date_to_int(date: date, month_only: bool = False) -> int

Converts a date object to an integer representation.

For example, the date(2025, 3, 10) gets converted to 20250310.

If month_only is set to True, the day will be removed from the date.

For example, the same date above gets converted to 202503.

Source code in actual/utils/conversions.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
def date_to_int(date: datetime.date, month_only: bool = False) -> int:
    """
    Converts a date object to an integer representation.

    For example, the `date(2025, 3, 10)` gets converted to `20250310`.

    If `month_only` is set to `True`, the day will be removed from the date.

    For example, the same date above gets converted to `202503`.
    """
    date_format = "%Y%m" if month_only else "%Y%m%d"
    return int(datetime.date.strftime(date, date_format))

int_to_date 

int_to_date(
    date: int | str, month_only: bool = False
) -> date

Converts an int or str object to the datetime.date representation.

For example, the int 20250310 gets converted to date(2025, 3, 10).

Source code in actual/utils/conversions.py 
22
23
24
25
26
27
28
29
def int_to_date(date: int | str, month_only: bool = False) -> datetime.date:
    """
    Converts an `int` or `str` object to the `datetime.date` representation.

    For example, the int `20250310` gets converted to `date(2025, 3, 10)`.
    """
    date_format = "%Y%m" if month_only else "%Y%m%d"
    return datetime.datetime.strptime(str(date), date_format).date()

date_to_datetime 

date_to_datetime(date: date) -> datetime

date_to_datetime(date: None) -> None

date_to_datetime(date: date | None) -> datetime | None

Converts one object from date to the datetime object.

The reverse is possible directly by calling datetime.date().

Source code in actual/utils/conversions.py 
40
41
42
43
44
45
46
47
48
def date_to_datetime(date: datetime.date | None) -> datetime.datetime | None:
    """
    Converts one object from date to the datetime object.

    The reverse is possible directly by calling `datetime.date()`.
    """
    if date is None:
        return None
    return datetime.datetime.combine(date, datetime.time.min)

day_to_ordinal 

day_to_ordinal(day: int) -> str

Converts an integer day to an ordinal number, i.e., 1 -> 1st, 32 -> 32nd

Source code in actual/utils/conversions.py 
51
52
53
54
55
56
57
def day_to_ordinal(day: int) -> str:
    """Converts an integer day to an ordinal number, i.e., 1 -> 1st, 32 -> 32nd"""
    if 11 <= (day % 100) <= 13:
        suffix = "th"
    else:
        suffix = ["th", "st", "nd", "rd", "th"][min(day % 10, 4)]
    return f"{day}{suffix}"

next_month 

next_month(month: date) -> date

Returns the next month after the provided month. Original source.

Source code in actual/utils/conversions.py 
60
61
62
63
64
def next_month(month: datetime.date) -> datetime.date:
    """
    Returns the next month after the provided `month`. [Original source](https://stackoverflow.com/a/59199379/12681470).
    """
    return (month.replace(day=1) + datetime.timedelta(days=32)).replace(day=1)

month_range 

month_range(month: date) -> tuple[date, date]

Range of the provided month as a tuple [start, end).

The end date is not inclusive, as it represents the start of the next month.

Source code in actual/utils/conversions.py 
67
68
69
70
71
72
73
74
75
def month_range(month: datetime.date) -> tuple[datetime.date, datetime.date]:
    """
    Range of the provided `month` as a tuple `[start, end)`.

    The end date is not inclusive, as it represents the start of the next month.
    """
    range_start = month.replace(day=1)
    range_end = next_month(month)
    return range_start, range_end

current_timestamp 

current_timestamp() -> int

Returns the current timestamp in milliseconds, using UTC time.

Source code in actual/utils/conversions.py 
78
79
80
def current_timestamp() -> int:
    """Returns the current timestamp in milliseconds, using UTC time."""
    return int(datetime.datetime.now(datetime.timezone.utc).timestamp() * 1000)

cents_to_decimal 

cents_to_decimal(amount: int | None) -> Decimal

Converts the number of cents to a decimal.Decimal object.

When providing 500, the result will be decimal.Decimal(5.0).

Source code in actual/utils/conversions.py 
83
84
85
86
87
88
89
90
91
def cents_to_decimal(amount: int | None) -> decimal.Decimal:
    """
    Converts the number of cents to a `decimal.Decimal` object.

    When providing `500`, the result will be `decimal.Decimal(5.0)`.
    """
    if amount is None:
        return decimal.Decimal(0)
    return decimal.Decimal(amount) / decimal.Decimal(100)

decimal_to_cents 

decimal_to_cents(amount: Decimal | int | float) -> int

Converts the decimal amount (decimal.Decimal or int or float) to an integer value.

When providing decimal.Decimal(5.0), the result will be 500.

Source code in actual/utils/conversions.py 
 94
 95
 96
 97
 98
 99
100
def decimal_to_cents(amount: decimal.Decimal | int | float) -> int:
    """
    Converts the decimal amount (`decimal.Decimal` or `int` or `float`) to an integer value.

    When providing `decimal.Decimal(5.0)`, the result will be `500`.
    """
    return int(round(amount * 100))