date_utils

`app.utils.date_utils`

Módulo de Python para validaciones de fechas.

Para más información, te recomendamos leer la documentación del Proyecto.

Warning

estas funciones:

1	`- necesitan más pruebas y ejemplos.`

`get_current_time(type_format=None, date_format=False, use_delta=False)`

Devuelve la fecha y hora actual, en formato YYYY-MM-DD H:mm:ss.

Parameters:

Name	Type	Description	Default
`type_format`	`Literal[str]`	especifica si el valor de retorno de la función, es un `string` (en formato `YYYY-MM-DD H:mm:ss`) ó un objeto de tipo fecha (`datetime`), por defecto `str`.	`None`
`date_format`	`bool`	especifica si el valor de retorno de la función estará en formato `YYYY-MM-DD` (implica `type_format` fijado en `str`), por defecto `False`	`False`
`use_delta`	`bool`	sí se envía en `True` aplica `timedelta(hours=-5)` a la fecha y hora actual, por defecto `False`	`False`

Returns:

Type	Description
`Optional[str \| datetime]`	la fecha y hora actual en formato `string` ó `datetime` según el campo `date_format` ó `None` en caso de error

Examples:

ejemplo 1
get_current_time()

ejemplo 2
get_current_time("str", True, False)

`get_timestamp(as_str=False)`

Genera una marca de tiempo(timestamp) en formato YmdHMS.

Parameters:

Name	Type	Description	Default
`as_str`	`bool`	define si el timestamp será devuelto en formato `string` ó `datetime`, por defecto `False`.	`False`

Returns:

Type	Description
`Optional[str \| datetime]`	el timestamp ó `None` en caso de error

Examples:

ejemplo 1
get_timestamp()

ejemplo 2
get_timestamp(True)

`days_between_dates(init_date, end_date, return_as='seconds')`

Calcula el tiempo transcurrido entre dos fechas.

Parameters:

Name	Type	Description	Default
`init_date`	`Any`	la fecha inicial, en formato `YYYY-MM-DD`	required
`end_date`	`Any`	la fecha final, en formato `YYYY-MM-DD`	required
`return_as`	`Literal[str]`	el formato de retorno de la función, por defecto `seconds`	`'seconds'`

Notes

los valores admitidos por el parámetro return_as son:

'dict': para este caso devolverá un diccionario con el tiempo transcurrido en horas, minutos y segundos.
'days'
'hours'
'minutes'
'seconds'

Returns:

Type	Description
`Any`	el tiempo transcurrido entre dos fechas, el valor de retorno se establece según el parámetro `return_as` ó `None` en caso de error

Examples:

ejemplo 1
days_between_dates("2023-01-31", "2023-02-28")

ejemplo 2
days_between_dates("2023-01-31", "2023-02-28", "hours")

ejemplo 3
days_between_dates("2023-01-31", "2023-02-28", "minutes")

`to_date(current_date, type_format='date')`

Convierte una fecha (string en fomato YYYY-MM-DD) a un objeto de tipo datetime.

Parameters:

Name	Type	Description	Default
`current_date`	`str`	la fecha actual en formato `YYYY-MM-DD`	required
`type_format`	`str`	Defaults to "date".	`'date'`

Warning

esta función:

se encuentra en revisión, puede cambiar en el futuro.
se necesitan más pruebas y ejemplos.

Returns:

Type	Description
`Any`	la fecha (string en fomato `YYYY-MM-DD`) ó un objeto de tipo `datetime`, según las opciones enviadas, ó `None` en caso de error

Examples:

1 2	`... to_date("2023-06-14 04:50:39.353000")`

`is_valid_date(date_to_validate)`

Comprueba si una fecha coincide con el formato YYYY-MM-DD.

Parameters:

Name	Type	Description	Default
`date_to_validate`	`str`	la fecha en formato string a validar	required

Returns:

Type	Description
`bool`	el resultado de la validación ó `False` en caso de error

Examples:

1 2	`... is_valid_date("2023-02-31")`

`is_valid_hour(time_to_validate)`

Comprueba si una hora coincide con el formato "H:M:S.

Parameters:

Name	Type	Description	Default
`time_to_validate`	`str`	la hora en formato string a validar	required

Returns:

Type	Description
`bool`	el resultado de la validación ó `False en caso de error

Examples:

1 2	`... is_valid_hour("17:09:25")`

`compare_dates(init_date, end_date, compare='eq')`

Compara dos fechas en formato YYYY-MM-DD, utilizando un prefijo para realizar la comparación (el parámetro compare).

Parameters:

Name	Type	Description	Default
`init_date`	`str`	la fecha inicial en formato `YYYY-MM-DD`	required
`end_date`	`str`	la fecha final en formato `YYYY-MM-DD`	required
`compare`	`Literal[str]`	un prefijo para realizar las comparaciones, por defecto `eq`.	`'eq'`

Notes

los valores admitidos por el parámetro compare son:

'eq': igual
'gr': mayor
'le': menor
'gt': mayor ó igual
'lt': menor ó igual

Returns:

Type	Description
`bool`	el resultado de la comparación ó `False` en caso de error

Examples:

...
# ejemplo 1
compare_dates("2023-01-31", "2023-02-28")

# ejemplo 2
compare_dates("2023-01-31", "2023-02-28", "gt")

`compare_times(init_time, end_time, compare='eq')`

Compara dos horas en formato H:M:S, utilizando un prefijo para realizar la comparación (el parámetro compare).

Parameters:

Name	Type	Description	Default
`init_time`	`str`	la hora inicial en formato `H:M:S`	required
`end_time`	`str`	la hora final en formato `H:M:S`	required
`compare`	`str`	un prefijo para realizar las comparaciones, por defecto `eq`.	`'eq'`

Notes

los valores admitidos por el parámetro compare son:

'eq': igual
'gr': mayor
'le': menor
'gt': mayor ó igual
'lt': menor ó igual

Returns:

Type	Description
`bool`	el resultado de la comparación

Examples:

...
# ejemplo 1
compare_times("12:00:59", "21:59:59")

# ejemplo 2
compare_times("12:00:59", "21:59:59", "gt")

`add_days(current_date, num_days=1)`

Agrega días a una fecha dada.

Parameters:

Name	Type	Description	Default
`current_date`	`str`	la fecha a validar en formato `YYYY-MM-DD`	required
`num_days`	`int`	el número de días a agregar, por defecto `1`	`1`

Returns:

Type	Description
`Optional[str]`	la nueva fecha en formato `YYYY-MM-DD`, ó `None` en caso de error

Examples:

1 2	`... add_days("2023-11-01", 10)`

`add_months(init_date, add_months=1)`

Agrega meses a una fecha dada.

Parameters:

Name	Type	Description	Default
`init_date`	`str`	la fecha a validar en formato `YYYY-MM-DD`	required
`add_months`	`int`	el número de meses a agregar, por defecto `1`	`1`

Returns:

Type	Description
`Optional[str]`	la nueva fecha en formato `YYYY-MM-DD`, ó `None` en caso de error

Examples:

1 2	`... add_months("2023-11-01", 2)`

`add_time(count, unit_time, init_hour=None)`

Agrega horas, minutos ó segundos a una hora dada.

Parameters:

Name	Type	Description	Default
`count`	`int`	la cantidad de tiempo a agregar	required
`unit_time`	`Literal[]`	la unidad de tiempo a agregar	required
`init_hour`	`str`	la hora a validar en formato `H:M:S`, en caso de que no se envíe, se utiliza la hora actual	`None`

Returns:

Type	Description
`Optional[str]`	la nueva hora en formato `H:M:S`, ó `None` en caso de error

Examples:

1
2
3

...
add_time(5, "hours")
add_time(59, "minutes", "14:02:03")

`add_date(count, unit_time, init_date=None)`

Agrega días, horas, minutos ó segundos a una fecha y hora dada.

Parameters:

Name	Type	Description	Default
`count`	`int`	la cantidad de tiempo a agregar	required
`unit_time`	`Literal[]`	la unidad de tiempo a agregar	required
`init_date`	`str`	la fecha y hora a validar, en formato `Y-m-d H:M:S`, en caso de que no se envíe, se utiliza la fecha y hora actual	`None`

Returns:

Type	Description
`Optional[str]`	la nueva fecha y hora en formato `Y-m-d H:M:S`, ó `None` en caso de error

Examples:

1
2
3

...
add_date(5, "days")
add_date(59, "seconds", "2023-11-01 14:02:03")

`date_to_str(obj_date, default_format=DEFAULT_FORMAT)`

Convierte un objeto tipo date/datetime a str, utilizando el formato por defecto (DEFAULT_FORMAT).

Parameters:

Name	Type	Description	Default
`obj_date`	`Any`	objeto tipo date/datetime	required
`default_format`	`str`	el formato a covertir, por defecto (`DEFAULT_FORMAT`)	`DEFAULT_FORMAT`

Returns:

Type	Description
`Optional[str]`	la nueva fecha y hora en el formato envíado, ó `None` en caso de error

Examples:

...
now = datetime.utcnow()

# ejemplo 1
date_to_str(now)

# ejemplo 2
date_to_str(now, "%Y-%m-%d")