Casting is essential in programming. With Pydicts I try to put together main castings, to work easyly with all kind of data structures.
ignore_exception¶
Morever, this module casting function has two additional parameters, that are useful for rapid development:
ignore_exception. By default False. If you set this parameter to True, casting with return ignore_exception_value if a CastException happens.
ignore_exception_value. By default None. It’s the value casting will return if a CastException happens
For example, this code casts.str2bool(None) will raise a CastException, due to None is not a valid value.
But this code will return None
from pydicts import casts
casts.str2bool(None, ignore_exception=True)And this code will return False
from pydicts import casts
casts.str2bool(None, ignore_exception=True,ignore_exception_value=False)FalseCasts¶
base64bytes2bytes¶
Help on function base64bytes2bytes in module pydicts.casts:
base64bytes2bytes(value, ignore_exception=False, ignore_exception_value=None)
Decodes a base64-encoded bytes object back into its original bytes.
Args:
value (bytes): The base64-encoded bytes object.
ignore_exception (bool, optional): If True, returns `ignore_exception_value` on error instead of raising an exception. Defaults to False.
ignore_exception_value (any, optional): The value to return if an exception is ignored. Defaults to None.
Returns:
bytes: The decoded bytes object.
bytes2base64bytes¶
Help on function bytes2base64bytes in module pydicts.casts:
bytes2base64bytes(value, ignore_exception=False, ignore_exception_value=None)
Encodes a bytes object into a base64-encoded bytes object.
Args:
value (bytes): The bytes object to encode.
ignore_exception (bool, optional): If True, returns `ignore_exception_value` on error instead of raising an exception. Defaults to False.
ignore_exception_value (any, optional): The value to return if an exception is ignored. Defaults to None.
Returns:
bytes: The base64-encoded bytes object.
bytes2str¶
Help on function bytes2str in module pydicts.casts:
bytes2str(
value,
code='UTF-8',
ignore_exception=False,
ignore_exception_value=None
)
Converts a bytes object to a string using the specified encoding.
date2str¶
Help on function date2str in module pydicts.casts:
date2str(
value,
format='JsIso',
ignore_exception=False,
ignore_exception_value=None
)
Converts a datetime.date object to its string representation.
Args:
value (date): The datetime.date object to convert.
format (str, optional): The desired output format. Allowed values:
"JsIso" (YYYY-MM-DD), "DD/MM/YYYY", "DD.MM.YYYY",
"long string" (e.g., "January 15, 2023" or "15 de enero de 2023" based on locale).
Defaults to "JsIso".
ignore_exception (bool, optional): If True, returns `ignore_exception_value` on error instead of raising an exception. Defaults to False.
ignore_exception_value (any, optional): The value to return if an exception is ignored. Defaults to None.
Returns:
str: The string representation of the date.
Note:
The "long string" format is locale-dependent. It attempts to format the date
in a human-readable way based on the system's current locale (e.g., English, Spanish).
If the locale is not explicitly handled, it defaults to an English-like format.
dtaware2dtnaive¶
Help on function dtaware2dtnaive in module pydicts.casts:
dtaware2dtnaive(dtaware)
Converts a timezone-aware datetime object to a timezone-naive datetime object.
Args:
dtaware (datetime): A timezone-aware datetime object.
Returns:
datetime: A timezone-naive datetime object.
Raises:
exceptions.CastException: If the input datetime object is not timezone-aware.
dtaware2epochmicros¶
Help on function dtaware2epochmicros in module pydicts.casts:
dtaware2epochmicros(d)
Converts a timezone-aware datetime object to microseconds since the Unix epoch (1970-01-01 UTC).
Args:
d (datetime): A timezone-aware datetime object.
Returns:
int: The number of microseconds since epoch.
dtaware2epochms¶
Help on function dtaware2epochms in module pydicts.casts:
dtaware2epochms(d: datetime)
Converts a timezone-aware datetime object to milliseconds since the Unix epoch (1970-01-01 UTC).
Args:
d (datetime): A timezone-aware datetime object.
Returns:
int: The number of milliseconds since epoch.
dtaware2str¶
Help on function dtaware2str in module pydicts.casts:
dtaware2str(
value,
format='JsUtcIso',
ignore_exception=False,
ignore_exception_value=None
)
Converts a timezone-aware datetime object to its string representation in a specified format.
Args:
value (datetime): A timezone-aware datetime object.
format (str, optional): The desired output format. Allowed values:
"%Y-%m-%d", "%Y-%m-%d %H:%M:%S", "%Y%m%d %H%M", "%Y%m%d%H%M", "JsUtcIso",
"long string" (e.g., "January 15, 2023 at 10:30 UTC" or "15 de enero de 2023 a las 10:30 (UTC)" based on locale).
Defaults to "JsUtcIso".
ignore_exception (bool, optional): If True, returns `ignore_exception_value` on error instead of raising an exception. Defaults to False.
ignore_exception_value (any, optional): The value to return if an exception is ignored. Defaults to None.
Returns:
str: The string representation of the datetime.
Note:
The "long string" format is locale-dependent. It attempts to format the datetime
in a human-readable way including the timezone name, based on the system's current locale.
If the locale is not explicitly handled, it defaults to an English-like format.
dtnaive2dtaware¶
Help on function dtnaive2dtaware in module pydicts.casts:
dtnaive2dtaware(dtnaive, tz_name)
dtnaive2str¶
Help on function dtnaive2str in module pydicts.casts:
dtnaive2str(
value,
format='JsIso',
ignore_exception=False,
ignore_exception_value=None
)
Converts a timezone-naive datetime object to its string representation in a specified format.
Args:
value (datetime): A timezone-naive datetime object.
format (str, optional): The desired output format. Allowed values:
"%Y-%m-%d", "%Y-%m-%d %H:%M:%S", "%Y%m%d %H%M", "%Y%m%d%H%M", "JsIso",
"long string" (e.g., "January 15, 2023 at 10:30" or "15 de enero de 2023 a las 10:30" based on locale).
Defaults to "JsIso".
ignore_exception (bool, optional): If True, returns `ignore_exception_value` on error instead of raising an exception. Defaults to False.
ignore_exception_value (any, optional): The value to return if an exception is ignored. Defaults to None.
Returns:
str: The string representation of the datetime.
Note:
The "long string" format is locale-dependent. It attempts to format the datetime
in a human-readable way based on the system's current locale.
If the locale is not explicitly handled, it defaults to an English-like format.
epochmicros2dtaware¶
Help on function epochmicros2dtaware in module pydicts.casts:
epochmicros2dtaware(n, tz='UTC')
## Return a UTC datetime aware
epochms2dtaware¶
Help on function epochms2dtaware in module pydicts.casts:
epochms2dtaware(n: int | float, tz='UTC')
Converts milliseconds since the Unix epoch to a timezone-aware datetime object.
Args:
n (int | float): The number of milliseconds since epoch.
tz (str, optional): The target timezone name. Defaults to "UTC".
Returns:
datetime: A timezone-aware datetime object.
none2alternative¶
Help on function none2alternative in module pydicts.casts:
none2alternative(value, alternative)
If a value is None, returns an alternative value; otherwise, returns the original value.
Args:
value (any): The input value to check.
alternative (any): The value to return if `value` is None.
Returns:
any: `alternative` if `value` is None, otherwise `value`.
Example:
>>> none2alternative(None, 0)
0
>>> none2alternative(5, 0)
5
str2bool¶
Help on function str2bool in module pydicts.casts:
str2bool(value, ignore_exception=False, ignore_exception_value=None)
Converts a string representation ("true", "false", "1", "0") to a boolean.
Case-insensitive for "true" and "false".
Args:
value (str): The string to convert.
ignore_exception (bool, optional): If True, returns `ignore_exception_value` on error instead of raising an exception. Defaults to False.
ignore_exception_value (any, optional): The value to return if an exception is ignored. Defaults to None.
Returns:
bool: The converted boolean value.
from pydicts import casts
casts.str2bool("true")Truefrom pydicts import casts
casts.str2bool("0")FalseThese calls will raise CastException:
casts.str2bool(None)casts.str2bool(True)casts.str2bool("Verdadero")
str2bytes¶
Help on function str2bytes in module pydicts.casts:
str2bytes(
value,
code='UTF8',
ignore_exception=False,
ignore_exception_value=None
)
Converts a string to a bytes object using the specified encoding.
Args:
value (str): The string to convert.
code (str, optional): The encoding to use. Defaults to 'UTF8'.
ignore_exception (bool, optional): If True, returns `ignore_exception_value` on error instead of raising an exception. Defaults to False.
ignore_exception_value (any, optional): The value to return if an exception is ignored. Defaults to None.
Returns:
bytes: The converted bytes object.
str2date¶
Help on function str2date in module pydicts.casts:
str2date(
value,
format='YYYY-MM-DD',
ignore_exception=False,
ignore_exception_value=None
)
Converts a string representation of a date to a `datetime.date` object.
Args:
value (str): The string to convert.
format (str, optional): The format of the input string. Allowed values:
"YYYY-MM-DD", "DD/MM/YYYY", "DD.MM.YYYY", "DD/MM", "JsIso". Defaults to "YYYY-MM-DD".
ignore_exception (bool, optional): If True, returns `ignore_exception_value` on error instead of raising an exception. Defaults to False.
ignore_exception_value (any, optional): The value to return if an exception is ignored. Defaults to None.
Returns:
date: The converted `datetime.date` object.
str2decimal¶
Help on function str2decimal in module pydicts.casts:
str2decimal(value, ignore_exception=False, ignore_exception_value=None)
Converts a string to a decimal
Parameters:
Converts a string representation to a Decimal object.
Args:
value (str): The string to convert.
ignore_exception (bool, optional): If True, returns `ignore_exception_value` on error instead of raising an exception. Defaults to False.
ignore_exception_value (any, optional): The value to return if an exception is ignored. Defaults to None.
Returns:
Decimal: The converted Decimal object.
str2dtaware¶
Help on function str2dtaware in module pydicts.casts:
str2dtaware(
value,
format='JsUtcIso',
tz_name='UTC',
ignore_exception=False,
ignore_exception_value=None
)
Converts a string representation of a datetime to a timezone-aware `datetime.datetime` object.
Args:
value (str): The string to convert.
format (str, optional): The format of the input string. Allowed values:
"%Y-%m-%d %H:%M:%S%z", "%Y-%m-%d %H:%M:%S.%z", "JsUtcIso". Defaults to "JsUtcIso".
tz_name (str, optional): The target timezone name for the aware datetime. Defaults to 'UTC'.
ignore_exception (bool, optional): If True, returns `ignore_exception_value` on error instead of raising an exception. Defaults to False.
ignore_exception_value (any, optional): The value to return if an exception is ignored. Defaults to None.
Returns:
datetime: The converted timezone-aware `datetime.datetime` object.
str2dtnaive¶
Help on function str2dtnaive in module pydicts.casts:
str2dtnaive(
value,
format='JsIso',
ignore_exception=False,
ignore_exception_value=None
)
Converts a string representation of a datetime to a timezone-naive `datetime.datetime` object.
Args:
value (str): The string to convert.
format (str, optional): The format of the input string. Allowed values:
"%Y%m%d%H%M", "%Y-%m-%d %H:%M:%S", "%d/%m/%Y %H:%M", "%d %m %H:%M %Y",
"%Y-%m-%d %H:%M:%S.", "%H:%M:%S",
'%b %d %H:%M:%S' (e.g., "Jan 15 10:30:00", locale-dependent month abbreviation),
"JsIso" (e.g., "2021-08-21T06:27:38.294").
Defaults to "JsIso".
ignore_exception (bool, optional): If True, returns `ignore_exception_value` on error instead of raising an exception. Defaults to False.
ignore_exception_value (any, optional): The value to return if an exception is ignored. Defaults to None.
Returns:
datetime: The converted timezone-naive `datetime.datetime` object.
str2time¶
Help on function str2time in module pydicts.casts:
str2time(
value,
format='JsIso',
ignore_exception=False,
ignore_exception_value=None
)
Converts a string representation of time to a `datetime.time` object.
Args:
value (str): The string to convert.
format (str, optional): The format of the input string. Allowed values:
"HH:MM", "HH:MM:SS", "HH:MMxx" (e.g., "5:12am"), "JsIso". Defaults to "JsIso".
ignore_exception (bool, optional): If True, returns `ignore_exception_value` on error instead of raising an exception. Defaults to False.
ignore_exception_value (any, optional): The value to return if an exception is ignored. Defaults to None.
Returns:
time: The converted `datetime.time` object.
str2timedelta¶
Help on function str2timedelta in module pydicts.casts:
str2timedelta(value, ignore_exception=False, ignore_exception_value=None)
Converts an ISO 8601 duration string into a `datetime.timedelta` object.
Args:
value (str): The ISO 8601 duration string to convert.
ignore_exception (bool, optional): If True, returns `ignore_exception_value` on error instead of raising an exception. Defaults to False.
ignore_exception_value (any, optional): The value to return if an exception is ignored. Defaults to None.
Returns:
timedelta: The converted `datetime.timedelta` object.
Raises:
exceptions.CastException: If `value` is not a string, is empty, or is not a valid ISO 8601 duration string, and `ignore_exception` is False.
time2str¶
Help on function time2str in module pydicts.casts:
time2str(
value,
format='JsIso',
ignore_exception=False,
ignore_exception_value=None
)
Converts a `datetime.time` object to its string representation.
Args:
value (time): The `datetime.time` object to convert.
format (str, optional): The desired output format. Allowed values:
"HH:MM", "HH:MM:SS", "Xulpymoney", "JsIso". Defaults to "JsIso".
ignore_exception (bool, optional): If True, returns `ignore_exception_value` on error instead of raising an exception. Defaults to False.
ignore_exception_value (any, optional): The value to return if an exception is ignored. Defaults to None.
Returns:
str: The string representation of the time.
timedelta2str¶
Help on function timedelta2str in module pydicts.casts:
timedelta2str(value, ignore_exception=False, ignore_exception_value=None)
Converts a `datetime.timedelta` object into an ISO 8601 duration string.
Args:
value (timedelta): The `datetime.timedelta` object to convert.
ignore_exception (bool, optional): If True, returns `ignore_exception_value` on error instead of raising an exception. Defaults to False.
ignore_exception_value (any, optional): The value to return if an exception is ignored. Defaults to None.
Returns:
str: The ISO 8601 duration string.
Raises:
exceptions.CastException: If `value` is not a `timedelta` object and `ignore_exception` is False.
Date and time utils¶
date_first_of_the_month¶
Help on function date_first_of_the_month in module pydicts.casts:
date_first_of_the_month(year, month)
Returns a date object representing the first day of the specified month and year.
Args:
year (int): The year.
month (int): The month (1-12).
Returns:
date: A `datetime.date` object for the first day of the month.
date_first_of_the_next_x_months¶
Help on function date_first_of_the_next_x_months in module pydicts.casts:
date_first_of_the_next_x_months(year, month, x)
date_first_of_the_year¶
Help on function date_first_of_the_year in module pydicts.casts:
date_first_of_the_year(year)
Returns a date object representing the first day of the specified year.
Args:
year (int): The year.
Returns:
date: A `datetime.date` object for January 1st of the year.
date_last_of_the_month¶
Help on function date_last_of_the_month in module pydicts.casts:
date_last_of_the_month(year, month)
Returns a date object representing the last day of the specified month and year.
Args:
year (int): The year.
month (int): The month (1-12).
Returns:
date: A `datetime.date` object for the last day of the month.
date_last_of_the_next_x_months¶
Help on function date_last_of_the_next_x_months in module pydicts.casts:
date_last_of_the_next_x_months(year, month, x)
date_last_of_the_year¶
Help on function date_last_of_the_year in module pydicts.casts:
date_last_of_the_year(year)
Returns a date object representing the last day of the specified year.
Args:
year (int): The year.
Returns:
date: A `datetime.date` object for December 31st of the year.
dtaware¶
Help on function dtaware in module pydicts.casts:
dtaware(date_, time_, tz_name)
Creates a timezone-aware datetime object from a date, time, and timezone name.
Args:
date_ (date): A `datetime.date` object.
time_ (time): A `datetime.time` object.
tz_name (str): A string representing the timezone name (e.g., "Europe/Madrid").
Returns:
datetime: A timezone-aware datetime object.
dtaware_changes_tz¶
Help on function dtaware_changes_tz in module pydicts.casts:
dtaware_changes_tz(dt, tzname)
Changes the timezone of a timezone-aware datetime object.
Args:
dt (datetime): A timezone-aware datetime object.
tzname (str): The name of the target timezone (e.g., "Europe/Madrid").
Returns:
datetime: A new timezone-aware datetime object converted to the target timezone.
Raises:
exceptions.CastException: If the input datetime object is timezone-naive.
Example:
>>> dt_madrid = datetime(2018, 5, 18, 8, 12, tzinfo=ZoneInfo('Europe/Madrid'))
>>> dtaware_changes_tz(dt_madrid, "Europe/London")
datetime.datetime(2018, 5, 18, 7, 12, tzinfo=<DstTzInfo 'Europe/London' BST+1:00:00 DST>)
dtaware_day_end¶
Help on function dtaware_day_end in module pydicts.casts:
dtaware_day_end(dt, tz_name)
Returns the last datetime (microsecond level) of the day in tz_name zone
dtaware_day_end_from_date¶
Help on function dtaware_day_end_from_date in module pydicts.casts:
dtaware_day_end_from_date(date, tz_name)
Returns a timezone-aware datetime object representing the end of the day for a given date and timezone.
Args:
date (date): A `datetime.date` object.
tz_name (str): The name of the timezone.
Returns:
datetime: A timezone-aware datetime object set to 23:59:59.999999 of the given date in the specified timezone.
dtaware_day_start¶
Help on function dtaware_day_start in module pydicts.casts:
dtaware_day_start(dt, tz_name)
dtaware_day_start_from_date¶
Help on function dtaware_day_start_from_date in module pydicts.casts:
dtaware_day_start_from_date(date, tz_name)
Returns a timezone-aware datetime object representing the start of the day for a given date and timezone.
Args:
date (date): A `datetime.date` object.
tz_name (str): The name of the timezone.
Returns:
datetime: A timezone-aware datetime object set to 00:00:00.000000 of the given date in the specified timezone.
dtaware_month_end¶
Help on function dtaware_month_end in module pydicts.casts:
dtaware_month_end(year, month, tz_name)
dtaware_month_start¶
Help on function dtaware_month_start in module pydicts.casts:
dtaware_month_start(year, month, tz_name)
Returns a timezone-aware datetime object representing the start of the specified month and year.
Args:
year (int): The year.
month (int): The month (1-12).
tz_name (str): The name of the timezone.
Returns:
datetime: A timezone-aware datetime object for the first day of the month, 00:00:00.000000.
dtaware_now¶
Help on function dtaware_now in module pydicts.casts:
dtaware_now(tzname=None)
Returns the current datetime as a timezone-aware object.
Args:
tzname (str, optional): The name of the timezone. If None, returns UTC aware datetime. Defaults to None.
Returns:
datetime: A timezone-aware datetime object representing the current time.
If tzname is None: returns UTC dtaware
Returns a aware datetime object of current moment. By default returns UTC timezone
from pydicts import casts
print(casts.dtaware_now())
print(casts.dtaware_now("Europe/Madrid"))2026-04-26 10:21:11.648554+00:00
2026-04-26 12:21:11.649101+02:00
dtaware_year_end¶
Help on function dtaware_year_end in module pydicts.casts:
dtaware_year_end(year, tz_name)
Returns a timezone-aware datetime object representing the end of the specified year.
Args:
year (int): The year.
tz_name (str): The name of the timezone.
Returns:
datetime: A timezone-aware datetime object for December 31st, 23:59:59.999999.
dtaware_year_start¶
Help on function dtaware_year_start in module pydicts.casts:
dtaware_year_start(year, tz_name)
Returns a timezone-aware datetime object representing the start of the specified year.
Args:
year (int): The year.
tz_name (str): The name of the timezone.
Returns:
datetime: A timezone-aware datetime object for January 1st, 00:00:00.000000.
dtnaive¶
Help on function dtnaive in module pydicts.casts:
dtnaive(date_, hour)
Creates a timezone-naive datetime object from a date and time object.
Args:
date_ (date): A `datetime.date` object.
hour (time): A `datetime.time` object.
Returns:
datetime: A timezone-naive datetime object.
dtnaive_day_end¶
Help on function dtnaive_day_end in module pydicts.casts:
dtnaive_day_end(dt)
Returns a timezone-naive datetime object representing the end of the day for the given datetime.
Args:
dt (datetime): A timezone-naive datetime object.
Returns:
datetime: A timezone-naive datetime object set to 23:59:59.999999 of the same day.
Raises:
exceptions.CastException: If the input datetime object is timezone-aware.
dtnaive_day_end_from_date¶
Help on function dtnaive_day_end_from_date in module pydicts.casts:
dtnaive_day_end_from_date(date_)
Returns a timezone-naive datetime object representing the end of the day for a given date.
Args:
date_ (date): A `datetime.date` object.
Returns:
datetime: A timezone-naive datetime object set to 23:59:59.999999 of the given date.
dtnaive_day_start¶
Help on function dtnaive_day_start in module pydicts.casts:
dtnaive_day_start(dt)
## Returns a dtnaive or dtawre (as parameter) with the end of the day
dtnaive_day_start_from_date¶
Help on function dtnaive_day_start_from_date in module pydicts.casts:
dtnaive_day_start_from_date(date_)
Returns a timezone-naive datetime object representing the start of the day for a given date.
Args:
date_ (date): A `datetime.date` object.
Returns:
datetime: A timezone-naive datetime object set to 00:00:00.000000 of the given date.
dtnaive_now¶
Help on function dtnaive_now in module pydicts.casts:
dtnaive_now()
Returns the current datetime as a timezone-naive object.
Returns:
datetime: A timezone-naive datetime object representing the current time.
Returns a naive datetime object of current moment. By default returns UTC timezone
from pydicts import casts
casts.dtnaive_now()datetime.datetime(2026, 4, 26, 10, 21, 12, 62232)is_aware¶
Help on function is_aware in module pydicts.casts:
is_aware(dt)
Checks if a datetime object is timezone-aware.
Args:
dt (datetime): The datetime object to check.
Returns:
bool: True if the datetime object is timezone-aware, False otherwise.
Returns if a datetime object is aware (with timezone)
from pydicts import casts
print(casts.is_aware(casts.dtaware_now()))
print(casts.is_aware(casts.dtnaive_now()))True
False
is_naive¶
Help on function is_naive in module pydicts.casts:
is_naive(dt)
Checks if a datetime object is timezone-naive.
Args:
dt (datetime): The datetime object to check.
Returns:
bool: True if the datetime object is timezone-naive, False otherwise.
from pydicts import casts
print(casts.is_naive(casts.dtaware_now()))
print(casts.is_naive(casts.dtnaive_now()))False
True
months¶
Help on function months in module pydicts.casts:
months(year_from, month_from, year_to=None, month_to=None)
Generates a list of (year, month) tuples for a range of months.
Args:
year_from (int): The starting year.
month_from (int): The starting month (1-12).
year_to (int, optional): The ending year. If None, uses the current year. Defaults to None.
month_to (int, optional): The ending month (1-12). If None, uses the current month. Defaults to None.
Returns:
list: A list of (year, month) tuples, inclusive of the start and end months.
Other utils¶
is_email¶
Help on function is_email in module pydicts.casts:
is_email(value)
Checks if a string is a valid email address using a regular expression.
Args:
value (str): The string to validate.
Returns:
bool: True if the string is a valid email address, False otherwise.
Note: This validation is based on a common regex pattern and might not cover all edge cases defined by RFCs.
from pydicts import casts
print(casts.is_email("hi.hi.com"))
print(casts.is_email("hi@hi.com"))
print(casts.is_email("hi@hi.com."))False
True
False
is_noe¶
Help on function is_noe in module pydicts.casts:
is_noe(value)
Checks if a value is None or an empty string.
Args:
value (any): The value to check.
Returns:
bool: True if the value is None or an empty string, False otherwise.
from pydicts import casts
print(casts.is_noe(None))
print(casts.is_noe(""))
print(casts.is_noe(1))True
True
False
object_or_empty¶
Help on function object_or_empty in module pydicts.casts:
object_or_empty(v)
Returns an empty string if the input value is None, otherwise returns the value itself.
Args:
v (any): The input value.
Returns:
str or any: An empty string if `v` is None, otherwise `v`.
Example:
>>> object_or_empty(None)
''
>>> object_or_empty("hello")
'hello'