1# -*- coding: utf-8 -*-
  2"""
  3Created on Sun Jan  2 18:30:14 2022
  4
  5@author: Philippe@loco-labs.io
  6
  7The `python.observation.timeslot` module contains the `TimeSlot` and the `TimeInterval` classes.
  8
  9# What is the TimeSlot Object ?
 10
 11The TimeSlot Object is a representation of time intervals data and properties. For example,
 12 I can represent the working day of 2022-march-15 by a TimeSlot which includes the following intervals:
 13- from 9 a.m. to 12 p.m.
 14- from 2 p.m. to 4:30 p.m.
 15- from 5 p.m. to 7:30 p.m.
 16i.e. a duration of 8 hours centered around 3 p.m. with bounds at 9 a.m. and 7:30 p.m.
 17
 18# Main principles
 19
 20The main principles are as follows :
 21
 22<img src="./timeslot_data_structure.png" width="800">
 23    
 24## Data structure
 25
 26A `TimeSlot` is a list of `TimeInterval`.
 27
 28A `TimeInterval` is defined by two `datetime` objects (start and end)
 29
 30Multiple properties are associated with the data :
 31    
 32- duration : sum of the lenght of each TimeInterval
 33- centroïd : instant assicited to the middle of the duration
 34- bounds : minimum, maximum and middle
 35- type : instant, interval or slot
 36
 37## Relationships and assembly
 38
 39Two `TimeSlot` can be compared with five statuses (equals, contains, within, disjoint, intersects).
 40
 41Multiple operations between two objects can be performed :
 42    
 43- union between two `TimeSlot`
 44- intersection between two `TimeSlot`
 45- complementing a `TimeSlot` in an interval
 46
 47"""
 48import datetime
 49import json
 50import numpy
 51import pandas
 52import bson
 53
 54from observation.esconstante import ES  # , _identity
 55
 56
 57class TimeSlotEncoder(json.JSONEncoder):
 58    """add a new json encoder for TimeSlot"""
 59
 60    def default(self, o):
 61        if isinstance(o, datetime.datetime):
 62            return o.isoformat()
 63        return json.JSONEncoder.default(self, o)
 64
 65
 66class TimeSlot:
 67    '''        
 68    *Attributes (for @property see methods)* :
 69
 70    - **slot** : list of `TimeInterval`
 71
 72    The methods defined in this class are : 
 73
 74    *dynamic value property (getters)*
 75
 76    - `TimeSlot.Bounds`
 77    - `TimeSlot.bounds`
 78    - `TimeSlot.Centroid`
 79    - `TimeSlot.duration`
 80    - `TimeSlot.instant`
 81    - `TimeSlot.middle`
 82    - `TimeSlot.interval`
 83    - `TimeSlot.stype`
 84
 85    *instance methods*
 86
 87    - `TimeSlot.json`
 88    - `TimeSlot.link`
 89    - `TimeSlot.timetuple`
 90    - `TimeSlot.union`
 91    '''
 92
 93    def __init__(self, val=None):
 94        '''
 95        TimeSlot constructor.
 96
 97        *Parameters*
 98
 99        - **val** : date, interval, list of interval (default None) - with several formats 
100        (tuple, list, string, datetime, TimeSlot, TimeInterval, numpy datetime64, pandas timestamp)
101
102        *Returns* : None'''
103        slot = []
104        if isinstance(val, str):
105            try:
106                val = json.loads(val)
107            except:
108                val = TimeInterval._dattz(datetime.datetime.fromisoformat(val))
109                # try:    val = TimeInterval._dattz(datetime.datetime.fromisoformat(val))
110                # except: val = None
111        if val == None:
112            self.slot = slot
113            return
114        val = TimeSlot._listed(val)
115        #if isinstance(val, tuple): val = list(val)
116        if isinstance(val, list) and len(val) == 2 and not isinstance(val[0], TimeInterval):
117            try:
118                slot.append(TimeInterval(val))
119            except:
120                for interv in val:
121                    slot.append(TimeInterval(interv))
122        elif isinstance(val, list):
123            try:
124                for interv in val:
125                    slot.append(TimeInterval(interv))
126            except:
127                slot.append(TimeInterval(val))
128        elif isinstance(val, datetime.datetime):
129            slot.append(TimeInterval(val))
130        elif isinstance(val, TimeSlot):
131            slot = val.slot
132        elif isinstance(val, TimeInterval):
133            slot.append(val)
134        else:
135            slot.append(TimeInterval(val))
136        self.slot = TimeSlot._reduced(slot)
137
138    def __add__(self, other):
139        ''' Add other's values to self's values in a new TimeSlot'''
140        return TimeSlot(TimeSlot._reduced(self.slot + other.slot))
141
142    def __iadd__(self, other):
143        ''' Add other's values to self's values'''
144        self.slot = self._reduced(self.slot + other.slot)
145
146    def __contains__(self, item):
147        ''' item of extval'''
148        return item in self.slot
149
150    def __getitem__(self, index):
151        ''' return interval item'''
152        return self.slot[index]
153
154    def __setitem__(self, index, interv):
155        ''' modify interval item'''
156        if index < 0 or index >= len(self):
157            raise TimeSlotError("out of bounds")
158        self.slot[index] = TimeInterval(interv)
159        self.slot = TimeSlot._reduced(self.slot)
160
161    def __len__(self):
162        '''return the number of intervals included'''
163        return len(self.slot)
164
165    # def __repr__(self):
166    def __str__(self):
167        ''' return the type of slot and the json representation'''
168        return self.stype + '\n' + self.json(encoded=True, encode_format='json')
169
170    def __repr__(self):
171        # return self.__class__.__name__ + f'({self.slot})'
172        return self.__class__.__name__ + '(' + self.json(encoded=True, encode_format='json') + ')'
173
174    def __eq__(self, other):
175        '''equal if the slots are equals'''
176        try:
177            return self.slot == other.slot
178        except:
179            return False
180
181    def __lt__(self, other):
182        '''compare the earliest dates'''
183        return self.slot[0] < other.slot[0]
184
185    def __hash__(self):
186        return sum(hash(interv) for interv in self.slot)
187        # return hash(self.json(True))
188
189    @property
190    def Bounds(self):
191        '''return an interval TimeSlot with the bounds of the TimeSlot object'''
192        return TimeSlot(self.bounds)
193
194    @property
195    def bounds(self):
196        '''return a tuple with the start and end dates with isoformat string'''
197        return (TimeSlot.form(self.slot[0].start), TimeSlot.form(self.slot[len(self) - 1].end))
198
199    @classmethod
200    def cast(cls, value):
201        '''
202        tranform a value (unique or list) in a list of `TimeSlot`
203
204        *Parameters*
205
206        - **value** : value to transform
207
208        *Returns*
209
210        - **list** : list of `TimeSlot`
211        '''
212        if isinstance(value, list):
213            try:
214                return [cls(val) for val in value]
215            except:
216                return [cls(value)]
217        else:
218            return [cls(value)]
219
220    @property
221    def Centroid(self):
222        '''return a TimeSlot with the date corresponding to the middle of the duration'''
223        return TimeSlot(self.instant)
224
225    @property
226    def duration(self):
227        '''cumulative duration of each interval (timedelta format)'''
228        duration = datetime.timedelta()
229        for interv in self.slot:
230            duration += interv.duration
231        return duration
232
233    @staticmethod
234    def form(dtime):
235        if dtime.timetuple()[3:6] == (0, 0, 0):
236            return dtime.date().isoformat()
237        return dtime.isoformat()
238
239    @property
240    def instant(self):
241        '''return the date corresponding to the middle of the duration (datetime format)'''
242        duration = self.duration / 2
243        for interv in self.slot:
244            if duration > interv.duration:
245                duration -= interv.duration
246            else:
247                return interv.start + duration
248
249    @property
250    def middle(self):
251        '''return the date corresponding to the middle of the bounds (datetime format)'''
252        return self.bounds.instant
253
254    @property
255    def name(self):
256        ''' class name'''
257        return self.__class__.__name__
258
259    @property
260    def interval(self):
261        '''return a list with the start and end dates (datetime format)'''
262        return [self.slot[0].start, self.slot[len(self) - 1].end]
263
264    @property
265    def stype(self):
266        '''return a string with the type of TimeSlot (instant, interval, slot)'''
267        if len(self.slot) == 1:
268            return self.slot[0].stype
269        else:
270            return 'slot'
271
272    def json(self, **kwargs):
273        '''
274        Return json/bson structure with the list of TimeInterval.
275
276        *Parameters*
277
278        - **encoded** : defaut False - if False return dict, else return json string/bson bytes
279        - **encode_format** : defaut 'json' - return json, bson or cbor format
280
281        *Returns* : string or dict'''
282        option = {'encoded': False, 'encode_format': 'json'} | kwargs
283        if len(self) == 1:
284            js = self.slot[0].json(
285                encoded=False, encode_format=option['encode_format'])
286        else:
287            js = [interv.json(
288                encoded=False, encode_format=option['encode_format']) for interv in self.slot]
289        if option['encoded'] and option['encode_format'] == 'json':
290            return json.dumps(js, cls=TimeSlotEncoder)
291        if option['encoded'] and option['encode_format'] == 'bson':
292            return bson.encode(js)
293        return js
294
295    def link(self, other):
296        '''
297        Return the status (string) of the link between two TimeSlot (self and other).
298        - equals     : if self and other are the same
299        - disjoint   : if self's intervals and other's intervals are all disjoint
300        - within     : if all self's intervals are included in other's intervals
301        - contains   : if all other's intervals are included in self's intervals
302        - intersects : in the others cases
303
304        *Parameters*
305
306        - **other** : TimeSlot to be compared
307
308        *Returns* 
309
310        - **tuple** : (string(status), boolean(full or not))'''
311        if self.stype == 'instant':
312            point, oslot = self[0], other
313        elif other.stype == 'instant':
314            point, oslot = other[0], self
315        else:
316            point = None
317        if point is not None:
318            contains = equals = False
319            for interv in oslot:
320                contains = contains or interv.link(point) == 'contains'
321                equals = equals or interv.link(point) == 'equals'
322            if equals and not contains:
323                return ('equals', True)
324            if contains and point == other[0]:
325                return ('contains', True)
326            if contains and point == self[0]:
327                return ('within', True)
328            return ('disjoint', True)
329        else:
330            union = self + other
331            link = 'intersects'
332            full = True
333            if union.duration == self.duration == other.duration:
334                full = len(union) == len(self) == len(other)
335                link = 'equals'
336            elif union.duration == self.duration:
337                full = len(union) == len(self)
338                link = 'contains'
339            elif union.duration == other.duration:
340                full = len(union) == len(other)
341                link = 'within'
342            elif union.duration == self.duration + other.duration:
343                full = len(union) == len(self) + len(other)
344                link = 'disjoint'
345            return (link, full)
346
347    def timetuple(self, index=0, encoded=False):
348        '''
349        Return json structure with the list of TimeInterval (timetuple filter).
350
351        *Parameters*
352
353        - **index** : integer, defaut 0 - timetuple format to apply :
354            - 0 : year
355            - 1 : month
356            - 2 : day
357            - 3 : hour
358            - 4 : minute
359            - 5 : seconds
360            - 6 : weekday
361            - 7 : yearday
362            - 8 : isdst (1 when daylight savings time is in effect, 0 when is not)
363        - **encoded** : defaut False - if True return string, else return dict
364
365        *Returns* : string or dict'''
366        if len(self) == 1:
367            js = self.slot[0].timetuple(index, False)
368        else:
369            js = [interv.timetuple(index, False) for interv in self.slot]
370        if encoded:
371            return json.dumps(js, cls=TimeSlotEncoder)
372        else:
373            return js
374
375    def union(self, other):
376        ''' Add other's values to self's values in a new TimeSlot (same as __add__)'''
377        return self.__add__(other)
378
379    @staticmethod
380    def _reduced(listinterv):
381        ''' return an ordered and non-overlapping list of TimeInterval from any TimeInterval list'''
382        if not isinstance(listinterv, list) or len(listinterv) == 0:
383            return []
384        union = []
385        slot = sorted(listinterv)
386        interv = slot[0]
387        i = j = 0
388        while i < len(slot):
389            for j in range(i + 1, len(slot)):
390                if interv.link(slot[j]) == 'within':
391                    interv = slot[j]
392                elif interv.link(slot[j]) == 'intersects':
393                    interv = interv.union(slot[j])
394                elif interv.link(slot[j]) == 'disjoint':
395                    union.append(interv)
396                    interv = slot[j]
397                    i = j
398                    break
399            if j >= len(slot) - 1:
400                union.append(interv)
401                break
402        return union
403
404    @staticmethod
405    def _listed(idx):
406        '''transform a tuple of tuple in a list of list'''
407        if not isinstance(idx, str) and hasattr(idx, '__iter__'):
408            return [val if not isinstance(val, tuple) else TimeSlot._listed(val) for val in idx]
409        return idx
410
411
412class TimeInterval:    # !!! interval
413    '''        
414    *Attributes (for @property see methods)* :
415
416    - **start** : datetime Object - start of `TimeInterval`
417    - **end**   : datetime Object - end of `TimeInterval`
418
419    The methods defined in this class are : 
420
421    *dynamic value property (getters)*
422
423    - `TimeInterval.Bounds`
424    - `TimeInterval.bounds`
425    - `TimeInterval.Centroid`
426    - `TimeInterval.duration`
427    - `TimeInterval.instant`
428    - `TimeInterval.stype`
429
430    *instance methods*
431
432    - `TimeInterval.json`
433    - `TimeInterval.link`
434    - `TimeInterval.timetuple`
435    - `TimeInterval.union`
436    '''
437
438    def __init__(self, val=ES.nullDate):
439        '''
440        TimeInterval constructor.
441
442        *Parameters*
443
444        - **val** : date, interval (default ES.nullDate) - with several formats 
445        (list, string, datetime, TimeInterval, numpy datetime64, pandas timestamp)
446
447        *Returns* : None'''
448        self.start = self.end = ES.nullDate
449        if isinstance(val, str):
450            try:
451                sl = TimeInterval._dattz(datetime.datetime.fromisoformat(val))
452                if sl != None:
453                    self.start = self.end = sl
454                return
455            except:
456                try:
457                    val = json.loads(val)
458                except:
459                    val = ES.nullDate
460        if isinstance(val, list):
461            self._initInterval(val)
462        elif isinstance(val, TimeInterval):
463            self.start, self.end = val.start, val.end
464        else:
465            dat = self._initDat(val)
466            if dat != None:
467                self.start = self.end = dat
468
469    # def __repr__(self):
470    def __str__(self):
471        ''' return the type of interval and the json representation'''
472        return self.stype + '\n' + self.json(encoded=True, encode_format='json')
473
474    def __repr__(self):
475        # if self.stype == 'instant' : return self.__class__.__name__ + f'("{self.start}")'
476        # return self.__class__.__name__ + f'(["{self.start}","{self.end}"])'
477        return self.__class__.__name__ + '(' + self.json(encoded=True, encode_format='json') + ')'
478
479    def __eq__(self, other):
480        '''equal if the 'start' and 'end' dates are equals'''
481        return self.start == other.start and self.end == other.end
482
483    def __lt__(self, other):
484        '''compare the earliest dates (start)'''
485        return self.start < other.start
486
487    def __hash__(self):
488        return hash(self.start) + hash(self.end)
489        # return hash(self.json(True))
490
491    @property
492    def bounds(self):
493        '''return a tuple with the start and end dates with isoformat string'''
494        return (TimeSlot.form(self.start), TimeSlot.form(self.end))
495
496    @property
497    def Centroid(self):
498        '''return a TimeInterval with the date corresponding to the middle of the interval'''
499        return TimeInterval(self.instant)
500
501    @property
502    def duration(self):
503        '''duration between 'end' and 'start' date (timedelta format)'''
504        return self.end - self.start
505
506    @property
507    def instant(self):
508        '''return the date corresponding to the middle of the duration (datetime format)'''
509        return self.start + (self.end - self.start) / 2
510
511    @property
512    def stype(self):
513        '''return a string with the type of TimeInterval (instant, interval)'''
514        if self.start == self.end:
515            return 'instant'
516        return 'interval'
517
518    def json(self, encoded=False, encode_format='json'):
519        '''
520        Return json/bson structure (date if 'instant' or [start, end] if 'interval') 
521        with datetime or datetime.isoformat for dates.
522
523        *Parameters*
524
525        - **encoded** : defaut False - if True return dict, else return json string/bson bytes
526        - **encode_format**   : defaut 'json' - return json, bson or cbor format
527
528        *Returns* : string or dict'''
529        if self.stype == 'instant':
530            js = self.start
531        else:
532            js = [self.start, self.end]
533        '''if   self.stype == 'instant' : 
534            if encode_format == 'bson':  js = self.start
535            else:           
536                js = TimeSlot.form(self.start)
537        elif self.stype == 'interval' : 
538            if encode_format == 'bson':  js = [self.start, self.end]
539            else:           js = [TimeSlot.form(self.start), TimeSlot.form(self.end)]'''
540        if encoded and encode_format == 'json':
541            return json.dumps(js, cls=TimeSlotEncoder)
542        if encoded and encode_format == 'bson':
543            return bson.encode(js)
544        return js
545
546    def link(self, other):
547        '''
548        Return the status (string) of the link between two TimeIntervals (self and other).
549        - equals     : if self and other are the same
550        - disjoint   : if self's interval and other's interval are disjoint
551        - within     : if other's interval is included in self's interval
552        - contains   : if self's interval is included in other's interval
553        - intersects : in the others cases
554
555        *Parameters*
556
557        - **other** : TimeInterval to be compared
558
559        *Returns* : string'''
560        if self.start == other.start and self.end == other.end:
561            return 'equals'
562        if self.start <= other.start and self.end >= other.end:
563            return 'contains'
564        if self.start >= other.start and self.end <= other.end:
565            return 'within'
566        if self.start <= other.end and self.end >= other.start:
567            return 'intersects'
568        return 'disjoint'
569
570    def timetuple(self, index=0, encoded=False):
571        '''
572        Return json structure (timetuple filter).
573
574        *Parameters*
575
576        - **index** : integer, defaut 0 - timetuple format to apply :
577            - 0 : year
578            - 1 : month
579            - 2 : day
580            - 3 : hour
581            - 4 : minute
582            - 5 : seconds
583            - 6 : weekday
584            - 7 : yearday
585            - 8 : isdst (1 when daylight savings time is in effect, 0 when is not)
586        - **encoded** : defaut False - if True return string, else return dict
587
588        *Returns* : string or dict'''
589        if index not in [0, 1, 2, 3, 4, 5, 6, 7, 8]:
590            return None
591        if self.stype == 'instant':
592            js = self.start.timetuple()[index]
593        elif self.stype == 'interval':
594            js = [self.start.timetuple()[index], self.end.timetuple()[index]]
595        if encoded:
596            return json.dumps(js, cls=TimeSlotEncoder)
597        else:
598            return js
599
600    def union(self, other):
601        ''' Add other's values to self's values in a new TimeInterval 
602        if self and other are not disjoint'''
603        if self.link(other) != 'disjoint':
604            return TimeInterval([min(self.start, other.start), max(self.end, other.end)])
605        else:
606            return None
607
608    def _initInterval(self, val):
609        '''initialization of start and end dates from a list'''
610        self.start = self.end = self._initDat(val[0])
611        if len(val) > 1:
612            self.end = self._initDat(val[1])
613        else:
614            self.start = self.end = self._initDat(val)
615        if self.end < self.start:
616            self.start, self.end = self.end, self.start
617
618    def _initDat(self, val):
619        '''initialization of start and end dates from a unique value 
620        (datetime, string, numpy.datetime64, pandas Timestamp)'''
621        if isinstance(val, datetime.datetime):
622            res = val
623            '''if val.tzinfo is None or val.tzinfo.utcoffset(val) is None:
624                res = val.astimezone(datetime.timezone.utc)
625            else: res = val'''
626        elif isinstance(val, str):
627            try:
628                res = datetime.datetime.fromisoformat(val)
629            except:
630                res = ES.nullDate
631        elif isinstance(val, numpy.datetime64):
632            res = pandas.Timestamp(val).to_pydatetime()
633        elif isinstance(val, pandas._libs.tslibs.timestamps.Timestamp):
634            res = val.to_pydatetime()
635        else:
636            raise TimeSlotError("impossible to convert in a date")
637        return TimeInterval._dattz(res)
638
639    @staticmethod
640    def _dattz(val):
641        if val.tzinfo is None or val.tzinfo.utcoffset(val) is None:
642            return val.replace(tzinfo=datetime.timezone.utc)
643        return val
644
645
646class TimeSlotError(Exception):
647    pass