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