Skip to content

Commit ce8387d

Browse files
asuiuasuiu
committed
v0.1.13: - TS.as_ms() typehint update
- README.md update
1 parent 82d46da commit ce8387d

File tree

3 files changed

+364
-7
lines changed

3 files changed

+364
-7
lines changed

‎README.md

+362-5
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,13 @@
22

33
**T**ime **S**tamp e**X**tensions for Python
44

5-
This library was created as a response to the known Python datetime standard library flaw that violates ISO
5+
Why tsx? `tsa` was created as a response to the known Python datetime standard library flaw that violates ISO
66
8601. ( [Example](https://stackoverflow.com/questions/19654578/python-utc-datetime-objects-iso-format-doesnt-include-z-zulu-or-zero-offset) )
77

8-
Under the hood, it uses external dateparser library that's fully compatible with ISO 8601, and it simplifies working
9-
with date & time stamps.
8+
It properly handles the Daylight Saving Time (summer time), and provides functionality for creating, manipulating, and formatting timestamps in various formats
9+
and precisions.
1010

11-
It also handles properly the Daylight Saving Time (summer time).
11+
Under the hood, it uses external dateparser library that's fully compatible with ISO 8601, and it simplifies working with date & time stamps.
1212

1313
### Installation
1414

@@ -57,8 +57,337 @@ ts.as_file_date == '20090213'
5757
ts.as_file_ts == '20090213-233130'
5858
```
5959

60+
## Classes
61+
62+
### `TS`
63+
64+
The TS class, a subclass of float, represents Unix timestamps in seconds. It includes additional methods for timestamp manipulation and formatting.
65+
66+
#### Key Methods and Properties
67+
68+
- `now_dt()`: Returns the current datetime in UTC.
69+
- `now_ms()`, now_us, now_ns: Returns the current timestamp in various precisions.
70+
- `now()`: Returns the current TS instance.
71+
- `from_iso()`: Parses an ISO string to a TS instance.
72+
- `timestamp()`: Returns the timestamp as a TS instance.
73+
- `as_iso()`, `as_iso_date()`, `as_iso_date_basic()`, `as_iso_tz()`, `as_iso_basic()`: Various ISO format representations.
74+
- `as_file_ts()` and `as_file_date()`: File-friendly timestamp formats.
75+
- `as_sec()`, `as_ms()`, `to_sec()`: Conversions to different precisions with deprecation notices.
76+
- `floor()` and `ceil()`: Methods for flooring and ceiling the timestamp.
77+
- `weekday()` and `isoweekday()`: Methods to get the day of the week.
78+
- *Arithmetic Operations*: Overloaded methods for arithmetic.
79+
80+
#### now_dt
81+
82+
- **Description**: Returns the current datetime in UTC.
83+
- **Example**:
84+
```python
85+
current_dt = TS.now_dt()
86+
current_dt == datetime.datetime(2021, 10, 15, 12, 0, 0, 123456, tzinfo=datetime.timezone.utc)
87+
```
88+
89+
#### now
90+
91+
- **Description**: Returns the current timestamp in seconds.
92+
- **Example**:
93+
```python
94+
current_ts = TS.now()
95+
current_ts == TS(1634294400.123456) == 1634294400.123456
96+
```
97+
98+
#### now_ms
99+
100+
- **Description**: Returns the current timestamp in milliseconds.
101+
- **Example**:
102+
```python
103+
current_ts = TS.now_ms()
104+
current_ts == iTSms(1634294400123) == 1634294400123
105+
```
106+
107+
#### now_us
108+
109+
- **Description**: Returns the current timestamp in microseconds.
110+
- **Example**:
111+
```python
112+
current_ts = TS.now_us()
113+
current_ts == iTSus(1634294400123456) == 1634294400123456
114+
```
115+
116+
#### now_ns
117+
118+
- **Description**: Returns the current timestamp in nanoseconds.
119+
- **Example**:
120+
```python
121+
current_ts = TS.now_ns()
122+
current_ts == iTSn(s1634294400123456789) == 1634294400123456789
123+
```
124+
125+
#### from_iso
126+
127+
- **Description**: Parses an ISO string to a TS instance.
128+
- **Example**:
129+
```python
130+
ts = TS.from_iso("2021-10-15T12:00:00.123456Z")
131+
ts == TS(1634294400.123456) == 1634294400.123456
132+
```
133+
134+
#### timestamp
135+
136+
- **Description**: Returns the timestamp as a TS instance.
137+
- **Example**:
138+
```python
139+
ts = TS.timestamp(1634294400.123456)
140+
ts == TS(1634294400.123456) == 1634294400.123456
141+
```
142+
143+
#### as_iso
144+
145+
- **Description**: Returns the timestamp as an ISO string.
146+
- **Example**:
147+
```python
148+
ts = TS(1634294400.123456)
149+
ts.as_iso == '2021-10-15T12:00:00.123456Z'
150+
```
151+
152+
#### as_iso_date
153+
154+
- **Description**: Returns the timestamp as an ISO date string.
155+
- **Example**:
156+
```python
157+
ts = TS(1634294400.123456)
158+
ts.as_iso_date == '2021-10-15'
159+
```
160+
161+
#### as_iso_date_basic
162+
163+
- **Description**: Returns the timestamp as an ISO date string in basic format.
164+
- **Example**:
165+
```python
166+
ts = TS(1634294400.123456)
167+
ts.as_iso_date_basic == '20211015'
168+
```
169+
170+
#### as_iso_tz
171+
172+
- **Description**: Returns the timestamp as an ISO string with timezone.
173+
- **Parameters**:
174+
- `tz: str|tzinfo`: The timezone to use.
175+
- **Example**:
176+
```python
177+
ts = TS(1634294400.123456)
178+
ts.as_iso_tz(pytz.timezone("Europe/Bucharest")) == '2021-10-15T14:00:00.123456+02:00'
179+
```
180+
181+
#### as_iso_basic
182+
183+
- **Description**: Returns the timestamp as an ISO string in basic format.
184+
- **Example**:
185+
```python
186+
ts = TS(1634294400.123456)
187+
ts.as_iso_basic == '20211015T120000.123456Z'
188+
```
189+
190+
#### as_file_ts
191+
192+
- **Description**: Returns the timestamp as a file-friendly timestamp string.
193+
- **Example**:
194+
```python
195+
ts = TS(1634294400.123456)
196+
ts.as_file_ts == '20211015-120000'
197+
```
198+
199+
#### as_file_date
200+
201+
- **Description**: Returns the timestamp as a file-friendly date string.
202+
- **Example**:
203+
```python
204+
ts = TS(1634294400.123456)
205+
ts.as_file_date == '20211015'
206+
```
207+
208+
#### as_sec
209+
210+
- **Description**: Returns the timestamp as a TS instance in seconds.
211+
- **Example**:
212+
```python
213+
ts = TS(1634294400.123456)
214+
ts.as_sec == TS(1634294400.0) == 1634294400.0
215+
```
216+
217+
#### as_ms
218+
219+
- **Description**: Returns the timestamp as a TS instance in milliseconds.
220+
- **Example**:
221+
```python
222+
ts = TS(1634294400.123456)
223+
ts.as_ms == iTSms(1634294400123) == 1634294400123
224+
```
225+
226+
#### to_sec
227+
228+
- **Description**: Returns the timestamp as a TS instance in seconds.
229+
- **Example**:
230+
```python
231+
ts = TS(1634294400.123456)
232+
ts.to_sec == TS(1634294400.0) == 1634294400.0
233+
```
234+
235+
#### floor
236+
237+
- **Description**: Floors the timestamp to the nearest second.
238+
- **Parameters**:
239+
- `unit: int|float`: the unit to ceil which should be of the same precision as the timestamp
240+
- **Example**:
241+
```python
242+
ts = TS(1634294413.123456)
243+
ts.floor(100) == TS(1634294400.0) == 1634294400.0
244+
245+
ts.floor(0.025) == TS(1634294413.1) == 1634294400.1
246+
```
247+
248+
#### ceil
249+
250+
- **Description**: Ceils the timestamp to the nearest second.
251+
- **Parameters**:
252+
- `unit: int|float`: the unit to ceil which should be of the same precision as the timestamp
253+
- **Example**:
254+
```python
255+
ts = TS(1634294413.123456)
256+
ts.ceil(100) == TS(1634294500.0) == 1634294500.0
257+
258+
ts.ceil(0.025) == TS(1634294413.125) == 1634294500.125
259+
```
260+
261+
#### weekday
262+
263+
- **Description**: Return the day of the week as an integer, where Monday is 0 and Sunday is 6. See also isoweekday().
264+
- **Parameters**:
265+
- `utc: bool = True`: Whether to use UTC or local time.
266+
- **Example**:
267+
```python
268+
ts = TS(1634294400.123456)
269+
ts.weekday() == 4
270+
```
271+
272+
#### isoweekday
273+
274+
- **Description**: Return the day of the week as an integer, where Monday is 1 and Sunday is 7. See also weekday().
275+
- **Parameters**:
276+
- `utc: bool = True`: Whether to use UTC or local time.
277+
- **Example**:
278+
```python
279+
ts = TS(1634294400.123456)
280+
ts.isoweekday() == 5
281+
```
282+
283+
#### Arithmetic Operations
284+
285+
- **Description**: Overloaded methods for arithmetic.
286+
- **Parameters**:
287+
- `other: Union[TS, int, float]`: The other timestamp to use.
288+
- **Example**:
289+
```python
290+
ts = TS(1634294400.123456)
291+
ts + 100 == TS(1634294500.123456) == 1634294500.123456
292+
ts - 100 == TS(1634294300.123456) == 1634294300.123456
293+
ts * 100 == TS(163429440012.3456) == 163429440012.3456
294+
ts / 100 == TS(16342944.00123456) == 16342944.00123456
295+
ts // 100 == TS(16342944.0) == 16342944.0
296+
ts % 100 == TS(1634294400.123456) == 1634294400.123456
297+
ts ** 100 == TS(1634294400.123456) == 1634294400.123456
298+
```
299+
300+
### `TSMsec`
301+
302+
The TSMsec class, a subclass of float, and it's used as a factory class to instantiate TS from milliseconds precision.
303+
304+
After instantiation, the TSMsec instance is identical to TS instance, and it includes all the same methods and properties.
305+
306+
### `iTS`
307+
308+
- The iTS class, a subclass of int, represents Unix timestamps in seconds. It includes additional methods for timestamp manipulation and formatting.
309+
- It inherits from `BaseTS` and `int` classes, so it exposes all the methods `TS` has, as well as it supports all the arithmetic operations `int` supports.
310+
- It's identical to `TS` class, but all the methods that return `TS` will return `iTS` instead, excepting the timestamp(), which returns `TS`.
311+
312+
#### Key Methods and Properties
313+
314+
- The same as `TS` class, but all the methods that return `TS` will return `iTS` instead.
315+
316+
### `iTSms`
317+
318+
- The iTSms class, a subclass of int, represents Unix timestamps in milliseconds. It includes additional methods for timestamp manipulation and formatting.
319+
- It inherits from `BaseTS` and `int` classes, so it exposes all the methods `TS` has, as well as it supports all the arithmetic operations `int` supports.
320+
- It's identical to `TSMsec` class, but all the methods that return `TS` will return `iTSms` instead, excepting the timestamp(), which returns `TS`.
321+
322+
### `iTSus`
323+
324+
- The iTSus class, a subclass of int, represents Unix timestamps in microseconds. It includes additional methods for timestamp manipulation and formatting.
325+
- It inherits from `BaseTS` and `int` classes, so it exposes all the methods `TS` has, as well as it supports all the arithmetic operations `int` supports.
326+
- It's identical to `TS` class, but all the methods that are expected to return `TS` will return `iTSus` instead, excepting the timestamp(), which returns `TS`.
327+
328+
### `iTSns`
329+
330+
- The iTSns class, a subclass of int, represents Unix timestamps in nanoseconds. It includes additional methods for timestamp manipulation and formatting.
331+
- It inherits from `BaseTS` and `int` classes, so it exposes all the methods `TS` has, as well as it supports all the arithmetic operations `int` supports.
332+
- It's identical to `TS` class, but all the methods that are expected to return `TS` will return `iTSns` instead, excepting the timestamp(), which returns `TS`.
333+
- **Note**: The `iTSns` class is only available for Python >= 3.8, and it support ns level now precision by using `time.time_ns()` instead of `time.time()`.
334+
60335
### Changelog
61336

337+
##### 0.1.13
338+
- TypeHint update: `TS.as_ms()` now returns `iTSms` instead of simple `int`
339+
- Added more documentation to README.md
340+
341+
##### 0.1.12
342+
343+
- Added dTS object
344+
345+
##### 0.1.11
346+
347+
- fixed the pickling/unpickling of TSMsec objects by instantiating the TSMsec as actually an instance of TS
348+
349+
##### 0.1.10
350+
351+
- upgrade dependency ciso8601 2.3.0 -> 2.3.1
352+
353+
##### 0.1.9
354+
355+
- Fixed bug in TS.__sub__ and TS.__add__ introduced in 0.1.7
356+
357+
##### 0.1.8
358+
359+
- Added TS.to_sec as temporary alias for TS.as_sec
360+
361+
##### 0.1.7
362+
363+
- Added iTS, iTSms, iTSus, iTSns classes.
364+
- deprecated TS.as_msec and TS.as_sec
365+
- No breaking changes yet
366+
367+
##### 0.1.6
368+
369+
- Fixed bug in TSMsec from TSMsec initialization
370+
371+
##### 0.1.5
372+
373+
- Fixed bug in parsing with date_util the Truncated formats with no TZ info
374+
375+
##### 0.1.4
376+
377+
- Exporting FIRST_MONDAY_TS, DAY_SEC, DAY_MSEC, WEEK_SEC into tsx public space
378+
379+
##### 0.1.3
380+
381+
- Fixed bug in TSMsec(<ISO_STRING>)
382+
383+
##### 0.1.2
384+
385+
- Added as_dt() and as_local_dt() methods
386+
387+
##### 0.1.1
388+
389+
- fixed bug in converting from numpy numbers
390+
62391
##### 0.1.0
63392

64393
- Added the `utc:bool=True` parameter to TS constructor, which if set to `True` (by default) will force the timestamp to
@@ -67,4 +396,32 @@ ts.as_file_ts == '20090213-233130'
67396
- Improved speed of TS.from_iso(). For Python <3.11 it uses [`ciso8601`](https://github.com/closeio/ciso8601) which is
68397
the fastest ISO 8601 parser, and for Python >= 3.11 it uses the builtin `datetime.fromisoformat()`.
69398
- some minor parsing speed improvements
70-
- added public time utility variables `FIRST_MONDAY_TS`, `DAY_SEC`, `DAY_MSEC`, `WEEK_SEC`
399+
- added public time utility variables `FIRST_MONDAY_TS`, `DAY_SEC`, `DAY_MSEC`, `WEEK_SEC`
400+
401+
##### 0.0.9
402+
403+
- str(ts) now returns ts.as_iso
404+
405+
##### 0.0.8
406+
407+
- added weekday() + isoweekday()
408+
409+
##### 0.0.7
410+
411+
- added floor() and ceil() methods
412+
413+
##### 0.0.6
414+
415+
- added TS.as_iso_date_basic and as_iso_basic
416+
417+
##### 0.0.5
418+
419+
- added TS.from_iso()
420+
421+
##### 0.0.4
422+
423+
- added return typehint to TS.now()
424+
425+
##### 0.0.3
426+
427+
- Lower the minimal typing-extensions version

0 commit comments

Comments
 (0)