API

This part of the documentation covers all the interfaces of Stilpy. That includes TimeGaps and TimeInterval class.

TimeGaps Objects

class stilpy.timegaps.TimeGaps(iterable: Iterable, tag_loc: str | int, i_tag: Any, f_tag: Any, dt_loc: str | int, *args: str | None, group_by: Any | None = None)[source]

Bases: object

Class representing a collection for time interval objects.

It’s an iterator of TimeInterval Objects.

Variables:

  • grouper_tags (List of dicts) – A list containig a collection of dictionarys with the keys passed as grouped_by parameter and the values finded in the iterable that makes the different groups.

  • grouped_intervals (List of TimeGaps iterators) – Returns time intervals separated by groups. For every group a TimeGaps iterator is made an stored in a list. The groups are created using the group_by argument passed in the instance.

Raises:

  • StopIteration – Raised when the __next__() method is called but there are no more records to read.

  • AttributeError – Raised when grouper_tags or grouped_intervals attribute is reasigned.

ERROR_ITERABLE = "it's not a supported iterable."
__init__(iterable: Iterable, tag_loc: str | int, i_tag: Any, f_tag: Any, dt_loc: str | int, *args: str | None, group_by: Any | None = None) → None[source]
Parameters:

  • iterable (iterable of iterables) –

    An iterable object that contains a list of items. Those items must be dicts or dictlike objects. Lists, tuples and objects with __dict__ atribute are accepted as well. Every item, must content the next items inside:

    1. A datetime object or a string format datetime

    2. A item that defines if the datetime object or string that we just mentioned is an initial or a final time point of a time interval.

  • tag_loc (str or int) – Where to find the tag that contains the value representing wich part of the interval defines each element. In a list or a tuple can be an index. In a dict can be a key that reference the value.

  • i_tag (Any) – The name of the initial time tag in the iterable. It’s needed to know if a specific element of the iterable is an initial time value. Default is 'start'.

  • f_tag (Any) – The name of the final time tag in the iterable. It’s needed to know if a specific element of the iterable is a final time value. Default is 'end'.

  • dt_loc (str or int) – The location, inside each element of the iterable, of the datetime information.

  • args (str, optional) –

    Any argument that will be an attribute of the TimeInterval. For example, a name, an age… This parameter expects the key, or the attribute, depending on the iterable that is passed as first argument. Cannot be a int, or a TypeError will be raised.

    If both records for an interval contains a key with different values, the attribute will be populated with a tuple like (<start_record_value>, <end_record_value>)

  • group_by (Any, optional) – The tags that you want to use for making the correct pairs between the diferent records of your iterable. If it is None, the intervals will be made considering only the i_tag and the f_tag. You can pass a list, tuple or a single value. But every tag you pass must be contained in the iterables inside the main iterable.

Raises:

  • ValueError – If the iterables inside the main iterable are not supported a ValueError will be raised.

  • TypeError: – When int types are passed to the args parameter as additional attributes for TimeInterval.

property grouped_intervals: List[TimeGaps]

Returns a list with a TimeGaps iterator for each group.

If there are no groups, a single TimeGaps object will be returned, with the same intervals, properties and methods as the initial instance of TimeGaps.

property grouper_tags: List[dict]

Return a list of dictionaries with the grouper tags.

For example, if the group were made with 'name' and 'surname', this property will return something like: {'name': 'Jonh', 'surname': 'Smith', ...}.

total_duration(default: Any = None) → timedelta | Any[source]

Returns the total duration of the TimeIntervals iterator.

If any TimeInterval object is imperfect (start or end atributte is empty ‘’), the default argument passed to the method will be returned.

Parameters:

default (Any, optional) – The value that will be returned if any TimeInterval object in the TimeGaps iterator hasn’t a valid duration for the sum.

Returns:

  • timedelta – When every TimeInterval object in the TimeGaps iterator has a valid duration atributte (that’s a timedelta type) the method will return a timedelta object representing the sum of every duration atributte in the TimeInterval objects.

  • Any – If the method can’t reach the sum, it returns the value of the default parameter.

total_duration_anyway() → timedelta[source]

Returns the total duration of the TimeIntervals iterator.

If any TimeInterval object is imperfect (start or end atributte is empty ‘’) the duration of the others intervals will be returned.

Returns:

When every TimeInterval object in the TimeGaps iterator has a valid duration atributte (that’s a timedelta type) the method will return a timedelta object representing the sum of every duration atributte in the TimeInterval objects. If any timeinterval hasn’t a valid duration, that interval will be ignored, but the duration will be returned anyway, with the sum of the intervals that do have a duration.

Return type:

timedelta

TimeInterval Objects

class stilpy.timeinterval.TimeInterval(*args, start: datetime | str = '', end: datetime | str = '', **kwargs: str | None)[source]

Bases: object

Class representing a time interval between two moments.

Variables:

  • start (datetime object or an empty str) – The starting point of the time interval. Default is an empty string.

  • end (datetime object or an empty str) – The ending point of the time interval. Default is an empty string.

  • duration (timedelta object or and empty str) – The duration of the time interval. If one of the limits (start or end) it’s not set, the duration property will return an empty string.

  • is_perfect (bool) – It will return False if neither start or end are empty strings. Othewise, True will be returned.

__init__(*args, start: datetime | str = '', end: datetime | str = '', **kwargs: str | None) → None[source]
Parameters:

  • start (datetime object or str) –

    A datetime object representing the lower limit of the time interval. Default is an empty string. It accepts string formatted datetime like:

    • ’dd-mm-yyyy HH:MM:SS’

    • ’yyyy-mm-dd HH:MM:SS’

    Your can use dots, dashes and slashes as separators between the date elements and colons for the time elements. Hours goes from 00 to 23, minutes and seconds from 00 to 59.

  • end (datetime object or str) –

    A datetime object representing the upper limit of the time interval. Default is an empty string. It accepts string formatted datetime like:

    • ’dd-mm-yyyy HH:MM:SS’

    • ’yyyy-mm-dd HH:MM:SS’

    Your can use dots, dashes and slashes as separators between the date elements and colons for the time elements. Hours goes from 00 to 23, minutes and seconds from 00 to 59.

  • **kwargs (Any) – Any argument that must be an attribute of the TimeInterval object. For example, a name, an age…

Raises:

ValueError – if the start or end argument passed to the constructor is not a datetime object, a valid formatted datetime or an empty string.

property duration: timedelta | str

Returns the duration property.

property end: datetime

Returns the end property.

property is_perfect: bool

Returns True if the interval hasn’t an empty start or end.

property start: datetime

Returns the start property

static str_to_datetime(n_datetime: str) → datetime | str[source]

Tries to cast short string dates to date objet.

Parameters:

n_datetime (str) – A string format datetime. Date part accepts two formats: ‘yyyy-mm-dd’ and ‘dd-mm-yyyy’. You can use 3 different separators: '-', '/' and '.'. Time part only accepts one format: HH:MM:SS, using colons as separators. Hours goes from 00 to 23, minutes and seconds from 00 to 59.

Returns:

  • datetime – datetime object if n_datetime is a valid datetime formatted string.

  • str – if n_datetime is an empty string.

Raises:

ValueError – if the n_datetime argument passed to function is not a valid formatted datetime or an empty string.