README.md 7.62 KB
Newer Older
Robert Sebille's avatar
Robert Sebille committed
1
# AaaaHorodatage
Robert Sebille's avatar
Robert Sebille committed
2
3
This program is under GNU General Public License, version 3, see LICENCE text file.

4
This program needs python 3 and modules aaaa.ahordat, aaaa.ahordattools.
Robert Sebille's avatar
Robert Sebille committed
5

6
7
8
9
## AaaaHorodatage format
[0-9]+AAAAZ+/-HH:MM where [0-9]+ = the number of seconds from the epoch until the date entered, AAAA = the epoch of the timestamp, and Z+/-HH:MM the UTC offset (e.g for CEST summertime: Z+02:00).  The timezone and epoch are embedded.

__Below, in the same directory as this README.md file__
Robert Sebille's avatar
Robert Sebille committed
10
11
## Usage
### In a file.py:
12
    from aaaa.ahordat import AaaaHorodatageTools
Robert Sebille's avatar
Robert Sebille committed
13
    <your code>
14
15
### Démo
in python shel, eg:
Robert Sebille's avatar
Robert Sebille committed
16

17
18
	from aaaa.demo import demo
	demo()
19
20
21
22
23
### Init:

    from aaaa.ahordattools import AaaaHorodatageTools

    new_ts_object = AaaaHorodatageTools()
Robert Sebille's avatar
Robert Sebille committed
24
    or
25
26
27
28
29
    new_ts_object = AaaaHorodatageTools(AaaaTimestamp)
    or
    new_ts_object = AaaaHorodatageTools("server")

    ... your code ...
Robert Sebille's avatar
Robert Sebille committed
30

Robert Sebille's avatar
Robert Sebille committed
31
32
Exemples:

33
34
- _new_ts_object_ =  _AaaaHorodatageTools()_ will create 2000Z+02:00 = 2000-01-01T00:00:00+02:00, embedded epoch = 2000, (Default).
- _new_ts_object_ =  _AaaaHorodatageTools("server")_ will create ts_object with time server UTC.
Robert Sebille's avatar
Robert Sebille committed
35
36

### Modifiers
37
An AaaaHordatage instance has one public instance attibutes: _self.ts_ (its timestamp). 
Robert Sebille's avatar
Robert Sebille committed
38
 
39
Some methods, i call modifiers, can change this attribute; they will be documented with _update self.ts_.
Robert Sebille's avatar
Robert Sebille committed
40

41
42
43
### Generate timestamps

    encode(d="", utc=False) # possible inputs:
44
        update and return self.ts
45
46
47
48
        d="": keyboard input
        d= list, tuple or dictionary.
        utc=False: Local UTC offset encoding (see "Setting your timezone")
        utc=True: UTC encoding
Robert Sebille's avatar
Robert Sebille committed
49

50
51
52
53
    decode("typ", ts="") 
        return typ = "string", "list", "dict" ou "dictionary"
        ts = timestamp (e.g.: ts_object.get_ts()): use ts.
        ts = none or "": use self.ts.
54

55
56
NB: encode year > 9999 with an epoch = 1000 can causes long calculations.

57
58
59
60
61
62
63
64
65
66
67
68
### timestamps copy
Shallow copy, but it's enough, here.

    new_ts_object = ts_object.copy()

### Harmonize epoch and UTC offset
Convert ts_object_to_harmonize to same epoch and UTC offset than ts_object

    ts_object.set_ts_same_epoch_offset(ts_object_to_harmonize)
        ts_object_to_harmonize.ts is updated
    

Robert Sebille's avatar
Robert Sebille committed
69
70
## Timezones
### Setting your timezone
71
Your local timezone is stored in _utc_local_offset_ class attribute
72
Default is +7200 seconds, that is to say +02:00; Europe/Brussels summertime
73
_utc_local_offset_ range: -43200 >= _utc_seconds_ <= +50400<br />
74
Timestamps embbed their own UTC offset, then this attribute is just for encoding timestamp. 
75

Robert Sebille's avatar
Robert Sebille committed
76
77
You can use public methods to get or set it.

78
79
80
    get_utc_local_offset(typ="") # instance method
        typ="": default, seconds (integer); typ="string": "+/-HH:MM"
        Return _utc_local_offset
Robert Sebille's avatar
Robert Sebille committed
81

82
    set_utc_local_offset(*offset) # class method
Robert Sebille's avatar
Robert Sebille committed
83
84
85
        work with encode(). Default +02:00
        -43200 >= *offset <= +50400 or '-12:00' >= *offset <= '+14:00'

86
Get the embedded UTC offset (the UTC offset embedded in self.ts)
Robert Sebille's avatar
Robert Sebille committed
87

88
89
90
    get_utc_ts_offset(typ=""):
        typ="": default, seconds (integer); typ="string": "+/-HH:MM" 
        return the embedded UTC offset
91

Robert Sebille's avatar
Robert Sebille committed
92
### Converting timezone
Robert Sebille's avatar
Robert Sebille committed
93
94
You can use methods to convert timestamp from utc to a specific timezone and from a specific timezone to utc.

95
96
    tz2utc()
        update and return self.ts
Robert Sebille's avatar
Robert Sebille committed
97
        
98
99
100
    utc2tz(*new_offset) 
        update and return self.ts
            
Robert Sebille's avatar
Robert Sebille committed
101
102
        -43200 >= *new_offset <= +50400 or 
        '-12:00' >= *new_offset <= '+14:00'. 
Robert Sebille's avatar
Robert Sebille committed
103
104

### Converting offset
Robert Sebille's avatar
Robert Sebille committed
105
You can use this utility methods to convert offset from seconds to string and from string to seconds.
Robert Sebille's avatar
Robert Sebille committed
106

Robert Sebille's avatar
Robert Sebille committed
107
108
109
    offset_seconds2string(offset_seconds)  # -43200 >= *new_offset <= +50400
    offset_string2seconds(offset_string)  # no control
    
Robert Sebille's avatar
Robert Sebille committed
110
### Timezones sites
111
112
113
114
115
116
Some timezones sites can help you to determine tour timezone.

* [24timezones](https://24timezones.com/);
* [Time.is](https://time.is/time_zones)
* [Time_zone](https://en.wikipedia.org/wiki/Time_zone) on Wikipedia.

117
## Epoch
118
119
the reference epoch of the AaaaHorodatage class stored in _epoch_ class attribute<br />
Default is 2000. Range: 1000 <= _epoch_ <= 9999.<br />
120
The epoch attribute is used for encoding timestamps only. For decoding, the script uses the embedded epoch. Timestamp epoch lesser than epoch class attribute are accepted on decoding.
121

122
### Setting epoch
Robert Sebille's avatar
Robert Sebille committed
123
124
125
You can use this class methods to get or set it.

    get_epoch() 
126
    set_epoch(num)  #  1000 <= epoch <= 9999, return epoch
127
128
129
130

### Converting epoch
You can change and adapt the embedded epoch of a timestamp.

131
132
    convert2epoch(epoch) 
        update and return self.ts
Robert Sebille's avatar
Robert Sebille committed
133
134
        Convert an embedded epoch to an other. 
        1000 <= epoch <= 9999.
135
136
137

## Operations
Operations relate to timestamps of the same UTC offset and at the same epoch only.
138

139
140
141
142
143
### diffDays
_See &laquo; - operator &raquo; too_

    ts1_object.diffDays(typ="string", ts2=0) 
        return ts2 - self.ts1 in days, hours, minutes, seconds.
144
145
        Offset UTC timestamp 1 must match offset UTC timestamp 2 and epoch timestamp 1 must match epoch timestamp 2.
        Return typ =
146
            - "seconds": return the number of seconds.
147
148
149
150
151
            - "string": return a string (+/-DDTHH:MM:SS). Default.
            - "list": return a list (fixed order).
            fixed order: sens_difference, day, hour, minutes, seconds.
            - "dict" or "dictionary": return a dict (any order).
        ts2 = 0 or none: keyboard input.
152
        ts2 eg: ts2_object.get_ts()
Robert Sebille's avatar
Robert Sebille committed
153
        
154
155
Tips with _ts1_object.diffDays(typ="string", ts2=0)_<br />
I want diffDays between ts1_object, epoch 2000 and offset +02:00, and ts2_object, epoch 1900 and offset +08:00, but not update ts2_object.<br />
156
157
158
159
160
Consider this tips:

    ts3_object = ts2_object.copy()
    ts1_object.set_ts_same_epoch_offset(ts_object3)
    diff_ts2_ts1 = ts1_object.diffDays("string", ts3_object.get_ts())
Robert Sebille's avatar
Robert Sebille committed
161
    del ts3_object
162
163
164

### + operator
  
165
166
    + operator: ts_object = ts_object + nb_seconds
        update self.ts and return ts_object + nb_seconds
167
168
169
        Add nb_seconds at timestamp
        Tips: 
        - use dhms2second(d=0, h=0, m=0, s=0) utility method 
Robert Sebille's avatar
Robert Sebille committed
170
        to convert days + hours + minutes + seconds in seconds
171
172
        - To add seconds to a new timestamp instance:
        new_ts_object = ts_object.copy()
173
        new_ts_object - nb_seconds
174
175

### - operator
Robert Sebille's avatar
Robert Sebille committed
176

177
178
    - operator: new_ts = ts_object - *nb_seconds_or_ts_object
        if *nb_seconds_or_ts_object is a nb_seconds integer
179
        update self.ts and return ts_object - *nb_seconds
180
181
182
183
        self.ts seconds - seconds must be >= 0 (epoch-01-01)
        
        if *nb_seconds_or_ts_object is ts_object, call
        self.ts.diffDays("string", *nb_seconds_or_ts_object.get_ts())
184
        self.ts is NOT updated. See diffDays() method above.
185
186
187
        
        Tips: 
        - use dhms2second(d=0, h=0, m=0, s=0) utility method 
Robert Sebille's avatar
Robert Sebille committed
188
        to convert days + hours + minutes + seconds in seconds
189
190
191
        - To add seconds to a new timestamp instance:
        new_ts_object = ts_object.copy()
        new_ts_object - seconds
Robert Sebille's avatar
Robert Sebille committed
192
193
194
195
196
197
198
199
200
201

### Comparison operators

	ts_object1 == ts_object2
	ts_object1 != ts_object2
	ts_object1 < ts_object2
	ts_object1 <= ts_object2
	ts_object1 > ts_object2
	ts_object1 >= ts_object2

Robert Sebille's avatar
Robert Sebille committed
202
203
### Conversion to and from Posix

204
205
    ts_object.convert_aaaa2posix(aaaa_ts)
        Return a Posix timestamp (UTC) from an Aaaa timestamp
206

207
    ts_object.convert_posix2aaaa(posix_ts):
Robert Sebille's avatar
Robert Sebille committed
208
        Return an Aaaa timestamp from a Posix timestamp
209
        update self.ts
Robert Sebille's avatar
Robert Sebille committed
210
        posix_ts will be considered at UTC time.
Robert Sebille's avatar
Robert Sebille committed
211

Robert Sebille's avatar
Robert Sebille committed
212
## Help:
Robert Sebille's avatar
Robert Sebille committed
213
    import aaaa.ahordattools
Robert Sebille's avatar
Robert Sebille committed
214
215
216
217
218
    help(aaaa.ahordattools)

## Short demo

    python3 main.py
219

220
__You can find some thoughts about algorithms in this [pdf document](https://bit.ly/2seHHvU "Horodatage").__ This is not a documentation book, just a few thoughts.
221